minimal-agent 0.12.0 → 0.14.0

package/workflows/research/workflow.mjs

@@ -0,0 +1,288 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    '六阶段技术深度调研：定义问题→测绘领域地图→候选方案对比→分支深度调研→动手验证→综合升华。产出含知识地图、对比矩阵、验证记录与最终建议的报告',
+  inputs: [
+    {
+      name: 'topic',
+      required: true,
+      greedy: true,
+      description: '要调研的技术主题/问题/领域（自然语言一句话，越具体越好）',
+    },
+    {
+      name: 'depth',
+      type: 'enum',
+      values: ['light', 'standard', 'deep'],
+      default: 'standard',
+      description: '调研深度（light=快速扫盲；standard=可用结论；deep=学术级深度）',
+    },
+    {
+      name: 'max_iterations',
+      type: 'number',
+      default: 2,
+      description: '综合阶段自检-补洞最大轮数（防无限递归）',
+    },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task, workflowDir } = wf.runtime
+const { agent } = wf.model
+const { shell: sh, file: execFile } = wf.exec
+const { readText, readJson, exists } = wf.fs
+const { ask } = wf.flow
+const { budget, resetModelContext: resetContext, addGoalSupplement } = 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) })
+
+// ============================================================
+//  自 research.yaml 迁移。本文件是**流程的目录** —— 细节下沉到：
+//    prompts/*.md          九段长 prompt（改措辞不用动代码，diff 干净）
+//    scripts/build-report.mjs  报告拼装（原 bash 用 sed/basename，Windows 上不可靠）
+//
+//  六阶段 + 两个可选分支：
+//    阶段0 定义问题 →（用户确认闸门）
+//    阶段1 测绘地图 →【提前退出判定】→ 是：简化报告直奔阶段6
+//    阶段2 方案对比 → 阶段3 逐分支深挖 → 阶段4 动手验证 → 阶段5 综合
+//    阶段5b 自检补洞循环（缺口清空即退出）
+//    阶段6 确定性拼装报告 + 精选脚本交付
+// ============================================================
+
+const DIR = `out/research/${session}/${task}`
+const REPORT = `${DIR}/deliverable/report.md`
+const PROMPTS = typeof workflowDir === 'string' && workflowDir ? `${workflowDir}/prompts` : 'workflows/research/prompts'
+
+/** 读 prompt 文件并填占位符。用 readText 而不是 tool('Read')：后者返回的是
+ *  给模型看的格式（每行带「行号+TAB」前缀），整段行号会跟着进 prompt。 */
+async function prompt(name, vars = {}) {
+  const raw = await readText(`${PROMPTS}/${name}.md`)
+  if (raw === null) throw new Error(`读不到 prompt 文件：${PROMPTS}/${name}.md`)
+  let text = raw
+  for (const [k, v] of Object.entries({ topic: args.topic, depth: args.depth, dir: DIR, ...vars })) {
+    text = text.split(`{{${k}}}`).join(String(v ?? ''))
+  }
+  return text
+}
+
+/**
+ * 跑一个阶段并核实它该产出的文件；没产出就有界 nudge。
+ * 这是脊梁规则的统一实现 —— 每个写文件的阶段都必须经它，不许直接 agent()。
+ */
+async function stage(label, promptText, outputs, opts = {}) {
+  let out = await agent(promptText, { label, maxTurns: opts.maxTurns ?? 25, ...opts })
+  for (let i = 1; i <= 2; i++) {
+    const missing = []
+    for (const f of outputs) if (!(await exists(f))) missing.push(f)
+    if (missing.length === 0) break
+    log(`${label}：还缺 ${missing.length} 个文件，第 ${i} 次提醒`)
+    out = await 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 exists(f))) still.push(f)
+  if (still.length > 0) {
+    throw new Error(`${label} 未能产出：${still.join('、')}`)
+  }
+  for (const f of outputs) declareArtifact(f)
+  return out
+}
+
+const RESEARCH_TOOLS = ['WebSearch', 'WebFetch', 'Read', 'Write', 'Bash', 'Glob']
+
+// ── 初始化：只 mkdir，不删任何文件 ──────────────────────────────────
+// 产物路径唯一且命名固定，子 agent 用 Write 覆盖本身就幂等；用 rm 反而会
+// 静默删掉用户预先放在这里的东西，也会撞上 Bash 的永久删除守卫。
+await sh(`mkdir -p ${DIR}/verify ${DIR}/deliverable/scripts`)
+
+// ── 阶段 0：定义问题 ────────────────────────────────────────────────
+await stage('阶段0/6·定义问题', await prompt('s0-goal'), [`${DIR}/01-goal.md`], {
+  allowedTools: ['Read', 'Write'],
+  maxTurns: 12,
+})
+// 澄清结论并入贯穿目标，后续每一步（含打回重来轮）都看得到
+await addGoalSupplement(`调研目标定义见 ${DIR}/01-goal.md`)
+
+// ── 用户确认闸门（非交互宿主自动选推荐项，不挂起）────────────────────
+const approval = await ask(
+  `已完成问题定义，请阅读 ${DIR}/01-goal.md。\n` +
+    '确认核心问题、范围边界、验收标准是否符合预期；要调整范围或补充要求就选「其他」输入，' +
+    '工作流会把它作为补充要求贯穿全程。',
+  [
+    { label: '继续执行 (推荐)', description: '按当前问题定义继续调研' },
+    { label: '停止', description: '中止本次运行；现场保留可续跑' },
+  ],
+)
+if (approval.includes('停止')) {
+  throw new Error('用户在问题定义确认闸门选择停止（现场已保留，重跑同目标可续跑）')
+}
+if (!approval.includes('继续执行') && approval.trim()) {
+  await addGoalSupplement(approval)
+  log('已把你的补充要求并入贯穿目标')
+}
+
+// ── 阶段 1：测绘领域地图 + 提前退出判定 ─────────────────────────────
+await stage(
+  '阶段1/6·测绘领域地图',
+  await prompt('s1-map'),
+  [`${DIR}/02-map.md`, `${DIR}/early-exit.json`],
+  { allowedTools: RESEARCH_TOOLS, maxTurns: 25 },
+)
+
+const exitJson = await readJson(`${DIR}/early-exit.json`)
+const earlyExit = exitJson?.early === true
+if (earlyExit) {
+  log(`提前退出：${exitJson?.reason ?? '（未给理由）'}`)
+}
+
+if (earlyExit) {
+  // ── 简化路径：一次补齐全套文件，让阶段6 的拼装无需分叉 ──────────────
+  await stage(
+    '简化路径·补齐全套文件',
+    await prompt('s1-early-exit'),
+    [
+      `${DIR}/03-options.md`,
+      `${DIR}/branches.json`,
+      `${DIR}/05-verification.md`,
+      `${DIR}/06-synthesis.md`,
+      `${DIR}/07-learning-debt.md`,
+      `${DIR}/gaps.json`,
+    ],
+    { allowedTools: ['Read', 'Write'], maxTurns: 12 },
+  )
+} else {
+  // ── 阶段 2：候选方案对比 ──────────────────────────────────────────
+  await stage(
+    '阶段2/6·候选方案对比',
+    await prompt('s2-options'),
+    [`${DIR}/03-options.md`, `${DIR}/branches.json`],
+    { allowedTools: RESEARCH_TOOLS, maxTurns: 25 },
+  )
+
+  const branches = await readJson(`${DIR}/branches.json`)
+  if (!Array.isArray(branches) || branches.length === 0) {
+    throw new Error(
+      `未能从 ${DIR}/branches.json 读到任何深度调研分支（JSON 格式错误或数组为空）`,
+    )
+  }
+
+  // ── 阶段 3：逐分支深挖。每轮重置上下文，分支之间互不干扰 ────────────
+  for (const [i, branch] of branches.entries()) {
+    resetContext()
+    const safe = String(branch.safe_name ?? `branch-${i + 1}`).replace(/[^\w.-]/g, '-')
+    await stage(
+      `阶段3/6·深挖「${branch.name ?? safe}」`,
+      await prompt('s3-deep-dive', {
+        branchName: branch.name ?? safe,
+        branchDesc: branch.description ?? '（未给描述，按分支名自行判断）',
+        safeName: safe,
+      }),
+      [`${DIR}/04-deep-dive-${safe}.md`],
+      { allowedTools: RESEARCH_TOOLS, maxTurns: 30 },
+    )
+  }
+
+  // ── 阶段 4：动手验证 ─────────────────────────────────────────────
+  resetContext()
+  await stage('阶段4/6·动手验证', await prompt('s4-verify'), [`${DIR}/05-verification.md`], {
+    allowedTools: ['Bash', 'Read', 'Write', 'Glob', 'WebSearch', 'WebFetch'],
+    maxTurns: 25,
+  })
+
+  // ── 阶段 5：综合升华 ─────────────────────────────────────────────
+  resetContext()
+  await stage(
+    '阶段5/6·综合结论',
+    await prompt('s5-synthesis'),
+    [`${DIR}/06-synthesis.md`, `${DIR}/07-learning-debt.md`, `${DIR}/gaps.json`],
+    { allowedTools: ['Read', 'Write', 'Glob', 'WebSearch', 'WebFetch'], maxTurns: 20 },
+  )
+
+  // ── 阶段 5b：自检补洞循环，缺口清空即退出 ──────────────────────────
+  const maxRounds = Number(args.max_iterations ?? 2)
+  for (let round = 1; round <= maxRounds; round++) {
+    // 预算闸只在开新一轮之前判 —— 补洞循环是本工作流里唯一「不断开新一轮」的地方，
+    // 前面那些 for 都是按数据项遍历（有界，不会失控），不需要也不该加。
+    const money = await budget()
+    if (money.exhausted) {
+      echo(`\n💰 token 预算已用尽（已花 ${money.used} / 上限 ${money.limit}），补洞循环停在第 ${round - 1} 轮。`)
+      echo('已产出的部分完好；加大预算后重跑可从断点继续。')
+      break
+    }
+    const gaps = await readJson(`${DIR}/gaps.json`)
+    if (!Array.isArray(gaps) || gaps.length === 0) {
+      echo('✅ 自检无缺口，补洞循环结束。')
+      break
+    }
+    resetContext()
+    log(`补洞第 ${round}/${maxRounds} 轮，待补 ${gaps.length} 条`)
+    await agent(
+      await prompt('s5b-fill-gaps', {
+        round: String(round),
+        gaps: gaps.map((g) => `- ${g}`).join('\n'),
+      }),
+      {
+        label: `阶段5b·补洞第 ${round}/${maxRounds} 轮`,
+        allowedTools: RESEARCH_TOOLS,
+        maxTurns: 20,
+      },
+    )
+  }
+}
+
+// ── 综合报告形式校验：确定性，不依赖 agent 自觉 ─────────────────────
+// 「核心结论」兼容两种表述：prompt 要求的字面 + agent 改写时常见的
+// 「核心问题的一句话答案」（实战中补洞轮曾改写标题导致误判 halt）。
+const synth = await sh(
+  `grep -E '^#+ .*(核心结论|核心问题的一句话答案|推荐方案)' ${DIR}/06-synthesis.md || true`,
+)
+const hasConclusion = /核心结论|一句话答案/.test(synth.stdout)
+const hasRecommend = synth.stdout.includes('推荐方案')
+if (!hasConclusion || !hasRecommend) {
+  throw new Error(
+    `${DIR}/06-synthesis.md 缺少「核心结论」或「推荐方案」章节 —— ` +
+      '综合报告没有直接回答核心问题，不允许进入拼装。',
+  )
+}
+
+// ── 阶段 6：确定性拼装最终报告 ──────────────────────────────────────
+const built = await execFile('./scripts/build-report.mjs', [DIR, String(args.depth ?? 'standard')])
+if (built.exitCode !== 0) {
+  throw new Error(`报告拼装失败：${built.stderr || built.stdout}`)
+}
+if (!(await exists(REPORT))) {
+  throw new Error(`报告拼装脚本报告成功，但 ${REPORT} 不存在`)
+}
+declareArtifact(REPORT)
+
+// ── 阶段 6：精选验证脚本交付（失败不阻断，报告已经在手）──────────────
+try {
+  await stage(
+    '阶段6/6·精选脚本交付',
+    await prompt('s6-package'),
+    [`${DIR}/deliverable/scripts/README.md`],
+    { allowedTools: ['Read', 'Write', 'Bash', 'Glob'], maxTurns: 12 },
+  )
+} catch (e) {
+  log(`精选交付降级（不阻断，报告已生成）：${e.message}`)
+}
+
+// ── 收尾 ───────────────────────────────────────────────────────────
+const remaining = await readJson(`${DIR}/gaps.json`)
+const gapCount = Array.isArray(remaining) ? remaining.length : 0
+
+echo(`✅ 技术调研完成\n\n主题：${args.topic}\n深度：${args.depth ?? 'standard'}`)
+echo(
+  gapCount > 0
+    ? `⚠️ 补洞循环达上限退出，仍有 ${gapCount} 条缺口未补全（见 ${DIR}/gaps.json 与 06-synthesis.md 的「调研局限」），结论使用时注意置信度。`
+    : '✅ 调研缺口已全部收敛。',
+)
+echo(`★ 请直接阅读汇总报告：${REPORT}\n  过程产物在 ${DIR}/，精选脚本在 ${DIR}/deliverable/scripts/`)
+
+return { report: REPORT, dir: DIR, remainingGaps: gapCount, earlyExit }
+}

package/workflows/wechat-reading-shots/prompts/collect-params.md

@@ -0,0 +1,16 @@
+本次任务需要三个参数。**已经给了的直接用，只问缺的那些**：
+
+    书名     book       = 「{{book}}」   （空字符串 = 未提供）
+    起始页   start_page = {{startPage}}  （0 = 未提供）
+    截图张数 shots      = {{shots}}      （0 = 未提供）
+
+有缺失就用 **AskUserQuestion 一次性问清所有缺的项**（不要一项一项分多轮问）。
+给选项的同时也允许自由输入：起始页给 1 / 12 / 50 之类，张数给 5 / 10 / 20 之类。
+
+三项都齐了就**不要问任何问题**，直接输出结果。
+
+最后**只回复一行 JSON**，不要任何解释、不要代码块围栏：
+
+```
+{"book":"书名","page":起始页数字,"shots":张数数字}
+```

package/workflows/wechat-reading-shots/prompts/evaluate.md

@@ -0,0 +1,20 @@
+评估**这次自动化跑得成不成功**（不是评估书的内容）。
+
+本次流程：打开《{{book}}》正文 → 翻到第 {{targetPage}} 页（落点 {{landing}}）→
+循环 {{shots}} 次「截图 + 翻页」，实际拍了 {{actualShots}} 张。
+
+observe 一次（用说明书的 `read_page_number` 流程读清当前页码），结合过程中看到的
+截图，如实回答：
+
+1. 打开的确实是《{{book}}》吗？依据是什么？
+2. 截图是否都是**不同**的页面？依据是每次翻页回执里的变化率（0.0% = 没翻动）。
+3. 过程中有没有误触？（弹出菜单、放大插图、跳转别的界面、触发购买/分享）
+4. 当前停在第几页？用放大镜读出来的真实数字，不要猜。
+
+要求：
+
+- 每条结论都要说清依据，不要笼统说"成功"
+- 拿不准就明说拿不准
+- **不要凭记忆报按键次数或截图张数** —— 那两个数字上面已经给你了，
+  它们由引擎的循环结构保证，比你的记忆可靠
+- 最后一句总评：成功 / 部分成功 / 失败，以及卡在哪一步

package/workflows/wechat-reading-shots/prompts/open-book.md

@@ -0,0 +1,28 @@
+把微信读书弄到《{{book}}》的**正文页**。
+
+判据只有一条：**能读出页码**（形如「N / 总数」）。读得到就算完成。
+读页码的方法、界面各处的位置、遇到奇怪界面怎么退回去 —— 说明书里都有，
+它的摘要就在你每次 observe 的回执里，照着做。
+
+⛔ **这一步只负责「打开到正文页」，到此为止。**
+**不要**去翻到第几页 —— 说明书里那条 seek_to_page 流程不归你执行，
+下一步由引擎驱动，它会先读页码再决定翻多少。你在这里翻页只会把落点搞乱。
+**一旦读到页码，立刻回 OPEN=ok 结束本步**，一个多余动作都不要做。
+（实测教训：这一步曾自作主张把书翻到目标页，干了 4 分钟、还忘了给结论行，
+整条工作流因为「没有产出任何结果」而 halt。）
+
+纪律：
+
+- 第一个动作必须是 observe，先看清在哪再决定做什么
+- 只读任务：不点购买 / 订阅 / 分享 / 赠一得一 / 加入书架
+- **搜索结果里出现多本书名高度相似的书时（这在本应用里非常常见），
+  不要自己挑 —— 用 AskUserQuestion 把候选的完整书名 + 作者列给用户确认。**
+  点错书的代价是后面全部十几张截图都白拍。
+- 操作飞到了不认识的界面：按说明书的 back_to_home 流程复位。
+  **别在原地反复试**，也别用鼠标去正文里乱点。
+- 其它卡住、拿不准的地方一样用 AskUserQuestion 问，不要瞎试
+
+⚠️ 无论过程如何，**最后一行必须是下面两者之一**，缺了这行整步算失败：
+
+- 已停在能读到页码的正文页 → `OPEN=ok`
+- 试过各种办法仍进不去     → `OPEN=fail`

package/workflows/wechat-reading-shots/prompts/read-page.md

@@ -0,0 +1,13 @@
+只做一件事：**读出当前页码**。不要翻页，不要点任何东西。
+
+方法见说明书的 `read_page_number` 流程（摘要就在你每次 observe 的回执里）。
+
+**只回复一行**，格式严格如下，不要任何解释：
+
+```
+PAGE=<左页码> <右页码>
+```
+
+例：`PAGE=84 85`；单页显示时两个写一样：`PAGE=12 12`。
+
+实在读不出来就回复：`PAGE=0 0`

package/workflows/wechat-reading-shots/prompts/turn-batch.md

@@ -0,0 +1,24 @@
+当前页码：{{curPage}}   目标页：{{targetPage}}
+
+照这三步做，**不要自由发挥**：
+
+① 取当前左页码 L —— 就是 `{{curPage}}` 里的第一个数字
+
+② 方向 = L > {{targetPage}} 时用 `left`，否则用 `right`
+   N（还要按几次）= 向上取整( |L − {{targetPage}}| ÷ 2 )
+   （每次按键翻几页由说明书 `seek_to_page` 给出，别自己假设）
+
+③ 按 N 发**一次**工具调用，然后立刻结束本步：
+   - N ≥ 5 → `{action:"key", key:"<方向>", repeat:<min(N,8)>, repeatFrames:"last"}`
+   - N ≤ 4 → `{action:"key", key:"<方向>"}`
+
+⛔ **N ≥ 5 时必须用 repeat 一次发满，不许一下一下按。**
+   一下一下按，每按一次都要多花一个完整的 LLM 往返（约 30 秒），
+   而 repeat 一轮就干完（约 1 秒）—— 实测 N=6 时一次一按比批量多花了 5 分钟。
+   `repeatFrames:"last"` 也必须带上：不带的话 `repeat:8` 会回 8 张全屏图
+   （约 1 万 token），而中间那些页你根本不看。
+
+⛔ 发完就结束本步。不要自己循环、不要自己再 observe 确认 ——
+   外层引擎下一轮会先重新读页码，那才是权威值。
+
+⛔ 全程零鼠标。