research-external

外部研究工作流

研究外部来源（文档、网络、API），了解库、最佳实践和一般主题。

**注意：**当前年份为 2025 年。研究最佳实践时，请以 2024–2025 年为参考时间范围。

调用

/research-external <focus> [options]

问题流程（无参数）

如果用户仅输入 /research-external，或提供的参数不完整，请通过以下问题流程引导他们。每个阶段都使用 AskUserQuestion。

阶段 1：研究类型

question: "What kind of information do you need?"
header: "Type"
options:
  - label: "How to use a library/package"
    description: "API docs, examples, patterns"
  - label: "Best practices for a task"
    description: "Recommended approaches, comparisons"
  - label: "General topic research"
    description: "Comprehensive multi-source search"
  - label: "Compare options/alternatives"
    description: "Which tool/library/approach is best"

对应关系：

• “如何使用库” → 以库为重点
• “最佳实践” → 以最佳实践为重点
• “一般主题” → 以一般内容为重点
• “比较选项” → 以最佳实践为重点，并采用比较的角度

阶段 2：具体主题

question: "What specifically do you want to research?"
header: "Topic"
options: []  # Free text input

优质回答示例：

• “如何将 Prisma ORM 与 TypeScript 搭配使用”
• “Python 中的错误处理最佳实践”
• “用于构建仪表盘的 React、Vue 和 Svelte 对比”

阶段 3：库的详细信息（以库为重点时）

如果用户选择了以库为重点：

question: "Which package registry?"
header: "Registry"
options:
  - label: "npm (JavaScript/TypeScript)"
    description: "Node.js packages"
  - label: "PyPI (Python)"
    description: "Python packages"
  - label: "crates.io (Rust)"
    description: "Rust crates"
  - label: "Go modules"
    description: "Go packages"

然后，如果用户尚未提供库的具体名称，请询问。

阶段 4：深度

question: "How thorough should the research be?"
header: "Depth"
options:
  - label: "Quick answer"
    description: "Just the essentials"
  - label: "Thorough research"
    description: "Multiple sources, examples, edge cases"

对应关系：

• “快速解答” → --depth shallow
• “深入研究” → --depth thorough

阶段 5：输出

question: "What should I produce?"
header: "Output"
options:
  - label: "Summary in chat"
    description: "Tell me what you found"
  - label: "Research document"
    description: "Write to thoughts/shared/research/"
  - label: "Handoff for implementation"
    description: "Prepare context for coding"

对应关系：

• “研究文档” → --output doc
• “交接” → --output handoff

执行前摘要

Based on your answers, I'll research:

**Focus:** library
**Topic:** "Prisma ORM connection pooling"
**Library:** prisma (npm)
**Depth:** thorough
**Output:** doc

Proceed? [Yes / Adjust settings]

重点模式（第一个参数）

重点	主要工具	用途
library	nia-docs	API 文档、使用模式、代码示例
best-practices	perplexity-search	推荐方法、模式、比较
general	所有 MCP 工具	综合多来源研究

选项

选项	值	说明
--topic	"string"	**必填。**要研究的主题、库或概念
--depth	shallow、thorough	搜索深度（默认值：shallow）
--output	handoff、doc	输出格式（默认值：doc）
--library	"name"	以 library 为重点时：具体的包名称
--registry	npm、py_pi、crates、go_modules	以 library 为重点时：包注册表

工作流

步骤 1：解析参数

从用户输入中提取：

FOCUS=$1           # library | best-practices | general
TOPIC="..."        # from --topic
DEPTH="shallow"    # from --depth (default: shallow)
OUTPUT="doc"       # from --output (default: doc)
LIBRARY="..."      # from --library (optional)
REGISTRY="npm"     # from --registry (default: npm)

步骤 2：根据重点执行研究

重点：library

主要工具：nia-docs - 查找 API 文档、使用模式和代码示例。

# Semantic search in package
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --registry "$REGISTRY" \
  --query "$TOPIC" \
  --limit 10)

# If thorough depth, also grep for specific patterns
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --grep "$TOPIC")

# Supplement with official docs if URL known
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py \
  --url "https://docs.example.com/api/$TOPIC" \
  --format markdown)

深入研究时的补充操作：

• 使用不同表述执行多次语义查询
• 搜索特定函数或类的名称
• 抓取官方文档页面

重点：best-practices

主要工具：perplexity-search - 查找推荐方法、模式和反模式。

# AI-synthesized research (sonar-pro)
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --research "$TOPIC best practices 2024 2025")

# If comparing alternatives
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC vs alternatives - which to choose?")

深入研究时的补充操作：

# Chain-of-thought for complex decisions
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC tradeoffs and considerations 2025")

# Deep comprehensive research
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --deep "$TOPIC comprehensive guide 2025")

# Recent developments
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --search "$TOPIC latest developments" \
  --recency month --max-results 5)

重点：general

使用所有可用的 MCP 工具，进行综合多来源研究。

步骤 2a：库文档（nia-docs）

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --search "$TOPIC")

步骤 2b：网络研究（perplexity）

(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --research "$TOPIC")

步骤 2c：具体文档（firecrawl）

# Scrape relevant documentation pages found in perplexity results
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py \
  --url "$FOUND_DOC_URL" \
  --format markdown)

深入研究时的补充操作：

• 使用扩展后的查询运行全部三个工具
• 交叉比对不同来源的发现
• 沿着初始结果中的链接继续查找，以获得更深入的背景信息

步骤 3：综合研究结果

汇总所有来源的结果：

1. 关键概念 - 核心思想和术语
2. 代码示例 - 文档中的可用示例
3. 最佳实践 - 推荐方法
4. 注意事项 - 应避免的常见错误
5. 替代方案 - 考虑过的其他选项
6. 来源 - 所有引用的 URL

步骤 4：撰写输出

输出：doc（默认值）

写入：thoughts/shared/research/YYYY-MM-DD-{topic-slug}.md

---
date: {ISO timestamp}
type: external-research
topic: "{topic}"
focus: {focus}
sources: [nia, perplexity, firecrawl]
status: complete
---

# Research: {Topic}

## Summary
{2-3 sentence summary of findings}

## Key Findings

### Library Documentation
{From nia-docs - API references, usage patterns}

### Best Practices (2024-2025)
{From perplexity - recommended approaches}

### Code Examples
```{language}
// Working examples found

建议

• {建议 1}
• {建议 2}

应避免的注意事项

• {注意事项 1}
• {注意事项 2}

考虑过的替代方案

选项	优点	缺点
{选项 1}	...	...

来源

• {来源 1}
• {来源 2}

#### Output: `handoff`

Write to: `thoughts/shared/handoffs/{session}/research-{topic-slug}.yaml`

```yaml
---
type: research-handoff
ts: {ISO timestamp}
topic: "{topic}"
focus: {focus}
status: complete
---

goal: Research {topic} for implementation planning
sources_used: [nia, perplexity, firecrawl]

findings:
  key_concepts:
    - {concept1}
    - {concept2}

  code_examples:
    - pattern: "{pattern name}"
      code: |
        // example code

  best_practices:
    - {practice1}
    - {practice2}

  pitfalls:
    - {pitfall1}

recommendations:
  - {rec1}
  - {rec2}

sources:
  - title: "{Source 1}"
    url: "{url1}"
    type: {documentation|article|reference}

for_plan_agent: |
  Based on research, the recommended approach is:
  1. {Step 1}
  2. {Step 2}
  Key libraries: {lib1}, {lib2}
  Avoid: {pitfall1}

步骤 5：返回摘要

Research Complete

Topic: {topic}
Focus: {focus}
Output: {path to file}

Key findings:
- {Finding 1}
- {Finding 2}
- {Finding 3}

Sources: {N} sources cited

{If handoff output:}
Ready for plan-agent to continue.

错误处理

如果 MCP 工具失败（缺少 API 密钥、受到速率限制等）：

1. 在输出中记录失败：

   tool_status:
     nia: success
     perplexity: failed (rate limited)
     firecrawl: skipped
   

2. 继续使用其他来源——部分结果也有价值

3. 设置适当的状态：

   • complete - 所有请求的工具均成功
   • partial - 部分工具失败，但调查结果仍有用
   • failed - 未获得任何有用结果

4. 在调查结果中注明缺失内容：

   ## Gaps
   - Perplexity unavailable - best practices section limited to nia results
   

示例

库研究（浅层）

/research-external library --topic "dependency injection" --library fastapi --registry py_pi

最佳实践（全面）

/research-external best-practices --topic "error handling in Python async" --depth thorough

用于交接的一般研究

/research-external general --topic "OAuth2 PKCE flow implementation" --depth thorough --output handoff

快速查询库

/research-external library --topic "useEffect cleanup" --library react

与其他技能集成

研究之后	使用技能	用途
--output handoff	plan-agent	创建实施计划
找到代码示例	implement_task	直接实施
架构决策	create_plan	详细规划
库比较	呈现给用户	辅助决策

必需环境

• NIA_API_KEY 或 mcp_config.json 中的 nia 服务
• 环境变量或 ~/.claude/.env 中的 PERPLEXITY_API_KEY
• FIRECRAWL_API_KEY 和 mcp_config.json 中的 firecrawl 服务

注意事项

• 不用于探索代码库——请使用 research-codebase 或 scout
• 始终引用来源——为所有调查结果附上 URL
• 2024-2025 年时间范围——聚焦当前最佳实践
• 优雅降级——部分结果胜过没有结果