附录：发布 manifest

发布清单#

1.0.0 有两份发布清单约定，适用范围不同：

这两个文件都从记录下来的发布源 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.0.0 只替换与下列 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.0.0",
    "channel": "rc",
    "tag": "v1.0.0"
  },
  "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 参考
• 分发与发布