⚡

外部研究Skill research-external

这是一个用于进行外部研究的工作流程技能，专注于文档、网络和API的研究，帮助用户获取库使用指南、最佳实践和一般主题信息。关键词：外部研究、文档搜索、API研究、最佳实践、量化交易、股票分析。

AI智能体 0 次安装 0 次浏览 更新于 3/14/2026

name: research-external description: 用于文档、网络、API的外部研究工作流程 - 非代码库探索 model: sonnet allowed-tools: [Bash, Read, Write, Task]

外部研究工作流程

研究外部源（文档、网络、API）以获取库、最佳实践和一般主题的信息。

注意： 当前年份是2025年。在研究最佳实践时，使用2024-2025作为参考时间框架。

调用

/research-external <focus> [options]

问题流程（无参数）

如果用户只输入/research-external而没有或部分参数，则通过以下问题流程引导他们。使用AskUserQuestion为每个阶段。

阶段1：研究类型

question: "您需要哪种类型的信息？"
header: "类型"
options:
  - label: "如何使用库/包"
    description: "API文档、示例、模式"
  - label: "任务的最佳实践"
    description: "推荐方法、比较"
  - label: "一般主题研究"
    description: "全面的多源搜索"
  - label: "比较选项/替代方案"
    description: "哪个工具/库/方法最好"

映射：

  • “如何使用库” → 库焦点
  • “最佳实践” → 最佳实践焦点
  • “一般主题” → 一般焦点
  • “比较选项” → 带有比较框架的最佳实践

阶段2：具体主题

question: "您具体想研究什么？"
header: "主题"
options: []  # 自由文本输入

好答案的示例：

  • “如何在TypeScript中使用Prisma ORM”
  • “Python错误处理的最佳实践”
  • “用于仪表板的React vs Vue vs Svelte”

阶段3：库详细信息（如果库焦点）

如果用户选择了库焦点：

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

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

阶段4：深度

question: "研究的彻底程度如何？"
header: "深度"
options:
  - label: "快速答案"
    description: "仅基本内容"
  - label: "彻底研究"
    description: "多个源、示例、边缘案例"

映射：

  • “快速答案” → --depth shallow
  • “彻底” → --depth thorough

阶段5：输出

question: "我应该产生什么输出？"
header: "输出"
options:
  - label: "聊天中的摘要"
    description: "告诉我你找到了什么"
  - label: "研究文档"
    description: "写入thoughts/shared/research/"
  - label: "实施交接"
    description: "为编码准备上下文"

映射：

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

执行前摘要

基于您的答案，我将研究：

**焦点：** 库
**主题：** "Prisma ORM连接池"
**库：** prisma (npm)
**深度：** 彻底
**输出：** doc

继续？[是 / 调整设置]

焦点模式（第一个参数）

焦点 主要工具 目的
library nia-docs API文档、使用模式、代码示例
best-practices perplexity-search 推荐方法、模式、比较
general 所有MCP工具 全面的多源研究

选项

选项 值 描述
--topic "字符串" 必需。 要研究的主题/库/概念
--depth shallow, thorough 搜索深度（默认：shallow）
--output handoff, doc 输出格式（默认：doc）
--library "名称" 对于library焦点：特定的包名称
--registry npm, py_pi, crates, go_modules 对于library焦点：包注册表

工作流程

步骤1：解析参数

从用户输入中提取：

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

步骤2：按焦点执行研究

焦点：library

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

# 在包中进行语义搜索
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --registry "$REGISTRY" \
  --query "$TOPIC" \
  --limit 10)

# 如果是彻底深度，也grep特定模式
(cd $CLAUDE_OPC_DIR && uv run python -m runtime.harness scripts/mcp/nia_docs.py \
  --package "$LIBRARY" \
  --grep "$TOPIC")

# 如果已知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)

彻底深度添加：

  • 多个语义查询，带变体
  • Grep特定的函数/类名称
  • 抓取官方文档页面

焦点：best-practices

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

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

# 如果比较替代方案
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC vs alternatives - which to choose?")

彻底深度添加：

# 复杂决策的链式思考
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --reason "$TOPIC tradeoffs and considerations 2025")

# 深度全面研究
(cd $CLAUDE_OPC_DIR && uv run python scripts/mcp/perplexity_search.py \
  --deep "$TOPIC comprehensive guide 2025")

# 近期发展
(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）

# 抓取在perplexity结果中找到的相关文档页面
(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时间戳}
type: external-research
topic: "{topic}"
focus: {focus}
sources: [nia, perplexity, firecrawl]
status: complete
---

# 研究：{主题}

## 摘要
{2-3句发现摘要}

## 关键发现

### 库文档
{来自nia-docs - API参考、使用模式}

### 最佳实践（2024-2025）
{来自perplexity - 推荐方法}

### 代码示例
```{语言}
// 找到的工作示例

推荐

  • {推荐1}
  • {推荐2}

要避免的陷阱

  • {陷阱1}
  • {陷阱2}

考虑的替代方案

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

源


#### 输出：`handoff`

写入：`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: "{pattern name}"
      code: |
        // 示例代码

  best_practices:
    - {practice1}
    - {practice2}

  pitfalls:
    - {pitfall1}

recommendations:
  - {rec1}
  - {rec2}

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

for_plan_agent: |
  基于研究，推荐的方法是：
  1. {步骤1}
  2. {步骤2}
  关键库：{lib1}, {lib2}
  避免：{pitfall1}

步骤5：返回摘要

研究完成

主题：{topic}
焦点：{focus}
输出：{文件路径}

关键发现：
- {发现1}
- {发现2}
- {发现3}

源：{N}个源引用

{如果交接输出：}
准备继续由plan-agent处理。

错误处理

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

  1. 记录失败在输出中：

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

  2. 继续其他源 - 部分结果有价值

  3. 适当设置状态：

    • complete - 所有请求的工具成功
    • partial - 一些工具失败，发现仍有有用
    • failed - 未获得有用结果

  4. 在发现中注意间隙：

    ## 间隙
- Perplexity不可用 - 最佳实践部分仅限于nia结果

示例

库研究（浅）

/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或nia服务器在mcp_config.json中
  • PERPLEXITY_API_KEY在环境或~/.claude/.env中
  • FIRECRAWL_API_KEY和firecrawl服务器在mcp_config.json中

注意

  • 不用于代码库探索 - 使用research-codebase或scout来实现
  • 始终引用源 - 为所有发现包含URL
  • 2024-2025时间框架 - 专注于当前最佳实践
  • 优雅降级 - 部分结果优于无结果