附錄：發布 manifest

發布清單#

1.1.1 有兩份發布清單約定，適用範圍不同：

這兩個檔案都從記錄下來的發布源 Snapshot 裡讀取。未知欄位會被拒絕，路徑 按儲存庫相對路徑規範化，各項宣告還會拿那個 Snapshot 裡實際存在的檔案來 核對。

通用介面卡：ait-release.json#

{
  "schema": "ait.release.adapter/v1",
  "package": {
    "name": "sample-tool",
    "version": "1.2.0",
    "description": "Portable sample package.",
    "license_files": [
      {"path": "LICENSE", "role": "license"},
      {"path": "NOTICE", "role": "notice"}
    ]
  },
  "components": [
    {
      "id": "cli",
      "ecosystem": "native",
      "working_directory": ".",
      "dependency_files": ["Cargo.toml", "Cargo.lock"],
      "commands": {
        "prepare": [],
        "test": [["cargo", "test", "--locked"]],
        "build": [["cargo", "build", "--release", "--locked"]],
        "smoke": [["target/release/sample-tool", "--version"]]
      },
      "artifacts": [
        {"path": "target/release/sample-tool", "kind": "native-executable"}
      ]
    }
  ]
}

根欄位與 package 欄位#

元件欄位#

命令階段#

每條命令都是 argv 陣列，不是 shell 字串。test 和 build 是必填的， 各自必須含 1 到 16 條命令。prepare 和 smoke 可選，可以含 0 到 16 條 命令。每條命令含 1 到 64 個字串引數；可執行檔案那個引數不能為空。

命令直接執行，不隱式套 shell。1.1.1 只替換與下列 token 之一完全相等的 整個 argv 值：

$AIT_RELEASE_ID
$AIT_RELEASE_VERSION
$AIT_RELEASE_COMPONENT
$AIT_RELEASE_ECOSYSTEM
$AIT_RELEASE_TARGET
$SOURCE_DATE_EPOCH

這些 token 不做子串插值，也不構成任意環境變數展開的許可。argv 值裡出現 換行、回車和 NUL 字元會被拒絕。

產物欄位#

選定的建置必須把宣告的每個產物都產出為確切的普通檔案。選定某個目標時， 會包含匹配該目標的產物；選擇可移植集合時，只包含沒有 target 的產物。

通用上限#

清單大小上限為 1 MiB。識別符號以 ASCII 字母或數字開頭，之後可用字母、數字、 .、_ 或 -。文字欄位是有界的單行字串。相對路徑用 /，不能是絕對 路徑，也不能包含空段、.、.. 段、磁碟機代號字首、冒號或反斜槓。

AIT 家族協調器：ait-release-family.json#

這不是一份通用的多專案清單。約定 ait.release.family/v3 負責協調官方 AIT 原生元件、目標、公開原始碼投影和分發身份。

{
  "schema": "ait.release.family/v3",
  "family": {
    "name": "ait-native",
    "version": "1.1.1",
    "channel": "stable",
    "tag": "v1.1.1"
  },
  "targets": ["aarch64-apple-darwin", "x86_64-unknown-linux-gnu"],
  "public_source": {},
  "components": [],
  "distributions": [],
  "compatibility": {}
}

上面那些空物件和空陣列只是展示根層形狀，它們不是一份有效的發布。真正的 家族清單必須滿足下面所有的關係約束。

家族身份與目標矩陣#

元件#

components 含 1 到 64 個唯一的元件物件。

產物 kind 和 target 組成的二元組，在同一個元件內不得重複。

分發#

distributions 含 1 到 128 條記錄。每個元件都必須被至少一條分發覆蓋到。

public_source#

v3 的公開原始碼物件故意定得很死，因為它產出的是一個可評審的發布 monorepo。

目前的允許清單裡，只有 runner 和 Python 原始碼 subtree 所需的同級 core 路徑 投影。任意改寫原始碼不是這份清單的擴充套件機制。那唯一一條 GitHub product 分發 必須使用同一個公開身份，並覆蓋家族裡的每個元件和每個目標。

相容性對映#

compatibility 是必填物件，最多 64 條。每個 key 是一個識別符號，每個 value 是非空的有界單行字串。它記錄的是針對使用者的相容性事實；它不替代元件 版本、Snapshot 鎖定或目標矩陣。

評審邊界#

• 清單的改動，要和它引用的原始碼及依賴檔案改動記進同一個 Snapshot。
• 更新元件的 source_snapshot 之前，一定要先評審它接納的產物、授權條款、 版本和分發覆蓋情況。
• 生成出來的候選、檢查、建置、凍結、晉級、檢查碼、對映與回執檔案，別放 進這份編寫參考裡。它們是發布輸出，不是額外的使用者設定檔案。
• 用完整的 ait release 命令參考去建立、檢查、建置和檢視發布證據；不要 手寫輸出回執。

相關參考#

• 設定檔案一覽
• 完整 CLI 參考
• 分發與發布