minimal-agent 0.12.0 → 0.14.0

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。

package/workflows/research/prompts/s6-package.md

@@ -0,0 +1,32 @@
+你在执行最后的「精选交付」步骤：把值得交付的验证脚本从 `{{dir}}/verify/` 精选、
+清理后复制进 `{{dir}}/deliverable/scripts/`。
+
+`{{dir}}/verify/` 里的失败/废弃/探索性脚本是**过程记录，一律不进入交付目录**。
+
+请先 Read：
+- `{{dir}}/05-verification.md`（哪些脚本验证通过、对应什么结论）
+- `{{dir}}/06-synthesis.md` 的「三b、已通过脚本验证的关键结论」小节（哪些结论被最终引用）
+- Glob `{{dir}}/verify/*`（现有脚本清单）
+
+## 筛选规则（**三条同时满足**才复制）
+1. 该脚本对应的验证记录是「验证通过」；
+2. 对应结论被 06-synthesis.md 引用了；
+3. 脚本能独立用 `bun run` / `node` 运行。
+
+## 复制时做最小整理
+- 去掉纯调试用的打印；
+- 文件头补 2-3 行注释：这个脚本验证什么结论、怎么运行、预期输出；
+- 文件名要能看出验证内容（如 `verify_binance_kline_fetch.ts`，不要 `test3_v2.ts`）。
+
+## 必须写 `{{dir}}/deliverable/scripts/README.md`（脚本清单表）
+
+| 脚本文件名 | 对应结论（简述） | 运行方式 | 预期输出说明 |
+|---|---|---|---|
+
+交付目录里每个脚本都必须在表里有一行。
+若没有可交付脚本（提前退出路径 / 全部验证失败 / 全部待人工验证），
+README 直接写明原因（例：「本次调研提前退出，未产生验证脚本」），**不要硬凑**。
+
+## 约束
+- 只准往 `{{dir}}/deliverable/scripts/` 写，**不改 `{{dir}}/verify/` 里的原件**。
+- 不确定某脚本是否该交付时，**宁可不交付**、在 README 里说明。

package/workflows/research/scripts/build-report.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * workflows/research/scripts/build-report.mjs —— 把各阶段产物拼装成最终报告
+ *
+ * 用法：node workflows/research/scripts/build-report.mjs <研究目录> <depth>
+ *
+ * 自 research.yaml 的 s6_build_report 迁移。原来是一大段 bash：
+ *   sec() { sed -E 's/^(#+) /\1## /' "$1"; }
+ * 改写成 node 的三个理由（不是为了好看）：
+ *  ① **可移植**：原版依赖 `sed -E`、`set -euo pipefail`、`basename`，Windows 上要靠
+ *     Git Bash 才有；宿主回落 cmd 时整段直接不可用（本项目为此踩过坑）。
+ *  ② **可单独跑**：拼装出问题时 `node scripts/build-report.mjs out/research/x standard`
+ *     一条命令复现，不用启动整条工作流等前面五个阶段跑完。
+ *  ③ **注入面为零**：原版把 depth 内插进 shell 命令体（虽是 enum 白名单所以当时安全），
+ *     这里根本不经过 shell。
+ *
+ * 标题降级的取舍与原版一致：子文档的 `#` 降两级成 `###`，落在章节 `##` 之下。
+ * 已知副作用：代码块里顶格的 `# 注释` 也会被降级 —— 纯视觉影响，不改语义。
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const [dir, depth = 'standard'] = process.argv.slice(2);
+if (!dir) {
+  console.error('用法：build-report.mjs <研究目录> [depth]');
+  process.exit(1);
+}
+
+/** 读文件并把所有标题降两级；文件不存在返回占位说明而不是空串。 */
+function section(file) {
+  if (!existsSync(file)) {
+    return `> ⚠️ 缺少 \`${basename(file)}\` —— 该阶段可能被跳过或失败，详见 progress.md。`;
+  }
+  return readFileSync(file, 'utf8').replace(/^(#+) /gm, '$1## ');
+}
+
+const out = [];
+const push = (...lines) => out.push(...lines);
+const rule = () => push('', '---', '');
+
+push('# 技术研究报告', '');
+push(`_调研深度：${depth}　|　由 minimal-agent research 工作流自动生成_`);
+rule();
+
+push('## 1. 目标与边界', '');
+push(section(join(dir, '01-goal.md')));
+rule();
+
+push('## 2. 领域地图', '');
+push(section(join(dir, '02-map.md')));
+rule();
+
+push('## 3. 候选方案对比', '');
+push(section(join(dir, '03-options.md')));
+rule();
+
+push('## 4. 深度调研', '');
+let dives = [];
+try {
+  dives = readdirSync(dir)
+    .filter((f) => f.startsWith('04-deep-dive-') && f.endsWith('.md'))
+    .sort();
+} catch {
+  /* 目录读不到就当没有深挖文件 */
+}
+if (dives.length === 0) {
+  push('> 本次调研未产生深度调研分支（可能走了提前退出路径）。', '');
+} else {
+  for (const f of dives) {
+    push(`### ${f.replace(/^04-deep-dive-/, '').replace(/\.md$/, '')}`, '');
+    push(section(join(dir, f)), '');
+  }
+}
+rule();
+
+push('## 5. 动手验证', '');
+push(section(join(dir, '05-verification.md')));
+rule();
+
+push('## 6. 综合结论与建议', '');
+push(section(join(dir, '06-synthesis.md')));
+
+if (existsSync(join(dir, '07-learning-debt.md'))) {
+  rule();
+  push('## 7. 学习债务与后续研究方向', '');
+  push(section(join(dir, '07-learning-debt.md')));
+}
+
+rule();
+push('_本报告由 minimal-agent research 工作流自动生成。验证脚本见 deliverable/scripts/ 及其 README。_');
+
+const target = join(dir, 'deliverable', 'report.md');
+mkdirSync(join(dir, 'deliverable', 'scripts'), { recursive: true });
+writeFileSync(target, `${out.join('\n')}\n`, 'utf8');
+
+// 输出给调用方解析：路径 + 拼进去了几个深挖分支
+console.log(JSON.stringify({ ok: true, path: target, dives: dives.length }));