research · diff
git:20261016.211e188 to git:20261023.3bafb01
19 added, 93 removed. Audit A to A.
---
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/` 已存在，就将调查记录放进去；只有交付物符合其用途时才使用。
+ 需要隔离大量材料或分配独立调查问题时，使用宿主的通用子 agent 能力；独立且无冲突的任务才并行，无派发能力时自行调查。
- 同一主题、同一用途优先更新已有报告，保留仍有用的证据；需要独立版本或历史快照时才新建。新文件默认命名为 `YYYY-MM-DD-主题.md`，正文包含问题、方法、事实与证据、推断、结论、置信度及未确认项，篇幅按交付需要调整。
+ 任务说明包含问题、范围、相关版本与条件、实际可用的项目或资料位置、必要的技能资源及交付要求。子 agent 只调查分配的问题，按本技能的结果要求返回，不代替主 Agent 决策。
- 回复中给出报告路径；只有确认后才说明 Git 跟踪状态，不自动提交，也不擅自修改 `.gitignore`。
+ 主 Agent 等待实际结果，核对支撑关键结论的证据；发现缺失、冲突或版本不一致时补证。未完成或失败的调查不能算作已验证。
- ## 异常调查
+ ## 结果要求
- 排查异常时先确定时间、版本与影响范围，再对照日志、最近变更和调用链，列出根因假设及可验证的下一步。查询数据库或外部系统前确认访问能力；记录查询时间、条件与范围，无法访问时说明限制。
+ 直接回答调查问题，给出关键证据与结论；篇幅按问题规模调整，不强制套完整报告模板。结果应清楚区分：
- ## 边界
+ - **事实**：直接观察或核实的内容，附可定位的来源及相关版本、时间或环境条件。
+ - **推断**：基于事实得出的解释，说明推理依据，不把假设写成已验证事实。
+ - **未确认项**：证据、权限或工具不足以确认的部分，以及影响结论的反证、证据冲突和适用限制。
- 本技能负责调查和编排，不负责擅自修改业务代码、不负责替用户做最终产品决策。实施阶段交给 `implementation-workflow` 和实施子任务。
+ 说明关键结论的确定程度及依据，不强制使用统一的置信度标签。证据不足时允许交付未确定结论；“没有查到”不等于“不存在”，“工具不可用”不等于“系统没有数据”。