---
name: research-output
description: 对任何主题进行系统调研，自动产出图文并茂的 Markdown 文档（含 Mermaid 结构图 + qwen-image 可视化），保存到认知结构对应维度的知识库，并自动注册到文档分类清单和知识图谱。当用户说「帮我调研/调研一下/系统调研/研究一下/帮我系统了解/深度研究 [主题]」时触发。
---

# 系统调研输出 Skill（research-output）v2.0

> 触发词：「调研」「系统调研」「研究一下」「帮我系统了解」「深度研究」「全景调研」「大量调研」「调研一下」+ 主题词
> 产出：REF-EXT 图文 Markdown → 保存到认知结构知识库 → 自动注册三处
> ⚠️ 核心原则：**关键词驱动 → 多轮迭代 → 读原文 → 知识网络 → 写稿**

---

## 知识导航表（执行前必须理解的概念根）

| 层级 | 文档 | 需要理解的概念 |
|---|---|---|
| **D0 认知根（必读）** | `_内部总控/认知结构/L0_大脑总地图.md` | 调研成果的存放位置：K2外部参考（REF-EXT）存放在各L1维度的知识库子目录；调研前先确认目标维度 |
| **D3 规范参考** | `.cursor/rules/knowledge-integrity-rules.mdc`（R2 NO_FABRICATION + R3 READ_FIRST）| R2：调研结论必须有来源，禁止捏造；R3：读原文而非摘要（WebFetch优先于WebSearch）|
| **D4 运行时数据** | `_内部总控/认知结构/文档分类清单.md` + 目标L1维度的 `知识库/` 目录 | 注册目标：调研完成后必须注册到分类清单+知识图谱+L0总地图三处 |

**核心概念速查**：
① 调研产出 = K2 REF-EXT（外部知识汇编），不是L1框架（不代表郑总自己的思考）
② 读原文而非摘要（R3）：WebSearch只用于发现URL，WebFetch读取实际页面内容
③ 注册三处是ceremony(K2)的强制步骤：文档分类清单 + 知识图谱 + L0总地图

---

## 触发判断（先执行）

```
IF 用户说「帮我调研/大量调研/全景调研/全面调研/研究一下/调研一下/系统了解/深入了解/搜一下/查一下（需要结构化知识产出时）」
AND 有明确的调研对象（不是临时问一个问题/不是空答）
→ 触发本 Skill（mode=research，从 Phase 0 开始）

IF 用户说「完善[已有文档]/给[已有文档]加图/补充[已有文档]/这个文档缺图/按规范完善」
AND 明确指向某个已存在的知识库文档（REF-EXT）
→ 触发本 Skill（mode=improve，从 Phase 7 开始）

不触发（优先判断）：
- 「搜索一下/查一下/找一下」→ 临时查找，直接回答，不触发
- 「解释一下/这个是什么意思」→ 单点解释，不触发
- 「帮我调试/排查错误」→ 不触发
- 「研究一下/帮我研究」+ 后接「报错/错误/bug/为什么/怎么解决/代码问题/调试/排查」→ 调试场景，不触发

主题词不明确时：询问「你想调研的具体主题是什么？」等用户回答后触发。

组合场景：若用户同时含写作类关键词（「调研X然后写成文章/推文」）
→ 告知「本 Skill 先产出调研知识库文档，文章写作请完成本 Skill 后另触发 general-article-writer/wechat-article-writer」
→ 先执行本 Skill 完整流程
```

---

## D0：认知根确认（所有调研前必做，在三原则之前）

> 调研不是凭空获取外部知识，而是用认知结构作为框架来组织外部信息。
> 开始任何调研前，先回答：这个主题在郑总的认知结构（L1文档）里有没有相关内容？
>
> 快速读取 `_内部总控/认知结构/L0_大脑总地图.md` 扫描相关维度，若找到相关 L1 文档：
> → 先读该文档核心框架，以此作为「调研结果的落点」
> → 调研产出将以 REF-EXT 形式补充到对应 L1 维度知识库
>
> 若未找到相关 L1 文档：
> → 正常执行调研，调研完成后评估是否有 L2 碎片价值

---

## 调研架构前置三原则（执行前必读）

执行任何调研任务前，先完成「调研骨架」——这三条原则是 Phase 1-4 的提炼，违反任意一条会导致调研表面化：

**原则1「关键词图谱先行」**：列出 5-10 个种子词 → 扩展同义词/上下位词 → 按主题聚类 → 形成搜索骨架
（跳过此步骤 = 后续搜索在随机游走，无法保证覆盖完整性；对应 Phase 1）

**原则2「WebFetch 读原文强制」**：WebSearch 摘要只用于发现 URL，不可直接引用作为知识来源
> 正确路径：WebSearch 发现 URL → WebFetch 读原文 → 提炼知识点
> 违反 = 知识节点来自搜索引擎摘要，可靠性无法保证（对应 Phase 2 读原文标准）

**原则3「知识网络三层合成」**：核心（直接回答问题的）/ 中间（支撑背景）/ 外围（相关但非核心）
最终产出按三层组织，来源层级标注清楚（对应 Phase 4）

---

## Phase 0：维度判断（确定知识库路径）

将调研主题映射到 L1 维度：

| 主题特征 | 目标维度 | 知识库路径（完整）|
|---|---|---|
| 技术框架/开源工具/架构/编程/API/系统设计 | 技术架构思维维度 | `_内部总控/认知结构/L1_系统性文档/技术架构思维维度/知识库/` |
| 认知心理学/脑科学/学习/记忆/认知偏误 | 认知科学基础维度 | `_内部总控/认知结构/L1_系统性文档/认知科学基础维度/知识库/` |
| 产品设计/市场/竞品/商业模式/用户研究 | 产品理论维度 | `_内部总控/认知结构/L1_系统性文档/产品理论维度/知识库/` |
| 写作/发布/内容创作/配图/工具使用方法 | 待建维度 | `_内部总控/认知结构/L1_系统性文档/待建维度/知识库/` |
| 研究方法/学术规范/论文写作/数字人/仿真 | 研究范式维度 | `_内部总控/认知结构/L1_系统性文档/研究范式维度/知识库/` |
| 组织设计/团队协作/AI组织/社区运营 | 组织理论维度 | `_内部总控/认知结构/L1_系统性文档/组织理论维度/知识库/` |

**跨维度主题**：选更具体的维度，告知用户。
**无法判断**：询问「这个主题属于哪个方向？[列出上表6个选项]」，等用户确认后继续。

---

## Phase 1：关键词架构（研究开始的第一步，不可跳过）

> **核心思想**：好的调研从知道「要搜什么」开始，而不是直接开始搜。关键词图谱是整个调研的骨架。

### 1.1 生成种子关键词

```
基于调研主题，生成以下四类关键词（每类 3-5 个）：

A. 核心概念词：主题的核心术语（英文 + 中文）
B. 上位词：更宏观的领域/分类词
C. 下位词：更具体的子方向/分支词
D. 关联词：领域内常用的配套概念（工具/方法/场景）

示例（主题 = "多智能体协作"）：
A. 核心: multi-agent collaboration, LLM agent, 多智能体系统
B. 上位: distributed AI, autonomous AI systems
C. 下位: agent communication protocols, task decomposition, 工具调用链
D. 关联: LangGraph, CrewAI, AutoGen, 工作流编排, function calling
```

### 1.2 关键词扩展检查

```
对每个种子关键词，快速做：
- 同义/近义词检查（避免遗漏）
- 学术术语 vs 工程术语对照（两者都要搜）
- 最新版本/别名（如「ReAct」既是论文名也是方法名）
```

### 1.3 输出关键词图谱（Mermaid）

```
用 Mermaid mindmap 可视化关键词结构：

mindmap
  root((主题))
    核心概念A
    核心概念B
    上位域
      上位词1
    子方向
      下位词1
      下位词2
    关联工具/方法
      关联词1
      关联词2
```

输出关键词图谱后，**告知用户**：
```
📌 关键词图谱已就绪。我将按以下 [N] 个维度分轮调研：
[维度1]: [关键词列表]
[维度2]: [关键词列表]
...

✏️ 如果有遗漏的关键方向，请现在补充，确认后开始第一轮调研。
（等待用户确认或补充，若无响应则直接开始）
```

---

## Phase 2：第一轮调研（广度覆盖 + 读原文）

> **核心原则**：WebSearch 只用于**发现 URL**，每个重要来源必须用 **WebFetch 读取原始内容**，不允许将搜索摘要作为知识来源。

### 2.1 搜索执行规则

```
对每个关键词维度：

Step A: WebSearch "[关键词]"
   → 只记录 URL 列表，不从摘要提取知识
   → 优先级：官方文档/论文 > 权威技术博客 > 其他

Step B: WebFetch 前 N 个重要来源（N ≥ 2）
   → 实际读取原始页面内容
   → 必须：正文内容至少读 500 字
   → 禁止：只看标题/摘要后就记录知识

Step C: 记录知识节点（见 2.2）
```

**读原文标准（硬性要求）**：

```
✅ 合格：用 WebFetch 读取了该 URL，从原文中提取具体内容
✅ 合格：官方文档 → 读了对应章节的原文
✅ 合格：论文 → 读了摘要 + 引言 + 结论（PDF 无法访问时标注原因）

❌ 不合格：只有 WebSearch 摘要的 1-2 句话
❌ 不合格：「根据我的训练知识」→ 必须搜索验证，训练知识不作为调研来源
❌ 不合格：URL 已记录但未 WebFetch → 此条知识标注 [⚠️ 仅检索摘要，未读原文]
```

### 2.2 知识节点记录格式（内存中维护）

```
每读完一个来源，创建一个知识节点：

节点 {
  概念: "XXX 是什么/怎么工作"
  要点: ["核心事实1", "核心事实2"]
  来源_URL: "https://..."
  来源_类型: "官方文档 / 论文 / 博客 / ..."
  已读原文: true / false
  新发现关键词: ["出现的新术语1", "新术语2"]
  未解决问题: ["这里提到了X但不清楚是怎么做到的", ...]
}
```

### 2.3 第一轮结束后的知识盘点

```
第一轮搜索完成后，输出：

📊 第一轮调研总结：
- 已读原文来源：N 个
- 覆盖的知识节点：M 个
- 发现的新关键词：[列出]
- 未解决的知识空白：[列出]
- 需要第二轮深入的方向：[列出]
```

---

## Phase 3：关键词更新 + 第二轮调研（深度填空）

> **核心原则**：第二轮是针对空白的**定向补充**，而不是重复第一轮。

### 3.1 关键词更新

```
基于第一轮的「新发现关键词」和「未解决知识空白」，更新关键词列表：
- 新增第一轮发现的术语
- 标记第一轮没有覆盖到的子方向
- 删除已充分覆盖的关键词（避免重复搜索）
```

### 3.2 第二轮调研执行

```
专注于填充空白：

对每个「未解决知识空白」和「新发现关键词」：
  Step A: WebSearch
  Step B: WebFetch 读原文（规则同 Phase 2）
  Step C: 更新对应知识节点，或新建节点

第二轮必须包括：
  - 至少 1 次对比性搜索（"XXX vs YYY"，理解边界）
  - 至少 1 次「实践/案例」类搜索（不只是理论）
  - 至少 1 次「局限性/批评」类搜索（找这个方向的反面意见）
```

### 3.3 是否进行第三轮的判断

```
第二轮结束后评估：
  IF 未解决空白减少 > 80% AND 知识节点数量 ≥ 15 → 停止，进入 Phase 4
  IF 还有重要空白 AND 空白数量 > 3 → 告知用户执行第三轮
  IF 用户明确说「够了/停止」→ 直接进入 Phase 4

最多 3 轮（防止无限循环）。
```

---

## Phase 4：知识网络合成（从节点到结构）

> **核心原则**：调研结束后，不要直接写文章。先建立知识的层次关系，再写。

### 4.1 三层知识网络

```
将所有知识节点分层归类：

核心层（2-4个）：
  - 整个主题的「骨架概念」
  - 删去这些，整个主题就崩塌的概念

中间层（5-10个）：
  - 支撑核心层的主题群
  - 每个都有自己的关键词、来源和细节

外围层（若干）：
  - 具体实现/工具/案例/数据
  - 为中间层提供证据支撑
```

### 4.2 输出知识连接图（Mermaid）

```
用 Mermaid graph 展示节点连接：

graph TD
  核心概念A --> 中间层主题1
  核心概念A --> 中间层主题2
  核心概念B --> 中间层主题2
  中间层主题1 --> 外围工具/案例1
  ...

连接类型（用边标签标注）：
  A -->|"includes"| B   (A 包含 B)
  A -->|"enables"| B    (A 使得 B 成为可能)
  A -->|"vs"| B         (A 与 B 是对比关系)
  A -->|"example"| B    (B 是 A 的一个具体例子)
```

---

## Phase 5：撰写 V1 草稿（基于知识网络）

> V1 草稿的结构应反映知识网络的层次，而不是「网上看到什么就写什么」。

**文档结构**（从知识网络映射）：

```markdown
# [主题] 调研报告

> 文档类型：**REF-EXT**（外部参考知识）
> 调研日期：YYYY-MM-DD
> 调研轮次：N 轮（N 个来源，M 个已读原文）
> 调研目的：[从用户请求提取，一句话]
> 来源说明：AI网络调研产出（具体来源见文档末「参考来源」章节）
> 注意：本文档为外部知识汇编，不是郑总个人思考产物，不进入认知结构 L1/L2/L3
> 分类登记：`_内部总控/认知结构/文档分类清单.md` 区域十二

## 摘要
[核心结论 3-5 条，每条一句话，必须对应知识网络的核心层]

## 知识结构导览
[嵌入 Phase 4 生成的知识连接图 Mermaid]

## 一、[核心层概念1]（对应核心层节点）
[内容，每个重要事实标注来源序号 [N]]

## 二、[核心层概念2]
[内容]

## 三、[中间层主题群 - 按逻辑分章]
[内容]

...

## 局限性与反面意见
[第二轮「批评类」搜索的发现，不可省略]

## 参考来源

> 强制要求：每条必须包含全部字段；标注是否已 WebFetch 读原文

| 序号 | 作者/机构 | 标题 | URL | 访问日期 | 已读原文 |
|---|---|---|---|---|---|
| [来源1] | GitHub/xxx | 标题 | https://... | 2026-03-21 | ✅ |
| [来源2] | arXiv | 标题 | https://... | 2026-03-21 | ✅ |
| [来源N] | ... | ... | [⚠️ 无URL] | ... | ❌ |

未 WebFetch 的来源需标注「❌ 未读原文」，并说明原因。
```

**Mermaid 使用规则**：
```
✅ 用 Mermaid：流程/决策/步骤序列 / 系统模块关系 / 时序交互
❌ 不用 Mermaid（留给 qwen-image）：数据图表 / 概念框架/矩阵 / 需要视觉层次的架构图
```

> ⚠️ **草稿完成检查点（强制）**：V1 草稿完成后，**下一步必须执行 Phase 6（绘图识别）**，不允许直接跳到 Phase 8 写文件。

---

## Phase 6：自审 — 识别 qwen-image 画图位置（内存操作）

```
第一步：确认绘图指南文件位置
  尝试 Read: _内部总控/认知结构/L1_系统性文档/待建维度/知识库/全场景绘图指南.md
  若文件不存在（路径可能变更）：
    使用 Glob 搜索：**/全场景绘图指南.md
    找到 → 读取找到的路径
    未找到 → 跳过 Phase 6 和 Phase 7，告知用户「绘图指南文件未找到，已跳过 qwen-image 可视化」

按以下标准扫描 V1 草稿，识别适合 qwen-image 的位置：

✅ 适合 qwen-image：
  - 概念框架图（多概念关系，Mermaid 无法美观展示）
  - 对比矩阵/象限图（两维度比较）
  - 数据可视化（有具体数值）
  - 分层架构图（视觉层次感强）
  - 已有 Mermaid 的位置 → 在 Mermaid 下方加可视化版本

❌ 不适合：
  - 纯文字段落
  - 代码块
  - 表格已清晰的内容
  - 来源列表

输出：适合 qwen-image 的位置列表（位置描述 + 图类型 + 提示词草稿）

降级条件：
- 绘图指南文件不存在 → 跳过 Phase 6 和 Phase 7，直接进 Phase 8
- 识别到 0 个适合位置 → 跳过 Phase 7，直接进 Phase 8
```

---

## Phase 7：调用 qwen-image 生成图片并嵌入（内存操作）

**若 Phase 6 识别到 0 个适合位置，跳过本 Phase。**

> ❌ **严禁使用 Cursor 内置的 `GenerateImage` 工具**
> ❌ **严禁只输出提示词让用户手动执行**
> ❌ **严禁引用 `article-image-angles` Skill**（公众号专用）
> ✅ 唯一正确路径：加载 `ai-image-generator` Skill，按其绘图流程（Step 0~5）执行

**调用方式**：

```
Step 1：Read `.cursor/skills/ai-image-generator/SKILL.md`
Step 2：按 ai-image-generator 的绘图流程执行：
   - Step 0（对象-关系分析）
   - Step 1（分析段落逻辑）
   - Step 2（多视角草图，每张图至少2个视角）
   - Step 3（API 调用，优先 qwen-image-2.0-pro）
   - Step 4（更新配图索引，若无索引则创建）
   
模型选择：
   - 含中文文字的信息图/结构图 → qwen-image-2.0-pro（首选）
   - 纯视觉风格图 → wan2.6-t2i（次选）
   API 配置统一引用：_内部总控/凭证/AI能力配置.md
```

**嵌入格式**（Mermaid 保留，qwen 图插入下方）：

```markdown
```mermaid
[原 Mermaid 代码，保留不删]
```

> 📊 可视化版本：
![图描述](data:image/png;base64,[base64字符串])
```

**失败处理**：
- 单张图失败 → 跳过该图，继续其他图
- 全部失败 → 使用文字+Mermaid 版本，末尾标注「[图片生成失败，已保存文字版本]」

---

## Phase 8：一次性写入文件

> ⚠️ **写入前强制确认（不可跳过）**：
> - Phase 6 识别出了几个适合 qwen-image 的位置？
> - Phase 7 实际生成/尝试了几张图？
> - 若两个数字均为 0，且用户未明确说「不要图片」或「跳过生图」：
>   → 不允许进入 Phase 8，必须回到 Phase 6 重新识别，或向用户确认
> - 允许继续的条件：① 生成了图片，OR ② 绘图指南不存在（已降级），OR ③ 用户明确说不要图

> ℹ️ **write-guard 例外**：本步骤写入 `L1_系统性文档/[维度]/知识库/` 路径，属于 REF-EXT 操作，`cognitive-structure-write-guard` 明确豁免此路径。无需版本快照/归因标注/L0更新。

**文件命名**：`[主题关键词]_调研_YYYYMMDD.md`

**目录检查**（写入前）：
```
检查 `_内部总控/认知结构/L1_系统性文档/[维度]/知识库/` 是否存在。
不存在则先创建：mkdir -p [路径]
```

**重复文件检查**（写入前）：
```
检查目标目录下是否有文件名含相同主题关键词的文件（完全同名才算）。
若有：询问「已有 [文件名]，更新现有文件还是新建？」等用户选择后继续。
```

写入内容 = V1 草稿（包含 Phases 4-7 的所有内容）。

**保存失败时**：在对话中输出完整文档内容，告知用户建议手动保存到 `[正确路径]`。

⚠️ **写入成功后，不输出「完成」信号，立即继续 Phase 9**。

---

## Phase 9：自动注册三处（不可跳过）

**先执行：确定知识图谱 ID 序号**
```
Read: _内部总控/认知结构/知识图谱_正式文档.md
→ grep 全部今日条目，找 REF-EXT 区段中以「[维度缩写]-」开头的最大序号
→ 新 ID = 最大序号 + 1（如已有 TECH-001、TECH-002 → 新建 TECH-003）
→ 若该维度无已有条目 → 从 001 开始
维度缩写规则：技术架构=TECH / 认知科学=COGS / 产品理论=PROD / 待建维度=METH / 研究范式=RSCH / 组织理论=ORG
```

**①** `_内部总控/认知结构/文档分类清单.md` 区域十二末尾追加一行：
```
| _内部总控/认知结构/L1_系统性文档/[维度]/知识库/[文件名] | REF-EXT | [维度] | ★ CURRENT | [主题一句话描述，含调研日期] |
```

**②** `_内部总控/认知结构/知识图谱_正式文档.md` REF-EXT 区段末尾追加一行：
```
| [文档ID] | [主题简称] | [维度] | [核心内容一句话] | [维度]/知识库/ | [关联L1文档，不确定填「—」] |
```

**③** `_内部总控/认知结构/L3_原始记录/系统日志.md` 末尾追加一条：
```
[LOG-YYYYMMDD-NN] research-output | 调研：[主题] → [维度]/知识库/[文件名]，知识图谱ID：[ID]，调研轮次：N轮，已读原文来源：M个
```

**注册完成后，告知用户**：
```
✅ 调研完成
📄 文档：[完整文件路径]
📌 知识图谱 ID：[ID]
📋 已注册到文档分类清单（区域十二）
📝 系统日志已更新
📊 本次调研：N 轮，已读原文 M 个来源，知识节点 K 个
```

**若 D0 中找到了相关 L1 文档**（调研前已读过的相关 L1 文档），在✅告知后追加一行：
```
💡 本次调研涉及到您的认知文档「[L1文档名]」，建议检查是否存在矛盾。
   [运行矛盾检测（cognitive-detect-contradiction）] [暂不检测]
```
→ 用户选「运行矛盾检测」→ 触发 cognitive-detect-contradiction Skill
→ 用户选「暂不检测」→ 正常结束

**任一注册失败时**：告知哪步失败，建议手动补注册；已成功的注册保留。

---

## 边界情况

| 情况 | 处理方式 |
|---|---|
| 主题跨维度 | 选更具体维度，注册时告知用户 |
| 用户说「不用存文件/只是问问」| 跳过 Phase 8/9，只输出调研内容 |
| 目录不存在 | Phase 8 写入前自动创建 |
| 同名文件已存在 | 询问「更新还是新建」 |
| 组合触发（调研+写文章）| 先完成本 Skill，再提示触发写作 Skill |
| 调研轮次超过 3 轮仍有空白 | 输出现有成果，标注「[⚠️ 以下方向未充分覆盖：...]」 |
| WebFetch 某 URL 无法访问 | 标注 [⚠️ URL 无法访问，已跳过]，搜索替代来源 |

---

## 长文档生成工具参考（2026-03-21 新增）

以下工具适用于调研后的大规模文档生成场景，可与本 Skill 的 Phase 5 产出配合使用：

| 工具 | 来源 | 特点 |
|---|---|---|
| WriteHERE | principia-ai（EMNLP 2025 Oral）| 学术背书最强，DAG 任务管理 + 异质递归规划，单次生成 4万字+；适合超长调研报告 |
| OpenDraft | 19 Agent 协作（MIT 许可）| 学术引用准确率 100%（vs ChatGPT 76.6%），适合知识系统调研类文档，引用来源可信度更高 |

> 注意：以上工具为外部工具参考，本 Skill 不自动调用，仅作为「Phase 5 草稿 → 长文档扩展」阶段的选项提示。

---

## mode=bulk_archive：批量文档归档（新增，2026-03-24）

> **触发条件**：用户提供 URL 列表 + 可选 GitHub 仓库列表，要求批量下载/存档
> **区别于 mode=research**：本模式是「被动存档」——给定来源，下载全量内容；不做主动搜索和知识合成
> 触发词：「下载这些页面」「把这些文档存下来」「下载到本地」「把参考资料存档」「git到本地」「clone这些仓库」

### Phase A0：准备归档目录

```bash
# 创建归档根目录（以主题命名，日期后缀）
mkdir -p "{知识库路径}/{主题}_参考文档库/{域名1}"
mkdir -p "{知识库路径}/{主题}_参考文档库/{域名2}"
mkdir -p "{知识库路径}/{主题}_参考文档库/github_repos"
```

目录结构约定：
```
{主题}_参考文档库/
├── {域名1}/          ← 每个站点一个子目录（如 mbrenndoerfer_com/）
│   ├── {页面标题}_{日期}.md
│   └── ...
├── {域名2}/
├── github_repos/    ← 克隆的仓库
│   ├── {repo1}/
│   └── clone_log.txt
└── INDEX.md         ← 归档索引
```

### Phase A1：批量下载网页

对每个指定 URL，执行：
1. `WebFetch {URL}` 获取完整内容
2. `Write` 保存为 `{域名子目录}/{标题简化}_{YYYYMMDD}.md`
3. 探索该站点相关页面链接（同域名，与主题相关，最多 3-5 页），重复步骤 1-2

**大页面处理**（>500行内容）：
- 若内容已在 agent-tools 缓存中（路径：`/Users/boyuan/.cursor/projects/.../agent-tools/{uuid}.txt`）
- 直接使用 `Shell: cp {cache_path} {dest_path}` 复制，避免重复 fetch

**Write 格式**：
```markdown
> 来源：{URL}
> 下载日期：{YYYYMMDD}
> 站点：{domain}

{完整页面内容}
```

### Phase A2：克隆 GitHub 仓库

```bash
# 浅克隆（只取最新 commit，节省空间）
git clone --depth=1 {repo_url} {本地路径}

# 记录日志
echo "[$(date +%Y%m%d)] {repo_url}" >> github_repos/clone_log.txt
```

**仓库选择标准**（与主题相关度 × 实用性）：
- 有实际生产级代码示例（not just README）
- Stars 数量较高（生产验证）
- 代码量适中（不选超 500MB 的巨型仓库，除非用户明确指定）

**大型仓库处理**：
- `vllm/ray/langchain` 等超大仓库 → `--depth=1`（只取最新快照）
- 或使用 sparse-checkout 只拉取 examples/ 目录

### Phase A3：创建归档索引

在归档根目录创建 `INDEX.md`：

```markdown
# {主题}参考文档库 - 归档索引
归档日期：{YYYYMMDD} | 总文件数：N | 总仓库数：M

## 已保存网页
| 来源 | 本地路径 | 简述 |
|---|---|---|
| {URL} | {相对路径} | {一句话} |

## 已克隆仓库
| 仓库 | 本地路径 | 简述 | Stars |
|---|---|---|---|
| {URL} | github_repos/{name} | {一句话} | {N}k |

## 使用说明
- 所有内容均为只读参考，不做主动维护
- 如需更新，重新执行 mode=bulk_archive
```

### Phase A4：系统日志追加

```
[LOG-YYYYMMDD-NN] research-output(bulk_archive) | 归档：{主题} → {归档路径}，网页 N 篇，仓库 M 个
```

---

## 变更记录

### v1.0 — 2026-03-19 — 初始创建

**根因**：网络调研结果无持久化规范；AI 随机保存到错误位置，无图无注册。

**内容**：维度自动判断→V1含Mermaid→自审选图→qwen-image嵌入（Mermaid保留）→一次性保存→自动注册三处

**关卡A/B/C修复**：绘图指南路径/API调用方式/系统日志路径/路径前缀/跳过逻辑/ID序号/write-guard例外/维护协议矛盾/触发词完善/参考资料强制/pre-save强制门/mode=improve入口/ai-image-generator统一引用/Step 2强制检查点

**验证状态**：✅ 关卡A/B/C 通过

---

### v1.2 → v1.3 — 2026-03-20 — thin wrapper 化（document-pipeline 统一入口）

**根因**：创建了 document-pipeline 统一写作流水线。research-output 变为入口路由层。
**修改内容**：新增 thin wrapper 转发块。原有 Step 0-5 保留为历史参考。
**验证状态**：🔵 待验证（v2.0 中已废弃 thin wrapper，恢复独立执行）

---

### v1.5 → v1.6 — 2026-03-21 — Step 1 末尾加强制 Step 2 提醒

**根因**：AI 完成 V1 草稿后直接跳到写文件，跳过绘图步骤。
**修改内容**：Step 1 末尾新增强制检查点提示。
**备份路径**：`history/SKILL_v1.5_20260321.md`

---

### v1.6 → v2.0 — 2026-03-21 — 关键词驱动 + 多轮迭代 + 读原文强制（架构重写）

**根因**：用户明确指出 research-output 的单轮搜索缺乏深度——没有关键词架构、没有多轮迭代、没有读原文强制，导致调研是表面知识而非系统性知识。核心改进：「先建关键词图谱 → 多轮迭代（至少2轮）→ 每轮必须 WebFetch 读原文 → 知识网络合成 → 最后写稿」。

**修改内容**：
- 新增：Phase 1「关键词架构」——种子词/扩展/聚类/Mermaid图谱/用户确认
- 新增：Phase 3「关键词更新」——第一轮后盘点空白，更新关键词，驱动第二轮
- 新增：Phase 4「知识网络合成」——三层结构（核心/中间/外围）+ 知识连接图
- 修改：Phase 2「第一轮调研」——新增读原文强制规则、知识节点记录格式、知识盘点输出
- 新增：Phase 3「第二轮调研」——定向填空、对比搜索、批评类搜索强制要求
- 修改：Phase 5（原 Step 1）——文档结构从「网上看什么写什么」改为「从知识网络映射」
- 废弃：thin wrapper 转发机制（恢复独立执行）
- 所有原 Step 编号改为 Phase 编号，与迭代逻辑对应

**验证方法**：
- 正向①：下次执行 research-output，回复中应出现「关键词图谱」Mermaid，以及「第一轮调研总结」的分析段
- 正向②：每个知识来源应有对应的 WebFetch 调用，参考资料表中「已读原文」列大多数为 ✅
- 负向：触发词不变，非调研场景（「研究一下这个报错」）不触发

**已知风险**：多轮迭代会增加调研时间（约增加 30-50%），但深度显著提升。用户可在关键词确认时明确说「快速模式/只做一轮」来跳过第二轮。

**备份路径**：`history/SKILL_v1.6_20260321.md`

**验证状态**：🔵 待验证（下次真实调研任务时验证）

---

### v2.1 → v2.2 — 2026-03-22 — Phase 9 补 L1 矛盾检测提示（GAP-CN009-1 修复）

**根因**：scenario-sandbox-builder Phase 2 验证（CN-009沙盘）发现：research-output 调研完成后，即使 D0 读到了相关 L1 文档，Phase 9 也不会主动提示用户检查调研结论与 L1 是否存在矛盾，长期导致知识库内容分裂。

**修改内容**：
- 新增：Phase 9「注册完成后告知用户」之后，若 D0 中找到了相关 L1 文档，追加矛盾检测提示（含触发词「运行矛盾检测」和「暂不检测」选项）
- 备份路径：`history/SKILL_v2.1_20260322_before_cn009.md`

**验证方法**：调研完成后，若 D0 找到了相关 L1 文档，Phase 9 应输出「💡 建议检查是否存在矛盾」提示
**验证状态**：🔵 待验证

---

### v2.2 → v2.3 — 2026-03-24 — 新增 mode=bulk_archive（批量文档归档能力）

**根因**：research-output 只有主动研究+合成模式，无法处理「给定 URL 列表批量下载 + GitHub 仓库克隆到本地」的纯存档需求。典型场景：用户在调研后标记了若干高质量文档希望完整保存，以及希望将相关开源仓库 git clone 到本地作为离线参考。

**修改内容**：
- 新增 `mode=bulk_archive` 触发条件及 Phase A0-A4 步骤
- 大页面处理：优先使用 agent-tools 缓存文件 Shell cp（避免重复 fetch）
- 明确仓库选择标准和大型仓库处理策略

**备份路径**：`history/SKILL_v2.2_20260324_before_bulk_archive.md`

**验证状态**：🔵 待验证（本次执行即为验证场景）

---

### v2.0 → v2.1 — 2026-03-21 — 补充调研架构三原则（前置骨架）+ WriteHERE/OpenDraft 工具标注

**根因**：
- 经验D（2026-03-21）：多轮迭代调研中，「关键词图谱先行 / WebFetch读原文 / 三层合成」三条原则是调研深度的核心骨架，但原 v2.0 将其分散在 Phase 1/2/4 中，缺乏前置统一声明，导致 AI 可能只走形式而忽略原则。
- 经验E（2026-03-21）：WriteHERE（principia-ai，EMNLP 2025 Oral）和 OpenDraft（19 Agent协作，MIT）是调研后长文档生成的高价值工具，值得在 Skill 中标注备查。

**修改内容**：
- 新增：「调研架构前置三原则」区块（置于 Phase 0 之前），将三条原则提炼为执行前必读
- 新增：「长文档生成工具参考」表格（置于变更记录之前），标注 WriteHERE 和 OpenDraft

**验证方法**：
- 正向验证：下次执行 research-output，AI 应在回复开头体现三原则意识（如提到「先建骨架」「WebFetch读原文」）
- 负向验证：工具参考表不干扰现有执行流程（Phase 1-9 步骤不变）

**验证状态**：🔵 待验证

**备份路径**：`history/SKILL_v2.0_20260321.md`