编码代理接入器 fatwang2/pi-dsh

pi-dsh

Pi Coding Agent provider 扩展，将 DeepSeek Harness（dsh）暴露为可选的 provider。选择 dsh provider 后，每一轮都会路由到 DSH 自身的 harness，运行一个进程内的 cordis 树，并带有按对话持久化的会话池，而不是 HTTP LLM 端点。

上下文归属 = DSH。 DSH 原生加载自己的系统提示词、AGENTS.md（~/.dsh/AGENTS.md + 通过 dsh-agent-instructions 加载的项目 AGENTS.md 链）以及技能（~/.agents/skills、~/.dsh/skills、项目 .dsh/skills + 通过 dsh-skill-filesystem 加载的 .agents/skills）。pi-dsh 不会再次转发 pi 的 AGENTS.md/技能——那会导致重复加载。

要求

- Pi Coding Agent 宿主（@earendil-works/pi-ai / @earendil-works/pi-coding-agent >= 0.82.0）
- 池模式需要真实的 DSH 安装（~/.dsh/profiles/headless + 凭据）；oneshot 回退需要 PATH 中有 dsh
- 运行验证脚本需要 Node.js >= 22（test/verify-pathb.mjs 通过原生类型剥离导入一个独立的 .ts 模块）

工作原理

- 注册一个 provider dsh，使用自定义的 api: "dsh-exec" 和非 HTTP 的 baseUrl: "dsh-exec://local"。
- 池模式（默认，mode: "pool"）：每个进程启动一个进程内的 DSH cordis 树（dsh-base 组合，禁用 HMR 行），然后维护一个活跃 agent 池——每个 Pi 对话对应一个 DSH 对话，以 Pi 的 session id 为键（LRU 上限 8，空闲 TTL 15 分钟）。每一轮都是 agent.followup(...)，session/event 事件流被转换为 Pi 的 AssistantMessageEventStream——text_delta / thinking_delta，工具活动以 thinking 块的形式展示——因此回答是实时流式输出的，而不是一次性整块返回。
- 一次性回退（mode: "oneshot"）：path-B 之前的行为——启动 dsh --profile headless ""，收集 stdout，输出一个文本块。保留为可配置选项，以防 rc 树出现异常。
- DSH 拥有提示词/记忆/技能；pi-dsh 只路由最新的用户消息。跨轮连续性来自 DSH 的会话持久化（~/.dsh/sessions JSONL）：恢复的 Pi 对话会恢复同一个 DSH 会话（通过确定性的 session id，因此连续性甚至能在宿主重启后保持）。

权限

嵌入式 DSH 树以 sandbox danger-full-access + approval never 启动，在 src/dsh-host.ts 中于启动时打补丁（否则 dsh-base 会默认使用 workspace-write + approval ask）。
这是一个安装时的信任决策，而不是每次操作的关卡。DSH 在 provider 内部运行自己的工具循环（bash/fs/subagents），这些活动以 thinking 块的形式呈现——Pi 的审批 UI 从设计上就永远不会看到或拦截这些调用（将它们作为 Pi 的 toolcall_ 事件转发会把工具执行交给 Pi 的 agent 循环，并导致该轮次被无限重新驱动）。因此，一旦安装了 pi-dsh，该 harness 就会以你的完整本地访问权限行事，并且没有任何东西——无论是 Pi 还是 DSH——会在模型写入文件或运行命令之前进行提示。这与 pi-claude-bridge 的 permissionMode: "bypassPermissions" 以及 pi-cursor-sdk 的 SDK 嵌入（完全没有权限对话框）如出一辙。

这两个设置是一对，而其中只有一个才是真正让工具得以运行的关键。danger-full-access 在沙箱层允许一切，因此永远不需要升级。审批 never 并不意味着“自动批准”——dsh-user-approval 会将其解析为 rejected——它意味着升级请求会确定性地失败，并且模型会事先被告知不要尝试 sandbox_permissions。

- DSH 的文件沙箱不会限制来自嵌入式树的写入。
- 在任何模式下，网络/进程策略都超出了 DSH 的 SandboxMode 词汇范围。
- 限制该树（例如 workspace-write）需要首先将审批请求桥接到 Pi 的权限 UI，这是一项有意为之的未来变更。仅仅降低沙箱模式是行不通的：ask 会诱使模型升级，但在没有挂载应答者的情况下，每个请求都会以 unavailable 失败关闭，因此它会在永远无法成功的重试上浪费步骤。

安装

已发布到 npm：

pi install npm:pi-dsh

对于本地开发，请将此仓库的绝对路径添加到 ~/.pi/agent/settings.json → packages：

{
"packages": [
""
]
}

然后重启 pi（或你的 pi 宿主）。dsh provider 会出现在 /model 中，形式为 dsh/——即 DSH 自身被配置为运行的模型（~/.dsh/settings.yaml → agent-default-model，例如 dsh/deepseek-v4-pro）。
当该文件不可读时，目录会回退到一个合成的 dsh/dsh-harness 条目。DSH 拥有模型选择权；pi-dsh 只是镜像它。

依赖布局

@deepseek-ai/ 是固定版本（0.1.0-rc.6）的 pi-dsh dependencies，并作为真实安装存在于此仓库的 node_modules 中，与 pi 宿主的依赖图隔离（dsh 会拉取 zod@4，而它绝不能在一个固定 zod@3 的宿主上被提升）。pi 宿主包和开发工具通过作用域级符号链接解析到宿主安装中。有关确切的布局和理由，请参见 plans/002-design-notes.md。

开发

npm install # 安装固定版本的 @deepseek-ai/* 依赖 + 开发工具
将 pi 宿主包指向你的 pi 安装（单一物理 pi-ai 实例）： ln -s /node_modules/@earendil-works node_modules/@earendil-works
npm run typecheck # tsc --noEmit
npm run verify # provider 注册检查
npm run verify:stream # oneshot 模式回归测试（fake dsh）
npm run verify:pathb # pool 模式集成测试（真实 dsh；若不存在则 SKIP）

配置（可选）

~/.pi/agent/dsh.json：

{
"mode": "pool",
"poolMax": 8,
"poolIdleTtlMs": 900000,
"dshBin": "dsh",
"timeoutMs": 1800000
}

- mode："pool"（默认）或 "oneshot"。
- poolMax：池中最大会话数（超出时按 LRU 淘汰）。默认 8。
- poolIdleTtlMs：池中会话关闭前的空闲时间，单位毫秒。默认 15 分钟。
- dshBin：仅由 "oneshot" 回退路径使用。默认 dsh。
- timeoutMs：仅由 "oneshot" 回退路径使用（每次运行的预算）。默认 30 分钟。

环境变量覆盖：PI_DSH_MODE、PI_DSH_POOL_MAX、PI_DSH_POOL_IDLE_TTL_MS、PI_DSH_BIN、PI_DSH_TIMEOUT_MS。

版本固定策略

进程内 DSH 接口不稳定（0.1.0-rc.6、SESSION_FORMAT_VERSION = 0、“不隐含任何兼容性保证”）。@deepseek-ai/ 在 package.json 中固定为精确版本（不带 ^），并且每一处 @deepseek-ai/ 导入都被隔离在 src/dsh-host.ts 之后（唯一的收口点）。任何 dsh 升级（0.1.0-rc.x → 更新版本）都需要重新运行 Phase 1–2 的 spike 门禁（记录在仓库的 plans/ 笔记中——不会随 npm tarball 发布），然后才能提升版本固定——assistant/chunk / turn/end 事件词汇表没有任何兼容性保证。

限制

- Pool 模式需要真实的 DSH 安装（~/.dsh/profiles/headless + ~/.dsh/.credentials.yaml 中的凭据）。如果 rc 树行为异常，设置 mode: "oneshot" 回退到无状态子进程路径（无连续性，无流式输出）。
- 中止（Abort）会取消当前活动轮次，但保留池中会话；只有在真实轮次出错时，或由空闲 TTL/LRU 清理器触发时，条目才会被销毁。
- 工具调用运行在 DSH 自己的工具循环内，并按其时间顺序位置显示为思考块（调用时显示 [tool] …，完成时显示 [tool result] …）——因此流按时间交错（思考 → 工具 → 思考 → 工具），而不是把工具堆叠到单独区域。它们永远不会是 Pi 的 toolcall_* 事件：外来的 toolCall 块会让 Pi 的 agent 循环接管工具执行，产生空的 toolResults 并重新驱动该轮次（无限循环）。
- 用量（Usage）按轮次报告：DSH 的 usage 块是按模型调用计的（已对照持久化会话验证），因此 pi-dsh 会对该轮次的块求和；totalTokens 保持在提示词侧，这样 Pi 的自动压缩就永远不会误触发。

验证

npx tsc --noEmit # 类型检查
node verify.mjs # provider 已注册
node verify-stream.mjs # path-A（oneshot）回归测试，对照 fake-dsh.sh
node test/verify-pathb.mjs # path-B pool 集成测试（真实 dsh；若不存在则 SKIP）