Dwsy/dsh-pi-extension-bridge

dsh-pi-extension-bridge

一个用 TypeScript 编写的兼容桥，把 Pi Coding Agent 的扩展能力适配到 DeepSeek DSH，包括扩展资源、工具、命令、生命周期事件，以及 DSH Web 端中的 Pi 风格终端 UI 渲染。

本项目是集成桥，不是对 Pi 或 DSH 的重新实现。原则是优先复用宿主原生能力；只有语义能够可靠对应时才做映射，无法无损映射时明确降级或报错，不伪造兼容。

主要能力

- TypeScript 权威源码：src/ 是唯一源码入口，lib/index.js 与 lib/client.js 是生成的运行产物。
- Host 多模块架构：runtime/session、lifecycle、resources/tools、message conversion、Typert protocol、UI registry、terminal surface 各自独立。
- Pi 原生扩展加载：复用 Pi loader/runtime，不维护手写扩展清单。
- DSH 原生能力优先：在 session scope 内桥接 tools、commands、skills、prompt resources、model/thinking 与 lifecycle；DSH 已经拥有的宿主能力不重复接管。
- Web 终端 UI：保留 ANSI、终端列宽、overlay、自定义 TUI 输入、WTerm 渲染与 Pi 光标元数据。
- Host-plane UI + revision 驱动传输：Web Host 全局持有 piExtensionUi Typert 路由，Pi tools/commands 仍保持 session scope；每个 session 通过 waitRevision() 唤醒，静止 UI 不持续轮询 snapshot。
- Pi tool renderer：支持把 Pi 的 renderCall / renderResult 自定义渲染接到 DSH tool view。
- Pi 资源管理器：DSH Web 设置页新增 Pi Resources 工作台，直接读取当前挂载 Pi runtime 的真实 loader/runner catalog，可搜索并查看 extensions、tools、commands、skills、lifecycle handlers、prompts、themes、context files、shortcuts、flags、renderers、diagnostics 与 runtime/context bridge 状态及来源。
- 隔离回归测试：测试 Web Host 使用独立端口，不重启或替换用户正在运行的 DSH。

环境要求

- Node.js 22+（当前开发验证使用过 Node.js 24）
- 提供本桥所需 Web Client/runtime services 的 DSH
- Host 可访问 Pi Coding Agent 安装与资源

当前配置中保留了面向本地开发环境的 Pi/DSH 默认路径。如果你的安装位置不同，请通过 bridge 配置覆盖。

本地安装与构建

目前仓库定位是本地 DSH 插件开发，不是 npm 发布包。

npm install
npm run typecheck
npm run build

运行时 export 契约保持不变：

- . → lib/index.js（Host）
- ./client → lib/client.js（Web Client）

通过 DSH/Cordis 配置或 scoped preset 挂载。本项目当前的开发约束是只在 Pi 风格 session scope 中启用，避免污染所有标准 DSH session。

开发命令

TypeScript 正确性检查
npm run typecheck

构建 Host + Client
npm run build

单独构建
npm run build:host
npm run build:client

检查生成 JS 语法
node --check lib/index.js
node --check lib/client.js

不要直接修改 lib/ 下的生成文件；修改 src/ 后重新构建。

架构

Host 入口只负责组装，主要职责已经拆到独立模块：

| 模块 | 职责 |
| --- | --- |
| src/host/index.ts | 插件组装、Host service 注册、bridge wiring |
| src/host/runtime-bridge.ts | Pi runtime actions、model/thinking/session 适配 |
| src/host/ui-surface.ts | terminal surface、overlay、ANSI/cursor、输入路由 |
| src/host/lifecycle.ts | Pi lifecycle、prompt、command 集成 |
| src/host/resources.ts | extension loading、resources、skills、tools、command adapters |
| src/host/messages.ts | DSH ↔ Pi message/replay 转换 |
| src/host/ui-protocol.ts | piExtensionUi Typert wire descriptors |
| src/host/ui-registry.ts | session 级 UI bridge registry |
| src/host/config.ts | 配置归一化 |
| src/client/index.ts | DSH Client module 与 slot 组装 |
| src/client/terminal-layout.ts | 终端字体度量、列宽与 overlay 几何 |
| src/client/types.ts | snapshot/frame 类型 |
| src/client/errors.ts | remote envelope 与错误解码 |

更完整的数据流与边界见 架构文档。

Pi UI 渲染契约

浏览器端把 Pi UI 当作终端 frame，而不是普通 React 文本：

- ANSI 原样进入 WTerm；去 ANSI 的 lines 只作为 fallback/debug。
- 宽度按终端列计算，并使用浏览器中实际等宽字体的测量结果。
- Pi CURSOR_MARKER 会在 Host 侧转换成 row/column cursor metadata，用于硬件光标与 IME 定位。
- custom component / overlay 获得焦点时优先接收键盘输入，然后才考虑全局 extension shortcut。
- UI 静止时不产生周期性 /snapshot 请求；Host revision 变化后才唤醒 Client 获取下一帧。

兼容边界

本项目追求“明确的兼容”，而不是宣称所有 Pi API 都能与 DSH 一一对应。详细实现状态与历史验证证据见：

- COMPATIBILITY_MATRIX.md
- STATE.md

当 DSH 没有公开等价 primitive 时，对应能力可能只能部分支持。这类边界应明确保留，而不是通过修改全局状态等危险方式伪装实现。

回归测试

不要为了测试 bridge 重启、kill 或替换用户正在运行的 DSH Web/TUI。使用独立端口：

dsh --profile web --port 3081

最低回归范围：typecheck/build、生成 bundle 语法、Web 启动、ANSI 样式、自定义 TUI 输入、cursor/IME、overlay 尺寸、extension shortcut 路由，以及 Pi Resources catalog 加载/搜索/详情渲染。自定义 TUI 还必须覆盖“点击 surface 后 Escape 仍由 WTerm 捕获并关闭 overlay”的焦点回归。

当前状态

TypeScript 模块化重构已经完成：原先的 Host 巨型单文件已经按职责拆分，Host entry 只保留组装流程；Client 也已经迁移到 TypeScript。当前 typecheck/build gate 均通过。详细工程接力信息以 STATE.md 为准。

贡献约定

保持依赖方向简单：protocol/config/conversion 等叶子模块不要反向依赖 composition entry。不要重新引入 *-vN.js 形式的临时版本文件。提交前至少运行：

npm run typecheck && npm run build
node --check lib/index.js
node --check lib/client.js

License

目前尚未添加开源许可证。公开可见不等于自动授予复制、修改或再分发权限；如果你希望开放这些权利，请后续明确选择许可证。