深入理解 dsh 02 / 06 目录 单页全本 学习手册 对比站

深入理解 dsh/第 02 章

2.1

为什么工具必须先是一个注册表

在 pi 里,工具是四个函数的返回值——createReadOnlyToolDefinitions() 这样的东西, 静态、可枚举。在 dsh 里,工具是运行时可增删的分层集合,而且注册本身就是一个插件行为。

两者都合理,但代价完全不同。先看 dsh 要解决什么:

真实场景静态工具表做不到的地方
子 agent 有更少的工具 需要「按 scope 限制」,而不是复制一份新表
某个工具只在特定模型下可用 需要每步重新求值的准入条件,而不是加载时确定
插件热卸载 注册必须绑定到插件生命周期,卸载即撤销
部署方想禁掉某几个工具 限制必须能叠加(intersect),且不能改注册

这四条需求,正好对应 ToolsService 的四个机制:分层 / 准入 / effect 注册 / 限制。

index.ts:99-100(服务定义,inject = ['systemPrompt'])

2.2

view():遮蔽与限制是两件事

这是全章最容易读错的地方。view(scope) 返回一个 scope 能看到什么,它做了两轮处理, 语义完全不同:

packages/core/tools/src/index.ts:199-226
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 跳过、留到第二轮单独处理——否则自己就会被自己覆盖掉。

一个反直觉的推论:同一个名字的工具,可能在 A 处可见、在 B 处不可见,既不是 A 注册的也不是 B 注册的。 所以任何「工具存在吗」的判断都必须带 scope,get(name, scope) 的签名里 scope 不是可选项而是语义的一部分。

index.ts:199-226(view)· :239(get 带 scope)

2.3

注册就是一次 effect

register() 的返回值是一个 disposer,但它不是手写的清理函数——它来自 this.layers.effect(...):

packages/core/tools/src/index.ts:128-153
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 被无条件保留
注释解释得极清楚:any agent may select a code mode for itself, so a name free to take under the deployment default would become a collision the moment a preset mounted. ——今天不冲突,不代表明天不冲突,所以现在就禁。
③ effect 让注册与插件 fiber 同生共死
插件卸载 → effect 回收 → 工具消失 → tools/change 事件 → 提示词与 schema 重新计算。 一条 effect 串起了「生命周期 → 可见性 → 提示词」。

index.ts:128-153(register)

2.4

resolve():每步一份快照 + 身份栅栏

可见性是一回事,这一步实际能用哪些是另一回事。后者由 resolve() 在 preStep 里求值(第 1 章 1.5):

packages/core/tools/src/index.ts:264-303
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 + 身份栅栏)

2.5

一次工具调用的六个阶段

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:

packages/core/tools/src/pipeline.ts:147-158
// 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)

2.6

执行器也是可换的

最后一个可插拔点:「怎么执行一批工具」本身是个服务。selectExecutor 按 scope 链就近查找:

packages/core/tools/src/index.ts:357-366
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: z.never().description('Removed. Mount a native or PTC tool executor instead.')
mode:已移除。改为挂载一个 native 或 PTC 工具执行器。
— packages/core/tools/src/index.ts:101
z.never() 是一种「迁移 API」的写法:字段还在 schema 里,所以老配置文件会被读到并明确报错, 而不是被静默忽略。删字段会让用户拿到「配置没生效但不报错」这种最难查的 bug。

index.ts:357-366(selectExecutor)· :101-104(z.never 迁移)

2.7

四层过滤器,从粗到细

① 分层(register / effect)——谁能装工具
注册绑在插件 fiber 上;scoped 注册遮蔽 global;run_code 与同层重名直接抛错。
② 限制(restrict)——部署方/父级砍工具
allow / deny 在 scope 链上求交;只作用于继承来的,自己的注册豁免。
③ 准入(when + resolve)——这一步能不能用
每步重新求值;抛错包成 ToolActivationError;结果是一份冻结快照 + dispose。
④ 守卫(guard / pre-execute)——这一次调用能不能落地
单调拒绝(只说不),在 pre-execute 之后、dispatch 之前检查;外部 hook 的 deny 也从这里进。

四层各有各的粒度:装 / 砍 / 本步可用 / 本次可执行。 在 pi 里这四件事被压成一件事(函数返回数组),代价是「按 scope 变化」和「热卸载」做不到; dsh 把代价明确摊开成四层,代价是读代码必须先看 scope。

本章学习记录

记录仅保存在当前浏览器。