research

name	research
description	对外部项目进行深度调研分析，产出结构化报告。当用户提到'调研 XXX 项目'、'分析 XXX'、'对比 XXX 和我们的项目'、'研究一下 XXX 的架构/设计'等意图时加载此 skill。

research

前置准备

调研开始前，先明确三个关键信息。如果用户没有明确说明，主动询问：

1. 调研对象：目标项目名称 + GitHub 地址（或其他来源）
2. 调研侧重点：架构设计？功能对比？某个具体模块？还是全面分析？
3. 预期产出类型（默认为 full）：
   • full：完整调研报告（包含所有章节）
   • quick：快速扫描，只出核心发现和迁移建议
   • compare：聚焦对比分析，突出差异和借鉴点

调研流程

阶段一：信息收集（深度优先）

不要先做信息收集计划再执行——直接开始，边收集边判断。

收集策略（按优先级）：

1. 项目 README / 官方文档：了解定位、核心特性、架构概览
2. 源码结构：find 目录树 + 关键文件阅读，理解代码组织
3. 核心模块源码：根据调研侧重点，深入阅读关键实现文件
4. 测试文件：了解 API 契约、边界情况、设计意图
5. Issue / PR / Discussion：了解社区反馈、演进方向、设计决策背景

信息获取方式：

• 公开 GitHub 仓库：优先 gh CLI（gh repo view、gh api、gh browse）
• 有源码本地：直接 Read、grep、find
• Web 内容：WebSearch 发现 → WebFetch 读取详情
• 需要交互的内容：CDP 浏览器

信息饱和判断：当连续 2-3 轮阅读不再产生新的重要发现时，进入分析阶段。不要为了"完整"而无限收集。

阶段二：分析框架

按以下维度分析目标项目（根据调研侧重点取舍）：

A. 架构与设计

• 整体架构模式（分层、插件化、微内核...）
• 核心抽象和接口设计
• 依赖关系和数据流
• 可扩展性机制

B. 功能与特性

• 核心功能清单
• 特色功能 / 创新点
• 功能完整度评估

C. 工程质量

• 代码组织与模块化
• 测试策略和覆盖率
• 文档质量
• CI/CD 和发布流程

D. 与 pi-go 的对比（核心章节）

• 架构理念差异
• 功能覆盖对比（表格形式）
• pi-go 已有的等价能力
• pi-go 缺失但值得补齐的能力
• pi-go 做得更好的地方（不要妄自菲薄）

E. 迁移可行性评估

• 哪些设计可以直接迁移（接口兼容、模式相似）
• 哪些需要适配改造（架构差异、语言差异 Go vs TS）
• 哪些不适用（过度工程、场景不匹配）
• 优先级排序

阶段三：产出报告

默认情况下，调研报告写入 docs/research/ 目录，文件名格式：{项目名}-{侧重点}.md

例如：

• docs/research/claude-code-hooks-analysis.md
• docs/research/aider-architecture-compare.md
• docs/research/cursor-agent-design.md

报告模板

产出报告必须遵循以下结构（quick 类型可省略标注为可选的章节）：

# {项目名} 调研报告 — {侧重点}

> 调研日期：{YYYY-MM-DD}
> 来源：{GitHub 仓库地址 / 其他来源}
> 调研目标：{一句话说明为什么调研这个项目}

---

## 1. 概述

### 项目定位
| 项目 | 角色 | 技术栈 | 定位 |
|------|------|--------|------|
| {目标项目} | | | |
| pi-go | 我们的 Agent 框架 | Go | 通用 Agent 底座 + coding-agent 应用层 |

### 核心发现摘要
> 3-5 条最重要的发现，每条一句话。

---

## 2. 架构分析

### 整体架构
{架构图 + 分层说明}

### 核心抽象
{关键接口 / 类型 / 模式的设计分析}

### 数据流
{请求从输入到输出的完整路径}

---

## 3. 功能分析

### 功能清单
{核心功能列表，标注创新程度}

### 亮点特性
{值得深入学习的 2-3 个特性，附代码片段或设计说明}

---

## 4. 与 pi-go 对比

### 架构理念对比
| 维度 | {目标项目} | pi-go | 评价 |
|------|-----------|-------|------|
| | | | |

### 功能覆盖对比
| 功能 | {目标项目} | pi-go | 差距评估 |
|------|-----------|-------|----------|
| | | | |

### pi-go 的优势
{pi-go 做得更好的地方——必须要有，不要只写差距}

---

## 5. 迁移建议

### 优先级排序
| 优先级 | 特性/设计 | 迁移难度 | 预期收益 | 实现路径 |
|--------|----------|----------|----------|----------|
| P0 | | | | |
| P1 | | | | |
| P2 | | | | |

### 实施路线图
{按时间顺序的迁移计划，每个阶段有明确交付物}

---

## 6. 详细参考

### 关键文件索引
| 文件路径 | 职责 | 值得关注的点 |
|----------|------|-------------|
| | | |

### 参考资料
- {链接列表}

写作标准

1. 基于事实：每个判断必须引用具体的源码文件、行号、或官方文档。不写"据说"、"大概"。
2. 代码为王：关键设计点附带代码片段（原项目代码 + pi-go 等价实现的对比）。
3. 有态度：给出明确的优先级和建议，不做"都可以"的骑墙结论。
4. 承认局限：如果因为源码不可见、语言障碍等原因无法深入某部分，明确标注。
5. 更新 docs/README.md：报告完成后，在 docs/README.md 的调研报告索引中添加条目。

research vs decisions 边界

• docs/research/：外部项目的原始调研报告，强调“我看到了什么”
• docs/decisions/：基于一个或多个调研报告，再结合 pi-go 当前状态得出的采纳判断，强调“我们现在准备怎么做”

如果用户要的是：

• “调研 XXX 项目 / 分析 XXX 源码 / 对比 XXX 和我们” → 放 research/
• “基于这些调研，帮我形成一个结论/取舍/采纳路线” → 产出应放 decisions/

pi-go 项目上下文

pi-go 项目路径：/Users/weijian/Desktop/develop/test/pi/pi-go

调研开始前必须先读取 {pi-go路径}/docs/PROJECT_CONTEXT.md，获取 pi-go 的架构、核心能力、技术栈、关键文件等对比基准信息。这样调研时不需要反复读 pi-go 源码，直接以该文档作为对比参照。

如果发现该文档内容与实际代码不一致（架构变更后未更新），调研结束后顺手更新它。

报告和 docs/README.md 的更新路径也是基于 pi-go 项目路径：

• 调研报告：{pi-go路径}/docs/research/{项目名}-{侧重点}.md
• 文档索引：{pi-go路径}/docs/README.md

调研结束检查清单

报告完成前自查：

• 每个结论有源码/文档支撑
• 与 pi-go 的对比章节完整
• 迁移建议有优先级排序
• 关键文件索引已填写
• docs/README.md 调研报告索引已更新
• 文件已保存到 docs/research/