工具能力：注册分派与独立执行服务

tools 持有工具定义、策略和结果处理，文件、Shell 与 PTC 能力通过各自服务提供执行。消费者先解析执行请求，提供者落实运行与隔离，工作所有者承担取消和清理。

工具注册表消费三类执行能力

箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。

文字关系说明与章节链接

tool-fs →（登记工具）→ tools；bash / pwsh tools →（登记工具）→ tools；tool-fs →（文件服务）→ ctx.fs / fs-local；tools →（程序与工具绑定）→ ptc-runtime；bash / pwsh tools →（执行服务）→ ctx.shell / executor。

tool-fs · tools · bash / pwsh tools · ctx.fs / fs-local · ptc-runtime · ctx.shell / executor

tools 统一定义、策略与结果事件

dsh-tools 持有工具定义。模型接收可见的输入 schema，宿主内部字段不应被混进模型参数；执行返回的规范结构化值由 output.schema 校验，render(args, value) 将其转换为内容。

dsh-tools · 接口摘录，省略上下文 · ctx.tools.guard · packages/core/tools/README.md

// 策略插件注册同步单向拒绝检查；后续监听器不能把已拒绝调用改成允许。
const dispose = ctx.tools.guard(guard)

projectContent 接收不可变执行身份与后置策略前的规范结果，返回替换内容或 undefined（保留 render 输出）；绕过后置策略的流水线失败不执行此步。tools/post-execute 可接受结果、替换内容或重新校验替换值，也可附加上下文或把结果阻止为错误。随后可选的同步 finalizeContent 接收不可变执行身份与完整规范结果，只返回替换内容或 undefined，不修改其他字段；它对每个规范结果恰好执行一次，包括绕过后置策略的失败。

dsh-tools · 接口摘录，省略上下文 · tools/result · packages/core/tools/README.md

// 观察者接收内容收尾后的冻结结果，不能借此事件重新改变工具输出。
 'tools/result'

注册表先物化候选结果，再调用 finalizeContent，最后将接受结果物化为无损 JSON 并冻结，才发出 tools/result。该实时通知供观察者读取最终结果，之后循环才追加持久 tool/result；规范 value 只在执行期保留，持久记录保存内容、错误与元数据，崩溃耐久性仍取决于存储检查点。

文件与 Shell 消费各自能力服务

shell 工具将命令交给 shell 能力，提供者先执行 resolve(request)，明确工作目录、时限和执行选择，再把完整 Spec 交给 execute(spec)。省略时限、请求一个数值和请求无截止时间具有不同含义，提供者可以限制或拒绝不支持的选择。管理的 DSH_* 环境变量先清除旧值，再以当前快照覆盖；可信调用方专用的 stdin、环境和输出上限不能因模型可传任意 JSON 就自动开放。

dsh-shell · 接口摘录，省略上下文 · ctx.shell.resolve / ctx.shell.execute · packages/shell/shell/README.md

// 命令调用方先解析目录和预算，再执行完整 Spec；进程非零退出仍通过结果返回。
const spec = ctx.shell.resolve({ command: 'ls -la' })
const execution = await ctx.shell.execute(spec)
const result = await execution.result()

文件工具采用另一条明确路径：tool-fs 调用 ctx.fs，fs-local 执行访问；可选 fs-observation-policy 要求写入或编辑前已有相应观察，并拒绝过期版本。fs-sandbox 限制写入与编辑，读取直接交给后端，不应把它描述为所有文件读取的工作区读取限制。

dsh-tool-fs · 接口摘录，省略上下文 · read · packages/fs/tool-fs/README.md

// 模型以文件路径和可选行范围请求正文；tool-fs 解释参数并调用文件服务。
{"file_path":"README.md","offset":1,"limit":40}

执行结果与工作结算分别表达

shell 报告超时、取消、信号与退出码，它们并非一个布尔成功标记。输出还可能经过凭据清理和大小限制；用户看到预览不等于进程只写出了这些字节。

工具必须转发并观察取消信号，拥有进程的提供者负责终止及资源释放，调用方等待终止和资源释放完成后才能结束。对于同进程不合作代码，取消信号无法提供强制中断保证，不能把一次通知当成完成停止。

PTC 与远程执行保留独立提供者

dsh-ptc-runtime 接受程序与宿主 bindings，由提供者解析目录、时限和可用沙箱选择。运行失败放在结果 error 字段，执行前非法输入可以拒绝；停止脚本之后，已发出的宿主 binding 调用仍由调用者收尾。

dsh-ptc-runtime · 接口摘录，省略上下文 · ctx.ptcRuntime.resolve / ctx.ptcRuntime.run · packages/ptc-runtime/ptc-runtime/README.md

// 编排消费者解析程序和宿主 bindings 后运行；返回 value、logs 或 error。
const spec = ctx.ptcRuntime.resolve({
  program: 'return await tools.add({ a: 1, b: 2 })',
  bindings: [{ global: 'tools', functions: { add: async (args) => args.a + args.b } }],
})
const result = await ctx.ptcRuntime.run(spec)

SSH 相关插件则通过 dsh-ssh 连接，fs-ssh、subprocess-ssh 与 sandbox-ssh 分别提供远端文件、进程和文件限制。远端路径属于远端执行环境，不能拿字符串相同推断本机也能访问。

辅助示例

模型要求运行项目构建时，命令工具先校验参数，shell 提供者明确目录与预算，subprocess 提供者启动进程。若运行在 SSH 配置中，同一业务调用落到远端进程。超时返回的状态与编译器主动退出码不同；模型应依据实际结果解释失败，而不是仅凭最后一段输出判断构建成功。

设计取舍

工具语义与执行提供者分离，能复用模型工具而更换本地、远端或脚本运行环境；代价是调用方必须尊重提供者拥有的路径和取消语义。统一结果有利于比较失败，但不能抹去不同平台的终止能力和沙箱完整度。

工具能力：注册分派与独立执行服务 ​

tools 统一定义、策略与结果事件 ​

文件与 Shell 消费各自能力服务 ​

执行结果与工作结算分别表达 ​

PTC 与远程执行保留独立提供者 ​