minimal-agent 0.12.0 → 0.14.0

package/skills/workflow-creator/references/patterns.md

@@ -0,0 +1,779 @@
+# 结构模式 —— 把守卫放在该放的地方
+
+这份文档解决的不是「怎么调 API」，而是**「复杂任务该怎么搭结构」**。
+
+## 0. 先理解这个架构为什么不像 LangChain 那样脆
+
+LangChain / 低码平台的脆是**结构性**的：节点边界就是失败终止的地方，
+那里根本没有放处理器的位置。这里不一样，有两层网：
+
+**第一层（免费，你什么都不用写）**：`wf.model.agent()` 内部是 TAOR 循环，
+工具失败**从不抛异常** —— 内核把 `{ok:false, error}` 转成一条 `tool` 消息回填历史，
+下一轮模型就看得见并自己改路。实测：某次 agent 试 `Edit` 被权限拒绝，
+它自己推断出「当前宿主只授权了只读类工具」然后换用 `Read/Grep/Glob` 继续。
+
+**第二层（要你写）**：`wf.tools.call()` 失败会抛、`wf.model.agent()` 可能烂尾。
+这一层的网是你的 `try/catch` 和核实检查。**忘了写就没有。**
+
+> 一句话：**适应性是免费的，可靠性是你写出来的。**
+
+---
+
+## 1. 旋钮：这一步用 `wf.tools.call()` 还是 `wf.model.agent()`
+
+| | `wf.tools.call()` | `wf.model.agent()` |
+|---|---|---|
+| 语义 | 确定性执行 | 把判断权交给模型 |
+| 失败 | **抛异常**，你必须 catch | 模型自己看到错误并改路 |
+| 适合 | 路径明确的动作：写文件、跑脚本、转格式 | 开放任务：调研、整理、"看情况处理" |
+| 代价 | 不会随机应变 | 慢、贵、可能烂尾 |
+
+**默认选 `wf.tools.call()`。** 只有当「怎么做得看现场」时才升级到 `wf.model.agent()` ——
+`wf.model.agent()` 是你花钱买的适应性，不是默认档位。
+
+```javascript
+// ✅ 路径明确 → tool
+await wf.tools.call('Write', { file_path: OUT, content: text })
+
+// ✅ 开放任务 → agent
+const notes = await wf.model.agent('调研这个主题，整理成 markdown 写到 notes.md', {
+  allowedTools: ['Read', 'Write', 'Grep', 'Glob'],
+})
+```
+
+`allowedTools` 是给 `wf.model.agent()` 收窄注意力的手段，不是安全边界 ——
+弱模型工具一多就容易乱选。只读探索就只给只读工具。
+
+---
+
+## 2. 脊梁：必需后置条件可观察 + 有界恢复
+
+先为阶段写清楚必需后置条件，再选择与它匹配的证据和恢复方式。文件落盘用 `exists/verify`，
+结构化判断用 `schema`，状态协议用精确令牌，外部应用成果用真实打开/渲染检查。只有文件缺失且再次
+提醒确实可能解决时才使用 nudge；不要给纯分析、分类和可选探索机械套写文件循环。
+
+⚠️ **核实要查产物本身，不要查模型的话**：
+
+```javascript
+// ❌ 错：模型说做完了就信
+if (out.includes('完成')) { /* … */ }
+
+// ✅ 对：查磁盘
+if (!(await wf.fs.exists(OUT))) { /* nudge */ }
+```
+
+复杂产物（pptx/docx/pdf）要**忠实校验**，不能只测「某个库能打开」——
+真正的判据是「目标程序能干净打开」。
+
+---
+
+## 3. 降级不阻断（对应 yaml 的 `onError: continue`）
+
+某一步失败不该拖垮整条工作流时，给它一个占位值继续：
+
+```javascript
+let research = '（探索降级，按目标与常识推断）'
+try {
+  research = await wf.model.agent('探索代码库…', { allowedTools: ['Read', 'Grep', 'Glob'] })
+} catch (e) {
+  wf.output.progress(`探索阶段降级（不阻断）：${e.message}`)
+}
+```
+
+**占位值要写成人话**，因为它会被拼进下游的 prompt —— 下游模型看到
+「（探索降级）」就知道该自己推断，看到空字符串则会以为探索结果真的是空。
+
+### 3.1 组件级部分交付
+
+不要把复合成果压成一个布尔值。主体可用、附件缺失时，应保留主体并把缺失组件结构化传给下游：
+
+```javascript
+return {
+  completeness: 'partial',
+  components: {
+    body: { status: 'complete', path: BODY },
+    attachment: {
+      status: 'source_limited',
+      reason: '原始输入没有包含该附件',
+    },
+  },
+}
+```
+
+下游只为 `attachment` 放占位或请求补充，不能丢弃 `body`。如果缺的是主体必需输入，
+则诚实停止或生成明确的整项占位。`source_limited`、`processing_failed`、`ambiguous`
+要分开：前者重试无收益，后两者才可能通过换输入、修定位或补证据恢复。
+
+---
+
+## 4. 就地自愈（对应 yaml 的 `onError: recover`）
+
+比降级更进一步：失败时起一个 agent，**把真实错误给它看**，让它想办法把结果做出来。
+
+```javascript
+let count
+try {
+  const r = await wf.exec.shell(`wc -l ${NOTES}`)
+  if (r.exitCode !== 0) throw new Error(r.stderr)
+  count = r.stdout.trim()
+} catch (e) {
+  wf.output.progress(`统计失败，起 agent 自愈：${e.message}`)
+  count = await wf.model.agent(
+    `执行 \`wc -l ${NOTES}\` 失败了：${e.message}\n` +
+      '请先用 Glob/Read 定位文件真实位置，再统计行数。',
+    { label: 'recover-count', allowedTools: ['Read', 'Glob', 'Bash'] },
+  )
+}
+```
+
+**关键是把 `e.message` 原样给它** —— 恢复 agent 最需要的信息就是「到底错在哪」。
+只说「上一步失败了」等于让它从零猜。
+
+恢复前再问一句：**下一轮与上一轮相比，什么会改变？** 如果答案是“什么都不变”，就不要重试。
+结构格式错误交给 `schema` 的有界修复；坐标或范围错误要按缺失方向改输入；工具路径错误要先定位
+真实路径；原始输入没有信息则记录部分结果并结束该组件。重复同一图片、同一框和笼统提示不是自愈。
+
+---
+
+## 5. 打回 vs 只许向前（带标签的 continue / break）
+
+多阶段工作流常有两种"回退"，语义完全不同，别混：
+
+```javascript
+planLoop: for (let round = 1; round <= 3; round++) {
+  // …规划…
+  for (let a = 1; a <= 5; a++) {          // 审批小循环
+    const fb = await wf.flow.ask('请审批', [/* … */])
+    if (isFundamental(fb)) {
+      learnings.push(fb)
+      continue planLoop                    // ← 方向性变化：回到规划阶段重来
+    }
+    // …小改就地修订，本小循环下一轮再确认…
+  }
+
+  for (let ex = 1; ex <= 3; ex++) {        // 执行闭环
+    await wf.model.agent('执行计划…')
+    const ok = await wf.check.verify(CHECKS)
+    if (ok.passed) break planLoop          // ← 验收通过：直达收尾
+    // ⚠️ 不合格**只重执行**，绝不回规划阶段
+  }
+  throw new Error('执行 3 轮仍未通过验收，诚实停止')
+}
+```
+
+**一条实战裁决**：用户批准过的计划**只许向前**。验收不合格时带着阻塞原因重新执行，
+不要打回规划、不要重新审批 —— 那会让用户反复看到同一个审批闸门，被误读成死循环。
+
+---
+
+## 6. 扇出 —— 用 `wf.flow.pipeline()`，**不要**裸 `Promise.all`
+
+```javascript
+const batch = await wf.flow.pipeline(files, {
+  label: '逐文件审计',
+  concurrency: 6,
+  errorMode: 'collect',
+  stages: [async (_previous, file) =>
+    wf.model.agent(`审计 ${file}`, { label: file })],
+})
+const results = batch.results
+  .filter((item) => item.ok)
+  .map((item) => item.value)
+```
+
+⚠️ **这一节以前给的范例是 `Promise.all(files.map(f => wf.model.agent(...)))`，那是错的。**
+账本按「**车道内序号** + 内容指纹」定位断点。裸 `Promise.all` 让所有 agent 挤在
+**同一条车道**上并发记账 —— 序号取决于谁先返回，也就是取决于 LLM 延迟。同一个脚本
+两次运行的序号分配可能完全不同 → 首个失配 → 其后全部实跑，**断点续跑静默失效**。
+
+**最阴的地方是它测不出来**：扇出 N ≤ 8（并发闸门）时所有项同时起跑、完成顺序恰好
+稳定，小规模用例恒绿。等真实任务扇出 12 项才炸，而那时你已经不在改这段代码了。
+引擎检测到同车道并发会发一次 warning（文案里有「断点续跑随之失效」），看到它就是
+在提示你改用 `pipeline`。
+
+`pipeline` 给每一项一条确定的车道（`<父车道>/p<第几个>i<第几项>`），车道内串行、
+序号与调度无关，**扇出与 resume 因此可以兼得**；嵌套 pipeline 同样成立。
+
+**多阶段无屏障**：`wf.flow.pipeline(items, { stages: [阶段1, 阶段2] })` 里每项独立走完全部阶段 ——
+A 项可以在阶段 2 而 B 项还在阶段 1，不必等齐。阶段回调签名是
+`(上一阶段结果, 原始项, 下标)`，所以后续阶段拿得到原始项，不用把上下文串进返回值。
+
+**需要屏障时不必找别的原语**：`pipeline` 本身就是 await 全部完成后返回数组，
+单阶段的 `wf.flow.pipeline(items, { stages: [阶段] })` 就是「全部跑完再往下」。真正需要屏障的只有
+「下一步要看全部结果」的场景（跨项去重、汇总、零结果早退）。
+
+**失败语义必须显式选择**：`errorMode:'collect'` 会把失败项保留为
+`{ok:false,index,error:{name,message,code}}` 并继续其它项；`fail-fast` 停止调度尚未开始项、
+等待已开始项退出后抛 `AggregateError`。返回顺序恒等于输入顺序，不能再用 `null` 猜失败原因。
+
+---
+
+## 7. loop-until-dry（未知规模的发现类任务）
+
+固定轮数会漏掉尾巴。改成「连续 K 轮没有新东西才停」：
+
+```javascript
+const seen = new Set()
+let dry = 0
+for (let round = 1; round <= 10 && dry < 2; round++) {
+  wf.state.resetModelContext()
+  const found = await wf.model.agent(`找出还没被发现的问题。已知：${[...seen].join('、')}`)
+  const fresh = extractItems(found).filter((x) => !seen.has(x))
+  if (fresh.length === 0) { dry++; continue }
+  dry = 0
+  for (const x of fresh) seen.add(x)
+}
+```
+
+**去重要对 `seen`（全部见过的），不是对"已确认的"** —— 否则被否掉的项每轮都会重新出现，永远不收敛。
+
+---
+
+## 8. 验收员与执行者分离
+
+同一个模型评自己的产出会偏袒。让验收走**独立的一次调用**，并明确要求它**亲自核验**：
+
+```javascript
+const assess = await wf.model.agent(
+  `你是独立验收员。不要轻信执行 agent 的自述，也不要把"写了一部分"当完成。
+用 Bash/Read/Glob **亲自核实**产物真实存在、满足每条成功标准。
+只输出 JSON：{"qualified":bool,"blocking_reason":string,"summary":string}`,
+  { allowedTools: ['Read', 'Bash', 'Glob'], contextFiles: [{ path: PLAN, hint: '成功标准' }] },
+)
+const v = parseJson(assess) ?? { qualified: false, blocking_reason: '验收本身失败' }
+```
+
+⚠️ **上面这段是旧写法，现在应该传 `schema:`**（见第 18 节）：
+
+```javascript
+const v = await wf.model.agent(`你是独立验收员。……`, {
+  allowedTools: ['Read', 'Bash', 'Glob'],
+  contextFiles: [{ path: PLAN, hint: '成功标准' }],
+  schema: {
+    type: 'object',
+    required: ['qualified', 'blocking_reason', 'summary'],
+    properties: {
+      qualified: { type: 'boolean' },
+      blocking_reason: { type: 'string' },
+      summary: { type: 'string' },
+    },
+  },
+})
+```
+
+这一节以前写着「**不要依赖 provider 的 json_schema** —— 弱 provider 不支持时整条会挂掉」。
+那条顾虑是真的，但 `schema:` 不等于 provider 原生约束，它是**三层**：
+
+1. provider 原生 `response_format`（**仅零工具调用时**开；Anthropic 格式直接跳过）
+2. 引擎侧抽 JSON + 按 schema 校验（手写子集，不认识的关键字忽略）
+3. 不合格就把**逐条违规**回喂模型做有界修复（2 轮）
+
+所以第 1 层没有也不会挂 —— 2、3 层是可移植的地板。这正是「弱 provider 也能用结构化输出」
+的实现方式，不是绕过它。
+
+⚠️ 但 `wf.model.agent()` 的工具循环**不能**开原生约束（`response_format` 要求每条 assistant
+消息都是 JSON，与 `tool_calls` 互斥）—— 引擎的做法是「带工具干完活，再零工具整形」，
+你不用管，但要知道带工具的 `schema` 会多一次调用。
+
+### ⚠️ 从「解析失败就降级」的旧封装迁过来时，**别忘了包 try/catch**
+
+这是 `plan` 迁移时踩到的：旧的 `askJson(prompt, opts, fallback)` 语义是
+「解析不出来就返回 fallback，**不抛**」，调用点靠这个降级继续
+（分类判不出来当 minor、验收判不出来当不合格）。而 `schema` **修完两轮仍不合格会抛**。
+
+```javascript
+// ❌ 直接把 parseJson 换成 schema —— 一次分类失败就让整条工作流崩在审批闸门上
+return await wf.model.agent(prompt, { ...opts, schema })
+
+// ✅ 失败语义要自己接回来
+async function askJson(prompt, opts, fallback) {
+  try {
+    return await wf.model.agent(prompt, opts)   // opts.schema 由调用点给
+  } catch (e) {
+    wf.output.progress(`结构化输出失败，降级到默认值：${e.message}`)
+    return fallback
+  }
+}
+```
+
+**先问自己这个调用点该不该抛**：产出物类的（写文件、给结论）该抛，
+让阶段契约定义的有界恢复接住；分类/判定类的往往需要一个「破坏最小的默认值」
+继续走 —— 后者才需要这层 try/catch。
+
+### `enum` 挡的是「分支被静默走错」
+
+只要下游有 `if (x.category === 'fundamental')` 这样的分支，就给它 `enum`：
+
+```javascript
+properties: { category: { enum: ['minor', 'fundamental'] } }
+```
+
+没有 enum 时模型吐 `"Fundamental"` / `"方向性"` / `"major"`，代码会**静默落进
+else 分支**。`plan` 里这意味着用户提了方向性意见却被当成小改就地改两句 ——
+这类错不报警、不留痕，只是结果不对。
+
+---
+
+## 9. HITL 闸门放哪
+
+`wf.flow.ask()` 会真停等。放的位置有讲究：
+
+- ✅ **方案定型后、开始烧钱之前**（执行前审批）
+- ✅ **不可逆动作之前**（发布、删除、提交）
+- ❌ 不要放在循环体里每轮都问 —— 非交互宿主会自动选推荐项，等于没问；交互宿主则烦死人
+- ❌ 不要用它替代核实。`wf.flow.ask()` 问的是「要不要继续」，`wf.check.verify()` 问的是「做成了没有」
+
+**推荐项放第一个**并在 label 写「(推荐)」：非交互宿主自动选第一个。
+
+---
+
+## 10. 长循环记得 `wf.state.resetModelContext()`
+
+每轮都带着前几十轮的对话跑，模型会被旧上下文带偏，token 也线性膨胀。
+截回入口快照（含 Skills 目录，不是清空）：
+
+```javascript
+for (let i = 1; i <= MAX; i++) {
+  wf.state.resetModelContext()
+  // …本轮…
+}
+```
+
+跨轮要保留的东西放**变量**里（`learnings` 数组之类），它们不受 `wf.state.resetModelContext()` 影响。
+别用「写文件 + 每轮读回来」的土办法 —— Read 的输出带行号和空文件标记，
+逐轮把格式垃圾累积进档案。
+
+---
+
+## 11. 大工作流拆多文件（`research` / `illustrate` 实战）
+
+超过两三个阶段、或 prompt 很长的工作流，**别都塞进一个 `workflow.mjs`**。
+主入口应该读起来像**流程的目录**，细节下沉：
+
+```
+workflows/research/
+├── workflow.mjs              主入口 —— 一眼看清六个阶段、守卫在哪
+├── prompts/s0-goal.md …      九段长 prompt（改措辞不用动代码，diff 干净）
+└── scripts/build-report.mjs  报告拼装（可单独跑，见下）
+```
+
+**读 prompt 文件的标准写法**：
+
+```javascript
+const PROMPTS = 'workflows/<名字>/prompts'
+
+async function prompt(name, vars = {}) {
+  let text = await wf.fs.readText(`${PROMPTS}/${name}.md`)
+  if (text === null) throw new Error(`缺少 prompt：${PROMPTS}/${name}.md`)
+  for (const [k, v] of Object.entries({ topic: args.topic, dir: DIR, ...vars })) {
+    text = text.split(`{{${k}}}`).join(String(v ?? ''))
+  }
+  return text
+}
+
+await wf.model.agent(await prompt('s1-map'), { label: '阶段1', allowedTools: [...] })
+```
+
+用 `{{name}}` 而不是 `${name}` 做占位符：prompt 文件里常有 JS/shell 代码示例，
+`${}` 会撞车。
+
+**确定性处理抽成 `scripts/*.mjs` 的三个理由**（不是为了好看）：
+1. **可移植** —— 原 yaml 里报告拼装是一大段 bash（`sed -E` / `basename` / `set -euo pipefail`），
+   Windows 上要靠 Git Bash 才有，宿主回落 cmd 时整段不可用。
+2. **可单独跑** —— 拼装出问题时 `node workflows/research/scripts/build-report.mjs out/research/x standard`
+   一条命令复现，不用等前面五个阶段重跑一遍。真实价值：迁移 `research` 时我就是这么
+   先把拼装逻辑验证完的。
+3. **注入面为零** —— 不经过 shell，用户输入拼不进命令体。
+
+**易变的东西当数据放 `assets/`**。`illustrate` 的三家搜索引擎抽取 JS 随页面改版
+必然失效，拆成 `assets/extract-*.js` 后，加一家引擎 = 加一个 json 条目 + 一个 js 文件，
+主脚本一行不动。
+
+---
+
+## 12. 把脊梁规则收进一个 `stage()`（多阶段工作流必备）
+
+阶段一多，"调 agent → 核实产出 → 没有就 nudge" 会重复十几遍。收进一个函数：
+
+```javascript
+async function stage(label, promptText, outputs, opts = {}) {
+  let out = await wf.model.agent(promptText, { label, maxTurns: opts.maxTurns ?? 25, ...opts })
+  for (let i = 1; i <= 2; i++) {
+    const missing = []
+    for (const f of outputs) if (!(await wf.fs.exists(f))) missing.push(f)
+    if (missing.length === 0) break
+    wf.output.progress(`${label}：还缺 ${missing.length} 个文件，第 ${i} 次提醒`)
+    out = await wf.model.agent(
+      `以下文件还没有生成：\n${missing.map((m) => `- ${m}`).join('\n')}\n\n` +
+        '请**现在就调用 Write 工具**把它们写出来，不要只描述你打算做什么。',
+      { label: `${label}·nudge-${i}`, allowedTools: opts.allowedTools, maxTurns: 12 },
+    )
+  }
+  const still = []
+  for (const f of outputs) if (!(await wf.fs.exists(f))) still.push(f)
+  if (still.length > 0) throw new Error(`${label} 未能产出：${still.join('、')}`)
+  for (const f of outputs) wf.output.artifact(f)
+  return out
+}
+```
+
+之后每个阶段一行：
+
+```javascript
+await stage('阶段1/6·测绘领域地图', await prompt('s1-map'),
+  [`${DIR}/02-map.md`, `${DIR}/early-exit.json`],
+  { allowedTools: RESEARCH_TOOLS, maxTurns: 25 })
+```
+
+**收益不只是少写字**：产出核实与 `declareArtifact` 变成"经过这个函数就一定有"，
+而不是每个阶段作者自觉。漏写一处 = 一个静默不落盘的产物。
+
+---
+
+## 13. 从 DSL 迁过来时，**把不该给模型的活收回来**
+
+yaml 里有些 `agent:` 步不是因为该让模型做，而是因为 **DSL 表达不了**。
+迁移时要认出来并改成确定性代码。
+
+真实例子（`illustrate` 阶段6）：yaml 里是一个 agent，让模型 Glob 出十几个
+`score_*.json`、逐个 Read、心算 `relevance × quality`、排序、取前 N、剔除广告图。
+
+JS 里这是三行：
+
+```javascript
+const picks = scored
+  .filter((s) => !s.is_ad)
+  .sort((a, b) => b.relevance * b.quality - a.relevance * a.quality)
+  .slice(0, wanted)
+```
+
+模型做这件事会算错乘积、会漏剔广告、而且**结果不可复现**。
+
+> **判据**：这一步的输入输出如果能写成一个纯函数，就不该用 `wf.model.agent()`。
+> 需要判断力（读代码、看图、写文章、决定方案）才用模型。
+
+---
+
+## 14. 外部依赖失败时，**报真实错误而不是猜测**
+
+工作流里凡是「依次尝试多个来源」的地方，失败时必须把**每一家的真实报错**带出来。
+
+反例（`illustrate` 第一版）：三家图搜都没抓到候选，报错写的是
+「可能全被墙/反爬，或抽取规则需随页面改版调整」—— 纯猜测。
+而真实原因是「WebBrowser 的 eval 需要 Developer Mode 授权」，
+照着那句猜测去查抽取规则会白费很多时间。
+
+正确写法：
+
+```javascript
+const failures = []
+for (const engine of engines) {
+  try { /* …尝试… */ }
+  catch (e) { failures.push(`${engine.label}：${e.message}`) }
+}
+
+if (got.length === 0) {
+  const detail = failures.length
+    ? `\n\n各家的真实报错：\n${failures.map((f) => `  · ${f}`).join('\n')}`
+    : ''
+  throw new Error(`全部来源都失败。${detail}\n\n常见原因：① … ② … ③ …`)
+}
+```
+
+**真实报错在前，可能原因在后**。前者是事实，后者是提示。
+只给提示等于让用户去猜，而猜错的成本是几十分钟。
+
+---
+
+## 15. 有外部前置条件的工作流，把它写进 README 开头
+
+`illustrate` 需要「设置 → 浏览器」里开启 Developer Mode 并把三个搜索站点
+加进白名单，否则 `eval` 一定失败。这类**环境前置条件**不写清楚，
+用户第一次跑必然撞墙，还以为是工作流坏了。
+
+README 里单开一节 `## ⚠️ 前置条件`，写明：要什么、为什么要、**没有时的表现是什么**。
+第三条最有用 —— 用户是靠"表现"反查到那一节的。
+
+---
+
+## 16. 给工作流写单元测试（依赖外部环境时的唯一出路）
+
+有些工作流依赖跑不动的东西 —— `wechat-reading-shots` 要 ComputerUse，而它目前
+只吃 macOS，Windows 上**端到端根本跑不了**。但这类工作流真正容易错的地方全在
+**控制流**上，而控制流可以脱离外部环境测：给默认导出的 `run(wf)` 传入最小的
+`WorkflowContext` stub。只有要验证 ESM 装载、journal 或恢复时才经过 Runner。
+
+```typescript
+const { default: run, meta } = await import(
+  new URL('../../../workflows/<名字>/workflow.mjs', import.meta.url).href
+)
+expect(meta.apiVersion).toBe(2)
+
+// stub 按 label 决定每次调用返回什么 —— 这就是“剧本”
+const wf = {
+  input: { values: args, resources: {} },
+  runtime: { sessionId: 's', taskId: 't', goal: '' },
+  model: {
+    agent: async (_prompt, opts = {}) => {
+      if (opts.label?.includes('读页码')) return pageReads[i++]
+      if (opts.label?.includes('打开正文')) return 'OPEN=ok'
+      return ''
+    },
+  },
+  tools: { callResult: async (name, input) => { /* 记调用、按 action 返回 */ } },
+  output: {
+    message: (message) => log.messages.push(message),
+    artifact: (path) => log.artifacts.push(path),
+  },
+  /* 其余被工作流实际访问的分组给最小实现 */
+}
+
+const result = await run(wf)
+```
+
+**能测到什么**（都是真实踩过的坑）：
+
+| 断言 | 防的是什么 |
+|---|---|
+| 模型回复带前言/围栏时参数仍能提取 | 「只回一行 JSON」这种约定**没法强制** |
+| `'ok 的路子都走不通'` 不得判成成功 | 用 `includes('ok')` 而非精确取值 |
+| `PAGE=112 113` 不因含子串 `12` 误判 | 同上，判据要精确 |
+| 请求 N 张就拍 N 张 | 张数交给模型 = 它会数错并且说谎 |
+| 撞到边界提前收工且如实报数 | 继续拍只会得到 N 张一样的图 |
+| 每次调用都带 `uses:['computer']` | 漏了宿主不转授权，工具必失败 |
+
+**给 label 起有意义的名字**不只是为了日志好看 —— stub 靠它路由，
+测试的可读性直接取决于它。
+
+---
+
+## 17. 核实不一定是查文件
+
+脊梁规则的本质是「**不盲信 agent 的自述**」，核实形态有三种：
+
+| 形态 | 写法 | 适用 |
+|---|---|---|
+| 核实文件 | `wf.fs.exists()` / `wf.check.verify()` | agent 应当产出文件 |
+| **核实协议令牌** | `text.match(/OPEN=([a-z]+)/)?.[1] === 'ok'` | agent 报告一个状态 |
+| **核实结构化产出** | 传 `schema:` 让引擎校验（旧写法是 `parseJson` 后自己判字段） | agent/llm 返回 JSON |
+
+⚠️ 第三种现在应该用 `schema:` 而不是手写 `parseJson` —— 见第 18 节，
+手写那套的问题不在于啰嗦，在于**兜底会掩盖失败**。
+
+⚠️ **协议令牌一定要精确取值，不要在自由文本里找关键词。**
+`includes('ok')` 会把「ok 的路子都走不通」判成成功；
+`includes('12')` 会把 `PAGE=112 113` 判成到了第 12 页。两条都是实测踩出来的。
+
+`validate.mjs` 的脊梁检查认这三种形态。早先它只认第一种，于是
+`wechat-reading-shots`（守卫其实很严，只是核实的是令牌不是文件）被误报 ——
+**误报比漏报更伤**：作者一旦习惯「这个警告可以忽略」，真正该看的那次也会被划过去。
+
+---
+
+## 18. 逐项独立评估 = `pipeline` + `schema` + `isolated`
+
+「拿 N 个东西，逐个让模型评估打分，再确定性选优」是最常见的扇出形状
+（`illustrate` 的识图选图、研究类工作流的候选打分、批量质检）。
+三项能力**各自解决这个形状里的一个真实缺陷**，缺一个都留着坑：
+
+```javascript
+const SCORE = {
+  type: 'object',
+  required: ['relevance', 'quality', 'is_ad', 'reason'],
+  properties: {
+    relevance: { type: 'number', minimum: 0, maximum: 10 },
+    quality: { type: 'number', minimum: 0, maximum: 10 },
+    is_ad: { type: 'boolean' },
+    reason: { type: 'string' },
+  },
+}
+
+const scored = (
+  await wf.flow.pipeline(
+    candidates,
+    // 阶段 1：评估。拿到的是**校验过的对象**，不是待解析的字符串
+    (cand) =>
+      wf.model.generate(`评估这张图……只输出 JSON 对象本身。`, {
+        label: `打分 #${cand.index}`,
+        images: [{ source: cand.path, detail: 'high' }],
+        schema: SCORE,
+        isolated: true,
+      }),
+    // 阶段 2：与原始元信息合并（纯 JS，不烧 token）
+    (s, cand) => ({ ...cand, ...s }),
+  )
+).filter(Boolean)
+
+// 阶段 3：确定性选优 —— 排序、剔除、取前 N 都不该交给模型
+const picks = scored.filter((s) => !s.is_ad)
+  .sort((a, b) => b.relevance * b.quality - a.relevance * a.quality)
+  .slice(0, wanted)
+```
+
+各自挡的是什么：
+
+| 能力 | 挡掉的缺陷 |
+|---|---|
+| `schema` | 手写 `parseJson` + `Number(s.x ?? 0)` 兜底 —— 见下，**兜底会掩盖失败** |
+| `pipeline` | 串行排队；以及裸 `Promise.all` 导致的 resume 静默失效（第 6 节） |
+| `isolated` | **前项锚定后项**：共享主线时第 10 项打分能看见前 9 项的评语 |
+
+### ⚠️ 上了 `schema` 就**删掉**兜底，别两个都留
+
+```javascript
+// ❌ schema 已经保证 relevance 是 0-10 的 number，这个 ?? 0 是在拆网
+relevance: Number(s.relevance ?? 0)
+// ✅
+relevance: s.relevance
+```
+
+`?? 0` 看着"稳健"，实际是把「打分没解析出来」伪装成「这张图得 0 分」——
+它被排到末位淘汰掉，你在结果里**看不到任何异常**。schema 的价值恰恰是让这种
+失败抛出来：两轮修复（引擎会把逐条违规回喂给模型）都不合规才抛，
+pipeline 接住变 `null`，`.filter(Boolean)` 之后数量对不上你就发现了。
+
+### ⚠️ `schema` 保证「形状对」，保证不了「模型真看见了输入」
+
+一个完全没收到图片的模型照样能吐出合法 JSON。带 `images` 时值得再加一条判据：
+
+```javascript
+const subjects = new Set(results.map((r) => r.subject))
+if (results.length > 1 && subjects.size === 1) {
+  throw new Error('不同的图给出了完全相同的描述 —— images 通道很可能没真的送到')
+}
+```
+
+### ⚠️ 扇出的项来自 `sh` 时，**排序**，否则指纹不稳
+
+```javascript
+// ❌ find/ls 的输出顺序不保证 —— 顺序一变每项就换了车道，resume 整片失配
+const r = await wf.exec.shell(`find "${dir}" -iname '*.png'`)
+// ✅
+const r = await wf.exec.shell(`find "${dir}" -iname '*.png' | sort`)
+```
+
+确定性纪律不只管 `Date.now()`/`Math.random()`（那两个 `scriptGuard` 会拦），
+**任何进入指纹的东西都得稳定**，而扇出项的顺序决定了车道分配。这条 guard 拦不住。
+
+### 实测过的组合边界
+
+- `images` + `schema` **可用**：图片走消息附件通道、不需要工具，所以仍是零工具调用，
+  provider 原生 `response_format` 照常开。已在真实 provider（豆包 seed-2.1，OpenAI 格式）
+  上跑通 10 项扇出，schema 校验与 enum 全部生效。
+- 修复轮**仍然带图**（要模型看着图改分才有意义），所以一次修复的成本约等于一次原调用。
+- `isolated` 与 `images` 正交：`isolated` 只换 history（只留系统提示），不碰附件通道。
+- 探针 `workflows/e2e-vision-schema/` 就是锁这条组合路径的，改引擎后可以直接跑它。
+
+---
+
+## 19. Goal Runtime 管理下的自主循环（`workflows/goal/` 实战）
+
+Goal 生命周期属于外层 `Goal Runtime`：稳定 Goal/契约版本、Attempt、暂停恢复、资源状态和人类最终
+验收都不能由 Workflow Runner 或脚本自行发明。具体循环策略属于
+`workflows/goal/workflow.mjs`：契约化、执行、硬门、独立审计、停滞检测和报告都在工作流目录内实现。
+该工作流用 `managedRuntime: 'goal'` 获取通用执行租约；Runner 不理解 Goal 字段。
+
+下面是可按业务裁剪的循环设计要点，不是让所有工作流复制一套 Goal 生命周期：
+
+### ① 先把目标**契约化**，再开始循环
+
+自主循环的成败**在第一步就决定了**：契约就是停止条件本身。
+写得可验证，循环自己收敛；写成「代码更好」「性能优化」，循环永远判不了何时结束 ——
+要么早早误判完成，要么一直空转烧钱。
+
+所以阶段 0 不是「理解目标」，是**产出一份可机器验证的契约**：产出物清单 +
+`hard_checks`（`wf.check.verify()` 能吃的四种格式）+ 只评估不阻塞的质量维度。
+拟不出判据时**反过来问用户**（`wf.flow.ask()`，开头一次问完，之后全程自主）。
+
+### ② 校验模型给的检查项，**用引擎自己的解析器**
+
+模型写的 `hard_checks` 经常自创前缀（`command:` / `assert:` / `exists:`）。
+不要在工作流里再写一份正则去校验 —— `wf.check.verify()` 遇到无法解析的串会**响亮抛错**，
+直接拿它当校验器，配一个有界修复循环：
+
+```javascript
+for (let fix = 0; fix <= 2; fix++) {
+  try { await wf.check.verify(contract.hard_checks); break }   // 能解析就行，通不通过不重要
+  catch (e) {
+    if (fix === 2) throw new Error(`检查项格式反复不合法：${e.message}`)
+    contract = await wf.model.generate(`${基础提示}\n⚠️ 上次的 hard_checks 无法解析：${e.message}`, { schema })
+  }
+}
+```
+
+好处是判据只有一份（引擎的），不会漂移；坏处是要多跑一次 `verify`，很便宜。
+
+### ③ 完成判定要**两道独立的关**，别让干活的模型自己打分
+
+```javascript
+const gate = await wf.check.verify(hardChecks)          // 关 1：引擎真跑命令，不问模型
+if (!gate.passed) { /* 带失败项进下一轮 */ }
+
+const audit = await wf.model.agent(审计提示, {           // 关 2：独立审计
+  allowedTools: ['Read','Glob','Grep','Bash'],  //   只读
+  isolated: true,                               //   ← 关键：看不见执行者说过什么
+  schema: AUDIT_SCHEMA,
+})
+```
+
+`isolated: true` 是这一关的**承重部分**。审计员一旦看得见执行者的自述，
+就会被「我已经完成了 X」带着走；隔离之后它只能自己去查文件系统。
+
+审计要专门查两件硬门查不出来的事：
+- **为通过检查而削弱检查**（改松断言、`|| true`、`--passWithNoTests`、关键字塞注释里）
+- **检查覆盖不全**（目标要三种格式，而检查只测了已实现的那一种）
+
+### ④ 停滞指纹同时看失败项和归一化证据
+
+这条最容易写错，而且错了**看起来一切正常**：
+
+```javascript
+// ❌ 原始 summary/output 含时间、耗时等噪声，每轮都会变化
+const sig = gate.summary
+
+// ❌ 只看检查名称也会误伤：检查仍失败，但错误行、缺失项或证据可能正在收敛
+const sig = failed.map(d => checkLabel(d.check)).sort().join(' | ')
+
+// ✅ 失败项 + 去掉时间/耗时噪声后的失败证据共同组成进展指纹
+const sig = evidenceFingerprint(gate, failed)
+```
+
+`wf.check.verify()` 返回 `{ passed, summary, details: [{check, passed, output}] }`，
+`check` 是结构化对象（`{type, command?, file?, pattern?, minCount?}`）。实际实现见
+`workflows/goal/workflow.mjs::evidenceFingerprint`，避免参考文档与工作流分叉。
+
+**为什么非要有卡死检测**：纯轮数上限拦不住空转 —— 目标模糊时循环会反复无效尝试，
+一路烧到撞顶才停。实测（`max_iterations=5, stall_rounds=2`）在第 3 轮就止损了。
+
+### ⑤ 质量评估**只报告、不阻塞**
+
+功能达成做门；性能 / 易用性 / 鲁棒性做报告。把开放式质量判断放进停止条件，
+循环永远不收敛（总能再挑出一条可优化的）—— 本仓库的 PPT 视觉门为此付过学费。
+
+在审计的 schema 里带一个嵌套的 `quality` 对象即可（校验器支持嵌套，违规消息带路径
+如 `quality.performance`），并在提示里明说「这几个分数不影响 achieved 判定，
+请诚实打分，不会因为打低分就多跑一轮」。
+
+### ⑥ 落盘要在抛错**之前**
+
+未达成时抛错是对的（让 `-p --output-format json` 的 `ok`/`stop_reason` 如实反映失败），
+但报告是排障的唯一线索：
+
+```javascript
+await wf.tools.call('Write', { file_path: REPORT_PATH, content: ... })   // 先落盘
+wf.output.artifact(REPORT_PATH)
+if (status !== 'achieved') throw new Error(...)                 // 再抛
+```
+
+### ⑦ ⚠️ 含空格的 `--input` 值必须加引号（这条坑所有带贪婪首参的工作流）
+
+```bash
+--input checks=shell:bun test test/x.ts     # ❌ 截断成 `shell:bun`
+--input "checks=shell:bun test test/x.ts"   # ✅
+```
+
+引擎对「值被拆碎」有自动拼回 + 告警，但**只在贪婪首参已经走了 `--input` 时才触发**；
+首参走位置参数时命中另一条分支，散落的词被**静默**拼进首参末尾。
+更阴的是截断后的值往往**仍然合法** —— 自测时 `shell:exit 1` 被截成 `shell:exit`，
+而不带参数的 `exit` 退出码是 0，于是那道本该永远失败的硬门反而"通过"了。
+在 README 里明确写出正确写法，别指望用户猜。