antithesis-triage

Antithesis 运行分诊

技能版本： 2026-10-21 4f8d80b

使用此技能分析 Antithesis 测试运行。

参考文件： 此技能的 references/ 目录中包含针对特定任务的详细指南。请勿一开始就全部读取——只有在收到指示时才读取参考文件。每个参考文件都会在需要时按名称提及。

前置条件

• 如果未安装 snouty，请勿继续。有关安装选项，请参阅 https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md。
• 如果 snouty 版本低于 0.8.0，请勿继续。使用 snouty --version 查看版本。使用 snouty update 进行更新。
• 如果未安装 jq，请勿继续。有关安装选项，请参阅 https://jqlang.org/download/。

预检：确认分诊可以正常工作

分诊技能通过 snouty API（snouty runs ...）与 Antithesis 通信。开始任何工作前，请确认设置已就绪：

snouty doctor --json

此操作会验证 API 连接，并报告 snouty 解析出的配置。

只有顶层 ok 为 true 且 api_key 检查的 status 为 ok 时，才能继续。否则，请转述失败检查的 message/notes 并停止；如果失败的检查是 api_key，请告知用户设置 ANTITHESIS_API_KEY。

同一输出中的 settings 数组包含 snouty 解析出的参数。例如，可以通过以下命令查询解析出的租户：

snouty doctor --json | jq -r '.settings[] | select(.name == "tenant") | .value'

收集用户输入

开始前，请向用户收集以下信息：

1. 租户名称（必填）——必须知道租户名称。通过 snouty doctor --json 读取 snouty 解析出的租户（参见“预检”）；snouty 会从环境或设置文件中解析该值，因此应以此值为准。只有在 doctor 显示租户未设置时才询问用户。

2. 他们想了解的内容——他们是想查看特定运行中的所有失败项、调查某个特定失败项、获取总体概览，还是比较不同运行？这将决定要遵循的工作流。

如何从运行中获取信息

获取信息的主要方法是使用带有 --json 选项的 snouty runs <OPTION> 命令。--json 选项会返回按行分隔的 JSON。JSON 中的字段取决于所用选项。同一命令不带 --json 时会以表格形式返回较少字段，更适合人工查看。

你需要知道 RUN_ID。阅读 references/run-discovery.md，了解如何获取 run_id。

工作流

汇总近期运行

阅读 references/run-discovery.md 获取近期运行列表，然后在报告中汇总。

查询特定运行

如需查询特定运行（报告），请阅读 references/run-info.md，然后根据需要继续执行其他工作流。

分诊运行

如果运行状态为“incomplete”，请参阅下文的“诊断未完成的运行”部分。

1. 阅读 references/run-info.md，加载运行信息
2. 如果运行信息输出中的 links.triage_report 为 null 或缺失，则表示此运行未生成分诊报告（cancelled 运行以及某些 unknown/starting 状态通常如此）。请说明该运行无法进行分诊——这些运行的 properties 和 logs 端点会返回 404。
3. 阅读 references/properties.md，加载属性
4. 检查通过/失败数量
5. 检查检测设置的信号——Software was instrumented 和 Symbols were uploaded 属性。阅读 references/instrumentation.md，了解如何解读这些属性。
6. 编写运行的详细摘要，包括审查所有失败项并标出任何新失败项。在摘要中包含检测状态。

调查失败的属性

1. 阅读 references/properties.md，使用 snouty runs --json properties 提取属性及其示例，并了解如何下载日志

2. 阅读 references/logs.md，了解如何理解日志

3. 对于每个要调查的属性： a. 选择第一个失败示例 b. 找到对应时刻。如果反例没有 moment 字段（遥测／元属性——请参阅 references/properties.md），则将反例值作为证据报告，并跳过步骤 c–e。 c. 按照 references/logs.md 中的说明下载该示例的日志 d. 在本地分析下载的日志 e. 如果无法确定问题原因，可考虑下载同一属性其他反例和示例的日志。比较每次出现的情况，尝试找出可能解释失败原因的相似之处或差异。也可以将通过的示例日志作为对照，找出成功与失败情况之间的差异。

   若要查找该属性更多通过或失败的评估结果，请使用 snouty runs --json search。先运行 snouty runs search --help：其中介绍了查询语言，并提供可直接粘贴使用的代码片段，包括按 ID 选择某项断言评估结果的代码片段。ID 是你正在调查的属性数据中的 “name” 字段；将 “condition” 字段与想要查看更多结果的示例或反例匹配。结果是数量受 --limit 限制（默认为 50）的样本，因此显示的只是部分评估结果，不一定包含全部结果。你已有的示例和反例很可能也会出现在其中；请将每条结果的 moment 与你已下载的内容进行比较。

4. 重要： 将日志与被测系统（SUT）的源代码及工作负载交叉参照（如果你可以访问它们）。

5. 深入调查故障，了解导致故障的事件时间线，以及可能造成故障的事件。

6. 报告调查结果。

重要： 仅凭属性状态和断言文本还不够；日志提供了理解故障所需的实际运行时上下文。

跨时间线搜索

下载的日志涵盖一段历史。若要回答涉及运行中所有时间线的问题，例如“事件 A 是否总是先于故障 B？”、“如果没有之前的故障，故障是否仍会发生？”、“哪个容器最先记录了此错误？”，请使用 snouty runs --json search。编写查询前，先运行 snouty runs search --help 了解查询语言。其中介绍了如何按日志文本、容器、断言和 vtime 时间窗口进行筛选，如何组合事件集，以及如何为每个事件标注同一时间线上来自其他集合的最近先前或后续事件。每条结果都包含 moment，因此你可以按照 references/logs.md 中的说明下载导致任意命中结果的日志。

验证插桩

若要验证 SUT 和工作负载是否已插桩，以及它们的符号是否已注册，请阅读 references/instrumentation.md。

诊断未完成的运行

如果某次运行的“status”为“incomplete”，可能有错误日志可供检查。排查“incomplete”状态运行的步骤：

1. 执行 snouty runs --json show ${RUN_ID}
2. 查看返回的 JSON 中的 failure_moment 结构。如果存在，请使用 failure_moment 中的 input_hash 和 vtime，按照 references/logs.md 中的说明下载日志。
3. 尝试获取构建日志，尤其是在没有 failure moment 时，执行 snouty runs --json build-logs ${RUN_ID}，并查找构建中的错误。

关于 links.triage_report 的说明： 对于未完成的运行，针对各属性的 properties 和 logs 端点通常会返回 404，但 links.triage_report 和 failure_moment 仍可能在 show 中有值。请如实报告 show 中实际包含的内容；除非该字段为 null，否则不要声称缺少 triage_report 链接。未完成运行的排查流程是 failure_moment + build-logs，无论是否存在报告 URL。

一般指导

• 得出失败结论前先查看日志。 如果失败的属性包含带有 moment 的示例，请先下载并分析日志，再判定根本原因。有些属性没有示例或日志，此时只能依据状态本身作为证据。
• 如果提供了“details”部分，请考虑其中的信息。 这些是由属性作者整理提供的字段，旨在说明发生失败时系统的状态。
• 清晰呈现结果。 报告属性状态时，请使用表格或列表。报告日志分析结果时，请包含虚拟时间戳、来源、容器和日志文本。
• 在浏览器中打开报告；不要粘贴签名 URL。 用户想查看完整排查报告时，请建议使用 snouty runs show <RUN_ID> --web，而不是输出冗长的 links.triage_report URL。只有存在排查报告时，--web 才可用。请参阅 references/run-info.md。

建议后续技能

在分流摘要末尾添加一个简短的“后续步骤”部分，在适用时列出有帮助的后续技能或其他分流工作流。将这些内容作为建议提供给用户，而不是自动执行的操作——由用户（或其编排流程）决定何时调用。如果用户明确要求串联技能（例如“运行分流，然后调试任何失败的属性”），请遵循其指示并继续执行串联流程。

可根据分流发现的情况建议以下技能：

• antithesis-research — 梳理代码库，找出更适合测试的属性。当失败指向覆盖率存在系统性缺口，而非单个明确的 bug 时，此技能很有用。
• antithesis-workload — 扩展或完善断言、测试命令和日志。所有属性都通过时，应始终建议使用此技能来逐步改进工作负载；如果因工作负载能力不足而无法触达某些属性，也应建议使用此技能。此技能还可用于添加更多日志，或修复属性，以协助根因分析。
• antithesis-debug — 使用 snouty runs exec 在运行失败或更早的时刻执行 shell 命令，以检查容器、进程和磁盘状态。当仅靠日志分析无法解释失败时，此技能很有用。需要 snouty。已完成的运行需要调试会话，该会话会占用核心时长，直到取消为止。
• antithesis-mutation-testing — 为每个属性注入一个符合实际的 bug，并确认相应属性会触发，以证明这些属性确实能够失败。仅在运行结果为绿色（没有失败属性，因此无需优先追查 SUT bug），并且没有迹象表明该目录已进行过变异测试时，才建议此技能——检查 scratchbook 的属性证据文件中是否有 ## Falsification 部分，或是否存在 antithesis/scratchbook/mutation-testing/ 目录。报告全绿时，恰恰无法判断系统是否有完善的防护，还是目录根本不会发现问题。

提供后续技能所需的数据（run_id、属性名称、时刻等），让用户无需重新查找上下文即可调用技能。

自我审查

在宣布此技能已完成之前，请根据以下标准检查你的工作。此技能的输出是对话形式（摘要、表格、分析），因此应在当前上下文中进行审查。重新阅读此文件中的指导，然后逐项对照以下标准，系统检查你给出的答案和分析。

审查标准：

• 所有报告的属性状态（通过、失败、未找到）都来自实际获取的属性数据，而非推断或假设
• 调查结果引用属性数据中的具体信息——属性名称、断言文本、日志行、时间戳
• 对于有可用日志的失败属性，提供可采取行动的上下文：断言文本、相关日志行和时间线背景。当存在日志时，关于失败的结论应以日志证据为依据
• 摘要区分报告所显示的内容与解读或建议
• 比较运行结果时，差异应以两份报告中的数据为依据，而非仅依据其中一份
• 关于二进制文件未插桩的说法，应遵循 references/instrumentation.md，不能仅依据去重后的 Software was instrumented 属性示例