Research 技能

描述

对某个主题进行开放式研究，生成一份持续更新的 Markdown 文档。对话内容是临时的，真正重要的是最终形成的文档。

触发条件

当用户希望：

• 研究一个主题、想法或问题
• 在决定构建之前先探索相关内容
• 调查选项、模式或方法
• 创建“研究文档”或“调查报告”
• 对复杂主题执行深度异步研究

研究目录结构

每个研究主题都有独立的文件夹：

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # 原始研究问题/提示
├── research.md        # 主要发现（并行输出或交互式笔记）
├── research.pdf       # PDF 导出文件（如生成）
└── ...                # 其他相关文件（数据、图片等）

两种研究模式

1. 交互式研究（默认模式）

适用于在对话中共同探索的主题。你实时搜索、整合信息，并更新文档。

2. 深度研究（异步模式）

适用于需要全面调查的复杂主题。通过 parallel-research CLI 使用并行 AI API。耗时数分钟至数小时，返回详细的 Markdown 报告。

适合使用深度研究的情况：

• 市场分析、竞争格局调研
• 需要大量资料收集的技术深入探究
• 多维度问题，适合并行探索
• 用户明确要求“深度研究”或希望获得全面覆盖

交互式研究工作流程

1. 初始化研究

1. 创建研究文件夹

在 ~/.openclaw/workspace/research/<topic-slug>/ 下建立新目录。

1. 创建 prompt.md，写入原始问题：

   # <主题标题>

   > <核心问题或好奇心>

   **开始时间：** <日期>

1. 创建 research.md，设定初始结构：

   # <主题标题>

   **状态：** 正在研究
   **开始时间：** <日期>
   **最后更新：** <日期>

   ---

   ## 待解决的问题
   - <初始待探索的问题>

   ## 发现
   <!-- 随研究过程逐步填充 -->

   ## 可选方案 / 方法
   <!-- 若在比较不同解决方案 -->

   ## 资源
   <!-- 链接、参考文献、来源 -->

   ## 下一步
   <!-- 接下来可探索的方向，或“转入项目”建议 -->

1. 向用户确认 —— 展示文件夹已创建，并询问下一步想探索什么。

2. 研究循环

每次交流按以下步骤进行：

1. 开展研究 —— 进行网络搜索、获取文档、分析代码
2. 更新文档 —— 添加发现内容，标记已解答的问题，补充来源
3. 展示进展 —— 说明新增内容（无需重复全部内容）
4. 引导下一步 —— 以问题或建议结尾

关键行为：

• 优先更新现有章节，而非新建
• 发现内容使用项目符号；总结性描述用段落
• 标注不确定性（如“看起来像”、“根据 X 表明”、“未经验证”）
• 尽可能提供来源链接

3. 整合检查点

每 5–10 次交流后，主动提供：

• 撰写“当前理解”摘要
• 清理重复内容
• 如结构混乱则重新组织
• 检查潜在盲点

4. 完成阶段

研究完成后，在 research.md 中更新状态：

• “状态：已完成” —— 已结束，作为参考资料保留
• “状态：进行中” —— 活动文档，未来可继续更新

若研究结果将用于实际项目开发：

• 转移至 ~/specs/<project-name>.md 作为项目规格文档
• 或基于研究成果直接创建项目
• 更新状态为 “状态：已迁移 → ~/specs/...”

大多数研究仅作为研究用途，无需转化为规格文档。只有当你确实要基于它构建项目时才进行迁移。

深度研究工作流程

1. 启动深度研究

parallel-research create "你的研究问题" --processor ultra --wait

处理器选项：

• lite, base, core, pro, ultra（默认）, ultra2x, ultra4x, ultra8x
• 加 -fast 后缀可提升速度但降低深度：如 ultra-fast, pro-fast 等

选项说明：

• -w, --wait —— 等待完成并显示结果
• -p, --processor —— 选择处理器级别
• -j, --json —— 输出原始 JSON 格式

2. 设置自动检查（可选）

深度研究任务耗时从几分钟到数小时不等。建议设置自动轮询机制，避免手动频繁查询。

选项：

• OpenClaw 用户：参阅 OPENCLAW.md 了解基于 cron 的自动检查调度方式
• 其他环境：使用任意调度工具（cron、systemd timer、CI 任务）定期运行 parallel-research status <run_id> 和 parallel-research result <run_id>，直到任务完成
• 简单做法：直接使用 parallel-research create "..." --wait 阻塞等待结果（适用于较短任务）

3. 手动检查（如需）

parallel-research status <run_id>
parallel-research result <run_id>

4. 保存至研究文件夹

创建研究目录并保存结果：

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # 原始问题 + 运行元数据
├── research.md        # 完整的并行输出结果

prompt.md 应包含：

# <主题标题>

> <原始研究问题>

**运行 ID：** <run_id>
**处理器：** <processor>
**开始时间：** <date>
**完成时间：** <date>

research.md 包含完整的并行输出结果，以及后续补充说明。

PDF 导出

所有 PDF 文件均存放在研究文件夹中 —— 不得保存至 tmp/ 目录。无论使用 export-pdf、浏览器“打印为 PDF”功能，或其他方式，输出路径必须为 research/<topic-slug>/。

使用 export-pdf 脚本将研究文档转换为 PDF：

export-pdf ~/.openclaw/workspace/research/<topic-slug>/research.md
# 生成：~/.openclaw/workspace/research/<topic-slug>/research.pdf

对于浏览器生成的 PDF（例如网页另存为 PDF）：

浏览器 PDF → 保存至 research/<topic-slug>/<描述性名称>.pdf

注意： 表格会以堆叠行形式呈现（受 PyMuPDF 限制），在研究文档中可接受。

命令

• "new research: <主题>" - 启动交互式研究文档
• "deep research: <主题>" - 启动异步深度研究
• "show doc" / "show research" - 显示当前研究文件
• "summarize" - 汇总检查点
• "graduate" - 将研究推进到下一阶段
• "archive" - 标记为已完成的参考资料
• "export pdf" - 导出为 PDF
• "check research" - 检查待处理的深度研究任务状态

文档原则

• 原子化发现 - 每个要点仅包含一个洞察
• 链接一切 - 关联来源、文档、代码仓库
• 记录上下文 - 说明为何关注此主题
• 标注可信度 - 不确定时使用限定词
• 标注重要发现的时间 - 尤其适用于快速变化的主题

设置

请参阅 SETUP.md 了解首次安装以下内容：

• parallel-research CLI 工具
• PDF 导出工具（pandoc、PyMuPDF）