# Deep Research Agent

深度研究技能，用于系统性调研与分析。适用于研究、调研、竞品分析、市场分析或结构化信息收集等需求。

- Repository: https://github.com/ZHangZHengEric/Sage (1219 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add ZHangZHengEric/Sage --skill deep-research-agent -g -a claude-code -y`
Codex: `npx skills add ZHangZHengEric/Sage --skill deep-research-agent -g -a codex -y`
Cursor: `npx skills add ZHangZHengEric/Sage --skill deep-research-agent -g -a cursor -y`
Gemini CLI: `npx skills add ZHangZHengEric/Sage --skill deep-research-agent -g -a gemini-cli -y`

## Description

深度研究技能，用于系统性调研与分析。适用于研究、调研、竞品分析、市场分析或结构化信息收集等需求。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 深度研究 Agent

以增量方式开展系统化研究并输出。

## 工作流

```
1. 大纲 → 2. 初始化 → 3. 研究 → 4. 更新 → 5. JSON → 6. HTML
```

### 1. 创建大纲（必须）

研究前先向用户展示大纲：
- 研究目标
- 需要回答的关键问题
- 需要探索的信息来源
- 预期交付物

**获得用户确认后再继续。**

### 2. 初始化研究环境

运行初始化脚本，使用绝对路径创建工作目录：

```bash
python skills/deep-research-agent/scripts/init_research.py <absolute_template_path> <absolute_project_path>
```

**用法：** `python init_research.py <absolute_template_path> <absolute_project_path>`

**模板（研究方向模板）：**

不同研究类型使用对应的 Markdown 模板：

模板统一放在 `deep-research-agent/templates` 目录下，初始化时只需选择对应模板文件路径。

**创建内容：**
- `report.md` - 复制选定模板（位于项目目录）
- `materials/` - 原始资料与笔记目录（包含 raw/ 与 notes/）

> **重要：** 不要用 mkdir 或 Write tool 手动创建目录，必须通过初始化脚本生成结构。

### 3. 执行研究（增量）

**搜索并立即保存：**

每条有价值的信息都要 **先保存到 materials 目录：**

```python
file_write(
    file_path="{project_path}/materials/raw/source_001.md",
    content="""## 来源: [标题]
- URL: [链接]
- 时间: [日期]

### 关键信息
- [要点1]
- [要点2]

### 数据
- [数据点]

### 引用原文
> [原文摘录]
"""
)
```

**研究策略：**
- 按章节/小节搜索
- 立即保存来源到 `materials/`
- 标注与报告章节的关联

### 4. 按章节更新报告

当某一节内容充足时，**立即更新报告：**

```python
file_update(
    file_path="{project_path}/report.md",
    operations=[{
        "update_mode": "search_replace",
        "search_pattern": "## 1. 研究背景与目标\n\n{研究背景说明}",
        "replacement": """## 1. 研究背景与目标

### 1.1 研究背景

[基于materials/中的资料，撰写详细背景]

[包含数据支撑、引用来源]

### 1.2 研究目标

[具体目标]

### 1.3 研究范围

[范围界定]"""
    }]
)
```

**更新规则：**
- 某一节有 3+ 可靠来源即可撰写
- **必须完全替换**：更新时务必彻底替换模板中的占位符内容，不要保留任何示例文字（如 `[在此填写...]`、`{占位符}` 等）
- **逐段检查**：替换后通读该节内容，确保没有残留的模板示例文字

### 5. 质量检查与内容验证

**在生成最终输出前，必须执行以下检查：**

#### 5.1 清理模板内容
- 检查 `report.md` 中是否还有未填充的模板占位符（如 `{研究背景说明}`、`{在此填写...}`、`[请填写...]` 等）
- **全部删除或替换**为实际内容，禁止保留任何占位符

#### 5.2 章节完整性检查
- 确保所有章节都已用实际研究内容替换，没有空章节
- 检查是否有仅包含标题而无实质内容的章节
- 如某些章节确实无相关内容，**直接删除该章节标题**，不要留空

#### 5.3 内容合理性验证
- **通读全文**：从头到尾阅读报告，确保逻辑连贯
- **检查一致性**：确保数据、结论在各章节中保持一致
- **验证引用**：确保引用的来源与实际收集的 materials 对应
- **删除示例文字**：确保没有残留的模板示例文字（如 "[基于materials/中的资料...]" 等指导语）

The rest: https://github.com/ZHangZHengEric/Sage/blob/HEAD/app/skills/deep-research-agent/SKILL.md