前言¶
在 DeepSeek Harness（DSH）里让模型跑一小段 Python，常见做法是先落盘临时脚本，再调 shell 或 PowerShell 执行。在 Windows 与 PowerShell 环境下，这条路径往往还要应付引号转义、命令行长度限制，以及控制台编码与 UTF-8 源码不一致带来的乱码。dsh-plugin-pyrun 把「给源码、拿结果」收成一次工具调用：源码经 JSON 参数写入子进程 stdin，由 python -X utf8 -u - 解释执行，stdout/stderr 按 UTF-8 解码回传，并与内置 pwsh 工具共用同一套沙箱策略与后台作业语义。
这是什么¶
dsh-plugin-pyrun 是社区维护的 DSH 插件（目录页：ds-hu/dsh-plugin-pyrun，源码：GitHub），分类为模型推理。它在 harness 中注册工具名 python，面向「模型直接给出 Python 程序原文、一步返回执行结果」的场景，支持前台等待、后台作业，以及在沙箱拒绝时按审批流程一次性提权重试。
核心功能¶
stdin 直灌，绕过 shell 引号层¶
工具不把源码拼进 argv，而是把 code 参数对应的程序原文写入 Python 子进程的 stdin，等价于：
python -X utf8 -u -
-X utf8 与全链路 UTF-8 解码配合，减轻 Windows 下 GBK 干扰；-u 减少缓冲，便于及时看到输出。相对「经 shell 传参」，少了引号转义层，也避开了典型命令行长度上限。
前台与后台两种模式¶
前台调用会等待进程结束，结果里用 [exit code: N] 标明非零退出码（视为结果而非工具错误）。可设 timeout_ms（受部署上限约束）；超时、中止分别标记为 [timed out after Nms]、[aborted]。stderr 以 [stderr] 分节；超长输出会截尾并给出 [output truncated; full output: <path>]。
后台模式在传入 run_in_background 时立即返回 job id；timeout_ms 与后台互斥，同时传入会被拒绝。作业名册里 kind 为 python，用 job_output 收割输出、job_kill 停止、job_list 查看，语义与内置 pwsh 工具对齐。
沙箱与一次性提权¶
默认受 DSH 沙箱约束。若因文件访问等被拒绝，可在同轮用 sandbox_permissions 配合 justification 发起一次性重试，审批面板展示说明文案；拒绝时结果中会带 [sandbox: file access denied under <mode> mode] 及提权提示。
安装与启用¶
README 中的安装示例使用 link: 指向本机插件目录（仅建 profile 软链，不向 profile 根安装插件依赖，改代码后重启 dsh 即可加载）：
dsh plugin --profile web add link:D:/Projects/dsh-plugin-pyrun
将路径换成你本机克隆或解压后的插件根目录。若使用 dsh plugin add 等方式写入 ~/.dsh 并走 pnpm 安装，在受限沙箱下可能需要一次性提权；该包声明了 dsh.bundle.patch，安装成功后作为一层 bundle 进入 profile。
装完后必须重启 dsh：宿主侧为 Node ESM 模块，只有重启才会重新加载插件代码。
版本与依赖闸门¶
package.json 中 peerDependencies 要求 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-sandbox 为 ^0.2.0-rc.1，并与 @deepseek-ai/cordis ^4.0.1 配套。宿主启动时会按 semver 检查 peer；不满足时整包跳过（日志中可见 skipping profile bundle）。0.1.x 宿主不会加载当前版本；0.1.x 用户需使用仓库中面向 0.1.5-rc.2 契约的历史提交。运行环境需 Node >=22。
插件作者强调：@deepseek-ai/dsh-tools 与 @deepseek-ai/dsh-sandbox 只能出现在 peerDependencies（及开发用的 devDependencies），不可写入 dependencies，否则 profile 可能出现第二份核心包副本，导致工具调度 Symbol 分裂、进程内工具调用失败。
典型用法¶
工具名 python，主要参数如下（类型与含义以 README 为准）：
| 参数 | 类型 | 说明 |
|---|---|---|
code |
string（必填） | Python 程序原文 |
workdir |
string | 工作目录；缺省为会话 cwd |
timeout_ms |
number | 前台超时；后台不适用 |
run_in_background |
boolean | 后台运行并返回 job id |
sandbox_permissions |
enum | 对被拒绝调用的一次性提权重试 |
justification |
string | 审批面板展示的一句话说明 |
模型或 agent 在对话中调用该工具时，把完整源码放进 code 即可；需要长时间计算或流式观察输出时，使用 run_in_background 再配合 job_output。在指定目录下读写文件时，通过 workdir 限定范围，并遵守沙箱策略。
适用场景与注意¶
适合需要在 DSH agent 循环里快速验证算法片段、数据处理脚本、或与模型协作的短 Python 逻辑，且希望减少「写临时文件 + shell 执行」步骤的团队。后台作业适合耗时任务；沙箱与提权行为与 pwsh 一致，便于在同一 harness 里统一策略。
使用前请自行阅读 GitHub 仓库 源码与 MIT 许可证。插件在 当前 dsh 进程权限 下启动 Python 子进程，安装与提权等同于信任维护者与本地路径。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库页面为准（当前包版本 0.1.0）。
结尾¶
dsh-plugin-pyrun 用 stdin 直灌与 UTF-8 全链路，把 Python 快捷执行收成 harness 内的一个工具，并与沙箱、后台作业体系对齐。若你已在 0.2.x 上运行 DSH，可按 README 的 link: 或 profile 安装方式接入，重启后通过工具 python 调用。
- 目录页：https://www.skillhub.cn/plugins/ds-hu/dsh-plugin-pyrun
- GitHub：https://github.com/ds-hu/dsh-plugin-pyrun
