minimal-agent 0.13.0 → 0.14.0

package/workflows/ralph-loop/workflow.mjs

@@ -0,0 +1,162 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    'Ralph Wiggum 迭代开发循环：重复执行同一目标直到完成。状态机 PLAN→BUILD→VERIFY/HEAL→DONE + 哨兵协议 + 验证门',
+  inputs: [
+    {
+      name: 'goal',
+      required: true,
+      greedy: true,
+      description: '不可变目标描述（可一句话自然语言，不会被空格拆碎）',
+    },
+    {
+      name: 'max_iterations',
+      type: 'number',
+      default: 50,
+      description: '最大迭代次数（安全阀）',
+    },
+    {
+      name: 'verify_checks',
+      default: '',
+      description:
+        "验证门检查项，逗号分隔（如 'shell:bun test,file_exists:src/index.ts'）。空则跳过验证门",
+    },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { agent } = wf.model
+const { call: tool } = wf.tools
+const { verify } = wf.check
+const { budget, resetModelContext: resetContext } = wf.state
+const echo = wf.output.message
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// 自 ralph-loop.yaml 迁移（201 行 → 约 90 行）。
+// 原 yaml 里这些 DSL 机制在代码形态下的对应物：
+//   type:set × 6          → JS 变量赋值
+//   type:loop + max_iter  → for 循环
+//   fresh_context: true   → resetContext()
+//   type:branch × 4       → if / else if
+//   type:break × 2        → 原生 break
+//   extract(…, 正则)      → String.matchAll
+//   ${a ? b : c} 插值     → 模板串里的三元
+// 引擎因此不需要 set / loop / branch / break / extract / 插值引擎这六样东西。
+
+const MAX = Math.min(Number(args.max_iterations ?? 50), 200)
+
+/** 哨兵：完整标签精确匹配。裸词 'need_replan' 会被 agent 复述协议说明时误触。 */
+const has = (text, tag) => text.toLowerCase().includes(`<promise>${tag}</promise>`)
+
+let phase = 'PLAN'
+/** 教训存在**变量**里而不是文件里：曾用「Write + 每轮 Read 回读」，Read 输出带
+ *  行号/空文件标记，逐轮把格式垃圾累积进档案。文件只作事后排查的存档副本。 */
+const learnings = []
+
+let iter = 0
+for (iter = 1; iter <= MAX; iter++) {
+  // 预算闸：只在**开新一轮之前**判。一轮一旦开始，中途超额也一路跑完到节点 ——
+  // 宁可超一点预算，也不能把 agent 停在半成品状态（引擎内核同样一行预算检查都没有）。
+  const money = await budget()
+  if (money.exhausted) {
+    echo(`\n💰 token 预算已用尽（已花 ${money.used} / 上限 ${money.limit}），停在第 ${iter - 1} 轮结束处。`)
+    echo('现场已保留；加大预算后用同一任务重跑即可从这里继续。')
+    break
+  }
+
+  // 每轮从干净的入口快照起步：长循环里带着前几十轮对话跑，模型会被旧上下文带偏
+  resetContext()
+  log(`第 ${iter}/${MAX} 轮 · ${phase}`)
+
+  const guidance = {
+    PLAN: '分析任务、拆解步骤、识别风险与未知项；先想清楚再动手。',
+    BUILD: '按计划实现，一次只聚焦一个子任务，落到具体文件改动。',
+    VERIFY: '运行测试/检查输出/核对验收标准，用证据确认，别凭感觉。',
+    HEAL: '已多次验证失败：停止猜测，定位根因再修，避免回归。',
+  }[phase] ?? '目标已达成。'
+
+  const output = await agent(
+    `# 不可变目标 (IMMUTABLE GOAL)
+${args.goal}
+⚠️ 你不能修改或扩大上述目标。
+
+# 当前阶段: ${phase}
+${guidance}
+
+# 与循环驱动的通信协议（务必逐字遵守标签格式）
+- 任务**真正完成**时输出 \`<promise>DONE</promise>\`（驱动会运行验证门）
+- 当前方案走不通、要换打法时输出 \`<promise>NEED_REPLAN</promise>\`（回 PLAN）
+- **目标本身**有问题时输出 \`<promise>NEED_GOAL_REVISION</promise>\`（干净终止）
+- 踩到的坑用 \`<learning>一句话</learning>\` 标记（驱动自动存档供后续参考）
+⚠️ 切勿为逃出循环而谎报完成 —— 只有陈述完全为真时才输出完成哨兵。
+${learnings.length ? `\n# 关键教训（必须遵守，避免重复踩坑）\n- ${learnings.join('\n- ')}` : ''}
+
+---
+本轮任务 (迭代 ${iter})`,
+    { label: `${phase} 第 ${iter} 轮`, maxTurns: 15 },
+  )
+
+  // 确定性提取教训：曾用 llm 步提取，模型会改写/漏抄/编造，档案被污染
+  for (const m of String(output).matchAll(/<learning>(.*?)<\/learning>/gs)) {
+    const t = m[1].trim()
+    if (t && !learnings.includes(t)) learnings.push(t)
+  }
+
+  if (has(output, 'done')) {
+    // 验证门：模型说完成了不算数
+    if (args.verify_checks) {
+      const checks = String(args.verify_checks)
+        .split(',')
+        .map((c) => c.trim())
+        .filter(Boolean)
+      const gate = await verify(checks)
+      if (!gate.passed) {
+        log(`验证未通过，回到 BUILD 继续：${gate.summary}`)
+        phase = 'BUILD'
+        continue
+      }
+    }
+    phase = 'DONE'
+    break
+  }
+
+  if (has(output, 'need_goal_revision')) {
+    phase = 'GOAL_REVISION'
+    break
+  }
+
+  if (has(output, 'need_replan')) {
+    phase = 'PLAN'
+  } else if (phase === 'PLAN' && !String(output).includes('<promise>')) {
+    // 自动推进：只在本轮没有任何流程哨兵时。learning 标签不算流程哨兵。
+    phase = 'BUILD'
+  }
+}
+
+// 教训存档（事后排查用；失败不影响结论）
+if (learnings.length) {
+  const archive = `.minimal-agent-workflow/ralph-loop/learnings.md`
+  try {
+    await tool('Write', {
+      file_path: archive,
+      content: `# ralph-loop 教训档案\n\n- ${learnings.join('\n- ')}\n`,
+    })
+  } catch (e) {
+    log(`教训存档写入失败（不影响结论）：${e.message}`)
+  }
+}
+
+const verdict =
+  phase === 'DONE'
+    ? `✅ 目标达成（${iter} 轮）`
+    : phase === 'GOAL_REVISION'
+      ? `⚠ 目标本身需要修订，已干净终止（${iter} 轮）`
+      : `⏹ 达到迭代上限 ${MAX} 轮仍未完成`
+
+echo(verdict)
+if (learnings.length) echo(`本轮累积教训 ${learnings.length} 条`)
+
+return { phase, iterations: iter, learnings }
+}

package/workflows/research/README.md

@@ -0,0 +1,74 @@
+# research —— 六阶段技术深度调研
+
+## 意图
+
+把「调研一个技术主题」这件事从「问一次 LLM 拿一段话」升级成**有过程、有证据、有边界**的调研：
+每个阶段的产出都落盘，关键论断要动手验证，结论要标证据等级，搞不清楚的必须诚实说出来。
+
+## 输入
+
+| 输入 | 必填 | 说明 |
+|---|:---:|---|
+| `topic` | ✅ | 要调研的技术主题/问题（贪婪首参，一句自然语言即可，不会被空格拆碎） |
+| `depth` | | `light`（快速扫盲）/ `standard`（默认，可用结论）/ `deep`（学术级） |
+| `max_iterations` | | 自检补洞的最大轮数，默认 2 |
+
+```bash
+/workflow research 时序数据库选型该怎么做 --input depth=deep
+```
+
+## 流程
+
+```
+阶段0 定义问题（零搜索，防锚定偏差）
+  └─ 用户确认闸门（可补充要求，并入贯穿目标）
+阶段1 测绘领域地图 ─→【提前退出判定】─→ 是：简化报告，直奔阶段6
+  └─ 否
+阶段2 候选方案对比（产出 branches.json 驱动下一阶段）
+阶段3 逐分支深挖（每分支一个文件，每轮 resetContext 互不干扰）
+阶段4 动手验证（只验证「假的话结论会变」的关键论断）
+阶段5 综合升华（结论标证据等级）
+  └─ 阶段5b 自检补洞循环（缺口清空即退出）
+阶段6 确定性拼装报告 + 精选验证脚本交付
+```
+
+## 产物
+
+全部落在 `out/research/<session>/<task>/` 下：
+
+| 文件 | 内容 |
+|---|---|
+| `deliverable/report.md` | ★ **汇总报告，先读这个** |
+| `deliverable/scripts/` | 精选验证脚本 + README 清单 |
+| `01-goal.md` … `07-learning-debt.md` | 各阶段过程产物 |
+| `branches.json` / `gaps.json` / `early-exit.json` | 驱动控制流的机器可读文件 |
+| `verify/` | 全部验证脚本（含失败尝试，过程保留不交付） |
+
+## 目录结构
+
+```
+workflows/research/
+├── workflow.mjs                 主入口 —— 读起来是流程的目录
+├── prompts/*.md                 九段长 prompt（改措辞不用动代码）
+└── scripts/build-report.mjs     报告拼装（可单独跑，见下）
+```
+
+调报告格式时不用跑整条工作流：
+
+```bash
+node <workflowDir>/scripts/build-report.mjs out/research/<session>/<task> standard
+```
+
+## 已知坑
+
+- **阶段0 禁止搜索**是有意的。一旦搜索，agent 会用「搜到的东西」定义问题，
+  而不是用户真正想解决的问题 —— 引入锚定偏差。摸底是阶段1的职责。
+- **验证脚本只能是 `.ts` / `.js`**。本系统基于 bun/node，**不保证有 Python 环境**；
+  写了 `pip install` 的脚本必然跑不起来，白白烧掉时间预算。
+- **`06-synthesis.md` 的「一、核心结论」「二、推荐方案」标题字面不能改** ——
+  阶段5c 有确定性 grep 校验。补洞轮曾改写标题导致误判 halt，所以 prompt 里
+  和这里都写死了这条。
+- **「不可补」的缺口必须清出 `gaps.json`**。信息根本不可得的东西留在里面，
+  只会让补洞循环空转到上限，还让用户以为「还有洞没补」。
+- 报告拼装会把子文档标题降两级。**代码块里顶格的 `# 注释` 也会被降级** ——
+  纯视觉影响，不改语义，已知取舍。

package/workflows/research/prompts/s0-goal.md

@@ -0,0 +1,43 @@
+你是一名资深技术研究员，现在启动六阶段技术调研流程的【阶段0：定义问题】。
+
+## 调研主题
+{{topic}}
+
+## 调研深度
+{{depth}}（light=快速扫盲 / standard=可用结论 / deep=学术级深度）
+
+## 你的任务
+
+**本阶段禁止任何搜索**（WebSearch/WebFetch 都不允许）—— 目标澄清靠分析用户请求本身，
+不是靠了解主题。一旦搜索，你会用「搜到的东西」定义问题，而不是用「用户真正想解决的问题」，
+引入锚定偏差。摸底是阶段1的职责。
+
+基于用户的主题描述和你的常识，输出结构化的问题定义文档：
+
+1. 把「主题词」转化为「问题句」：一句话描述要回答的具体问题
+   （不是"研究一下 A"，而是"针对什么场景，A 类方案该怎么选/值不值得投入，为什么"）。
+2. 只澄清决定「哪个方案适配」的隐藏变量：目标、交付物形态、场景约束、已知信息。
+   **严禁预设或询问具体技术方案** —— 方案选择是本次研究的产出，不是输入。
+3. **必须用 Write 工具把结果写入 `{{dir}}/01-goal.md`**，含以下章节（`##` 二级标题）：
+
+   ## 一、核心问题
+   一句话描述这次调研要回答的核心问题。
+
+   ## 二、背景与动机
+   为什么这个问题值得研究？典型应用场景是什么？
+
+   ## 三、范围与边界
+   - **包含**：本次调研要覆盖的子话题/子问题（3-7 个）
+   - **不包含**：明确排除的内容（防止范围蔓延）
+   - **目标读者**：谁会看这份调研报告
+
+   ## 四、验收标准
+   满足哪些条件才算「调研清楚了」？（3-5 条可判定的标准）
+
+   ## 五、待澄清问题
+   对用户需求不清楚的地方（技术选型偏好、规模要求、时间约束等）列在这里；没有就写「无」。
+
+## 约束
+- **本阶段零搜索、零方案预设**，只做目标澄清。
+- 必须写文件 `{{dir}}/01-goal.md`，不要只在对话里输出。
+- 中文，Markdown 格式。

package/workflows/research/prompts/s1-early-exit.md

@@ -0,0 +1,22 @@
+地图阶段已判定「提前退出」（`{{dir}}/early-exit.json` 里记录了原因）。
+
+你的任务：跳过深挖/验证/综合阶段，直接产出简化版全套文件，保证最终报告可拼装。
+
+请先 Read `{{dir}}/01-goal.md` 和 `{{dir}}/02-map.md`。
+
+## 必须用 Write 写入以下全部文件
+
+1. `{{dir}}/03-options.md` —— 写明「已提前退出，未做方案对比」+ 退出原因 +
+   地图层面看到的候选方向简述（若有）。
+2. `{{dir}}/branches.json` —— 内容 `[]`（空数组）。
+3. `{{dir}}/05-verification.md` —— 写明「已提前退出，未做动手验证」+ 原因。
+4. `{{dir}}/06-synthesis.md` —— 基于 01-goal 的问题定义和 02-map 的地图直接给结论，
+   **必须包含「一、核心结论」和「二、推荐方案」两个章节**（标题字面一个字都不能改，
+   下游有确定性校验按关键词 grep 它们）；给不出的诚实标注「信息不足，需全流程调研」。
+5. `{{dir}}/07-learning-debt.md` —— 记录因提前退出未覆盖的问题清单
+   （每条：问题 + 为什么值得后续研究 + 建议入口）。
+6. `{{dir}}/gaps.json` —— 内容 `[]`（简化路径不进补洞循环）。
+
+## 约束
+- 全部文件中文（JSON 除外），JSON 严格合法。
+- **诚实第一**：简化报告的价值在于明确说出「哪些没做、为什么」，而不是硬凑结论。

package/workflows/research/prompts/s1-map.md

@@ -0,0 +1,58 @@
+你正在执行六阶段技术调研的【阶段1：测绘领域地图】。
+
+调研主题：{{topic}}
+调研深度：{{depth}}
+
+请先 Read `{{dir}}/01-goal.md` 了解已定义的问题、范围和验收标准。
+
+## 你的任务
+快速扫描领域全貌，画出「知识地图」：
+
+1. **WebSearch 搜索 5-8 次**，不同关键词组合（中英文都试）：
+   overview / survey / tutorial、awesome-list 或 github topics、comparison / alternatives、
+   wikipedia / 官方文档 / 权威博客。
+2. **WebFetch 精读 3-5 个核心入口页面**（官网/综述/awesome-list 优先），提取领域结构。
+3. 不要陷进任何一个具体技术细节 —— 目标是建立「全景图」。
+
+## 输出要求
+**必须用 Write 写入 `{{dir}}/02-map.md`**，含：
+
+## 一、领域一句话定义
+## 二、发展历程（时间线）
+关键里程碑：起源年份、主要版本/突破、当前状态。5-10 个节点。
+## 三、核心概念与术语
+5-15 个关键术语，每个一句话解释，按重要性排序。
+## 四、生态/子领域划分
+主要分支/子方向/派系的树形分类。
+## 五、关键人物/组织/项目
+5-10 个主要推动者。
+## 六、核心资源索引
+5-10 个最值得读的资源，格式 `- [名称](URL) — 一句话说明为什么值得读`。
+## 七、初印象：主流方向与争议点
+目前主流做法是什么？有哪些主要争议/分歧/开放问题？
+
+## 八、提前退出判定（early-exit check）
+判断这次调研是否需要走完整六阶段：
+
+- **硬性规则**：若「生态/子领域划分」识别出 **≥3 个候选方案/流派**，必须判定
+  `early=false`（领域有实质结构，值得全流程），不得以「主题简单」为由偷懒退出。
+- 仅当以下情况才允许 `early=true`：
+  - 领域公开资料极少（可靠来源 < 3 个）；
+  - 或主题足够简单（一份官方 quickstart 即可完整回答核心问题）；
+  - 或地图层面已能直接给出结论。
+
+**同时必须用 Write 写入 `{{dir}}/early-exit.json`**（严格合法 JSON）：
+
+```json
+{"early": true, "reason": "一句话理由"}
+```
+或
+```json
+{"early": false}
+```
+
+## 约束
+- WebSearch 总次数 ≤ 10，不要无止境搜索。
+- 不做方案对比 —— 那是下一阶段的事。
+- 关键事实/论断后附来源链接 `- [来源](URL)`（可信度要能从源头追溯）。
+- 中文 Markdown。

package/workflows/research/prompts/s2-options.md

@@ -0,0 +1,53 @@
+你正在执行六阶段技术调研的【阶段2：候选方案对比】。
+
+调研主题：{{topic}}
+调研深度：{{depth}}
+
+请先 Read：
+- `{{dir}}/01-goal.md`（问题定义与验收标准）
+- `{{dir}}/02-map.md`（领域地图）
+
+## 你的任务
+在地图基础上，识别出解决这个问题的 **3-5 个主要候选方案/技术路线**，做系统对比。
+
+1. 确定 3-5 个最值得比较的候选方案（light 可只列 2-3 个；standard/deep 列 3-5 个并覆盖主要分支）。
+2. 每个方案做 1-3 次针对性 WebSearch/WebFetch 补充关键事实（性能指标、成熟度、社区活跃度等）。
+3. 发现阶段1 地图遗漏了重要分支时，本阶段可补充搜索。
+
+## 输出要求：**两个文件缺一不可**
+
+### 文件1：`{{dir}}/03-options.md`（人读的对比报告）
+
+## 一、候选方案清单
+每个方案是什么、由谁主导/维护、定位是什么。
+
+## 二、对比矩阵
+Markdown 表格（维度按领域特性增删）：核心思路 / 成熟度·生态 / 性能·规模 / 学习曲线 /
+适用场景 / 不适用场景 / 社区活跃度 / 许可证·成本。
+
+关键数据格**必须标注来源**（格内 `[来源](URL)` 或表下方集中列）；
+某维度缺乏公开可靠信息时明确写「信息不足」，**不要编造或用弱相关信息强行填充**。
+
+## 三、初步判断
+哪些方案值得在阶段3深入调研？列 2-4 个深度调研分支，每个配 1-2 句理由。
+
+### 文件2：`{{dir}}/branches.json`（机器读的分支列表，驱动阶段3 逐分支深挖）
+
+```json
+[
+  {
+    "name": "分支显示名（中文，如「FFmpeg 命令行方案」）",
+    "safe_name": "分支短标识（只用字母/数字/短横线/下划线，如 ffmpeg-cli）",
+    "description": "这个分支要深挖什么？一句话"
+  }
+]
+```
+
+- `safe_name` 用于生成文件名 `{{dir}}/04-deep-dive-{safe_name}.md`。
+- 数组长度：light=2，standard=2-3，deep=3-4。
+- **严格合法 JSON**（无 trailing comma、无注释、字符串用双引号）。
+
+## 约束
+- 对比要客观、基于事实，不要有偏向性。
+- **不下最终推荐结论** —— 那是阶段5的事。
+- md 文件中文（JSON 除外）。

package/workflows/research/prompts/s3-deep-dive.md

@@ -0,0 +1,56 @@
+你正在执行六阶段技术调研的【阶段3：深度调研】，负责深挖其中一个分支。
+
+## 你的分支
+- **名称**：{{branchName}}
+- **要深挖什么**：{{branchDesc}}
+
+调研主题：{{topic}}
+调研深度：{{depth}}
+
+请先 Read `{{dir}}/01-goal.md`、`{{dir}}/02-map.md`、`{{dir}}/03-options.md`
+了解全局定位，避免与其它分支重复。
+
+## 输出要求
+**必须用 Write 写入 `{{dir}}/04-deep-dive-{{safeName}}.md`**，含：
+
+## 一、这是什么
+一句话定义 + 它在整个领域里的位置。
+
+## 二、工作原理 / 核心机制
+它到底怎么做到的？关键设计决策是什么？
+
+## 三、关键特性与能力边界
+能做什么、不能做什么。
+
+## 四、上手成本
+安装/配置/依赖、最小可用示例的复杂度、文档质量。
+
+## 五、生产就绪度
+版本稳定性、破坏性变更历史、已知重大缺陷、维护活跃度、真实生产案例。
+
+## 六、优劣势
+**优势**（3-5 条，每条带事实/场景）
+**劣势/局限/坑**（3-5 条，**必须诚实**，每条带具体问题，参考 issues / stackoverflow /
+博客里的真实负面反馈）
+
+## 七、适用/不适用场景
+- 最适合：…
+- 不适合：…
+
+## 八、关键资源
+3-5 个最值得读的资源：`- [名称](URL) — 说明`
+
+## 九、与其他分支的关系
+互补？竞争？可组合？
+
+## 十、未深挖问题（学习债务源头）
+调研中冒出但**超出本分支边界/深度上限**、没展开的问题，逐条记录：
+问题是什么 + 为什么值得后续研究 + 建议入口（文档/论文/代码位置）。没有则写「无」。
+
+## 约束
+- WebSearch 总次数 ≤ 15。
+- **不要动手写代码做实测**（那是阶段4）。
+- **不下最终推荐结论**（那是阶段5）。
+- 关键论断/数据后必须附来源链接 `[来源](URL)`；矛盾信息同时列出并注明冲突。
+- 文件名严格是 `{{dir}}/04-deep-dive-{{safeName}}.md`。
+- 中文 Markdown。

package/workflows/research/prompts/s4-verify.md

@@ -0,0 +1,74 @@
+你正在执行六阶段技术调研的【阶段4：动手验证】。
+
+调研主题：{{topic}}
+调研深度：{{depth}}
+
+请先 Read `{{dir}}/01-goal.md`、`{{dir}}/02-map.md`、`{{dir}}/03-options.md`
+以及所有 `{{dir}}/04-deep-dive-*.md`。
+
+## 你的任务
+针对前面调研出的方案做小规模动手验证（纸上得来终觉浅）。
+
+力度按深度：**light** 跑官方 hello-world / quickstart 即可；**standard** quickstart +
+最小功能验证，对比 2 个方案的使用体验；**deep** 对 top 1-2 个方案做小型 benchmark，
+写出可复现脚本。
+
+## 验证方法（按决策顺序执行）
+
+1. **只验证关键支撑论断**：从 03-options 和 04-deep-dive 里挑「如果它是假的，
+   最终推荐会改变」的论断（通常 2-4 条）。不影响结论的细节一律跳过，
+   不为了「看起来完整」去验证边角料。
+2. 对每条论断，先**改写成可证伪的具体假设**（「给定输入 X，输出应该是 Y」），
+   再设计「缩小规模但保留核心逻辑」的最小实验。
+3. 用 Bash 在 `{{dir}}/verify/` 目录下做实验：安装/下载 → 写最小脚本 → 运行，
+   **完整记录真实输出（含报错）**。
+
+4. **运行时约束（最高优先级）：验证脚本必须是 TypeScript / JavaScript（`.ts` / `.js`）**
+   - 本系统基于 bun 运行时（Node 兼容），**不保证有 Python 环境**。
+   - `.ts` 用 `bun run xxx.ts`；bun 不可用则写 `.js` 用 `node xxx.js`。
+   - **严禁写 Python 脚本、严禁 `pip install` / `python` / `python3`** ——
+     脚本会因缺解释器/依赖跑不起来，白白浪费时间预算。
+   - Python 生态更方便时优先找等价 JS/TS 方案：直接 `fetch` 调 HTTP API、
+     用对应 npm 包、或收窄到语言无关的接口行为验证。
+   - 确实无 JS/TS 可行路径的论断：不执行，记入「五、待人工验证」并跳过。
+
+5. **时限双保险**
+   - 每次 Bash 调用**必须显式传 `timeout: 60000`**（工具级硬中断，不依赖自觉）；
+   - 命令同时以 `timeout 60 ` 前缀守护（进程级）。
+   - 运行前估算耗时；预计超时的先缩小规模，仍超时的（训练类/大规模回测类）一律不执行，
+     转入「五、待人工验证」。
+
+6. 因网络/环境无法安装的，**诚实记录失败原因，不要假装成功**。
+
+## 输出要求
+**必须用 Write 写入 `{{dir}}/05-verification.md`**，含：
+
+## 一、验证的假设清单
+本轮选的 2-4 条关键论断，每条说明：为什么它是关键支撑（假的话哪个推荐结论会动摇）。
+
+## 二、环境说明
+操作系统、运行时（bun/node 版本）、依赖版本，一句话。
+
+## 三、验证记录（逐条对应假设，禁止混写）
+每条记：
+- **假设**：可证伪陈述
+- **脚本**：文件名（放 `{{dir}}/verify/` 下，命名能看出验证什么，如 `verify_xxx.ts`）
+- **运行方式与耗时**：`bun run xxx.ts`，实际运行 X 秒
+- **真实输出**：关键输出原文（含报错；**不许只写「成功」**）
+- **结论**：验证通过 / 假设被推翻
+- **影响面**（被推翻时必填）：动摇了 03-options / 04-deep-dive 里哪条结论？综合阶段须优先重估。
+
+## 四、验证总结
+验证通过的说法 / 被推翻或修正的说法（及影响面汇总）/ 新发现的问题与优势。
+
+## 五、待人工验证
+因超时、需特定硬件、仅有 Python 绑定等无法由本工作流验证的论断，逐条列出：
+论断内容、为什么验证不了、建议的人工验证方法、不验证对结论置信度的影响（高/中/低）。
+没有则写「无」。**这份清单是下一轮调研的输入，不是本阶段的失败项。**
+
+## 约束
+- 脚本只写 `.ts`/`.js`，严禁 Python；Bash 一律 `timeout:60000` + `timeout 60` 前缀。
+- 不装重型 IDE/桌面应用，只装 CLI 工具/库；不验证需要 GUI/账号/付费的服务。
+- 必然失败的（需付费/特定硬件）诚实记录并跳过。
+- **不允许出现「怕超时就完全不验证、也不记录」的空白状态。**
+- 中文 Markdown。

package/workflows/research/prompts/s5-synthesis.md

@@ -0,0 +1,81 @@
+你正在执行六阶段技术调研的【阶段5：综合升华】。
+
+调研主题：{{topic}}
+调研深度：{{depth}}
+
+请 **Read 所有前面产出的文件**（这一步以读为主，除非发现重大缺口才补 1-2 次搜索）：
+`{{dir}}/01-goal.md`、`{{dir}}/02-map.md`、`{{dir}}/03-options.md`、
+所有 `{{dir}}/04-deep-dive-*.md`（用 Glob 列出来逐个 Read）、`{{dir}}/05-verification.md`。
+
+## 你的任务
+1. **优先重估被推翻的结论**：Read 05-verification.md 的「验证总结/影响面」，
+   凡被推翻的论断，先重估 03-options / 04-deep-dive 里受影响的对比结论，再综合。
+2. 汇总所有阶段的发现，回答阶段0 定义的核心问题。
+3. 给出明确的推荐方案和使用建议。
+4. **诚实承认尚未搞清楚的问题。**
+5. 自我质检，列出仍存在的缺口（gaps），供补洞循环使用。
+
+## 输出要求：**三个文件缺一不可**
+
+### 文件1：`{{dir}}/06-synthesis.md`
+
+⚠️ **下面的章节标题字面一个字都不能改** —— 下游有确定性校验按关键词 grep 它们。
+
+## 一、核心结论
+3-5 句话直接回答阶段0 定义的核心问题。
+
+## 二、推荐方案
+- **首选推荐**：xxx，理由（2-3 条）
+- **备选方案**：xxx，适用场景
+- **不推荐**：xxx，原因（如有）
+
+## 三、决策依据
+为什么做这个推荐？引用前面哪些发现/数据/验证结果？每条必须标注**证据等级**：
+- 【已实证】阶段4动手验证过
+- 【多源一致】≥2 个独立可靠来源交叉印证
+- 【单源】只有一个来源支撑（注明链接）
+- 【推断】基于已知信息的合理推断（说明推断链）
+
+## 三b、已通过脚本验证的关键结论
+逐条列出，**固定格式**（与 05-verification.md 一一对应，**不许凭记忆编**）：
+`结论陈述 —— 已验证（脚本：scripts/<文件名>，运行方式：bun run <文件名>，运行耗时：Xs，实际输出：<关键输出>）`
+语气肯定自信，不加「可能/理论上」模糊词 —— 不确定的内容不配进本节。
+
+## 三c、未附脚本的结论说明
+报告引用了但没有验证脚本支撑的关键结论，逐条按三种情况说明：
+`结论陈述 —— 未验证（原因：过于简单无需验证 / 超时限难以端到端验证 / 无法验证；如需验证建议：…）`
+
+## 四、使用建议
+快速上手路径（第一步做什么）/ 关键注意事项与容易踩的坑 / 进阶学习资源。
+
+## 五、调研局限 & 未决问题
+诚实列出这次调研**没搞清楚**或**存在不确定性**的地方。
+完美调研不存在 —— 明确边界本身就是高质量的体现。
+
+## 六、调研缺口
+（为下一轮自检补洞提供起点；没有就写「无」。）逐条写：缺什么信息？补什么能让结论更可靠？
+
+### 文件2：`{{dir}}/07-learning-debt.md`（学习债务清单，本阶段拥有并维护）
+
+汇总各 deep-dive 的「未深挖问题」小节 + 本阶段新发现的边界外问题，每条：
+- **问题**：一句话描述
+- **为什么值得后续研究**：与本次核心问题的关系
+- **建议入口**：文档/论文/代码/关键词
+
+没有则写「无」。
+
+### 文件3：`{{dir}}/gaps.json`（机器可读缺口列表，驱动补洞循环）
+
+JSON **字符串数组**，每元素一条缺口的一句话描述：
+
+```json
+["方案A的并发性能数据缺失，需要补充 benchmark 来源", "方案B在 Windows 上的兼容性未验证"]
+```
+
+没有缺口就写 `[]`。**严格合法 JSON。**
+
+## 约束
+- 以综合为主，尽量不大量搜索（读完所有文件再决定是否补搜）。
+- 结论要明确，**不要和稀泥**。
+- **「已验证」小节绝不允许编造**：每条都必须能在 05-verification.md 找到对应的真实运行记录，
+  否则降级写进「未验证」小节。

package/workflows/research/prompts/s5b-fill-gaps.md

@@ -0,0 +1,32 @@
+你在执行综合阶段的【自检补洞】第 {{round}} 轮。
+
+调研主题：{{topic}}
+
+之前已完成全流程调研，综合报告在 `{{dir}}/06-synthesis.md`。
+上一轮自我质检发现这些缺口：
+
+{{gaps}}
+
+## 你的任务
+1. Read 已有的所有 `{{dir}}/*.md`（避免重复调研）。
+2. 针对每条缺口用 WebSearch/WebFetch 补充调研（**每个缺口 2-5 次搜索**）。
+3. 发现新的关键信息/反例/数据时**更新** `{{dir}}/06-synthesis.md`
+   （Read 现有内容 → 修改 → Write 覆盖）。
+4. 重新评估缺口：已填补的删除、仍未填补的保留、新发现的加入。
+5. 把更新后的缺口列表写回 `{{dir}}/gaps.json`（JSON 字符串数组；全补完写 `[]`）。
+6. 新发现若直接影响某个 deep-dive / verification 文件，同时更新它。
+
+## 约束
+
+- 每个缺口针对性搜 2-5 次即可，**不要重新全面调研**。
+- **保持 06-synthesis.md 的章节标题字面不变** —— 尤其「一、核心结论」和「二、推荐方案」
+  这两个标题**一个字都不能改**，下游有确定性校验按关键词 grep 它们。
+  只更新章节内容，不重排结构、不改标题措辞。
+- **「不可补」的缺口必须清出 gaps.json**：信息根本不可得（无公开数据/需付费/需长期实盘）
+  或超出本工作流能力（需特定硬件/账号）的，本轮就把它移入 06-synthesis.md 的
+  「调研局限」并**从 gaps.json 删除** —— 它不是「待补缺口」，是「已知边界」。
+  留着不删只会让下一轮空转、让用户误以为还有洞没补。
+- 判断标准：搜了 2-5 次仍找不到可靠来源 → 不可补；找到来源 → 填进报告。
+- 不要推翻整个报告，只补充和修正。
+- `gaps.json` 必须是合法 JSON 数组。
+- 中文 Markdown。