Aigora Bot 協定

0. 開始之前

1. 管理員在後台建立 bot，取得 handle（例如 plm）與一把 token。
2. 管理員把 bot 授權給要用的房間（未授權的房，bot 讀不到也寫不到）。
3. Bot 啟動後：PUT /api/bot/commands 註冊子指令 → 開一條 outbound 連線等事件。

1. 認證

所有 /api/bot/* 端點都要帶：

Authorization: Bearer <bot token>

• 驗不過一律 401。token 被撤銷、bot 被停用、或 token 到期，效果相同。
• Token 是憑證：外洩等同整顆 bot 被接管。管理員可隨時撤銷單一 token。

2. Outbound：取得事件

兩種傳輸共用同一個佇列，選一種就好。同一顆 bot 同時只能有一條 outbound 連線——開第二條會把第一條踢掉。

2.1 序號與游標

每則事件有一個 per-bot 的 seq（從 1 起算、單調遞增、永不重複）。兩種傳輸的游標語意差一，這是最容易寫錯的地方：

⇒ long-poll 收到最後一則 seq=7 之後，下一次要送 ?offset=8；SSE 斷線重連時要送 Last-Event-ID: 7。

2.2 long-poll：GET /api/bot/updates

GET /api/bot/updates?offset=8&timeout=25000
Authorization: Bearer <token>

200

{ "updates": [ { "seq": 8, "type": "command", "payload": "{…}", "createdAt": 1754200000000 } ] }

• 佇列空 ⇒ 伺服器 hold 住連線，有新事件就立刻回；等滿 timeout 則回 {"updates":[]}。
• 🔥 單批上限 100 則。回傳筆數等於 100 就代表還有更多 ⇒ 應立刻用新的 offset 再拉一次，不要進入下一輪 long-poll 等待。
• 下一次的 offset ＝ 這次回應裡最後一則的 seq + 1。

2.3 SSE：GET /api/bot/stream

GET /api/bot/stream
Authorization: Bearer <token>
Last-Event-ID: 7

回應是 text/event-stream。三種輸出：

event: update
id: 8
data: {"seq":8,"type":"command","payload":"{…}","createdAt":1754200000000}

: hb                     ← 心跳，每 15 秒一次，忽略即可

event: auth-invalid
data: {"reason":"token-invalid"}

• 每一則 update 都帶 id: <seq> ⇒ 用標準 EventSource 的話 Last-Event-ID 會自動維護。
• 🔥 auth-invalid 是終止事件、刻意不帶 id:（不污染游標）。收到它代表憑證失效，伺服器接著就會關閉連線。收到後不要自動重連——沒換 token 之前重連只會在握手時拿 401。
• 連線期間伺服器會自動補齊 backlog（超過 100 則也會分批連續推完），你不必自己分頁。

2.4 連線會被伺服器收線的三種情況

2.5 事件保留

• 未取走的事件保留 24 小時，之後由每日清理刪除。
• 「送出成功」不是刪除的理由——只有三條：long-poll 的 offset ack、24 小時 TTL、以及送出前判定「這則已經不能送」（例如那間房的授權在事件入列之後被撤銷了）。
• ⇒ client 處理到一半當掉不會遺失：沒有推進 offset 之前，重連還拿得到同一批。

3. command 事件

目前 type 只有一種：command。payload 是 JSON 字串（要自己 JSON.parse）：

{
  "roomId": "01J…",
  "threadId": null,
  "invocationId": "01J…",
  "actorName": "小明",
  "args": ["show", "123"]
}

4. 註冊指令：PUT /api/bot/commands

整份取代（送什麼就是什麼；送 [] 等於清空）。

[
  { "name": "show",   "description": "顯示一張票", "usage": "/plm show <id>" },
  { "name": "search", "description": "搜尋票",     "usage": "/plm search <關鍵字>" }
]

任一不合 ⇒ 400，訊息會指出第幾項、哪個欄位。

註冊成功後，該 bot 當下有授權的每一間房都會即時收到通知，前端的 / 自動完成立刻更新。使用者打 /plm 就會看到你註冊的子指令與說明。

5. Inbound：回話與查詢

5.1 發言（主欄）

POST /api/bot/rooms/:roomId/messages
{ "content": "票 #123：修好了" }

回傳落庫後的訊息物件，房裡的人即時看得到。

5.2 發言（討論串）

POST /api/bot/threads/:threadId/messages
{ "content": "…" }

⇒ 收到的 command 事件裡 threadId 不是 null 時，就用這條回（回到同一個 scope）。

5.3 開一條新討論串

POST /api/bot/rooms/:roomId/threads
{ "content": "部署失敗了", "title": "2026-08-03 部署" }

• title 可省略（伺服器自動命名）。
• 伺服器會在單一交易內先插一則主欄訊息當 root，再以它開串。
• 回 { thread, messageId }。
• ⚠️ 不接受 rootMessageId（帶了回 409 root-not-accepted）——root 一律由伺服器自己插。

5.4 查詢

5.5 房間解析的錯誤碼

6. 限制一覽

7. 最小可用 client（TypeScript 虛擬碼）

const BASE = 'https://aigora.proty.pe';
const H = { Authorization: `Bearer ${process.env.BOT_TOKEN}` };

// 1) 註冊指令（每次啟動都送一次，整份取代）
await fetch(`${BASE}/api/bot/commands`, {
  method: 'PUT',
  headers: { ...H, 'content-type': 'application/json' },
  body: JSON.stringify([{ name: 'show', description: '顯示一張票', usage: '/plm show <id>' }]),
});

// 2) long-poll 迴圈
let offset = 1;                                   // 有做持久化的話從上次存的接
for (;;) {
  const res = await fetch(`${BASE}/api/bot/updates?offset=${offset}&timeout=25000`, { headers: H });

  if (res.status === 401) { /* 憑證失效：換 token，別急著重試 */ break; }
  if (res.status === 409) { /* 有另一條連線接手了：這條退場 */ break; }
  if (!res.ok) { await sleep(5000); continue; }   // 5xx／網路問題：退避後重試

  const { updates } = await res.json();
  for (const u of updates) {
    const p = JSON.parse(u.payload);              // { roomId, threadId, invocationId, actorName, args }
    await handle(p);                              // ⚠️ 用 invocationId 做冪等
    offset = u.seq + 1;                           // 推進游標＝ack 掉這則
  }
  // 🔥 滿批代表還有更多：立刻再拉，不要等下一輪 long-poll
  if (updates.length === 100) continue;
}

// 3) 回話——回到同一個 scope
async function reply(p, text: string) {
  const url = p.threadId
    ? `${BASE}/api/bot/threads/${p.threadId}/messages`
    : `${BASE}/api/bot/rooms/${p.roomId}/messages`;
  await fetch(url, { method: 'POST', headers: { ...H, 'content-type': 'application/json' },
                     body: JSON.stringify({ content: text }) });
}

8. 容易寫錯的六件事

1. 游標差一：long-poll 的 offset 是「下一則」，SSE 的 Last-Event-ID 是「最後一則」。兩者混用會漏掉或重複收一則。
2. 滿批不代表結束：updates.length === 100 時要立刻再拉，不要進入下一輪等待——否則 backlog 大時每 25 秒才前進 100 則。
3. 只在真的處理完才推進 offset：推進即刪除，中途當掉就拿不回來了。
4. 收到 auth-invalid 不要自動重連：那不是網路問題，是鑰匙失效了。
5. 回錯 scope：threadId 不是 null 時要回討論串端點；打到房間端點會被 409 拒絕（不會靜默寫到主欄）。
6. 用 invocationId 做冪等：重連、重送、以及「處理到一半當掉」都可能讓你看到同一則事件兩次。

9. 已知行為

走 long-poll 的 bot，在兩次 poll 之間的空檔被觸發時，房裡會多出一則「已排入佇列，Bot 連線後即會處理（保留 24 小時）」的系統訊息——即使你的 bot 幾十毫秒後就回來了。這是「觸發當下有沒有連線在等」的字面判定；走 SSE（常駐連線）不會有這個現象。