Research 技能

描述

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

触发条件

当用户希望：

• 研究一个主题、想法或问题
• 在决定开发前先探索某件事
• 调研选项、模式或方法
• 创建一份“研究文档”或“调查报告”
• 对复杂主题执行深度异步研究

研究目录结构

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

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

两种研究模式

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

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

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

适用于需要全面调查的复杂主题。通过 parallel-research CLI 使用 Parallel 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        # 完整的 Parallel 输出

prompt.md 应包含：

# <主题标题>

> <原始研究问题>

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

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

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）