minimal-agent 0.12.0 → 0.13.0

package/workflows/ralph-loop.yaml

@@ -106,7 +106,9 @@ steps:
           learnings_text: "${learnings_text}- ${extracted_learning}\n"
         when: "extracted_learning != ''"
 
-      # 存档副本落盘（事后排查用；状态目录随成功归档为 ralph-loop.done）
+      # 存档副本落盘（事后排查用；learnings.md 是 workflow 级共享学习档案，
+      # 写在 ralph-loop/ 父目录下，不随任务实例归档改名——实例归档为
+      # .minimal-agent-workflow/ralph-loop/<taskId>.done/，档案持续累积跨轮存活）
       - id: save_learning
         title: "教训存档落盘"
         tool: Write

package/workflows/research.md

@@ -0,0 +1,449 @@
+# 技术研究 Agent 工作流设计文档
+
+> 目标：把人类专家做技术研究时的思维方式（目标锚定、边界控制、多方案对比、边动手边验证、元认知复盘）固化成一套可执行的 agent 工作流，而不是简单的 "search → summarize"。
+
+---
+
+## 1. 设计理念
+
+现有 agent 自带的 research 工具普遍存在的问题：
+
+- **无目标锚定**：拿到 query 直接开始搜索，容易在无关分支上发散，也容易漏掉用户真正关心的约束条件。
+- **无边界控制**：遇到陌生概念就无限展开搜索，既浪费 token，也容易迷失在工具层细节里（对应我们讨论的"递归爆炸"问题）。
+- **只读不做**：纯靠搜索结果堆砌结论，没有用脚本验证过任何一个关键论断，容易产生"看起来对但经不起推敲"的结论。
+- **单一答案幻觉**：把搜到的第一个/最热门的方案当作唯一答案，而不是先建立候选方案集合再做取舍（对应"多个并存的技术方案"问题）。
+- **无复盘机制**：任务结束就结束，不检查产出是否真的回答了用户最初的问题。
+- **把选型责任错误地推给用户**：一上来就问用户"你想用哪个框架/算法"，但用户往往正是因为不了解该领域才发起研究请求，这类判断应该是研究的产出，而不是研究的输入。
+
+本工作流用你现有的工具（`ask`、`web_search`、`web_fetch`、`write`/`edit`、`bun run`/脚本执行、`fork_agent`）组合实现六个阶段，每个阶段有明确的输入、输出、边界和退出条件。
+
+> **运行时约束（贯穿全文档，优先级高于其他实现细节）**：本系统基于 bun 运行时，具备 Node.js 兼容性，但**不保证有 Python 环境**。因此阶段4所有验证脚本必须是 **TypeScript / JavaScript**（`.ts` / `.js`），用 `bun run xxx.ts` 直接执行，不需要额外装环境；严禁编写 Python 脚本或依赖 `pip install` 的验证方式，避免脚本因缺少解释器/依赖而无法运行，白白浪费时间预算。
+
+### 工具 → 阶段映射
+
+| 工具 | 主要承担的阶段 | 作用 |
+|---|---|---|
+| `ask` | 阶段 0（目标澄清）、阶段 5（结果确认） | 把"主题词"逼成"问题句"，锚定深度和边界 |
+| `web_search` / `web_fetch` | 阶段 1（广度扫描）、阶段 2（方案对比） | 建立坐标系，填充对比矩阵 |
+| `fork_agent` | 阶段 3（深度分叉调研） | 有界递归的具体实现：每个分叉子 agent 只负责一个边界明确的子问题 |
+| `write` / `edit` / `bun run`（执行 ts/js 脚本） | 阶段 4（动手验证循环） | 避免闭门造车，用最小可行脚本验证关键论断（严禁 Python，统一用 ts/js） |
+| 主 agent 自身 | 阶段 5（综合、整理交付与复盘） | 汇总、去冗余、检查是否回答了原始问题、筛选清理脚本并打包 deliverable/ 目录 |
+
+---
+
+## 2. 总体流程图
+
+```mermaid
+flowchart TD
+    A["阶段0 目标澄清与边界锚定<br/>(ask)"] --> B["阶段1 广度扫描/建立坐标系<br/>(web_search + web_fetch)"]
+    B --> C["阶段2 候选方案对比矩阵<br/>(web_search + web_fetch)"]
+    C --> D{"需要深挖的分支<br/>是否明确？"}
+    D -- 否 --> A2["回到阶段0/1<br/>补充澄清"] --> B
+    D -- 是 --> E["阶段3 有界深度分叉调研<br/>(fork_agent × N)"]
+    E --> F["阶段4 动手验证循环<br/>(write/edit + bun run ts/js 脚本)"]
+    F --> G{"验证结果<br/>是否推翻假设？"}
+    G -- 是 --> C
+    G -- 否 --> H["阶段5 综合与元认知复盘<br/>(主agent汇总 + ask确认)"]
+    H --> I{"是否满足<br/>研究纲领的成功标准？"}
+    I -- 否 --> A
+    I -- 是 --> J["打包 deliverable/ 目录<br/>(report.md + 精选脚本)并交付"]
+```
+
+关键点：这不是一条直线，**阶段4和阶段5都可能触发回退**——这正是对应我们之前讨论的"元认知复盘"和"实践反馈修正认知"，不是走完流程就结束。
+
+---
+
+## 3. 工作区文件结构
+
+每次研究任务分配一个**隔离的任务根目录**，根目录下再分为 `workspace/`（过程文件，不直接给用户看）和 `deliverable/`（最终交付物，唯一会被展示/提交给用户的部分）。这样设计有两个目的：一是支持多个研究任务并行而不互相污染，二是让"给 agent 用的外部记忆"和"给用户看的成果"彻底分开，避免把中间失败尝试、废弃脚本也一股脑丢给用户。
+
+### 3.1 任务隔离（支持并行）
+
+```
+research_tasks/
+├── 20260816_143012_crypto-quant-strategy/     # task_id = 时间戳 + 简短slug，保证唯一且可读
+│   ├── workspace/
+│   └── deliverable/
+├── 20260816_150221_yolo-vs-vlm-detection/      # 另一个并行任务，完全隔离，互不可见
+│   ├── workspace/
+│   └── deliverable/
+└── ...
+```
+
+规则：
+
+1. 任务开始时（阶段0）就生成 `task_id`（建议 `{YYYYMMDD_HHMMSS}_{英文slug}`，slug 从问题句提炼，避免中文/空格导致路径问题），后续所有阶段、包括所有 `fork_agent` 子任务，**只允许在自己 task_id 目录下读写**，禁止跨任务目录访问或写入，这是防止并行任务互相污染的硬性规则。
+2. `fork_agent` 产生的子 agent，各自的草稿/中间搜索记录写在 `workspace/03_deep_dive/<branch>/` 各自的子文件夹里（而不是直接混在 `03_deep_dive/` 根下），最终只把整理好的 `<branch>_report.md` 留在 `03_deep_dive/` 层级，子文件夹内容视为该分支自己的"草稿区"。
+3. 用户的原始输入、对话记录中涉及的关键信息，落盘进 `workspace/00_charter.md`，不要只留在对话上下文里——一旦任务需要跨会话恢复或被审计，文件才是唯一可靠来源。
+
+### 3.2 目录结构总览
+
+```
+research_tasks/<task_id>/
+├── workspace/                          # 过程文件：agent的外部记忆，不直接交付
+│   ├── 00_charter.md                   # 研究纲领：问题句、场景约束、成功标准（阶段0产出）
+│   ├── 01_territory_map.md             # 领域地图：术语表、候选方案清单、资源索引（阶段1产出）
+│   ├── 02_comparison_matrix.md         # 候选方案对比矩阵（阶段2产出）
+│   ├── 03_deep_dive/
+│   │   ├── <branch_1>/                 # 每个fork子agent的草稿区（搜索记录、临时笔记）
+│   │   ├── <branch_2>/
+│   │   ├── <branch_1>_report.md        # 整理后的分支调研报告
+│   │   └── <branch_2>_report.md
+│   ├── 04_experiments/                 # 全部验证脚本（.ts/.js，用bun运行），含失败/废弃尝试，全部保留以便追溯
+│   │   ├── <script_001>.ts
+│   │   ├── <script_002_failed>.ts      # 失败/废弃的尝试也保留在这里，不删除，但不会进入交付目录
+│   │   └── results_log.md              # 每次实验的假设、脚本、真实耗时、真实输出、结论
+│   ├── 05_learning_debt.md             # 学习债务清单：边界外冒出来但未深挖的问题
+│   └── 07_pending_human_verification.md  # 因耗时过长无法由agent验证、需人工验证的清单
+└── deliverable/                        # 唯一交付给用户的目录，阶段5打包产出
+    ├── report.md                       # 主报告：结论、推荐方案、证据、脚本清单等
+    └── scripts/                        # 从 workspace/04_experiments 精选、清理后的脚本（.ts/.js）
+        ├── <script_a>.ts
+        └── <script_b>.ts
+```
+
+> 后续各阶段描述中出现的 `00_charter.md`、`02_comparison_matrix.md` 等裸文件名，均指 `workspace/` 下对应文件；只有 `deliverable/` 是交付产物，其打包规则见阶段5。
+
+---
+
+## 4. 分阶段详细设计
+
+### 阶段 0：目标澄清与边界锚定（ask）
+
+**目的**：把用户的原始请求从"主题词"转化为"问题句 + 边界 + 成功标准"，这是防止后续递归失控和方案发散的锚点。这一步不做任何搜索，只对话。
+
+**输出**：`00_charter.md`
+
+**核心原则：只问目标和隐藏条件，绝不问技术方案本身。**
+
+用户往往并不知道有哪些候选技术方案、也不知道该怎么在方案之间取舍——这正是需要 agent 去研究的部分。如果阶段0问用户"你想用哪个框架/哪种算法"，等于让不了解该领域的人替 agent 做本该由研究得出的判断，这是本末倒置。阶段0要问的是**决定"哪个方案适配"的隐藏变量**（目标、场景约束、资源上限），至于具体选哪个技术方案，由 agent 在阶段1-3研究之后自己给出并说明理由，用户只在阶段5对最终建议做确认或提出场景层面的修正。
+
+| 该问 | 不该问 |
+|---|---|
+| 你最终要达成的目标是什么？成功的标准是什么？ | 你想用什么模型/框架/算法？ |
+| 部署环境、延迟、预算、数据规模等硬约束是什么？ | 你倾向于方案A还是方案B？ |
+| 交付物是报告、能跑的代码，还是决策建议？ | 这个技术细节你想怎么实现？ |
+| 团队现有技术栈/已排除的方向（如"不能用闭源模型"）？ | （技术选型问题全部留给agent） |
+
+**必须澄清的四个维度**（用 `ask` 工具，避免一次问太多，2-3 轮为宜）：
+
+1. **问题句**：用一句话描述要回答的具体问题，而不是研究主题（"哪种技术路线最适合我这个场景，为什么"，而不是"研究一下A"）。
+2. **交付物形态**：技术选型报告 / 可运行的验证代码 / 学习笔记 / 决策建议，不同形态决定阶段4要投入多少动手验证。
+3. **场景约束（硬条件）**：部署环境、延迟/吞吐要求、预算、数据规模、团队现有技术栈、明确排除的方向（如合规要求不能用某类服务）——这些是阶段2对比矩阵的打分标准来源，也是agent最终选型的依据。
+4. **已知信息**：用户是否已经了解某些候选方案、是否已经踩过坑，避免重复劳动，但不代表要用户来做最终选择。
+
+**系统提示词模板**：
+
+```
+你现在处于研究任务的"目标澄清"阶段，唯一的目标是把用户的请求转化为一份清晰的研究纲领，
+禁止在本阶段调用 web_search / web_fetch / fork_agent，只使用 ask 与用户对话。
+
+请遵循以下原则：
+1. 如果用户的请求是一个主题词（如"研究一下端到端自动驾驶"），追问把它转化为一个问题句
+   （如"针对我的场景，端到端范式相对模块化pipeline是否值得投入，该选哪条技术路线"）。
+2. 严禁向用户询问具体技术方案/框架/算法的选择——用户大概率不了解该领域的候选方案，
+   这类判断属于agent的研究职责，不是用户澄清的内容。你只问能决定"哪个方案适配"的
+   隐藏变量：目标、部署场景、性能与资源约束、团队技术栈、已排除的方向。
+3. 每轮最多问1-2个关键问题，优先问对后续研究方向影响最大的场景约束，不要一次性抛出清单。
+4. 深度边界不需要问用户"你希望多深入"，而是由agent在阶段1扫描完地图后，自己判断
+   哪些分支与目标强相关、哪些是工具层，写入charter草案，阶段5时再向用户展示这个
+   判断是否合理，用户只做确认/修正，不做从零选择。
+5. 澄清完成后，生成 00_charter.md，包含：问题句、交付物形态、场景约束、已知信息、
+   成功标准（即"什么样的结果算是回答清楚了这个问题"）。明确写一行：
+   "技术方案选择由本次研究产出，不由用户预先指定。"
+6. 把 charter 内容展示给用户做最终确认，用户确认后才能进入下一阶段。
+```
+
+**退出条件**：`00_charter.md` 写完并经用户确认。
+
+---
+
+### 阶段 1：广度扫描 / 建立坐标系（web_search + web_fetch）
+
+**目的**：不深入，只建立地图——术语表、该领域公认的候选方案/流派、经典资源索引。这一步严格 timebox，避免过早深挖某一个方案。
+
+**输出**：`01_territory_map.md`
+
+**系统提示词模板**：
+
+```
+你现在处于"广度扫描"阶段，目标是建立整个领域的地图，而不是理解任何一个方案的细节。
+
+严格遵守：
+1. 本阶段搜索预算上限为 N 次（建议 8-15 次，按 charter 中问题的复杂度调整），超过预算必须停止
+   并进入下一阶段，即使地图还不完整——广度扫描允许留白，深度会在阶段3补齐。
+2. 每次搜索聚焦一个独立维度（如"该领域有哪些流派"、"该领域权威综述"、"该领域最活跃的开源实现"），
+   不要用同一个宽泛query反复搜索。
+3. 输出必须包含：
+   - 术语表（术语 + 一句话定义，暂不追求完全理解，只求眼熟）
+   - 候选方案/流派清单（每个方案一句话描述 + 1-2个代表性来源链接）
+   - 资源索引（该领域公认的综述/课程/权威仓库，标注哪个适合作为阶段3精读对象）
+4. 不要在本阶段对任何方案下结论或做推荐——建立地图和做判断是两个阶段，混在一起会导致
+   还没扫完全貌就锚定在第一个搜到的方案上。
+5. 结合 00_charter.md 中的边界设定，如果搜索过程中发现某个分支明显属于"工具层"，
+   在术语表里标注即可，不展开搜索它的实现细节。
+```
+
+**退出条件**：术语表和候选方案清单完成，达到搜索预算上限。
+
+---
+
+### 阶段 2：候选方案对比矩阵（web_search + web_fetch）
+
+**目的**：这是应对"多个并存的技术方案"问题的核心步骤——不是孤立地学习每个方案，而是用同一组维度横向对比，差异点本身就是最重要的信息。
+
+**输出**：`02_comparison_matrix.md`
+
+**系统提示词模板**：
+
+```
+你现在处于"方案对比"阶段，目标是把阶段1找到的候选方案放进同一张表里对比，而不是逐个孤立研究。
+
+步骤：
+1. 从 00_charter.md 的约束条件中提取对比维度（如：性能上限、工程成熟度、可解释性、数据/算力
+   需求、社区生态、与用户现有技术栈的兼容性）。维度必须是所有候选方案都能填的，不要出现
+   "只有A方案有这一栏"的情况。
+2. 对每个候选方案，针对性搜索填充这些维度的信息，标注信息来源。
+3. 如果某个维度缺乏公开可靠信息，明确标注"信息不足"，不要编造或用弱相关信息强行填充。
+4. 输出对比矩阵后，基于 00_charter.md 的成功标准，给出一个初步的"建议深入方向"排序，
+   但明确这只是初筛，不是最终结论——真正的判断要在阶段3、4拿到更扎实的证据后才下。
+5. 把初筛结果和矩阵展示给用户（可选择通过ask确认），如果用户对边界或候选集有异议，
+   回到阶段0/1调整，不要自己擅自替用户做最终技术决策。
+```
+
+**退出条件**：对比矩阵完成，明确了阶段3需要 fork_agent 深挖的具体分支（通常2-4个）。
+
+---
+
+### 阶段 3：有界深度分叉调研（fork_agent）
+
+**目的**：这是"递归学习"问题的正式解法——把无界递归变成若干个有界的并行子任务。每个 fork 出去的子 agent，只负责一个边界明确的子问题，不允许无限往下钻。
+
+**关键设计**：主 agent 在 fork 之前，必须为每个子任务显式写清楚：子问题、深度上限、允许使用的工具、输出格式。这四项缺一不可——没有深度上限的 fork 只是把递归爆炸问题转移给了子 agent。
+
+**输出**：`03_deep_dive/<branch>_report.md`（每个 fork 一份）
+
+**Fork 子任务的系统提示词模板**（主 agent 生成，每次 fork 时填充占位符）：
+
+```
+你是一个专注于单一子问题的深度调研子agent，你的调研范围严格限定如下，不允许扩展：
+
+【子问题】：{具体问题句，从主charter和对比矩阵中派生，不是笼统主题}
+【所属研究纲领摘要】：{00_charter.md 的问题句 + 成功标准，让子agent知道自己的调研最终服务于什么}
+【深度上限】：{例如"最多下钻2层：先理解方案的核心设计动机和关键机制，若涉及具体实现细节
+  （如底层库/硬件），只需要接口级理解，不需要读懂源码实现"}
+【工具范围】：仅使用 web_search / web_fetch，不允许再次 fork_agent（防止递归失控）
+【搜索预算】：最多 {N} 次搜索
+
+执行要求：
+1. 先用1-2次搜索确认这个子问题当前是否有明确公开答案，若已有权威综述直接回答，不要重复造轮子。
+2. 用费曼技巧组织输出：假设读者是同领域但不熟悉这个子方向的人，先给结论，再给支撑论据，
+   最后给关键取舍/局限性。
+3. 如果调研过程中冒出超出【深度上限】的子问题（比如需要理解更底层的实现），不要展开搜索，
+   把它记录在报告末尾的"未深挖问题"小节里，交还给主agent处理（可能进入学习债务清单，
+   也可能是下一轮值得单独fork的分支）。
+4. 报告必须包含：结论摘要（3-5句话）、支撑论据、关键取舍/局限性、信息来源列表、未深挖问题。
+5. 报告长度控制在可被主agent快速吸收的范围内（建议不超过800字），细节可以在来源链接里，
+   不需要把所有搜索结果都塞进报告。
+```
+
+**主 agent 侧的调度原则**：
+
+```
+在阶段2产出的候选方案/待深挖分支基础上，为每个分支生成上面的 fork 子任务提示词，
+可以并行 fork 多个子agent。fork 之后：
+1. 等待所有子agent返回，不要在只有部分结果时就仓促综合。
+2. 检查每份报告末尾的"未深挖问题"，判断是否有任何一条会实质性影响最终结论——
+   会的话补一轮fork或标记为阶段4必须验证的重点；不会的话直接归入 05_learning_debt.md，
+   不再处理。
+3. 不要把子agent报告原样拼接当作最终结果，阶段5还需要综合与去冗余。
+```
+
+**退出条件**：所有 fork 出的分支报告完成，且未深挖问题中没有实质性阻塞项。
+
+---
+
+### 阶段 4：动手验证循环（write / edit + bun run 执行 ts/js 脚本）
+
+**目的**：这是避免"闭门造车"的核心步骤。凡是阶段2、3中出现的**可验证的具体论断**（性能数字、API 行为、某个算法的实际输出特征等），都应该用最小脚本实际跑一遍，而不是只信搜索结果里的二手描述。同样重要的是：**这一步必须有严格的时间上限，绝不能因为验证一个耗时任务把整个研究流程卡死**。
+
+**输出**：`04_experiments/` 下的脚本 + `results_log.md` + （超时任务）`07_pending_human_verification.md`
+
+**硬性语言规则（必须写入系统提示词，不可省略）**：
+
+- 所有验证脚本一律用 **TypeScript 或 JavaScript** 编写，用 `bun run <script>.ts` 执行——这是运行时环境的硬约束（系统基于 bun，具备 Node.js 兼容性，但不保证有 Python 及其依赖），不是风格偏好。
+- 遇到"这个验证在 Python 生态里更容易实现"的情况（比如某个论断对应的库只有 Python 版本），不要因此改用 Python，而是优先寻找等价的 JS/TS 方案：直接调用目标服务的 HTTP API（用 `fetch`）、使用对应功能的 npm 包、或者把验证范围收窄到"用 fetch 直接验证接口/数据行为"这个更底层但语言无关的层面。
+- 如果确实找不到任何 JS/TS 可行的验证路径（比如强依赖某个只有 Python 绑定的专用库），不要勉强执行会失败的脚本，直接归入 `07_pending_human_verification.md`，注明"受限于运行时环境（无Python），建议人工在Python环境中验证"，不要浪费时间预算在会报错的环境搭建上。
+
+**硬性时间规则（必须写入系统提示词，不可省略）**：
+
+- 每个验证脚本设一个默认执行时限（建议 **60 秒**，用户可在charter里调整，但必须有默认值），超时立即终止，不重试、不加大规模重跑。
+- 判断一个论断能否在时限内验证，优先用"缩小规模"的方式让它可验证，而不是直接放弃：
+  - 数据规模缩小（下载几十条历史行情而不是几年的数据、下载5-10张图片而不是整个数据集、处理1个点云/图像帧而不是整个序列）。
+  - 计算规模缩小（跑1个epoch/1个batch而不是完整训练、用小模型/量化版本代替完整大模型做接口验证）。
+  - 只验证"链路能不能跑通、接口行为是否符合预期"，不追求验证最终性能指标（性能指标类论断如果必须大规模计算才能验证，直接归为待人工验证）。
+- 明确排除默认不测试的类别：模型训练/微调（尤其LLM）、大规模历史数据回测、任何预计超过时限的任务——这些一律不在阶段4执行，直接写入 `07_pending_human_verification.md`，作为下一轮研究的输入，而不是阶段4的失败项。
+
+**系统提示词模板**：
+
+```
+你现在处于"动手验证"阶段，目标是用最小可行、且必须在时间上限内完成的方式验证前面阶段中的关键论断。
+
+【语言与运行时约束】：所有验证脚本必须是 TypeScript 或 JavaScript，用 `bun run <script>.ts` 执行。
+系统运行时基于 bun（兼容 Node.js），不保证有 Python 环境，严禁编写 Python 脚本或依赖
+pip 安装任何东西。如果某个验证在 Python 生态里更容易做，优先改用等价的 JS/TS 方案
+（如直接用 fetch 调用目标HTTP API、使用对应功能的 npm 包）；如果确实没有可行的 JS/TS
+路径，不要勉强执行，直接归入待人工验证清单（见第4步）。
+
+【全局时限】：单个验证脚本执行时间不得超过 {T_max}秒（默认60秒）。超时必须立即终止进程，
+不允许重试、不允许放宽限制继续等待，这是硬性规则，优先级高于"想把这个论断验证完整"。
+
+判断是否需要验证、以及怎么验证，按下面的决策顺序执行：
+1. 这个论断是否是最终结论的关键支撑？不重要的细节不验证，直接跳过。
+2. 这个论断能否设计一个"缩小规模但保留核心逻辑"的代理实验，在时限内跑完？
+   - 数据类：只取小样本（几条记录/几张图/几帧点云），验证"数据能否成功获取、格式是否符合预期、
+     处理链路是否跑通"，不追求验证大规模下的性能表现。
+   - 算法/接口类：验证"给定输入，输出的形状/类型/关键特征是否符合预期"，不追求端到端最优结果。
+   - 如果代理实验设计后预计仍会超时（如模型训练、大规模回测、任何依赖长时间等待或大量算力的任务），
+     禁止执行，直接跳到第4步。
+3. 对能在时限内跑完的代理实验：
+   a. 明确假设：把论断改写成一个可证伪的具体陈述。
+   b. 写最小 TypeScript/JavaScript 脚本，运行前先估算预计耗时，超过时限的调整规模直到预计能在时限内完成。
+   c. 运行并完整记录真实输出（含报错信息）。
+   d. 结果写入 results_log.md：假设 / 脚本路径 / 实际运行时间 / 真实输出 / 结论（验证通过 or 假设被推翻）。
+   e. 假设被推翻时，标注这会影响哪个对比结论或哪份深度调研报告，交还主agent评估是否要回到阶段2。
+4. 对无法在时限内验证的论断（训练类、大规模回测类、任何预期超时的任务），以及找不到
+   JS/TS 可行验证路径（强依赖仅有Python绑定的专用库）的论断：
+   不要尝试执行，写入 07_pending_human_verification.md，内容包括：
+   - 需要验证什么、为什么agent当前跑不了（预计耗时/算力需求/运行时环境限制）
+   - 如果用户要自己验证，建议的验证方法/脚本框架/需要准备的资源（此时可以建议用户在
+     自己的Python环境中验证，不受本系统运行时约束限制）
+   - 这一项如果不验证，对最终结论的置信度有多大影响（高/中/低）
+   这份清单本身就是下一轮调研的输入，不是阶段4的失败产出。
+
+禁止事项：
+- 不要为了"看起来完整"而验证不影响最终结论的细枝末节。
+- 不要为了让一个耗时任务"验证成功"而不断放宽时限或降低验证标准到失去意义。
+- 不要跳过时限检查直接执行——任何脚本执行前都要有耗时预估。
+```
+
+**退出条件**：所有关键论断要么在时限内完成验证并记录真实结果，要么明确进入 `07_pending_human_verification.md`。不允许出现"因为怕超时就完全不验证、也不记录"的空白状态。
+
+---
+
+### 阶段 5：综合、整理交付与元认知复盘（主 agent + ask 确认）
+
+**目的**：整合前面所有产物，打包出唯一交付给用户的 `deliverable/` 目录，同时做一次"回头看"——检查最终结论是否真的回答了阶段0的问题句，而不是自然而然地跑完流程就交差。
+
+**输出**：`deliverable/report.md` + `deliverable/scripts/`（精选后的验证脚本）
+
+**脚本筛选与清理规则**：`workspace/04_experiments/` 里保留了所有验证脚本，包括失败、废弃、探索性的尝试——这些是过程记录，**不能原样搬进交付目录**。打包时按以下标准筛选：
+
+- **保留并清理进 `deliverable/scripts/` 的情况**：脚本对应的论断最终被写进了报告的"已通过脚本验证"小节，且该脚本本身能独立用 `bun run` 运行、逻辑清晰。搬入前要做最小整理：去掉调试用的打印语句、补一行文件头注释说明这个脚本验证了什么/怎么运行，文件命名要能让用户从名字看出对应哪条结论（如 `verify_binance_kline_fetch.ts`，而不是 `test3_final_v2.ts`）。
+- **不带脚本，只在 report.md 里用文字说明原因的三种情况**（这三种都正常，不是缺陷）：
+  1. **过于简单，无需验证**：论断本身是常识性/文档明确注明的行为，跑脚本验证的边际价值很低（如"某开源库支持pip安装"），报告里直接说明"未附验证脚本：该结论为公开文档明确说明的基础事实，验证价值低"。
+  2. **过于复杂，难以端到端验证**：结论依赖的是大规模训练/长期运行/真实资金等无法在 agent 时限内完成的验证（对应阶段4流程里进入 `07_pending_human_verification.md` 的部分），报告里说明"未附验证脚本：需要{具体资源/时间}，已列入待人工验证清单及建议验证方法"。
+  3. **无法验证**：受限于工具权限、外部依赖（如需要用户自己的交易账户/私有数据）等，agent 本身不具备验证条件，报告里说明"未附验证脚本：受限于{具体原因}，无法由agent独立验证，建议{替代验证方式}"。
+- 探索过程中产生的**失败尝试和废弃脚本一律不进入 `deliverable/`**，它们留在 `workspace/04_experiments/` 里作为过程记录，用户默认不会看到，但如果用户明确要求"我要看所有尝试过程"，可以按需从 workspace 里额外提供。
+
+**系统提示词模板**：
+
+```
+你现在处于"综合、整理交付与复盘"阶段，目标是产出 deliverable/ 目录，并对整个研究过程做一次质量检查。
+
+综合步骤：
+1. 重新读一遍 workspace/00_charter.md 的问题句和成功标准。
+2. 整合 workspace/02_comparison_matrix.md、03_deep_dive/ 的所有报告、04_experiments/ 的验证结果、
+   07_pending_human_verification.md，去除重复信息，按 charter 中要求的交付物形态组织。
+3. report.md 结构必须包含以下部分，且严格区分"已验证"与"未验证"内容，不允许混写：
+   - 结论先行（3-5句话直接给出针对用户场景的明确技术方案推荐，不是罗列选项）
+   - 推荐方案与理由（附对比矩阵精简版，说明为什么这个方案匹配charter中的场景约束）
+   - **已通过脚本验证的关键结论**：逐条列出，格式固定为：
+       "结论陈述 —— 已验证（脚本：scripts/xxx.ts，运行方式：bun run xxx.ts，运行耗时：Xs，实际输出：...）"
+     路径必须指向 deliverable/scripts/ 下打包后的相对路径，不要写 workspace 内部路径
+     （用户拿到的是 deliverable/ 目录，看不到 workspace）。语气要肯定自信，不要加
+     "可能/大概/理论上"这类模糊词——不确定的内容不应该出现在"已验证"小节里。
+   - **未附脚本的结论说明**：按上面三种情况（过于简单/过于复杂/无法验证）逐条说明原因，
+     格式："结论陈述 —— 未验证（原因：...；如需验证建议：...）"。
+   - **验证脚本清单表**：汇总 deliverable/scripts/ 下的所有文件，表格列为
+     "脚本文件名 | 对应结论（简述） | 运行方式 | 预期输出说明"，让用户能直接对照报告
+     去运行某个脚本复现验证过程。
+   - 局限性与未决问题（来自 05_learning_debt.md 中确实重要但未深挖的部分）
+   - 参考资料列表
+
+4. 按【脚本筛选与清理规则】把有价值的脚本从 workspace/04_experiments/ 复制、清理、重命名后
+   放入 deliverable/scripts/，废弃/失败尝试不要复制过去。
+
+语气要求：对"已验证"部分，agent应该像一个做过实测的工程师一样自信地陈述结果
+（"已实际下载并解析了近30天的BTC/USDT历史K线数据，验证了数据获取链路可行，
+耗时约12秒，样例输出见xxx"），而不是泛泛地说"理论上应该可以获取历史数据"——
+如果已经跑过验证，报告里就要体现出这是实测结果，而不是转述别人的说法。
+
+复盘检查（在生成报告前，先对照 charter 自问）：
+1. 这份结论是否真的回答了阶段0的问题句，并且是一个明确的技术方案推荐，
+   而不是罗列几个选项让用户自己选？如果是后者，说明研究还没做完，需要补充判断依据。
+2. "已通过脚本验证"小节里的每一条，是否都能在 workspace/04_experiments/results_log.md
+   里找到对应的真实运行记录，并且对应脚本确实已经复制进了 deliverable/scripts/？
+   如果某条结论没有实际脚本支撑却写成了"已验证"，必须改写为未验证或删除
+   ——绝不允许编造验证结果，也不允许报告引用了一个实际没打包进deliverable的脚本路径。
+3. workspace/05_learning_debt.md 或 07_pending_human_verification.md 里是否有任何一条，
+   如果不解决会让核心推荐不可靠？如果有，说明需要额外一轮 fork_agent 或验证，
+   而不是直接交付。
+4. workspace/04_experiments/ 中是否存在"假设被推翻"但报告结论没有相应更新的情况？
+   如果有，必须先回到阶段2重新评估受影响的对比结论。
+5. deliverable/ 目录里是否混入了任何废弃/失败的探索性脚本？打包前必须清理干净，
+   deliverable/scripts/ 里的每一个文件都应该能在 report.md 的脚本清单表里找到对应条目。
+
+完成上述检查且无阻塞项后，展示 deliverable/report.md 摘要给用户（用 ask 工具）确认是否满足需求；
+如果用户认为深度不够或方向有偏差，回到阶段0重新锚定（大概率只需要调整场景约束，而不是从零开始）。
+```
+
+**退出条件**：`deliverable/` 目录打包完成（report.md + 精选脚本），且用户确认满足 charter 中的成功标准。
+
+---
+
+## 5. 关键防护机制（Guardrails）
+
+设计这套 workflow 时最容易失效的几个点，以及对应的防护：
+
+| 失效模式 | 对应哪个我们之前讨论的问题 | 防护机制 |
+|---|---|---|
+| fork_agent 无限递归下去 | 递归知识爆炸 | 子agent禁止再次fork，且必须显式带"深度上限" |
+| 每个候选方案单独学一遍，效率低还看不出取舍 | 多方案并存 | 阶段2强制用统一维度做横向矩阵，禁止孤立研究 |
+| 只读资料不验证，结论似是而非 | 闭门造车 | 阶段4强制对"关键支撑论断"做最小脚本验证 |
+| 搜索目标漂移，越搜越偏离用户真实需求 | 无目标锚定 | 阶段0产出的charter作为阶段2/5的强制检查锚点 |
+| 流程走完但没检查是否真的解决了问题 | 无元认知复盘 | 阶段5的复盘检查清单，允许显式回退 |
+| 广度扫描阶段陷入无限搜索 | 广度焦虑 | 阶段1设置显式搜索预算上限，允许留白 |
+| 验证脚本卡在长耗时任务（训练/大规模回测）上，拖死整个流程 | 动手验证要有边界 | 阶段4强制单脚本时限（默认60秒），超时任务一律降级为代理实验或转入待人工验证清单 |
+| 让用户在不了解领域的情况下预先选定技术方案，本末倒置 | 技术选型是研究产出而非输入 | 阶段0明确禁止询问技术方案，只澄清目标与场景约束，方案由agent研究后给出 |
+| 最终报告用"可能/理论上"模糊带过已经验证过的结论，显得不专业不自信 | 结果要专业可实操 | 阶段5强制"已验证"结论必须附真实脚本路径、耗时、输出，语气肯定；未验证内容单独列出不混淆 |
+| 多个研究任务并行时读写同一目录，互相覆盖/污染 | 并行隔离 | 每个任务分配唯一 task_id 根目录，agent及其fork子任务只允许在自己task_id下读写 |
+| 把失败尝试、废弃脚本、探索性草稿一并丢给用户，交付物又乱又不可信 | 交付要干净可用 | workspace/（过程） 与 deliverable/（交付） 严格分离，只有精选清理过的脚本才进入 deliverable/scripts/，报告里逐条列出对应关系 |
+
+---
+
+## 6. 领域示例：如何在时限内设计"代理实验"
+
+这些例子说明阶段4里"缩小规模但保留核心逻辑"具体怎么做，是通用模式的示范，不是要agent死记这几个领域。核心思路都一样：**取真实的小样本、跑真实的最小链路、在时限内拿到真实输出**，而不是伪造结果或者跳过验证。
+
+**量化交易类研究**
+- 可验证（时限内）：调用交易所公开API获取近期一小段历史K线数据（如近7天BTC/USDT的日线或分钟线），验证数据获取链路是否通畅、字段格式是否符合预期；用这段小样本数据跑一个最小回测脚本（如简单均线策略），验证策略逻辑代码本身能否正确执行、下单/仓位计算逻辑是否符合预期。
+- 默认不验证（转入待人工验证）：跨年度大规模历史数据的完整回测、真实资金的自动化下单、需要长期运行才能看出效果的策略表现评估。
+
+**图像识别 / 视觉算法类研究**
+- 可验证（时限内）：下载一个轻量目标检测模型（如YOLO系列的small/medium版本）和几张公开测试图片，实际跑一次推理，记录检测框、置信度、耗时；如果研究问题涉及"传统CV模型 vs 多模态LLM"的效果对比，可以额外调用一次多模态模型对同样的图片做描述/识别，把两者的真实输出并排记录，作为对比证据而不是转述别人的评测结果。
+- 默认不验证：在大规模数据集上跑完整评测指标（mAP等）、模型微调/重新训练。
+
+**自动驾驶感知算法类研究**
+- 可验证（时限内）：找一份小型公开样例数据（几帧图像或点云），实现并跑通一个独立的最小算法单元，比如相机到BEV空间的射线投影/编码逻辑、点云体素化(voxelization)预处理逻辑，验证输入输出的维度和数值范围是否符合预期，用真实的几帧数据而不是随机造的假数据。
+- 默认不验证：端到端模型的训练、在完整数据集上的整体感知性能评估。
+
+**通用判断标准（不限于以上领域）**：如果一个验证任务的核心是"某段代码逻辑对不对、某个接口能不能通、某个数据处理链路能不能跑通"，通常可以设计出时限内的代理实验；如果核心是"某个模型/策略的最终性能有多好"，通常需要大规模数据/长时间训练才能有意义，这类应默认归入待人工验证清单，agent不应该用极小样本的结果冒充性能结论。
+
+---
+
+## 7. 后续可扩展方向
+
+- **多轮迭代支持**：如果用户后续基于报告提出新问题（比如"那具体怎么落地方案A"），可以直接复用同一个 charter，只新开一轮阶段2-4，不需要重新走阶段0/1。
+- **fork_agent 之间的横向通信**：目前设计是纯并行、结果汇总到主agent，如果发现两个分支的结论互相矛盾，可以考虑让主agent发起一轮"仲裁式"二次fork，专门调研这个矛盾点。
+- **可信度标注**：在最终报告中对每条结论标注证据强度（"多来源交叉验证" / "单一来源" / "脚本验证通过" / "未验证，需用户自行确认"），帮助用户判断哪些结论可以直接采信。