# 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++ 垫片: ```text 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 垫片 + 复制清单/脚本) ```powershell 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`),无需垫片: ```bash chmod +x plugins/external/templates/python_service/vde_service_echo.py python3 plugins/external/templates/python_service/vde_service_echo.py --help ``` ## 直接调用 ```bash python3 vde_service_echo.py --request request.json --response response.json ``` 请求/响应契约与 C++ 模板完全相同,见 [../cpp_service/README.md](../cpp_service/README.md): `operation=echo`、可选 `input`、必填 `output`(位于 request 目录内)、可选 `args.message`/`args.sleep_ms`;响应 `outputs[].path` 返回文件名;退出码 0/2/3/5。 示例请求: ```json { "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` 等),模板只用标准库以保持零依赖。