附錄：外部 Repository 設定
透過三份 1.1.1 TOML 約定宣告、鎖定、物化、繫結並在本地覆蓋外部 Repository。
適用對象： 開發者、整合方與發布工程師
外部 Repository 設定#
1.1.1 把作者意圖、確切解析結果和本地開發覆蓋項，拆成三個 TOML 檔案：
| 檔案 | 權威 |
|---|---|
ait-external.toml | 由 Repository 編寫的直接宣告。 |
ait-external.lock | 解析完成的完整依賴圖，帶確切的 Snapshot 鎖定；由 AIT 生成。 |
ait-external.links.toml | 由 AIT 命令管理的本地路徑覆蓋項。 |
ait-external.toml#
每一條 [[external]] 指明一個直接的外部 Repository，以及它的內容物化到 哪裡。
[[external]]
name = "shared-core"
repo_name = "shared-core"
repository_index = 23
remote = "origin"
line = "main"
snapshot = "SNP-0123456789AB"
materialize_to = ".ait-external/shared-core"
license = "Apache-2.0"
version = "1.2.0"
[external.bindings.rust]
kind = "cargo-path"
path = "rust/crates/shared-core"
package = "shared-core"
[external.bindings.python]
kind = "python-path"
path = "python"
package = "shared-core"
module = "shared_core"宣告欄位#
| 欄位 | 型別與含義 |
|---|---|
name | 必填，非空的本地外部名。它用來標識這條宣告和對應的 link 覆蓋項。 |
repo_name | 必填，非空的源 Repository 名。 |
repository_index | 必填，無符號 32 位的 server Repository 索引。 |
remote | 必填，非空的已設定遠端名，用來解析源。 |
line | 必填，非空的源 Line。 |
snapshot | 必填，非空且確切的源 Snapshot ID。這是鎖定，不只是一個分支提示。 |
materialize_to | 必填，規範化的儲存庫相對目標路徑。絕對路徑和 .. 穿越會被拒絕。 |
license | 必填，非空的已宣告授權條款表示式或標籤。 |
version | 可選，非空的、給人看的版本字串。內容權威仍然是 Snapshot。 |
bindings | 可選對映，每種受支援的語言最多一條繫結。 |
直接名稱必須無歧義。物化路徑和繫結路徑會按儲存庫相對路徑校驗，不能逃出 它們所屬的根目錄。
繫結欄位#
| 表 | 必填欄位 | 可選後設資料 |
|---|---|---|
[external.bindings.rust] | kind = "cargo-path"、path | package |
[external.bindings.python] | kind = "python-path"、path | package、module |
[external.bindings.node] | kind = "file-package"、path | package |
[external.bindings.go] | kind = "replace-path"、path | module |
每個 path 都是相對於該外部 Repository 物化位置的。後設資料只要寫了就必須 非空。繫結校驗還會檢查相應的語言工具和依賴檔案；光是 TOML 形狀合法， 並不能證明這條包繫結真的能用。
ait-external.lock#
不要憑空造這個檔案，也別隨手手改。ait external update 會解析直接和 傳遞的外部依賴、規範化順序、校驗依賴圖，並原子地寫入 lock。
format = "ait.external.lock"
[[node]]
name = "shared-core"
repo_name = "shared-core"
repository_index = 23
remote = "origin"
line = "main"
snapshot = "SNP-0123456789AB"
parent_path = ""
materialize_to = ".ait-external/shared-core"
license = "Apache-2.0"
version = "1.2.0"
[[node.binding]]
language = "rust"
kind = "cargo-path"
path = "rust/crates/shared-core"
package = "shared-core"Lock 欄位#
| 欄位 | 約定 |
|---|---|
format | 確切字串 ait.external.lock。 |
[[node]] | 零個或多個規範化的直接與傳遞依賴圖節點。 |
node.name | 必填非空名稱，與 parent_path 組合後唯一。 |
node.repo_name | 必填，非空的源 Repository 名。 |
node.repository_index | 必填，無符號 32 位的源 Repository 索引。 |
node.remote | 必填，非空的遠端名。 |
node.line | 必填，非空的源 Line。 |
node.snapshot | 必填，非空且確切的 Snapshot ID。 |
node.parent_path | 直接根節點為空；否則是規範化的相對祖先路徑。 |
node.materialize_to | 必填，規範化的相對目標路徑。 |
node.license | 必填，非空的授權條款標籤。 |
node.version | 可選的版本字串。 |
[[node.binding]] | 零個或多個規範化的繫結摘要。 |
node.binding.language | rust、python、node 或 go。 |
node.binding.kind | 該語言允許的確切 kind。 |
node.binding.path | 規範化的相對路徑。 |
node.binding.package | 可選，非空的包名。 |
node.binding.module | 可選，非空的模組名。 |
lock 會拿 ait-external.toml 來比對，查出缺失的、多餘的和欄位漂移的 直接根節點。乾淨的 lock 必須和清單一起提交，這樣每個 worktree 和遠端 建置看到的才是同一張依賴圖。
ait-external.links.toml#
本地 link 讓開發者可以臨時把某個具名外部從一個已有目錄物化出來，而不是 用它鎖定的 Snapshot。
[[link]]
name = "shared-core"
path = "../shared-core"每一條只有 name 和 path 這兩個操作值。name 指向一條外部宣告；path 必須能解析到一個已存在的目錄。用擁有它的那兩條命令：
ait external link shared-core ../shared-core
ait external unlink shared-core最後一條 link 被移除時，AIT 會把這個檔案刪掉。本地 link 屬於開發者覆蓋 項，在鎖定的或可發布的物化過程中會被拒絕。它們從不修改已宣告的 Snapshot 或生成的 lock。
更新與驗證流程#
ait external update
ait external status
ait external doctor
ait diff ait-external.toml ait-external.lock像評審一次依賴升級那樣評審 lock 的改動：在記錄最終的 Snapshot 之前，先 核對 Repository 索引、Line、Snapshot、物化目標、授權條款和繫結漂移。