research · diff
git:20261009.171c8e9 to git:20261016.211e188
31 added, 19 removed. Audit A to A.
---
name: research
- description: 调研与调查工作流。当需要研究技术、库、框架、协议、代码实现、日志异常、配置问题、依赖关系或外部资料时使用。负责把调查过程整理成可复核的结论、证据链、未确认项和建议。
+ description: 对需要多步取证、交叉验证或比较分析的问题开展系统调查，形成有证据支持的结论。适用于跨模块行为调查、版本差异分析、技术方案比较及存在多种解释的疑难问题。不用于简单事实查询、定位符号或配置、单次文档查阅，以及其他技能中的常规信息确认。
user-invocable: true
---
# 调研与调查工作流
## 目标
将一个问题转化为可验证、可复核的调查结果：
```text
定义问题 → 限定范围 → 收集证据 → 交叉验证
- → 区分事实与推断 → 评估置信度 → 输出结果/落盘报告
+ → 区分事实与推断 → 评估置信度 → 在对话中交付，按需保存正式报告
```
## 何时使用
- - 技术、库、框架、协议和版本行为研究
- - 官方文档或源码调查
- - 代码库结构、调用链和实现方式调查
- - 日志和异常行为排查
- - 配置、依赖和构建问题调查
- - 用户要求查询数据库或外部系统状态
- - 需要为架构设计或实施方案准备事实依据
+ 先直接处理简单查询：查函数定义、定位配置、确认参数含义、查一项官方 API 用法，通常无需本技能。只有发现需要持续追踪、验证多个假设或综合多类证据时，再使用本技能；用户明确指定时遵从，并按问题规模精简过程。
+ 适用情形包括：
+
+ - 跨模块追踪行为及原因，需要综合调用链、配置或日志取证。
+ - 对比版本行为，核对源码、版本记录与实际观察是否一致。
+ - 比较技术方案，结合项目约束和资料形成决策依据。
+ - 存在多种解释，需要设计调查步骤逐一验证。
+
+ 不单凭文件数量、预计耗时或问题长短判断是否调用。其他技能执行中的常规读代码、搜索文档、查看配置或单次状态查询，不必转交本技能；只有形成独立调查问题时才委派。
+
用户围绕具体症状要求定位并修复 Bug 时，以可用的 `bug-debugging` 为主流程；本技能承接其中限定的源码、日志或版本调查。返回证据索引、实际实验结果及未确认项供其复用，不重复启动一轮完整调查，也不代替用户批准修复方案。
用户要求设计测试用例或检查业务场景覆盖时，以可用的 `test-design` 为主；本技能仅补充其中缺失的业务约定、项目事实或调用链证据，不重复设计或扩大为实施。
## 调查前
先明确：
- 要回答的具体问题
- 调查范围
- 代码版本、分支或时间范围
- 环境和系统边界
- - 期望的交付形式
+ - 交付形式：默认在对话中回复，已有明确文件交付要求时遵循
问题模糊时，先拆成可验证的问题列表，不要直接开始泛搜。
## 证据优先级
按可靠性优先使用：
1. 当前代码和配置
2. 当前测试、构建输出和原始日志
3. 官方文档、官方源码和版本说明
4. 项目历史、提交记录和变更记录
5. 第三方文章、问答和经验推断
关键结论尽量使用两类独立证据交叉验证。
## 调查任务委派
- 需隔离大量代码、日志或资料调查时，用宿主通用子 agent 工具派发；独立问题才并行。简单问题直接调查。任务说明包含目标项目绝对路径、问题与范围/版本、必要的本技能或 reference 绝对路径，以及交付要求；子 agent 只调查分配的问题，不代替主 Agent 决策。无法读取资源时附必要方法；无派发能力时自行调查并说明。
+ 需隔离大量代码、日志或资料调查时，用宿主通用子 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/`、`docs/architecture/`。
- 4. 都没有时新建 `docs/research/`；仓库没有 `docs/` 就先建 `docs/`，不要把裸文件丢在仓库根。
+ 3. 无明确约定时使用 `docs/research/`，按需创建。不要仅因 `docs/adr/`、`docs/rfcs/` 或 `docs/design/` 已存在，就将调查记录放进去；只有交付物符合其用途时才使用。
- 文件名为 `YYYY-MM-DD-主题.md`，正文包含问题、方法、事实与证据、推断、结论、置信度及未确认项。回复里给出路径，并说明该文件**未被跟踪**：不需要入库就自行删除或加忽略规则，**不要擅自改用户的 `.gitignore`**。
+ 同一主题、同一用途优先更新已有报告，保留仍有用的证据；需要独立版本或历史快照时才新建。新文件默认命名为 `YYYY-MM-DD-主题.md`，正文包含问题、方法、事实与证据、推断、结论、置信度及未确认项，篇幅按交付需要调整。
- **写入即卸载**：证据正文写盘后，上下文只保留结论、未确认项和文件路径，不再回读整份报告，需要引用时只读对应小节。调查量很大时改用一个主题目录加多份证据文件（如 `docs/research/2026-01-01-主题/evidence-模块.md`），主报告只留索引与结论，避免反复重写整份文件。
+ 回复中给出报告路径；只有确认后才说明 Git 跟踪状态，不自动提交，也不擅自修改 `.gitignore`。
+
+ ## 异常调查
排查异常时先确定时间、版本与影响范围，再对照日志、最近变更和调用链，列出根因假设及可验证的下一步。查询数据库或外部系统前确认访问能力；记录查询时间、条件与范围，无法访问时说明限制。
## 边界
本技能负责调查和编排，不负责擅自修改业务代码、不负责替用户做最终产品决策。实施阶段交给 `implementation-workflow` 和实施子任务。