深入理解 dsh/第 02 章
为什么工具必须先是一个注册表
在 pi 里,工具是四个函数的返回值——createReadOnlyToolDefinitions() 这样的东西,
静态、可枚举。在 dsh 里,工具是运行时可增删的分层集合,而且注册本身就是一个插件行为。
两者都合理,但代价完全不同。先看 dsh 要解决什么:
| 真实场景 | 静态工具表做不到的地方 |
|---|---|
| 子 agent 有更少的工具 | 需要「按 scope 限制」,而不是复制一份新表 |
| 某个工具只在特定模型下可用 | 需要每步重新求值的准入条件,而不是加载时确定 |
| 插件热卸载 | 注册必须绑定到插件生命周期,卸载即撤销 |
| 部署方想禁掉某几个工具 | 限制必须能叠加(intersect),且不能改注册 |
这四条需求,正好对应 ToolsService 的四个机制:分层 / 准入 / effect 注册 / 限制。
index.ts:99-100(服务定义,inject = ['systemPrompt'])
view():遮蔽与限制是两件事
这是全章最容易读错的地方。view(scope) 返回一个 scope 能看到什么,它做了两轮处理,
语义完全不同:
private view(scope?: ScopeKey): ToolView { const layers = this.layers.chainLayers(scope) const own = this.layers.peek(scope) const inherited = new Map(this.layers.global.tools.entries()) for (const layer of layers) { if (layer === own) continue for (const [name, registration] of layer.tools.entries()) inherited.set(name, registration) } // 第一轮:继承来的(global + 祖先 scope),要过限制检查 for (const [name, registration] of inherited) { if (layers.every(layer => layer.admits(name))) { visible.set(name, registration.definition) } } // 第二轮:自己 scope 注册的,无条件可见 if (own !== undefined) { for (const [name, registration] of own.tools.entries()) { visible.set(name, registration.definition) } } }
| 轮次 | 成员 | 受限吗 | 为什么 |
|---|---|---|---|
| 继承 | global + 所有祖先 scope | 受:layers.every(admits) |
限制是「部署方/父级对下级的约束」 |
| 自身 | 本 scope 注册的 | 不受 | 你给自己装的东西,不该被别人的过滤器删掉 |
遮蔽(shadowing)发生在第一轮的 inherited.set 上:近的覆盖远的(global 打底,祖先 scope 依次覆盖)。
而 own 被 continue 跳过、留到第二轮单独处理——否则自己就会被自己覆盖掉。
get(name, scope) 的签名里 scope 不是可选项而是语义的一部分。
index.ts:199-226(view)· :239(get 带 scope)
注册就是一次 effect
register() 的返回值是一个 disposer,但它不是手写的清理函数——它来自 this.layers.effect(...):
register(definition: ToolDefinition, options: ToolRegistrationOptions = {}): () => void {
const name = definition.name
const output = (definition as Partial<ToolDefinition>).output
if (output === undefined || typeof output !== 'object'
|| typeof output.render !== 'function') {
throw new TypeError(`tool "${name}" must declare output { schema, render, presentationMeta? }`)
}
assertSupportedJsonSchema(output.schema)
if (name === RUN_CODE_NAME) {
throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the PTC mode presentation transport…`)
}
return this.layers.effect(
this.ctx,
layer => layer.tools.insert(name, { definition, when: options.when }),
{ label: 'tools.register()' },
)
}
三个设计点:
{ schema, render, presentationMeta? }render),不只是能执行。assertSupportedJsonSchema 还会拒绝「JSON Schema 里我们不支持的写法」——
因为 schema 要发给模型,而不同 provider 支持度不一。
run_code 被无条件保留effect 让注册与插件 fiber 同生共死tools/change 事件 → 提示词与 schema 重新计算。
一条 effect 串起了「生命周期 → 可见性 → 提示词」。
index.ts:128-153(register)
resolve():每步一份快照 + 身份栅栏
可见性是一回事,这一步实际能用哪些是另一回事。后者由 resolve() 在 preStep 里求值(第 1 章 1.5):
async resolve(context: ToolActivationContext): Promise<ResolvedToolSet> { const { agent, signal } = context signal.throwIfAborted() const view = this.view(agent) const admitted = new Map<string, ToolDefinition>() for (const [name, definition] of view.visible) { const registration = view.registrations.get(name) let enabled: boolean try { enabled = registration?.when === undefined || await registration.when(context) // 条件注册 } catch (cause: unknown) { signal.throwIfAborted() throw new ToolActivationError(name, cause) } if (enabled) admitted.set(name, definition) } let closed = false return Object.freeze({ dispose: () => { closed = true }, view: (scope) => { const visible = new Map() if (closed || scope !== agent) return visible const current = this.view(agent) for (const [name, definition] of admitted) { if (current.visible.get(name) === definition // 定义未换 && current.registrations.get(name) === view.registrations.get(name)) { // 注册未换 visible.set(name, definition) } } return visible }, }) }
这段里藏了两个非常精确的决定:
| 机制 | 代码 | 防的是什么 |
|---|---|---|
when 抛错 → 包装 |
throw new ToolActivationError(name, cause) |
条件函数写错时,报错要能指向哪个工具,而不是一个光秃秃的 undefined 错误 |
| 双重身份比较 | visible.get(name) === definition 且 registrations.get(name) === 快照时的 |
同名工具被换成了另一个对象(插件重装、热更新)时,旧快照必须失效 |
closed 闸门 |
if (closed || scope !== agent) return empty |
已 dispose 的快照不允许再被查询 |
definition 会漏掉「definition 对象复用了、但 registration 换了」的情形
(比如注册方偷偷换了 when 条件)。只比 registration 会漏掉「registration 没变、definition 被原地替换」。
两个都比,才叫「身份未变」。
index.ts:264-303(resolve + 身份栅栏)
一次工具调用的六个阶段
pipeline.ts 有 771 行,但它做的是一条固定流水线。压成六个阶段:
| 阶段 | 做什么 | 失败时 | 关键点 |
|---|---|---|---|
| ① prepare | 快照参数、冻结、分配关联 token | 参数不可 JSON 化 → 立即 final-result |
不可序列化的参数根本不进流水线 |
| ② pre-execute | tools/pre-execute waterfall:策略 + 守卫 + 审批 |
拒绝 → final-result,不执行 |
这里是外部 hook 的 deny 落地处(第 5 章) |
| ③ execute | tool.execute(args, exec) |
抛错 → toolErrorResult,变成模型可见的输入 |
错误不是异常,是数据 |
| ④ post-execute | tools/execute 事件,可要求再跑一轮 |
— | 允许「结果出来了但我还想改」 |
| ⑤ finalize | finalizeContent:定义自己收尾 |
— | 截断、附路径、加提示都在这 |
| ⑥ materialize | 无损、冻结、发布给观察者 | — | Object.freeze 后的同一份给所有人 |
其中「先抓回调、再读参数」这一步单独值一提——因为参数可能带 getter:
// Capture callbacks before argument getters run; rejected calls retain finalization only when aborted. const capturedFinalizer = visible?.finalizeContent?.bind(visible) const capturedProjector = visible?.projectContent?.bind(visible) const finalizerFor = (): ToolDefinition['finalizeContent'] | undefined => rejected && !signal.aborted ? undefined : capturedFinalizer try { const detached = snapshotJsonValue(exec.arguments) if (detached === undefined) { throw new TypeError('tool execution arguments must be losslessly JSON-serializable') } const execution: MutableToolRunContext = { ...base, arguments: deepFreeze(detached) }
rejected && !signal.aborted ? undefined : capturedFinalizer 这一行值得慢慢读:
| 情形 | 保留 finalizer | 为什么 |
|---|---|---|
| 被策略拒绝,且未中断 | 不保留 | 压根没执行,没有产出可收尾 |
| 被策略拒绝,但已中断 | 保留 | 中断前可能已有部分输出,仍要按工具自己的方式收尾 |
| 正常进入执行 | 保留 | — |
pipeline.ts:147-158(prepare 快照)· :190-230(pre-execute)
执行器也是可换的
最后一个可插拔点:「怎么执行一批工具」本身是个服务。selectExecutor 按 scope 链就近查找:
private selectExecutor(scope?: ScopeKey): ToolExecutor { let record: Registration | undefined for (const key of scopeChainOf(scope)) { record = this.scoped.get(key) if (record !== undefined) break } record ??= this.root const executor = record?.executor if (executor === undefined) throw new ToolExecutorUnavailableError() return executor }
这就是为什么 ToolsService.Config 里那两个字段被写成 z.never()——
mode 和 maxParallelSubCalls 被移除了,改成「装一个 executor 插件」:
mode:已移除。改为挂载一个 native 或 PTC 工具执行器。z.never() 是一种「迁移 API」的写法:字段还在 schema 里,所以老配置文件会被读到并明确报错,
而不是被静默忽略。删字段会让用户拿到「配置没生效但不报错」这种最难查的 bug。
index.ts:357-366(selectExecutor)· :101-104(z.never 迁移)
四层过滤器,从粗到细
run_code 与同层重名直接抛错。allow / deny 在 scope 链上求交;只作用于继承来的,自己的注册豁免。ToolActivationError;结果是一份冻结快照 + dispose。deny 也从这里进。四层各有各的粒度:装 / 砍 / 本步可用 / 本次可执行。 在 pi 里这四件事被压成一件事(函数返回数组),代价是「按 scope 变化」和「热卸载」做不到; dsh 把代价明确摊开成四层,代价是读代码必须先看 scope。