附录：Patchset CI 配置
定义规范的 1.0.0 Patchset CI 套件目录、支持的 runner、检查项、产物，以及有界的本地定位器。
适用人群： Repository 所有者、CI 维护者与运维
Patchset CI 配置#
ci/patch_ci.json 是 1.0.0 的规范套件目录，在 Repository 向 AIT server 注册时、以及远程就绪要跑 Patchset CI 时使用。目录里至少要有一个阻塞式的 Patchset 关卡。
最小的命令包目录#
{
"schema_version": 1,
"suites": [
{
"schema_version": 1,
"suite_id": "patchset_gate",
"display_name": "Patchset Gate",
"plane": "patchset",
"mode": "gate",
"default_blocking": true,
"purpose": "Validate this repository before remote land.",
"runner": {
"kind": "command_bundle",
"commands": ["./ait.sh test"]
},
"artifacts": {
"log_path": ".ait/generated/ci/patchset_gate.log",
"summary_json": ".ait/generated/ci/patchset_gate.json"
}
}
]
}文件不存在时，ait remote add 会创建一份起步目录，然后停下来，好让你把 占位命令替换掉。它绝不会覆盖已有的目录。占位值 replace-with-your-ci-command 会被拒绝。
目录与套件字段#
| 字段 | 约定 |
|---|---|
schema_version | 顶层整数 1；必填。起步文件也会在每个套件上写一个 1。 |
suites | 套件对象数组。其中至少要有一个具名、可运行的阻塞式 Patchset 关卡。 |
suites[].suite_id | 非空且唯一的操作名。每个被选中的阻塞关卡都必须有。 |
suites[].display_name | 可选的、给人看的字符串。 |
suites[].plane | 用于 Patchset CI 选择时填 patchset。 |
suites[].mode | 用于就绪判定时填 gate。 |
suites[].default_blocking | 布尔值。true 让选中的套件成为就绪证据的一部分；false 仅供参考。 |
suites[].purpose | 可选的说明字符串。 |
suites[].runner | 必填对象，其 kind 必须非空且受支持。 |
suites[].artifacts.log_path | 可选的日志产物相对路径。 |
suites[].artifacts.summary_json | 可选的 JSON 摘要相对路径。 |
只有 plane 和 mode 解析为 patchset 与 gate 的套件才会被编排。用于 首次注册的目录里，至少要有一个这样的套件，并且 default_blocking: true。 不要把未知的 key 当成扩展点来用。
command_bundle runner#
这个 runner 按顺序执行 shell 命令字符串，第一次失败就停。预热命令和主命令 共用同一份接纳的环境。
| Runner 字段 | 类型与行为 |
|---|---|
kind | 确切字符串 command_bundle。 |
commands | 非空数组，元素是非空的 shell 命令字符串。 |
prewarm_commands | 可选数组，在 commands 之前执行。 |
env | 可选对象，把字符串环境值加进干净的 CI 进程环境里。 |
runner_parallelism | 可选的正整数，用作接纳的命令并行度。 |
cpu_tokens | runner_parallelism 的别名。 |
workers | runner_parallelism 的低优先级别名。 |
timeout_seconds | 可选的正数有界超时，对每个进程分别生效。 |
调度器可以给出更严格的接纳并行度。光靠配置本身并不会分到 CPU 容量。完整 日志和有界的 JSON 摘要是两个分开的产物。
test_discovery_sharded runner#
这个 runner 会发现测试用例、构建选中的测试可执行文件，并跑有界的分片。它 支持 Cargo 和一个通用命令适配器。
通用字段#
| Runner 字段 | 类型与行为 |
|---|---|
kind | 确切字符串 test_discovery_sharded。 |
adapter | 默认 cargo；填 command 选用通用适配器。 |
env | 可选的字符串到字符串环境对象。 |
runner_parallelism、cpu_tokens、workers | 正整数并行度的三个名字，优先级依此顺序。 |
timeout_seconds | 可选的正数有界进程超时。 |
exclude_test_cases | 可选数组，列出要略过的确切已发现测试用例名。 |
checks | 可选的测试前检查数组，见下文。 |
Cargo 适配器字段#
| Runner 字段 | 类型与行为 |
|---|---|
cargo_binary | Cargo 可执行文件名或路径；默认 cargo。 |
manifest_path | 规范化的相对路径；默认 Cargo.toml。 |
workspace | 布尔值；默认 true。 |
build_args | 可选的 argv 字符串，用来替换默认的 Cargo 构建参数。 |
doc_tests | 布尔值；默认 false。命令适配器下不接受这个字段。 |
doc_test_args | 可选的 argv 字符串，用于文档测试。 |
命令适配器字段#
| Runner 字段 | 类型与行为 |
|---|---|
discovery_program | 必填，非空的可执行文件名或路径。 |
discovery_args | 可选的发现阶段 argv 数组。 |
discovery_output_format | 默认 json_array，也可以是 lines。 |
run_program | 必填，非空的可执行文件名或路径。 |
run_args | 可选的运行阶段 argv 数组。 |
append_test_items | 布尔值；为 true 时，把发现到的用例名追加到运行 argv 后面。默认 false。 |
working_directory | 工作区内规范化的相对目录；默认是工作区根。该目录必须存在。 |
测试前检查#
checks 的条目接受 check_id、kind、file_name_suffix、exclude_dirs 和 args。缺少 check_id 时会变成 check-N。
kind: "forbid_files"：只要有文件以file_name_suffix结尾、且不在指定 的目录段之内，就判失败。该后缀默认是.py。kind: "cargo_fmt"：跑 Cargo 格式化校验。args可以替换它默认的 argv。
套件运行时，其他种类的 check 会被拒绝。
可选的构建缓存#
runner.build_cache 接受 policy 和 executable_manifest_path。唯一能开启 缓存的 policy 是 reuse_when_rust_inputs_unchanged；不写或写别的值都表示 复用关闭。变更路径的证据由执行请求提供，不应该当成静态目录数据写进去。
可选的本地定位器：ci/config.contract.json#
当 ci/patch_ci.json 不存在时，本地工作流的命令发现可以读取：
{
"schema_version": 1,
"ci": {
"suite_manifest_path": "config/patchset-suites.json"
}
}1.0.0 只读取非空的 ci.suite_manifest_path 值，并且只在被引用的文件确实 存在时才用它。只要 ci/patch_ci.json 在，就总是它说了算。远程 Repository 注册依然会校验并发布那份规范的 ci/patch_ci.json；这个定位器不会改变注册 时的约定。
运维检查#
ait remote add origin https://server.example.invalid --default
ait workflow ready <change-id> --apply
ait task audit <task-id>ait workflow ready 是当前 Patchset 的决策面。本地跑通一条测试命令，替代 不了有远程支撑的 Task 所要求的 server 证据。