附錄：.ait/config.json

約定與權威#

.ait/config.json 是 1.1.1 裡權威的、持久化的 Repository 設定。它儲存 儲存庫身份與路由、工作流程預設值、遠端註冊資訊、Task worktree 放置位置，以及 一小組由 AIT 託管的執行時提示。這一頁把目前支援的每個欄位和巢狀欄位都 列全。

有三個 JSON 面是相關的，但彼此不能互換：

JSON 讀取器在改寫某個設定時，可能會把不認識的 key 原樣保留下來。保留並 不等於支援。別把任意 key 當成擴充套件點。

安全的修改邊界#

只要 1.1.1 提供了擁有某個值的那條命令，就用那條命令：

ait config show --json
ait config set --workflow-mode solo_remote
ait config set --id-namespace-prefix W
ait config unset task-worktree-main-seed-ram-max-bytes
ait remote add origin https://server.example.invalid --default
ait doctor memory-root --json

ait config set 接受十項使用者持有的設定，ait config unset 接受八項可選 覆蓋項。儲存庫索引、Line 選擇器、遠端記錄、推匯出來的作用域、Plan 繫結的 內部細節、worktree 疊加層和等待提示，都不能透過 ait config set 寫。讓 擁有它們的那條 AIT 生命週期去寫。

如果確實要維護某個只能改檔案的高階值，就先停掉併發的 AIT 變更，留一份 可信副本，原子地寫入合法 JSON，驗證結果之後再繼續幹活。絕對不要照抄別的 Repository 的 repository_index、遠端對映或 worktree 疊加層。

有代表性的根檔案#

這份中性樣例只是展示常見形狀；它不是恢復用的模板。server 分配的索引、 遠端後設資料、各種路徑和身份，都必須來自這個 Repository 自己的生命週期。

{
  "repo_name": "sample-project",
  "default_line": "main",
  "current_line": "main",
  "default_remote": "origin",
  "repository_index": 42,
  "remotes": {
    "origin": {
      "remote_id": 1,
      "url": "https://server.example.invalid",
      "repo_name": "sample-project",
      "created_at": "2026-08-17T08:00:00Z"
    }
  },
  "id_namespace_prefix": "W",
  "policy_profile": "prototype",
  "default_author_mode": "ai_with_human_review",
  "workflow_mode": "solo_remote",
  "workflow_default_scope": "remote",
  "task_default_scope": "remote",
  "change_default_scope": "remote",
  "sprint": "on",
  "plan_task_binding": { "mode": "required" },
  "task_worktree": {
    "alias_root": ".ait-worktree-links",
    "main_seed_ram_max_bytes": 8589934592
  }
}

全新初始化#

ait init 會建立 repo_name、default_line、current_line、一個為 null 的 default_remote、一個空的 id_namespace_prefix、policy_profile、 default_author_mode、sprint 和 plan_task_binding。在受支援的宿主上， 它還能記錄檢測到的 task_worktree.memory_root。可選的預設模型之後用 ait config set --default-model <model> 設定。

預設 Line 是 main。沒有明確給出 Repository 名時，用規範根目錄的目錄名。 全新的策略檔位是 prototype、team 或 release 之一；它必須和 .ait/policy.yaml 一致。

儲存庫身份與 Line 選擇#

策略、溯源與本地評審人預設值#

生效的 actor 也可能來自 AIT_NATIVE_ACTOR。所以 ait config show --json 顯示出來的生效值，可能和存下來的身份欄位不一樣。

工作流程預設的聯動#

設整套預設，別單獨去改它下面那些從屬欄位：

ait config set --workflow-mode <value> 會寫 workflow_mode 和那三個作用域 欄位。除非同一條命令裡帶了 --sprint off，否則它還會寫 sprint: "on" 和 plan_task_binding.mode: "required"。

改這些預設值，不會搬動或改寫已有的 Task、Change、Plan 繫結或 worktree。 已經開始的工作，按它開始時記錄下來的那份約定走完。

遠端對映#

remotes 是一個以本地遠端名為 key 的物件。它的公開寫入方是 ait remote add。

遠端 URL 可能暴露內網拓撲。它是路由資料，不是憑據。認證 token 屬於程序的 機密邊界，不該放在這個檔案裡。

task_worktree 物件與 AIT_RAM#

記憶體放置是在建立新的 Task worktree 時評估的。嚴格大於所設定 main seed 上限 的 Snapshot，會走 Repository 內部的持久儲存。除此之外，AIT 能用就用經過 校驗的受支援 RAM 根，用不了就回落到 Repository 內部的持久儲存。完整的 隔離、容量和恢復行為見 並行 Task 隔離。

由 AIT 託管的執行欄位#

這些等待值只是給使用者反饋用的提示，不是就緒、策略或超時方面的權威。刪掉 或改掉它們，並不會讓某個操作完成。

已有檔案裡的相容欄位#

這些欄位可以留在升級過來的儲存庫裡。這裡寫出來是為了讓備份或審計看得懂； 別把它們加進全新的 1.1.1 檔案。

完整的 worktree 疊加層#

AIT 會在受管 worktree 裡建立 .ait-worktree.json，並把其中每個非 null 的 值疊加到根設定之上，只對那個 worktree 生效。Task worktree 會用到下面這些 欄位：

這個疊加層是歸屬後設資料，不是可搬運的使用者畫像。別複製它、別編輯它，也別 把受管的 .ait 連結換成另一個權威。

驗證、備份與恢復#

做完一次受支援的改動之後，把生效投影和相關子系統都驗一遍：

ait config show --json
ait remote list --json
ait status --json
ait doctor memory-root --json

備份整個 .ait 權威，不要只備份 config.json。這個檔案裡有 server 分配 的儲存庫索引和遠端路由，把本地權威重新接回已有的異地副本要靠它們。分享 診斷資訊之前，先把 server URL、本地路徑、姓名和郵箱地址脫敏掉。這個檔案 裡不應該出現密碼、bearer token 或整合用的機密。

萬一本地權威丟了，別指望對著一個同名的已有 server Repository 跑 ait remote add 就能重新掛上。作為已儲存本地權威的一部分，先恢復可信的 repository_index、default_remote 和 remotes 路由資料，用 ait config show --json 和 ait repo show --remote origin --json 驗證， 然後先預覽 ait remote recover-head --remote origin，再考慮加 --apply。如果確切的已儲存路由恢復不了，就停下來，別去造一個替代權威。

相關#

• 設定檔案一覽
• ait config
• 完整的 `ait config` 命令參考
• 並行 Task 隔離
• 遠端基礎設施
• 附錄：環境變數