Pi 扩展兼容宿主 TGYD-helige/dsh-pi

DSH Pi

在 DeepSeek Harness 中运行可信、未经修改的 Pi 扩展。这是一个兼容性宿主，而非源码到源码的转换器：Pi 的官方加载器和 ExtensionRunner 负责 Pi 语义，而本包将其可观察的表面适配为 agent 作用域的 DSH 工具、命令、消息、附件和生命周期钩子。

该项目目前面向 Pi 0.80.x 和 DSH 0.1.5-rc.2。DSH 仍处于开发者预览阶段；peer 范围被有意收窄。

为什么使用宿主而非生成插件

扩展工厂是带有生命周期和会话状态的可执行代码。对其源码进行一次转换无法保留在 session_start 期间注册的工具、可变的活动工具集、取消、提供者或每个 agent 的状态。因此，宿主为每个 DSH agent 创建一个 Pi 运行时，并将注册项协调到该 agent 的 Cordis 上下文中。

flowchart LR
C["DSH bundle config"] --> R["Package / manifest resolver"]
R --> P["Pi loader + ExtensionRunner"]
P --> A["Agent-scoped adapter"]
A --> T["DSH tools"]
A --> M["DSH commands"]
A --> L["DSH lifecycle and messages"]
F["Existing Pi packages\nread-only fixtures"] --> R

本地开发

pnpm install
pnpm check
PI_FIXTURE_WORKSPACE=/absolute/path/to/pi pnpm test
pnpm compat /absolute/path/to/pi

位于 ../pi 的仓库仅被读取。兼容性测试会盘点其 packages/pi- 清单和源码 API 用法；代表性冒烟测试会加载已构建的入口，而不会调用付费工具。

作为 DSH bundle 安装

在同一 profile 中安装已发布的 bundle 以及你想要的 Pi 扩展：

dsh plugin --profile demo add dsh-pi-host \
@amaster.ai/pi-image-gen \
@amaster.ai/pi-video-gen
dsh --profile demo --dump-config

对于本地开发，将 dsh-pi-host 替换为此检出目录的路径，例如从父目录运行时使用 ./dsh-pi。

所选的 Pi 包必须安装在同一 DSH profile 中，以便裸包说明符能从该 profile 解析。DSH 可能会警告它们未声明 dsh.bundle；这是预期行为，因为它们是普通的依赖项，由 dsh-pi-host 加载，而非独立的 DSH 层。以相同方式安装 extensions 中指定的任何其他包。

选择 Pi 扩展

然后在 profile 的 cordis.patch.yml 中覆盖 bundle 行。DSH 会替换某一行的完整 config，因此请保留每个字段：

- id: dsh-pi
config:
extensions:
- '@amaster.ai/pi-image-gen'
- '@amaster.ai/pi-video-gen'
projectTrusted: false
allowLocalPaths: false
strict: false
flags: {}
strict: true 在任何选定的 Pi 工具 schema 无法在不拓宽的情况下表示时，会导致 agent 组合失败。使用 strict: false 时，这些工具会被跳过，从 Pi 可见的适配后活动集合中排除，并且只有在它们的定义发生变化或被重新激活后才会重试。数值边界（minimum/maximum/exclusiveMinimum/minItems）会传递到面向模型的 schema——执行时仍会根据原始 TypeBox schema 进行验证——因此当前的 pi-video-gen fixture 会挂载全部四个工具，包括 video_generate。

对于本地 fixture 包，启用显式的代码执行边界：

- id: dsh-pi
config:
extensions:
- '/Users/me/Workspace/pi/packages/pi-image-gen'
projectTrusted: false
allowLocalPaths: true
strict: true
flags: {}

allowLocalPaths 默认关闭，因为 Pi 扩展是受信任的 Node.js 代码，而不是沙箱化的插件。projectTrusted 是一个单独的开关：它控制扩展是否可以消费项目本地的 Pi 设置和策略。宿主只加载从 extensions 解析出的条目；它从不自动发现 /.pi/extensions。

更改 extensions 后重新加载 profile，然后运行 dsh --profile demo --dump-config 以验证生效的列表。

配置 Pi 扩展

将 Pi 设置放在 DSH profile 配置旁边，并将 PI_CODING_AGENT_DIR 指向该 profile 目录。使用 Pi 既有的 settings.json 文件名，而不是单独的 pi-settings.json 兼容格式：

$DSH_HOME/profiles/demo/
├── cordis.patch.yml # selects Pi extensions
└── settings.json # configures those Pi extensions

对于 pi-image-gen，最小配置选择一个模型并将 API key 保留在环境中：

{
"pi-image-gen": {
"defaultModel": "nano-banana"
}
}

export DSH_HOME="$HOME/.dsh"
export PI_CODING_AGENT_DIR="$DSH_HOME/profiles/demo"
export GEMINI_API_KEY="..."
dsh --profile demo

同一个设置文件可以在各自的顶层键下配置多个选定的 Pi 扩展。项目本地的 /.pi/settings.json 仅在启用 projectTrusted 时可用。

Pi API 到 DSH 的兼容性

状态：

- ✅ 支持 — 可观察到的 Pi 行为有对应的 DSH 映射。
- 🟡 部分支持 — 有用的行为可以工作，但缺少一些 Pi 语义。
- ❌ 不支持 — 目前还没有忠实的适配器；宿主不会假装它已生效。

ExtensionAPI 方法

| Pi ExtensionAPI | 最接近的 DSH 能力 | 此处已实现 | 备注 |
| pi.on(...) | Cordis ctx.on(...) 以及 DSH agent/session/tool 事件 | 🟡 部分支持 | 参见下面的生命周期事件表。 |
| pi.registerTool(...) | agent.ctx.tools.register(...) | 🟡 部分支持 | 执行、严格模式投影（包括不相交的 TypeBox 字面量联合类型和数值边界；$schema 草稿标记会被丢弃）、prepareArguments、取消、净化错误、有序更新、图像、并发、活动工具变更以及生命周期时注册/替换均可工作。成功的文本被限制为 50KB/2000 行，过大的详情会被省略，图像在解码前会对照 DSH 附件限制进行检查。无法表示的 schema 会被拒绝；Pi TUI 渲染器和 DSH 实时更新卡片则不会。 |
| pi.registerCommand(...) | agent.ctx.commands.register(...) | 🟡 部分支持 | 命令处理器、净化后的意外失败以及 ctx.ui.notify 文本均可工作。Pi 补全和交互式 ctx.ui 对话框则不会。 |
| pi.registerShortcut(...) | 没有插件自有的 DSH 键盘快捷键注册表 | ❌ 不支持 | 需要单独的客户端/UI 插件。 |
| pi.registerFlag(...) | DSH 插件配置加上嵌入式 Pi 标志存储 | ✅ 支持 | 默认值和配置的覆盖值使用 Pi 的官方运行器。 |
| pi.getFlag(...) | 读取嵌入式 Pi 标志存储 | ✅ 支持 | 保留 Pi 标志查找行为。 |
| pi.registerMessageRenderer(...) | DSH 可重放消息投影/UI 插件 | ❌ 不支持 | Pi TUI 组件无法作为 DSH 渲染意图重放。 |
| pi.registerEntryRenderer(...) | DSH 会话投影/UI 插件 | ❌ 不支持 | 同样的渲染器模型不匹配。 |
| pi.sendMessage(...) | agent.followup()、agent.steer()、agent.inject()、agent.send() | 🟡 部分支持 | 非唤醒空闲注入、触发回合、引导、跟进和原生下一回合投递可映射。附件持久化在生命周期边界处排空，并且在处置开始后投递会被抑制；持久化的 Pi 自定义条目、display、customType 和渲染器详情无法映射。 |
| pi.sendUserMessage(...) | agent.followup() / agent.steer() | ✅ 支持 | 文本和图像映射到已标识的 DSH 消息；图像使用 DSH 附件。 |
| pi.appendEntry(...) | 声明的自定义 SessionEventMap 事件加上 session.append() | 🟡 部分支持 | 仅存储在嵌入式 Pi 会话中；尚未持久化到 DSH 日志中。 |
| pi.setSessionName(...) | DSH 会话标题域/投影 | 🟡 部分支持 | 仅更新 Pi 侧的内存状态。 |
| pi.getSessionName() | 读取 DSH 标题投影 | 🟡 部分支持 | 返回 Pi 侧的内存名称。 |
| pi.setLabel(...) | 自定义 DSH 会话事件/投影 | 🟡 部分支持 | 仅存储在嵌入式 Pi 会话树中。 |
| pi.exec(...) | DSH 子进程/shell 服务 | ✅ 支持 | 使用 Pi 自己的进程运行器，支持 cwd、env、超时和取消选项。 |
| pi.getActiveTools() | ctx.tools.schemas(agent) / 作用域工具视图 | 🟡 部分支持 | 返回适配后的 Pi 工具的过滤活动集；不包含 DSH 原生工具。 |
| pi.getAllTools() | ctx.tools.get() / ctx.tools.schemas() | 🟡 部分支持 | 返回 Pi 的官方扩展注册表，而非 DSH 原生工具。 |
| pi.setActiveTools(...) | 释放/注册 agent 作用域的 DSH 工具效果 | 🟡 部分支持 | 协调已适配的 Pi 注册并忽略未知名称，但不会切换 DSH 原生工具。 |
| pi.getCommands() | ctx.commands.list(agent) | 🟡 部分支持 | 仅返回 Pi 扩展命令；不包含 DSH 原生命令、技能和模板。 |
| pi.setModel(...) | DSH Agent.options 加上已安装的 LlmAdapter | 🟡 部分支持 | 提供者/模型 id 可映射；DSH 仍掌控适配器可用性和凭据。 |
| pi.getThinkingLevel() | DSH 请求推理强度/请求头 | 🟡 部分支持 | 仅 Pi 侧状态。 |
| pi.setThinkingLevel(...) | DSH 请求推理强度/请求头 | 🟡 部分支持 | 尚未更新 DSH 推理强度。 |
| pi.registerProvider(...) | 注册 DSH LlmAdapter | ❌ 不支持 | Pi ProviderConfig 不是 DSH 适配器。请单独配置 @deepseek-ai/dsh-llm-pi-ai。 |
| pi.unregisterProvider(...) | 释放 DSH LlmAdapter 注册 | ❌ 不支持 | 宿主不拥有对应的 DSH 适配器。 |
| pi.events | Cordis 事件总线 | ✅ 支持 | Pi 的共享 EventBus 由官方 Pi 加载器直接提供。 |

ExtensionContext 与命令上下文

| Pi 上下文能力 | 最接近的 DSH 能力 | 此处是否实现 | 备注 |
| ctx.ui. | DSH 命令响应及可选的客户端 UI 插件 | 🟡 部分支持 | /command 处理器将 ctx.ui.notify 捕获为响应文本。对话框和 Pi TUI 控件使用 Pi 的空操作 UI 上下文。 |
| ctx.mode | 活动宿主传输 | 🟡 部分支持 | 报告嵌入式 Pi 模式（默认为 rpc），而非已连接的 DSH 前端。 |
| ctx.hasUI | 支持对话框的 UI 是否可用 | ✅ 支持 | 正确返回 false；此宿主不暴露任何 Pi 对话框。 |
| ctx.cwd | agent.session.header.cwd | ✅ 支持 | 使用 DSH agent 的工作目录。 |
| ctx.sessionManager | DSH 事件溯源会话 | 🟡 部分支持 | 提供内存中的 Pi SessionManager，但 DSH 历史不会投射到其中。 |
| ctx.modelRegistry | DSH LLM 适配器/目录服务 | 🟡 部分支持 | 记录 Pi 提供者注册；不暴露 DSH 适配器、凭据和模型目录。 |
| ctx.model | 选定的 DSH 提供者/模型 | ❌ 不支持 | 不会合成 Pi Model 对象。 |
| ctx.isIdle() | agent.status | ✅ 支持 | 读取 DSH agent 的实时状态。 |
| ctx.isProjectTrusted() | projectTrusted 配置 | ✅ 支持 | 返回显式的宿主信任决定。 |
| ctx.signal | DSH 轮次/工具 AbortSignal | ✅ 支持 | 作用域为单次调用，可安全用于并行 Pi 工具。 |
| ctx.abort() | agent.cancel(...) | ✅ 支持 | 取消当前 DSH agent 操作。 |
| ctx.hasPendingMessages() | DSH 收件箱 | ✅ 支持 | 读取 agent 收件箱。 |
| ctx.shutdown() | DSH agent 取消/释放 | 🟡 部分支持 | 取消当前 agent 操作；它不会退出 DSH 进程。 |
| ctx.getContextUsage() | DSH 用量投影 | ❌ 不支持 | 尚无 Pi ContextUsage 投影。 |
| ctx.compact(...) | DSH 压缩生命周期 | ❌ 不支持 | 契约不同，且不会调用任何操作。 |
| ctx.getSystemPrompt() | DSH 系统提示词组装 | ❌ 不支持 | 有效组装后的提示词未暴露给 Pi。 |
| ctx.getSystemPromptOptions() | DSH 组装上下文 | 🟡 部分支持 | 命令上下文仅接收 cwd。 |
| ctx.waitForIdle() | agent.whenIdle() | ✅ 支持 | 等待所属 DSH agent 稳定下来。 |
| ctx.newSession()、ctx.fork()、ctx.navigateTree()、ctx.switchSession() | DSH agent/会话创建 API | ❌ 不支持 | Pi 的可变会话树操作无法忠实映射；调用会显式失败。 |
| ctx.reload() | Cordis/DSH 插件重载 | ❌ 不支持 | DSH 负责插件重载；调用会显式失败。 |

生命周期事件

| Pi 事件 | 最接近的 DSH 事件/能力 | 此处实现情况 |
| project_trust | 部署/插件信任配置 | 🟡 配置的 projectTrusted 控制 ctx.isProjectTrusted()；交互式处理器不会运行。 |
| resources_discover | DSH 技能与系统提示词注册表 | 🟡 处理器会运行，但返回的技能/提示词/主题路径不会挂载到 DSH 中。 |
| session_start | agent/session-start | ✅ 按 agent 执行，并在第一步之前等待；在 DSH 恢复/清除/压缩时于 session_shutdown 之后重新发出。 |
| session_shutdown | agent/disposed / Cordis effect 释放 | 🟡 在每次 DSH 恢复/清除/压缩重启之前以转换原因运行，并在 agent 或插件拆除期间排空；拆除以原因 quit 报告给 Pi。 |
| session_info_changed | DSH 会话标题投影 | ❌ 未映射。 |
| session_before_switch、session_before_fork | DSH 会话准备/发布 | ❌ 尚无等效的否决映射。 |
| session_before_compact、session_compact | DSH 压缩插件/事件 | ❌ 压缩契约不同；在压缩生命周期变化后，会发出具有重载语义的 session_shutdown/session_start 重启。 |
| session_before_tree、session_tree | DSH 事件溯源会话历史 | ❌ Pi 树导航没有直接的 DSH 等效项。 |
| input | DSH 轮次的第一个 agent/pre-step | 🟡 continue、handled 以及文本/图像转换会针对初始认领的 DSH 消息批次运行一次。文本以换行符连接，图像会保留，转换会用一个新的 DSH 消息身份替换已认领的批次。 |
| before_agent_start | 第一个 agent/pre-step 加上 system-prompt/assemble | 🟡 处理器每次 agent 运行运行一次；返回的自定义消息和系统提示词替换尚未应用。 |
| agent_start | DSH 轮次中的第一个 agent/pre-step | ✅ 每轮发出一次。 |
| agent_end | 已提交的 DSH session/event: turn/end | 🟡 在 DSH 回合持久关闭后运行一次，包括错误和取消路径。文本历史可映射；精确图像、用量和工具消息会被缩减。 |
| agent_settled | 已提交的回合结束，且没有待处理的 DSH 收件箱消息 | 🟡 当没有排队输入剩余时，在 agent_end 之后发出；DSH 和 Pi 仍具有不同的队列模型。 |
| turn_start | DSH 步骤开始 | ✅ 每个 DSH 步骤发出一次。 |
| turn_end | 下一个 DSH 步骤 / 已提交的 turn/end | 🟡 与每个发出的 turn_start 配对，包括失败或中止的最终步骤；最终文本助手消息可映射，但 Pi 的 toolResults 不会被重建。 |
| context | DSH 持久请求重建 | ❌ 可变的 Pi 上下文数组无法安全替换 DSH 持久历史。 |
| message_start、message_update、message_end | DSH 会话消息/分块事件 | ❌ 尚无精确的实时消息映射。 |
| tool_call | tools/pre-execute / 适配的工具包装器 | 🟡 阻塞有效；DSH 会冻结参数，因此 Pi 处理器无法可靠地就地修改它们。 |
| tool_result | tools/post-execute / 适配的工具包装器 | ✅ 可以在 DSH 转换之前替换内容、详情和错误状态。 |
| tool_execution_start、tool_execution_end | DSH 工具执行流水线 | ✅ 围绕适配的 Pi 工具配对，包括失败和取消。 |
| tool_execution_update | 没有匹配的 DSH 工具拥有的实时更新回调 | 🟡 Pi 处理器在 tool_execution_end 之前接收并完成更新；DSH UI 不会流式传输它们。 |
| before_provider_request、before_provider_headers、after_provider_response | DSH LlmAdapter 边界 | ❌ 必须在 DSH 提供程序适配器内部实现。 |
| model_select、thinking_level_select | DSH 代理/请求配置 | ❌ 尚无选择事件映射。 |
| user_bash | DSH shell 工具策略/事件 | ❌ DSH 不暴露 Pi 的用户 bash 拦截契约。 |

宿主还提供 Pi 包清单发现、通过 DSH 配置进行动态扩展选择、每个 DSH 代理一个官方 Pi 运行时、HMR 安全的副作用处置，以及针对并行工具的调用作用域取消。

请参阅详细兼容性矩阵以及 src/capabilities.ts 中可执行的真相来源。

发布

Git 安装需要 pnpm 权限来运行此包的 prepare 构建。npm 包附带预构建的 lib/，不需要安装时构建权限。维护者通过推送与包版本完全匹配的标签来发布，例如 v0.1.0-rc.2；发布工作流会使用仓库的 NPM_TOKEN 密钥验证、构建、测试并发布 dsh-pi-host。预发布版本使用 npm 的 next 标签，稳定版本使用 latest。