Research

---
name: research
description: 调研与调查工作流。当需要研究技术、库、框架、协议、代码实现、日志异常、配置问题、依赖关系或外部资料时使用。负责把调查过程整理成可复核的结论、证据链、未确认项和建议。
user-invocable: true
---

# 调研与调查工作流

## 目标

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

```text
定义问题 → 限定范围 → 收集证据 → 交叉验证
→ 区分事实与推断 → 评估置信度 → 输出结果/落盘报告
```

## 何时使用

- 技术、库、框架、协议和版本行为研究
- 官方文档或源码调查
- 代码库结构、调用链和实现方式调查
- 日志和异常行为排查
- 配置、依赖和构建问题调查
- 用户要求查询数据库或外部系统状态
- 需要为架构设计或实施方案准备事实依据

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

## 调查前

先明确：

- 要回答的具体问题
- 调查范围
- 代码版本、分支或时间范围
- 环境和系统边界
- 期望的交付形式

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

## 证据优先级

按可靠性优先使用：

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

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

## 调查任务委派

需隔离大量代码、日志或资料调查时，用宿主通用子 agent 工具派发；独立问题才并行。简单问题直接调查。任务说明包含目标项目绝对路径、问题与范围/版本、必要的本技能或 reference 绝对路径，以及交付要求；子 agent 只调查分配的问题，不代替主 Agent 决策。无法读取资源时附必要方法；无派发能力时自行调查并说明。

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

## 结果要求

研究结果必须区分：

### 事实

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

### 推断

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

### 未确认项

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

### 置信度

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

不要把：

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

## 长报告与异常调查

内容多到会挤爆上下文，或用户要求保存/交付报告时，**必须落盘**——用磁盘换上下文，不要凭记忆硬扛。

落盘位置按顺序取第一个命中项：

1. 用户显式指定的路径。
2. 仓库明文约定：`AGENTS.md`、`CONTRIBUTING.md`、`README.md` 中规定的报告目录。
3. 仓库已有报告类目录：`docs/research/`、`docs/adr/`、`docs/rfcs/`、`docs/design/`、`docs/architecture/`。
4. 都没有时新建 `docs/research/`；仓库没有 `docs/` 就先建 `docs/`，不要把裸文件丢在仓库根。

文件名为 `YYYY-MM-DD-主题.md`，正文包含问题、方法、事实与证据、推断、结论、置信度及未确认项。回复里给出路径，并说明该文件**未被跟踪**：不需要入库就自行删除或加忽略规则，**不要擅自改用户的 `.gitignore`**。

**写入即卸载**：证据正文写盘后，上下文只保留结论、未确认项和文件路径，不再回读整份报告，需要引用时只读对应小节。调查量很大时改用一个主题目录加多份证据文件（如 `docs/research/2026-01-01-主题/evidence-模块.md`），主报告只留索引与结论，避免反复重写整份文件。

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

## 边界

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