# Research

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

- Skill: `hwj123hwj/research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hwj123hwj/research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hwj123hwj/research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: hwj123hwj (https://skillmd.com/u/hwj123hwj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hwj123hwj/research

---


# 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/Codex-hooks-analysis.md`
- `docs/research/aider-architecture-compare.md`
- `docs/research/cursor-agent-design.md`

## 报告模板

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

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

> 调研日期：{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/