3.8 KiB
3.8 KiB
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。
替换为真实服务
- 修改清单
id/name/version/capabilities与脚本内SERVICE_ID/OPERATION; - 保留请求校验、错误响应、
outputs文件名规则与退出码; - 生产实现建议用正式 JSON schema 校验(
jsonschema等),模板只用标准库以保持零依赖。