@inf-monkeys-tech/monkeys-cli

v0.12.12

Published

8 hours ago

Monkeys command-line client for AI agents, automation, and interactive use

0High
0Medium
0Low

ruiruiz

yttydcs

taxue

monkeys-cli

中文版 | English

Monkeys 官方命令行工具，让人类、自动化脚本和 AI Agent 都能在终端中安全操作 Monkeys。它支持云端与私有化部署，覆盖订阅与身份、Workflow、Execution、Agent Work、Ontology/Data、System Config、文件传输和动态 OpenAPI。

CLI 是唯一执行层；npm 包内的 7 个聚焦领域 Skill 按需指导 Agent，monkeys-shared 统一保存上下文、安全、错误和版本规则，不内置模型、规划器或 Agent Runtime。

安装 · AI Agent Skill · 认证 · 命令体系 · 进阶用法 · 安全 · 开发

为什么选择 monkeys-cli？

Agent 原生 — CLI 与全部官方 Skills 同包、同版本发布，一条命令完成安装
多订阅设计 — 一个本地 CLI 可连接多个云端或私有化 Endpoint，并快速切换 Subscription
语义优先 — Workflow、Execution、Agent Work、Data 和 Config 都有明确的领域命令
开放覆盖 — 动态发现部署实际发布的 OpenAPI，并提供受控的原始 API 调用
自动化友好 — 稳定 JSON/NDJSON 输出、固定退出码、Request ID 和上下文摘要
安全可控 — 浏览器登录不接收账户密码，API Key 不进入命令参数，高风险写入要求显式确认
可恢复 — 写入前预检、配置原子更新、本地快照以及结果未知时的禁止重放策略

功能

| 类别 | 能力 | | ------------------------ | ----------------------------------------------------------------------- | | 🔗 Deployment 与 Subscription | 管理多个 Endpoint、Tenant、Team 和 Subscription，支持云端及私有化部署 | | 🔐 认证 | 浏览器 Device Code 登录、API Key 登录、状态验证、身份查询和安全存储诊断 | | 🔁 Workflow 与 Execution | Workflow CRUD、导入、运行，以及 Execution 查询、等待和状态流 | | 🤖 Agent Work | 创建、查询、分配、对话、Spec 审批、运行控制、Review 与状态观察 | | 🧠 Ontology 与 Data | Ontology、View、Asset、Field、Feature Value、Tag、Container 和数据迁移 | | ⚙️ System Config | 配置总览、发现、读取、校验、历史、脱敏导出与受控更新 | | 📁 文件与媒体 | 文件、Asset 媒体和 View Attachment 的流式上传下载 | | 🧩 OpenAPI | 动态发现、缓存、Operation 描述与带证据约束的原始 API 调用 |

安装与快速开始

环境要求

Node.js 22 或更高版本
npm / npx

快速开始（人类用户）

第 1 步 — 安装 CLI 与 Skills

npx @inf-monkeys-tech/monkeys-cli@latest install

安装向导会全局安装 monkeys CLI，并从同一个 npm 制品安装匹配版本的 7 个官方 Skills。

如果只需要 CLI：

npm install --global @inf-monkeys-tech/monkeys-cli

第 2 步 — 登录订阅

订阅 URL 就是该 Subscription 对应的 Endpoint。浏览器登录成功后，CLI 会读取当前租户的 tenantId，用它命名 Subscription，并设为当前订阅。

monkeys auth login --url https://customer.example.com

CLI 会输出并打开该 Endpoint 的登录 URL。账户密码只在浏览器页面输入，不会经过 CLI。

第 3 步 — 验证并开始使用

monkeys auth status --output json
monkeys subscription list --output json
monkeys workflow list --team <team-id> --output json

运行 monkeys <命令> --help 查看当前版本的真实参数。

快速开始（AI Agent）

以下步骤面向正在协助用户安装和登录的 AI Agent。浏览器授权必须由用户完成。

第 1 步 — 安装

npx @inf-monkeys-tech/monkeys-cli@latest install
monkeys version check --output json

第 2 步 — 创建浏览器授权

monkeys auth login \
  --url https://customer.example.com \
  --no-wait \
  --output json

把返回的授权 URL 交给用户。用户完成浏览器登录后，使用同一响应中的临时 Subscription 和 Device Code 继续轮询：

monkeys auth login \
  --subscription <temporary-subscription> \
  --device-code <device-code> \
  --output json

第 3 步 — 验证上下文

monkeys auth status --output json
monkeys subscription list --output json

如果使用 API Key，不要把 Key 放进参数或 shell history：

monkeys auth login \
  --url https://customer.example.com \
  --api-key-stdin \
  --output json

AI Agent Skill

| Skill | 说明 | | --- | --- | | monkeys-shared | Subscription、Context、Team、Identity、输出、安全、错误与版本规则 | | monkeys-auth | 浏览器登录与 API Key 认证 | | monkeys-workflow | Workflow、Execution 与文件 | | monkeys-dev-agent-work | Dev Agent Work 全生命周期 | | monkeys-data | Ontology、Data、治理与迁移 | | monkeys-system-config | Kernel System Config | | monkeys-openapi | Schema 与受控 OpenAPI 降级 |

安装命令会全局安装正在执行的精确 CLI 版本，删除废弃的官方 Skill，逐个验证 Agent 实际发现路径和内容校验和，全部成功后才记录所有权。可随时查看或修复漂移：

monkeys version check --output json
monkeys skills status
monkeys skills sync

Agent 可直接读取 npm 包内的同版本内容，例如 monkeys skills read monkeys-data references/data-read.md；参数真相来自 monkeys schema <命令路径> 与命令 Help，不能凭记忆构造。

认证

| 命令 | 说明 | | --------------------- | ---------------------------------------------------------- | | auth login | 使用 Endpoint URL 发起浏览器登录，或从安全输入导入 API Key | | auth status | 验证当前 Credential，并返回身份、Team、Surface 和权限 | | auth whoami | 查询当前服务端身份 | | auth logout | 移除指定 Subscription 保存的 Credential | | auth doctor | 检查当前浏览器 Session Store 的安全读写能力 | | auth api-key import | 从 stdin 或指定环境变量导入 API Key |

浏览器登录

monkeys auth login --url https://customer.example.com --output json

API Key 登录

monkeys auth login --url https://customer.example.com --api-key-stdin --output json
monkeys auth login --url https://customer.example.com --api-key-env MONKEYS_API_KEY --output json

多订阅切换

monkeys subscription list --output json
monkeys subscription use --name <subscription-name> --output json
monkeys subscription test --name <subscription-name> --output json

版本更新

每次正常调用 CLI 都会读取本地更新缓存。npm latest 高于当前版本时，JSON 输出会包含 _notice.update，Text 输出会直接提示准确的恢复命令：

Update available: 0.10.2 → 0.10.3. Run `monkeys update` to install.

CLI 最多每 24 小时通过所属 npm/pnpm 的 registry 与代理配置在独立后台进程中刷新一次缓存，不会因版本查询拖慢当前命令。CI、非发布版本以及设置了 MONKEYS_CLI_NO_UPDATE_NOTIFIER=1 的进程不会检查更新。

# 只检查，不执行安装
monkeys update --check --output json

# 升级由 npm/pnpm 实际拥有的全局包，并验证全部匹配 Skill
monkeys update

# 只校验并输出精确升级计划，不执行修改
monkeys update --dry-run

# 强制重装当前最新版和 Skills
monkeys update --force

在交互式终端裸运行 monkeys 时，还会显示可选的 [y/N] 升级询问。执行升级时始终通过所属包管理器实时解析目标版本，不会直接信任缓存；只更新由 npm 或 pnpm 实际拥有的安装，并验证 PATH 中生效的精确 CLI 与实际 Skills，最终验证失败时回滚到精确旧版本。

命令体系

monkeys-cli 提供三种调用粒度，从稳定领域操作到部署实际发布的底层 API。

1. 语义命令

优先供人类和 Agent 使用，内置上下文校验、风险分类和稳定输出。

monkeys workflow list --subscription customer-a --team <team-id> --output json
monkeys workflow run <workflow-id> --subscription customer-a --team <team-id> --input-json '{"prompt":"hello"}' --output json
monkeys execution wait <execution-id> --subscription customer-a --team <team-id> --timeout-seconds 600 --output json
monkeys agent work list --subscription customer-kernel --output json
monkeys data asset list --subscription customer-kernel --perspective kernel --ontology <ontology-id> --output json
monkeys config overview --subscription customer-kernel --output json

2. OpenAPI 发现

从当前部署发布的新鲜 OpenAPI 合同中列出并描述真实 Operation。

monkeys api list --subscription customer-a --output json
monkeys api describe --operation-id <operation-id> --subscription customer-a --output json

3. 受控原始 API

只在没有合适语义命令时使用。写操作要求显式确认；语义命令返回受控降级证据时，必须在相同 Subscription、Tenant、Team 和 Credential Context 中消费。

monkeys api call \
  --operation-id <operation-id> \
  --subscription customer-a \
  --query-json '{}' \
  --output json

进阶用法

统一分页

所有 list、search 和 rows 命令统一使用 --page-size、--page-token、--page-all、--page-limit 和 --page-delay。输出统一为 items 和 pageInfo；只有在 Subscription、Team、筛选条件和分页大小完全相同时，才能继续使用 pageInfo.nextPageToken。

monkeys workflow list --subscription customer-a --page-size 50 --output json
monkeys workflow list --subscription customer-a --page-token <next-page-token> --page-size 50 --output json

结构化输出

自动化和 Agent 使用 --output json；长时间状态观察使用 NDJSON。成功结果写入 stdout 且退出码为 0，错误写入 stderr 并返回固定非零退出码。

{
  "ok": true,
  "data": {},
  "meta": {
    "command": "workflow list",
    "schemaVersion": "2",
    "timestamp": "..."
  }
}

Dry Run 与显式确认

支持 --dry-run 的副作用命令应先执行预检；通过预检后，真实高风险写入必须显式添加 --yes。

monkeys workflow delete <workflow-id> \
  --subscription customer-a \
  --team <team-id> \
  --dry-run \
  --output json

明确上下文

--subscription 选择订阅和 Credential
--team 选择 Team 上下文或显式筛选
--perspective kernel|studio 断言 Data 视角，不扩大权限
--resource-team 在需要时明确下游数据资源分区

不要根据资源名称猜测 Subscription、Team、Ontology 或其他 ID；先用只读命令解析真实上下文。

深入文档

| 主题 | 文档 | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | 平台、上下文与安全 | platform-overview.md · safety-errors.md | | 认证与多订阅 | authentication.md | | Workflow、Execution 与文件 | workflow-execution-files.md | | Agent Work | agent-work.md | | Data 读取与视角 | data-read.md · data-perspective.md | | Data 写入与迁移 | data-write.md · data-transfer.md | | System Config | system-config.md | | OpenAPI 降级 | fallback.md |

安全与风险提示（使用前必读）

monkeys-cli 可以被 AI Agent 调用来读取或修改用户有权访问的 Monkeys 数据。模型幻觉、提示词注入、错误上下文和权限误用仍可能造成数据泄露或非预期操作；请只授予任务所需的最小权限，并在写入前核对精确目标。

CLI 不接收账户密码；账户登录只在订阅 Endpoint 的浏览器页面完成
API Key 只允许从 stdin 或环境变量读取，不得写入参数、仓库、日志或普通配置文件
HTTPS 是默认要求；HTTP 只允许本机地址，私有 CA 不会关闭 TLS 校验
自定义 Header 不能覆盖认证、Tenant、Team、Host、Cookie 或代理认证 Header
删除、治理和其他高风险操作要求精确目标与显式确认，--yes 不扩大权限
写请求结果未知时禁止自动重试，先用对应的只读 list/get/status/history 命令核查
输出统一递归脱敏，但调用者仍应避免把业务数据和调试日志发送给无关第三方

开发与发布

仓库使用 Bun 管理依赖和执行脚本；用户安装仍使用 npm / npx。

bun install --frozen-lockfile
bun run verify

bun run verify 包含格式、类型、单元与合同测试、构建、CLI/Skill 兼容检查、npm 安装冒烟和性能门禁。

默认分支每增加一个提交都会自动发布一个稳定版本。GitLab CI 按提交顺序串行发版：当源码中的 package.json 版本高于 npm 时使用该版本，否则在 npm 最新稳定版本上递增 patch；发布包会记录源提交，并且流水线只构建一个 tarball、安装验证并把同一字节发布到 npm latest，随后创建同版本 Git tag、GitLab Release 和 AI changelog。功能分支 push 只执行验证。本地不得执行 npm publish。

License

本项目仅按 GNU General Public License v3.0（GPL-3.0-only）授权。