Files

3.8 KiB
Raw Permalink Blame History

Python 外部服务模板(echo)

VDE 进程外服务最小 Python 模板:仅标准库,不依赖 VDE。复制 vde_service_echo.py 作为自定义服务起点;Windows 上清单指向原生启动垫片(launcher/),POSIX 上可直接执行 .py(shebang + 可执行位)。不加入 VDE 默认构建。

目录

文件 说明
vde_service_echo.py 服务实现(Python 3 标准库:json/os/sys/time)
vde-service.json 服务清单;Windows executable 为 vde_service_echo_launch.exe,POSIX 为 .py
launcher/vde_service_echo_launch.cpp Windows 启动垫片:定位同目录 .py 与 python,转发参数/退出码
launcher/CMakeLists.txt 独立构建垫片并复制清单/脚本到产物目录
README.md 本文件

为什么 Windows 需要启动垫片

vde-service 清单的 executable 是单个可执行路径,runner/宿主通过 CreateProcess(Windows)或 execve(POSIX)直接启动,不经 shell,也没有额外参数。 Windows CreateProcess 不能直接执行 .py,因此本模板提供最小 C++ 垫片:

vde_service_echo_launch.exe --request R --response P
  → python vde_service_echo.py --request R --response P

可用环境变量覆盖定位(宿主默认不传,除非清单 sandbox.env_allow 声明): VDE_SERVICE_PYTHON(解释器)、VDE_SERVICE_SCRIPT(脚本路径)。生产部署也可用 PyInstaller 等打包为单文件可执行程序,替换清单 executable 即可。

构建(Windows 垫片 + 复制清单/脚本)

cmake -S plugins/external/templates/python_service/launcher -B build/wp-p4-13-template/python-launcher -G Ninja
cmake --build build/wp-p4-13-template/python-launcher
# 产物:build/wp-p4-13-template/python-launcher/service/
#   vde_service_echo_launch.exe, vde_service_echo.py, vde-service.json

POSIX 可直接把 vde_service_echo.py 作为 executable(确保 chmod +x),无需垫片:

chmod +x plugins/external/templates/python_service/vde_service_echo.py
python3 plugins/external/templates/python_service/vde_service_echo.py --help

直接调用

python3 vde_service_echo.py --request request.json --response response.json

请求/响应契约与 C++ 模板完全相同,见 ../cpp_service/README.md: operation=echo、可选 input、必填 output(位于 request 目录内)、可选 args.message/args.sleep_ms;响应 outputs[].path 返回文件名;退出码 0/2/3/5。

示例请求:

{
  "protocol": "vde-service/0.1",
  "request_id": "py-1",
  "operation": "echo",
  "output": "D:/tmp/work/out.txt",
  "args": { "message": "hello from python" }
}

与宿主/runner 的兼容性

  • 清单字段与 docs/design/vde-service-protocol.md §3 一致;
  • runner/宿主会以 --request/--response 调用清单 executable;
  • Windows 上必须使用垫片(或 PyInstaller 产物),不能直接把 .py 填入清单;
  • 垫片以 _spawnvp(_P_WAIT) 等待 Python 子进程并透传退出码。超时终止注意: 宿主/runner 杀死垫片时,Python 子进程不保证被一并杀死;需要严格超时回收时,请使用 容器模式或宿主 limits.kill_on_close 的 Job Object / POSIX 进程组(见协议 §7.1/§7.3)。
  • 容器模式使用 ../container/vde-service.python.container.json,镜像 ENTRYPOINT ["python3"], 清单容器内入口为 /opt/vde/vde_service_echo.py。

替换为真实服务

  1. 修改清单 id/name/version/capabilities 与脚本内 SERVICE_ID/OPERATION;
  2. 保留请求校验、错误响应、outputs 文件名规则与退出码;
  3. 生产实现建议用正式 JSON schema 校验(jsonschema 等),模板只用标准库以保持零依赖。