Mininglamp-OSS/octo-cli

octo-cli – Octo AI-代理生態系專用的輕量級、以 JSON 為先的 CLI

是什麼 – octo-cli 是用 Go 編寫的單一二進制命令列客戶端，與 Octo 平台的 REST API 通訊。它旨在由 AI 代理執行時（如 OpenClaw、Claude Code）透過 exec 呼叫。每次呼叫都會在 stdout 上回傳決定性的 JSON 包裝；錯誤以 JSON 格式在 stderr 上輸出，並採用固定分類體系。該工具無互動式提示——完全為程式化使用而設計。

為何存在 – 所有業務邏輯均位於 Octo 的後端服務中（文件儲存、磁碟、訊息、車隊控制等）。CLI 的職責是：

• 讀取嵌入二進制檔中的 OpenAPI 3.x 規範；
• 自動基於 Cobra 生成命令樹；
• 在任何網路呼叫前，根據規範驗證請求負載；
• 發送 HTTP 請求；
• 將回應格式化為標準包裝。

關鍵設計要點

特性	說明
基於元資料	端點僅在嵌入的 OpenAPI 規範中定義；新增 API 僅需修改規範，無需變更 Go 程式碼。
代理優先輸出	包含 ok、identity、data、分頁和速率限制資訊的穩定 JSON 包裝。
依賴性注入	內部 Factory 提供設定、憑證、HTTP 客戶端和規範註冊表——便於測試。
決定性錯誤	驗證錯誤在本機捕獲；後端拒絕回傳具有固定 type/code 模式的錯誤。
輕量級客戶端	無業務邏輯；CLI 僅為傳輸、驗證和格式化服務。

支援的領域 – CLI 按領域分組公開大量操作（每個領域對應一個後端服務）：

• docs – 生命週期、全文搜尋、電子試算表、白板、評論、版本、附件。
• html – 不可變的互動式 HTML 文件、草稿、共享代碼、基於 UID 的授權。
• drive – 網路磁碟空間、資料夾樹、兩階段 blob 上傳、簽署下載、共享連結。
• group, thread, message, file, event – 協作原語。
• bot – 機器人註冊、心跳、使用者資訊。
• loop – 車隊控制平面（任務、執行、專家、自動化等）。
• matter, summary – 列出但暫時停用，因後端仍在穩定中。

安裝

• npm – npm install -g @mininglamp-oss/octo-cli（為宿主平台拉取預建構二進制檔）。
• Go – go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest。
• Homebrew – 計畫中（brew install Mininglamp-OSS/tap/octo-cli）。
• GitHub 發布 – 下載適用於您作業系統/架構的 tarball，並將二進制檔移動到 $PATH 中的目錄。
• install.sh – 一鍵 curl 腳本，用於取得最新發行版本。

典型工作流程（環境變數控制認證和路由）：

export OCTO_BOT_TOKEN="bf_…"          # 機器人權杖（app_、bf_、uk_ 或 octo_loop_）
# 可選：export OCTO_API_BASE_URL="https://im-test.deepminer.com.cn"

# 從機器人發送訊息
octo-cli message send \
  --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'

# 跨通道搜尋訊息
octo-cli message search --keyword "quarterly report"

# 列出群組，建立線程
octo-cli group list
octo-cli thread create group-abc --name "design review"

# 將檔案上傳到磁碟
octo-cli file upload --file ./report.pdf

所有命令均支援通用旗標，如 --format（json|table|csv|ndjson）、--jq 用於後處理、--dry-run 查看解析後的請求、--verbose 查看請求/回應日誌，以及分頁輔助工具（--page-all、--page-limit）。

認證模型 – 僅機器人。CLI 按優先順序讀取權杖：

1. 儲存的設定檔（octo-cli auth login）
2. OCTO_TOKEN
3. OCTO_BOT_TOKEN 權杖類型可以是 App 機器人（app_*）、使用者機器人（bf_*）、使用者 API 金鑰（uk_*）或 Loop 任務憑證（octo_loop_*）。權杖類型決定後端允許的功能；CLI 會執行一些預檢檢查（例如，拒絕 app_* 用於訊息搜尋）。

輸出格式 – 成功呼叫輸出：

{ "ok": true, "identity": "bot", "data": {…}, "_pagination": {…}, "_rate_limit": {…} }

失敗時在 stderr 上輸出類似包裝，包含 error.type、code、message 和可選的 hint/detail。退出碼：3（認證）、2（驗證/設定）、1（其他）。

代理技能 – 人類可讀、機器可解析的技能檔案位於 skills/ 目錄下。它們描述每個領域的命令、旗標和錯誤分類體系，以便 AI 代理在執行時載入（octo-cli skills）。這些檔案也嵌入在二進制檔中，支援離線使用。

可擴展性 – 新增或變更端點只需編輯 internal/registry/specs/ 下的 OpenAPI 規範檔案；CLI 在啟動時自動重新生成命令樹。無需修改 Go 原始碼。

許可證 – Apache-2.0。

---

總結 – octo-cli 是一個專為特定用途設計的非互動式 CLI，使 AI 代理能夠以可預測、以 JSON 為中心的方式與 Octo 平台互動，內建模式驗證、分頁支援和豐富的協作 API。