--- 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: 结构化记录** 每发现一条有价值的信息，立即保存为结构化知识： ```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 个维度记录 - **可追溯**：记录所有参考来源 - **可评估**：初始评分 + 持续反馈