1.0.0
文档修订 2
附录：环境变量
已安装 1.0.0 环境的规范化 31 条约定，明确写出归属、设置方式、机密性与进程边界行为。
适用人群： 开发者、运维、集成方与发布工程师
这份附录覆盖什么#
这是当前 ait-native 1.0.0 家族（ait、Agent worker、ait-server 和 ait-runner）已安装进程环境的完整约定。它包含 31 个规范化名称或有界 名称族。这些条目来自三份机器可读的运行时注册表，而不是在源码里搜 AIT_ 字样搜出来的。
整份约定就放在这一篇里。每一行都写明：哪个组件拥有这个值、由谁设置、 是不是机密，以及它会改变什么。
- 用户和运维类的值可以放进被拉起的进程环境里。命令若暴露了同样 的选择，明确的命令行选项仍然优先。
- AIT 注入类的值会跨越受管的子进程边界。用户不应该靠设置它们去把 另一个 Task 或 CI 尝试引到别处。
- 自动化类的值只属于指名的、受支持的构建或发布边界。
- 机密应该放进服务或 CI 的密钥库。不要提交、不要打印，也不要留在会被 保存的命令行历史里。
ait-server 和 ait-runner 都不会自动加载项目的 .env 文件。必须由 shell、服务管理器、容器运行时或 Agent 监管进程把配置好的值放进进程环境。
注册表口径#
| 注册表 | 公布的口径 |
|---|---|
ait.environment-contract/v1 | 23 条 ait-core、CLI、Agent 与发布边界条目。 |
ait.server.environment-contract/v1 | 7 条 server 条目。AIT_NATIVE_SERVER_DATA 和 AIT_PERFETTO_TRACE 已经归 core 所有，所以 server 净增 5 个新名称。 |
ait.runner.environment-contract/v1 | 4 条 runner 条目。它的外部仓库名称族里包含了 core 那个具体的 AIT_EXTERNAL_CORE_REPO_ROOT 输入，所以 runner 净增 3 个规范化名称。 |
| 公布总数 | 31 个唯一名称或有界名称族。 runner 那个有界的外部 Repository 名称族里含有 core 的具体诊断成员，所以只算一次。 |
运行时、仓库与身份#
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_NATIVE_ACTOR | ait-core · 用户或运维 · 非机密。 记入本地溯源和远程请求的作者身份。 |
AIT_NATIVE_SERVER_DATA | ait-core 与 ait-server · 运维 · 非机密。 没有传 ait-server --data 时使用的持久 server 权威根目录，server 感知型的 core 操作也会用到。放在持久存储上。 |
AIT_REPO_ROOT | ait-cli · 用户或监管进程 · 非机密。 用于进程发现的显式仓库根。优先正常进入仓库目录；只有调用方无法确定工作目录时才用它。 |
AIT_RUNTIME_DATA | ait-core · 运维 · 非机密。 本地诊断、Snapshot 元数据、status 缓存和 server 感知型操作共用的运行时数据根目录。 |
AIT_SERVER_TOKEN | ait-runner · 运维 · 机密。 runner 发往配置好的 ait-server 端点的可选 bearer 凭据。server URL 和 worker 身份仍然是 runner 的显式命令行选项。 |
Agent worker 与集成凭据#
Agent worker 先选定一份带类型的 worker 清单。下面这些环境值提供有界的 worker 引导参数和凭据——这些东西不适合直接放进普通的仓库内容里。
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_AGENT_CONFIG_PATH | ait-agent-worker · 用户或监管进程 · 非机密。 带类型的 Agent worker 清单路径。普通仓库的默认值是 .ait/agent-workers.json。 |
AIT_DISCORD_APPLICATION_ID | ait-agent-worker · 运维 · 非机密。 所选 worker 的 Discord 应用身份。 |
AIT_DISCORD_BOT_TOKEN | ait-agent-worker · 运维 · 机密。 所选 worker 的 Discord bot 凭据。 |
AIT_DISCORD_PUBLIC_KEY | ait-agent-worker · 运维 · 非机密。 用于校验 interaction 请求的 Discord 公钥。 |
AIT_LINE_CHANNEL_ACCESS_TOKEN | ait-agent-worker · 运维 · 机密。 所选 worker 的 LINE channel access 凭据。 |
AIT_LINE_CHANNEL_SECRET | ait-agent-worker · 运维 · 机密。 所选 worker 的 LINE 请求校验密钥。 |
AIT_OPENAI_API_KEY | ait-agent-worker · 运维 · 机密。 当所选 worker 走 OpenAI 边界时，提供给它的 OpenAI 凭据。 |
AIT_SLACK_APP_TOKEN | ait-agent-worker · 运维 · 机密。 所选 worker 的 Slack app 级凭据。 |
AIT_SLACK_SIGNING_SECRET | ait-agent-worker · 运维 · 机密。 Slack 请求签名校验密钥。 |
AIT_TELEGRAM_BOT_TOKEN | ait-agent-worker · 运维 · 机密。 所选 worker 的 Telegram bot 凭据。 |
AIT_TELEGRAM_OPENAI_API_KEY | ait-agent-worker · 运维 · 机密。 当该 worker 用单独的 key 时，Telegram 专用的 OpenAI 凭据。 |
AIT_TELEGRAM_WEBHOOK_SECRET | ait-agent-worker · 运维 · 机密。 Telegram webhook 校验密钥。 |
server CI 内存接纳#
这三个变量只属于 server 持有的 CI 接纳环节。Task worktree 的 RAM 放置 属于仓库配置，在 task_worktree.memory_root 下面，不是进程环境配置。 它带类型的字段、macOS 上 8 GiB 的默认值、只读诊断和回落到持久磁盘的 规则，都写在 并行 Task 隔离。
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_NATIVE_SERVER_CI_RAM_MIN_AVAILABLE_BYTES | ait-server · 运维 · 非机密。 可选的确切空闲字节下限，在把 server CI 接纳到已验证的 RAM 根目录时生效。不设置就只做挂载校验，不额外加下限。 |
AIT_NATIVE_SERVER_CI_RAM_RECLAIM_TARGET_BYTES | ait-server · 运维 · 非机密。 可选的回收后空闲字节目标值。生效目标永远不会低于接纳下限。 |
AIT_NATIVE_SERVER_CI_RAM_ROOT | ait-server · 运维 · 非机密。 用于隔离 server CI 作业的绝对路径、经过校验的内存宿主根目录。它必须位于持久 server 权威之外。 |
存储与远程操作调优#
这些是高级的有界控制项。取值非法时会走写明的回落值，或者在拥有它的 边界上校验失败；它们不会改写已经存下来的对象。
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_OBJECT_PACK_CHUNK_MIB | ait-server · 运维 · 非机密。 object pack 写入分块大小，单位 MiB，取正数。不设置、非法或为零时用 8 MiB。 |
AIT_REMOTE_MUTATION_RESPONSE_DEADLINE_SECONDS | ait-core · 运维 · 非机密。 远程变更的响应截止时间。普通变更默认 10 秒，Task Land 默认 30 秒；取值小于等于零时，仅关闭这一项响应截止时间。 |
AIT_REMOTE_MUTATION_SETTLE_POLL_SECONDS | ait-core · 运维 · 非机密。 远程变更之后的对账轮询间隔。默认 0.25 秒。 |
AIT_REMOTE_MUTATION_SETTLE_WINDOW_SECONDS | ait-core · 运维 · 非机密。 变更之后的对账窗口。默认 5 秒。 |
AIT_TREE_PACK_CHUNK_MIB | ait-server · 运维 · 非机密。 Tree pack 写入分块大小，单位 MiB，取正数。不设置、非法或为零时用 8 MiB。 |
受管进程边界#
下面这些值在子进程里能看到，但不是普通配置项。AIT 会用当前操作确切的 路径或归属令牌把它们覆盖掉。
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_EXTERNAL_<NAME>_REPO_ROOT | ait-runner 与 ait-core · AIT 注入名称族 · 非机密。 runner 创建的、指向某个已锁定外部仓库的路径。<NAME> 是非空的规范化大写 ASCII，可含数字或下划线；core 的诊断用的是具体的 AIT_EXTERNAL_CORE_REPO_ROOT 成员。 |
AIT_RUNNER_ATTEMPT_ROOT | ait-runner · AIT 注入 · 非机密。 当前这次执行尝试的确切 runner 私有根目录。runner 的父级位置用 --attempt-root 选定；环境里现成的值无法把子尝试引到别处。 |
AIT_RUNNER_WORKSPACE | ait-runner · AIT 注入 · 非机密。 当前这次执行物化出来的确切工作区。 |
AIT_WORKSPACE_LOCK_OWNER_TOKEN | ait-cli · AIT 注入 · 机密。 只传给共用当前工作区锁、且已通过校验的嵌套命令的不透明令牌。不要自己造，也不要打日志。 |
诊断与发布边界自动化#
| 名称 | 归属、设置方、是否机密及行为 |
|---|---|
AIT_PERFETTO_TRACE | ait-core 与 ait-server · 用户或运维 · 非机密。 在开启 tracing 的进程中，选择性采集 Perfetto trace 的非空输出路径。 |
AIT_SHARED_CARGO_TARGET_DIR | ait-release · 自动化 · 非机密。 受支持的原生发布冒烟边界所用的显式共享 Cargo target 目录。它不是通用的运行时存储选择器。 |
哪些是有意排除的#
发布清单里的占位符是由发布适配器解析的 argv 模板 token，不是环境输入。 工作流里局部的 CI env: 别名、测试夹具、故障注入开关、生成的 ID、报告 标签，以及只归仓库构建或部署脚本所有的值，同样不在已安装运行时约定的 范围内。这些东西应该在拥有它们的工作流或脚本旁边说明，而不是摆出来当 成用户必须理解的设置项。
这条范围规则让这份附录保持完整，又不至于把源码里每一个 token 都变成 对外的配置承诺。