antithesis-setup

Antithesis 设置

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

目的和目标

搭建 antithesis/ 测试框架，以便在 Antithesis 中启动系统，并使其处于基本空闲、随时就绪的状态。

成功标准：

• antithesis/config/docker-compose.yaml 存在，且所需的 SUT 镜像通过 build: 指令引用
• 对 antithesis/config/ 运行 snouty validate 成功
• SUT 依赖图包含相关的 Antithesis SDK，用于运行断言或生命周期钩子
• 至少有一个最简引导属性，位于简单的 SUT 路径中，并且预计会出现在首次 Antithesis 运行中
• 测试框架已准备就绪，可供 antithesis-workload 技能添加或迭代测试模板、断言和工作负载代码
• 如果用户要求提交或启动运行，请使用 antithesis-launch 技能——不要直接运行 snouty launch

前提条件

• 必须具备研究产物。 开始前，检查 antithesis/scratchbook/ 是否存在且包含研究输出（至少包括 sut-analysis.md 和 deployment-topology.md）。如果 scratchbook 缺失或为空，请停止并警告用户：

  尚未运行 antithesis-research 技能（未找到 antithesis/scratchbook/）。设置依赖研究产物，尤其是 SUT 分析和部署拓扑，以便针对插桩、镜像结构和服务组合做出明智决策。请先运行 antithesis-research，查看其输出，然后再返回设置。

  没有研究产物时，不要尝试继续。缺少研究提供的上下文会显著降低设置决策的质量。

• 验证研究来源信息。 设置每个项目只运行一次，且会生成耗费大量精力、需要长期保留的产物（Dockerfile、compose、插桩），因此不一致的代价很高。读取 antithesis/scratchbook/sut-analysis.md 和 antithesis/scratchbook/deployment-topology.md 中存在的来源信息 frontmatter。使用你找到的字段——架构可能会随时间演进，因此不要将不完整或较旧的 frontmatter 视为损坏。用通俗语言描述你找到的信息。示例：

  • 完整架构：“此 scratchbook 对应的 SUT 位于 /path/X，提交为 abc12345abcd（2026-05-05），外部引用：A、B。”
  • 部分信息：“目录记录了 commit 和 updated，但没有 sut_path 或 external_references。”
  • 缺失信息：“未记录来源信息；此 scratchbook 创建于该约定出现之前。”
  • 文件间信息不一致：“sut-analysis 对应 /path/A，提交为 abc；deployment-topology 对应 /path/B，提交为 def——两者不一致。”

  然后询问用户：

  这仍然是你要测试的系统吗？

  如果用户回答不是，请勿继续。停止并告知用户重新运行 antithesis-research。基于已确认过时的研究进行设置，会导致脚手架不匹配。

  面向用户显示的提交哈希使用短哈希（前 12 个字符），以便阅读；frontmatter 仍存储完整 SHA。

• 如果未安装 snouty，请勿继续。安装选项请参阅 https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md。

• 如果 snouty 版本低于 0.8.0，请勿继续。使用 snouty --version 查看版本。使用 snouty update 更新。

文档依据

使用 antithesis-documentation 技能访问以下页面。优先使用 snouty docs。

• Docker Compose 设置指南：https://antithesis.com/docs/getting_started/setup_guide/docker_compose.md
• Docker 最佳实践：https://antithesis.com/docs/best_practices/docker_best_practices.md
• 覆盖率插桩：https://antithesis.com/docs/reference/instrumentation/coverage_instrumentation.md
• 断言目录编制：https://antithesis.com/docs/reference/sdk/assertion_cataloging.md
• 处理外部依赖：https://antithesis.com/docs/reference/dependencies.md
• 故障注入：https://antithesis.com/docs/product/fault_injection.md

工作流

此技能分为多个步骤，每个步骤对应一个不同的参考文件。请按顺序阅读并执行下列每个参考文件，完成项目设置。每完成一个步骤后，请检查新学到的内容是否会推翻之前步骤中的决定。开始构建镜像（步骤 3）后，步骤 2 中的插桩决定最常需要调整。

• references/directory-init.md：从 assets/antithesis/ 初始化或合并 antithesis/ 目录
• references/instrumentation.md：决定如何对每个 SUT 服务进行插桩、如何安装 SDK、如何提供符号，以及引导属性的位置
• references/docker-images.md：为 SUT 组件创建或调整 Dockerfile
• references/docker-compose.md：编写 antithesis/config/docker-compose.yaml
• references/config-dir.md：了解 antithesis/config/ 中应包含哪些内容
• references/submit-and-test.md：在本地测试并提交首次运行

通用指南

• 合并现有的 antithesis/ 内容，而不是覆盖它。
• 使用 compose CLI 在本地构建和测试，并检查容器运行时 snouty doctor 的报告。请参阅 references/submit-and-test.md。
• 尽可能将仅供 Antithesis 使用的脚手架放在 antithesis/ 下。
• 此技能应专注于基础设施和准备工作，而不是定义工作负载本身。
• 将相关 Antithesis SDK 安装到 SUT 中，并添加一条最简引导断言，属于设置工作，不应延后为工作负载工作。
• 如果 antithesis/test/ 尚不存在，请创建后续工作负载所需的目录结构，但将实际测试模板和断言留给 antithesis-workload。
• 将插桩和符号化视为引导工作。只有当相关镜像能根据其语言正确提供 /opt/antithesis/catalog/ 或 /symbols/ 时，设置才算完成。
• 首次提交前必须进行本地测试。
• 使用 antithesis-launch 技能提交运行，不要直接运行 snouty launch。如果不存在 antithesis-launch 技能，则直接使用 snouty launch 提交运行。运行 snouty launch 之前，先运行 compose build，确保镜像是最新的。
• 除非部署明确要求，否则不要在 antithesis/config/ 下添加单独的 Dockerfile。
• 禁用每个容器中的颜色和 ANSI 输出。Antithesis 会存储原始字节，且不会渲染转义码，因此彩色输出在日志和问题排查中会变成乱码。通过 docker-compose.yaml 的 environment 块或 Dockerfile ENV 指令，为所有服务设置 NO_COLOR=1。必要时添加工具专用标志（例如 FORCE_COLOR=0）。

自我审查

在宣布此技能已完成之前，请根据以下标准检查你的工作。如果你的 Agent 支持生成子 Agent，请创建一个使用全新上下文的 Agent 来执行此审查——将此技能文件的路径提供给它，并让它读取所有输出产物。使用全新上下文的审查者能发现上下文内审查容易忽略的问题。如果你的 Agent 不支持子 Agent，请自行执行审查：重新阅读此文件顶部的成功标准，然后针对实际输出逐项系统地检查以下内容。

审查标准：

• antithesis/config/docker-compose.yaml 存在，且每项服务都已正确配置 build:（用于本地镜像）或 image:（用于公共镜像）
• docker-compose.yaml 中的每项服务都包含 platform: linux/amd64
• 每项服务都设置了 hostname:，其值与 container_name: 一致，且两者都不包含下划线（请使用连字符——下划线不是有效的 DNS 标签字符）
• 每项服务都设置了 init: true，确保服务进程不以 pid 1 运行
• 服务间依赖使用 depends_on，并针对已定义的 healthcheck 设置 condition: service_healthy，而不是使用普通的 depends_on
• 运行时 compose 不设置自定义 logging: 驱动，不配置任何 internal: true 网络，也不设置 pull_policy:
• references/instrumentation.md 中的检测清单已全部落实：每项服务均已完成检测、仅列入目录，或明确记录为未检测
• 已在被测系统的依赖关系图中安装相关的 Antithesis SDK
• 在简单且保证会执行的代码路径中存在 bootstrap 属性（不得依赖罕见行为）
• 已根据每项服务使用的语言，正确暴露 /opt/antithesis/catalog/ 或 /symbols/
• 至少有一个入口点接入了 setup_complete 信号
• snouty validate 在 antithesis/config/ 上运行成功
• 所有构建的镜像都以 amd64 为目标（通过 snouty 选择的引擎运行 image inspect 验证）
• 构建使用了 compose CLI，且引擎的 snouty doctor 报告正常
• 每项服务的环境中都设置了 NO_COLOR=1（通过 docker-compose.yaml 和／或 Dockerfile），以防止容器输出 ANSI 转义码
• 测试框架已准备好供 antithesis-workload 技能使用——测试模板目录已存在或已配置为供后续使用
• 如果用户要求启动运行，请使用 antithesis-launch 技能，而不是直接运行 snouty launch
• sut-analysis.md 和 deployment-topology.md 中已有的任何研究来源信息，都已向用户说明并在开始搭建脚手架之前获得确认（来源信息 frontmatter 格式定义于 antithesis-research 技能的 references/scratchbook-setup.md）