ait-agent-worker：消息与应答运行时
通过它经过验证的命令面、四种传输、Codex 应答提供方、运行时准入和安全边界，运维可选的原生消息 worker。
适用人群： Agent 运维、集成维护者与 Repository 所有者
在 ait-native 里的角色#
ait-agent 和 ait-agent-worker 是同一份 ait-core 源码权威里出来 的两个独立发布组件。ait-agent 管 worker 的配置和进程； ait-agent-worker 是不依赖 Python 的原生传输与回复执行运行时，服务 Telegram、LINE、Discord 和 Slack。
日常用 ait CLI 不需要这个 worker，它也不是另一个桌面或移动端的 coding client。交互式的编写体验，仍然由主 coding client 负责。 ait-agent-worker 从一个明确配置好的传输收下消息，把它绑到一个 Repository 上下文，拿到一份有界的回复，再顺着同一个传输送回去。
worker 不会自动去建 sprint card、开 Task、创建 Snapshot 或者 Land 一个 Change。只有当回复 provider 或者别的获授权客户端明确跑了对应的 ait 命令时，这些工作流变更才会发生。
适合拿来做什么#
- 在一个 AIT Repository 上跑一个具名的消息机器人，还不用装 Python worker 运行时。
- 通过为某个服务实现的那种传输模式，接 Telegram、LINE、Discord 或 Slack 的请求，返回带 Repository 上下文的回复。
- 把一个原生的无界面 worker 放在受信任的服务守护进程或 HTTP 适配层 后面。
- 在把某个安装好的可执行文件放进生产之前，查清它编译进去的确切传输、 事件循环、平台和回退能力。
- 用 worker 自带的原生 Codex 回复 provider，或者为受控集成明确指定 一个自定义的本地回复程序。
远程 Repository 权威、异地保存、恢复、Patchset CI 和 runner 的 job 协调，这些该用 ait-server，不是 ait-agent-worker。worker 可以 解析出本地或远程的 Repository 目标，但它不是服务端的管理 API。
从消息到回复的执行路径#
- 进程先解析出 Repository 根目录、
.ait/config.json和 worker 清单。AIT_AGENT_CONFIG_PATH可以指向另一个清单路径。 - 清单被规范化，然后选中确切的
<kind>/<name>worker。字段非法、 worker 不存在、kind 和 name 对不上，都会在传输启动前就失败。 - 解析凭据和运行时设置。生效的工作流模式决定了 Repository 目标是 本地的，还是走它配置好的默认 remote。
- 请求的原生事件循环后端和从零开始编号的分片，会拿去和运行时准入 计划核对。后端或分片对不上就直接失败。
- 传输完成认证或核验它自己那套入站校验，解析出确切的请求，套用 会话状态和去重状态，然后提交一个有界的回复 job。
- 配置好的本地回复程序开跑。没有提供完整的自定义 provider 时， 原生 worker 会把自己的
reply-provider子命令装成 provider，用 选定的模型、推理强度、沙箱和超时去调 Codex。 - 传输把回复发出去或返回。失败走结构化的原生诊断，不会回退到 Python worker。
worker 的同步状态和 Codex 线程绑定，把传输侧的会话身份跟 AIT 的 工作流权威分了开。恢复一段会话可以复用它兼容的 Codex 线程，而 Task、Change、Snapshot 和 Land 的状态仍然归 AIT 所有。
可执行文件的完整命令面#
| 命令 | 作用、输入和结果 |
|---|---|
capabilities | 报出安装的平台、架构、socket 与进程控制后端、支持的传输、事件循环后端、默认后端，以及 Python 回退状态。默认输出文本；--json 输出 ait.agent.worker.capabilities.v1。 |
run | 在配置规范化和运行时准入之后，跑起一个确切的具名 worker。它要求传输、worker 名、事件循环后端和分片。服务模式是长期运行的。Telegram 还允许通过 console 模式收下一次 stdin webhook 事务。 |
slack-command | 执行一次签名过的 Slack 斜杠命令事务。它从 stdin 读取确切的表单 body，核验受信任 HTTP 边界传进来的请求元数据，然后写出一份脱敏的 JSON 结果。 |
discord-interaction | 执行一次签名过的 Discord interaction 事务。它从 stdin 读取确切的 JSON body，核验受信任 HTTP 边界传进来的请求元数据，然后写出 Discord 的响应对象。 |
reply-provider | 执行一次带版本的原生 Codex 回复 provider 请求。它从 stdin 读 JSON，写出 ait.agent.gateway_reply_provider_response.v1 JSON。 |
1.0.0 的确切写法：
ait-agent-worker capabilities [--json]
ait-agent-worker run \
--transport <telegram|discord|slack|line> \
--worker <name> \
--event-loop-backend <backend-reported-by-capabilities> \
--shard <zero-based-index> \
[--console-mode <service|webhook>]
ait-agent-worker slack-command [--worker <name>] \
--signature <signature> --signature-timestamp <unix-seconds> < exact-slack-body
ait-agent-worker discord-interaction [--worker <name>] \
--signature <signature> --signature-timestamp <timestamp> < exact-discord-body
ait-agent-worker reply-provider < provider-request.jsonrun 的 console 模式默认是 service。只有在 stdin 上喂一次 Telegram webhook 载荷时才用 webhook。Slack 和 Discord 那两个一次性 命令是适配层边界，不是不认证的网络监听器：调用方必须原样保住那份 raw body，并通过受信任的请求边界把匹配的签名和时间戳元数据一起传 进来。
启动之前，把两种形式的能力证据都记下来：
ait-agent-worker --version
ait-agent-worker capabilities
ait-agent-worker capabilities --json别光凭操作系统名字去猜后端或传输。以安装好的二进制报出来的能力结果 为准，再把启动规划选定的后端和分片传给 run。
各个传输的行为#
| 传输 | 长期运行的服务 | 有界的单次请求模式 | 认证与投递边界 |
|---|---|---|---|
| Telegram | 轮询，或者配置成 webhook 服务。 | run --console-mode webhook 从 stdin 消费一次 webhook 载荷。 | Bot token 是必须的。webhook 模式可以要求配置好的 webhook 密钥。回复支持消息合并、Markdown、解耦投递，以及可选的本地语音转文字设置。 |
| LINE | 在配置的 host、端口和路径上跑 HTTP 回调服务。 | 没有单独的公开一次性子命令。 | Channel secret 用来验回调签名；channel access token 负责通过配置的 LINE API base URL 投递回复。 |
| Discord | 选定模式具备所需 bot 凭据时，跑 Gateway 服务。 | discord-interaction 处理一次签名过的 interaction body。 | 应用身份决定选中哪个 worker。选定的 interaction 或 gateway 模式会要求公钥校验和 bot 投递凭据。 |
| Slack | 选定的 worker 有 app token 时，走 Socket Mode。 | slack-command 处理一次签名过的斜杠命令表单 body。 | 签名密钥用来验 HTTP 命令。Socket 模式和 HTTP 模式各用各自需要的凭据；延迟投递的命令响应受这次命令事务的边界约束。 |
所有监听器默认都绑在 loopback 地址上。要把 HTTP 监听器放到受信任的 反向代理后面，得先拿确切选定的那个传输，把请求校验、TLS、body 大小、 超时和转发行为都测过再说。
原生 Codex 回复 provider#
传输 worker 需要一个回复 provider；它们自己不带第二个编码模型。配置 里给了完整的 local_reply.program 加 local_reply.args，那就以它 为准。否则原生可执行文件就跑自己的 reply-provider 子命令，把自己 配成 provider。
原生 provider 接收带版本的 ait.agent.gateway_reply_provider_request.v1 JSON 契约。请求里绑定 了一个 Repository 根目录、会话 key、surface、actor、输入载荷、可选的 上一个 provider 线程，以及回复设置。它为那个兼容的 Repository 和会话 启动或恢复一个 Codex 线程，抓取最终回复和有界的这一轮遥测数据， 再返回带版本的响应契约。
provider 会强制约束请求和进程输出的大小上限、一把线程锁、配置好的 超时，以及 read-only、workspace-write、danger-full-access 三个 沙箱取值之一。选哪个沙箱就是执行边界。它必须和这个 worker 在那个 Repository 里被允许做的事对得上；传输凭据不会额外给出文件系统权限 或者 AIT 权威。
准入、并发与关停#
run 从不随便挑一个分片。它会规范化整份 worker 清单，把配置好的 worker 集合按选定的原生事件循环后端排一遍计划，再核对请求的那个 worker 确实属于传进来的分片。Telegram 还能额外限定预期的并发 worker 数和每个分片的 worker 数。
传输的回复工作走的是有界的原生 job 准入。容量满了，worker 会直接 报失败，而不是攒出没有上限的后台工作。服务在把已准入的工作排干之前， 会先停止接新 job；进程控制的具体行为，就是 capabilities 报出来的 那个原生后端。
失败与安全契约#
运行期的失败以 ait.agent.worker.error.v1 JSON 的形式写到 stderr。 这份诊断里包含一个稳定的 code、消息、数字退出码、有界的细节，还有 python_worker_execution_allowed: false。
| 退出码 | 含义 |
|---|---|
2 | 请求非法，包括输入格式不对，或者签名入站被拒。 |
3 | worker、清单、凭据、后端或分片配置非法。 |
4 | 必需的原生运行时、传输、进程或输出边界不可用。 |
诊断只报凭据在不在，不报具体值。Slack 和 Discord 校验的是确切的 raw body。一次性命令的结果会把密钥和投递定位信息脱敏。1.0.0 的传输、 签名、回复和状态相关工作，Python 回退一律关闭。
有意划下的界限#
ait-agent-worker不是通用的桌面、移动或 Web 应用。- 它不是持久的远程权威，也替代不了
ait-server。 - 收到一条消息，本身不会创建或完成任何 AIT 工作流对象。
- 一个传输 worker，每次进程调用只对应一个解析出来的 Repository 和 一个选中的具名 worker。
- 这些公开命令不会绕过传输签名、清单校验、运行时准入、Codex 沙箱 或者 AIT 的工作流策略。
配置索引#
- 附录：Agent-worker 配置 展开讲
.ait/agent-workers.json、凭据优先级、每个传输字段、本地 回复设置、运行时路径和核验方法。 - 附录：环境变量 列出受支持的 worker 引导和凭据类环境输入。
- ait-server：远程权威与恢复 讲清楚另一套远程权威、保存和恢复的边界。