---
name: research
description: 对需要多步取证、交叉验证或比较分析的问题开展系统调查，形成有证据支持的结论。适用于跨模块行为调查、版本差异分析、技术方案比较及存在多种解释的疑难问题。不用于简单事实查询、定位符号或配置、单次文档查阅，以及其他技能中的常规信息确认。
user-invocable: true
---

# 调研与调查工作流

## 目标

将一个问题转化为可验证、可复核的调查结果：

```text
定义问题 → 限定范围 → 收集证据 → 交叉验证
→ 区分事实与推断 → 评估置信度 → 在对话中交付，按需保存正式报告
```

## 何时使用

先直接处理简单查询：查函数定义、定位配置、确认参数含义、查一项官方 API 用法，通常无需本技能。只有发现需要持续追踪、验证多个假设或综合多类证据时，再使用本技能；用户明确指定时遵从，并按问题规模精简过程。

适用情形包括：

- 跨模块追踪行为及原因，需要综合调用链、配置或日志取证。
- 对比版本行为，核对源码、版本记录与实际观察是否一致。
- 比较技术方案，结合项目约束和资料形成决策依据。
- 存在多种解释，需要设计调查步骤逐一验证。

不单凭文件数量、预计耗时或问题长短判断是否调用。其他技能执行中的常规读代码、搜索文档、查看配置或单次状态查询，不必转交本技能；只有形成独立调查问题时才委派。

用户围绕具体症状要求定位并修复 Bug 时，以可用的 `bug-debugging` 为主流程；本技能承接其中限定的源码、日志或版本调查。返回证据索引、实际实验结果及未确认项供其复用，不重复启动一轮完整调查，也不代替用户批准修复方案。

用户要求设计测试用例或检查业务场景覆盖时，以可用的 `test-design` 为主；本技能仅补充其中缺失的业务约定、项目事实或调用链证据，不重复设计或扩大为实施。

## 调查前

先明确：

- 要回答的具体问题
- 调查范围
- 代码版本、分支或时间范围
- 环境和系统边界
- 交付形式：默认在对话中回复，已有明确文件交付要求时遵循

问题模糊时，先拆成可验证的问题列表，不要直接开始泛搜。

## 证据优先级

按可靠性优先使用：

1. 当前代码和配置
2. 当前测试、构建输出和原始日志
3. 官方文档、官方源码和版本说明
4. 项目历史、提交记录和变更记录
5. 第三方文章、问答和经验推断

关键结论尽量使用两类独立证据交叉验证。

## 调查任务委派

需隔离大量代码、日志或资料调查时，用宿主通用子 agent 工具派发；独立问题才并行。简单问题直接调查。任务说明包含目标项目绝对路径、问题与范围/版本、必要的本技能或 reference 绝对路径，以及交付要求；子 agent 只调查分配的问题，不代替主 Agent 决策。默认通过消息返回结果，沿用主 Agent 已确定的保存方式，不自行在项目中创建报告。无法读取资源时附必要方法；无派发能力时自行调查并说明。

要求返回结论、带文件行号或来源的证据、置信度、未确认项和完成状态。主 Agent 等待报告，抽查 2–5 处关键证据后给出结论；发现问题交回原任务补证。未完成或失败的调查不能算作已验证。

## 结果要求

默认直接在对话中给出结论、关键证据和未确认项；篇幅随问题规模调整，不为简单问题强制套完整报告模板。需要区分以下内容，但不要求逐项设标题：

### 事实

已经直接观察到的内容，带文件路径、日志位置、时间或来源。

### 推断

根据事实得出的解释，必须说明推理链。

### 未确认项

当前权限、工具或证据不足以确认的部分。

### 置信度

使用高 / 中 / 低，并说明依据。

不要把：

- “可能”写成“确定”
- “没有查到”写成“不存在”
- “工具不可用”写成“系统没有数据”

## 保存规则

调用本技能、使用子 agent、查阅材料较多或调查耗时较长，都不单独构成在项目中创建文件的理由。“调研一下”“给我报告”可在对话中完成；用户要求保存、生成报告文件、指定路径，或当前任务明确要求形成项目文档时，才保存正式报告。不要为每次普通调查询问是否保存。

### 临时记录

大量材料确需卸载上下文时，使用系统临时目录下本任务独立的目录保存必要证据，不在项目中创建报告目录或临时文件。消息中交付可理解的结论与关键来源，不让已删除或可能失效的临时文件成为唯一证据入口。临时记录不自动升级为正式报告。

保留结论、未确认项与证据索引，需要复核时只读取相关片段，避免反复加载全部材料。

### 正式报告

确定需要文件交付后，保存位置按顺序选择：

1. 用户显式指定的路径。
2. 仓库明文约定：`AGENTS.md`、`CONTRIBUTING.md`、`README.md` 中规定的报告目录。
3. 无明确约定时使用 `docs/research/`，按需创建。不要仅因 `docs/adr/`、`docs/rfcs/` 或 `docs/design/` 已存在，就将调查记录放进去；只有交付物符合其用途时才使用。

同一主题、同一用途优先更新已有报告，保留仍有用的证据；需要独立版本或历史快照时才新建。新文件默认命名为 `YYYY-MM-DD-主题.md`，正文包含问题、方法、事实与证据、推断、结论、置信度及未确认项，篇幅按交付需要调整。

回复中给出报告路径；只有确认后才说明 Git 跟踪状态，不自动提交，也不擅自修改 `.gitignore`。

## 异常调查

排查异常时先确定时间、版本与影响范围，再对照日志、最近变更和调用链，列出根因假设及可验证的下一步。查询数据库或外部系统前确认访问能力；记录查询时间、条件与范围，无法访问时说明限制。

## 边界

本技能负责调查和编排，不负责擅自修改业务代码、不负责替用户做最终产品决策。实施阶段交给 `implementation-workflow` 和实施子任务。