name: 深度调研 description: Use when 用户需要深度、多来源、经事实验证的研究报告 metadata: version: "1.0.1"

深度调研

一次调研 = 一个可增长的知识库目录，不是一份报告。 产物落在 docs/research/<主题-slug>/，按调研的逻辑要点切成多个 md 文件，可嵌套子目录、可续写、可修订。

触发

• 必须触发：调研/研究/全面了解、技术选型与方案对比（"A vs B"）、需多来源验证的事实问题、查"XX 最新状况"。
• 不触发：简单事实查询（直接搜索回答）、纯代码问题（走代码通道）、用户已有明确答案只需确认。

前置强制步骤

1. 禁止用自身知识替代搜索——训练数据可能过时/有偏见，即使知道答案也必须实际搜索。
2. 锁定范围：请求模糊 → ask_user_question 缩小（≤3 轮）；仍模糊 → 在总览页标注"范围基于以下假设：…"。
3. 假设显式化：查不到的信息标注"信息缺口"或"假设（未核实）"并继续核实；不确定的一律标注、禁止编造，不得把假设当事实写进正文。
4. 🔴 硬门禁——产物必须落盘为本地 .md 文件，禁止仅对话输出；对话只给 ≤5 行摘要 + 目录路径，无例外。
5. 🔴 硬门禁——写入范围锁定 `docs/research/`（或其 fallback `./research/`），不得写入任何其他位置。
6. 执行级别先判、工序不接力：单一不可再分的一份报告 → L1 单智能体自己做完；≥2 个可独立交付的资料包 → L2 子智能体平铺；资料包间有依赖或需跨回合持续负责人 → L3 团队。并行是默认，禁止把同一份报告拆成「先搜 → 再写 → 再审」三个执行者接力。

主线

明确范围 → 划分逻辑骨架 → 建目录骨架 → 多源并行搜索 → 交叉验证 → 逐文件落盘 → 回写总览；发现矛盾或可信度不足 → 补充搜索（聚焦）后回写对应文件。

执行级别按交付物判，不按工序拆：一份完整报告（连同它的搜索与验证）→ L1 单智能体自己做完；≥2 个可独立交付的资料包（每个都能单独验收）→ L2 子智能体平铺，一个资料包一个执行者端到端；资料包之间有依赖或需跨回合持续负责人 → L3 团队，leader 下 mission、member 按资料包端到端负责。主线各步是同一个 owner 内部的工序顺序，禁止把「先搜 → 再写 → 再审」拆给三个执行者接力。（团队里每个 member 相当于一个 L2；L3 只用于大型长程任务，见本文末尾「协作模型与等待纪律」。）

产出结构规范

<项目根>/docs/research/<主题-slug>/
├── 00-总览.md              # 索引页：调研了什么 / 有哪几部分 / 结论摘要 / 变更记录
├── 01-<逻辑要点>.md        # 一个逻辑要点 = 一个文件
├── 02-<逻辑要点>.md
├── 03-<逻辑要点>.md
└── <子主题-slug>/          # 某个要点体量大 → 升格为子目录
    ├── 00-总览.md          # 子目录自己的索引
    ├── 01-<层面>.md
    └── 02-<层面>.md

命名规则：

• <主题-slug> / <子主题-slug>：英文 kebab-case（如 vector-database-selection），稳定，不随调研轮次变化。
• 文件编号两位递增，编号即阅读顺序；索引页固定 00-。
• 每个 NN-<要点>.md 头部固定三行：调查的问题 / 结论一句话（含可信度）/ 最后更新日期。

三个必备要素（缺一即不合格）：有总览索引页、按逻辑要点分文件、支持子文件夹嵌套。

00-总览.md 结构

# 调研：<主题>
> 首次调研 YYYY-MM-DD ｜ 最后更新 YYYY-MM-DD ｜ 轮次 N ｜ 来源总数 N
 
## 调研范围与假设
## 目录索引
| 文件 | 回答的问题 | 状态 | 最后更新 |
## 结论摘要
[每部分 1-2 句 + 可信度 + 指向文件]
## 变更记录
| 日期 | 变更 | 影响文件 |
## 信息缺口

单文件体量阈值

拆分不是为了行数好看：同一文件里出现两个能各自独立回答的问题，就该是两个文件。

阶段 1：明确范围 + 逻辑骨架先行

这是解决"大量调研最后只挤出一小份报告"的关键步骤，绝不允许跳过直入搜索。

1. 解析用户意图：主题 / 深度（概览→快速，学术级→完整流程）/ 时效性 / 约束（语言、地域、排除项）。
2. 锁定问题（模糊时 ask_user_question 缩小，≤3 轮）：① 缩小主题 ② 确认深度 ③ 确认产出位置（docs/research/ 还是 fallback ./research/）。
3. 划分逻辑要点——先不搜索，先产出「逻辑骨架表」：

划分判据：

• 一个要点 = 一个可以被单独回答的问题，不是"一个章节标题"。
• 要点数建议 3–8 个；少于 3 个说明没调研价值，多于 8 个考虑折叠为子目录。
• 骨架阶段就要标出哪个要点预计体量大——预计会写很多的直接定为子目录，别等写完再拆。
• 资料包判据（横向切分 vs 阶段接力）：一个资料包 = 一个能独立交付、独立验收的调研产物（问题 + 来源 + 归属文件）；「先搜」「再写」「再审」单独拿出来都不构成可用成果，那是阶段接力，禁止拆给不同执行者。

1. 建目录骨架：把骨架表落成真实文件——00-总览.md（含范围与索引表）+ 每个要点一个带标题的空壳文件。先有文件，才有归属，后续每条发现都有明确落点，从机制上消除"结尾压缩"。
2. 用户确认骨架，或"直接开始"。
3. 出口：核心问题一句话说清、逻辑骨架表已生成、目录骨架已建、用户已确认、执行级别（L1/L2/L3）已按资料包判定。

阶段 2：多源搜索（并行）

1. 设计搜索维度（从以下选 ≥3 个；并行是默认）：

官方文档 <topic> official documentation；社区讨论 <topic> reddit/hackernews；对比评测 <A> vs <B> comparison；学术/技术博客 <topic> deep dive；中文社区 <主题> 实践 经验；GitHub/开源 <topic> github stars；定价/成本 <service> pricing；负面/批评 <topic> problems/issues。

1. 按资料包横切并行（资料包 = 骨架表里一个可独立交付的要点）：L1 自己把各资料包依次搜完；L2 每个资料包一个子智能体端到端（自己搜、自己验、自己写回归属文件）；L3 资料包间有依赖或需跨回合持续负责人时，leader 下 mission、member 按资料包端到端负责。

每个资料包内：web_search ≥3 次不同关键词组合 → 选 3-5 个最相关来源 → web_fetch 全文 → 提取与骨架表相关的关键信息 → 输出 来源 | URL | 关键发现 | 归属文件 | 可信度 表 + 详细摘录。 摘录必须按「归属文件」分桶输出，禁止交回一段笼统总结——否则又回到压缩成小报告的老路。 禁止「先搜 → 再写 → 再审」阶段接力：搜索、写回、审查由同一个 owner 在自己的交付物内一次做完。 派发并行检索后不阻塞等待：发起 → 输出本轮结论 → 结束回合，靠二次唤醒收结果；单条命令 >30 秒一律转后台。

1. 可信度：🟢 官方/权威/同行评议/数据可复现；🟡 知名博客/社区高赞/公司技术博客；🔴 个人博客/匿名/未注日期/明显偏见。
2. 出口：≥3 维度并行、每维度 ≥2 个有效来源、总来源 ≥8、每个来源已标可信度、每条发现已指定归属文件。

阶段 3：交叉验证

1. 提取核心声明为清单（声明 → 来源 A/B/C → 验证状态 → 归属文件）。
2. 分类处理：

• ✅ ≥2 独立来源确认 → 写入归属文件，标注来源。
• ⚠️ 单一来源 → 写入但标"单一来源，未交叉验证"。
• ❌ 来源矛盾 → 触发补充搜索，聚焦矛盾点找第 3-4 个来源裁决。
• 🔴 无来源 → 标"信息缺口"，在总览页「信息缺口」区登记。

1. 处理矛盾不选边站：补充搜索聚焦矛盾；文中并列呈现各方观点及依据；给出基于方法论的判断但标"仅供参考"。
2. 证据绑定：每条要写进正文的结论都必须能指认来源（URL/文献 + 可信度）；裁决冲突以可复现数据或官方文档为准并记录冲突；不能核实的写「未核实 / 无法判定」，禁止用「应该/大概/可能」下结论。
3. 出口：核心声明全列入、每声明 ≥2 来源（或已标注单一/矛盾/缺口）、矛盾已补充搜索、缺口已标注。

阶段 4：逐文件落盘 + 总览回写

1. 逐要点写入：用 write/edit 把分桶后的内容写进对应文件。正文每个事实性声明必须带来源标注（[来源 #N] 或内联链接 + 可信度）。禁止把内容集中堆在总览页。
2. 回写总览：更新索引表「状态/最后更新」、结论摘要（每条 1-2 句 + 指向文件）、变更记录、信息缺口。涉及选型/方案/迁移建议的结论必须附代价与影响面（成本、不可逆、影响范围、回滚路径）与风险；高风险建议先备份/预演/小步验证，不确定按高风险处理（代价优先）。
3. 双向一致性检查：每个要点文件必须能被总览索引到；总览索引的每个文件必须真实存在（悬空 + 孤儿双向检测）。
4. 落盘后验证：glob/read 确认目录结构完整、每个文件非空、来源清单完整（URL + 可信度 + 引用点）。
5. 对话中仅允许 ≤5 行摘要 + 目录路径。
6. 禁止阶段接力：落盘与总览回写是同一交付物的收尾，由该资料包/团队的同一个 owner 做完；「搜索的人 → 写文件的人 → 审查的人」接力 = 违规。

🔴 落盘硬门禁：产物必须写入 docs/research/<主题-slug>/（或 fallback ./research/<主题-slug>/），禁止仅对话输出；禁止写入该目录以外的任何位置（含 docs/design/、docs/information/、项目根）。

更新式调研（同主题二次调研）

必须更新已有目录，不得另起新目录——<主题>-v2、<主题>-2、<主题>-<日期> 一律禁止。

无论哪种情形都要回写总览页「变更记录」——只改分文件不改总览 = 更新未完成。

与项目管理体系的衔接

• docs/research/ 是新文档体系的一部分，回答「外部世界怎么说」；docs/design/ 回答「做什么」，不得混写。
• 项目尚无 `docs/` 体系时：ask_user_question 二选一——① 先走 myworkflow-project-init 建立文档体系，再落盘 docs/research/；② 就地建 ./research/<主题-slug>/（fallback，且不创建 `docs/`）。不得代用户决定。
• 不建 index.json——docs/research/ 靠总览页 + 目录结构导航；索引只服务于 design/ 与 information/。
• 经验沉淀归 `docs/information/`：调研中得出的可复用经验，本技能不直接写入，只提示用户走 myworkflow-project-maintain 登记。
• 不主动改动项目既有文档（CLAUDE.md、GOAL、STATE、PROGRESS 等），本轮只产出 research 目录。

完成标志

• [ ] 逻辑骨架表已生成（每个要点对应明确的产出文件），且目录骨架已建
• [ ] ≥3 搜索维度并行执行，总来源 ≥8 个独立来源，每条发现已指定归属文件
• [ ] 核心声明已交叉验证（≥2 来源或已标注单一/矛盾/缺口）；矛盾已补充搜索且未选边站
• [ ] 每条结论能指认来源；不能核实的已标「未核实/信息缺口」，没有「应该/大概/可能」式结论
• [ ] 产物位于 docs/research/<主题-slug>/（或 fallback ./research/<主题-slug>/），未写入任何其他位置
• [ ] 含 00-总览.md 索引页；总览索引与磁盘文件双向一致（无悬空、无孤儿）
• [ ] 无单文件超阈值未拆分；体量大的要点已升格为子目录
• [ ] 更新式调研：更新已有目录而非新建，总览「变更记录」已回写
• [ ] 🔴 已落盘并 read/glob 验证文件存在且非空
• [ ] 对话仅 ≤5 行摘要 + 目录路径（未贴全文）
• [ ] 执行级别已按资料包判定（L1/L2/L3），同一交付物没有被拆成阶段接力
• [ ] 选型/方案/迁移建议附了代价、影响面、风险与回滚路径
• [ ] 没有阻塞等待/轮询；>30 秒命令已放后台或 leaf

反绕过红线

• 跳过逻辑骨架直接开搜、最后把结果压成一段总览 → 本次调研作废重做。
• 只搜一个维度/一个关键词就"查完" → 覆盖面不足。
• 全部内容塞进 00-总览.md、分文件只是空壳 → 等价于退回单报告模式。
• 所有来源说法一致 → 可能同源互引，检查是否独立来源。
• 用自身知识代替搜索 / 把矛盾简化成"大家普遍认为" → 违规。
• 🔴 只在对话贴全文不写文件 → 硬门禁违规，先写文件再给摘要。
• 写入 docs/research/ 之外的路径 → 越界违规。
• 同主题二次调研另起新目录 → 知识库碎片化，违规。
• 写完后未 read/glob 确认文件存在 → 可能写入失败。
• 不判执行级别、一律把「派子智能体搜索」当唯一协作模型 → 级别误判（L1 自己做完、L2 平铺、L3 团队）。
• 把「先搜 → 再写 → 再审」拆给不同执行者/不同窗口 → 阶段接力，违规。
• 派发后在本回合阻塞等待/轮询/空转 → 违反等待纪律（回合内禁止等待）。
• 把 >30 秒的命令卡在回合里同步等 → 违反 30 秒硬上限（应放后台或 leaf）。
• 把「应该/大概/可能/通常」当结论、或把假设写成事实 → 违反证据纪律（禁止编造）。
• 给选型/迁移建议却不算代价、影响面与回滚路径 → 违反代价优先。

协作模型与等待纪律（硬）

L2 与 L3：L2 是一个可独立完整执行的交付单元——有明确输入、明确产出、可独立验收，由主智能体派 subagent，一个执行者端到端做完；L3 只用于大型、长程任务，把一个超大任务切成若干相互独立的部分，模仿真人团队「各自独立工作 → 沟通 → 整合」。团队里每个 member 就相当于一个 L2。判据仍是：多域、交付物之间有接口/依赖、需要跨回合持续负责人、需要多批推进；不要因为「任务大」就建团。

member 与 member 可以直接沟通（不必经 leader 中转）：任务切分一开始不可能完美，执行中会出现交叉、重叠、接口变化与相互依赖，直接沟通比「上报 leader 再转发」快。leader 只在边界冲突需裁决、目标变更、验收标准修改时介入；双方改了交付边界要同步 leader 记录，但不必阻塞等批准。

member 与 leaf 的区别：leaf 寿命绑定具体任务、只负责一个任务、只与派发者/owner 沟通（缺输入要输入）；member 长期存在（睡眠唤醒复用、跨任务保留知识与状态）、掌管一个领域、可直接与其它 member 和 leader 沟通——一个 member ≈ 一个领域级的 L2。

等待与阻塞纪律（禁止等待）：派发子智能体/后台任务后不得在自己的回合里等待（不阻塞、不轮询、不空转）；正确做法是「发起 → 输出本轮结论 → 结束回合」，完成后靠二次唤醒继续。30 秒是硬上限：任何不能保证 30 秒内跑完的命令（脚本、构建、测试、批量检索、网络抓取）一律放后台或交给 leaf，不在回合里同步等。