dsh-pi-extension-bridge

English | 简体中文

一个用 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 与错误解码

更完整的数据流与边界见 [架构文档](docs/ARCHITECTURE.zh-CN.md)。

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](COMPATIBILITY_MATRIX.md)
[STATE.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

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

来源信息

安装

检查来源文件