hwj123hwj research
前置准备
调研开始前，先明确三个关键信息。如果用户没有明确说明，主动询问：
- 调研对象：目标项目名称 + GitHub 地址（或其他来源）
- 调研侧重点：架构设计？功能对比？某个具体模块？还是全面分析？
- 预期产出类型（默认为 full）：
full：完整调研报告（包含所有章节）quick：快速扫描，只出核心发现和迁移建议compare：聚焦对比分析，突出差异和借鉴点
调研流程
阶段一：信息收集（深度优先）
不要先做信息收集计划再执行——直接开始，边收集边判断。
收集策略（按优先级）：
- 项目 README / 官方文档：了解定位、核心特性、架构概览
- 源码结构：
find目录树 + 关键文件阅读，理解代码组织 - 核心模块源码：根据调研侧重点，深入阅读关键实现文件
- 测试文件：了解 API 契约、边界情况、设计意图
- Issue / PR / Discussion：了解社区反馈、演进方向、设计决策背景
信息获取方式：
- 公开 GitHub 仓库：优先
ghCLI（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.mddocs/research/aider-architecture-compare.mddocs/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. 详细参考
### 关键文件索引
| 文件路径 | 职责 | 值得关注的点 |
|----------|------|-------------|
| | | |
### 参考资料
- {链接列表}
写作标准
- 基于事实：每个判断必须引用具体的源码文件、行号、或官方文档。不写"据说"、"大概"。
- 代码为王：关键设计点附带代码片段（原项目代码 + pi-go 等价实现的对比）。
- 有态度：给出明确的优先级和建议，不做"都可以"的骑墙结论。
- 承认局限：如果因为源码不可见、语言障碍等原因无法深入某部分，明确标注。
- 更新 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/