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.1.1 的確切寫法：
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.1.1 的傳輸、 簽名、回覆和狀態相關工作，Python 回退一律關閉。
有意劃下的界限#
ait-agent-worker不是通用的桌面、移動或 Web 應用。- 它不是持久的遠端權威，也替代不了
ait-server。 - 收到一條訊息，本身不會建立或完成任何 AIT 工作流程物件。
- 一個傳輸 worker，每次程序呼叫只對應一個解析出來的 Repository 和 一個選中的具名 worker。
- 這些公開命令不會繞過傳輸簽名、清單校驗、執行時準入、Codex 沙箱 或者 AIT 的工作流程策略。
設定索引#
- 附錄：Agent-worker 設定 展開講
.ait/agent-workers.json、憑據優先順序、每個傳輸欄位、本地 回覆設定、執行時路徑和核驗方法。 - 附錄：環境變數 列出受支援的 worker 引導和憑據類環境輸入。
- ait-server：遠端權威與恢復 講清楚另一套遠端權威、儲存和恢復的邊界。