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 草稿的结构应反映知识网络的层次，而不是「网上看到什么就写什么」。

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

# [主题] 调研报告

> 文档类型：**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 图插入下方）：

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

📊 可视化版本：


**失败处理**：
- 单张图失败 → 跳过该图，继续其他图
- 全部失败 → 使用文字+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` 区域十二末尾追加一行：


**②** `_内部总控/认知结构/知识图谱_正式文档.md` REF-EXT 区段末尾追加一行：


**③** `_内部总控/认知结构/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，执行：

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

大页面处理（>500行内容）：

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

Write 格式：

> 来源：{URL}
> 下载日期：{YYYYMMDD}
> 站点：{domain}

{完整页面内容}

Phase A2：克隆 GitHub 仓库

# 浅克隆（只取最新 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：

# {主题}参考文档库 - 归档索引
归档日期：{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

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总地图三处

触发判断（先执行）

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 的提炼，违反任意一条会导致调研表面化：

原则2「WebFetch 读原文强制」：WebSearch 摘要只用于发现 URL，不可直接引用作为知识来源

正确路径：WebSearch 发现 URL → WebFetch 读原文 → 提炼知识点违反 = 知识节点来自搜索引擎摘要，可靠性无法保证（对应 Phase 2 读原文标准）

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 草稿的结构应反映知识网络的层次，而不是「网上看到什么就写什么」。

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

# [主题] 调研报告

> 文档类型：**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 图插入下方）：

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

📊 可视化版本：


**失败处理**：
- 单张图失败 → 跳过该图，继续其他图
- 全部失败 → 使用文字+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 序号**


**①** `_内部总控/认知结构/文档分类清单.md` 区域十二末尾追加一行：


**②** `_内部总控/认知结构/知识图谱_正式文档.md` REF-EXT 区段末尾追加一行：


**③** `_内部总控/认知结构/L3_原始记录/系统日志.md` 末尾追加一条：

[LOG-YYYYMMDD-NN] research-output | 调研：[主题] → [维度]/知识库/[文件名]，知识图谱ID：[ID]，调研轮次：N轮，已读原文来源：M个


**注册完成后，告知用户**：


**若 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，执行：

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

大页面处理（>500行内容）：

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

Write 格式：

> 来源：{URL}
> 下载日期：{YYYYMMDD}
> 站点：{domain}

{完整页面内容}

Phase A2：克隆 GitHub 仓库

# 浅克隆（只取最新 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：

# {主题}参考文档库 - 归档索引
归档日期：{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 通过

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

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 — 关键词驱动 + 多轮迭代 + 读原文强制（架构重写）

修改内容：

新增：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 修复）

修改内容：

新增：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（批量文档归档能力）

修改内容：

新增 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 步骤不变）

验证状态：🔵 待验证

research-output

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills

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

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

触发判断（先执行）

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

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

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

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

1.1 生成种子关键词

1.2 关键词扩展检查

1.3 输出关键词图谱（Mermaid）

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

2.1 搜索执行规则

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

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

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

3.1 关键词更新

3.2 第二轮调研执行

3.3 是否进行第三轮的判断

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

4.1 三层知识网络

4.2 输出知识连接图（Mermaid）

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

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

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

Phase A1：批量下载网页

Phase A2：克隆 GitHub 仓库

Phase A3：创建归档索引

Phase A4：系统日志追加

变更记录

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

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

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

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

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

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

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

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

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

触发判断（先执行）

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

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

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

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

1.1 生成种子关键词

1.2 关键词扩展检查

1.3 输出关键词图谱（Mermaid）

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

2.1 搜索执行规则

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

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

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

3.1 关键词更新

3.2 第二轮调研执行

3.3 是否进行第三轮的判断

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

4.1 三层知识网络

4.2 输出知识连接图（Mermaid）

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

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

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

Phase A1：批量下载网页

Phase A2：克隆 GitHub 仓库

Phase A3：创建归档索引

Phase A4：系统日志追加

变更记录

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

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

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

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

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

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

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