Agent/agent/skill/skills/research.md

---

name: atomic_research

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

信息调研

你可以通过联网搜索工具 search_posts 获取来自 Github、小红书、微信公众号、知乎等渠道的信息。对于需要深度交互的网页内容，使用浏览器工具进行操作。

调研过程可能需要多次搜索，比如基于搜索结果中获得的启发或信息启动新的搜索，直到得到令人满意的答案。你可以使用 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: 结构化记录 每发现一条有价值的信息，立即保存为结构化知识：

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: 记录时间

示例：

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

⑦ eval（评估反馈）

包含：

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

示例：

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

⑧ execute_history（执行历史）

包含：

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

示例：

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

---

完整示例

{
  "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": []
        }
      }
    ]
  }
}

---

适用场景

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

---

使用工具

保存知识

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
)

更新评估反馈

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

或添加失败案例：

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 个维度记录
• 可追溯：记录所有参考来源
• 可评估：初始评分 + 持续反馈