BPMAX CLI 使用说明

bpmax-cli 用于在本地终端、Codex、OpenClaw 等 Agent 环境中连接 BPMAX，完成授权、流程查询、流程单创建、审批处理以及 BPMAX Business Skill（BBS）的同步和安装。

本文面向开发者、实施人员和 Agent 使用者，介绍从安装授权到 BBS 发布、同步、懒加载安装的完整使用方式。

如果只需要让 Agent 第一次接入 BPMAX CLI，请阅读 Agent 首次接入 BPMAX CLI。

适用场景

  • 在本地脚本或 Agent 中调用 BPMAX 能力
  • 查询流程、项目、待办和表单模板
  • 创建或提交流程单
  • 发布、升级和安装 BPMAX Business Skill
  • 通过 BBS Catalog 让 Agent 发现可用业务能力

安装与更新

推荐：让 Agent 自动安装并初始化

首次接入 BPMAX CLI 时，最推荐的方式是在 Agent 对话中直接发送下面这句话。Agent 会按快速开始文档完成安装、初始化授权、profile 检查和 Skill 同步。

帮我安装并初始化 bpmax-cli, 具体内容参考文档： https://doc.bpmax.cn/develop/bpmax-cli/agent-quickstart.html

这种方式适合 Codex、OpenClaw 等 Agent 场景，能减少手动复制命令和漏同步 Skill 的问题。

手动安装

首次安装使用 npm 全局安装：

npm i -g bpmax-cli

安装完成后确认命令可用：

bpmax-cli --version
bpmax-cli --help

如果当前环境已经安装 bpmax-cli，后续更新优先使用内置更新命令：

bpmax-cli update

更新会同步 CLI 自身和内置 Skill。对于 BBS，update 不会全量安装远端业务 Skill；需要先同步 Catalog，再在真正使用某个 BBS 时懒加载安装。

bpmax-cli bbs sync --agent codex --profile <profile> --format json
bpmax-cli bbs ensure <skill-key> --agent codex --profile <profile> --format json

初始化授权

第一次连接某个 BPMAX 环境时，使用 init 生成授权会话。--url 填写目标工作区地址，--name 是本地 profile 名称。

bpmax-cli init \
  --agent codex \
  --channel feishu \
  --url "https://your-bpmax.example.com/w:default" \
  --name demo-default \
  --format json

命令会返回授权链接、验证码和 session 信息。Agent 对话中通常会先把授权链接和用户码发给用户；用户完成授权后，Agent 继续执行返回的 next_command，并确认 profile、授权状态和 Skill 同步结果。

Agent 对话初始化示例

按返回提示在浏览器中完成授权后，可检查连接状态：

bpmax-cli auth status --profile demo-default --format json

常用 profile 命令：

bpmax-cli config profile list
bpmax-cli config profile show --profile demo-default

Profile 与 API Key

profile 是本地连接配置，通常包含环境地址、工作区、授权结果和 API Key 信息。Agent 执行 BPMAX 操作时会读取 profile，因此同一个本地环境可以同时保存多个 BPMAX 工作区。

建议按环境和工作区命名 profile：

demo-default
yuanrong-test
local-default

如果命令返回未授权、无权限或找不到接口，优先检查：

  • --profile 是否指向正确环境
  • 当前用户是否有对应 BPMAX 权限点
  • API Key 是否启用
  • --url 是否包含正确 workspace，例如 /w:default

常用 BPMAX 操作

查询流程定义：

bpmax-cli flow list --profile demo-default --format json
bpmax-cli flow show <flow-id-or-key> --profile demo-default --format json

查询项目和待办：

bpmax-cli project list --profile demo-default --format json
bpmax-cli project show <project-id> --profile demo-default --format json
bpmax-cli project current-user-steps --profile demo-default --format json

创建流程单：

bpmax-cli project create \
  --profile demo-default \
  --flow-id <flow-id> \
  --interactive \
  --format json

对于含有复杂初始化脚本、关联表单或需要用户确认的流程，优先使用交互式创建。CLI 会引导收集字段；当必须由页面完成选择或初始化时，会返回 BPMAX 创建页链接。

BBS 管理页面

如果需要了解 BBS 的概念、适用场景和开发方法，请阅读 BPMAX Business Skill（BBS）。

BPMAX Business Skill 管理页用于维护远端业务 Skill。管理员可以在这里创建 BBS、上传标准 Skill zip 包、升级版本、删除记录，并查看版本信息。

入口示例：

https://your-bpmax.example.com/w:default/business-skills

BBS 管理列表

点击“创建 BBS”后，上传 zip 包并补充场景说明。zip 根目录必须包含 SKILL.md，并在 frontmatter 中声明 name、version、description。

创建 BBS

截图中的 BBS 为示例数据。创建或上传成功后，可在列表行操作中进入升级、版本详情和删除等功能。

BBS CLI 使用

查看远端 BBS

bpmax-cli bbs list --profile demo-default --format json
bpmax-cli bbs show <key-or-id> --profile demo-default --format json

创建 BBS

bpmax-cli bbs create \
  --name "预算查询" \
  --scene "预算分析" \
  --zip ./skill.zip \
  --profile demo-default \
  --format json

升级 BBS

bpmax-cli bbs upgrade <key-or-id> \
  --zip ./skill.zip \
  --release-note "补充预算执行率统计" \
  --profile demo-default \
  --format json

版本号必须递增。同一个 BBS 下不能重复上传相同版本。

同步 Catalog

bpmax-cli bbs sync --agent codex --profile demo-default --format json

bbs sync 只安装或更新轻量 bpmax-business-skill-catalog，让 Agent 能发现远端 BBS 列表、场景、版本摘要和推荐命令。它不会默认安装所有业务 Skill。

使用前确保安装

bpmax-cli bbs ensure <key-or-id> \
  --agent codex \
  --profile demo-default \
  --format json

bbs ensure 会检查本地是否已安装该 BBS，并对比远端最新版本：

  • 未安装：下载并安装
  • 版本落后：自动更新
  • 已是最新：跳过安装

安装、更新和卸载

bpmax-cli bbs install <key-or-id> --agent codex --profile demo-default --format json
bpmax-cli bbs update <key-or-id> --agent codex --profile demo-default --format json
bpmax-cli bbs uninstall <key-or-id> --agent codex --profile demo-default --format json

OpenClaw 场景下，CLI 会优先尝试 OpenClaw 自身的 Skill 安装命令，失败后再 fallback 到本地 Skill 目录。不要手动复制远端 BBS，避免版本和安装记录不一致。

BBS 发布前 Lint

发布或升级 BBS 前，可以单独运行 lint：

bpmax-cli bbs lint --zip ./skill.zip --format json

bbs create 和 bbs upgrade 默认会先执行 lint：

  • errors 会阻断上传
  • warnings 只提示，不阻断
  • 如确需临时绕过，可显式使用 --allow-lint-errors

lint 主要检查：

  • zip 根目录是否包含 SKILL.md
  • SKILL.md frontmatter 是否包含 name、version、description
  • version 是否符合 semver
  • 升级版本是否大于远端最新版本
  • 文档中的 bpmax-cli 命令是否存在
  • 是否引用高风险操作
  • 审批类 BBS 是否包含确认、批量限制、上下文获取和失败停止等 guardrail

BBS 业务 Gate

BBS 可以在 zip 根目录增加 bbs.json，声明业务执行前后的 gate。Agent 在执行关键业务动作前后，应调用 CLI gate 命令。

{
  "lint": {
    "commands": ["npm test"]
  },
  "gates": {
    "preflight": {
      "requiredCommands": ["bpmax-cli project approval-context"],
      "requiredInputs": ["project_id", "step_id", "decision"]
    },
    "verify": {
      "requiredOutputs": ["project_id", "step_id", "action_result"]
    }
  }
}

业务动作前：

bpmax-cli bbs gate <skill-key> \
  --stage preflight \
  --input @input.json \
  --profile demo-default \
  --format json

业务动作后：

bpmax-cli bbs gate <skill-key> \
  --stage verify \
  --input @result.json \
  --profile demo-default \
  --format json

如果 gate 返回 ok: false，Agent 必须停止后续状态变更，或不要声称业务处理成功。

推荐工作流

使用者

  1. 初始化并确认 profile 可用
  2. 执行 bpmax-cli bbs sync 同步 Catalog
  3. 根据业务需求选择 BBS
  4. 执行 bpmax-cli bbs ensure 安装或更新目标 BBS
  5. 按 BBS 文档执行具体业务命令
  6. 审批、批量处理等高风险业务按 bbs.json 执行 gate

发布者

  1. 在本地开发标准 Skill
  2. 确认 zip 根目录包含 SKILL.md
  3. 执行 bpmax-cli bbs lint --zip ./skill.zip
  4. 使用 bbs create 发布首个版本
  5. 后续使用 bbs upgrade 上传新版本
  6. 在管理页查看版本和安装记录

排障

未授权或 profile 不存在

先检查 profile：

bpmax-cli config profile list
bpmax-cli auth status --profile <profile> --format json

如授权已失效，重新执行 bpmax-cli init。

API Key 权限不足

如果接口返回无权限，说明当前用户或 API Key 缺少对应权限点。需要在 BPMAX 角色管理中为当前账号补充权限后，再重新授权或更新 API Key。

下载地址返回登录页

BBS 下载必须走受控下载接口或签名后的上传文件地址。如果下载内容是登录页，通常说明 URL 不是实际包地址，或当前下载请求没有携带有效授权。

处理方式：

  • 先更新到最新 bpmax-cli
  • 重新执行 bpmax-cli bbs show <key-or-id> 查看下载信息
  • 使用 bpmax-cli bbs ensure <key-or-id> 下载，不要手动复制页面 URL

checksum 不匹配

checksum 不匹配表示下载到的内容和服务端记录的包不一致，常见原因是包被覆盖、下载到了登录页或版本记录未同步。

处理方式：

  • 删除本地该 BBS 后重新 bbs ensure
  • 确认服务端版本记录的 checksum 与文件一致
  • 避免手动替换远端包文件

BBS 版本未递增

bbs upgrade 要求新 zip 中 SKILL.md 的 version 大于远端 latest_version。修改 Skill 后应同步递增版本号，例如从 1.0.0 升级到 1.0.1。

lint 或 gate 阻断

lint 阻断说明发布包不满足质量要求。gate 阻断说明业务执行上下文不完整或结果未通过校验。应修复 Skill、输入或业务前置条件，而不是默认绕过。