Agent 框架源码
第 6 节:工具只负责干活,规矩挂在七道关上
工具执行插了七道关卡,三个 waterfall 都能改调用。pre-execute 能拒能问,guard 单调不可翻案,post-execute 只动结果。同一份 bash 于是能在开发机放行、生产审批、多租户沙箱,而不用维护三份工具。
- 流水线关卡
- 七道tool/call → pre-execute → guard → execute → 工具体 → post-execute → result
- 可改调用的 waterfall
- 三个pre-execute、execute、post-execute,权限等级不同
- 单调守卫
- guard一旦 deny,后续监听器无法撤销
七道关:任何一道都能改调用,工具本身不知道
工具执行是 dsh 里最值得抄的一段设计。它把「工具干什么」和「允许它干什么」彻底分开,中间插了七道关卡,每一道都能改调用或改结果,而工具代码只有一份:
模型吐出 tool-call
│
① tool/call 先落盘,再执行 —— 日志在动作之前
│
② tools/pre-execute waterfall 钩子 / 权限 / 沙箱判定
│ ├ deny ────────────────→ 跳过工具体,结果标失败
│ └ ask → ctx.approval 一次性询问(无人应答按拒绝)
│
③ guard 单调守卫 deny 或弃权;后续监听器无法翻案
│
④ tools/execute waterfall 环绕分发:超时 / 重试 / 指标
│
⑤ 工具 execute() 本体
│
⑥ projectContent → tools/post-execute waterfall
│ 接受 / 阻断 / 替换 / 追加上下文
│
⑦ finalizeContent → tools/result 同步通知
结果已冻结,只许看,不许改
↓
tool/result 落盘,模型看到唯一结果
三个 waterfall(②④⑥)都能改调用,区别在权限等级:pre-execute 能拒能问能改参数,guard 是单调的——一旦 deny,谁也别想翻案,这是最后一道硬闸;post-execute 只能动已经产生的结果。
为什么要把「能拒」和「只能改结果」分开?因为授权级别不同。pre-execute 的监听器来自插件,属于可扩展策略;guard 是部署方注册的最终约束,插件不得覆盖。两者混成一个钩子,就会出现「某个插件把自己的审批逻辑排到安全策略前面」这种事故。
同一份工具,三套规矩:这才是拆七道关的理由
如果只有一个部署环境,七道关确实过度设计。真实价值在多环境:
| 环境 | rm -rf 怎么处理 |
策略挂在哪 |
|---|---|---|
| 开发机 | 直接放行 | 不挂监听器,默认 allow |
| 生产 | 弹一次性审批,无人应答按拒绝 | tools/pre-execute 返回 ask + ctx.approval |
| 多租户 | 硬件层面拦住:沙箱后端在 spawn 前包装 argv | ctx.sandbox 提供方 + 单调 guard |
这是「策略不写进工具」的全部理由。工具只管干活,规矩挂在事件上。于是不需要维护三份 bash,也不会出现「开发版和生产版行为不一致」这种经典事故。
代价在前面第 1 节提过:打开 tool-bash 源码看不到它在生产会被拦,得翻 patch、审批策略、sandbox 提供方三处。dsh 用事件命名带域(tools/*)来缓解,但「读整棵树」的能力仍然必需。
失败要变成模型能读的结果,不是异常堆栈
工具里抛异常是允许的,注册表会捕获成带 isError 的结果交给模型。但「捕获成错误」和「模型知道怎么修正」是两件事。
// 真实实现:packages/core/tools/src/index.ts
guard(guard: ToolGuard): () => void {
return this.guards.effect(this.ctx, layer => layer.guards.append(guard), { label: 'tools.guard()' })
}
checkGuards(exec: ToolExecution): string | undefined {
for (const layer of [this.guards.global, ...this.guards.chainLayers(exec.agent)]) {
for (const guard of layer.guards.values()) {
const reason = guard(exec)
if (reason !== undefined) return reason // 第一个拒绝理由即终止
}
}
return undefined
}
注意 checkGuards 的返回类型是 string | undefined——返回的是给人看的拒绝理由,不是布尔值。这条细节决定了模型能不能自我修正:一句 denied 它只能换个参数瞎试,一句 写入目标在只读挂载点 /mnt/ro 上 它就知道该换路径。
另外两个约定值得抄:注册时校验定义(output 必须带 render、schema 必须受支持、保留名不许占用),失败要收敛而不是炸穿(schema 校验失败、渲染器抛错、JSON 不可无损表示,全部收敛成 isError,在观察者运行前完成)。
这条「失败收敛」在 dsh 里到处出现:UI 展示器对格式错误的旧日志返回通用卡片而不抛异常,理由是「展示绝不能导致回放崩溃」。同一个原则,不同落点。
下一节往上走一层:工具能访问的文件系统、进程、沙箱,为什么换一个提供方就会整组搬家。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 按 tool-execution-pipeline 与 pipeline.ts 实现画七道关 | 全页 |