DeepSeek Harness tools 切面实战:管住 agent 写文件

30 阅读20分钟

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 的一次工具调用是固定流水线。所谓“切面”,就是不改工具本身,只在流水线的三个固定位置插入横切逻辑:

tool-aop.png

图:三个切面的位置;虚线 = 错误结果也会走完后段。

文字版:pre → guards → execute → body → post → finalize → freeze → result。

pre 的拒绝会被物化成 error result,仍然进入 post;post 的 block 也会进入 result。后段监听器必须自己判断 result.isError 来跳过。所以 result 既能看到成功,也能看到被前两段拒绝/打回的失败——这正是账本能成立的原因。

二、三个钩子的权力边界

三个钩子的差别,核心不在“能做什么”,而在“不能做什么”。三条“不能”决定了它们各自只能解决哪类问题:

钩子派发方式能做的决策不能做的事能决定什么
tools/pre-executewaterfallallow / deny / cancel / ask改不了参数(exec.arguments 深度冻结)决定“要不要执行”
tools/post-executewaterfallaccept / block回滚不了磁盘(副作用已发生)决定“执行完给模型看什么”
tools/resultemit无改不了结果(已 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-executedeny.reason路径指引单:原因 + 现状 + 分类菜单 + 下一步
post-executeblock.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,所以“自动纠偏”只能由插件自己做四步:

  1. 拦截原调用;
  2. 按规范路径代写;
  3. 拒绝原调用;
  4. 在 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 / 只有 warningaccept + content提醒文本,不阻断
有新增 error,预算内block + feedback违规清单 + 目标模板 + 剩余次数
超预算,on_exhausted=allowaccept + content明确写“已放行但未通过”
超预算,on_exhausted=blockblock + 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本次新增的违规,不含历史遗留。