AngelosZou/dsh-python-env

English | 中文

面向 DeepSeek Harness 项目的工作区级 Python 虚拟环境管理——发现、创建、安装、删除虚拟环境，远离沙箱、网络与子进程的坑。

一个 DeepSeek Harness 插件，为每个项目（工作区）提供面向 Agent 的 Python 虚拟环境管理：

• 五个模型工具 —— pyenv_discover、pyenv_create、pyenv_install、pyenv_uninstall、pyenv_remove，外加 python-env 技能与 system-prompt 引导段。
• 通过平台 subprocess 通道（宿主进程）运行标准库 python -m venv / pip，而非沙箱 shell——venv 创建、ensurepip 引导、包索引网络访问在 shell 侧 pip 会失败的地方照常工作。
• 镜像与代理回退 —— 网络类失败时按清华 TUNA → 阿里云 → 中科大 USTC 镜像链重试，并探测常见本地代理端口；index / proxy 参数可分别钉死。
• 工作区约束 —— 所有路径都解析在工作区内（Windows 大小写不敏感）；缓存与临时状态位于 <工作区>/.dsh-pyenv/；命令为 argv 数组（不经 shell）；全局 Python 环境、宿主 pip 缓存、系统临时目录永不被触碰。
• 跨平台 —— Windows / macOS / Linux 的布局与解释器链（Scripts 与 bin、py -3 与 python3）。
• 零第三方依赖 —— 不需要 uv、virtualenv 或任何其他插件；缺失 pip 的环境用 ensurepip 离线修复。
• 会话模式对齐 —— 写工具遵循会话沙箱模式，read-only 会话中拒绝执行；发现工具始终可用。

环境要求

• Node.js >= 20
• 由 @deepseek-ai/dsh-base 组合的 DSH profile（提供插件使用的 subprocess、jobs、tools、skills 服务）
• Python >= 3.8（在 PATH 上，或显式传入）——仅用于插件管理的环境

安装

从 npm：

dsh plugin --profile web add dsh-python-env

从本地检出（开发）：

dsh plugin --profile web add link:<本仓库绝对路径>

然后重启 DSH 后端（宿主组合在进程启动时加载）。新会话中即出现 pyenv_discover / pyenv_create / pyenv_install / pyenv_uninstall / pyenv_remove 五个工具与 python-env 技能。

用法

Agent 侧：

工具	作用
pyenv_discover	按 pyvenv.cfg 标记或常见命名（.venv、venv、env、.env、virtualenv）在工作区内最多两层深度发现环境，报告路径、解释器、版本、pip 状态。
pyenv_create	用 python -m venv 创建环境——支持 name / root_dir / 基础 python 参数，对已存在环境幂等。
pyenv_install	把 packages 和/或 requirements 文件装入环境（显式 venv / 自动发现 / 自动创建 .venv）；ensurepip 修复缺失 pip；镜像/代理回退；upgrade 升级；本地项目 editable 安装；run_in_background 支持长安装。
pyenv_uninstall	从环境卸载包（pip uninstall -y）；离线；从不自动创建环境。
pyenv_remove	只删除工作区内的真实环境（拒绝非环境目录与工作区逃逸）。

pyenv_create                                  # -> 创建 .venv 并报告解释器路径
pyenv_install { packages: ["pytest>=8"] }     # 装入 .venv
pyenv_install { requirements: "requirements.txt" }
pyenv_uninstall { packages: ["pytest"] }      # 再卸载
pyenv_discover                                # 查看全部环境
# 用报告的解释器路径运行代码：
#   Windows: <venv>\Scripts\python.exe    macOS/Linux: <venv>/bin/python

行为说明：

• 写工具（create / install / uninstall / remove）遵循会话沙箱模式，read-only 会话中拒绝执行；发现工具仍可用。
• 常见需求覆盖：版本（"pkg==1.2.3"）、升级（upgrade: true）、按 requirements.txt 安装（requirements）、本地项目 editable 安装（packages: ["-e", "."]——editable 路径必须位于工作区内，远程/VCS editable URL 会被拒绝）。
• 未传 venv 时，pyenv_install 使用唯一发现的环境（优先 .venv），不存在则自动创建 .venv，存在多个则要求显式指定。
• 后台安装注册到 jobs 运行时——用 job_output 轮询、job_kill 停止。
• 两分钟预算。 每个 pyenv 工具必须在 2 分钟内完成（发现工具 1 分钟内）。超出预算时工具会终止运行中的进程树，并返回详细的停止原因——正在执行的操作、已尝试的索引/代理、最后输出、可能的原因与下一步建议——而不是挂起或只报一个干巴巴的超时。后台安装同样受 2 分钟上限约束；install/uninstall 的按次 timeoutMs 参数仍然有效，但上限为 120000 ms。

工作原理

• Subprocess 通道 —— DSH 沙箱会拦截 CPython 的 owner-only 临时目录（Windows 上 ensurepip / wheel 解包时 [Errno 13]）与包索引网络访问。插件代码运行在宿主进程中，因此所有 python/pip/venv 调用都走 ctx.subprocess（与 graphlint 插件同通道）：argv 数组、字节上限的输出收集、进程树级终止。非受限 token 由下述约束模型补偿——而非削弱沙箱。
• 约束模型 —— 每个受模型影响的路径都经过 guardWorkspacePath（绝对解析 + 包含性判定，防 ..）；venv 名称经单段正则校验并在 join 后再次守卫；子进程的 PIP_CACHE_DIR / TMP / TEMP / TMPDIR 重定向到 <工作区>/.dsh-pyenv/。
• 安装尝试链 —— 先走默认索引；网络类失败（连接重置/超时/DNS——绝非"No matching distribution found"或 TLS 错误）按 TUNA → 阿里云 → USTC 镜像回退，并一次性探测常见本地代理端口（7890、7891、10809、10808、8888），命中则经代理重试同一索引。
• ensurepip 修复 —— <venv-python> -m ensurepip --upgrade 用内置 wheel 离线引导 pip；ensurepip 本身缺失时报错附带 Debian/Ubuntu python3-venv 提示。
• 并发 —— 写工具声明 isConcurrencySafe: false，调度器原生串行化；发现只读。
• 技能与引导 —— python-env 技能教 Agent 工具优先与"绝不为 pip 申请升级"的规则；system-prompt 段（dsh-python-env:guidance，order 120）提醒每个会话 pyenv 工具才是正规路径。

项目结构

路径	用途
cordis.patch.yml	Profile 补丁层，插入 dsh-python-env 行
lib/index.js	宿主插件：注册五个工具、技能与引导段
lib/tools/	五个模型工具（discover / create / install / uninstall / remove）
lib/guard.js、lib/venv.js、lib/layout.js、lib/paths.js、lib/python.js	工作区约束、venv 解析、发现、平台布局、解释器链
lib/runner.js、lib/pip.js、lib/envdir.js	Subprocess 通道、安装链、工作区缓存
test/	无运行时行为测试（见开发）
docs/	设计与分析文档

开发

无构建步骤：插件是纯 ESM，测试直接用 Node 运行（mock ctx 替代 DSH 服务；真实的 defineTool 校验所有 schema）：

npm test
# 或：node --test --test-isolation=none "test/*.test.js"

开发循环（含离线依赖解析）见 CONTRIBUTING.md。

兼容性

当 DSH 同时安装了 dsh-multi-folder 插件时，Agent 可以通过 dsh-python-env 提供的工具管理在 dsh-multi-folder 中由用户指定的副工作目录，即使该工作目录不在主要工作目录内。对副工作目录的环境管理权限与主要工作目录一致，当Agent处于Read Only模式运行时，工具会拒绝任何操作。这一兼容是自动及可选的，当DSH环境中同时安装了dsh-multi-folder和dsh-python-env时这一兼容功能会自动生效。如果环境中未安装dsh-multi-folder，这不会对dsh-python-env的功能造成任何影响。这一兼容不会带来任何额外的性能负担或上下文开销。

安全

安装包意味着执行第三方代码：pyenv_install（含自动创建 .venv 的路径）会以宿主用户权限从配置的索引下载并运行代码，editable 安装会原样引入工作区内的项目。插件的缓解措施包括：仅 HTTPS 索引、爆炸半径限定在工作区（被攻破的环境可用 pyenv_remove 一次性丢弃）、路由全程透明、会话模式对齐（read-only 会话无法触发任何安装）、按 profile 选择安装。完整威胁模型与缓解清单见 SECURITY.md。

文档

• docs/design.md —— 架构、约束模型、安装链、已知限制
• SECURITY.md —— 威胁模型与补偿控制

参与贡献

见 CONTRIBUTING.md。欢迎提 issue 与 pull request。

许可证

MIT