DeepSeek Harness tools 切面实战:管住 agent 写文件
一句话摘要:三个切面钩子分别位于执行前、执行后、结果冻结后——
pre无副作用地准入/拒绝,post在落盘后决定模型看到什么,result只读审计。dsh-file-enhance用前两个实现按需校验,替代常驻 system prompt 规范。每个位置能做什么,由挂上去的监听器决定。本文视角:主角是 tools 切面,
dsh-file-enhance只是它的一个应用。先有切面,后有插件——第一部分不依赖任何具体插件,第二部分才把切面落到dsh-file-enhance。它只挂了前两个钩子,第三个只做观测、不负责规范。
读前提示:术语不熟没关系,文末有一张 8 条速查表。
全文地图:第一部分讲切面本身 → 第二部分落到 dsh-file-enhance → FAQ 与小结收束。
把镜头拉远:任何一次工具调用,都可以在三个位置插入横切逻辑——执行前、执行后、结果冻结后。这就是 tools 切面。
写文件只是其中一个场景。agent 写文件时有两处“随意”:写在哪、写成什么。项目规范通常写进 system prompt,但它常驻占 token、长文里会被衰减、而且没法机械验证。更糟的是,模型出错时不知道自己错在哪。
工具切面提供了另一种可能:把规范拆成一张张检查单,挂在工具执行的前后;只有触发时才进入上下文。
本文先讲清楚 tools 切面本身是什么、三个钩子各自能做什么;再把切面落到一个具体应用 dsh-file-enhance 上;最后用 FAQ 和小结收束。
案例部分的代码摘自 dsh-file-enhance 当前实现,文件路径为示意;只保留说明切面所需的部分。
第一部分:tools 切面本身
一、一次工具调用的流水线
宿主 @deepseek-ai/dsh-tools 的一次工具调用是固定流水线。所谓“切面”,就是不改工具本身,只在流水线的三个固定位置插入横切逻辑:
图:三个切面的位置;虚线 = 错误结果也会走完后段。
文字版:pre → guards → execute → body → post → finalize → freeze → result。
pre 的拒绝会被物化成 error result,仍然进入 post;post 的 block 也会进入 result。后段监听器必须自己判断 result.isError 来跳过。所以 result 既能看到成功,也能看到被前两段拒绝/打回的失败——这正是账本能成立的原因。
二、三个钩子的权力边界
三个钩子的差别,核心不在“能做什么”,而在“不能做什么”。三条“不能”决定了它们各自只能解决哪类问题:
| 钩子 | 派发方式 | 能做的决策 | 不能做的事 | 能决定什么 |
|---|---|---|---|---|
tools/pre-execute | waterfall | allow / deny / cancel / ask | 改不了参数(exec.arguments 深度冻结) | 决定“要不要执行” |
tools/post-execute | waterfall | accept / block | 回滚不了磁盘(副作用已发生) | 决定“执行完给模型看什么” |
tools/result | emit | 无 | 改不了结果(已 deepFreeze,返回值被忽略) | 决定“你最后知道什么” |
三条“不能”展开说:
pre-execute改不了参数。 决策只有四档,没有“改完继续执行”。路径不对时,只有两条路:打回让 agent 重试,或者插件自己按规范代写——不能悄悄把file_path换掉。post-execute回滚不了磁盘。 它发生在落盘之后,能改的是“模型看到的结果”,不是磁盘。tools/result改不了结果。 它是结果冻结后的广播:emit不是waterfall(见上方表注),返回值被忽略;同步派发,异步不等待;监听器抛错只记一条logger.warn。它能知道最终成没成,但不能改变最终成没成。
失败路径:三种钩子分别会发生什么
| 路径 | 工具执行 | 磁盘 | 模型看到 | 最终结果 |
|---|---|---|---|---|
pre deny | 不执行 | 不变 | Error: <reason> | isError;换参数重试 |
post block | 已执行 | 已写入 | block 反馈(违规清单 / 模板) | isError;改同一文件重试 |
result 只读 | 已执行 | 已写入 | 原结果,不受影响 | 结果不变;观察者只能记录 / 告警 |
记住一点:pre 的拒绝没有副作用,post 的 block 有副作用,result 连副作用都改不了。
这就是三个钩子的通用图景。接下来把切面落到一个具体应用上——落到 dsh-file-enhance 上:执行前的位置管落点,执行后的位置管形状;第三个位置它没有用。注意,它是应用,不是定义。
第二部分:一个应用——把切面落到 dsh-file-enhance
三、案例背景:为什么需要一个扩展
假设 agent 要写一份需求文档。它可能:
- 把文件写到
docs/需求-登录改造.md——但项目规范要求落在docs/projects/<项目编号>/requirement/; - 位置对了,但内容缺
owner、缺章节、status值不在允许值域里; - 改完之后,你还不确定这次写到底算不算成功。
前两个问题对应“落点”和“形状”——执行前和执行后两个位置;第三个问题(账本)这个插件没有解,留给 tools/result 的观测场景。
最直觉的解法是在 system prompt 里写一段规范。但它有四个问题:
- 常驻成本:每一轮都要付 token,哪怕这次不写文档;
- 长文衰减:文档越长,模型对开头约束的注意力越弱;
- 不可机械验证:写了“必须包含验收标准”,但没人检查;
- 出错时没有定位:模型不知道自己错在哪、该改成什么样。
粗略算一笔账(假设 10 轮里共 30 次模型请求;未计 prompt caching 折扣,只为量级,非 benchmark):
| 方案 | 注入时机 | 量级示意(非 benchmark) | 注意力位置 |
|---|---|---|---|
| system prompt 常驻(300 tokens) | 每次请求 | 300 × 30 ≈ 9,000 tokens | 上下文开头,和所有内容竞争 |
| 钩子按需注入(400 tokens/次) | 只在违规时 | 2 次 × 400 ≈ 800 tokens | 紧贴失败的工具结果 |
| 合规时 | 不注入 | 0 | — |
不同模型、缓存和任务长度都会改变数字,这里只看量级。但“每轮都付”与“只在违规时付”的差距是结构性的。
dsh-file-enhance 的选择是:零个自有工具,只挂 pre-execute 和 post-execute 两个监听器。 模型的工具面一个都没多,但每一次 write 都要先过路径关,落盘后再过内容关。
// src/index.ts(示意)
export const name = 'dsh-file-enhance'
export const inject = ['tools']
规范提示词从哪两个口子进对话:
| 钩子 | 载体 | 文本内容 |
|---|---|---|
pre-execute | deny.reason | 路径指引单:原因 + 现状 + 分类菜单 + 下一步 |
post-execute | block.feedback | 内容指引单:违规清单 + 目标模板 + 参考 + 剩余次数 |
案例里的三个位置各自擅长什么
把权力边界翻译成用途:
| 钩子 | 擅长 | 典型用法 |
|---|---|---|
pre-execute | 准入控制 | 路径判定、权限门控、要求审批、格式预检 |
post-execute | 结果整形 | 内容校验、结果脱敏、格式规范化、把成功标成失败 |
tools/result | 事后观测 | 审计日志、指标采集、两阶段提交、兜底清理 |
一个关键区分:前两个钩子是“决策点”,能改变模型看到什么;第三个是“观测点”,只能记录发生了什么。 规范类需求只能用前两个钩子实现,第三个钩子保证你知道最终管没管住。
在这个案例里,前两个位置被用上了;第三个位置擅长观测,但没有挂监听器。
下面只看这个应用怎么做。它不是切面的定义,只是一个把切面用完整的案例;读的时候可以对照第一部分。重点看设计决策和取舍,代码只保留说明问题的片段。
四、执行前的位置:解决“写在哪”
4.1 只拦“新建 write”
路径关的边界刻意窄:
// src/folder-path/intercept.ts(示意)
const WRITE_TOOLS = new Set(['write'])
const listener = async (
exec: ToolExecution,
next: () => Promise<PreToolDecision>,
) => {
if (!WRITE_TOOLS.has(exec.name)) return next()
const rawPath = exec.arguments?.file_path
if (typeof rawPath !== 'string' || rawPath === '') return next()
const target = toAbs(await deps.resolveRoot(exec), rawPath)
if (exists(target)) return next() // 改旧文件不归路径关管
...
}
三个过滤条件各有理由:不拦 edit / bash / read,因为路径关只管“文件建在哪”;没有 file_path 直接放行;目标已存在就放行——修改已有文件不是“放哪”的问题,位置早就定了。
MVP 只认 write。宁可先做一件小事做对,也不要一次吃掉所有写工具。
4.2 规则是项目数据,不是插件代码
路径规范放在工作区 .dsh/folder-path-rules/md.yaml,声明根目录、分类、目标模板、命名规则、集合型实例的编号格式。插件按 mtime 热重载:改 YAML 即生效,不用发版、不用重启。
为什么必须是项目数据?三个理由:规范的所有权属于项目;不同项目的目录习惯不同;改一条规则的成本,决定项目愿不愿意维护它。
工作区没有规则文件时,插件回落内置默认参与判定,并把默认规则落盘成可改的文件——装完第一单就生效,同时给项目一个修改起点。
4.3 五步判定链与“自由发挥”
decide.ts 是一个纯函数,按冻结顺序走五步:类型过滤 → 根目录检查 → 根之外 → 未分类(直接落在 root)→ 已进子目录。
其中最重要的一条缝是**“自由发挥”**:同一个 agent、同一个目标路径,第二次尝试即放行。根目录禁令是唯一例外。
为什么留这条缝?因为规范不可能穷尽现实。一个新项目、一种新文档,规则里没有分类;如果永远硬拦,插件会被卸载。首次拦截只做教导,第二次放手——既给规范一次机会,也承认了规范的边界。
4.4 指引单:把规范变成“人话投影”
判定链只返回数据(pass / deny / correct),把它变成宿主的 PreToolDecision 是另一层的事。关键是拒绝时返回什么:
if (verdict.kind === 'deny') {
return { kind: 'deny', reason: renderGuidance(verdict) }
}
renderGuidance 生成一张结构固定的回执:
⛔ 文件未创建:docs/需求-登录改造.md
【拦截原因】集合型分类需要先拿到实例编号,再放文件
【docs/ 现状】现有目录结构 + 文件数 + 样例
【可用分类】每个分类 → 目标模板|关键词
【下一步】1) 按分类重试 2) 问用户 3) 自由发挥
每一段回答一个问题:
| 段 | 回答的问题 | 设计要点 |
|---|---|---|
| 拦截原因 | 我错在哪? | 一句人话,不堆规则术语 |
| 现状 | 项目现在长什么样? | 让 agent 自己推断,而不是只给菜单 |
| 可用分类 | 合法落点有哪些? | 规则的“人话投影” |
| 下一步 | 我现在该做什么? | 给可执行命令,不给抽象建议 |
这张回执不是拒绝,是教学。 它不要求模型记住规范,只要求它在被拦下的这一刻读一张检查单。
4.5 自动纠偏:不能改参数,那就自己写
pre 改不了 file_path,所以“自动纠偏”只能由插件自己做四步:
- 拦截原调用;
- 按规范路径代写;
- 拒绝原调用;
- 在 reason 里告知实际落点。
这条路径有三个必须自己兜住的坑:
- 不能覆盖已有文件:原目标不存在,不代表纠偏目标也不存在。代写前先
exists。 - 代写前必须校验内容:原调用被拒后,
post只会收到 error,内容关不会跑;代写又不产生新工具事件,所以必须自己先校验。 - 仍然返回
deny:文件写好了,但这次调用在模型侧必须是失败——只有这样,模型才会读到“已归位”的回执。
五、执行后的位置:解决“写成什么”
5.1 为什么必须在落盘后
内容规范有一个硬约束:必须看到最终全文。
edit的最终内容只有执行完才知道;pre阶段只有入参里的content,edit根本没有完整正文;post的结果里自带after(落盘后全文)与before(落盘前全文),不用重新读盘。
所以内容关只能挂 post。代价必须显式接受:不合规的文件已经写在磁盘上了。
5.2 入口过滤与 delta 设计
入口要做几层过滤,各有理由:
// src/content-format/post-check.ts(示意)
// listener: (exec, result, next) => Promise<PostToolDecision>
if (!FORMAT_TOOLS.has(exec.name)) return next()
if (result.isError) return next() // pre 的拒绝也会进 post,必须挡住
if (typeof value?.after !== 'string') return next()
if (relative(workspaceRoot, abs).startsWith('..')) return next()
const spec = store.match(...)
if (spec === undefined) return next() // 未登记类型不受约束
校验本身是纯函数:parse → facts → derive → rules → delta。其中 delta 是最重要的设计:违规 key 由 rule.id + 失败标识 组成,不含行号——否则改一行就会重新报一次。只有本次新增的违规才进入 newErrors。历史遗留问题不算到本次编辑头上。
// key 不含行号:改一行不会重复报
const key = rule.id + ':' + (failure.key ?? failure.code)
if (!previousKeys.has(key)) newErrors.push(...)
正例:key 是 sections:背景。把这一节从第 10 行挪到第 30 行,key 不变,delta 认为还是同一条违规。
反例:key 写成 sections:背景:10。同一节挪到第 30 行后 key 变成 sections:背景:30,delta 就会把它当成新增违规再报一次。
5.3 三态策略与计数器
校验报告交给统一的策略层:
| 情况 | 决策 | 模型看到什么 |
|---|---|---|
| 未命中 spec / 无新增违规 | next() | 零返回 |
mode=warn / 只有 warning | accept + content | 提醒文本,不阻断 |
| 有新增 error,预算内 | block + feedback | 违规清单 + 目标模板 + 剩余次数 |
超预算,on_exhausted=allow | accept + content | 明确写“已放行但未通过” |
超预算,on_exhausted=block | block + feedback | 继续保持错误 |
一个细节:路径关和内容关各有一个计数器,不能共用。 路径的第二次放行是故意留的宽容,内容的预算是质量约束。共用会让“路径试错两次”白白吃掉“内容整改机会”。TTL 也不同:内容整改要读模板、补章节,慢得多。
// 示意:两个预算分开配置,互不侵蚀
const budget = {
path: { max: 2, ttl: '10m' },
content: { max: 3, ttl: '30m' },
}
5.4 内容指引单与 block 不是回滚
内容指引单的渲染优先级:模板全文 → 规则反推的骨架 → 只给违规清单。example.md 只给路径不内联全文——示例是参考不是目标,内联会抢走模板的位置,也让打回文本过长。
这里必须强调全文最重要的一句:
post-execute的block只改变工具结果,不改变磁盘。
文件在 block 之前就已经写完了。模型看到错误,去改同一个文件;下一次写入再校验。插件从头到尾没有“撤销”动作,也不打算有。
为什么接受这个取舍?文件已经写对一半,回滚会让 agent 丢失进度;edit 回滚意味着要恢复旧全文,成本和风险更高;真正要防的是“不合规内容被当成最终交付”,而 block 已经把这次调用标成失败。
案例讲完,先看什么时候不该挂钩子,再看一些高频问题;最后用一页小结收回切面。
什么时候不该挂钩子
| 场景 | 为什么不建议挂 | 替代方案 |
|---|---|---|
| 一次性初始化 | 不值得常驻监听器。 | 直接在初始化脚本或生成器里做一次。 |
| 需要改参数 | 钩子改不了 exec.arguments。 | 拒绝并让调用方重试,或由插件代写。 |
| 需要强事务回滚 | post 不回滚磁盘。 | 两阶段提交或外部事务。 |
| 只是记录日志 | 放 pre / post 会增加决策链复杂度。 | 放 result 做观测。 |
FAQ
Q:为什么内容校验不放 pre-execute?
因为 pre 拿不到最终全文(edit 没有完整正文),而且插件不能改参数。放 pre 只会退化成“写一次、拒一次、再写一次”的双倍往返。
Q:所有写文件动作都会被拦截吗?
不会。当前插件只对 write 工具新建文件做路径校验;bash、原生 edit、其他自定义工具如果写文件,不会自动经过这套路径校验(edit 仍会过内容校验,但不过路径校验)。要全覆盖,需要额外对这些工具挂同一份 pre 监听器,并定义各自的 file_path 提取方式。
Q:自动纠偏会不会覆盖已有文件?
不会主动覆盖。代写前先检查 verdict.to 是否存在;存在就取消纠偏并返回 deny。回退到 node:fs 时还用 wx 标志兜底;极端竞态下由宿主的 fs 策略决定。代价是这种情况 agent 仍需自己选路径。
Q:agent 反复写不对,会不会死循环?
默认不会无限重试。内容关有 max_attempts(默认 3);超预算后按 on_exhausted 处理:默认 allow 放行并附警告,设为 block 则继续拦截。路径关也有“第二次放行”的自由发挥缝。若显式设成 block,就是选择继续拦,需要自己承担反复重试的成本。
Q:多个 pre / post 监听器共存时,顺序怎么定?会不会一个 deny、另一个又放行?
pre / post 都是 waterfall,按注册顺序执行。谁先返回决策且不调 next(),谁就结束这条链,后面的监听器不会执行。
⚠️ 高危点:waterfall 不保证“拒绝单调”。 上游监听器调了
next()后,仍可以忽略下游的deny并返回allow;多插件同时挂pre/post时,这里最容易出冲突。
要绝对不可放行,用单调 guard(ctx.tools.guard):它在 pre 之后执行且只能拒绝。result 是 emit,所有监听器都会收到,不存在“谁否决谁”。
Q:同一个文件命中多条内容规则时,回执是聚合还是只报第一条?会超长吗?
一次报全:validateDocument 汇总所有 newErrors / newWarnings,report.ts 逐条渲染 checkId、message 和行号。当前没有硬性截断;规则和违规很多时回执会很长,这是“一次报全”的代价。max_attempts 只限制重试次数,不限制回执长度。
Q:计数器 / TTL 存在哪?agent 重启或会话断开后会丢吗?
在内存里,不落盘:路径放行记忆是 Map<key, { count, at }>,内容尝试计数是 AttemptStore 的 Map。TTL 只负责过期清理,不做持久化。插件重载或进程重启后状态丢失;会话断开是否丢取决于宿主是否销毁插件实例,不能把它当跨会话配额。
Q:多个 agent 会互相串吗?
不会。路径拦截记忆的 key 包含 agent.id;result 也按 exec.agent 做 scope 过滤。
Q:项目没有 spec 怎么办?
不校验、静默放行。插件只拦“登记过的类型”;没有规则就没有判据,不能凭空误伤。
小结
把视角拉回切面:位置是固定的——执行前、执行后、结果冻结后;每个位置挂什么监听器、做几件事,由插件决定。
落到 dsh-file-enhance 上,就是两件事:
- 执行前 → 落点:合规放行,不合规打回或纠偏;不能改参数,所以要么让 agent 重试,要么插件代写。
- 执行后 → 形状:落盘后校验,违规就
block,把清单、模板、参考和剩余次数一起递回去。
第三个位置(结果冻结后)它没有挂监听器;tools/result 只在第一部分的切面图景里出现,用来做观测,不参与这个案例。
三条原则:规范在违规那一刻注入;打回要教学;先落盘再打回是显式取舍。
三条边界:计数器与放行记忆只在内存;路径关只拦新建 write;block 不回滚磁盘。
实现提醒:pre / post 按注册顺序执行,上游可覆盖下游的 deny,要绝对不可放行就用单调 guard。
dsh-file-enhance 的全部秘密,其实只有一句:
规范不是一段永远在场的提示词,而是一次恰到好处的打断。
它不新增工具,不替 agent 写内容;只在 agent 要写文件的那一刻,把项目自己的形状递到它手里——写对了就消失,写错了才出现。
而这句话不只属于这个案例。回到切面本身:执行前、执行后、结果冻结后,三个位置向所有监听器开放——任何人都可以在自己的工具流水线上,挂上这三个位置。
参考链接:DSH tools、Cordis、js-yaml、dsh-file-enhance。
术语表
按文章里出现的顺序:
| 术语 | 一句话解释 |
|---|---|
waterfall | 监听器用 next() 串成一条链,返回值就是本次决策;不调 next() 就短路——后面的监听器不再执行。 |
emit | 广播,没有 next,返回值被忽略;只能做事,不能改变结果。 |
pre-execute | 执行前的切面:只能 allow / deny / cancel / ask;不能改参数。 |
post-execute | 执行后的切面:accept / block;能改结果,不能回滚磁盘。 |
tools/result | 结果冻结后的切面:只读广播,返回值被忽略。 |
deepFreeze | 结果已冻结,监听器改不了。 |
materialize | 把决策物化成最终结果对象。 |
delta | 本次新增的违规,不含历史遗留。 |