深度调研（Deep Research）

先摸清内部现状，再对标外部水位，找到差距，指导行动。 产出有判断、有依据、经得起反面追问的专业研究报告。

核心理念：6 步是能力库，不是必走流程

下面分 6 步介绍调研能力：理解命题 → 多跳搜集 → 分析结论 → 图表生成 → 撰写报告 → 质量自检。

这 6 步是能力清单，按命题复杂度调用——不是每次都得全部走完。简单事实查询硬走 6 步是浪费；复杂研究跳过任何一步都会丢深度。

调研深度判断

收到调研需求后，先判断命题复杂度，决定走哪条路径：

决策树

调研需求来了
↓
命题是单一具体事实查询？（"X 是什么"、"如何配置 Y"）
  ├─ 是 → 走简单事实路径：Lead 自查官方源 → 直接答复（不进入"理解命题"流程）
  └─ 否 → 进入 1.1 命题理解
            ↓
            归类为对比类 / 复杂研究 / 超深度
            ↓
            按 Scaling Rules（2.3）配置预算
            ↓
            按需调用 1.4-6.4 各能力

核心原则：

• 简单事实查询禁止启动 Multi-Agent——下面 2.1 的 Orchestrator-Subagent 架构是"复杂研究"才用的
• 对比类调研可省略部分能力——比如假设驱动（1.6）、调查拓扑（2.5）、反面观点段按内容选用
• 复杂研究走完整 6 步——任何步骤跳过都会丢深度
• 报告结构由内容形态决定——见 5.2 的"内容形态 → 组件"速查，没有对应内容就不要硬上对应组件

第一步：理解命题，摸清现状

收到调研需求后，先花时间理解命题本质和内部现状，不要急着搜索。

1.1 命题解析

向用户确认以下信息（已知的跳过，模糊的追问）：

• 核心问题：这次调研要回答什么问题？
• 调研动机：为什么要调研这个？（决策依据 / 学习了解 / 立项评估）
• 期望深度：快速摸底 还是 深度研究？
• 关注维度：有没有特别关心的角度？（性能 / 成本 / 生态 / 趋势）
• 已有认知：用户对这个领域已经了解多少？（避免重复输出已知信息）
• 内部数据源：是否有相关的内部文档、代码库、BI 数据、历史报告可供参考？路径在哪？
• 评估基准：有没有已知的行业标准或内部目标可作为参照？

1.2 判断调研类型

根据命题自动归类，不同类型决定后续的报告结构和搜索策略：

如果命题跨多个类型，以主要目的为准，兼顾次要维度。

评估不是独立类型。所有调研类型都内含评估逻辑——先理解内部现状，再对标外部水位，识别差距。 用户说"评估一下 xxx"、"诊断"、"差距分析"时，根据具体命题匹配上述 6 种类型，评估视角在 1.4 现状摸底中统一处理。

加载信源矩阵（完成归类后执行，详见 references/sources/_router.md）：

1. 闸门 1：具体查询 vs 命题调研
   • 具体查询（"API 用法 / 命令参数 / bug 复现"）→ Lead 自查官方 docs，跳过 YAML 加载，不走 Multi-Agent
   • 命题调研 → 进入闸门 2
2. 闸门 2：关键词匹配
   • 金融类（股票/财报/利率/央行/债券/加密/链上/宏观）→ 加载 references/sources/finance.yaml
   • 学术类（论文/研究/综述/预印本）→ 加载 references/sources/academic.yaml
   • 技术/AI/新兴产业 → 加载 references/sources/_source_heuristics.md
3. 闸门 3：全域加载 references/sources/blacklist.yaml（最高优先级过滤）
4. 搜索预算分配：有白名单时 70% 倾斜冷门权威 + 20% 开放搜索 + 10% 启发式发现；纯启发式时 60% P1 一手 + 30% P2 原厂/评测 + 10% P3 审核社区

Lead Agent 必须在派发 sub-agent 前，把加载的 YAML 内容注入 sub-agent prompt（见 2.1）。

1.3 确定视觉风格

根据调研类型自动选择图表风格主题，同一份报告内所有图表保持统一。 具体的风格配置见 references/chart-styles.md，根据调研类型查阅对应章节。

1.4 现状摸底（所有调研类型必做）

在进行任何外部搜索之前，先理解「我们自己」的状态。这是所有调研的起点——不知道自己在哪，就无法判断外部信息的价值。

数据采集来源：

按调研类型的摸底重点：

执行方式：

• 有内部数据时：优先采集，作为后续外部对比的基线
• 用户提供路径时：直接 Read/Grep 读取
• 无内部数据时：记录为「内部数据缺失」，报告中标注「本报告基于公开数据，未纳入内部数据验证」

1.5 快速扫描（建立基本认知）

在形成假设之前，先做一轮轻量级外部搜索，对命题领域建立基本认知。目的不是收集证据，而是了解「这个领域目前是什么状况」，让后续假设有事实基础而非凭空猜测。

执行方式：

• 围绕命题设计 3-5 个不同角度的搜索词
• 只看搜索结果摘要和页面标题，不深入阅读全文
• 记录关键发现：主要玩家、核心争议点、领域现状、意外发现
• 耗时控制在 1-2 分钟，不展开深度搜索

产出：一段简短的扫描摘要（3-5 个要点），作为下一步形成假设的输入。

示例：

调研命题："是否应该从 Redis 迁移到 Dragonfly"

快速扫描发现：
- Dragonfly 定位为 Redis 的直接替代品，声称性能提升 25 倍
- 多个 benchmark 显示在多线程场景下确实显著优于 Redis
- 但社区讨论中有人指出生产环境稳定性存疑
- Redis 7.0 已引入多线程 IO，缩小了部分差距
- 迁移案例主要集中在中小规模部署

1.6 形成初始假设

基于内部现状（1.4）+ 快速扫描结果（1.5），形成 2-4 个可验证/可证伪的假设：

• 每个假设用「我认为 X，因为 Y」格式表述，其中 Y 必须引用扫描中发现的具体事实
• 将假设拆解为可搜索的验证点
• 后续深度搜索围绕验证/证伪这些假设展开，而非漫无目的收集

示例（承接上面的扫描结果）：

假设 1：Dragonfly 在多线程高并发场景下性能显著优于 Redis
  → 依据：扫描发现多个 benchmark 支持此结论
  → 验证点：独立 benchmark 数据、生产环境案例、Redis 7.0 多线程对比

假设 2：Dragonfly 生态成熟度不足，大规模生产环境迁移风险高
  → 依据：扫描发现迁移案例集中在中小规模，社区有稳定性质疑
  → 验证点：客户端兼容性、大规模部署案例、已知 bug 和限制

假设 3：我们当前的性能瓶颈不在 Redis 层
  → 依据：内部摸底发现 APM 数据显示主要延迟在应用层
  → 验证点：内部监控数据、链路分析、Redis 慢查询日志

与旧流程的区别：假设不再基于猜测，而是基于内部数据和初步扫描的事实。每个假设的「依据」必须指向 1.4 或 1.5 中发现的具体信息。

1.7 与用户对齐

将解析结果简要告知用户：

调研命题：xxx
调研类型：技术选型
报告风格：商务蓝灰
输出格式：Markdown / HTML
命题复杂度：对比类 / 复杂研究 / 超深度
执行预算：派发 N 个 sub-agent，每个 WebSearch ≤ X / WebFetch ≤ Y
预计 Token 消耗：约 Mx chat 基准
初始假设：
  1. xxx
  2. xxx
内部数据源：已读取 / 用户将提供 / 无
预计涵盖：A、B、C 几个维度

开始调研？

输出格式判断规则：

• 默认 Markdown：绝大多数场景
• 选择 HTML：用户提到"HTML"、"网页版"、"富文本"、"好看点的"、"交互式"、"嵌入图表"时

用户确认后进入下一步。如果是简单直接的调研需求（命题明确、无歧义），可以跳过对齐直接开始。

第二步：多跳信息搜集

这是调研的核心环节。采用 Orchestrator-Subagent 架构：Lead Agent 负责规划与整合，Sub-agent 独立并行深挖，避免单一 context 被原始材料撑爆导致细节丢失。架构参考 Anthropic 官方 Research 系统实践。

2.1 Multi-Agent 执行模型

Lead Agent（主 agent）
↓ 拆子问题 → 派发
Sub-agent A / B / C  并行（独立 context + 独立预算）
↓ 压缩回传
Lead 整合 → 触发规则命中？
↓ 命中 → 再 fork sub-agent
↓ 未命中 → synthesis 出报告

Lead Agent 职责：

• 基于 1.6 假设拆解子问题（每个子问题独立可回答）
• 按 Scaling Rules（2.3）决定 sub-agent 数量和预算
• Spawn 前把调查计划写入 /tmp/research-plan-<timestamp>.md（防 context 截断丢失）
• 维护拓扑记录文件：每次 spawn 向 /tmp/research-topology-<timestamp>.json 追加条目，回传后补 budget_used / findings_count，Fork sub-sub 时记录 parent_id；线索被主动放弃也要记录（格式见 2.5）
• 注入信源矩阵：基于 1.2 加载的 YAML/heuristics，在 sub-agent prompt 中注入：
  1. blacklist（hard 必避 + soft 降级 + patterns）
  2. 对应领域白名单（finance/academic 的冷门权威列表）或 _source_heuristics.md 的规则 + 本命题所属子域推导示例
  3. 搜索预算分配比例（有白名单 70/20/10，纯启发式 60/30/10）
  4. 要求 sub-agent 回传 whitelist_hits / heuristic_hits / blacklist_avoided 字段（见 2.4）
• 只读 sub-agent 的压缩 JSON 回传，不读原始网页
• 按节点级触发规则（2.2）判断是否 fork 新 sub-agent
• 最终 synthesis 阶段整合所有 findings 产出报告，并基于拓扑文件生成 5.2"调查拓扑"段

Sub-agent 职责：

• 独立 context window，专注一个子问题
• 可自行并行调用多个搜索/抓取工具
• 在预算内查完，超预算强制收尾
• 回传结构化 JSON（格式见 2.4）
• 发现反直觉线索写入 surprises 字段供 Lead 判断是否深挖
• 长文档按 Filesystem Pattern 存 /tmp/，不塞进回传

硬性约束：

• 所有 sub-agent 必须使用 Agent 工具派发，指定 subagent_type: "general-purpose" + model: "sonnet"
• Lead Agent 保持当前调用模型不变
• Sub-agent 之间不直接通信，所有协作通过 Lead 协调

2.2 迭代式深挖与触发规则

废弃"固定 3 层广度优先"模型，改为按节点兴趣度动态深挖。

迭代上限：

• Synthesis 轮次 ≤ 3 轮（Lead 汇总 → 看缺口 → 再派发）
• 单轮内 sub-agent 可递归 fork sub-sub-agent，递归深度 ≤ 3

单轮流程：

Round N
↓
Lead 读全部 findings → 识别信息缺口 / 触发点
↓
Spawn 新一批 sub-agent（可含 sub-sub-agent）
↓
收集压缩回传
↓
满足终止条件 → 结束；否则 Round N+1

节点级 Fork 触发规则（满足任一条件，Lead 必须派新 agent）：

终止条件（满足任一即可结束）：

• 所有假设都有 T1 源或 2+ 独立 T2 源支撑
• 反面证据搜索已执行且无新发现
• 进入 Round 3 后仍无新信息

2.3 Scaling Rules（强制预算）

根据命题复杂度配置 sub-agent 数量和工具预算。超预算必须强制收尾，防止 runaway。

Lead Agent 在派发前必须声明（写入 plan 文件，并在 1.7 对齐阶段展示给用户）：

命题复杂度评估：<类型>
计划派发：<N> 个 sub-agent
每个预算：WebSearch ≤ X / WebFetch ≤ Y
预计 Token 消耗：约 <M>x chat 基准

Token 成本红线：

• Multi-Agent 架构消耗约 15x chat tokens（参考 Anthropic 工程数据）
• 简单事实查询禁止开 Multi-Agent，直接由 Lead 自查
• 如评估为复杂研究但用户明确要求"快速了解"，降级为对比类预算

2.4 Sub-agent 压缩回传协议（强制）

核心原则：Sub-agent 不得将原始网页内容回流给 Lead Agent。回传必须是结构化压缩摘要，避免 Lead context 被撑爆导致细节丢失。

标准回传 JSON：

{
  "topic": "本次调查的子问题",
  "findings": [
    {
      "claim": "一句话结论",
      "evidence": ["关键引文片段，每段 ≤100 字"],
      "urls": ["https://..."],
      "source_tier": "T1|T2|T3",
      "confidence": "high|mid|low",
      "date": "证据时间戳，如 2026-03"
    }
  ],
  "surprises": ["反直觉或意外发现，供 Lead 决定是否深挖"],
  "gaps": ["未能验证的点 / 需其他 agent 补充的信息"],
  "budget_used": { "search": N, "fetch": M },
  "whitelist_hits": N,
  "heuristic_hits": { "p1_official": 3, "p2_authoritative": 2, "p3_community": 1 },
  "blacklist_avoided": ["csdn.net", "guba.eastmoney.com"]
}

信源矩阵字段说明：

• whitelist_hits：若本次加载了 finance.yaml / academic.yaml，命中了几个白名单源（质量指标）
• heuristic_hits：若走启发式，按 P1/P2/P3 分类的命中源数（衡量 heuristics 有效性）
• blacklist_avoided：识别并避开的黑名单域列表（证明过滤生效）

硬性禁止：

• ❌ 回传中包含原始 HTML 或 markdown 全文
• ❌ 未精简的搜索结果列表
• ❌ 单条引文超过 100 字
• ❌ 省略 source_tier 或 confidence 字段

Filesystem Pattern（处理大文档）：

Lead Agent Synthesis 阶段：

• Context 中只有压缩 findings JSON，不含原文
• 需要核对原文时按 URL 或 /tmp/ 路径按需读取
• 避免一次性把所有 sub-agent 的原始内容塞进 context

2.5 调查拓扑记录协议（强制）

目的：让调研过程可观测——派发了几个 sub-agent、递归了几层、消耗了多少搜索/抓取、放弃了哪些线索，最终写入报告"调查拓扑"段（见 5.2）。

记录文件：/tmp/research-topology-<timestamp>.json（同次调研使用同一文件名，与 plan 文件共享 timestamp）。

条目结构：

{
  "session_id": "<timestamp>",
  "root_topic": "本次调研命题",
  "complexity_class": "simple|comparison|complex|super-deep",
  "agents": [
    {
      "agent_id": "sub-01",
      "parent_id": null,
      "round": 1,
      "topic": "子问题摘要",
      "spawn_reason": "初始拆解 | confidence_low | surprise_followup | contradiction | devils_advocate | missing_t1",
      "budget_plan": { "search": 10, "fetch": 15 },
      "budget_used": { "search": 8, "fetch": 11 },
      "findings_count": 4,
      "status": "completed|aborted|budget_exceeded"
    }
  ],
  "abandoned_leads": [
    { "topic": "放弃的线索", "reason": "反爬无法验证 | 时效性不足 | 预算触顶 | 其他" }
  ]
}

硬性约束：

• Spawn 前追加 agents[] 条目（填 budget_plan + spawn_reason，budget_used 和 findings_count 留空）
• 回传后 Lead 更新该条目的 budget_used / findings_count / status
• Fork sub-sub-agent 时必须填 parent_id 和 round，识别出递归层级
• 主动放弃的线索写入 abandoned_leads，不得静默丢弃
• 报告完成后，拓扑文件连同 /tmp/ 下其他本次调研产物一并清理（synthesis 结束后 Lead 负责）

简单事实查询：Lead 自查不开 Multi-Agent 时（见 2.3），仍需生成最小拓扑文件（agents 为空，记录自查的 budget_used），保证报告拓扑段统一。

2.6 搜索执行

• 使用 WebSearch 进行网络搜索，使用 WebFetch 获取具体页面内容
• 如果命题涉及本地项目，同时用 Grep/Read 检索本地代码库和文档
• 搜索关键词设计：每个搜索用不同角度的关键词，避免信息重复
  • 例：调研 Redis → "Redis performance benchmark 2026"、"Redis vs alternatives comparison"、"Redis use cases limitations"
• 并行原则：
  • 同一 sub-agent 内的多个工具调用尽量并行（单次消息多个 tool call）
  • 不同 sub-agent 之间通过 Lead 并行 spawn 实现跨 agent 并行
  • Sub-agent 搜索策略："start broad, then narrow"——先用短宽关键词扫全景，再聚焦深挖

2.7 页面抓取策略

很多高价值网站有反爬机制，WebFetch 可能拿不到内容。采用分层抓取策略：

第 1 层（默认）：WebFetch 直接请求
    │ 成功 → 使用
    │ 失败/内容为空/返回反爬页面 ↓
    │
第 2 层（降级）：Playwright 浏览器模拟
    │ 通过 Playwright MCP 工具模拟真实浏览器访问
    │ 成功 → 使用
    │ 失败 ↓
    │
第 3 层（替代）：换源搜索
    └── 放弃该 URL，搜索同一信息的其他来源

Playwright 浏览器抓取步骤（当 WebFetch 失败时）：

1. playwright__browser_navigate 访问目标 URL
2. playwright__browser_wait_for 等待页面加载完成（等待关键内容元素出现）
3. playwright__browser_snapshot 获取页面可访问性快照（结构化文本内容）
4. 如果快照不够，用 playwright__browser_evaluate 执行 JS 提取特定内容
5. 完成后 playwright__browser_close 关闭浏览器释放资源

常见需要 Playwright 的高价值站点（非完整列表，遇到新的反爬站点时自动识别并切换）：

抓取纪律：

• 同一域名连续请求间隔至少 2 秒，避免触发频率限制
• 优先抓取信息密度高的页面（官方文档、技术博客正文），跳过信息稀疏的页面（列表页、导航页）
• 如果一个站点连续 2 次抓取失败，放弃该站点，从其他来源获取同类信息
• Playwright 浏览器用完即关，不保持长连接

2.8 信息记录与来源分级

搜索过程中，对每条关键信息记录：

• 事实内容：具体是什么
• 来源：URL 或文档路径
• 来源层级（决定引用权重）：

• 数据属性（决定可比性）：

来源分级规则：

• 核心结论必须基于至少 1 个一手来源或 2 个独立二手来源
• 仅有三手来源支撑的数据，标注「未经独立验证」
• 跨来源对比前，先检查数据口径是否一致（地域/时间/定义）
• 不同来源的同一指标出现显著差异时，优先采信一手来源，并在报告中标注分歧

2.9 信息验证原则

• 多源交叉：关键结论至少 2 个独立来源佐证
• 时效性：优先采用近 1-2 年的数据，标注信息的时间
• 去伪存真：发现信息冲突时，列出不同说法，注明分歧，优先采信一手来源 [T1]
• 标注不确定性：仅单一来源的信息标注"据 xxx 称"；无法验证的数据标注"未经独立验证"
• 假设对照：每轮 synthesis 后回顾初始假设（见 1.6），标记哪些假设已获得支撑/被削弱/证据不足

第三步：分析与结论形成

搜集完信息后，进行系统性分析，形成有判断力的结论。

3.1 信息整理

• 对搜集的信息去重、分类
• 识别共识点（多数来源一致）和争议点（来源之间有分歧）
• 提取关键数据点，准备用于图表展示

3.2 分析框架选择

根据调研类型和行业背景，从框架库中选择合适的分析方法。 框架路由表见 references/frameworks/_index.md，各领域详细框架见 references/frameworks/<领域>.md。

此处只列选择逻辑：

选择流程：

1. 确定调研类型 → 查通用框架推荐（frameworks/_index.md 路由表 + frameworks/general.md）
2. 判断行业背景 → 叠加特化框架（互联网 → frameworks/internet-*.md，金融 → frameworks/finance-*.md）
3. 判断分析视角 → 调整产出重点（券商视角重估值、咨询视角重策略、VC 视角重增长）

不确定时默认：通用底座框架（PESTEL + 竞争格局 + 价值链）+ 咨询视角

3.3 形成判断

调研报告的价值在于有判断，不只是罗列信息。

假设回顾：

• 逐一回顾初始假设，标注验证结果：
  • ✅ 已验证（列出支撑证据及来源层级）
  • ❌ 已证伪（列出反面证据）
  • ⚠️ 证据不足（说明缺什么信息）
• 假设验证结果直接构成报告核心结论的骨架

结论要求：

• 对每个核心问题给出明确结论
• 结论必须有数据或事实支撑，标注来源层级
• 每个核心结论标注置信度（高/中/低），评估规则：
  • 高置信度：2+ 个独立 T1 来源支撑，或 3+ 个独立 T2 来源一致，且无有力反面证据
  • 中置信度：1 个 T1 或 2 个 T2 支撑，但存在部分反面证据或数据冲突
  • 低置信度：仅 T2/T3 来源，或来源间存在显著分歧，或数据时效性存疑
• 存在不确定性时，说明条件和假设
• 给出可操作的建议或下一步方向

反面观点：

• 每个核心结论都考虑「如果反过来呢？」
• 列出已收集到的反面证据和反面观点
• 对反面观点给出回应（接受 / 反驳 / 承认不确定性）

第四步：图表生成

报告中的图表是专业性的重要体现。根据内容需要自动选择合适的图表类型，不限制数量。

报告配图不带标题：图表标题由报告正文的章节标题承担，图表本身的 title 设为空字符串。避免标题重复。

统一使用 Diagram Skill 的固化脚本（bridge.py 和 capture.py），无需安装额外依赖。

禁止手动调用 Playwright MCP 工具截图（browser_navigate、browser_take_screenshot、browser_run_code 等）。所有图表截图统一通过 bridge.py / capture.py 完成，它们内部已封装 HTTP 服务启动、ELKjs 异步等待、Retina 2x 输出等逻辑。

4.1 图表类型选择

统计图表（bridge.py 生成，JSON 配置 → PNG）：

结构图表（需要时由 Claude 直接编写 HTML + capture.py 截图，参考 Diagram skill 模板）：

4.2 统计图表生成（bridge.py）

调用方式：

# ── Markdown 模式（默认）──
# 方式 1：JSON 文件输入
echo '<JSON配置>' > /tmp/chart-config.json
python ~/.claude/skills/diagram/scripts/bridge.py -c /tmp/chart-config.json -o docs/research/assets/<文件名>.png

# 方式 2：管道输入
echo '<JSON配置>' | python ~/.claude/skills/diagram/scripts/bridge.py -o docs/research/assets/<文件名>.png

# ── HTML 模式 ──
# 输出自包含 HTML 片段，后续直接嵌入报告
python ~/.claude/skills/diagram/scripts/bridge.py -c /tmp/chart-config.json -o /tmp/<文件名>.html -f html

JSON 配置格式：

{
  "type": "bar",
  "title": "图表标题",
  "subtitle": "副标题（可选）",
  "data": { ... }
}

各图表类型的 data 结构：

scatter 支持气泡图：data 中传 [[x, y, size], ...]，size 越大气泡越大。

4.3 结构图表生成（capture.py）

需要流程图、架构图等结构图时，直接编写 HTML 文件，然后用 capture.py 截图/导出：

# ── Markdown 模式（默认）──
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件路径> docs/research/assets/<文件名>.png

# ── HTML 模式 ──
# 输出自包含 HTML，或直接使用手写的 HTML 源文件
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件路径> /tmp/<文件名>.html -f html

HTML 编写参考 ~/.claude/skills/diagram/templates/html/ 下的模板和 lib/base.css 样式。

4.4 图表输出规范

Markdown 模式：

• 输出保存到 docs/research/assets/ 目录
• 文件名格式：<报告名>-<图表描述>.png，例如 redis-benchmark-bar.png
• 默认 2x Retina 输出，确保清晰度
• 禁止 Read PNG 文件：生成后只通过 ls -la 确认文件存在和大小，不要用 Read 工具查看 PNG，避免图片加载到会话上下文触发多图尺寸限制

HTML 模式：

• 图表暂存 /tmp/ 目录，后续直接读取 HTML 内容嵌入报告
• 不生成 PNG，不需要 assets 目录
• 用 Read 工具读取生成的 HTML 文件，提取 <body> 内的 SVG/图表内容嵌入报告

通用：

• 图表必须包含：标题、坐标轴标签（统计图）、图例（多系列时）

4.5 图表嵌入

Markdown 模式：用相对路径引用 PNG：

![Redis vs Memcached 读写性能对比](assets/redis-benchmark-bar.png)

HTML 模式：直接嵌入图表 HTML 片段，用 .chart-container 包裹：

<div class="chart-container">
  <div class="chart-inner">
    <!-- 此处粘贴 bridge.py -f html 输出的 SVG 或图表 HTML -->
  </div>
  <p class="chart-caption">图表说明文字</p>
</div>

每张图表紧跟在相关分析文字之后，配简要说明文字解读图表要点。

4.6 轻量图示：terminal / flow 代码块

报告中不是所有"流程/命令"都值得调 bridge.py / capture.py。以下两类直接写成 Markdown 代码块，preview-md / HTML 报告会自动渲染为带样式的图示：

• ```flow：方法论流程、决策树、阶段串联（≤ 10 个节点）
  • 适用：调研方法论示意、筛选流程、评估决策路径
  • 复杂多分叉流程仍调 bridge.py 画真正的流程图
• ```terminal：调研中执行的关键命令、CLI 输出示例
  • 适用：附录的复现步骤、benchmark 命令、数据抓取脚本展示
  • 单条命令仍用普通 ```bash

完整语法和示例见 preview-md SKILL.md "扩展语法"章节。

选型决策：

需要图示？
↓
数据可量化？→ bridge.py（柱状/折线/饼图等）
↓
结构复杂或多角色？→ capture.py（流程/时序/架构图）
↓
轻量流程/命令展示 → ```flow / ```terminal 代码块

第五步：撰写报告

5.1 报告输出位置

Markdown 模式（默认）：

docs/research/
├── YYYY-MM-DD-<命题关键词>.md    ← 报告正文
└── assets/
    ├── <报告名>-<图表1>.png
    ├── <报告名>-<图表2>.png
    └── ...

HTML 模式：

docs/research/
└── YYYY-MM-DD-<命题关键词>.html  ← 自包含 HTML 报告（图表内嵌，无 assets）

5.2 报告组成：组件驱动，不预设模板

报告结构由内容形态决定——先看手上有什么内容，再调对应组件，自然组合成文。不预设"必备章节"，不按调研类型套模板。

组件库：references/report-blocks.md 是调研报告的组件库（一句话结论 / Executive Summary / 现状基线 / 假设验证表 / 反面观点 / 置信度标注 / 对比表 / 评分雷达 / 场景化推荐 / 调查拓扑 / 来源分级 等）。通用组件（表格 / 卡片 / Timeline / Callout / Chart）复用 writing skill 的 references/components.md，本 skill 不重复。

内容形态 → 组件 速查

组合原则

内容 → 组件 → 组合         ✅ 内容驱动
调研类型 → 模板 → 填空    ❌ 模板驱动

• 最小集：任何出报告的场景至少包含"一句话结论 + 参考资料"，其余按内容叠加
• 没内容就不要用对应组件：没有反面证据就不要"反面观点"段；没有内部数据就不要"现状基线"段（用 B2 一行说明即可）；没有多个候选就不要"对比表"
• 组件克制：单份报告不堆叠 ≥10 种组件，否则变成"组件展示馆"
• 顺序由内容逻辑决定：通常的逻辑链是"读者先看结论 → 看依据 → 看反驳 → 看建议 → 验证过程"——但按命题自然调整，不强制
• 复杂度参考（不是规则）：
  • 简单事实查询：不出报告，直接对话答复
  • 对比类：一句话结论 + 关键发现 + 对比块 + 场景化推荐 + 参考资料；假设验证 / 反面观点 / 调查拓扑按内容选用
  • 复杂研究 / 超深度：通常覆盖到 A1/A2/A3/B1/C1/C2/C3/E1/F1 + 正文用通用组件组装

历史范式（仅作为灵感参考）

references/templates/_common.md 收录了少量历史常见的章节顺序示例——只作为"别人通常怎么组合"的参考，不作为必备清单。直接看 report-blocks.md 选组件即可，不需要先选模板。

5.3 HTML 模式报告撰写

当输出格式为 HTML 时，参照 references/html-report-template.html 模板直接编写 HTML 报告。

写作流程：

1. Read 模板：读取 references/html-report-template.html，复制完整 HTML 结构（含 CSS + JS）
2. 填充报告头：替换 {{REPORT_TITLE}} 等占位符
3. 编写 Executive Summary：填入 .exec-summary 区域
4. 编写正文：在 <article> 标签内用 <h2>/<h3> 组织章节（目录 JS 自动提取）
5. 嵌入图表：将 bridge.py/capture.py 生成的 HTML 图表内容读取后，用 .chart-container 包裹嵌入
6. 填写参考资料：在 .references 区域按 T1/T2/T3 分组

可用的富文本组件（模板注释中有完整示例）：

引用标注（HTML 模式）：

数据描述<sup><a href="#ref-1">1</a></sup><span class="tier-badge tier-t1">T1</span>

输出要求：

• 单个 .html 文件，所有 CSS/JS 内联，浏览器直接打开
• 用 Write 工具一次性写入 docs/research/YYYY-MM-DD-<topic>.html
• 写入后用 open 命令在浏览器中打开供用户 review

5.4 引用标注（Markdown 模式）

正文中使用上标编号标注数据来源，指向末尾参考资料列表（不使用脚注，避免脚注和参考资料重复）：

Redis 在高并发场景下的 p99 延迟通常低于 2ms[1]，
而 Memcached 在相同条件下约为 1.5ms[2]。

末尾参考资料按来源层级分组，编号与正文对应：

## 参考资料

### 一手来源 [T1]
1. [Redis 官方 benchmark 文档](https://redis.io/docs/...) — p99 延迟数据

### 二手来源 [T2]
2. [InfoQ Redis vs Memcached 性能对比](https://www.infoq.cn/...) — 对比测试数据

引用原则：

• 关键数据点必须标注来源及层级 [T1]/[T2]/[T3]
• 观点性结论标注出处
• 多个来源佐证同一结论时，标注最权威的 1-2 个（优先一手来源）
• 只在末尾参考资料列表维护一份引用，正文用编号指向，不重复

5.5 写作要求

• 语言：默认中文，用户要求时切换为英文
• 措辞精确：避免"大概"、"好像"、"可能"等模糊用语，除非确实存在不确定性（此时需说明原因）
• 数据优先：能用数据说明的不用形容词，"快 3 倍"优于"显著更快"
• 结构清晰：善用表格、列表、对比矩阵呈现结构化信息
• 篇幅自适应：根据命题复杂度自然决定篇幅，不人为压缩也不注水

第六步：质量自检

报告写完后，自动执行以下 5 项检查。可自动修复的问题直接修复，需要判断的列出供用户决定。

6.1 检查维度

检查 1：内容覆盖（组件适配）

不再检查"必备章节是否齐全"，改为检查 1.1-1.6 中识别出的内容形态是否都有对应组件承载——避免"忘了写"，但不强求模板。

处理方式：

• 内容形态存在但组件遗漏 → 终端提示，列出哪些内容没装进组件
• 没有对应内容形态 → 跳过检查，不要"为了齐全"补章节（例如调研中没有反方证据就不要写"反面观点"段，没有内部数据就不要写"现状基线"段）
• 自动可修复项：仅"结论后未标注置信度"、"来源未分级"——其他靠人补

检查 2：引用格式

逐条扫描参考资料章节，检查：

• 参考资料是否按「一手来源 [T1]」「二手来源 [T2]」「三手来源 [T3]」三级分组
• 每条引用是否有 [T1]/[T2]/[T3] 层级标记
• 每条引用格式是否为 [标题](URL) — 引用说明
• 正文中引用关键数据时是否标注了来源编号

处理方式：可自动修复。

• 缺少分组 → 按来源类型自动归类到 T1/T2/T3
• 缺少层级标记 → 根据来源类型自动补充
• 格式不符 → 自动调整为标准格式
• 修复后在终端展示修复摘要

检查 3：假设验证表

检查假设验证表的完整性：

• 报告中是否存在假设验证结果表格
• 1.6 中提出的每个初始假设是否都在表中出现
• 每行是否包含三列：假设内容 | 验证结果（✅/❌/⚠️）| 关键证据及来源层级

处理方式：

• 表存在但个别行缺少结果标记或来源标注 → 自动补充格式占位（如 ⚠️ 待补充），在终端提示
• 表不存在 → 在终端提示「缺少假设验证表」，询问用户是否根据全文内容生成

检查 4：核心结论来源支撑

逐条检查「核心结论」章节中的每个结论：

• 该结论引用的证据来源层级是什么？
• 是否满足：至少 1 个 T1 来源 或 至少 2 个独立 T2 来源
• 仅有 T3 来源支撑的结论标记为不达标

处理方式：不可自动修复。在终端逐条列出不达标结论及其当前来源情况，询问用户是否补充搜索。

检查 5：调查拓扑段完整性

核对报告的"调查拓扑"段与 /tmp/research-topology-<timestamp>.json 记录文件：

• 报告是否包含 ## 调查拓扑 段
• 指标表的"派发 Sub-agent 数 / 最深递归层级 / 总 search / 总 fetch"与拓扑文件聚合值一致
• Sub-agent 分解表中每条 agent_id / parent_id / budget_used / status 字段与拓扑文件一致，不得遗漏
• abandoned_leads 非空时，报告必须列出"放弃的线索"子节
• 报告头元信息中的"调研深度"数字与拓扑段聚合值一致

处理方式：可自动修复。

• 拓扑段缺失 → 读取拓扑文件，按 5.2 模板自动生成
• 数字不一致 → 以拓扑文件为准自动回填
• 拓扑文件缺失 → 终端告警"过程记录缺失，无法可观测"，不阻塞报告交付但提示用户下次确保 Lead Agent 写入

6.2 执行流程

报告写完
  ↓
读取报告全文 + 拓扑文件 `/tmp/research-topology-<timestamp>.json`，逐项执行 5 项检查
  ↓
自动修复可修项（检查 2 引用格式、检查 3 表格式、检查 5 拓扑段）
  ↓
在终端输出检查摘要
  ↓
有不可修项？→ 列出问题，逐项询问用户处理意见
  ↓
用户决策（补写 / 补充搜索 / 跳过）→ 执行 → 完成
  ↓
清理 `/tmp/` 下本次调研产物（拓扑 / 计划 / 子文档）

6.3 终端输出格式

检查完成后在终端输出以下格式的摘要（不写入报告文件）：

📋 报告质量自检
─────────────────────────────────────
✅ 结构完整性：N/N 必备章节齐全（N = 当前模板必备章节数）
🔧 引用格式：修复了 N 处问题（具体：补充了 X 个层级标记，调整了 Y 条格式）
✅ 假设验证表：N 个假设均有验证结果和证据来源
⚠️ 核心结论来源支撑：
   · "结论内容摘要A" → 仅 1 个 T3 来源，不达标
   · "结论内容摘要B" → 2 个独立 T2 来源，达标
🔧 调查拓扑：派发 N 个 sub-agent，最深 L 层，search/fetch 共 M 次；自动回填 X 处数字

总计：N 项通过，M 项需处理
─────────────────────────────────────

如果有不达标项，逐项询问：

⚠️ "结论内容摘要A" 仅有 T3 来源支撑。
   → 补充搜索以找到 T1/T2 来源？(y/n)

如果全部通过：

✅ 质量自检全部通过，报告已完成。
文件路径：<报告文件路径>

6.4 补充手动检查

以下维度不易自动化，作为自检提醒在完成 4 项自动检查后快速过一遍：

• 数据一致性：Executive Summary 中的数字与正文一致？图表中的数字与正文描述一致？同一指标在不同章节无矛盾？
• 图表文件验证：Markdown 模式下所有 PNG 路径可访问？HTML 模式下图表内嵌正常渲染？
• 搜索覆盖自评：所有初始假设的验证点都被搜索覆盖？反面证据搜索已执行？未覆盖维度已在「未覆盖的问题」中列出？
• 信息时效标注：关键数据是否标注了数据年份？

如发现问题，当场修复后继续。