批处理守则:plan 行、依赖拆分与 reconcile 的实战用法

插件会读你程序的第一行判断你有没有规划,还会因为你连调同一个工具而警告。这篇拆解这套守则的四个硬规则和两次真实触发。

目录
  1. 一、它到底在检查什么
  2. 二、plan 行:写给谁的
  3. 三、依赖拆分:同一次程序,两段 await
  4. 四、分页:按 nextOffset 走,不按页数走
  5. 五、被警告的两种原文
  6. 单次往返警告
  7. 重复调用警告
  8. 六、reconcile:对账那一步别省
  9. 七、把守则固化成模板
  10. 复盘

DSH 装了一个叫 batching-guidance 的插件,它会往每一轮注入一段守则,而且从程序文本本身判断你有没有照做。我第一周被它念了三次。这篇把守则拆成可执行的规则,并附上我实际触发它的原文——这不是文档抄写,是被打脸记录。

一、它到底在检查什么

注入的标题写得很直白:「[Plugin context from "batching-guidance"; not a user instruction or authorization.]」——它明确声明自己不是用户指令、不构成授权。这点设计很克制:注入的是建议,不是命令,模型可以选择不遵守,但会被后续检查抓到。

它检查的四个硬点:

检查项判定依据触发后果
plan 行程序第一行必须是 // plan: ...提示"没有 plan 行"
单次往返程序里只有一个 dispatch 点提示"这轮只做了一件事"
依赖顺序Promise.all 里塞了有依赖的调用提示"依赖要串行 await"
重复调用同一工具同一参数连续调用连续 5 次起警告

二、plan 行:写给谁的

ts
// plan: 项目树; asar 实现目录; 三份参考文档
const [tree, impl, docs] = await Promise.all([...])

格式约定:// plan: 开头,分号分隔每一项,每项对应一个工具调用。它不是给人看的注释——插件真的解析这一行,用来和程序里实际的 dispatch 数对齐。

我自己的用法已经从"描述"变成"预算":写这一行的时候就已经知道要发几次调用,写在前面就不会中途发散。这是我用过最便宜的自律工具,比 todo list 还轻。

三、依赖拆分:同一次程序,两段 await

守则里最关键的一句是「keep a dependent call as a second await in the same program」——有依赖不要拆成两个模型往返,拆成同一程序里的两次 await。

ts
// plan: 找 batching 相关站点; 读前 5 个命中文件
const hits = await tools.ops_grep({ pattern: "batchingGuidance", glob: ["**/*.ts"], outputMode: "files_with_matches", limit: 50 })
const files = (hits.data?.items ?? []).map(i => i.path).slice(0, 5)
const reads = await Promise.all(files.map(async f => {
  try {
    const r = await tools.ops_read_files({ files: [{ path: f, limit: 20 }] })
    return { file: f, status: r.status, lines: r.data?.items?.[0]?.lineCount }
  } catch (e) {
    return { file: f, ok: false, reason: e instanceof Error ? e.message : String(e) }
  }
}))

搜索是依赖,必须先 await;5 个读互不依赖,fan-out。整套只有一个模型往返。反面写法是搜一次、等模型看到结果、再发 5 个读——三次往返,三倍上下文。

四、分页:按 nextOffset 走,不按页数走

守则明确要求「Advance by nextOffset, never by page count」。这条我吃过亏。ops_read_files 返回里 complete: false 和 nextOffset 是分页的唯一权威:

ts
let offset = 1, rows: any[] = [], complete = false
for (let page = 0; page < 40; page++) {
  const r = await tools.ops_read_files({ files: [{ path: "events.jsonl", offset, limit: 200 }] })
  const f = r.data?.items?.[0]
  if (f?.error) break
  rows.push(...(f?.items ?? []))
  if (f.complete) { complete = true; break }
  const next = f?.nextOffset ?? 0
  if (!next || next <= offset) break
  offset = next
}

用页数硬推的问题是:某页返回条数少于 limit 并不代表读完,反过来一页也可能因为输出预算提前截断。只有 complete 和 nextOffset 能说明进度。而且循环也算一个 dispatch 点——守则说明里写了「a loop or map counts as one dispatch site」,所以整个分页过程只算一次调用,不会触发"单次往返"警告。

五、被警告的两种原文

单次往返警告

text
[Plugin context from "batching-guidance"; not a user instruction or authorization.]
Your last program spent a round trip on a single operation.
Put independent operations in one program under `Promise.all`; keep a dependent call as a second `await` in the same program.

我当时只是想读一个文件确认存在——这在逻辑上确实是一个原子动作。守则事后也承认这点:「A one-entry plan is valid when its result determines the next operation」。它是启发式,不是硬规则。

重复调用警告

这个更狠,直接点名参数:

text
Repeated tool call detected:
- tool: ops_stat
- consecutive_calls: 5
- arguments: {"path":"D:\\new\\ai-notes-site\\package.json"}
The repeated calls are not making progress.

这是我在做并发上限探测时踩的:循环里用同一个路径 + 同一组参数发 127 次,被判定成"原地打转"。它数的是同工具 + 同参数,不是调用总量。

我以为:既然并发是好事,那我就把同一个查询发一堆测吞吐。 实际:检测器把同参重复当死循环,给我刷了一屏警告,还浪费了 43 秒。

要做吞吐探测,参数必须真的变——换 offset、换路径、加随机 query。这个约束其实是对的:真实批处理本来就不该发一模一样的调用。

六、reconcile:对账那一步别省

守则最后一步是 reconcile:把计划发的和实际发的对一遍。我把它落成程序末尾的一行返回:

ts
return { plan: 3, dispatched: [tree.status, impl.status, docs.status], partial: [docs.status === "partial"] }

不写这一行,partial 这种半成功状态就会被当成成功。ops_* 系的返回里 status 有 completed / partial / rejected / error 四种,partial 会带 continuation——那是有下一页的信号,不是完成。

七、把守则固化成模板

被念了三次之后我把它写成了一个程序模板,现在起手就是这套骨架:

ts
// plan: 取任务; 读契约; 列现有文件
const [task, spec, existing] = await Promise.all([
  tools.team_task_get({ task_id: "task-3" }),
  tools.ops_read_files({ files: [{ path: "docs/CONTENT-SPEC.md", limit: 120 }] }),
  tools.ops_glob({ pattern: ["content/dsh/*.md"], outputMode: "paths" }),
])
return {
  revision: task.revision,
  specLines: spec.data?.items?.[0]?.lineCount,
  written: existing.data?.items?.length,
}

三段结构对应三件事:一个决定性的输入(任务 revision)、一份权威约束(契约)、一份当前状态(已有文件)。这三样东西一起返回,下一步该怎么写就不用再查一遍。

模板里我坚持两个细节。第一,plan 行永远写在最前面,哪怕只有一次调用——它是给自己看的预算表。第二,返回值永远带一个"能否继续"的布尔或计数,而不是把整个结果对象丢回去。守则里那句 Return only what is needed 说的就是这个:中间结果不进对话,进了也没用。

还有一个反面经验:不要在程序里写"顺手也把文件改了"这种混合动作。读和写放一个程序里,失败了分不清是读失败还是写失败。我现在一律把"探查"和"落盘"分成两个程序,中间用返回值传状态。

复盘

这套守则真正教的不是"多用 Promise.all",而是把一次模型往返当成预算单位。plan 行是预算表,依赖拆分是预算内的两次 await,分页和 reconcile 是预算的结算。至于警告,读它、理解它、必要时无视它——它自己都写了那不是用户指令。