comprehensive-research

用途

Comprehensive Research 是一个多阶段研究编排技能，用于对代码库、项目文档和外部知识进行系统性调查。它由 /ai-eng/research 命令调用，目标是产出有证据支撑、可执行的研究结论。默认输出约定为：只返回结果、阻塞项与必要证据，省略前言、过程叙述、重复上下文、置信度评分和后续提议；除非所需产物或 schema 要求更多，否则最多使用五条要点。

主要能力

该技能将研究流程组织为四个阶段：

1. Discovery（发现，并行）：并行启动多个定位智能体。

   • codebase-locator：查找相关文件、组件、目录，超时 5 分钟
   • research-locator：发现已有文档、决策、笔记，超时 3 分钟
   • codebase-pattern-finder：识别反复出现的实现模式，超时 4 分钟

   发现阶段输出结构包含 codebase_files（path/file.ext:lines）、documentation、patterns_identified 和 coverage_map。

2. Analysis（分析，串行）：发现完成后依次运行分析器。

   • codebase-analyzer：给出带 file:line 证据的实现细节，依赖 codebase-locator
   • research-analyzer：提取决策、约束与洞察，依赖 research-locator

3. 领域专家（按条件触发）：复杂研究时追加：

   • web-search-researcher：需要外部上下文时
   • system-architect：涉及架构影响时
   • database-expert：涉及数据层问题时
   • security-scanner：需要安全评估时

4. Validation（校验，并行）：code-code-reviewer 与 architect-review 并行执行。

使用方式

研究前需先定义上下文与范围，包括主要问题、拆解后的子问题、范围边界、深度级别（shallow | medium | deep）和预期交付物。关键规则：在启动智能体前必须完整阅读一手来源。

常见调用示例：

• /research "How does the authentication system work in this codebase?"
• /research "Analyze payment processing implementation" --scope=codebase --depth=deep
• /research --ticket="docs/tickets/AUTH-123.md" --scope=both

研究完成后，典型后续命令为 /plan（制定实施计划）、/review（校验结论）、/work（带着完整上下文开始实现）。

适用场景

• 想弄清某子系统（如认证、支付）在代码库中的实际工作方式
• 需要结合代码、文档历史决策与外部资料的综合调研
• 需要带 file:line 证据链、可追溯的架构洞察与建议
• 需要识别可复用的实现模式与跨组件关系

输出格式

研究结果汇总为带 frontmatter 的 Markdown 文档，包含 Synopsis、Summary、Detailed Findings（组件分析、文档洞察、代码引用）、Architecture Insights、Historical Context、Recommendations（即时行动与长期考虑）、Risks & Limitations、Open Questions。同时输出结构化 JSON，含 status、timestamp、cache 信息、research、findings、document、agents_used、metadata 与 confidence（overall、codebase_coverage、documentation_coverage、external_coverage）。

质量与缓存

质量指标包括：多智能体交叉验证的全面覆盖、所有发现带 file:line 引用、包含历史决策与理由的上下文深度、可执行的下一步、风险评估。

缓存策略：类型 hierarchical，TTL 3600 秒（1 小时），手动失效，作用域为 command。缓存内容包括成功的智能体协调策略、有效智能体组合、问题拆解模式、模式识别结果。缓存性能目标：命中率 ≥60%，内存占用 <30MB，响应时间提升 <150ms。

错误处理与限制

常见失败场景及缓解方式：研究问题无效（请求澄清）、智能体超时（缩小范围重试）、发现不足（扩大范围、增加智能体）、信息冲突（记录冲突并标记复核）。升级触发条件包括：多个智能体失败、范围超出单会话容量、需要跨仓库研究、需要外部 API/服务调查。

需避免的反模式：未读来源就启动智能体、本可并行却串行执行、仅依赖缓存文档、跳过缓存检查、忽略历史上下文、初始范围过大。

明确要求：所有论断须有 file:line 证据；相关处包含历史上下文；显式列出开放问题；建议须可执行；分配置信度；识别跨组件关系；记录潜在风险。关于收费方式、价格、平台支持的具体信息，资料中暂未提供。