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。