前言¶
DSH 默认走「工具调用」这一步：模型一次拿一个工具的参数，调完把结果带回对话，再决定下一步。单步读写没问题，遇到「循环分页处理」「先筛一批结果再汇总」「条件分支串联多次调用」这类任务，往返次数会迅速膨胀，中间结果也要反复塞进上下文。
CodeBridge 针对这个问题做了一件事：给标准模式加一个代码执行入口，让模型在一次调用里写 JavaScript / TypeScript，通过 tools.* 串联多个工具、控制流程，再把需要的结果返回给模型。原有的原生工具仍然可以直接调用，二者共存。
下面介绍这个插件。CodeBridge 由 MUKAPP 维护，仓库是 MUKAPP/dsh-codebridge，分类属于工作流类插件。当前版本 0.1.1，声明兼容 DSH 0.2.2-rc.1、Node.js >=24.9.0，许可证 MIT。
能做什么¶
官方 README 列出的能力，按用途归一下：
- 会话内状态：默认在同一会话里保留变量、函数、导入和中间结果，后续调用直接复用，不用包一层函数。
- 用代码串工具：支持条件判断、循环、结果筛选和汇总，减少模型往返。
- 先查结构再调用：按名称或描述搜索当前可见工具，再按需取参数和返回 schema；也可以只做只读环境诊断。
- 可选重启恢复：开启后自动保存受支持的顶层 JSON 数据变量，重启后按原变量名恢复，不重跑历史代码。
- 大输出可恢复：全文保存成功后缩短展示，保留规范 JSON 并提供取回位置。
- 沿用当前权限：每个子调用都经过 DSH 工具管线，保留可见性检查、审批、取消和调用记录。
- 与 PTC Plus 共存：使用专用官方 Node 运行时
codebridge-runtime，与公共运行时命名隔离。
需要说明的是，README 明确写了标准模式的工具 schema 仍然保留，CodeBridge 不承诺固定的 token 节省比例。
安装与启用¶
在 DSH 的「插件 → 添加插件」中输入 GitHub 地址：
https://github.com/MUKAPP/dsh-codebridge.git
安装过程会从源码编译插件，仓库的 prepare 和 prepack 脚本会编译 Host 与 Web 客户端。如果管理器提示构建脚本待批准，先核对该仓库的编译脚本再决定是否允许。安装完成后按管理器提示启用或重启 DSH，只刷新浏览器页面不会重新加载 Host 插件。
命令行方式可以装到指定 profile，下面以 web 为例：
dsh plugin --profile web add https://github.com/MUKAPP/dsh-codebridge.git
注意安装会影响使用该 profile 的全部会话。插件当前只声明支持 DSH 0.2.2-rc.1，其他版本需要先适配，不能靠忽略版本检查来兼容。
升级时同样需要重新加载整个 dsh-codebridge 组合包，使工具和专用运行时一起更新为持久模式。卸载时关闭或移除整个组合包，等待会话资源释放。
两个工具¶
插件提供两个工具：
| 工具 | 参数 | 用途 |
|---|---|---|
codebridge_exec |
code、description、可选 timeoutMs、maxInlineBytes |
执行代码并返回日志与结果 |
codebridge_tools |
names 或 query，可选 detail、offset、limit、diagnostics |
搜索摘要、查询完整结构或只读诊断 |
code 是 TypeScript REPL 源码，支持顶层 await 和最后一个表达式。工具名和返回结构以当前会话的查询结果为准，代码里拿到的是工具的规范 JSON，可能与原生工具展示的文本不同。子工具失败会抛出可捕获的 ToolCallError，包含 name、toolName 和 message。
典型用法：先查询，再调用，再编排¶
不知道工具名时，先让模型调用 codebridge_tools 按描述搜索：
{ "query": "文件", "limit": 20 }
搜索不区分大小写，按去除首尾空白后的子串匹配，query: "" 可以浏览全部可见工具。默认只返回名称和说明，不附带参数与返回结构。结果按名称排序，total 是匹配总数，有后续页时返回 nextOffset。limit 默认 20，范围 1–100，offset 默认 0。
找到目标后用精确名称查完整结构：
{ "names": ["working_directory"] }
names 查询默认返回名称、说明、完整 parameters 和 output，不可用的名称出现在 unavailable 里。确认参数后就可以调用 codebridge_exec：
{
"description": "读取当前工作目录",
"code": "const directory = await tools.working_directory({}); directory",
"timeoutMs": 10000
}
同一个会话里可以跨调用复用绑定。第一次调用准备数据和函数：
const values = [12, 8, 5]
function total() { return values.reduce((sum, value) => sum + value, 0) }
total()
下一次调用直接接着用：
values.filter(value => value >= 8).map(value => value * 2)
默认只在当前进程内保留会话状态。开启「重启后恢复」后，插件会额外保存受支持的顶层 JSON 数据变量，进程重启后从最近快照恢复；函数、模块和句柄不恢复。文件写入、网络请求和其他外部副作用不会因为代码失败而回滚。
设置项¶
在「设置 → 插件 → CodeBridge」里改两个开关，保存后即生效；配置属于当前 profile，使用该 profile 的会话共享设置。
| 设置 | 配置键 | 默认 | 行为 |
|---|---|---|---|
| 保留会话状态 | retainSessionState |
开启 | 同一会话复用 Node REPL；关闭后下一次调用释放旧环境，以新环境执行 |
| 重启后恢复 | restoreOnRestart |
关闭 | 需同时开启会话保留；保存与恢复受支持的顶层 JSON 数据变量 |
恢复功能只跟踪顶层的 const、let、var 声明（含解构），且只支持有限数字、字符串、布尔值、null 和普通 JSON 数组/数据对象。函数、类实例、Promise、句柄、getter、Proxy、循环引用、嵌套作用域属性和 globalThis 上的新增属性都不在恢复范围。每次快照的完整记录上限为 1 MiB。恢复只注入数据，不重跑原始代码。
运行时的限额在 codebridge-runtime 里调整：
| 配置 | 默认值 | 含义 |
|---|---|---|
executionMode |
persistent-in-memory |
每个会话保留一个 Node REPL；可选 JSON 数据快照恢复 |
timeoutMs |
120000 |
默认执行超时，毫秒 |
maxTimeoutMs |
600000 |
单次超时参数的上限，毫秒 |
maxOutputBytes |
67108864 |
日志与结果的合计输出上限，64 MiB |
CodeBridge 要求运行时保持 persistent-in-memory 和 programFormat: "repl"。手动改回 per-call 时，codebridge_tools({ diagnostics: true }) 会报告配置未就绪，代码执行也会明确拒绝，避免把 REPL 末尾表达式误交给函数体 runtime。
执行规则与注意点¶
阅读使用时要注意几条硬约束：
- 子调用串行：提交多个 Promise 不代表并行，所有异步工具调用都要
await，程序结束时未完成的调用会被取消并等待收尾。timeoutMs不含收尾工作。 - 遵守作用域：只能调用当前代理可见的工具，不提供递归调用 CodeBridge 或
run_code的入口，代码工具本身没有提权参数。 - 沙箱沿用宿主：Node 文件、网络和子进程操作受实际宿主策略约束。Windows 后端可能报告
partial，不能当成完整隔离。 - 大输出：
maxInlineBytes默认32768（32 KiB），范围1024–262144。超预算时插件用宿主已挂载的spillStore保存完整 JSON 并展示首尾预览；预览文本可能在 JSON 中间省略，不能当作完整 JSON 解析。 - 诊断非安全证明：
diagnostics返回stateRetention、stateRecovery、configurationReady等状态，但configurationReady只表示配置检查未发现问题，不证明沙箱完整隔离。运行时缺失时应恢复整个组合包，单独启用公共 Node 运行时可能无效。
安装前建议先读一遍仓库源码与编译脚本，确认许可证和权限符合自己环境的约束。插件以当前 DSH 进程权限运行，没有独立的提权通道。
目录页与源码¶
- 社区插件目录：https://www.skillhub.cn/plugins/MUKAPP/dsh-codebridge
- GitHub：https://github.com/MUKAPP/dsh-codebridge
需要说明的是，社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，也不等于官方应用商店。
CodeBridge 把「多步工具编排」收敛到一次代码调用里，状态在同一个会话里保持，权限仍走宿主的原生管线。适合需要在标准模式下做分页、筛选、汇总这类链路的场景；如果只是单步读写，直接调原生工具更省事。
