research

研究

通过引用证据，回答提问者范围明确的问题。根据问题选择常规调查、主张核查、已声明状态审计、决策脉络、仓库追踪或模式证据；这些是可选模式，并非必须依次执行。快速回答无需报告文件。 Plan 负责变更规划过程中的统一发现与恢复；如果问题属于变更规划的一部分，请将这份带引用的回答交还给现有意图，不要重新开始访谈，也不要替提问者做选择。

证据规则

• 同一来源脉络只计一次。 对同一上游来源的复制、移植和重复引用都算作同一个实例，不论有多少文件或报告载有它们。计数独立实例前，先核查来源；如果新查询只返回已读过的来源，就停止搜索。
• 区分不变量与偶然因素。 按行为中的作用对齐实例；指出必须满足的条件、合理变化的部分，以及偶然的语法形式。缺少不变量的实例不算实例。
• 重复出现不构成设卡理由。 阻断式检查需要有证据证明违反模式会造成代价：能追溯到该模式缺失的事故、缺陷或经测量的损害。建议采用承诺程度最低但有用的形式：不采取行动、添加参考资料或清单条目、模板、辅助工具，最后才是设卡。
• 证据薄弱时只能视为假设。 少于三个独立实例，或没有通过检验的留出样本，都意味着模式仍是假设；说明哪些证据可以证实或证伪它。
• 将观察、推断、矛盾和未知情况分开。每项实质性主张都要引用证据；引用文档或报告中的主张时，应引用明确陈述该主张的段落，而不是仅讨论相关主题的段落，否则应标为缺乏支持。若决定性主张仅依赖一个来源，应明确说明；来源之间一致并不能消除它们的共同出处。
• 调用不等于被调用方的行为。 看到代码调用 retry、validate 或某个服务，只能证明发生了调用。如果主张依赖被调用方提供的保证（重试、原子性、幂等性、有序性、持久性），应阅读其实现或测试，或查阅外部服务公布的契约；否则应在主张本身中将该保证标为未知，而不是留到之后的附注中再说明。
• 只有搜索范围确实能够匹配，搜索无结果才能证明缺失。 在声称某项内容不存在或未使用之前，应检查搜索的退出状态和错误输出、结果是否被截断、忽略规则或默认筛选条件是否跳过了相关路径（被忽略、隐藏、供应商提供或生成的文件），以及搜索针对的是预期的引用或目录树，而非过时索引。在成本低时，确认同一搜索能找到已知存在的词项。搜索失败或范围错误意味着未知，并应说明原因，而不是说“未找到”。对于“未使用”或“没有任何调用此项”的说法，文本搜索也会漏掉重新导出、别名、反射、字符串键分派、依赖注入、生成代码和外部使用者；如果宿主环境提供能识别引用关系的工具，应优先使用，并说明仍未检查上述哪些情况。

调查

1. 说明问题及其所涉及的决策。沿用已接受的范围，并明确哪些证据可以回答问题；不要在搜索过程中扩大目标。使用调用者指定的主题、范围和来源。如果范围为空、缺少主题或无法访问指定来源，应如实说明，而不是转而回答相近的问题；如果调用者允许使用替代来源，请指出所用的替代来源。
2. 检查最少量的相关来源，并对照实际来源核实搜索命中结果。对于会变化的外部事实（版本、供应商行为、标准），需要使用当前的第一手来源；如可用且获准，应通过宿主的网络工具获取，否则将相关说法标为未知，并指出可用于核实的来源。查询离开宿主之前，删除宿主名称、IP 地址、文件路径、查询片段、账户或客户标识符以及内部名称，并使用通用错误类别和库及其版本进行搜索；如果无法得到安全的查询形式，就跳过查询并说明原因。对于第三方库、工具或服务在此处的行为，应依据此仓库实际解析的版本（锁文件、已安装二进制文件的版本或 vendored 副本），以及该版本的源码、测试或发行说明作答；最新文档、网络答案和记忆只能作为线索，因此如果它们描述的是其他版本，应予以说明。在推荐外部 API、SDK、身份验证范围或服务之前，应检查该版本的弃用、停止服务和重大变更通知，并说明相关情况，或说明尚未检查其状态。
3. 先给出答案，再展示证据和仍存在的缺口。问题的每个部分都应得到回答，或明确标为未知并披露已搜索的范围。确定重要结论之前，应至少查找一次最有力的反面证据。若调用者要求解释，应使用通俗易懂的语言，并标明哪些理由有文档依据、哪些是推断、哪些未知。

代码相关说法应引用已观察到的提交及 file:line。对于尚未提交的内容，应说明 HEAD 和已更改文件的状态；不得声称当前工作区中的字节内容可以从 HEAD 重现。应清楚呈现来源身份和时效性。搜索输出、CASS、MS 和先前报告只是线索，并非权威依据，也不是必须经过的阶段。默认使用当前 Agent；只有在调用者选择或已有授权时，才使用额外的阅读器和运行时。

对于多份给定报告，应保留每个来源的标识符、作者／运行时（如已知）以及修订版本／日期。比较各项说法时，应标明一致、矛盾或未知，同时保留原始证据。应在来源处核实决定性说法，并给出一份综合结论；不要启动递归式的综合流程。

说法核查

若要核查草稿、报告或答案是否属实，应将其拆分为来源能够证实或反驳的原子说法。声称工作已完成、已发布或已接入的内容，属于状态声明审计。观点和预测不作核查；应说明这一点。优先核查最容易造成误导的内容：数字、引文、归属、最高级说法，以及结论所依赖的说法。训练数据中的记忆只能作为线索，绝不是来源。

• 重新推导，不要重新阅读。 对由数据得出的说法（查询、脚本、仓库计数），应通过另一条路径核查：使用另一条查询、不同的键或分组方式，或直接检查底层文件。重新运行生成结果的程序会重复其错误；报告自己的数字不能作为该报告的证据。
• 共同出现不代表作者身份。 “X 撰写、决定或导致了 Y”这类说法，需要有明确陈述或记录证明这种确切关系。两者出现在同一提交、会议或文档中，证据力度较弱；应如实报告其证据较弱。
• 将每项说法标为已支持、已反驳、缺乏支持或无法核查，并附上引用和所用路径。更正内容属于提议；编辑已核查的文档应交由 Doc 处理。

声明状态审计

对于已完成、已交付、已修复、可正常运行或已接入的声明（例如 Agent 的完成报告、工单摘要、变更日志条目或状态帖子），逐项比较预期状态与可观察到的证据。这里所指的失败模式是只审计差异实际触及的内容：声明中提及但证据中没有踪迹的项目属于缺口，不能从报告中省略。

要求核查明确声明、衡量已声明目标或报告原生状态时，无需再提问即可选择此审计。若只问“准备好了吗？”却没有声明，也没有确定的目的，则存在歧义：按照共享的建议还是验收规则询问一次。此审计不是验收，也不能替代 Validate 中新鲜且由不同作者做出的判断；如果用户希望进行验收，则应交接，并将缺少新鲜审核者报告为缺口。

1. 阅读准确的声明及其来源，并将其拆分为各个独立项目，包括从未开始的工作。
2. 为每个项目单独给出判定：已确认（引用证据）、缺口（指出缺失或与之矛盾的内容）或无法核实（说明需要什么证据才能判定）。只认可证据所展示的内容：仅报告运行而未提供输出、行为交由默认设置或其他组件决定，以及未断言所声明结果的测试，均属于无法核实，而非已确认。不要通过断言来判定无法测试的声明。
3. 可从实时入口访问。 如果生产环境会调用的实时入口（路由、命令、作业、处理程序或导出 API）都无法访问某段代码，那么无论该代码自身的测试结果如何，它都没有接入。对于声称已实现行为的声明，还要搜索其背后的代码，查找伪实现：常量或硬编码结果、TODO 或未实现分支、示例数据，或测试代码之外的测试替身。追踪每个命中项的调用方，再进行分类。生产路径会访问的占位实现会使该项目成为缺口；仅在测试中使用的替身，或无人调用的代码则不会。
4. 交付状态取决于当前远程状态中的可达性。 对于声称工作已推送、合并、交付或在指定提交或拉取请求中修复的说法，应根据可达性来判定，而不是依据本地引用、推送输出或保存的状态；还应按上述方式检查相关内容目前是否仍存在于目标头部，以及是否实现了声明的效果。已推送意味着可从指定的远程分支访问，或可从拉取请求在其自身头部分支仓库中的当前头部访问，包括分叉仓库。已合并意味着可从声明中指定的目标分支访问；若未指定，则从默认分支头部访问；或者拉取请求已以该分支为基础分支合并。合并到其他基础分支不能确认该声明。已交付意味着存在于仓库发布策略指定的位置（标签、已发布版本或部署）中，并应从该来源读取。若压缩合并或变基导致祖先关系中断，应将内容与目标进行比较，而非假定提交等价。在将提供的 SHA 或拉取请求编号传入命令之前，先检查其格式。
5. 对于计划，将拟议范围与原始目标进行比较；未经授权的新增内容属于范围升级，报告无权批准。重复测量应沿用同一问题和标准；问题发生变化时，应开始另一项比较。
6. 返回包含已检查和未检查范围的核对表。将原生跟踪器、Git、运行时、确定性检查和语义判断的事实分开记录。

Claim: <the claim as stated, and where it came from>
| # | Stated item | Disposition | Evidence, or what would settle it |
|---|---|---|---|
| 1 | <item> | confirmed / gap / unverifiable | <file:line, command output, artifact> |
Checked: <what was inspected>. Not checked: <what was not>.

核对表报告的是证据；即便所有项目都已确认，也不得给出整体 PASS、FAIL、判决或就绪状态。其持久化形式见输出与边界。

健康状况、目标和状态

对于“此仓库是否健康”或“检查是否通过”，请运行项目自身的只读检查（在其说明或 CI 配置中声明，或在构建文件中找到），优先选择 --check、dry-run 或 verify 变体，并记录每项检查的来源。将任何会写入受版本控制的文件、发布、部署或需要凭据的步骤列为未运行，并说明原因。每项检查单独运行，失败后继续。根据退出状态（而非解析输出）将每项报告为通过、失败、未运行（工具不可用）或未确定（未捕获输出），并列出未运行的已声明检查。不要修复任何内容，也不要将所有结果合并成一个掩盖失败的分数。

针对已声明的目标来源运行 ao goals 的方法见目标；使用 ao status 读取证据存储的方法，以及快照无法显示的内容，见状态。近期的产物时间戳只能证明证据较新，不能证明有活动中的工作进程。不要添加、删除、设定优先级、迁移或修复目标，也不要将测量缺口转化为已分配的工作。

采纳问题

对于“我们是否应该采纳、替换或保留 X”或“建议 Y 是否适用于我们”，答案需要兼顾两方。我们这方：当前使用的工具，以及引用其使用位置；或者搜索后确认未使用，并说明 X 可以接入的位置；还要列出此前对同一问题做出的任何决定。他们这方：答案所依据的每项外部事实都需要当前的一手来源。任何一方证据充分，都不能弥补另一方的缺失；若有缺失，则回答“目前尚无法作答”，并列出需要检查的内容。保留当前工具或按兵不动也是有效选项。来源、排序以及适配度、维持现状的许可和成本、维护等方面的事实，见采纳证据。

决策沿革

对于“为什么会这样”或“这个想法如何演变”，请通过提交、ADR、问题、评审和先前报告追溯一项决策或想法，并按日期整理到有引用的类别中：首次出现、最清晰的表述、当前形式、反转、矛盾（无法同时成立的两项主张）和已放弃的变体。空类别应说明搜索过哪些内容；被取代不等于矛盾；不要把杂乱的历史梳理成整齐的故事。在将过去的理由视为有约束力之前，请确认其成因在当前代码树或记录中仍然成立；若不成立，应将其报告为重新审议的依据，并由其负责人或提问者决定。

仓库追踪

对于仓库模型或审计，请从文档、构建清单或命令帮助中声明的入口点开始，并通过可执行路径核实。沿着相关流程追踪入口、领域逻辑、集成和测试；相较于浅层的目录盘点，应优先完成完整追踪。若追踪中断，请精确指出文件和行号，并说明缺少什么。选择一个有用的视角，例如持久化、授权、CLI、构建或测试；无需逐一全面检查所有视角。在任何追踪中（包括解释工作原理的回答），都要说明每一步读取或更改了什么，并保留问题所涉及的错误和边界分支，而不只描述成功路径。行为应以源代码和测试为依据；文件名或对话中的说法不能作为依据。

行内调查可以使用存在未提交更改的工作树证据，但必须明确说明其局限；已选定的持久化 codebase-recon.v1 包与提交绑定。

模式证据

对于反复出现的实现模式，请根据上述证据规则检验其相似性是否代表一条可复用规则。记录可重复执行的搜索、已检查的命中项和排除项，然后报告：

exemplars: <file:line> per independent lineage; copies listed under their source
invariant: <what every exemplar shares and the behavior needs>
variation: <legitimate differences>; incidental: <syntax, names>
cost:      <demonstrated cost of violation, or "none found">
shape:     <no-action | reference-line | template | helper | gate> and why
outcome:   hypothesis | promote (three independent exemplars, passing holdout and back-application)

研究会提供证据；是否采纳仍由提问者明确决定。

输出和边界

<skill-dir> 是包含此 SKILL.md 的目录。Claude Code 将其显示为“此技能的基础目录”；Codex 会列出此技能的 SKILL.md 路径；在 AgentOps 源代码检出中，它是 skills/research。运行命令前，请将 <skill-dir> 替换为该绝对路径。工作目录保持为用户的仓库。如果宿主未显示此技能的安装位置，请使用你读取的 SKILL.md 所在目录。如果无法确定，请勿猜测路径，也不要运行当前仓库中同名的脚本；请说明捆绑脚本不可用，并手动根据其格式检查产物字段。

除非请求了持久化输出，或所选模式要求持久化输出，否则直接返回带引用的答案。若要保存报告，请使用调用者指定的位置；否则使用仓库现有的研究或决策记录位置和命名规则；如果两者都没有，则返回答案并询问保存位置。读回文件并报告其准确路径。每种持久化模式都使用自己的格式：

• 普通报告： findings.json 仅允许包含 topic、summary、findings（每项包含 area、observation、evidence，以及可选的 implications）、checked、not_checked 和 schema_version: 1。多报告综合还需添加 source_ledger 和 comparison（包含 agreements、contradictions、unknowns）。
• 声明状态审计： 使用 reality-check-report.v1 格式的 reality-check-report.json。该名称沿用自已弃用的 Reality Check 技能。文件包含 claim；coverage，每个陈述事项占一行，包含 goal（该事项）、disposition 和 evidence（已确认项和差距项必须提供）；以及至少一条 findings，包含 category（confirmed、gap、incomplete-evidence 或 changed-assumption）、statement 和带引用的 evidence。如果所有事项都无法核实，则记录一条引用所做搜索的不完整证据发现。文件不包含 verdict、readiness 或 PASS 字段。使用 bash "<skill-dir>/scripts/claim-audit/validate-output.sh" <report.json> 检查。
• 仓库追踪： 按照 recon pack contract 中的 codebase-recon.v1 格式编写，并使用 bash "<skill-dir>/scripts/codebase-recon/validate-output.sh" --repo-root <target> <recon.json> 检查。
• 模式证据： 按照 pattern pack contract 中的 pattern-mining.v1 格式编写，并使用 bash "<skill-dir>/scripts/pattern-mining/validate-output.sh" <pattern.json> 检查。

仅使用获准的来源和目标位置。对于受限或挖掘出的事件材料，请遵循 Memory 的访问和存储边界。 Research 不负责选择工作、不拥有合并后的上下文存储、不修改生命周期状态，也不作语义判定。除请求的报告和数据包外，它唯一允许产生的输出副作用，是记录在案的目标快照，以及声明状态审计所请求的报告／规范写入。原生调用方负责获准结果的实现、判断和完成。