research-first

name	research-first
description	调研工作流引擎。自动判断调研级别（L1/L2/L3）和场景（W1-W6），按工作流模板执行。L1 快查在主线程完成，L2/L3 用子代理执行。当任务涉及技术选型、方案对比、可行性评估、寻找现有工具或最佳实践时自动触发。

调研工作流引擎

触发后自动声明 [MODE: RESEARCH]。

---

Step 1: 去重检查（L2/L3 必做）

L1 快查跳过此步。L2/L3 调研启动前：

1. 读项目 docs/research/INDEX.md（如存在）
2. 读全局 ~/.Codex/memory-bank/research/INDEX.md
3. Grep 关键词匹配已有调研
4. 找到相关 → 提示用户：复用（直接引用）/ 刷新（以旧报告为基础更新）/ 忽略（全新调研）

---

Step 2: 分级判断

根据 contexts/research.md 的分级规则判断 L1/L2/L3。

---

Step 3: 场景识别

根据 contexts/research.md 的场景→工作流表选择 W1-W6。 组合调研时识别多个工作流，每个分配给一个子代理。

---

Step 4: 需求澄清（按需）

如存在不确定性（功能边界、技术路线、偏好），用 AskUserQuestion 澄清（最多 2-3 个问题）。 L1 和需求已清晰时跳过。

---

Step 5: 执行声明

执行前向用户展示当前配置：

[MODE: RESEARCH] 调研启动
- 级别: L{1|2|3}
- 工作流: W{N} {工作流名称}
- 验证深度: {🔴|🟡|🟢}
- 时效性: {🔥|📅|📚}
- 工具: {将使用的主要工具列表}
- 执行方式: {主线程快查 | 单个子代理 | N 个并行子代理}

L1 快查可简化为一行：[RESEARCH L1] 主线程快查，使用 {工具}

---

Step 6: 执行

L1: 主线程快查

Read/Grep/Glob → 直接回答。无报告、无 PRD。

L2: 单个子代理

读取工作流模板文件后，启动子代理：

# 先读工作流模板
workflow = Read("~/.Codex/skills/research-first/workflows/{W1|W2|W3|W4|W5|W6}.md")

Agent(
  subagent_type: "Researcher",
  description: "调研 {任务简述}",
  prompt: """
    按以下工作流模板执行调研：

    {workflow 内容}

    调研问题：{详细描述}
    验证深度：{🔴/🟡/🟢}
    时效性：{🔥/📅/📚}

    工具优先级：
    - GitHub: gh CLI
    - 文档: Context7 → GitMCP → WebFetch
    - 搜索: Exa > Tavily > WebSearch
    - 中文: Baidu MCP

    输出要求：
    1. 筛选后的结果摘要（保留重要细节，去掉噪音和重复）
    2. 写报告到 {存储路径}/{主题}-{日期}.md
    3. 更新对应的 INDEX.md（追加一行）
    4. 返回：摘要 + 文件路径 + 不确定项
  """,
  run_in_background: true
)

L3: 多个并行子代理

识别子领域/工作流组合后，同一个 message 中启动多个 Agent：

Agent("Researcher", "按 W1 方案发现: ...", run_in_background: true)
Agent("Researcher", "按 W3 技术评估: ...", run_in_background: true)
Agent("Researcher", "按 W6 文献研究: ...", run_in_background: true)

中英双语调研时必须翻译搜索词。

全部完成 → 读各子代理摘要 → 汇聚结论。

---

Step 7: PERSIST

子代理已写报告和更新 INDEX.md。主线程确认：

• 文件路径正确
• INDEX.md 已更新
• 存储层级正确（项目级 vs 全局级）

---

Step 8: 输出 + 衔接

L1 输出

## 调研摘要
### 发现
- [关键发现 1-3]
### 建议
[简要建议]

L2/L3 输出

## 调研摘要

**报告位置**: `{文件路径}`

### 关键发现（≤10 点）
1. [发现 1]
2. [发现 2]

### 复用分析
| 方案/项目 | 策略 | 理由 |
|-----------|------|------|
| {名称} | 🟢 直接用 / 🟡 借鉴 / 🔵 参考 / ⚪ 自己写 | {简述} |

### 推荐方案
[简述]

### PRD 框架草案
**推荐方案**: [从调研推荐方案提取]
**核心功能**: [从关键发现提取]
**技术依赖**: [从复用分析提取]
**风险项**: [从对抗性检验提取]
**待澄清**: [从不确定项提取]

调研完成后给出下一步建议：编码 → 研发模式 / 决策 → 选项+推荐。

---

可选：开源项目深度研究

在 W1（方案发现）或 W3（技术评估）执行过程中，发现借鉴意义高的开源项目时可触发：

1. 克隆到 ~/projects/repos/{项目名}/
2. 更新 ~/projects/repos/index.md
3. 启动子代理做代码级研究，报告保存到项目 docs/research/{项目名}-analysis.md

---

调研阶段的行为约束

调研阶段专注于信息收集和分析，不进入编码实现：

• 调研阶段不写实现代码——调研完成后切换到研发模式再编码
• 不做最终技术决策——只提供建议和推荐，决策由用户做

---

GitHub 搜索规范（原 github-search skill，已合并）

搜索命令

gh search repos "<关键词>" --stars=">100" --sort=stars --limit=10
gh repo view <owner/repo> --json description,stargazersCount,updatedAt

筛选标准

指标	阈值	原因
Stars	> 100	基本质量保证
最近更新	< 6个月	活跃维护
License	MIT/Apache/BSD	商用友好
Issues 关闭率	> 50%	维护者响应
有 README	必须	基本文档
依赖数量	越少越好	轻量优先
TypeScript	优先	类型安全
测试覆盖	有则加分	代码质量

输出格式

对 Top 3 项目输出：项目名 + Stars + 链接、一句话描述、适用场景、潜在问题。

采用决策

方式	条件	行动
🟢 直接使用	功能完全匹配、维护良好、依赖可接受	安装并集成
🟡 借鉴实现	功能部分匹配、或依赖过重	阅读核心源码，理解关键逻辑后自己实现

在 W1（方案发现）的 SCAN/FILTER 步骤和 W3（技术评估）的 ORIENT 步骤中自动使用。