Python 执行器 jcy0chenyuan0/dsh-plugin-python

dsh-plugin-python

给 DeepSeek Harness（DSH）加一个模型能调用的 python 工具：用 Harness 自带的 Python 运行时执行代码，什么都不用装。

运行环境：Python 3.12.14，捆绑 numpy 2.3.5 / pandas 3.0.1 / python-docx / python-pptx / openpyxl / Pillow / lxml / XlsxWriter。

| 能力 | 状态 |
| 执行代码、返回 stdout | ✅ [exit code: 0] |
| 中文 / UTF-8 输出 | ✅ 强制 PYTHONUTF8=1 + PYTHONIOENCODING=utf-8 |
| 非零退出 + stderr 分离 | ✅ [exit code: 1] + traceback |
| args / stdin | ✅ sys.argv[1:]、sys.stdin |
| workdir（相对路径按会话工作区解析） | ✅ |
| files 多文件（辅助模块 / 数据 / 子目录） | ✅ import helpers、Path(__file__).parent |
| timeoutMs 超时终止 | ✅ [timed out after 1500 ms] |
| 临时目录清理 | ✅ 抛错路径也不泄漏 |
| 越界路径拦截（files / workdir 的 ../） | ✅ 拒绝 |

文件与安装

首次安装：先在本目录运行 install.ps1（Windows）或 node install.mjs（macOS/Linux）。
脚本按当前目录自动生成 cordis.patch.yml（已 .gitignore），不写死任何盘符。

缺少环境怎么办（默认自动安装）

安装时 install.ps1 默认静默安装缺失环境；只想检查时加 -CheckOnly：

powershell -ExecutionPolicy Bypass -File .\install.ps1
只检查、不安装： powershell -ExecutionPolicy Bypass -File .\install.ps1 -CheckOnly

插件加载时也会在后台运行 bootstrap.ps1 -AutoInstall -Quiet（6 小时内不重复），不阻塞 DSH 启动；首次装完可能需要重试工具。

- Python：优先用 DSH 自带运行时（dsh-runtimes\\dependencies\python\python.exe）；没有则 winget install Python.Python.3.12 --scope user。
- 也可以设置 DSH_PYTHON 或插件配置里的 pythonPath 指向任意 Python 3.11+。
- 关闭自动安装：patch 的 config 里设 autoInstall: false，或设置环境变量 DSH_BOOTSTRAP=0。

| 文件 | 作用 |
| lib/python.js | Host 侧插件：注册 python 工具 |
| cordis.patch.yml.tpl | bundle 补丁层模板；install 脚本生成 cordis.patch.yml |
| package.json | 包元数据（type: module，无任何运行时依赖）+ dsh.bundle 声明 |

本包是可安装的 DSH bundle，因此在 GUI 的「设置 → 插件」里可见、可整体启用/停用：

plugin_manager install_bundle file:<本目录的绝对路径> 装完 profile 的 package.json 里会同时出现：
dsh.profile.bundles: ["...", "dsh-plugin-python"]
dependencies: {"dsh-plugin-python": "file:<本目录的绝对路径>"}
卸载：GUI 插件页移除，或 plugin_manager remove_bundle dsh-plugin-python

机制：pnpm 会把本包复制到 <profile>/node_modules/dsh-plugin-python，而 cordis.patch.yml 里挂的是工作区绝对路径的 lib/python.js，所以改插件代码只需重启 DSH 即可生效（ESM 按 URL 缓存，不会热替换已激活的 fiber）；只有改了 cordis.patch.yml（挂载参数）才需要重新 install_bundle 刷新那份副本。

为什么不能只写 cordis.patch.yml 里的 insert：那样确实能挂载，但不会出现在 GUI 的插件页（那一页列的是已安装的 bundle/inventory）。bundle 化之后两种能力都有。

工具参数

| 参数 | 必填 | 说明 |
| code | ✅ | 要执行的 Python 源码（写入 main.py） |
| description | ✅ | 5–10 词的动作描述（UI 展示） |
| files | | [{ path, content }]，写入运行目录；用 import 名字 导入模块，用 Path(__file__).parent 读数据文件 |
| workdir | | 进程工作目录，默认会话工作区；相对路径按会话工作区解析，越界（.. 或工作区外的绝对路径）会被拒绝 |
| args | | 追加的命令行参数 |
| stdin | | 管道输入文本 |
| timeoutMs | | 超时毫秒数，到期终止进程 |

注意：进程工作目录是会话工作区，不是脚本目录。files 里的数据文件要用 Path(__file__).parent 解析；要留下产物则直接写工作区路径。

配置项（条目 config）

| 键 | 默认 | 含义 |
| pythonPath | 自动 | 指定解释器；默认按 runtime.json 找捆绑运行时，找不到才回退 PATH 上的 python |
| cwd | 会话工作区 | 默认工作目录 |
| timeoutMs | 120000 | 默认超时 |
| graceMs | 3000 | 终止宽限期 |
| maxOutputBytes | 200000 | 单流收集上限，超出部分落盘并给出 spillPath |
| keepScript | false | 保留临时脚本并回报 scriptPath |

设计要点

1. 零宿主依赖：模块只 import Node 内置模块，不导入任何 @deepseek-ai/。原因是工作区里的插件没有可达的 node_modules，而把 dsh-tools 作为真依赖安装会连带装入第二份 cordis（等于进程里出现第二个工具注册表）。
2. 原始 JSON Schema 方言：直接向 ctx.tools.register 传定义（不走 defineTool），对象层用 required: [...] 数组，oneOf 节点不挂同级关键字。
3. 沙箱合规：每次调用 ctx.sandboxPolicy.resolve({ session })；非 danger-full-access 时用 ctx.sandbox.confine(argv, policy) 包一层再 spawn；需要隔离却没有沙箱提供者时 fail closed，绝不静默不隔离。
4. 进程与输出：ctx.subprocess.spawn + collect 模式，terminate() 处理超时，readFrom(0) 读流，超限自动落盘。
5. 清理：mkdtemp 之后的所有步骤都在 try/finally 内，任何异常都会删除临时目录（这条是被测试抓出来的真实 bug）。

验证记录

离线真机测试：.tooling/test-python-plugin.mjs —— 因为插件零依赖，可以用普通 Node 直接加载，并把 ctx 打桩后用真实子进程跑全部路径：

PASS basic + unicode PASS args + stdin
PASS multi-file import + data PASS timeout terminates
PASS exit code + stderr PASS path escape rejected
PASS workdir inside honoured PASS workdir escape rejected
PASS temp dirs cleaned
9/9 passed

线上验证（运行中的 DSH）：plugin-python-4 = enabled + active（plugin-python / plugin-python-2 / plugin-python-3 已停用）； files 多文件调用返回 live after move: moved-to-python_hk / data: k,v | x,1，[exit code: 0]。

⚠️ 改动生效时机：运行中的 fiber 按 URL 缓存旧模块，改文件内容不会换来新实现。2026-10-06 给 workdir 加上越界拦截后，正是按 §4 坑③ 做的热替换（新 id plugin-python-4 + 停用 plugin-python-3），免重启即时生效：重挂后线上 workdir: "../.." 立即被拒绝，而工作区内的 workdir 仍照常可用。

DSH 插件怎么写（依据安装包内官方文档整理）

来源：@deepseek-ai/cordis-plugin-loader/README.md、@deepseek-ai/dsh-tools/README.md。

1. 插件模块形态

export const name = "plugin-python"; // 身份
export const inject = ["tools", "subprocess"]; // 激活前必须就绪的服务
export const Config = z.object({ ... }); // @deepseek-ai/schemastery（可选）
export function apply(ctx, config) { ... } // 挂载逻辑，产物由 fiber 托管

ctx.get("x") 取可选服务（自行判空）；inject 里的服务在 ctx.x 上必然存在。

2. Loader 条目选项

| 字段 | 说明 |
| id | 稳定标识，用于 resolve / update / remove |
| name | loader 导入的模块 specifier（包名、相对路径或绝对路径） |
| config | 传给 apply 的配置 |
| group | 该条目是组，config 是子条目列表 |
| disabled | 停用条目 |
| inject | 为条目追加必需服务 |

3. 注册工具

ctx.tools.register(defineTool({
name: "read_file",
description: "Read a file from disk.",
parameters: { path: { type: "string", required: true, description: "Absolute file path" } },
output: { schema: { type: "string" }, render: (_args, value) => [{ type: "text", text: value }] },
async execute(args, exec) { return readFile(args.path, { encoding: "utf8", signal: exec.signal }); }
}));

- 参数 DSL：string / number / integer / boolean / null / array / object / json / oneOf，required: true 写在属性上。
- output.schema 是值的 schema，render 返回内容块；注册即生效，schema 自动进系统提示。
- presentCall / presentResult 只给 Host 侧消费者；内置 Web 客户端不消费它们，卡片由客户端从原始调用参数推导。
- 策略扩展点：tools/pre-execute、ctx.tools.guard()、tools/execute、tools/post-execute、tools/result。

4. ⚠️ 三个实测坑

① 工作区插件没有 node_modules。 写 import { defineTool } from "@deepseek-ai/dsh-tools" 会在导入阶段失败，而 loader 只报一句 failed to import（真实原因是 ERR_MODULE_NOT_FOUND）。三条路：不导入宿主包，直接注册原始定义（本插件采用）；用 createRequire(<resources>/app.asar/dsh/package.json) 复用宿主模块实例；或作为 profile bundle 正规安装。

② 两套 schema 方言。 参数用属性级 required: true；原始 JSON Schema 的对象要在对象层写 required: [...]，写成属性级会报 JsonSchemaError: ... required is not supported on type "string"。另外 additionalProperties 只接受布尔值。

③ 改完代码（或搬了目录）不会自动生效。 ESM 模块按 URL 缓存：替换文件内容后重挂条目，fiber 拿到的还是旧模块（现象：条目 active 但工具 schema 依旧是旧的）。两种办法：重启 DSH；或换一个新的条目 id（新 id → 新 fiber → 新 URL 导入），并把旧 id 用 disabled: true 停掉——本插件三次迁移（换实现、搬进 python_hk、加 workdir 守卫）都是这样热替换的，现用 id 为 plugin-python-4。

5. 起进程：subprocess + sandbox

const policy = ctx.get("sandboxPolicy")?.resolve({ session: exec.agent.session });
let argv = [pythonPath, scriptPath];
if (policy && policy.mode !== "danger-full-access") {
const confined = await ctx.get("sandbox").confine(argv, policy, exec.signal);
argv = confined.argv; // 必须换成 confine 返回的 argv
}
const handle = ctx.subprocess.spawn({
argv, cwd, graceMs, signal: exec.signal,
stdio: { stdin: "ignore", stdout: { maxBytes, spill: { maxBytes } }, stderr: { maxBytes, spill: { maxBytes } } },
env: { PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" }
});
const outcome = await handle.done; // { exitCode, signal }
const text = handle.collected.stdout.readFrom(0).text; // 非消费式、按偏移读取

6. Windows 上的 Python 细节

捆绑解释器的 sys.stdout.encoding 默认是 gbk（locale cp936），不设 PYTHONUTF8=1 / PYTHONIOENCODING=utf-8 时中文输出会乱码。

7. 工具链

| 工具 | 用途 |
| .tooling/test-python-plugin.mjs | 打桩 ctx + 真实子进程的离线测试（9 项断言，含 workdir 越界拦截与合法放行） |

asar.mjs（读取 Electron app.asar 的辅助脚本）已于 2026-10-06 随工作区清理删除；需要时从 %TEMP%\dsh-workspace-cleanup-20261006-141447.zip 取回。

可移植性 / 换机器安装

这个仓库不包含本机绝对路径：cordis.patch.yml 由安装脚本按当前目录生成（已 .gitignore）。

换一台机器：

1. git clone 本仓库到任意目录；
2. 运行 powershell -ExecutionPolicy Bypass -File .\install.ps1（Windows）或 node install.mjs（macOS/Linux）；
3. 在 DSH 里执行 plugin_manager install_bundle file:<本目录的绝对路径>。

运行环境

- Windows / macOS / Linux 均可：插件只用 Node 内置模块。
- Python：默认按 runtime.json 找 DSH 自带运行时；找不到时回退 PATH 上的 python，也可在 patch 的 config.pythonPath 指定。
- 不额外安装任何 Python 包；捆绑运行时自带 numpy / pandas / python-docx / python-pptx / openpyxl / Pillow / lxml / XlsxWriter。