minimal-agent 0.13.0 → 0.15.0

package/workflows/goal/workflow.mjs

@@ -0,0 +1,501 @@
+export const meta = {
+  apiVersion: 2,
+  managedRuntime: 'goal',
+  description:
+    '目标驱动的自主循环：先把目标固化成可机器验证的完成契约（不清楚就问），再「执行 → 确定性硬门 → 独立审计」反复迭代，直到达成或触发停止条件；收尾出四维质量评估报告',
+  inputs: [
+    {
+      name: 'objective',
+      required: false,
+      greedy: true,
+      description: '要达成的目标（一句话自然语言即可，不会被空格拆碎）',
+    },
+    {
+      name: 'checks',
+      default: '',
+      description:
+        "已想好的退出条件，逗号分隔（如 'shell:bun test,file_exists:dist/app.js'）。给了就跳过契约拟定与确认，直接开跑",
+    },
+    { name: 'max_iterations', type: 'number', default: 8, description: '最大迭代轮数' },
+    {
+      name: 'stall_rounds',
+      type: 'number',
+      default: 3,
+      description: '连续几轮「失败的检查完全相同」就判定卡死并停止',
+    },
+    {
+      name: 'interactive',
+      default: 'true',
+      description: "'false' 则跳过契约确认闸门（无人值守场景）",
+    },
+    {
+      name: 'action',
+      type: 'enum',
+      values: ['start', 'status', 'pause', 'resume', 'update', 'cancel', 'accept', 'rework'],
+      description: 'Goal Runtime 控制动作；不填时创建、查询或继续当前 Goal',
+    },
+    { name: 'reason', description: '暂停、取消或返工原因' },
+    {
+      name: 'token_budget',
+      type: 'number',
+      description:
+        'token 预算上限（input+output）。缺省不限。只在每轮开始前判定，绝不打断进行中的一轮；' +
+        '用尽后加大预算用同一目标重跑即可从断点继续',
+    },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task, workflowDir } = wf.runtime
+const { generate: llm, agent } = wf.model
+const { call: tool } = wf.tools
+const { shell: sh } = wf.exec
+const { readText, exists } = wf.fs
+const { ask } = wf.flow
+const { verify } = wf.check
+const { budget, resetModelContext: resetContext, addGoalSupplement, syncManagedContract } = wf.state
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// ============================================================
+//  设计出处：对齐 OpenAI Codex 的 `/goal`（其内部叫 Ralph Loop），
+//  但**有意在三处不同** —— 这三处正是我们的取向：
+//
+//  ① **Codex 不做目标澄清**，官方明确「finish line 模糊时就别用 Goals」。
+//     我们有 `ask()`，所以在阶段 0 把目标**契约化**：拟不出可验证判据时反过来问用户。
+//     这是社区反复吐槽的那个坑（弱目标 → 循环不收敛 → 烧 token）的正面解法。
+//     ⚠️ 但只在**开头问一次**，确认后全程自主 —— 循环体里绝不停下来问。
+//
+//  ② **完成判定是两道独立的关**，不是让干活的模型自己打分：
+//     先过引擎跑的确定性硬门（`verify()` 真跑命令），再过一个 `isolated: true` 的
+//     审计 agent（看不见执行者的对话，只能自己去查文件系统）。
+//     Codex 的 completion audit 是同一个思路，社区吐槽点恰恰是「有时仍不够严格，
+//     需要额外的独立 critic」—— 隔离上下文就是为这个。
+//
+//  ③ **质量评估只报告、不阻塞**。功能达成做门，性能/易用性/鲁棒性做报告。
+//     把开放式质量判断放进停止条件，循环永远不收敛（总能再挑出一条可优化的）。
+//     这条在本仓库有过真实教训：PPT 视觉门一度把对比度/字号做成硬 ERROR，
+//     结果是卡死重试；后来改成质量类一律 WARNING、硬 ERROR 只留确定性缺陷。
+//
+//  三把停止刻度（**都只在开新一轮之前求值**，绝不打断进行中的一轮）：
+//    · 轮数 `max_iterations` —— 最粗的兜底。
+//    · 无进展 `stalled` —— 真正防空转烧钱的那把。纯轮数上限拦不住「反复无效尝试」，
+//      它会一直跑到撞顶；连续 N 轮失败项与失败证据完全相同才判定。
+//    · token 预算 `budget_limited` —— 由 Goal 契约的 `tokenBudget` 设，默认不限。
+//
+//  ⚠️ 「只在轮次边界」是产品决策，不是实现偷懒：一轮对话一旦开始，中途超额
+//     也一路跑完到节点。宁可超一点预算，也不能把 agent 停在半成品状态。
+//     引擎内核因此完全不做预算检查（`loop.ts` 里一行都没有），脚本层同守此约。
+// ============================================================
+
+const DIR = `out/goal/${session}/${task}`
+const CONTRACT_PATH = `${DIR}/CONTRACT.md`
+const STATUS_PATH = `${DIR}/STATUS.json`
+const REPORT_PATH = `${DIR}/REPORT.md`
+const PROMPTS = typeof workflowDir === 'string' && workflowDir ? `${workflowDir}/prompts` : 'workflows/goal/prompts'
+
+const MAX = Math.max(1, Math.min(Number(args.max_iterations ?? 8), 50))
+const STALL = Math.max(2, Number(args.stall_rounds ?? 3))
+const INTERACTIVE = String(args.interactive ?? 'true') !== 'false'
+const objective = String(args.objective ?? '').trim()
+
+/** 读 prompt 模板并替换 {{占位符}}（用 {{}} 而非 ${}：模板里有 shell/JS 示例会撞）。 */
+async function prompt(name, vars = {}) {
+  const text = await readText(`${PROMPTS}/${name}.md`)
+  if (text === null) throw new Error(`读不到 prompt 模板：${PROMPTS}/${name}.md`)
+  let out = text
+  for (const [k, v] of Object.entries(vars)) {
+    out = out.split(`{{${k}}}`).join(String(v ?? ''))
+  }
+  return out
+}
+
+const bullets = (arr, empty = '（无）') =>
+  Array.isArray(arr) && arr.length ? arr.map((x) => `- ${x}`).join('\n') : empty
+
+/**
+ * 一条 check 的稳定标识。停滞指纹还会加入经过时间/耗时归一化的失败证据：
+ * 只看名字会误伤有进展的修复，只看原始输出又会被时间戳噪音干扰。
+ */
+function checkLabel(c) {
+  if (!c || typeof c !== 'object') return String(c)
+  switch (c.type) {
+    case 'shell':
+      return `shell:${c.command}`
+    case 'file_exists':
+      return `file_exists:${c.file}`
+    case 'file_contains':
+      return `file_contains:${c.file}:${c.pattern}`
+    case 'test_count':
+      return `test_count:${c.minCount}`
+    default:
+      return JSON.stringify(c)
+  }
+}
+
+/** 失败项与失败证据必须同时不变才算空转，避免“尚未全过但确有进展”的误判。 */
+function evidenceFingerprint(gate, failed) {
+  const stable = (value) => String(value ?? '')
+    .replace(/\b\d{4}-\d{2}-\d{2}[T ][0-9:.+-Z]+\b/g, '<time>')
+    .replace(/\b\d+(?:\.\d+)?(?:ms|s)\b/g, '<duration>')
+    .slice(0, 4000)
+  return JSON.stringify({
+    failed: failed.slice().sort(),
+    evidence: (gate.details ?? [])
+      .filter((detail) => !detail.passed)
+      .map((detail) => stable(detail.summary ?? detail.output ?? detail.error)),
+  })
+}
+
+const CONTRACT_SCHEMA = {
+  type: 'object',
+  required: ['restated_goal', 'deliverables', 'hard_checks', 'soft_criteria'],
+  properties: {
+    restated_goal: { type: 'string' },
+    deliverables: { type: 'array', items: { type: 'string' } },
+    hard_checks: { type: 'array', items: { type: 'string' }, minItems: 1 },
+    soft_criteria: { type: 'array', items: { type: 'string' } },
+    clarifications: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const AUDIT_SCHEMA = {
+  type: 'object',
+  required: ['achieved', 'evidence', 'blocking_reason', 'quality'],
+  properties: {
+    achieved: { type: 'boolean' },
+    evidence: { type: 'array', items: { type: 'string' } },
+    blocking_reason: { type: 'string' },
+    quality: {
+      type: 'object',
+      required: ['functionality', 'performance', 'usability', 'robustness', 'notes'],
+      properties: {
+        functionality: { type: 'number', minimum: 0, maximum: 10 },
+        performance: { type: 'number', minimum: 0, maximum: 10 },
+        usability: { type: 'number', minimum: 0, maximum: 10 },
+        robustness: { type: 'number', minimum: 0, maximum: 10 },
+        notes: { type: 'string' },
+      },
+    },
+  },
+}
+
+const READ_ONLY = ['Read', 'Glob', 'Grep', 'Bash']
+
+await sh(`mkdir -p ${DIR}`)
+
+// ══ 阶段 0：把目标固化成可验证的完成契约 ═══════════════════════════════
+let contract
+
+const preset = String(args.checks ?? '')
+  .split(',')
+  .map((c) => c.trim())
+  .filter(Boolean)
+
+if (preset.length > 0) {
+  // 用户自带退出条件 —— 这是 Codex 推荐的用法（目标自带可验证判据），直接开跑。
+  contract = {
+    restated_goal: objective,
+    deliverables: [],
+    hard_checks: preset,
+    soft_criteria: [],
+  }
+  log(`用户已给 ${preset.length} 条退出条件，跳过契约拟定`)
+} else {
+  contract = await llm(await prompt('contract', { objective }), {
+    label: '阶段0·拟定完成契约',
+    schema: CONTRACT_SCHEMA,
+    isolated: true, // 拟契约不需要看主线对话，也不该把草案污染进去
+  })
+
+  // ⚠️ 用**引擎自己的解析器**验格式，不要在这里再写一份正则 ——
+  //    `verify()` 遇到无法解析的 check 串会响亮抛错，正好拿来当校验器。
+  //    在契约阶段暴露，总好过第一轮迭代跑到一半才炸。
+  for (let fix = 0; fix <= 2; fix++) {
+    try {
+      await verify(contract.hard_checks)
+      break // 能解析就行，这次的通过与否不重要（此刻当然大概率不通过）
+    } catch (e) {
+      if (fix === 2) {
+        throw new Error(
+          `契约里的检查项格式反复不合法，放弃：${e.message}\n` +
+            '可以用 --input checks="shell:...,file_exists:..." 自己指定退出条件绕过这一步。',
+        )
+      }
+      log(`检查项格式不合法，第 ${fix + 1}/2 次让模型修正`)
+      contract = await llm(
+        `${await prompt('contract', { objective })}\n\n` +
+          `⚠️ 你上次给的 hard_checks 无法被解析：${e.message}\n` +
+          '请只用 shell: / file_exists: / file_contains: / test_count: 四种前缀重新给出完整契约。',
+        { label: `阶段0·修正检查项格式 #${fix + 1}`, schema: CONTRACT_SCHEMA, isolated: true },
+      )
+    }
+  }
+
+  // ── 澄清 + 确认闸门：**只在开头问这一次**，之后全程自主 ────────────
+  if (INTERACTIVE) {
+    const asks = Array.isArray(contract.clarifications) ? contract.clarifications.slice(0, 3) : []
+    const detail =
+      `📋 完成契约已拟定：\n\n【目标】${contract.restated_goal}\n\n` +
+      `【产出物】\n${bullets(contract.deliverables)}\n\n` +
+      `【必须通过的检查】(循环会真跑这些命令)\n${bullets(contract.hard_checks)}\n\n` +
+      `【只评估不阻塞的质量维度】\n${bullets(contract.soft_criteria)}\n` +
+      (asks.length ? `\n【我不确定的点】\n${bullets(asks)}\n` : '') +
+      '\n选「开始」进入自主循环；选「取消」放弃；选「其他」输入补充要求或修改检查项。'
+
+    const fb = await ask(detail, [
+      { label: '开始执行 (推荐)', description: '按此契约进入自主循环，中途不再打扰' },
+      { label: '取消', description: '不执行，现场保留' },
+    ])
+
+    if (fb.includes('取消')) {
+      throw new Error('用户在契约确认闸门取消（现场已保留，重跑同目标可断点续跑）')
+    }
+    if (!fb.includes('开始')) {
+      // 自由输入 = 补充要求。经 addGoalSupplement 贯穿后续每一次调用，
+      // 而不只是改一下这份契约文本 —— 用户的话要一直在场。
+      await addGoalSupplement(fb)
+      log('已记入用户补充要求，据此修订契约')
+      contract = await llm(
+        `${await prompt('contract', { objective })}\n\n` +
+          `⚠️ 用户看过契约草案后补充了要求，**必须实质采纳**：\n${fb}\n\n` +
+          `原草案：${JSON.stringify(contract)}\n\n请给出修订后的完整契约。`,
+        { label: '阶段0·按用户补充修订契约', schema: CONTRACT_SCHEMA, isolated: true },
+      )
+      try {
+        await verify(contract.hard_checks)
+      } catch (e) {
+        throw new Error(`按补充要求修订后的检查项格式不合法：${e.message}`)
+      }
+    }
+  }
+}
+
+const hardChecks = contract.hard_checks
+await syncManagedContract({
+  objective: contract.restated_goal,
+  deliverables: contract.deliverables,
+  acceptanceCriteria: [...contract.hard_checks, ...contract.soft_criteria],
+  // 预算挂在**版本化的契约**上：改预算 = 新契约版本、留痕。
+  // 而已消耗量挂在 Goal 上、累计不重置 —— 所以「加预算继续跑」是自然操作，
+  // 不会把已经花掉的偷偷清零。
+  tokenBudget: Number(args.token_budget) > 0 ? Number(args.token_budget) : null,
+})
+const contractMd =
+  `# 完成契约\n\n## 目标\n${contract.restated_goal}\n\n` +
+  `## 产出物\n${bullets(contract.deliverables)}\n\n` +
+  `## 确定性检查（停止条件）\n${bullets(hardChecks)}\n\n` +
+  `## 质量维度（只评估，不阻塞）\n${bullets(contract.soft_criteria)}\n`
+
+await tool('Write', { file_path: CONTRACT_PATH, content: contractMd })
+declareArtifact(CONTRACT_PATH)
+if (!(await exists(CONTRACT_PATH))) throw new Error(`契约写入后核实失败：${CONTRACT_PATH}`)
+
+echo(`📋 契约已固化（${hardChecks.length} 条确定性检查）→ ${CONTRACT_PATH}`)
+
+// ══ 阶段 1..N：执行 → 硬门 → 独立审计 ════════════════════════════════
+let status = 'pursuing'
+let audit = null
+let lastStatusText = '（第一轮，还没有历史）'
+let lastFailSig = null
+let stallCount = 0
+let iter = 0
+
+const deliverablesMd = bullets(contract.deliverables)
+const hardChecksMd = bullets(hardChecks)
+const softMd = bullets(contract.soft_criteria)
+
+for (iter = 1; iter <= MAX; iter++) {
+  // ── 预算闸：只在**开新一轮之前**求值 ──────────────────────────────
+  // 一轮一旦开始，中途超额也一路跑完到节点 —— 引擎内核完全不做预算检查，
+  // 这条纪律在脚本层也要守住：宁可超一点预算，也不能把 agent 停在半成品状态。
+  const money = await budget()
+  if (money.exhausted) {
+    status = 'budget_limited'
+    lastStatusText =
+      `token 预算已用尽（已花 ${money.used} / 上限 ${money.limit}），停在第 ${iter - 1} 轮结束处。\n` +
+      '现场已保留，加预算后用同一目标重跑即可从这里继续。'
+    log(lastStatusText)
+    break
+  }
+  if (money.limit !== null && !money.trustworthy) {
+    // 账偏低就如实说 —— 不能让用户以为「还剩很多」。
+    log('⚠️ 部分调用的 provider 没回报 usage，实际消耗高于账面数字。')
+  }
+
+  // 每轮干净上下文：长循环里带着前几十轮对话跑，模型会被旧上下文带偏。
+  // 契约本身每轮都重新拼进 prompt，所以截断不会丢关键信息。
+  resetContext()
+  log(`第 ${iter}/${MAX} 轮`)
+
+  await agent(
+    await prompt('iterate', {
+      iter: String(iter),
+      max: String(MAX),
+      restated_goal: contract.restated_goal,
+      deliverables: deliverablesMd,
+      hard_checks: hardChecksMd,
+      supplements: '',
+      last_status: lastStatusText,
+    }),
+    { label: `第 ${iter}/${MAX} 轮·执行`, maxTurns: 30 },
+  )
+
+  // ── 关 1：确定性硬门。引擎真跑命令，不问模型 ──────────────────────
+  const gate = await verify(hardChecks)
+  const failed = gate.details.filter((d) => !d.passed).map((d) => checkLabel(d.check))
+
+  // ── 无进展检测：失败集合与证据完全没变 = 这一轮白跑了 ──────────────
+  const sig = gate.passed ? '' : evidenceFingerprint(gate, failed)
+  if (sig && sig === lastFailSig) {
+    stallCount++
+    log(`无进展 ${stallCount}/${STALL}（失败项及证据与上轮完全相同）`)
+    if (stallCount >= STALL) {
+      status = 'stalled'
+      lastStatusText = `连续 ${STALL} 轮卡在同样的检查上：\n${bullets(failed)}`
+      break
+    }
+  } else {
+    stallCount = 0
+    lastFailSig = sig
+  }
+
+  if (!gate.passed) {
+    lastStatusText =
+      `第 ${iter} 轮结束时，这些检查**仍未通过**（这就是你这一轮要攻的）：\n${bullets(failed)}\n\n` +
+      `详细输出：\n${String(gate.summary ?? '').slice(0, 1500)}`
+    echo(`  ⏳ 第 ${iter} 轮：${hardChecks.length - failed.length}/${hardChecks.length} 项检查通过`)
+    continue
+  }
+
+  // ── 关 2：独立审计。isolated —— 看不见执行者说过什么，只能自己查 ────
+  echo(`  ✅ 第 ${iter} 轮：确定性检查全部通过，进入独立审计`)
+  audit = await agent(
+    await prompt('audit', {
+      restated_goal: contract.restated_goal,
+      deliverables: deliverablesMd,
+      hard_checks: hardChecksMd,
+      soft_criteria: softMd,
+      supplements: '',
+    }),
+    {
+      label: `第 ${iter} 轮·独立审计`,
+      allowedTools: READ_ONLY,
+      maxTurns: 20,
+      isolated: true,
+      schema: AUDIT_SCHEMA,
+    },
+  )
+
+  if (audit.achieved) {
+    status = 'achieved'
+    break
+  }
+
+  lastStatusText =
+    `第 ${iter} 轮：确定性检查全过了，但**独立审计判定目标未达成**：\n` +
+    `${audit.blocking_reason}\n\n` +
+    '⚠️ 注意：这说明检查项覆盖不全，或产出物存在但没有实质内容。' +
+    '这一轮要补的是审计指出的实质缺口，不是再让检查通过一遍。'
+  echo(`  ⚠️ 第 ${iter} 轮审计未通过：${audit.blocking_reason}`)
+}
+
+if (status === 'pursuing') status = 'max_iterations'
+
+// ══ 收尾：状态 + 四维质量报告 ════════════════════════════════════════
+// 这里是 Attempt 的兼容报告状态；Goal Runtime 才是生命周期事实源。
+const STATUS_TEXT = {
+  achieved: '✅ Agent 自检通过，等待人类验收',
+  stalled: '🔁 卡死（连续多轮无进展）',
+  max_iterations: '⏱ 轮数耗尽，目标未达成',
+  // ⚠️ 与 usage_limited 分工不同：这个是**用户自己设的额度**用完了（加预算即可续）；
+  // usage_limited 是**服务端配额/授权**不给了（要去解决授权，加预算没用）。
+  budget_limited: '💰 token 预算用尽，已停在轮次边界',
+}
+
+await tool('Write', {
+  file_path: STATUS_PATH,
+  content: `${JSON.stringify(
+    {
+      // 这个文件只报告本次 workflow Attempt；Goal 生命周期只能由
+      // GoalRuntime/GoalStore 写入，工作流不得猜测 ready_for_acceptance 或 blocked。
+      schemaVersion: 2,
+      status,
+      outcome: status,
+      authority: 'workflow-attempt',
+      attempt_outcome: status,
+      objective,
+      restated_goal: contract.restated_goal,
+      iterations_used: iter > MAX ? MAX : iter,
+      max_iterations: MAX,
+      hard_checks: hardChecks,
+      verification_passed: status === 'achieved',
+      quality: audit?.quality ?? null,
+      blocking_reason: status === 'achieved' ? '' : (audit?.blocking_reason ?? lastStatusText),
+    },
+    null,
+    2,
+  )}\n`,
+})
+declareArtifact(STATUS_PATH)
+
+const q = audit?.quality
+const qualityMd = q
+  ? `## 质量评估（不作为停止条件）\n\n` +
+    `| 维度 | 分数 |\n|---|---|\n` +
+    `| 功能完整度 | ${q.functionality}/10 |\n` +
+    `| 性能 | ${q.performance}/10 |\n` +
+    `| 易用性 | ${q.usability}/10 |\n` +
+    `| 鲁棒性 | ${q.robustness}/10 |\n\n${q.notes}\n`
+  : '## 质量评估\n\n未产出 —— 本次运行没有走到独立审计那一步（确定性检查从未全部通过）。\n'
+
+await tool('Write', {
+  file_path: REPORT_PATH,
+  content:
+    `# 目标执行报告\n\n**结果**：${STATUS_TEXT[status] ?? status}（用了 ${iter > MAX ? MAX : iter}/${MAX} 轮）\n\n` +
+    `## 目标\n${contract.restated_goal}\n\n` +
+    `## 契约\n${bullets(hardChecks)}\n\n` +
+    (audit?.evidence?.length ? `## 审计证据\n${bullets(audit.evidence)}\n\n` : '') +
+    (status === 'achieved' ? '' : `## 未达成原因\n${audit?.blocking_reason || lastStatusText}\n\n`) +
+    qualityMd,
+})
+declareArtifact(REPORT_PATH)
+
+echo(`\n${STATUS_TEXT[status] ?? status}（${iter > MAX ? MAX : iter}/${MAX} 轮）`)
+if (q) {
+  echo(
+    `   质量：功能 ${q.functionality} · 性能 ${q.performance} · ` +
+      `易用 ${q.usability} · 鲁棒 ${q.robustness}（满分 10，仅供参考不阻塞）`,
+  )
+  echo(`   ${q.notes}`)
+}
+if (status !== 'achieved') {
+  echo(`   ⚠️ ${audit?.blocking_reason || lastStatusText.split('\n')[0]}`)
+  echo('   现场已保留：修好阻塞点后用**同一个目标**重跑即可断点续跑。')
+}
+echo(`   报告：${REPORT_PATH}`)
+
+// 未达成时抛错，让宿主的退出码/结局契约如实反映"没做成"。
+// ⚠️ 这一步必须在所有落盘之后 —— 报告是排障的唯一线索，不能因为抛错而丢。
+if (status !== 'achieved') {
+  const err = new Error(`${STATUS_TEXT[status] ?? status}：${audit?.blocking_reason || '见 ' + REPORT_PATH}`)
+  // 用通用 Error 属性把结局标签交给 Runner 原样转发；Runner 不解释 Goal 业务。
+  // 给 bridge.finish()，由 Goal 侧按 statusMapping.ts::OUTCOME_TO_ATTEMPT 精化真实状态。
+  // 没有这一步，budget_limited 会被引擎的通用 catch 一律记成 'failed'，
+  // Goal 也永远到不了 budget_limited（只会落在语义完全不同的 blocked）。
+  err.workflowOutcome = status
+  throw err
+}
+
+return {
+  status: status === 'achieved' ? 'ready_for_acceptance' : 'blocked',
+  iterations: iter > MAX ? MAX : iter,
+  report: REPORT_PATH,
+  quality: q ?? null,
+  evidence: audit?.evidence ?? [],
+  contract,
+}
+}

package/workflows/illustrate/README.md

@@ -0,0 +1,90 @@
+# illustrate —— 网上抓图配图
+
+## 意图
+
+给一个主题词，从网上抓一批候选图，**用 LLM 逐张看图打分**（相关度 / 质量 / 是不是广告图），
+选出最合适的几张落成清单，供 PPT / 文章工作流直接消费。
+
+不是"搜索返回前 N 张"——搜索引擎前排常常是广告图、比价图、带店铺水印的图，
+直接拿来配图会很难看。识图打分那一步就是为了把它们剔掉。
+
+## 输入
+
+| 输入 | 必填 | 说明 |
+|---|:---:|---|
+| `topic` | ✅ | 配图主题/关键词（贪婪首参，可一句话自然语言） |
+| `count` | | 最终选出的张数，默认 3 |
+| `min_candidates` | | 候选下限，某家抓到少于这个数就降级到下一家，默认 6 |
+
+```bash
+/workflow illustrate 太空探索 科技感 蓝色 --input count=5
+```
+
+## ⚠️ 前置条件：浏览器 Developer Mode
+
+本工作流靠 `WebBrowser` 的 **`eval`** 从搜索结果页抽图 URL，而 `eval` 需要：
+
+1. 「设置 → 浏览器」里**开启 Developer Mode**；
+2. 把 `google.com` / `bing.com` / `image.baidu.com` 加进**站点白名单**。
+
+这是内核刻意的安全门禁，不是配置疏漏 —— `eval` 能在页面里执行任意 JS，
+严格强于其它调试动作，所以单独设了闸。
+
+没授权时的表现：`navigate` 会成功（页面打开了），但 `eval` 逐家失败，
+最终报「三家都没抓到候选图」并**列出每家的真实报错**，照着提示开授权即可。
+
+## 流程
+
+```
+阶段1-3 有序降级抓候选（Google → Bing → 百度，某家被墙/不够就换下一家）
+阶段4   逐条下载（死链/防盗链跳过，不阻断）
+阶段5   逐张识图打分（relevance / quality / is_ad）
+阶段6   确定性选优：剔广告 → relevance×quality 降序 → 取前 count
+```
+
+## 产物
+
+`out/illustrate/<session>/<task>/build/illustrations.json`：
+
+```json
+{
+  "topic": "…", "engine_used": "google", "count": 3,
+  "picks": [{ "path": "…/cand_3.img", "url": "…", "relevance": 9, "quality": 8, "reason": "…" }]
+}
+```
+
+下游工作流读 `picks[].path` 取图即可。
+
+## 目录结构
+
+```
+workflows/illustrate/
+├── workflow.mjs                主入口
+└── assets/
+    ├── engines.json            三家引擎配置（url 模板 + 抽取器文件名）
+    ├── extract-google.js       ← 页面改版时**只改这些**
+    ├── extract-bing.js
+    └── extract-baidu.js
+```
+
+**加一家搜索引擎** = 往 `engines.json` 加一个条目 + 写一个 `extract-*.js`，
+主脚本一行不用动。
+
+## 已知坑
+
+- **抽取器随页面改版必然失效**，这是固有脆弱、与工作流引擎无关。
+  失效的表现是"某家抓到 0 个候选"（日志里看得到），改对应的
+  `assets/extract-*.js` 即可 —— 这正是把它们拆成独立文件的理由。
+
+- **WebBrowser eval 的结果要 `parseJson` 两层**。抽取器里 `JSON.stringify(...)`
+  返回字符串，agent-browser 显示结果时又 JSON 编码了一次，于是收到的是
+  「带外层引号的双编码串」。少套一层会**静默**拿到字符串而不是数组，
+  后面 `.length` 变成字符数，降级判断全错。已实测确认。
+
+- **识图只能走 `images` 通道**。内核的 tool 结果是纯字符串，
+  `llm(prompt, { images: [...] })` 是让模型看见图的唯一方式。
+
+- **选优是确定性的，不要改回让 agent 做**。原 yaml 里这步是 `agent:` ——
+  让模型 Glob + Read 十几个 score 文件、心算 `relevance×quality` 再排序。
+  那是 DSL 表达不了数组排序的妥协，不是该让模型做的事：模型会算错乘积、
+  会漏剔广告图，而且结果不可复现。

package/workflows/illustrate/assets/engines.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "google",
+    "label": "Google 图片",
+    "url": "https://www.google.com/search?tbm=isch&hl=en&q={{query}}",
+    "extractor": "extract-google.js"
+  },
+  {
+    "id": "bing",
+    "label": "Bing 图片",
+    "url": "https://www.bing.com/images/search?q={{query}}",
+    "extractor": "extract-bing.js"
+  },
+  {
+    "id": "baidu",
+    "label": "百度图片",
+    "url": "https://image.baidu.com/search/index?tn=baiduimage&word={{query}}",
+    "extractor": "extract-baidu.js"
+  }
+]

package/workflows/illustrate/assets/extract-baidu.js

@@ -0,0 +1,21 @@
+JSON.stringify(
+  Array.from(
+    new Set(
+      Array.from(document.querySelectorAll('img')).map(
+        (image) =>
+          image.getAttribute('data-imgurl') ||
+          image.currentSrc ||
+          image.src ||
+          image.getAttribute('data-src') ||
+          '',
+      ),
+    ),
+  )
+    .filter(
+      (url) =>
+        /^https?:\/\//.test(url) &&
+        !/\.svg($|\?)/i.test(url) &&
+        !/baidu\.com\/(static|img|aladdin)|bdstatic\.com|w3\.org/i.test(url),
+    )
+    .slice(0, 24),
+)

package/workflows/illustrate/assets/extract-bing.js

@@ -0,0 +1,33 @@
+JSON.stringify(
+  Array.from(
+    new Set(
+      [].concat(
+        Array.from(document.querySelectorAll('a.iusc')).map((anchor) => {
+          try {
+            return JSON.parse(anchor.getAttribute('m') || '{}').murl || ''
+          } catch {
+            return ''
+          }
+        }),
+        Array.from(document.querySelectorAll('a')).map((anchor) => {
+          try {
+            const url = new URL(anchor.href)
+            return url.searchParams.get('mediaurl') || url.searchParams.get('imgurl') || ''
+          } catch {
+            return ''
+          }
+        }),
+        Array.from(document.querySelectorAll('img')).map(
+          (image) => image.currentSrc || image.src || image.getAttribute('data-src') || '',
+        ),
+      ),
+    ),
+  )
+    .filter(
+      (url) =>
+        /^https?:\/\//.test(url) &&
+        !/\.svg($|\?)/i.test(url) &&
+        !/bing\.com\/(rp|sa\/)|gstatic\.com|w3\.org/i.test(url),
+    )
+    .slice(0, 24),
+)