Agent 首次接入 BPMAX CLI

这是一页给 Codex、OpenClaw、Claude、Gemini 等 Agent 使用的最短接入指南。目标是让 Agent 在所有 BPMAX 流程、审批、项目、表单和业务 Skill 场景中优先使用 bpmax-cli，并在多用户、多会话环境中隔离本地连接档案。

1. 安装 CLI

在 Agent 所在机器安装：

npm i -g bpmax-cli

确认命令可用：

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

已安装环境后续更新：

bpmax-cli update

2. 修改 Agent 定义

把下面这段加入 Agent 的系统指令、项目 AGENTS.md、OpenClaw agent definition 或同等配置中：

## BPMAX 操作规则

当用户提到 BPMAX、流程、流程单、审批、待办、项目、表单、预算、出差、报销、入库、库存、门店、经销商、业务 Skill 或 BBS 时，优先使用 `bpmax-cli`。

开始任何 BPMAX 操作前，先执行 `bpmax-cli init`。Agent 场景必须传入 `--profile-scope <TRUSTED_RUNTIME_SCOPE>`：

`TRUSTED_RUNTIME_SCOPE` 必须来自 Agent runtime、Gateway、channel metadata、当前用户 ID、租户 ID、会话 ID 等可信上下文，不能由 LLM 从自然语言里猜。

`init` 返回后：

1. 只使用返回的 `profile` 和 `config_dir`，不要自行拼接 profile 名。
2. 授权完成时逐字执行 `message_card.next_command`，不要从自然语言里重建 `auth complete` 命令。
3. 检查 profile、授权和 BBS 时逐字复制 `next_commands.profile_list`、`next_commands.auth_status`、`next_commands.bbs_list`。
4. 后续 `auth`、`config profile`、`flow`、`project`、`bbs`、`recipe` 等命令都必须保留返回命令中的 `--config-dir <config_dir>`。
5. 不要在共享 Agent runtime 中裸跑 `bpmax-cli config profile list`、`bpmax-cli auth status`、`bpmax-cli bbs ...`。
6. 远端业务命令必须使用 typed command，例如 `project search`、`project create`、`step submit`、`bbs ensure`，让 CLI 能执行终端注册、能力白名单校验和命令审计。不要为了绕过能力缺失改用 raw API。
7. 如果 CLI 返回“平台版本不支持 CLI 治理能力”“CLI terminal is disabled”或缺少 capability，必须停止并向用户说明原因，不能继续尝试手写接口。

流程单创建、审批、批量处理等状态变更必须走 `bpmax-cli`，不要手写 BPMAX 接口，不要手动拼接创建页链接。

环节推进、审批通过/拒绝、完成 step 时必须先执行 `step context`、`step actions` 和 `step requirements`。如果返回 `identity_unverified: true`，说明表单证据不足，不能只凭 ES 或附件文本命中自动推进。如果 `missing_required_inputs` 非空，必须先通过 `--data` 补齐当前环节必填内容。`step submit` 默认只 dry-run；只有用户确认后才允许追加 `--confirm <confirmation-text>` 执行真实提交。

<agent> 按实际环境填写：

codex
openclaw
claude
gemini
generic

3. 初始化 BPMAX 授权

为目标环境创建 Agent 隔离上下文：

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

init 会在 ~/.bpmax/agent-contexts/<agent>/<scope_hash>/ 下创建隔离配置目录，并返回 config_dir、profile、message_card.next_command 和 next_commands。

把命令返回的授权链接和验证码展示给用户。用户确认后，执行返回结果里的 message_card.next_command，不要从自然语言提示里猜命令。

授权完成后，CLI 会尝试注册当前终端并刷新服务端能力白名单。init 或 auth device complete 的 JSON 中可能包含 capabilities_probe，用于说明能力探查是否成功。探查失败不代表授权失败，但后续远端业务命令会在能力缺失或平台未升级时被阻断。

授权完成后检查时复制 init 返回的命令，例如：

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

需要人工排查能力时，可以执行：

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

Agent 对话初始化示例

4. 同步 BBS Catalog

授权成功后同步远端业务 Skill 目录。Agent 必须复制 next_commands.bbs_list 或显式保留 --config-dir：

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

bbs sync 只安装轻量 Catalog Skill，不会安装所有业务 Skill。

5. 使用 BBS

当用户提出具体业务需求时，先查找匹配的 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

使用前确保本地已安装并且是最新版本：

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

如果 BBS 声明了业务 gate，执行状态变更前后都要调用：

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 返回失败时停止，不要继续提交、审批或声称处理成功。

6. 常用 BPMAX 命令

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

审批或推进环节时，先 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

确认 dry-run 输出的 endpoint、payload、目标项目、requirements.can_submit 和风险提示无误后，再由用户明确确认并追加 --confirm <confirmation-text>。不要让 Agent 自行把“推进一步”解释成固定的 approve。

创建流程单使用 CLI 引导：

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

只有用户明确要求“打开页面填写”时，才允许生成 Web 表单接管链接，并且必须使用 project create 返回的链接。

7. 后续维护

每次新会话或切换环境时，先重新执行带 --profile-scope <TRUSTED_RUNTIME_SCOPE> 的 init。同一个 agent + scope 会复用同一个隔离目录；不同用户、会话或 Agent 会使用不同 config_dir。

后续命令继续复制 init 返回的 next_commands：

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

CLI 或内置 Skill 需要更新时：

bpmax-cli update

8. CLI 终端管控

新版平台会记录所有通过 API Key 连接的 CLI 终端和命令审计。Agent 不需要手动生成终端 ID；CLI 会在授权后自动注册，并在远端业务命令中携带终端、版本、命令、capability 和 request id。

管理员可以在 BPMAX 页面中进入：

系统配置 -> CLI 终端管理

页面会展示终端、用户、Agent、workspace、CLI 版本、最近活跃时间、状态和最近命令审计。命令审计会脱敏 --body、--data、API Key、token、手机号、验证码等敏感内容。

如果管理员禁用了某个终端，该终端后续业务命令会返回 CLI terminal is disabled。Agent 必须停止并提示用户联系管理员处理。

9. 最小排障

bpmax-cli: command not found：重新执行 npm i -g bpmax-cli
authenticated: false：重新执行带 --profile-scope <TRUSTED_RUNTIME_SCOPE> 的 bpmax-cli init ...
Agent 能看到其它用户或会话的连接档案：检查后续命令是否遗漏 --config-dir <config_dir>
没有权限：检查当前用户角色和 API Key 权限点
缺少 capability：执行 capabilities refresh 查看当前用户可用能力，补权限后重试
CLI terminal is disabled：当前终端已被管理员禁用，不能继续执行远端业务命令
平台版本不支持 CLI 治理能力：升级 huanpingtong-server 后再使用新版 CLI
找不到业务 Skill：先执行带 --config-dir 的 bbs sync，再 bbs list
BBS 版本落后：执行带 --config-dir 的 bbs ensure
checksum 不匹配：不要手动复制 Skill，使用 bbs ensure 重新安装