---
name: atomic_research
description: 知识调研 - 根据目标和任务自动执行搜索，返回结构化知识列表
---

## 信息调研

你可以通过联网搜索工具`search_posts`大概浏览来自Github、小红书、微信公众号、知乎等渠道的信息，并再使用`select_post`工具查看具体信息。

## 调研过程可能需要多次搜索，比如基于搜索结果中获得的启发或信息启动新的搜索，直到得到令人满意的答案。你可以使用 `goal` 工具管理搜索的过程，或者使用文档记录搜索的中间或最终结果。（可以着重参考browser的工具来辅助搜索）

## 工作流程

### 输入

- **目标**：要达成的目标（如"找到 PDF 表格提取的最佳方案"）
- **任务**：具体的任务描述（如"从复杂 PDF 中提取表格数据"）

### 执行流程

**Step 1: 拆解搜索维度**

```
goal(add="搜索工具, 搜索案例, 搜索方法论")
```

**Step 2: 多维度搜索**

- 搜索工具：`search_posts(query="PDF table extraction tool")`
- 搜索案例：`search_posts(query="PDF table extraction usercase site:github.com")`
- 搜索定义：`search_posts(query="PDF table extraction definition")`
- 搜索方法：`search_posts(query="PDF table extraction best practice")`

**Step 3: 结构化记录**
每发现一条有价值的信息，立即保存为结构化知识：

```python
knowledge_save(
    task="在什么情景下，要完成什么目标，得到能达成一个什么结果",
    content="这条知识实际的核心内容",
    types=["tool"],  # tool/usecase/definition/plan/strategy/user_profile
    urls=["参考的论文/github/博客等"],
    agent_id="当前 agent ID",
    score=5
)
```

**Step 4: 输出知识列表**

```
goal(done="已完成调研，共记录 N 条知识")
```

### 输出

- 保存到 `.cache/knowledge_atoms/` 目录，每条知识一个 JSON 文件
- 文件名格式：`atom-YYYYMMDD-HHMMSS-XXXX.json`
- 返回知识列表摘要

---

## 知识结构

每条知识原子包含以下字段：

### ① id（唯一标识）

格式：`atom-YYYYMMDD-NNN`

示例：`atom-20260302-001`

### ② tags（知识类型）

单条知识可以包含多个标签：

| 类型           | 说明                                       | 示例                                |
| -------------- | ------------------------------------------ | ----------------------------------- |
| **tool**       | 工具相关信息，包含使用案例和使用方法       | pdfplumber 库的使用方法             |
| **usercase**   | 针对任务的用户案例，某个用户完成任务的方法 | 某用户如何提取 PDF 表格的完整流程   |
| **definition** | 内容的具体定义，或任务的问题定义           | 什么是 PDF 表格提取，有哪些技术挑战 |
| **plan**       | 完成任务的通用计划、方法论或流程           | PDF 表格提取的标准流程和最佳实践    |

### ③ summary（摘要）

**格式**：在 [情景] 下，完成 [目标]，得到 [预期结果]。

**示例**：

```
在 Python 3.11 环境下，需要从结构复杂的 PDF（包含多列、嵌套表格）中提取表格数据，
并保留单元格坐标信息，最终得到可用于数据分析的结构化数据。
```

### ④ content（核心内容）

这条知识实际的核心内容，使用 Markdown 格式，根据类型不同包含不同信息：

**tool 类型**：

- 工具名称和简介
- 核心 API 和使用方法
- 适用场景
- 优缺点对比
- 代码示例

**usercase 类型**：

- 用户背景和需求
- 采用的方案
- 实现步骤
- 遇到的问题和解决方法
- 最终效果

**definition 类型**：

- 概念定义
- 技术原理
- 应用场景
- 与相关概念的区别

**plan 类型**：

- 完整流程步骤
- 关键决策点
- 常见陷阱和避坑指南
- 评估标准

### ⑤ tips（避坑指南）

⚠️ 具体的避坑指南或核心建议。

**示例**：

```
⚠️ 如果 PDF 包含隐形表格线，务必开启 explicit_horizontal_lines 参数
⚠️ 使用 page.crop() 先裁剪区域再提取，可提升 3-5 倍速度
```

### ⑥ trace（回溯）

**包含**：

- `urls`: 参考的论文、GitHub、博客等（URL 列表）
- `agent_id`: 执行此调研的 agent ID
- `timestamp`: 记录时间

**示例**：

```json
{
  "urls": ["https://github.com/jsvine/pdfplumber"],
  "agent_id": "research_agent_001",
  "timestamp": "2026-03-02T12:45:41Z"
}
```

### ⑦ eval（评估反馈）

**包含**：

- `helpful`: 好用的使用次数（初始值为 1）
- `harmful`: 不好用的使用次数（初始值为 0）

**示例**：

```json
{
  "helpful": 1,
  "harmful": 0
}
```

### ⑧ execute_history（执行历史）

**包含**：

- `helpful`: 好用的使用案例描述列表（字符串数组，初始为空）
- `harmful`: 不好用的使用案例描述列表（字符串数组，初始为空）

**示例**：

```json
{
  "helpful": [],
  "harmful": []
}
```

---

## 完整示例

````json
{
  "research_report": {
    "goal": "找到 PDF 表格提取的最佳方案",
    "task": "从复杂 PDF 中提取表格数据",
    "summary": "共记录 3 条核心知识原子，涵盖工具选型与实战 SOP",
    "atoms": [
      {
        "id": "atom-20260302-001",
        "tags": ["tool", "plan", "usercase"],
        "summary": "在 Python 3.11 环境下，从结构复杂的 PDF（包含多列、嵌套表格）中提取表格数据，并保留单元格坐标信息，最终得到可用于数据分析的结构化数据。",
        "content": "## 推荐工具\npdfplumber - 专注于 PDF 表格提取\n\n## 核心 API\n使用 extract_tables() 方法\n\n## 代码示例\n```python\nimport pdfplumber\nwith pdfplumber.open('file.pdf') as pdf:\n    tables = pdf.pages[0].extract_tables()\n```",
        "tips": "⚠️ 如果 PDF 包含隐形表格线，务必开启 explicit_horizontal_lines 参数\n⚠️ 使用 page.crop() 先裁剪区域再提取，可提升 3-5 倍速度",
        "trace": {
          "urls": ["https://github.com/jsvine/pdfplumber"],
          "agent_id": "research_agent_001",
          "timestamp": "2026-03-02T12:45:41Z"
        },
        "eval": {
          "helpful": 1,
          "harmful": 0
        },
        "execute_history": {
          "helpful": [],
          "harmful": []
        }
      },
      {
        "id": "atom-20260302-002",
        "tags": ["usercase"],
        "summary": "针对 500MB 以上的大型扫描版 PDF 进行自动化处理。",
        "content": "使用纯 Python 库（如 pdfplumber/PyMuPDF）性能极差且准确率低。",
        "tips": "建议方案：先使用 PaddleOCR 进行版面分析，再提取坐标区域。",
        "trace": {
          "urls": ["https://reddit.com/r/python/comments/..."],
          "agent_id": "research_agent_01",
          "timestamp": "2026-03-02T13:00:00Z"
        },
        "eval": {
          "helpful": 1,
          "harmful": 0
        },
        "execute_history": {
          "helpful": [],
          "harmful": []
        }
      }
    ]
  }
}
````

---

## 适用场景

- 需要从多个来源收集和整理知识
- 需要持续积累和评估知识的有效性
- 需要追溯知识来源和使用历史

---

## 使用工具

### 保存知识

````python
knowledge_save(
    task="在 Python 3.11 环境下，从复杂 PDF 中提取表格数据，并保留单元格坐标信息。",
    content="""
## 推荐工具
pdfplumber - 专注于 PDF 表格提取

## 核心 API
使用 extract_tables() 方法

## 代码示例
```python
import pdfplumber
with pdfplumber.open('file.pdf') as pdf:
    tables = pdf.pages[0].extract_tables()
```

⚠️ 必须设置 explicit_horizontal_lines=True 以识别隐形表格线
""",
    types=["tool", "plan"],
    urls=["https://github.com/jsvine/pdfplumber"],
    agent_id="research_agent_001",
    score=5
)
````

### 更新评估反馈

```python
knowledge_update(
    knowledge_id="knowledge-20260302-001",
    add_helpful_case={
        "description": "在解析 2025 年报 PDF 时，通过配置 explicit_lines 成功提取了 100+ 嵌套表格。",
        "trace_id": "trace-xxx"
    }
)
```

或添加失败案例：

```python
knowledge_update(
    knowledge_id="knowledge-20260302-001",
    add_harmful_case={
        "description": "在处理 300MB 的扫描版 PDF 时，该方案因缺乏 OCR 能力导致提取结果为空。",
        "trace_id": "trace-xxx"
    }
)
```

---

## 调研策略

### 1. 工具调研（tool）

**搜索关键词**：

- `[任务] tool python`
- `[任务] library comparison`
- `[任务] vs site:reddit.com`

**记录重点**：

- 工具名称和链接
- 核心 API
- 适用场景
- 优缺点对比
- 避坑指南

### 2. 案例调研（usercase）

**搜索关键词**：

- `[任务] example site:github.com`
- `[任务] tutorial`
- `how to [任务]`

**记录重点**：

- 用户背景
- 采用方案
- 实现步骤
- 遇到的问题
- 最终效果

### 3. 定义调研（definition）

**搜索关键词**：

- `what is [任务]`
- `[任务] definition`
- `[任务] explained`

**记录重点**：

- 概念定义
- 技术原理
- 应用场景
- 相关概念区别

### 4. 方法论调研（plan）

**搜索关键词**：

- `[任务] best practice`
- `[任务] workflow`
- `[任务] step by step`

**记录重点**：

- 完整流程
- 关键决策点
- 常见陷阱
- 评估标准

---

## 输出格式

调研完成后，输出知识列表摘要：

```
📚 调研完成报告

目标：找到 PDF 表格提取的最佳方案
任务：从复杂 PDF 中提取表格数据

共记录 5 条知识：

1. [tool] pdfplumber - PDF 表格提取工具
   评分：⭐⭐⭐⭐⭐ (5/5)
   反馈：helpful: 1, harmful: 0

2. [usercase] 财报 PDF 表格提取案例
   评分：⭐⭐⭐⭐ (4/5)
   反馈：helpful: 1, harmful: 0

3. [definition] PDF 表格提取技术原理
   评分：⭐⭐⭐⭐ (4/5)
   反馈：helpful: 1, harmful: 0

4. [plan] PDF 表格提取标准流程
   评分：⭐⭐⭐⭐⭐ (5/5)
   反馈：helpful: 1, harmful: 0

5. [tool] tabula-py - 替代方案
   评分：⭐⭐⭐ (3/5)
   反馈：helpful: 1, harmful: 0

知识文件保存在：.cache/knowledge_atoms/
```

---

## 记住

- **边搜边记**：发现有价值的信息立即保存
- **结构化**：严格按照 5 个维度记录
- **可追溯**：记录所有参考来源
- **可评估**：初始评分 + 持续反馈
