Back to Details

deep-research

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deep Research

深度研究

Coordinate deep technical research with intelligent caching for cross-project reuse and team knowledge sharing.
通过智能缓存协调深度技术研究，实现跨项目复用与团队知识共享。

Quick Start

快速开始

When research is needed:
  1. Resolve scripts path - Find 
    plugins/core/skills/deep-research/scripts/
    (or Glob for 
    **/deep-research/scripts/cache_manager.py
    )
  2. Check cache first - Run 
    python3 {scripts_dir}/cache_manager.py check "{topic}"
  3. If cached and valid - Run 
    cache_manager.py get "{slug}"
    and return content directly (no agent needed)
  4. If cache miss - Invoke 
    deep-researcher
    agent for EXA research, which caches via 
    cache_manager.py put
  5. Report findings - Include cache status and promote suggestion
当需要开展研究时：
  1. 解析脚本路径 - 找到
    plugins/core/skills/deep-research/scripts/
    （或通过Glob匹配
    **/deep-research/scripts/cache_manager.py
    ）
  2. 优先检查缓存 - 运行
    python3 {scripts_dir}/cache_manager.py check "{topic}"
  3. 如果缓存有效 - 运行
    cache_manager.py get "{slug}"
    并直接返回内容（无需调用Agent）
  4. 如果缓存未命中 - 调用
    deep-researcher
    Agent执行EXA研究，研究结果将通过
    cache_manager.py put
    存入缓存
  5. 汇报研究结果 - 包含缓存状态并给出推荐建议

Cache Architecture

缓存架构

TierLocationPurposeShared
1
~/.claude/plugins/research/
Fast, cross-projectUser only
2
docs/research/
Curated, version controlledTeam
层级存储位置用途是否共享
1
~/.claude/plugins/research/
快速访问，跨项目使用仅当前用户
2
docs/research/
精心整理，版本控制团队共享

Operations

操作说明

OperationTriggerFast Path?Action
Research
/research <topic>
or natural language		Yes (cache hit)Check cache → return if valid, else research → cache
Promote
/research promote <slug>
YesRun 
promote.py {slug}
directly
Refresh
/research refresh <slug>
NoSpawn agent → fresh research → cache → update promoted
List
/research list
YesRun 
cache_manager.py list
(project-scoped by default, 
--all
for everything)
操作触发方式是否有快速路径操作内容
研究
/research <topic>
或自然语言指令		是（缓存命中时）检查缓存→若有效则返回，否则执行研究→存入缓存
升级
/research promote <slug>
是直接运行
promote.py {slug}
刷新
/research refresh <slug>
否启动Agent→重新开展研究→更新缓存→同步到升级后的存储
列出
/research list
是运行
cache_manager.py list
（默认仅显示当前项目相关内容，使用
--all
查看全部）

Project Scoping

项目范围限定

Research entries are automatically associated with the current git repository when cached. The 
list
operation filters by current project by default, so each project sees only its relevant research. Use 
--all
to see everything.
  • Auto-detection: Project name derived from 
    git rev-parse --show-toplevel
    basename
  • Multi-project: Entries can belong to multiple projects (associations merge, never replace)
  • Backward compatible: Existing entries without project associations appear in 
    --all
    but not in project-scoped views
研究条目在存入缓存时会自动关联当前Git仓库。
list
操作默认仅筛选当前项目的内容，因此每个项目仅能查看与其相关的研究。使用
--all
参数可查看所有研究条目。
  • 自动检测：通过
    git rev-parse --show-toplevel
    命令的结果提取项目名称
  • 多项目支持：条目可关联多个项目（关联关系会合并，不会被替换）
  • 向后兼容：未关联项目的现有条目仅会在
    --all
    模式下显示，不会出现在项目专属视图中

Scripts

脚本说明

All cache operations use Python scripts in 
scripts/
:
ScriptPurpose
research_utils.py
Shared utilities (imported by all scripts)
cache_manager.py
Cache CRUD: get, put, check, list, delete
promote.py
Tier 1 → Tier 2 promotion with team notes
index_generator.py
README index generation for both tiers
所有缓存操作均使用
scripts/
目录下的Python脚本：
脚本用途
research_utils.py
共享工具库（被所有脚本导入使用）
cache_manager.py
缓存的增删改查操作：获取、存入、检查、列出、删除
promote.py
将层级1的条目升级到层级2，并添加团队备注
index_generator.py
为两个层级的缓存生成README索引

Slug Normalization

Slug标准化

Convert topics to cache keys:
  • "Domain-Driven Design" → 
    domain-driven-design
  • "DDD" → 
    domain-driven-design
    (via alias)
  • "React Hooks" → 
    react-hooks
将主题转换为缓存键：
  • "Domain-Driven Design" → 
    domain-driven-design
  • "DDD" → 
    domain-driven-design
    （通过别名映射）
  • "React Hooks" → 
    react-hooks

Output Format

输出格式

After research, report:
undefined
研究完成后，按以下格式汇报：
undefined

Research: {Topic}

研究主题: {Topic}

Cache: {Hit | Miss | Expired} Source: {Cached | Fresh research} Path: ~/.claude/plugins/research/entries/{slug}/
[Brief summary of findings]
Run 
/research promote {slug}
to add to project docs.
undefined
缓存状态: {命中 | 未命中 | 已过期} 来源: {缓存内容 | 最新研究结果} 路径: ~/.claude/plugins/research/entries/{slug}/
[研究结果简要总结]
运行 
/research promote {slug}
可将该条目添加到项目文档中。
undefined

Agent Delegation

Agent委托

For actual research execution (cache miss or refresh only), delegate to 
deep-researcher
agent:
  • Has MCP tool access (EXA web search, code context)
  • Uses 
    cache_manager.py put
    for cache write operations
  • Structures research output consistently
仅在缓存未命中或需要刷新时，才会委托给
deep-researcher
Agent执行实际研究：
  • 拥有MCP工具访问权限（EXA网页搜索、代码上下文）
  • 使用
    cache_manager.py put
    执行缓存写入操作
  • 输出格式保持一致

Additional Resources

额外资源

  • WORKFLOW.md - Detailed process flows
  • EXAMPLES.md - Usage examples
  • TROUBLESHOOTING.md - Common issues and solutions
  • WORKFLOW.md - 详细的流程说明
  • EXAMPLES.md - 使用示例
  • TROUBLESHOOTING.md - 常见问题及解决方案