架構總覽

discli 是一個以 Click 與 discord.py 建置的 Python CLI。它有兩種模式：

• 一次性指令（發起後不需維持連線的 CLI 指令），用於單次操作；
• 持續式 serve 模式，用於與 AI 代理即時雙向溝通。

高階請求流程

每次呼叫 discli 都會依照以下流程，從使用者輸入到 Discord API 呼叫：

flowchart LR
    A[使用者 / 代理] --> B[discli CLI]
    B --> C[Click 框架]
    C --> D[權限檢查]
    D --> E[Token 解析]
    E --> F[discord.py 用戶端]
    F --> G[Discord API]

1. 使用者（或 AI 代理）呼叫一個 discli 指令。
2. Click 解析參數與全域選項（--token、--json、--yes、--profile）。
3. 檢查目前啟用的權限設定檔，確認指令是否被允許。
4. 從旗標、環境變數或設定檔解析機器人權杖（token）。
5. 單次指令會驗證 HTTP 用戶端並直接執行；即時指令會建立 Gateway 用戶端並套用對應的 intent。
6. Discord API 處理請求。

模組依賴關係圖

flowchart TD
    CLI[cli.py] --> CMD[commands/*]
    CLI --> PERM[permission group]
    CLI --> AUDIT[audit group]
    CMD --> CLIENT[client.py]
    CLIENT --> SEC[security.py]
    CLIENT --> DISCORD[discord.py]
    CMD --> UTILS[utils.py]
    CMD --> SEC
    CLI --> CFG[config.py]
    SEC --> CFG_DIR["~/.discli/"]
    CFG --> CFG_DIR

    style CLI fill:#4f46e5,color:#fff
    style CMD fill:#7c3aed,color:#fff
    style CLIENT fill:#2563eb,color:#fff
    style SEC fill:#dc2626,color:#fff
    style CFG fill:#059669,color:#fff
    style UTILS fill:#d97706,color:#fff

模組角色

兩種運作模式

模式一：一次性 CLI 指令

這是預設模式。每個指令建立一個短生命週期的 HTTP 驗證 discord.Client，執行單一操作後即退出，不會開啟 Gateway 會話。

sequenceDiagram
    participant User
    participant CLI as discli CLI
    participant Client as discord.Client
    participant API as Discord API

    User->>CLI: discli message send "#general" "Hello"
    CLI->>CLI: 解析參數、檢查權限並解析 token
    CLI->>Client: 建立用戶端並驗證 token
    Client->>API: 透過 HTTP 送出訊息
    API-->>Client: 200 OK
    Client->>Client: 關閉連線
    CLI-->>User: 「訊息已送出至 #general」

這種方式簡潔且無狀態。它會受 Discord HTTP 速率限制影響，但不會送出 Gateway IDENTIFY、不會消耗 session-start 配額，且不需要不相關的 Gateway intents。

最適用於： 腳本、自動排程任務、單次操作、串接其他工具。

模式二：持續式 serve 模式

discli serve 會啟動長生命週期機器人，透過 stdin/stdout 使用逐行 JSON（JSONL）溝通。機器人會維持與 Discord Gateway 連線並即時轉發事件。

sequenceDiagram
    participant Agent as AI Agent
    participant Serve as discli serve
    participant API as Discord API

    Serve->>API: Gateway 連線
    API-->>Serve: on_ready
    Serve-->>Agent: {"event":"ready","bot_name":"..."}

    API-->>Serve: 新增訊息事件
    Serve-->>Agent: {"event":"message","content":"Hi bot",...}

    Agent->>Serve: {"action":"reply","channel_id":"...","message_id":"...","content":"Hello!"}
    Serve->>API: 送出回覆
    API-->>Serve: 200 OK
    Serve-->>Agent: {"event":"response","status":"ok","message_id":"..."}

Serve 模式會維持持續狀態：

• Typing 指示器：逐頻道啟停（透過動作）
• 串流編輯：每 1.5 秒批次推送內容更新，以配合 Discord 的速率限制
• Slash 指令註冊：啟動時逐伺服器同步
• 互動 token：用於延遲 slash 指令回應

最適用於： AI 代理、聊天機器人、即時監控、互動式應用。

命令註冊

所有命令群組皆在 cli.py 中透過 main.add_command() 註冊：

main.add_command(channel_group)
main.add_command(config_group)
main.add_command(dm_group)
main.add_command(listen_cmd)
main.add_command(member_group)
main.add_command(message_group)
main.add_command(reaction_group)
main.add_command(role_group)
main.add_command(server_group)
main.add_command(poll_group)
main.add_command(thread_group)
main.add_command(typing_cmd)
main.add_command(serve_cmd)
main.add_command(permission_group)
main.add_command(audit_group)

每個命令群組都對應 commands/ 中的一個檔案。新增命令群組採同樣流程：先在新檔案定義 Click 命令，再在 cli.py 註冊該群組。

主要設計決策

後續步驟