BPMAX CLI 使用说明

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

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

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

从 bpmax-cli@0.1.43 起，远端业务命令会接入 BPMAX 的 CLI 终端管控能力：CLI 终端会在授权后注册到平台，业务命令会先通过服务端能力白名单校验，并产生命令级审计记录。管理员可以在平台的“系统配置 -> 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 和多用户共享 profile 的问题。

手动安装

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

npm i -g bpmax-cli

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

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

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

bpmax-cli update

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

Agent 场景必须带 --config-dir <config_dir>：

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

本地单用户终端可继续使用旧兼容方式：

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 基础名称。

Agent 隔离初始化

Codex、OpenClaw、Claude、Gemini 等 Agent 场景必须传入 --profile-scope <TRUSTED_RUNTIME_SCOPE>：

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

TRUSTED_RUNTIME_SCOPE 必须来自可信 runtime metadata，例如当前用户 ID、租户 ID、会话 ID、channel + user/peer 标识。LLM 不能从自然语言中猜测 scope。

init 会返回：

  • config_dir：隔离配置目录，例如 ~/.bpmax/agent-contexts/<agent>/<scope_hash>/
  • profile：CLI 派生后的真实 profile 名
  • message_card.next_command：授权完成后必须逐字执行的命令
  • next_commands.profile_list、next_commands.auth_status、next_commands.bbs_list：后续检查命令

Agent 对话中通常会先把授权链接和用户码发给用户；用户完成授权后，Agent 继续执行 message_card.next_command。后续所有 auth、config profile、flow、project、bbs、recipe 命令都必须保留返回命令里的 --config-dir <config_dir>。

Agent 对话初始化示例

授权完成后可检查连接状态：

bpmax-cli --config-dir <config_dir> auth status --profile <profile> --format json

常用隔离 profile 命令：

bpmax-cli --config-dir <config_dir> config profile list --format json
bpmax-cli --config-dir <config_dir> config profile show --profile <profile> --format json

本地终端兼容初始化

本地单用户终端可以继续不传 --profile-scope，配置会写入默认 ~/.bpmax：

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

本地终端检查：

bpmax-cli auth status --profile demo-default --format json
bpmax-cli config profile list
bpmax-cli config profile show --profile demo-default

Profile、Config Dir 与 API Key

profile 是本地连接配置，通常包含环境地址、工作区、授权结果和 API Key 信息。config_dir 是本地状态根目录。

在 Agent 环境中，同一个机器或容器可能服务多个用户、会话和 Agent。如果所有人共享默认 ~/.bpmax/config.json，不同用户的授权、BBS 安装状态和 recipe 会互相可见。因此 Agent 必须使用 init --profile-scope 返回的隔离 config_dir。

隔离目录中会保存：

  • config.json
  • profile 数据目录
  • BBS state 和安装记录
  • Skill stamp
  • profile recipes

Profile recipes 位于：

<config-dir>/profiles/<profile>/recipes/<workspace>/<recipe-name>/

本地终端的默认兼容路径仍是 ~/.bpmax。

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

  • Agent 后续命令是否保留 --config-dir <config_dir>
  • --profile 是否使用 init 返回的真实 profile
  • 当前用户是否有对应 BPMAX 权限点
  • API Key 是否启用
  • --url 是否包含正确 workspace，例如 /w:default

配置工作区 AGENTS.md 初始化

当需要让 Agent 在某个项目目录中修改 BPMAX 配置时，可以先用 config init workspace 生成本地 AGENTS.md 指引。该命令只写本地文件，不调用远端接口；它会读取当前 profile 中的 config_environments[env]，把目标环境、Skill 路由和配置提交闭环写入一个带 marker 的 BPMAX 配置区块。

bpmax-cli config init workspace \
  --profile <profile> \
  --env <env> \
  --cwd /path/to/workspace \
  --format json

默认写入 /path/to/workspace/AGENTS.md。如果文件已存在，CLI 会保留原内容，并追加或替换下面这种同环境区块：

<!-- bpmax-cli:config-workspace:start env=<env> -->
...
<!-- bpmax-cli:config-workspace:end env=<env> -->

生成内容不会写入 API Key、Authorization、token、password、验证码、手机号等敏感明文。如果指定环境还没有配置，先执行：

bpmax-cli config-env add <env> --profile <profile>

如果当前 API Key 尚未开启配置能力，命令仍可生成本地 AGENTS.md，但文件中会提示需要重新授权并在授权页勾选“开启配置能力”后，才能执行远端配置写操作。

CLI 终端管控、能力白名单与审计

bpmax-cli@0.1.43+ 会把所有通过 API Key 执行的远端业务命令纳入平台治理：

  • init、setup 或 auth device complete 授权成功后，CLI 会向 huanpingtong-server 注册当前终端。
  • 业务请求会携带 X-BPMAX-CLI-Terminal-Id、X-BPMAX-CLI-Version、X-BPMAX-CLI-Command、X-BPMAX-CLI-Capability 和 X-Request-Id。
  • CLI 会请求 GET /api/cli/capabilities 获取当前用户、当前 workspace 可使用的能力白名单。
  • 只有命中白名单的 typed command 才会继续发业务请求；缺能力、能力探查失败、终端被禁用时都会在本地阻断。
  • 每次 CLI 执行只生成一条命令级审计，底层多个 API 请求会归入同一条审计摘要。
  • 审计会脱敏 Authorization、API Key、token、手机号、验证码、--body、--data 等敏感参数。

查看本地缓存的能力白名单：

bpmax-cli --config-dir <config_dir> capabilities status --profile <profile> --format json

强制刷新能力白名单：

bpmax-cli --config-dir <config_dir> capabilities refresh --profile <profile> --format json

能力白名单由服务端结合登录用户、API Key 用户、workspace 和权限点计算。CLI 只消费结果，不自行推断权限。典型能力包括：

  • project.search：通过 huanpingtong POST /api/project/list 的 ES 模式查询项目。
  • project.create：通过 typed project create 创建流程单，保留表单模板检测和 handoff 保护。
  • step.submit：通过 step submit 做安全环节提交。
  • bbs.ensure：按需下载和安装远端 BBS。

平台侧入口：

系统配置 -> CLI 终端管理

管理员可在该页面查看终端名称、用户、Agent、workspace、CLI 版本、最近活跃时间、启用状态和最近命令审计。禁用终端后，该终端后续业务命令会被拒绝；本地 CLI 如果发现服务端记录丢失，会自动重新注册一次，真正被禁用时才停止。

CLI 终端管理列表

点击终端行的“详情”可以查看该终端最近的命令审计。审计记录会展示命令、capability、workspace、状态、耗时和错误摘要，长参数和敏感参数会被脱敏，例如 --body [REDACTED]。

CLI 终端命令审计

如果平台尚未升级到支持 CLI 治理接口的版本，bpmax-cli@0.1.43+ 在远端业务命令前会提示：

当前 BPMAX 平台版本不支持 CLI 治理能力，请升级 huanpingtong-server 后再使用 bpmax-cli 0.1.42+ 的远端业务命令。

这种情况下，建议先升级平台，或临时使用与旧平台匹配的 bpmax-cli 版本；不要绕过 typed command 改用 raw API。

常用 BPMAX 操作

Agent 示例：

bpmax-cli --config-dir <config_dir> flow list --profile <profile> --format json
bpmax-cli --config-dir <config_dir> flow get <flow-id-or-key> --profile <profile> --format json
bpmax-cli --config-dir <config_dir> project list --profile <profile> --format json
bpmax-cli --config-dir <config_dir> project search --profile <profile> --body @project-search-query.json --page 1 --page-size 20 --format json
bpmax-cli --config-dir <config_dir> project get <project-id> --profile <profile> --format json
bpmax-cli --config-dir <config_dir> project my-step --profile <profile> --format json

本地单用户终端示例：

bpmax-cli flow list --profile demo-default --format json
bpmax-cli flow get <flow-id-or-key> --profile demo-default --format json
bpmax-cli project list --profile demo-default --format json
bpmax-cli project get <project-id> --profile demo-default --format json
bpmax-cli project my-step --profile demo-default --format json

创建流程单：

bpmax-cli --config-dir <config_dir> project create \
  --profile <profile> \
  --flow-id <flow-id> \
  --interactive \
  --format json

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

环节推进与审批处理

推进、通过、拒绝或完成环节属于状态变更。Agent 不应只凭 ES 关键词、附件文本或自然语言描述直接调用底层接口，必须先用 CLI 聚合当前环节上下文、可用按钮语义和当前环节绑定表单要求。

先读取上下文：

bpmax-cli --config-dir <config_dir> step context <step-id> \
  --project-id <project-id> \
  --profile <profile> \
  --format json

再读取可用动作：

bpmax-cli --config-dir <config_dir> step actions <step-id> \
  --project-id <project-id> \
  --profile <profile> \
  --format json

然后读取当前环节需要填写的内容：

bpmax-cli --config-dir <config_dir> step requirements <step-id> \
  --project-id <project-id> \
  --profile <profile> \
  --format json

step context 会返回项目 URL、环节 URL、当前用户是否可处理、流程节点动作、项目/环节表单摘要、requirements 和 identity_unverified。当 project_form: {}、step_forms: [] 但只从 ES 或附件文本命中候选人姓名时，CLI 会返回 identity_unverified: true，Agent 必须停止并请用户人工确认，不得自动推进。

step requirements 聚焦当前环节绑定的表单字段，会返回：

  • required_inputs：当前环节必填字段
  • optional_inputs：当前环节可选字段
  • missing_required_inputs：仍缺失的必填字段
  • provided_values：已从环节表单或 --data 中识别到的值
  • submit_payload_template：可作为 --data 参考的 payload 模板
  • can_submit 和 blocking_reasons：是否允许确认提交

如果 missing_required_inputs 非空，Agent 必须先补齐 --data，不能直接追加 --confirm。

提交前先 dry-run：

bpmax-cli --config-dir <config_dir> step submit <step-id> \
  --project-id <project-id> \
  --action approve \
  --label "通过" \
  --data '{"form":{"manager_opinion":"同意"}}' \
  --comments "确认推进" \
  --profile <profile> \
  --format json

只有用户确认后才加入 --confirm <confirmation-text> 执行真实提交：

bpmax-cli --config-dir <config_dir> step submit <step-id> \
  --project-id <project-id> \
  --action approve \
  --label "通过" \
  --data '{"form":{"manager_opinion":"同意"}}' \
  --comments "确认推进" \
  --confirm "确认推进 <project-id>/<step-id>" \
  --profile <profile> \
  --format json

step submit 会在提交前阻断已完成环节、项目和环节不匹配、当前用户不可处理、身份未确认、当前环节必填字段缺失等风险。底层会调用 PUT /api/step/:id?action=<action>，但业务推进应优先使用 step submit，不要让 Agent 手写 raw API。

通用 raw API 仍可用于排查和未封装接口，但写操作需要显式确认：

bpmax-cli --config-dir <config_dir> api PUT /step/<step-id>?action=approve \
  --profile <profile> \
  --data @payload.json \
  --confirm-mutating \
  --format json

raw API 不会替代 typed command 的能力语义。POST /project 和 POST /project/<anything> 在 raw 模式下会被硬阻断，避免把搜索、调试或未知路径误打到项目创建分支。项目查询使用 project list 或 project search；项目创建使用 project create。

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 使用

Agent 使用 BBS 时，必须沿用 init 返回的 config_dir/profile。

查看远端 BBS

bpmax-cli --config-dir <config_dir> bbs list --profile <profile> --format json
bpmax-cli --config-dir <config_dir> bbs show <key-or-id> --profile <profile> --format json

创建 BBS

bpmax-cli --config-dir <config_dir> bbs create \
  --name "预算查询" \
  --scene "预算分析" \
  --zip ./skill.zip \
  --profile <profile> \
  --format json

升级 BBS

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

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

同步 Catalog

bpmax-cli --config-dir <config_dir> bbs sync --agent codex --profile <profile> --format json

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

使用前确保安装

bpmax-cli --config-dir <config_dir> bbs ensure <key-or-id> \
  --agent codex \
  --profile <profile> \
  --format json

bbs ensure 会检查隔离目录下是否已安装该 BBS，并对比远端最新版本：

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

安装、更新和卸载

bpmax-cli --config-dir <config_dir> bbs install <key-or-id> --agent codex --profile <profile> --format json
bpmax-cli --config-dir <config_dir> bbs update <key-or-id> --agent codex --profile <profile> --format json
bpmax-cli --config-dir <config_dir> bbs uninstall <key-or-id> --agent codex --profile <profile> --format json

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

本地单用户终端可以省略 --config-dir，继续使用默认 ~/.bpmax。

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 命令，并保留 --config-dir。

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

业务动作前：

bpmax-cli --config-dir <config_dir> bbs gate <skill-key> \
  --stage preflight \
  --input @input.json \
  --profile <profile> \
  --format json

业务动作后：

bpmax-cli --config-dir <config_dir> bbs gate <skill-key> \
  --stage verify \
  --input @result.json \
  --profile <profile> \
  --format json

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

推荐工作流

使用者

  1. Agent 场景先执行带 --profile-scope <TRUSTED_RUNTIME_SCOPE> 的 bpmax-cli init
  2. 复制 init 返回的 next_commands，确认 profile、授权和 BBS 状态
  3. 执行带 --config-dir 的 bpmax-cli bbs sync 同步 Catalog
  4. 根据业务需求选择 BBS
  5. 执行带 --config-dir 的 bpmax-cli bbs ensure 安装或更新目标 BBS
  6. 按 BBS 文档执行具体业务命令
  7. 审批、批量处理等高风险业务按 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 不存在

Agent 场景先检查是否使用了 init 返回的 --config-dir：

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

本地单用户终端可继续使用：

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

如授权已失效，重新执行 bpmax-cli init。Agent 场景重新初始化时仍需传入可信 --profile-scope <TRUSTED_RUNTIME_SCOPE>。

Agent 能看到其它用户或会话档案

说明后续命令很可能遗漏了 --config-dir <config_dir>，或 Agent 没有从可信 runtime metadata 传入 --profile-scope。不要继续使用共享 ~/.bpmax/config.json，应重新执行隔离初始化，并只复制 init 返回的命令。

API Key 权限不足

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

如果 capabilities refresh 返回缺少某个能力，例如 project.search、project.create、step.submit 或 bbs.ensure，说明当前用户虽然已登录，但服务端未授权该 CLI 场景。应先补权限或切换用户，不要改用 raw API 绕过。

CLI 终端被禁用或未注册

如果命令返回 CLI terminal is disabled，说明管理员在“CLI 终端管理”中禁用了该终端。需要管理员确认并重新启用，或重新初始化新的受控终端。

如果返回 CLI terminal is not registered，新版 CLI 会自动清理本地旧 terminal_id 并重新注册一次。如果重试后仍失败，检查当前 API Key 是否仍有效、平台是否已执行 CLI 终端管理相关 migration、以及 huanpingtong-server 是否已升级到支持 /api/cli/terminals/register。

平台版本不支持 CLI 治理

如果新版 CLI 连接旧平台时提示“不支持 CLI 治理能力”，说明 huanpingtong-server 还没有 /api/cli/capabilities、/api/cli/terminals/register、/api/cli/audit/start、/api/cli/audit/finish 等接口。升级平台后再使用新版 CLI 执行业务命令。

下载地址返回登录页

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

处理方式：

  • 先更新到最新 bpmax-cli
  • 重新执行带 --config-dir 的 bpmax-cli bbs show <key-or-id> 查看下载信息
  • 使用带 --config-dir 的 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、输入或业务前置条件，而不是默认绕过。