minimal-agent 0.11.0 → 0.13.0

package/workflows/research.yaml

@@ -0,0 +1,873 @@
+# ============================================================
+#  workflows/research.yaml —— 六阶段技术深度调研工作流
+# ------------------------------------------------------------
+#  把 research.md 里的「人类调研方法论」编译成 agent 可执行的工作流：
+#
+#    Stage 0 · 定义问题   (goal)        → out/research/${session}/01-goal.md
+#    Stage 1 · 测绘地图   (map)         -> out/research/${session}/02-map.md + early-exit.json
+#    [early-exit 简化路径]               -> s1_exit_report 直出简化全套文件
+#    Stage 2 · 方案对比   (options)     → out/research/${session}/03-options.md + branches.json
+#    Stage 3 · 深度调研   (deep-dive)   → out/research/${session}/04-deep-dive-{safe_name}.md
+#    Stage 4 · 动手验证   (verify)      → out/research/${session}/05-verification.md
+#    Stage 5 · 综合升华   (synthesis)   -> out/research/${session}/06-synthesis.md + 07-learning-debt.md + gaps.json
+#    Stage 5b· 自检补洞   (fill gaps)   → 循环更新 06-synthesis.md
+#    Stage 6 · 拼装报告   (assemble)    → out/research/${session}/report.md
+#
+#  关键设计：
+#   · 每个阶段用 done_when + 落盘文件作为确定性闸门（对抗模型「只宣告不落盘」）
+#   · Stage 3 用 for-each + fresh_context 实现「多个 sub-agent 独立深挖」
+#   · 验证脚本强制 TypeScript/JavaScript（bun run / node 执行），严禁 Python
+#     （运行时基于 bun/Node，不保证 Python 环境）；超时以 timeout 60 守护
+#   · early-exit：地图阶段判定「资料极少/主题过简」时走简化路径，
+#     用 when 守卫跳过 s2/s4/s5/s5b，s3 空数组天然 0 迭代，s6 拼装无需分叉
+#   · 学习债务闭环：s3 各分支记「未深挖问题」-> s5 综合阶段汇总产出 07-learning-debt.md
+#   · 可信度标注：s1/s2/s3 关键论断带来源链接，s5 决策依据标证据等级
+#   · 综合后有 while 自检循环，按 gaps.json 数组补洞（最多 max_iterations 轮）
+#   · 最后用确定性 Bash heredoc 拼装 report.md（不烧 LLM，结果稳定可复现）
+# ============================================================
+
+name: research
+description: >
+  六阶段技术深度调研：定义问题→测绘领域地图→候选方案对比→分支深度调研→动手验证→综合升华。
+  输入一个技术主题/问题，自动产出 out/research/${session}/report.md（含知识地图、对比矩阵、验证记录、最终建议）。
+version: "1.0.0"
+
+artifacts:
+  - "out/research/${session}/01-goal.md"
+  - "out/research/${session}/02-map.md"
+  - "out/research/${session}/03-options.md"
+  - "out/research/${session}/05-verification.md"
+  - "out/research/${session}/06-synthesis.md"
+  - "out/research/${session}/07-learning-debt.md"
+  - "out/research/${session}/branches.json"
+  - "out/research/${session}/gaps.json"
+  - "out/research/${session}/early-exit.json"
+  - "out/research/${session}/deliverable/report.md"
+  - "out/research/${session}/deliverable/scripts/README.md"
+
+self_heal:
+  max_retries: 1
+  retry_delay_ms: 8000
+
+inputs:
+  - name: topic
+    type: string
+    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: "综合阶段自检-补洞最大迭代轮数（默认 2 轮，防止无限递归）"
+
+steps:
+  # ======================== 初始化 ========================
+  # 仅创建工作目录结构（mkdir -p），不删除任何文件——本工作流的产物路径唯一且命名固定，
+  # 子 agent 用 Write 覆盖时本身就幂等；既避免 rm -f/-rf 触发 Bash permanentDeleteGuard
+  # 拦在 init，又保护用户预先在 out/research/${session}/ 放的其他文件（避免被静默删除）。
+  # 想清空工作区，直接删整个 out/research/${session}/ 目录或在 TUI 用 /clear --session。
+  - id: init
+    title: "调研·初始化工作目录"
+    tool: Bash
+    args:
+      command: |
+        mkdir -p out/research/${session} out/research/${session}/verify out/research/${session}/deliverable/scripts
+        echo init_ok
+    capture:
+      content: _init_out
+
+  # ======================== Stage 0 · 定义问题 ========================
+  - id: s0_goal
+    title: "阶段0/6 · 定义问题与边界"
+    agent: |
+      你是一名资深技术研究员，现在启动六阶段技术调研流程的【阶段0：定义问题】。
+
+      ## 调研主题
+      ${inputs.topic}
+
+      ## 调研深度
+      ${inputs.depth}（light=快速扫盲 / standard=可用结论 / deep=学术级深度）
+
+      ## 你的任务
+      **本阶段禁止任何搜索**（WebSearch/WebFetch 都不允许）--目标澄清靠分析用户请求本身，
+      不是靠了解主题。一旦搜索，你会用「搜到的东西」定义问题，而不是用「用户真正想解决的问题」，
+      引入锚定偏差。摸底是阶段1的职责。
+
+      基于用户的主题描述和你的常识，输出结构化的问题定义文档：
+      1. 把「主题词」转化为「问题句」：一句话描述要回答的具体问题
+         （不是"研究一下A"，而是"针对什么场景，A 类方案该怎么选/值不值得投入，为什么"）。
+      2. 只澄清决定「哪个方案适配」的隐藏变量：目标、交付物形态、场景约束、已知信息。
+         **严禁预设或询问具体技术方案**--方案选择是本次研究的产出，不是输入。
+      3. **必须用 Write 工具把结果写入 `out/research/${session}/01-goal.md`**，文件必须包含以下章节（用 ## 二级标题）：
+
+         ## 一、核心问题
+         一句话描述这次调研要回答的核心问题。
+
+         ## 二、背景与动机
+         为什么这个问题值得研究？典型的应用场景是什么？
+
+         ## 三、范围与边界
+         - **包含**：本次调研要覆盖的子话题/子问题（3-7 个）
+         - **不包含**：明确排除的内容（防止范围蔓延）
+         - **目标读者**：谁会看这份调研报告
+
+         ## 四、验收标准
+         调研完成后，满足哪些条件才算「调研清楚了」？（3-5 条可判定的标准）
+
+         ## 五、待澄清问题
+         如果你对用户的需求有不清楚的地方（比如技术选型偏好、规模要求、时间约束等），列在这里。
+         如果没有问题，写「无」。
+
+      ## 约束
+      - **本阶段零搜索、零方案预设**，只做目标澄清。
+      - 必须写文件 `out/research/${session}/01-goal.md`，不要只在对话里输出。
+      - 文件用中文，Markdown 格式。
+    allowed_tools: [Read, Write]
+    maxTurns: 12
+    done_when: "fileExists('out/research/${session}/01-goal.md')"
+    goal_supplement: true
+
+  # --- 用户确认闸门 ---
+  - id: s0_pause
+    title: "阶段0 · 用户确认"
+    type: pause
+    free_text: approve
+    prompt: |
+      已完成问题定义，请阅读 out/research/${session}/01-goal.md。
+
+      请确认核心问题、范围边界、验收标准是否符合预期：
+      - 如果没问题 → 选「继续执行」
+      - 如果要调整范围/补充要求 → 在「其他」框输入你的指示，工作流会将其作为补充要求贯穿全程
+
+  # ======================== Stage 1 · 测绘领域地图 ========================
+  - id: s1_map
+    title: "阶段1/6 · 测绘领域地图"
+    agent: |
+      你正在执行六阶段技术调研的【阶段1：测绘领域地图】。
+
+      调研主题：${inputs.topic}
+      调研深度：${inputs.depth}
+
+      请先 Read `out/research/${session}/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 工具写入 `out/research/${session}/02-map.md`**，包含：
+
+      ## 一、领域一句话定义
+      用一句话说清楚这个领域/技术是做什么的。
+
+      ## 二、发展历程（时间线）
+      关键里程碑：起源年份、主要版本/突破、当前状态。控制在 5-10 个节点。
+
+      ## 三、核心概念与术语
+      这个领域的关键术语（5-15 个），每个配一句话解释。按重要性排序。
+
+      ## 四、生态/子领域划分
+      这个领域有哪些主要分支/子方向/派系？画一个结构化的树形分类。
+
+      ## 五、关键人物/组织/项目
+      这个领域的主要推动者是谁？（知名研究者、公司、开源项目）。列 5-10 个。
+
+      ## 六、核心资源索引
+      最值得读的 5-10 个资源（官网/文档/综述/awesome-list/经典论文/教程），
+      每个一行，格式：`- [名称](URL) — 一句话说明为什么值得读`。
+
+      ## 七、初印象：主流方向与争议点
+      从俯瞰角度看，这个领域目前的主流做法是什么？有哪些主要争议/分歧/开放问题？
+
+      ## 八、提前退出判定（early-exit check）
+      扫描完成后，判断这次调研是否需要走完整六阶段：
+      - **硬性规则**：若「生态/子领域划分」识别出 **≥3 个候选方案/流派**，必须判定
+        `early=false`（领域有实质性结构，值得全流程），不得以「主题简单」为由偷懒退出。
+      - 仅当以下情况才允许 `early=true`：
+        - 领域公开资料极少（可靠来源 < 3 个）；
+        - 或主题足够简单（一份官方 quickstart 即可完整回答核心问题）；
+        - 或地图层面已能直接给出结论。
+
+      **同时必须用 Write 写入 `out/research/${session}/early-exit.json`**（严格合法 JSON）：
+      ```json
+      {"early": true, "reason": "一句话理由"}
+      ```
+      或
+      ```json
+      {"early": false}
+      ```
+
+      ## 约束
+      - WebSearch 总次数控制在 10 次以内，不要陷入无止境的搜索。
+      - 不要做方案对比--那是下一阶段的事。
+      - 关键事实/论断后面附来源链接，格式 `- [来源](URL)`（可信度从源头可溯）。
+      - 文件写中文 Markdown。
+    allowed_tools: [WebSearch, WebFetch, Read, Write, Bash, Glob]
+    maxTurns: 25
+    done_when: "fileExists('out/research/${session}/02-map.md') && fileExists('out/research/${session}/early-exit.json')"
+
+  # --- early-exit：读取判定结果 ---
+  - id: s1_load_exit
+    title: "阶段1 · 读取提前退出判定"
+    type: set
+    set:
+      _early_exit: "${readJson('out/research/${session}/early-exit.json', 'early') == true}"
+
+  # --- early-exit 简化路径：跳过深挖/验证/综合，直出简化报告 ---
+  #    正常路径的 03/05/06/07 + branches.json + gaps.json 全部由此步补齐，
+  #    使后续 s2_assert / s3(空数组0迭代) / s6 拼装无需分叉。
+  - id: s1_exit_report
+    title: "阶段1 · 简化路径报告（提前退出）"
+    when: "_early_exit == true"
+    agent: |
+      地图阶段已判定「提前退出」（out/research/${session}/early-exit.json 里记录了原因）。
+      你的任务：跳过深挖/验证/综合阶段，直接产出简化版全套文件，保证最终报告可拼装。
+
+      请先 Read `out/research/${session}/01-goal.md` 和 `out/research/${session}/02-map.md`。
+
+      ## 必须用 Write 写入以下全部文件
+      1. `out/research/${session}/03-options.md`：写明「已提前退出，未做方案对比」+ 退出原因 +
+         地图层面看到的候选方向简述（若有）。
+      2. `out/research/${session}/branches.json`：内容 `[]`（空数组）。
+      3. `out/research/${session}/05-verification.md`：写明「已提前退出，未做动手验证」+ 原因。
+      4. `out/research/${session}/06-synthesis.md`：基于 01-goal 的问题定义和 02-map 的地图，
+         直接给出能给出的结论（必须包含「核心结论」和「推荐方案/下一步建议」章节）；
+         给不出的诚实标注「信息不足，需全流程调研」。
+      5. `out/research/${session}/07-learning-debt.md`：记录本次因提前退出未覆盖的问题清单
+         （每条：问题 + 为什么值得后续研究 + 建议入口）。
+      6. `out/research/${session}/gaps.json`：内容 `[]`（简化路径不进入补洞循环）。
+
+      ## 约束
+      - 全部文件中文（JSON 除外），JSON 必须严格合法。
+      - 诚实第一：简化报告的价值在于明确说出「哪些没做、为什么」，而不是硬凑结论。
+    allowed_tools: [Read, Write]
+    maxTurns: 10
+    done_when: "fileExists('out/research/${session}/03-options.md') && fileExists('out/research/${session}/branches.json') && fileExists('out/research/${session}/05-verification.md') && fileExists('out/research/${session}/06-synthesis.md') && fileExists('out/research/${session}/07-learning-debt.md') && fileExists('out/research/${session}/gaps.json')"
+
+  # ======================== Stage 2 · 候选方案对比 ========================
+  - id: s2_options
+    title: "阶段2/6 · 候选方案对比"
+    when: "_early_exit != true"
+    agent: |
+      你正在执行六阶段技术调研的【阶段2：候选方案对比】。
+
+      调研主题：${inputs.topic}
+      调研深度：${inputs.depth}
+
+      请先 Read：
+      - `out/research/${session}/01-goal.md`（问题定义与验收标准）
+      - `out/research/${session}/02-map.md`（领域地图）
+
+      ## 你的任务
+      在地图基础上，识别出解决这个问题的 **3-5 个主要候选方案/技术路线**，对它们做系统对比。
+
+      1. 基于阶段1的地图和补充搜索，确定 3-5 个最值得比较的候选方案（主流方向/代表性项目）。
+         - 如果调研深度是 light，可以只列 2-3 个。
+         - 如果是 standard/deep，列出 3-5 个并覆盖主要分支。
+      2. 对每个方案做 1-3 次针对性的 WebSearch/WebFetch 补充关键事实（性能指标、成熟度、社区活跃度等）。
+      3. 如果发现阶段1的地图遗漏了重要分支，可以在本阶段补充搜索。
+
+      ## 输出要求
+      你**必须**同时写入两个文件：
+
+      ### 文件1：`out/research/${session}/03-options.md`（人读的对比报告），包含：
+
+      ## 一、候选方案清单
+      简要介绍每个候选方案是什么、由谁主导/维护、定位是什么。
+
+      ## 二、对比矩阵
+      用 Markdown 表格对比（维度按领域特性增删）：
+      | 维度 | 方案 A | 方案 B | 方案 C | ... |
+      |------|--------|--------|--------|-----|
+      | 核心思路 | ... | ... | ... | ... |
+      | 成熟度/生态 | ... | ... | ... | ... |
+      | 性能/规模 | ... | ... | ... | ... |
+      | 学习曲线 | ... | ... | ... | ... |
+      | 适用场景 | ... | ... | ... | ... |
+      | 不适用场景 | ... | ... | ... | ... |
+      | 社区活跃度 | ... | ... | ... | ... |
+      | 许可证/成本 | ... | ... | ... | ... |
+
+      关键数据格必须标注来源（格内直接 `[来源](URL)` 或表下方集中列来源）；
+      某维度缺乏公开可靠信息时明确写「信息不足」，**不要编造或用弱相关信息强行填充**。
+
+      ## 三、初步判断
+      哪些方案值得在阶段3深入调研？列出 2-4 个深度调研分支，每个配 1-2 句理由。
+
+      ### 文件2：`out/research/${session}/branches.json`（机器读的分支列表，驱动阶段3 for-each）
+
+      ```json
+      [
+        {
+          "name": "分支显示名（中文，如「FFmpeg 命令行方案」）",
+          "safe_name": "分支短标识（英文/拼音，只用字母/数字/短横线/下划线，如 ffmpeg-cli）",
+          "description": "这个分支要深挖什么？一句话描述"
+        }
+      ]
+      ```
+      - safe_name 用于生成输出文件名 `out/research/${session}/04-deep-dive-{safe_name}.md`。
+      - 数组长度：light=2, standard=2-3, deep=3-4。
+      - **严格是合法 JSON**（不要有 trailing comma、不要有注释、字符串用双引号）。
+
+      ## 约束
+      - 对比要客观，基于事实，不要有偏向性。
+      - 不要做最终推荐——那是阶段5的事。
+      - 两个文件缺一不可。
+      - md 文件写中文（JSON 除外）。
+    allowed_tools: [WebSearch, WebFetch, Read, Write, Bash, Glob]
+    maxTurns: 25
+    done_when: "fileExists('out/research/${session}/03-options.md') && fileExists('out/research/${session}/branches.json')"
+
+  # --- 把 branches.json 加载进变量，驱动后续 for-each ---
+  - id: s2_load_branches
+    title: "阶段2 · 加载深度调研分支列表"
+    type: set
+    set:
+      branches: "${asArray(readJson('out/research/${session}/branches.json'))}"
+
+  - id: s2_assert_branches
+    title: "阶段2 · 分支列表校验"
+    type: assert
+    when: "_early_exit != true"
+    condition: "length(branches) > 0"
+    onFail: "未能从 out/research/${session}/branches.json 读取到任何深度调研分支（可能是 JSON 格式错误或数组为空）。"
+
+  # ======================== Stage 3 · 深度调研（per-branch sub-agent） ========================
+  - id: s3_deep_dive
+    title: "阶段3/6 · 深度调研（逐分支）"
+    type: loop
+    over: "${asArray(branches)}"
+    as: branch
+    fresh_context: true
+    do:
+      - id: s3_dive_one
+        title: "阶段3 · 深挖「${branch.name}」"
+        agent: |
+          你正在执行六阶段技术调研的【阶段3：深度调研】，负责深挖其中一个分支。
+
+          ## 你的分支
+          - 分支名称：${branch.name}
+          - 分支调研重点：${branch.description}
+
+          ## 全局调研背景
+          - 主题：${inputs.topic}
+          - 深度：${inputs.depth}
+
+          请先 Read 以下文件了解全局上下文：
+          - `out/research/${session}/01-goal.md`
+          - `out/research/${session}/02-map.md`
+          - `out/research/${session}/03-options.md`
+          - 其他已存在的 `out/research/${session}/04-deep-dive-*.md`（前面其他分支的深挖结果，可以参考但不要重复劳动）
+
+          ## 你的任务
+          对 **${branch.name}** 这个分支做深度调研，产出一份独立的深度报告。
+
+          调研方法（按顺序做，控制在 30-60 分钟内）：
+          1. **针对性搜索**：搜官方文档、GitHub 仓库、技术博客、性能测评、最佳实践、已知限制/issue。每方向 2-3 次，总次数控制在 8-15 次。
+          2. **精读核心材料**：WebFetch 官方文档/README/架构文档/1-2 篇深度技术博客。
+          3. **查负面信息**：搜 "xxx limitations" / "xxx pitfalls" / "xxx production issues" / "xxx vs" 了解坑和反对声音（只有正面的调研不可信）。
+          4. 必要时看 GitHub issues / Stack Overflow 上的真实问题。
+
+          ## 输出要求
+          **必须用 Write 工具写入 `out/research/${session}/04-deep-dive-${branch.safe_name}.md`**，包含：
+
+          ## 一、概览
+          这个分支/方案是什么？核心设计思路/工作原理是什么？（一段话）
+
+          ## 二、核心特性
+          最突出的 3-5 个特性/优势，每个配 1-2 句解释 + 事实支撑。
+
+          ## 三、工作原理（简化版）
+          技术方案：说明内部工作原理/架构（面向工程师，2-5 段）。
+          理论/算法：用通俗语言解释核心思想。
+
+          ## 四、使用方式（最小示例）
+          给出一个最小可用示例（代码片段/命令行/配置）。
+
+          ## 五、真实表现
+          - 性能指标：能找到的 benchmark/数据（注明来源和场景）
+          - 生产案例：谁在用？（至少 2-3 个知名案例）
+          - 社区数据：GitHub stars、最近 commit 时间、contributor 数、下载量
+
+          ## 六、优势与劣势
+          **优势**（3-5 条，每条带事实/场景）
+          **劣势/局限/坑**（3-5 条，必须诚实，每条带具体问题，参考 issues/stackoverflow/博客的真实负面反馈）
+
+          ## 七、适用/不适用场景
+          - 最适合：...
+          - 不适合：...
+
+          ## 八、关键资源
+          最值得读的 3-5 个资源（官网/文档/源码/最佳实践博客）：
+          - [名称](URL) - 说明
+
+          ## 九、与其他分支的关系
+          它和其他候选方案是什么关系？互补？竞争？可组合？
+
+          ## 十、未深挖问题（学习债务源头）
+          调研中冒出但**超出本分支边界/深度上限**、没有展开的问题，逐条记录：
+          问题是什么 + 为什么值得后续研究 + 建议入口（文档/论文/代码位置）。
+          交还综合阶段汇入学习债务清单。没有则写「无」。
+
+          ## 约束
+          - WebSearch 总次数 ≤ 15。
+          - 不要动手写代码做实测（那是阶段4）。
+          - 不要下最终推荐结论（那是阶段5）。
+          - 关键论断/数据后面必须附来源链接 `[来源](URL)`；矛盾信息同时列出并注明冲突。
+          - 文件写中文 Markdown。
+          - 文件名严格是 `out/research/${session}/04-deep-dive-${branch.safe_name}.md`。
+        allowed_tools: [WebSearch, WebFetch, Read, Write, Bash, Glob]
+        maxTurns: 30
+        done_when: "fileExists('out/research/${session}/04-deep-dive-' + branch.safe_name + '.md')"
+
+  # ======================== Stage 4 · 动手验证 ========================
+  - id: s4_verify
+    title: "阶段4/6 · 动手验证"
+    when: "_early_exit != true"
+    agent: |
+      你正在执行六阶段技术调研的【阶段4：动手验证】。
+
+      调研主题：${inputs.topic}
+      调研深度：${inputs.depth}
+
+      请先 Read：
+      - `out/research/${session}/01-goal.md`
+      - `out/research/${session}/02-map.md`
+      - `out/research/${session}/03-options.md`
+      - 所有 `out/research/${session}/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 在 `out/research/${session}/verify/` 目录下做实验：
+         - 安装/下载（npm/bun 包管理器/二进制/git clone）
+         - 写最小验证脚本并运行，完整记录真实输出（含报错）
+      4. **运行时约束（最高优先级）：所有验证脚本必须是 TypeScript / JavaScript（`.ts` / `.js`）**：
+         - 本系统基于 bun 运行时（Node.js 兼容），**不保证有 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 可行路径（强依赖仅有 Python 绑定的库）的论断：不执行，
+           记入「五、待人工验证」并跳过。
+      5. **时限双保险**：
+         - 每次 Bash 工具调用**必须显式传 `timeout: 60000` 参数**（工具级 60 秒硬中断，
+           超时自动杀进程，不依赖自觉）；
+         - 同时命令以 `timeout 60 ` 前缀守护（进程级）。
+         - 运行前先估算耗时；预计超时的先缩小规模，仍超时的（训练类/大规模回测类）
+         一律不执行，转入「五、待人工验证」。
+      6. 因网络/环境原因无法安装的，诚实记录失败原因，不要假装成功。
+
+      ## 输出要求
+      **必须用 Write 写入 `out/research/${session}/05-verification.md`**，包含：
+
+      ## 一、验证的假设清单
+      本轮选择验证的 2-4 条关键论断，每条说明：为什么它是关键支撑（如果它是假的，
+      哪个推荐结论会动摇）。
+
+      ## 二、环境说明
+      操作系统、运行时（bun/node 版本）、依赖版本（一句话）。
+
+      ## 三、验证记录（逐条对应假设，禁止混写）
+      对每条假设记录：
+      - **假设**：可证伪陈述（给定输入 X，输出应为 Y）
+      - **脚本**：文件名（放在 out/research/${session}/verify/ 下，命名能看出验证什么，如 verify_xxx.ts）
+      - **运行方式与耗时**：`bun run xxx.ts`，实际运行 X 秒
+      - **真实输出**：关键输出原文（含报错；不许只写「成功」）
+      - **结论**：验证通过 / 假设被推翻
+      - **影响面**（被推翻时必填）：这动摇了 03-options / 04-deep-dive 里的哪条对比结论？
+        综合阶段必须优先重估它。
+
+      ## 四、验证总结
+      - 验证通过的说法
+      - 被推翻/修正的说法（及影响面汇总）
+      - 新发现的问题/优势
+
+      ## 五、待人工验证
+      因超时/需要特定硬件/仅有 Python 绑定等无法由本工作流验证的论断，
+      逐条列出：论断内容、为什么验证不了、建议的人工验证方法、不验证对结论置信度的影响（高/中/低）。
+      没有则写「无」。这份清单是下一轮调研的输入，不是本阶段的失败项。
+
+      ## 约束
+      - **脚本只写 .ts/.js（bun run / node 跑），严禁 Python；Bash 一律 timeout:60000 + `timeout 60` 前缀**（细则见「验证方法」第 4、5 条）。
+      - 不装重型 IDE/桌面应用；只装 CLI 工具/库。
+      - 不验证需要 GUI/账号/付费的服务。
+      - 安装/执行必然失败的（需要付费/特定硬件），诚实记录并跳过。
+      - 不允许出现「怕超时就完全不验证、也不记录」的空白状态。
+      - 文件写中文 Markdown。
+    allowed_tools: [Bash, Read, Write, Glob, WebSearch, WebFetch]
+    maxTurns: 25
+    done_when: "fileExists('out/research/${session}/05-verification.md')"
+
+  # ======================== Stage 5 · 综合升华 ========================
+  - id: s5_synthesis
+    title: "阶段5/6 · 综合结论"
+    when: "_early_exit != true"
+    agent: |
+      你正在执行六阶段技术调研的【阶段5：综合升华】。这是产出最终结论的关键一步。
+
+      调研主题：${inputs.topic}
+      调研深度：${inputs.depth}
+
+      请 **Read 所有前面产出的文件**（这一步以读为主，除非发现重大缺口才补 1-2 次搜索）：
+      - `out/research/${session}/01-goal.md`
+      - `out/research/${session}/02-map.md`
+      - `out/research/${session}/03-options.md`
+      - 所有 `out/research/${session}/04-deep-dive-*.md`（用 Glob 列出来逐个 Read）
+      - `out/research/${session}/05-verification.md`
+
+      ## 你的任务
+      1. **优先重估被推翻的结论**：Read `out/research/${session}/05-verification.md` 的「验证总结/影响面」，
+         凡是被推翻的论断，先重估 03-options/04-deep-dive 里受影响的对比结论，再综合。
+      2. 汇总所有阶段的发现，回答 stage0 定义的核心问题。
+      3. 给出明确的推荐方案和使用建议。
+      4. 诚实承认尚未搞清楚的问题。
+      5. 进行自我质检，列出仍存在的缺口（gaps），供补洞循环使用。
+
+      ## 输出要求
+      你**必须**同时写入三个文件：
+
+      ### 文件1：`out/research/${session}/06-synthesis.md`（最终结论，人读），包含：
+
+      ## 一、核心结论
+      用 3-5 句话直接回答 stage0 定义的核心问题。
+
+      ## 二、推荐方案
+      - **首选推荐**：xxx，理由（2-3 条）
+      - **备选方案**：xxx，适用场景
+      - **不推荐**：xxx，原因（如果有）
+
+      ## 三、决策依据
+      为什么做这个推荐？引用前面阶段的哪些发现/数据/验证结果？
+      每条依据必须标注**证据等级**之一：
+      - 【已实证】阶段4动手验证过
+      - 【多源一致】≥2 个独立可靠来源交叉印证
+      - 【单源】只有一个来源支撑（注明来源链接）
+      - 【推断】基于已知信息的合理推断（说明推断链）
+
+      ## 三b、已通过脚本验证的关键结论
+      逐条列出，**固定格式**（与 05-verification.md 的记录一一对应，不许凭记忆编）：
+      `结论陈述 -- 已验证（脚本：scripts/<文件名>，运行方式：bun run <文件名>，运行耗时：Xs，实际输出：<关键输出>）`
+      语气肯定自信，不加「可能/理论上」模糊词--不确定的内容不配进本节。
+
+      ## 三c、未附脚本的结论说明
+      对报告引用了但没有验证脚本支撑的关键结论，按三种情况逐条说明：
+      `结论陈述 -- 未验证（原因：过于简单无需验证 / 超时限难以端到端验证 / 无法验证；如需验证建议：...）`
+
+      ## 四、使用建议
+      - 快速上手路径（第一步做什么）
+      - 关键注意事项/容易踩的坑
+      - 进阶学习资源
+
+      ## 五、调研局限 & 未决问题
+      诚实列出这次调研**没有搞清楚**或**存在不确定性**的地方。
+      完美调研不存在——明确边界本身就是高质量体现。
+
+      ## 六、调研缺口
+      （本节为下一轮自检补洞提供起点；如果没有缺口，写「无」。）
+      - 缺口1：具体缺什么信息？补什么能让结论更可靠？
+      - 缺口2：...
+
+      ### 文件2：`out/research/${session}/07-learning-debt.md`（学习债务清单，本阶段拥有并维护）
+
+      汇总各 deep-dive 报告「未深挖问题」小节 + 本阶段综合时新发现的边界外问题，
+      每条格式：
+      - **问题**：一句话描述
+      - **为什么值得后续研究**：与本次核心问题的关系
+      - **建议入口**：文档/论文/代码/关键词
+      没有则写「无」。
+
+      ### 文件3：`out/research/${session}/gaps.json`（机器可读缺口列表，驱动补洞循环）
+
+      是一个 JSON **字符串数组**，每个元素是一条缺口的一句话描述。例如：
+      ```json
+      [
+        "方案A的并发性能数据缺失，需要补充benchmark来源",
+        "方案B在Windows上的兼容性问题未验证"
+      ]
+      ```
+      如果没有缺口，写 `[]`（空数组）。
+      **严格是合法 JSON**。
+
+      ## 约束
+      - 以综合为主，尽量不要大量搜索（读完所有文件再决定是否补搜）。
+      - 结论要明确，不要和稀泥。
+      - **「已验证」小节绝不允许编造**：每条都必须能在 05-verification.md 找到对应真实运行记录，
+        否则降级写进「未验证」小节。
+      - 必须诚实--用户要的是可信结论，不是听起来全面的废话。
+      - md 文件写中文。
+    allowed_tools: [Read, Write, Glob, WebSearch, WebFetch]
+    maxTurns: 20
+    done_when: "fileExists('out/research/${session}/06-synthesis.md') && fileExists('out/research/${session}/07-learning-debt.md') && fileExists('out/research/${session}/gaps.json')"
+
+  # ======================== Stage 5b · 自检-补洞循环 ========================
+  - id: s5b_loop
+    title: "阶段5b · 自检补洞（最多 ${inputs.max_iterations} 轮）"
+    type: loop
+    when: "_early_exit != true"
+    max_iterations: "${inputs.max_iterations}"
+    do:
+      - id: s5b_load_gaps
+        title: "自检·读取缺口列表"
+        type: set
+        set:
+          _gaps: "${asArray(readJson('out/research/${session}/gaps.json'))}"
+
+      - id: s5b_break_if_empty
+        title: "自检·无缺口则退出"
+        type: branch
+        condition: "length(_gaps) == 0"
+        then:
+          - id: s5b_bye
+            type: echo
+            message: "✅ 自检无缺口，补洞循环结束。"
+          - id: s5b_brk
+            type: break
+
+      - id: s5b_fill
+        title: "自检·第 ${_iter_idx + 1} 轮补洞"
+        agent: |
+          你在执行综合阶段的【自检补洞】第 ${_iter_idx + 1} 轮。
+
+          调研主题：${inputs.topic}
+
+          之前已完成全流程调研，综合报告在 `out/research/${session}/06-synthesis.md`。
+          上一轮自我质检发现这些缺口：
+          ${join(_gaps, '\n')}
+
+          ## 你的任务
+          1. Read 已有的所有 `out/research/${session}/*.md`（避免重复调研）。
+          2. 针对每条缺口，用 WebSearch/WebFetch 做补充调研（每个缺口 2-5 次搜索）。
+          3. 如果发现新的关键信息/反例/数据，**更新** `out/research/${session}/06-synthesis.md`
+             （Read 现有内容 → 修改 → Write 覆盖）。
+          4. 重新评估缺口：
+             - 已填补的删除
+             - 仍未填补的保留
+             - 新发现的加入
+          5. 把更新后的缺口列表写回 `out/research/${session}/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。
+        allowed_tools: [WebSearch, WebFetch, Read, Write, Glob, Bash]
+        maxTurns: 20
+
+  # --- 补洞循环结束后读剩余缺口（达上限退出时 gaps 可能未清空，done 提示用户） ---
+  #    不带 when 守卫：early-exit 路径下 gaps.json 由 s1_exit_report 写 []，读取安全，
+  #    保证 _remaining_gaps 恒有定义（0），done 的插值不产生未定义变量 warning。
+  - id: s5b_final_gaps
+    title: "阶段5b · 汇总剩余缺口"
+    type: set
+    set:
+      _remaining_gaps: "${length(asArray(readJson('out/research/${session}/gaps.json')))}"
+
+  # --- 综合报告形式校验：必备章节存在（确定性，不依赖 agent 自觉） ---
+  #    「核心结论」兼容两种表述：prompt 要求的字面「核心结论」+ agent 改写时
+  #    常见的「核心问题的一句话答案」（实战中 s5b 补洞曾把标题改写导致误判 halt）。
+  #    s5b_fill 侧已同步加约束锁定标题字面，这里双保险。
+  - id: s5c_check_synthesis
+    title: "阶段5 · 综合报告形式校验"
+    tool: Bash
+    args:
+      command: "grep -E '^#+ .*(核心结论|核心问题的一句话答案|推荐方案)' out/research/${session}/06-synthesis.md || echo 'MISSING_SECTIONS'"
+    capture:
+      content: _syn_check
+
+  - id: s5c_assert_synthesis
+    title: "阶段5 · 综合报告校验闸门"
+    type: assert
+    condition: "(includes(_syn_check, '核心结论') || includes(_syn_check, '一句话答案')) && includes(_syn_check, '推荐方案')"
+    onFail: "out/research/${session}/06-synthesis.md 缺少「核心结论」或「推荐方案」章节--综合报告没有直接回答核心问题，不允许进入拼装。"
+
+  # ======================== Stage 6 · 拼装最终 report.md ========================
+  - id: s6_build_report
+    title: "阶段6/6 · 拼装最终报告"
+    tool: Bash
+    args:
+      command: |
+        set -euo pipefail
+        mkdir -p out/research/${session}/deliverable/scripts
+        OUT="out/research/${session}/deliverable/report.md"
+        # sec：cat 并把内容里所有标题降两级（# -> ###, ## -> ####, ...），
+        # 确保子文档 # 标题落在章节 ## 之下（章节用 ##，子文档 # 降两级成 ###，
+        # 子文档 ## 降两级成 ####），层级关系清晰不混乱。已知取舍：code fence 内
+        # 顶格的 "# 注释" 行也会被降级，纯视觉影响、不改语义。
+        sec() { sed -E 's/^(#+) /\1## /' "\$1"; }
+        {
+          # 标题不拼 inputs.topic：topic 是自由文本，引擎插值先于 shell 执行，
+          # 拼进命令体存在注入面（分号后接恶意命令）；主题信息已在正文 01-goal.md。
+          # depth 是 enum 白名单（light/standard/deep），无注入风险，可安全内插。
+          echo "# 技术研究报告"
+          echo ""
+          echo "_调研深度：${inputs.depth}　|　由 minimal-agent research 工作流自动生成_"
+          echo ""
+          echo "---"
+          echo ""
+          echo "## 1. 目标与边界"
+          echo ""
+          sec out/research/${session}/01-goal.md
+          echo ""
+          echo "---"
+          echo ""
+          echo "## 2. 领域地图"
+          echo ""
+          sec out/research/${session}/02-map.md
+          echo ""
+          echo "---"
+          echo ""
+          echo "## 3. 候选方案对比"
+          echo ""
+          sec out/research/${session}/03-options.md
+          echo ""
+          echo "---"
+          echo ""
+          echo "## 4. 深度调研"
+          echo ""
+          for f in out/research/${session}/04-deep-dive-*.md; do
+            if [ -f "\$f" ]; then
+              name="\$(basename "\$f" .md | sed 's/^04-deep-dive-//')"
+              echo "### \${name}"
+              echo ""
+              sec "\$f"
+              echo ""
+            fi
+          done
+          echo "---"
+          echo ""
+          echo "## 5. 动手验证"
+          echo ""
+          sec out/research/${session}/05-verification.md
+          echo ""
+          echo "---"
+          echo ""
+          echo "## 6. 综合结论与建议"
+          echo ""
+          sec out/research/${session}/06-synthesis.md
+          echo ""
+          if [ -f "out/research/${session}/07-learning-debt.md" ]; then
+            echo "---"
+            echo ""
+            echo "## 7. 学习债务与后续研究方向"
+            echo ""
+            sec out/research/${session}/07-learning-debt.md
+            echo ""
+          fi
+          echo "---"
+          echo ""
+          echo "_本报告由 minimal-agent research 工作流自动生成。验证脚本见 deliverable/scripts/ 及其 README。_"
+        } > "\$OUT"
+        echo "ok:\$OUT"
+    artifacts:
+      - "out/research/${session}/deliverable/report.md"
+    capture:
+      content: _report_out
+
+  # --- 精选验证脚本进 deliverable/scripts/（过程脚本留在 out/research/${session}/verify/ 不交付） ---
+  - id: s6_package
+    title: "阶段6 · 精选验证脚本打包交付"
+    onError: continue
+    agent: |
+      你在执行最后的「精选交付」步骤：把值得交付的验证脚本从 out/research/${session}/verify/ 精选、
+      清理后复制进 `out/research/${session}/deliverable/scripts/`。out/research/${session}/verify/ 里的失败/废弃/
+      探索性脚本是过程记录，**一律不进入交付目录**。
+
+      请先 Read：
+      - `out/research/${session}/05-verification.md`（哪些脚本验证通过、对应什么结论）
+      - `out/research/${session}/06-synthesis.md` 的「已通过脚本验证的关键结论」小节（哪些结论被最终引用）
+      - Glob `out/research/${session}/verify/*`（现有脚本清单）
+
+      ## 筛选规则（只有同时满足才复制）：
+      1. 该脚本对应的验证记录是「验证通过」；
+      2. 对应结论被 06-synthesis.md 引用了；
+      3. 脚本能独立用 bun run / node 运行。
+
+      ## 复制时做最小整理：
+      - 去掉纯调试用的打印；
+      - 文件头补 2-3 行注释：这个脚本验证什么结论、怎么运行、预期输出；
+      - 文件名保持/改成能看出验证内容的名字（如 verify_binance_kline_fetch.ts，不要 test3_v2.ts）。
+
+      ## 必须写 `out/research/${session}/deliverable/scripts/README.md`（脚本清单表）：
+      | 脚本文件名 | 对应结论（简述） | 运行方式 | 预期输出说明 |
+      |---|---|---|---|
+      交付目录里每个脚本都必须在表里有一行。
+      若没有可交付脚本（如提前退出路径、全部验证失败、全部待人工验证），
+      README 直接写明原因（例：「本次调研提前退出，未产生验证脚本」），不要硬凑。
+
+      ## 约束
+      - 只准往 out/research/${session}/deliverable/scripts/ 写，不改 out/research/${session}/verify/ 里的原件。
+      - 不确定某脚本是否该交付时，宁可不交付、在 README 里说明。
+    allowed_tools: [Read, Write, Bash, Glob]
+    maxTurns: 12
+    done_when: "fileExists('out/research/${session}/deliverable/scripts/README.md')"
+    artifacts:
+      - "out/research/${session}/deliverable/scripts/README.md"
+
+  - id: s6_assert_report
+    title: "阶段6 · 报告校验"
+    type: assert
+    condition: "fileExists('out/research/${session}/deliverable/report.md')"
+    onFail: "最终报告 out/research/${session}/deliverable/report.md 未能生成，请检查前面步骤。"
+
+  # --- 完成 ---
+  - id: done
+    title: "调研完成"
+    type: echo
+    message: |
+      ✅ 技术调研完成！
+
+      主题：${inputs.topic}
+      深度：${inputs.depth}
+
+      ${_remaining_gaps > 0 ? '⚠️ 补洞循环达到上限退出，仍有 ' + _remaining_gaps + ' 条缺口未补全（见 out/research/${session}/gaps.json 与 06-synthesis.md 的「调研局限」），结论使用时注意置信度。' : '✅ 调研缺口已全部收敛。'}
+
+      产物清单（研究过程在 out/research/${session}/，交付物在 out/research/${session}/deliverable/）：
+      - out/research/${session}/01-goal.md            问题定义
+      - out/research/${session}/02-map.md             领域地图
+      - out/research/${session}/03-options.md         方案对比
+      - out/research/${session}/04-deep-dive-*.md     各分支深度调研（每分支一个文件）
+      - out/research/${session}/05-verification.md    动手验证记录
+      - out/research/${session}/06-synthesis.md       综合结论
+      - out/research/${session}/07-learning-debt.md   学习债务清单
+      - out/research/${session}/branches.json         深度调研分支配置
+      - out/research/${session}/gaps.json             调研缺口列表
+      - out/research/${session}/early-exit.json       提前退出判定
+      - out/research/${session}/verify/               验证脚本（含失败尝试，过程保留）
+      - out/research/${session}/deliverable/report.md      ★ 汇总报告（请读这个）
+      - out/research/${session}/deliverable/scripts/       精选验证脚本 + README 清单
+
+      建议直接打开 out/research/${session}/deliverable/report.md 阅读最终成果。