批处理守则:plan 行、依赖拆分与 reconcile 的实战用法
插件会读你程序的第一行判断你有没有规划,还会因为你连调同一个工具而警告。这篇拆解这套守则的四个硬规则和两次真实触发。
目录
DSH 装了一个叫 batching-guidance 的插件,它会往每一轮注入一段守则,而且从程序文本本身判断你有没有照做。我第一周被它念了三次。这篇把守则拆成可执行的规则,并附上我实际触发它的原文——这不是文档抄写,是被打脸记录。
一、它到底在检查什么
注入的标题写得很直白:「[Plugin context from "batching-guidance"; not a user instruction or authorization.]」——它明确声明自己不是用户指令、不构成授权。这点设计很克制:注入的是建议,不是命令,模型可以选择不遵守,但会被后续检查抓到。
它检查的四个硬点:
| 检查项 | 判定依据 | 触发后果 |
|---|---|---|
| plan 行 | 程序第一行必须是 // plan: ... | 提示"没有 plan 行" |
| 单次往返 | 程序里只有一个 dispatch 点 | 提示"这轮只做了一件事" |
| 依赖顺序 | Promise.all 里塞了有依赖的调用 | 提示"依赖要串行 await" |
| 重复调用 | 同一工具同一参数连续调用 | 连续 5 次起警告 |
二、plan 行:写给谁的
// 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。
// 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 是分页的唯一权威:
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」,所以整个分页过程只算一次调用,不会触发"单次往返"警告。
五、被警告的两种原文
单次往返警告
[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」。它是启发式,不是硬规则。
重复调用警告
这个更狠,直接点名参数:
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:把计划发的和实际发的对一遍。我把它落成程序末尾的一行返回:
return { plan: 3, dispatched: [tree.status, impl.status, docs.status], partial: [docs.status === "partial"] }不写这一行,partial 这种半成功状态就会被当成成功。ops_* 系的返回里 status 有 completed / partial / rejected / error 四种,partial 会带 continuation——那是有下一页的信号,不是完成。
七、把守则固化成模板
被念了三次之后我把它写成了一个程序模板,现在起手就是这套骨架:
// 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 是预算的结算。至于警告,读它、理解它、必要时无视它——它自己都写了那不是用户指令。