邊界情境

這些問題發生頻率較低，通常只在特定場景出現。若你遇到不在 常見問題 的情況，可先從這裡查找。

大型伺服器成員清單

症狀： discli member list 對 1000+ 成員伺服器只回傳部分成員。

原因： Discord 要求有 Server Members Intent（受保護 Intents）才能完整抓取成員；沒有時只會回傳快取或線上成員。

修正方式：

1. 在開發者主控台的 Bot > Privileged Gateway Intents 啟用 Server Members Intent。
2. 大型伺服器（10,000+）會分頁回傳。discli 有自動分頁邏輯，但請求仍可能需要數秒。

互動 token 過期

症狀： 回應 Slash 指令時得到 Invalid Webhook Token 或 Interaction token expired。

原因： Discord 互動 token 在指令叫用後 15 分鐘 後失效；若處理過久未回應，token 會變為無效。

修正方式：

• 先立即回應：3 秒內送出延遲回覆，再以實際結果回填
• 縮短主流程時間：若 AI 花太久，先 defer，後續再更新回應

{"action": "interaction_defer", "interaction_id": "1234567890"}

再於 15 分鐘內跟進：

{"action": "interaction_followup", "interaction_id": "1234567890", "content": "Here's your answer..."}

Slash 指令同步延遲

症狀： 已註冊新指令但 Discord 命令選單仍未顯示。

原因： 全域 Slash 指令可能要最多 1 小時 才會傳播；伺服器內同步會立即生效。

**修正方式：**開發階段建議只用伺服器同步：

# 立即生效：伺服器同步
discli slash register --guild 1234567890 --name mycommand --description "Test command"

# 緩慢：全域同步（最多 1 小時）
discli slash register --name mycommand --description "Test command"

確認功能穩定後再全域發布。

Discord 訊息長度上限 2000

症狀： discli message send 在超過 2000 字元時失敗或被截斷。

原因： Discord 限制訊息內容最大 2000 字元，這是 API 層限制，無法繞過。

修正方式：

# 在 system prompt 中限制
"Keep responses under 1900 characters. If you need more space, split across multiple messages."

{"action": "message_send", "channel": "#general", "content": "First part of a long response..."}
{"action": "message_send", "channel": "#general", "content": "Continued from above..."}

Discord 429 速率限制

症狀： stderr 出現 HTTP 429，或 actions 執行被延遲。

原因： Discord API 在每個路徑有不同速率限制。短時間多次呼叫同 endpoint 會回 429，並附 retry_after。

修正方式： discli 會自動對 429 做指數退避。若持續 429，請：

• 降低行為頻率
• 避免短時間大量發送
• 注意 discli 預設內建 5 次破壞性操作/5 秒，目的是留有安全緩衝

member_info 快取未命中

症狀： discli member info @username 第一次較慢或資料不完整，第二次起就正常。

原因： discli 的成員資料主要來自 gateway 快取。機器人新啟動或該使用者近期未活躍時，快取可能沒資料，會回退為 API 抓取，故較慢。

修正方式： 屬預期行為。首次查詢通常 100–500ms，之後快取命中可降到 1ms 以內。若對延遲敏感，可在啟動階段預熱快取：

# 啟動時預先列出成員（捨棄輸出）
discli member list "My Server" --limit 1000 > /dev/null

機器人回應自己

症狀： 代理回覆自己的訊息，導致無限循環。

原因： 代理收到自身訊息事件而未過濾，進而對自己回應。

修正方式： 一定要過濾 bot 訊息：

for line in proc.stdout:
    event = json.loads(line)
    if event.get("type") == "message_create":
        # 跳過所有 bot 訊息（含自己）
        if event["data"].get("is_bot", False):
            continue
        # 繼續處理訊息...

多個 serve 實例

症狀： 使用同一 bot token 啟動第二個 discli serve，第一個實例斷線，或兩邊都出現重複/缺漏事件。

原因： Discord Gateway 同一 bot token 一般只允許一個連線（未分片）。第二個連線會迫使第一個重連，形成反覆重連循環。

修正方式：

• 每個 bot token 僅啟動一個 discli serve
• CLI 指令（discli message send、discli member list）是無狀態 REST 呼叫，可與 serve 並行使用
• 若需多代理，請使用不同 bot token 建立多個機器人應用

附件與 embed

症狀： 你要透過 discli 發送圖片、檔案或 embed。

原因： embed 現在在 CLI 與 serve 都支援。檔案可透過 CLI 的 --file，serve 可透過 files 欄位傳送。

修正方式：

• CLI 使用：附件用 --file，embed 用 --embed-* 旗標：

discli message send “#general” “這是回報內容” —file ./report.csv discli message send “#general” “更新” —embed-title “狀態” —embed-color “5865F2” —embed-field “變更” “修正錯誤並提升效能”

- **Serve 使用**：embed 透過 `embed` JSON，互動元件（按鈕、選單）透過 `components`。詳細請參考 [元件與模態視窗](/guides/components-modals)。

## 十六進位顏色驗證

**症狀：** embed 顏色被拒絕或顯示不正確。

**原因：** Discord embed 顏色使用整數，discli 會接受十六進位字串並自動轉換。

**修正方式：** discli 接受有無 `#` 的十六進位字串；`"5865F2"` 與 `"#5865F2"` 皆合法。非法值（如 `"ZZZZZZ"`、`"12345"`）會回傳清楚的錯誤訊息。

## 成員時限（timeout）秒數

**症狀：** `member_timeout` 回傳秒數無效。

**原因：** Discord 的 timeout 上限是 28 天。

**修正方式：** `duration` 可接受 `0` 到 `2419200` 秒（28 天）。若設為 `0` 代表取消既有 timeout。超過上限會被拒絕。

## 權限名稱驗證

**症狀：** `channel_set_permissions` 或 `role_edit` 回傳權限名稱無效。

**原因：** 權限名稱會用 `discord.Permissions()` 驗證，保證名稱真實存在。

**修正方式：** 請使用正確的 Discord 權限名稱（如 `send_messages`、`manage_channels`、`view_channel`）。可用 `discli role list` 查看現有角色權限，並取其名稱。

## 討論區頻道在 channel_list 中

**症狀：** `channel_list` 裡原本看不見 forum 伺服器頻道。

**修正方式：** 論壇頻道已加入列表，與文字、語音、分類一併顯示，`type` 會是 `forum`。

## 語音狀態事件帶 null channel

**症狀：** 某筆 `voice_state` 事件的 `channel` 與 `old_channel` 皆為 `null`。

**原因：** 少見情況下，Discord 發送的語音狀態更新可能找不到對應快取中的頻道資料。

**修正方式：** 此情況預期會被順利處理，事件仍會送出且含 `null` 欄位。你的代理應在處理前先檢查 `null`。

## 自動封存討論串

**症狀：** bot 先前活躍的討論串自動封存，導致無法再發言。

**原因：** Discord 會依活躍時間自動封存討論串（1 小時、24 小時、3 天、7 天，取伺服器設定）。封存後討論串為唯讀。

**修正方式：**

- **發言會重置封存計時器。** 只要 bot 或使用者都持續留言，討論串會維持活躍
- 要取消封存可直接對討論串發訊息，Discord 會自動解封
- 建立時可指定較長封存時間：
```bash
discli thread create "#general" "Support Thread" --auto-archive 1440  # 24 小時