附錄：Patchset CI 設定
定義規範的 1.1.1 Patchset CI 套件目錄、支援的 runner、檢查項、產物，以及有界的本地定位器。
適用對象： Repository 所有者、CI 維護者與維運
Patchset CI 設定#
ci/patch_ci.json 是 1.1.1 的規範套件目錄，在 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.1.1 只讀取非空的 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 證據。