Agent 首次接入 BPMAX CLI

这是一页给 Codex、OpenClaw、Claude、Gemini 等 Agent 使用的最短接入指南。目标是让 Agent 在所有 BPMAX 流程、审批、项目、表单和业务 Skill 场景中优先使用 bpmax-cli，并学会通过 BBS 懒加载业务能力。

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 操作前：

1. 执行 `bpmax-cli config profile list --format json` 确认 profile。
2. 执行 `bpmax-cli auth status --profile <profile> --format json` 确认授权。
3. 需要业务能力时，先执行 `bpmax-cli bbs sync --agent <agent> --profile <profile> --format json` 同步 Catalog。
4. 发现匹配 BBS 后，先执行 `bpmax-cli bbs ensure <skill-key> --agent <agent> --profile <profile> --format json`，再按该 Skill 指南处理。

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

<agent> 按实际环境填写：

codex
openclaw
claude
gemini
generic

3. 初始化 BPMAX 授权

为目标环境创建 profile：

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

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

授权完成后检查：

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

4. 同步 BBS Catalog

授权成功后同步远端业务 Skill 目录：

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

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

5. 使用 BBS

当用户提出具体业务需求时，先查找匹配的 BBS：

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

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

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

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

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

6. 常用 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 approval-context <project-id> --step-id <step-id> --profile demo-default --format json

创建流程单使用 CLI 引导：

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

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

7. 后续维护

每次新会话或切换环境时：

bpmax-cli auth status --profile <profile> --format json
bpmax-cli bbs sync --agent <agent> --profile <profile> --format json

使用某个业务 Skill 前：

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

CLI 或内置 Skill 需要更新时：

bpmax-cli update

8. 最小排障

bpmax-cli: command not found：重新执行 npm i -g bpmax-cli
authenticated: false：重新执行 bpmax-cli init ...
没有权限：检查当前用户角色和 API Key 权限点
找不到业务 Skill：先执行 bbs sync，再 bbs list
BBS 版本落后：执行 bbs ensure
checksum 不匹配：不要手动复制 Skill，使用 bbs ensure 重新安装