附录：.ait/config.json

约定与权威#

.ait/config.json 是 1.0.0 里权威的、持久化的 Repository 配置。它保存 仓库身份与路由、工作流默认值、远程注册信息、Task worktree 放置位置，以及 一小组由 AIT 托管的运行时提示。这一页把当前支持的每个字段和嵌套字段都 列全。

有三个 JSON 面是相关的，但彼此不能互换：

JSON 读取器在改写某个设置时，可能会把不认识的 key 原样保留下来。保留并 不等于支持。别把任意 key 当成扩展点。

安全的修改边界#

只要 1.0.0 提供了拥有某个值的那条命令，就用那条命令：

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.0.0 文件。

完整的 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 隔离
• 远程基础设施
• 附录：环境变量