Serve 協定

discli serve 透過 stdin 與 stdout 實作雙向通訊協定，資料格式為 逐行 JSON（JSONL）。每一行都是獨立 JSON 物件。事件從 stdout 輸出；動作從 stdin 輸入。

flowchart LR
    subgraph Agent Process
        A[AI Agent / Script]
    end
    subgraph discli serve
        B[Event Handlers] --> C[stdout]
        D[stdin] --> E[Action Dispatcher]
    end
    subgraph Discord
        F[Discord Gateway]
    end

    F -- events --> B
    C -- JSONL events --> A
    A -- JSONL actions --> D
    E -- API calls --> F

協定基礎

• 傳輸： stdin（動作）與 stdout（事件），每行一個 JSON 物件
• 編碼： UTF-8
• 分隔： 換行字元（\n），每行為完整 JSON 物件
• 方向： stdout 為伺服器到用戶端（事件），stdin 為用戶端到伺服器（動作）
• 關聯識別： 動作可包含 req_id；對應回應會回寫同一值

事件（stdout）

事件由 discli 在 Discord 發生對應狀態時發出。每個事件物件都會有 "event" 欄位標示類型。

生命週期事件

訊息事件

互動事件

語音事件

連線事件

表情事件

成員事件

回應事件

每個透過 stdin 發出的動作都會在 stdout 產生回應：

事件範例

{
  "event": "message",
  "server": "My Server",
  "server_id": "111111111111111111",
  "channel": "general",
  "channel_id": "222222222222222222",
  "author": "Alice#1234",
  "author_id": "333333333333333333",
  "is_bot": false,
  "content": "Hello bot!",
  "timestamp": "2026-03-15T10:30:00+00:00",
  "message_id": "444444444444444444",
  "mentions_bot": true,
  "is_dm": false,
  "attachments": [],
  "reply_to": null
}

{
  "event": "slash_command",
  "command": "ask",
  "args": {"question": "什麼是 discli？"},
  "channel_id": "222222222222222222",
  "user": "Alice#1234",
  "user_id": "333333333333333333",
  "guild_id": "111111111111111111",
  "interaction_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "is_admin": false
}

{
  "event": "response",
  "req_id": "msg-001",
  "ok": true,
  "message_id": "555555555555555555"
}

動作（stdin）

動作是 JSON 物件，透過 stdin 送入 discli。每個動作都必須有 "action" 欄位。可選擇加入 "req_id" 以對應回應。

{"action": "send", "channel_id": "222222222222222222", "content": "Hello!", "req_id": "msg-001"}

訊息操作

串流回應

串流可逐步更新同一則訊息，類似 ChatGPT 的回應方式。內容先暫存，並每 1.5 秒一次批次送到 Discord，以符合速率限制。

串流範例

{"action": "stream_start", "channel_id": "222222222222222222", "req_id": "s1"}

{"event": "response", "req_id": "s1", "stream_id": "a1b2c3d4", "message_id": "555555555555555555"}

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "以下是"}

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "您的問題回覆..."}

{"action": "stream_end", "stream_id": "a1b2c3d4", "req_id": "s1-end"}

互動操作

輸入指示

狀態更新

status 可為 online、idle、dnd、invisible。activity_type 可為 playing、watching、listening、competing。

表情操作

討論串

投票

answers 是字串陣列，或含 text 且可選 emoji 欄位的物件陣列。最少需提供 2 個答案。

頻道

成員

身分組

私訊

訊息查詢

表情（延伸）

Webhook

排程事件

伺服器

請求/回應關聯

每個動作可帶 req_id（任意字串）。回應會回填相同 ID，可在並行情境下對齊請求與回應。

{"action": "send", "channel_id": "123", "content": "Hello", "req_id": "abc-001"}

{"event": "response", "req_id": "abc-001", "ok": true, "message_id": "456"}

錯誤處理

動作失敗時，回應改以 "error" 取代 "ok"：

{"event": "response", "req_id": "abc-002", "error": "Channel not found: 999"}

常見錯誤原因：

非致命錯誤（例如 slash command 同步失敗）會以獨立 error 事件輸出：

{"event": "error", "message": "Failed to sync commands to My Server: ..."}

事件篩選

可用指令參數篩選要轉送的事件：

# 僅轉送訊息與反應事件
discli serve --events messages,reactions

# 僅來自特定伺服器
discli serve --server "My Server"

# 僅來自特定頻道
discli serve --channel "#general"

# 不包含機器人自己的訊息
discli serve --no-include-self

可用事件過濾值：messages, reactions, members, edits, deletes, voice, interactions。

Slash 指令註冊

於啟動時可傳入 JSON 檔註冊 slash 指令：

discli serve --slash-commands commands.json

[
  {
    "name": "ask",
    "description": "向機器人提問",
    "params": [
      {"name": "question", "type": "string", "required": true, "description": "你的問題"}
    ]
  },
  {
    "name": "status",
    "description": "檢查機器人狀態"
  }
]

指令會逐伺服器同步以提供即時可用性。使用者觸發 slash command 時，會收到 slash_command 事件，內含 interaction_token，供回應使用。

後續步驟