research-external

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

External Research Workflow

外部研究工作流

Research external sources (documentation, web, APIs) for libraries, best practices, and general topics.

Note: The current year is 2025. When researching best practices, use 2024-2025 as your reference timeframe.

针对库、最佳实践及通用主题，调研外部资源（文档、网页、API）。

注意： 当前年份为2025年。调研最佳实践时，请以2024-2025年作为参考时间段。

Invocation

调用方式

/research-external <focus> [options]

/research-external <研究方向> [选项]

Question Flow (No Arguments)

提问流程（无参数时）

If the user types just

/research-external

with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase.

如果用户仅输入

/research-external

而未带参数或参数不全，请引导用户完成以下提问流程。每个阶段使用AskUserQuestion进行交互。

Phase 1: Research Type

阶段1：研究类型

yaml

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"

Mapping:

"How to use library" → library focus
"Best practices" → best-practices focus
"General topic" → general focus
"Compare options" → best-practices with comparison framing

yaml

question: "你需要哪类信息？"
header: "类型"
options:
  - label: "如何使用某个库/包"
    description: "API文档、示例代码、使用模式"
  - label: "某任务的最佳实践"
    description: "推荐方案、对比分析"
  - label: "通用主题调研"
    description: "多来源综合搜索"
  - label: "对比不同选项/替代方案"
    description: "哪种工具/库/方案更优"

映射关系：

"如何使用库" → 库研究方向
"最佳实践" → 最佳实践研究方向
"通用主题" → 通用研究方向
"对比选项" → 带对比框架的最佳实践研究

Phase 2: Specific Topic

阶段2：具体主题

yaml

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

Examples of good answers:

"How to use Prisma ORM with TypeScript"
"Best practices for error handling in Python"
"React vs Vue vs Svelte for dashboards"

yaml

question: "你具体想调研什么内容？"
header: "主题"
options: []  # 自由文本输入

优秀回答示例：

"如何结合TypeScript使用Prisma ORM"
"Python错误处理的最佳实践"
"React、Vue、Svelte在仪表盘开发中的对比"

Phase 3: Library Details (if library focus)

阶段3：库详情（若为库研究方向）

If user selected library focus:

yaml

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"

Then ask for specific library name if not already provided.

如果用户选择了库研究方向：

yaml

question: "使用哪个包注册表？"
header: "注册表"
options:
  - label: "npm (JavaScript/TypeScript)"
    description: "Node.js包"
  - label: "PyPI (Python)"
    description: "Python包"
  - label: "crates.io (Rust)"
    description: "Rust包"
  - label: "Go modules"
    description: "Go包"

若用户未提供具体库名称，需进一步询问。

Phase 4: Depth

阶段4：调研深度

yaml

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"

Mapping:

"Quick answer" → --depth shallow
"Thorough" → --depth thorough

yaml

question: "调研需要达到什么细致程度？"
header: "深度"
options:
  - label: "快速回答"
    description: "仅获取核心要点"
  - label: "全面调研"
    description: "多来源验证、示例代码、边缘场景覆盖"

映射关系：

"快速回答" → --depth shallow
"全面调研" → --depth thorough

Phase 5: Output

阶段5：输出形式

yaml

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"

Mapping:

"Research document" → --output doc
"Handoff" → --output handoff

yaml

question: "需要生成什么形式的输出？"
header: "输出"
options:
  - label: "聊天内摘要"
    description: "直接告知调研结果"
  - label: "研究文档"
    description: "写入thoughts/shared/research/目录"
  - label: "开发交接文档"
    description: "为编码工作准备上下文信息"

映射关系：

"研究文档" → --output doc
"开发交接文档" → --output handoff

Summary Before Execution

执行前确认摘要

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
**主题：** "Prisma ORM连接池"
**库：** prisma (npm)
**深度：** thorough
**输出：** doc

是否继续？[是 / 调整设置]

Focus Modes (First Argument)

研究方向（第一个参数）

Focus	Primary Tool	Purpose
`library`	nia-docs	API docs, usage patterns, code examples
`best-practices`	perplexity-search	Recommended approaches, patterns, comparisons
`general`	All MCP tools	Comprehensive multi-source research

研究方向	核心工具	用途
`library`	nia-docs	API文档、使用模式、代码示例
`best-practices`	perplexity-search	推荐方案、模式分析、对比研究
`general`	所有MCP工具	多来源综合调研

Options

选项参数

Option	Values	Description
`--topic`	`"string"`	Required. The topic/library/concept to research
`--depth`	`shallow` , `thorough`	Search depth (default: shallow)
`--output`	`handoff` , `doc`	Output format (default: doc)
`--library`	`"name"`	For `library` focus: specific package name
`--registry`	`npm` , `py_pi` , `crates` , `go_modules`	For `library` focus: package registry

选项	取值	描述
`--topic`	`"字符串"`	必填项。要调研的主题/库/概念
`--depth`	`shallow` , `thorough`	调研深度（默认：shallow）
`--output`	`handoff` , `doc`	输出格式（默认：doc）
`--library`	`"名称"`	当研究方向为 `library` 时：指定具体包名称
`--registry`	`npm` , `py_pi` , `crates` , `go_modules`	当研究方向为 `library` 时：指定包注册表

Workflow

工作流步骤

Step 1: Parse Arguments

步骤1：解析参数

Extract from user input:

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)

从用户输入中提取参数：

FOCUS=$1           # library | best-practices | general
TOPIC="..."        # 来自--topic参数
DEPTH="shallow"    # 来自--depth参数（默认：shallow）
OUTPUT="doc"       # 来自--output参数（默认：doc）
LIBRARY="..."      # 来自--library参数（可选）
REGISTRY="npm"     # 来自--registry参数（默认：npm）

Step 2: Execute Research by Focus

步骤2：按研究方向执行调研

Focus:

library

研究方向：

library

Primary tool: nia-docs - Find API documentation, usage patterns, code examples.

bash

undefined

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

bash

undefined

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

若已知官方文档URL，补充抓取

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py
--url "https://docs.example.com/api/$TOPIC"
--format markdown)


**Thorough depth additions:**
- Multiple semantic queries with variations
- Grep for specific function/class names
- Scrape official documentation pages

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py
--url "https://docs.example.com/api/$TOPIC"
--format markdown)


**全面调研新增内容：**
- 多组语义查询，覆盖不同表述
- 搜索特定函数/类名称
- 抓取官方文档页面

Focus:

best-practices

研究方向：

best-practices

Primary tool: perplexity-search - Find recommended approaches, patterns, anti-patterns.

bash

undefined

核心工具：perplexity-search - 查找推荐方案、模式、对比分析。

bash

undefined

AI-synthesized research (sonar-pro)

AI合成调研结果（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?")


**Thorough depth additions:**
```bash

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


**全面调研新增内容：**
```bash

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

Scrape relevant documentation pages found in perplexity results

抓取perplexity结果中相关的文档页面

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py
--url "$FOUND_DOC_URL"
--format markdown)


**Thorough depth additions:**
- Run all three tools with expanded queries
- Cross-reference findings between sources
- Follow links from initial results for deeper context

(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/firecrawl_scrape.py
--url "$FOUND_DOC_URL"
--format markdown)


**全面调研新增内容：**
- 扩展查询词，运行全部三个工具
- 交叉验证不同来源的调研结果
- 追踪初始结果中的链接，获取更深入的上下文

Step 3: Synthesize Findings

步骤3：整合调研结果

Combine results from all sources:

Key Concepts - Core ideas and terminology
Code Examples - Working examples from documentation
Best Practices - Recommended approaches
Pitfalls - Common mistakes to avoid
Alternatives - Other options considered
Sources - URLs for all citations

合并所有来源的结果：

核心概念 - 核心思想与术语
代码示例 - 来自文档的可运行示例
最佳实践 - 推荐的实现方案
常见陷阱 - 需要避免的典型错误
替代方案 - 其他可选择的方案
来源 - 所有引用的URL

Step 4: Write Output

步骤4：生成输出

Output:

doc

(default)

输出：

doc

（默认）

Write to:

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

markdown

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

写入路径：

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

markdown

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

Research: {Topic}

调研：{Topic}

Summary

摘要

{2-3 sentence summary of findings}

{2-3句话总结调研结果}

Key Findings

核心发现

Library Documentation

库文档内容

{From nia-docs - API references, usage patterns}

{来自nia-docs的API参考、使用模式}

Best Practices (2024-2025)

2024-2025最佳实践

{From perplexity - recommended approaches}

{来自perplexity的推荐方案}

Code Examples

代码示例

// Working examples found

// 找到的可运行示例代码

Recommendations

建议

{Recommendation 1}
{Recommendation 2}

{建议1}
{建议2}

Pitfalls to Avoid

需避免的陷阱

{Pitfall 1}
{Pitfall 2}

{陷阱1}
{陷阱2}

Alternatives Considered

备选方案对比

Option	Pros	Cons
{Option 1}	...	...

方案	优势	劣势
{方案1}	...	...

Sources

参考来源

{Source 1}
{Source 2}

undefined

{来源1}
{来源2}

undefined

Output:

handoff

输出：

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}

写入路径：

thoughts/shared/handoffs/{session}/research-{topic-slug}.yaml

yaml

---
type: research-handoff
ts: {ISO时间戳}
topic: "{topic}"
focus: {focus}
status: complete
---

goal: 调研{topic}以支持开发规划
sources_used: [nia, perplexity, firecrawl]

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

  code_examples:
    - pattern: "{模式名称}"
      code: |
        // 示例代码

  best_practices:
    - {practice1}
    - {practice2}

  pitfalls:
    - {pitfall1}

recommendations:
  - {rec1}
  - {rec2}

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

for_plan_agent: |
  根据调研结果，推荐实现方案如下：
  1. {步骤1}
  2. {步骤2}
  核心库：{lib1}, {lib2}
  需避免：{pitfall1}

Step 5: Return Summary

步骤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.

调研完成

主题：{topic}
研究方向：{focus}
输出路径：{文件路径}

核心发现：
- {发现1}
- {发现2}
- {发现3}

参考来源：共引用{N}个来源

{若为handoff输出：}
已准备好，可交由plan-agent继续处理。

Error Handling

错误处理

If an MCP tool fails (API key missing, rate limited, etc.):

Log the failure in output:

yaml

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

Continue with other sources - partial results are valuable
Set status appropriately:
- ```
complete
```
  - All requested tools succeeded
- ```
partial
```
  - Some tools failed, findings still useful
- ```
failed
```
  - No useful results obtained

Note gaps in findings:

markdown

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

若MCP工具调用失败（如缺少API密钥、触发速率限制等）：

在输出中记录失败状态：

yaml

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

继续使用其他可用来源 - 部分结果仍具备参考价值
设置对应的状态：
- ```
complete
```
  - 所有请求的工具均调用成功
- ```
partial
```
  - 部分工具调用失败，但调研结果仍有用
- ```
failed
```
  - 未获取到有效结果

在结果中注明信息缺口：

markdown

## 信息缺口
- Perplexity不可用，最佳实践章节仅基于nia的结果

Examples

使用示例

Library Research (Shallow)

库调研（快速）

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

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

Best Practices (Thorough)

最佳实践调研（全面）

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

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

General Research for Handoff

通用调研（用于开发交接）

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

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

Quick Library Lookup

快速库查询

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

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

Integration with Other Skills

与其他技能的集成

After Research	Use Skill	For
`--output handoff`	`plan-agent`	Create implementation plan
Code examples found	`implement_task`	Direct implementation
Architecture decision	`create_plan`	Detailed planning
Library comparison	Present to user	Decision making

调研完成后	使用技能	用途
`--output handoff`	`plan-agent`	创建开发实现计划
找到代码示例	`implement_task`	直接进行开发实现
需要架构决策	`create_plan`	制定详细规划
完成库对比	呈现给用户	辅助决策

Required Environment

所需环境

```
NIA_API_KEY
```
or
```
nia
```
server in mcp_config.json
```
PERPLEXITY_API_KEY
```
in environment or
```
~/.claude/.env
```
```
FIRECRAWL_API_KEY
```
and
```
firecrawl
```
server in mcp_config.json

```
NIA_API_KEY
```
或在mcp_config.json中配置
```
nia
```
服务
环境变量或
```
~/.claude/.env
```
中配置
```
PERPLEXITY_API_KEY
```
```
FIRECRAWL_API_KEY
```
及在mcp_config.json中配置
```
firecrawl
```
服务

Notes

注意事项

NOT for codebase exploration - Use
```
research-codebase
```
or
```
scout
```
for that
Always cite sources - Include URLs for all findings
2024-2025 timeframe - Focus on current best practices
Graceful degradation - Partial results better than no results

不适用于代码库探索 - 此类需求请使用
```
research-codebase
```
或
```
scout
```
始终标注来源 - 需包含所有调研结果的URL
聚焦2024-2025年 - 重点关注当前的最佳实践
优雅降级 - 部分结果优于无结果

research-external

Original

Translation

External Research Workflow

外部研究工作流

Invocation

调用方式

Question Flow (No Arguments)

提问流程（无参数时）

Phase 1: Research Type

阶段1：研究类型

Phase 2: Specific Topic

阶段2：具体主题

Phase 3: Library Details (if library focus)

阶段3：库详情（若为库研究方向）

Phase 4: Depth

阶段4：调研深度

Phase 5: Output

阶段5：输出形式

Summary Before Execution

执行前确认摘要

Focus Modes (First Argument)

研究方向（第一个参数）

Options

选项参数

Workflow

工作流步骤

Step 1: Parse Arguments

步骤1：解析参数

Step 2: Execute Research by Focus

步骤2：按研究方向执行调研

Focus: library

研究方向：library

Semantic search in package

包内语义搜索

If thorough depth, also grep for specific patterns

若为全面调研，额外搜索特定模式

Supplement with official docs if URL known

若已知官方文档URL，补充抓取

Focus: best-practices

研究方向：best-practices

AI-synthesized research (sonar-pro)

AI合成调研结果（sonar-pro）

If comparing alternatives

若为对比替代方案

Chain-of-thought for complex decisions

复杂决策的链式思考分析

Deep comprehensive research

深度综合调研

Recent developments

最新发展动态

Focus: general

研究方向：general

Scrape relevant documentation pages found in perplexity results

抓取perplexity结果中相关的文档页面

Step 3: Synthesize Findings

步骤3：整合调研结果

Step 4: Write Output

步骤4：生成输出

Output: doc (default)

输出：doc（默认）

Research: {Topic}

调研：{Topic}

Summary

摘要

Key Findings

核心发现

Library Documentation

库文档内容

Best Practices (2024-2025)

2024-2025最佳实践

Code Examples

代码示例

Recommendations

建议

Pitfalls to Avoid

需避免的陷阱

Alternatives Considered

备选方案对比

Sources

Focus:
`library`

研究方向：
`library`

Focus:
`best-practices`

研究方向：
`best-practices`

Focus:
`general`

研究方向：
`general`

Output:
`doc`
(default)

输出：
`doc`
（默认）

Output:
`handoff`

输出：
`handoff`