BPMAX CLI Agent 首次接入执行契约

本页是提供给 OpenClaw、Codex、Claude、Gemini 等 Agent 的执行规范，不是面向人类用户的安装教程。首次接入时，Agent 必须在安装或运行 bpmax-cli 之前完整读取本页，再严格按顺序完成安装、授权、profile 隔离、capability 检查和 Skill 同步。

人类用户入口、可复制提示词和场景说明见 通过 Agent 使用 BPMAX CLI。

执行前输入

开始前，Agent 必须获得：

  • 用户提供的完整 BPMAX 页面地址。
  • 当前 Agent 类型，例如 openclaw 或 codex。
  • 可信 runtime 提供的 profile-scope；禁止从用户自然语言、环境名称或 BPMAX 地址猜测。
  • 当前交互通道，例如 terminal、feishu 或 json。

缺少 BPMAX 页面地址时向用户索取。缺少可信 profile-scope 时停止，不得退回共享配置目录；只有用户明确说明这是本机单用户环境时，才能评估 --single-user。

OpenClaw 通常使用 --agent openclaw，并从真实租户、channel、用户或 peer/session 元数据构造 profile-scope。长期运行的 OpenClaw 实例不得让多个用户共享同一个 profile 或默认 ~/.bpmax。其他 Agent 同样必须传入自己的真实 adapter 名称和可信隔离范围。

强制执行顺序

Agent 必须按以下顺序执行，不得跳步：

读取本页 -> 安装或更新 CLI -> init -> 等待用户完成授权
-> 执行 next_command -> auth status -> capabilities refresh
-> 同步并读取相关 Skill -> 配置任务先初始化并进入本地配置目录 -> 进入具体任务

任何步骤失败都必须停在当前阶段，报告失败原因和下一项可恢复操作，不得把未完成状态汇报为已就绪。

Agent 必须遵循的接入规则

1. 安装与版本检查

优先安装最新 beta：

npm i -g bpmax-cli@beta
bpmax-cli --version
bpmax-cli --help

已有安装使用：

bpmax-cli update

不要只更新二进制而跳过内置 Skill 同步。

2. 初始化隔离上下文

Agent runtime 必须提供可信的 profile-scope。它应来自 channel、peer/user、租户、会话或 runtime metadata，不能由 LLM 从用户输入猜测。

bpmax-cli init \
  --agent <agent> \
  --channel <channel> \
  --url "<BPMAX_URL>" \
  --name local \
  --profile-scope "<TRUSTED_RUNTIME_SCOPE>" \
  --format json

<agent> 必须替换为当前运行时，例如 openclaw、codex、claude 或 gemini；不得为了沿用示例而固定写成与当前运行时不一致的值。

init 返回后必须：

  1. 向用户展示 message_card.authorization_url 和 message_card.user_code。
  2. 用户确认授权完成后，逐字执行 message_card.next_command。
  3. 只使用返回的 profile 和 config_dir。
  4. 后续命令复制 next_commands 中的 --config-dir 前缀。
  5. 不得裸跑共享 ~/.bpmax 下的 profile、auth 或 BBS 命令。

3. 校验授权与 capability

优先复制 init 返回的检查命令。需要手工检查时：

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

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

缺少 capability、终端被禁用或平台不支持 CLI 治理时必须停止。不得改用 raw API 绕过白名单。

4. 配置任务先初始化本地配置目录

授权与本地配置目录初始化是两个独立阶段。查询项目、处理待办等任务不需要 sysconfig 目录；修改流程、表单、列表、详情、导航、数据集、角色、API 平台等配置前，必须先完成本步骤。

先根据平台返回的配置库环境确定 <env>，再初始化或绑定本地目录：

bpmax-cli --config-dir <config_dir> config workspace init <env> \
  --workspace-dir <local-sysconfig-dir> \
  --profile <profile> \
  --format json

cd <local-sysconfig-dir>

后续所有配置命令都必须从该目录或其子目录执行。CLI 会向上识别最近的有效配置根目录，要求同时存在 AGENTS.md、think_configuration/、think_flow/ 和 think_form_template/，并核对当前 profile 的 sysconfig_repo_path 绑定。

  • 不要求 AGENTS.md 包含新版 marker，旧格式文件可以使用。
  • 不得在普通代码仓库、其它 profile 的配置目录或相邻同名前缀目录中执行配置命令。
  • 不得为绕过错误自动切换 profile。
  • config latest pull/diff <env> 还必须与当前目录绑定的 env 完全一致。
  • 这里的本地配置目录不是 BPMAX 的 w:xxx 业务工作区。

如果 CLI 返回 config_workspace_required、config_workspace_profile_mismatch 或 config_workspace_environment_unbound，必须停止，不得读取 work、生成 payload 或发起远端配置请求。重新执行 config workspace init 修复目录或绑定，进入正确目录后重试。

5. 先查记忆，再执行非简单任务

流程、配置、数据集、角色、导航、BBS 和 E2E 等非简单任务先执行：

bpmax-cli --config-dir <config_dir> memory search \
  --scope all \
  --query "<环境 流程或对象 任务>" \
  --profile <profile> \
  --format json

记忆只作为历史线索。易变化的 ID、权限、线上配置和项目状态必须重新 readback。

6. 路由到正确 Skill

Agent 必须先读取与目标对象匹配的 BPMAX Skill：

  • 流程模板：bpmax-flow-template-editor
  • 表单模板：bpmax-form-template-editor
  • 列表模板：bpmax-list-template-editor
  • 筛选模板：bpmax-filter-template-editor
  • 项目详情：bpmax-project-detail-template-editor
  • 数据集与字段：对应 dataset Skill
  • 导航：bpmax-nav-config-editor
  • 审批矩阵：bpmax-approval-matrix
  • E2E：bpmax-e2e-flow-test-operator
  • 任务书：bpmax-ai-taskbook

不得脱离 Skill 自行猜测配置结构。

7. 配置只走 typed CLI

执行配置前检查 adapter：

bpmax-cli --config-dir <config_dir> config adapters \
  --profile <profile> \
  --format json

配置必须经过：

export -> work diff -> 用户确认 -> lint/build -> submit diff
-> 用户确认 -> typed submit -> verify/readback -> 运行态验收

禁止：

  • 直接编辑 think_* 镜像并把它当成线上提交。
  • 通过浏览器配置页面保存流程或模板。
  • 使用 curl、raw API 或页面 fetch 绕过 typed adapter。
  • 复用过期 submit、workspace-flow 全量 payload 或旧 dry-run。

8. 项目创建与审批

项目创建优先使用：

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

不确定复杂字段结构时先使用 --explain-validation。人员、项目、预算、子表等复杂控件优先 --handoff-only 或 CLI 自动 handoff，由 Agent 在真实页面完成选择。

环节推进固定顺序：

step context -> step actions -> step requirements -> step submit dry-run
-> 用户确认 -> step submit --confirm

identity_unverified=true、missing_required_inputs 非空或当前用户不可处理时必须停止。

9. 正式 E2E 必须由用例驱动

正式测试第一步必须是：

bpmax-cli test-suite run start \
  --scenario <scenario> \
  --case-id <case-id> \
  --profile <profile> \
  --latest-proof <proof.json> \
  --format json

每次只执行 execution manifest 返回的当前步骤。真实浏览器步骤必须保存本轮截图、URL、DOM 摘要和 console/network 证据。

用户明确要求重新运行时，不能查找旧报告代替执行。--diagnostic 结果不能记录为 pass。

10. 发现 bpmax-cli 问题时

稳定可复现的 CLI 缺陷可以自动提报，但必须先 lint 和 dry-run：

bpmax-cli issue lint --title "<标题>" --description-file <issue.md> --format json
bpmax-cli issue report --title "<标题>" --description-file <issue.md> --label bug --dry-run --format json
bpmax-cli issue report --title "<标题>" --description-file <issue.md> --label bug --format json

确认正文不包含凭据、客户敏感数据或大段 raw payload 后，才允许正式创建。客户业务配置问题不能误报为 CLI issue。

Agent 完成初始化后的汇报格式

Agent 至少应向用户汇报：

- CLI 版本：<version>
- 目标环境：<origin>
- profile：<profile>
- config-dir：已隔离（不输出敏感内容）
- 授权状态：<authorized / blocked>
- capability：<available / missing list>
- 已同步 Skill：<summary>
- 下一步：现在可以直接用自然语言描述流程、配置或测试目标

失败时的停止条件

以下情况不得继续状态变更：

  • 用户尚未完成授权。
  • profile 或 origin 与目标环境不一致。
  • 配置任务未进入已初始化且与当前 profile/env 匹配的本地 sysconfig 目录。
  • capability 缺失或探查失败。
  • typed adapter 不支持目标 domain。
  • 缺少线上最新 readback 或 base hash。
  • lint 未通过。
  • 用户尚未确认 work/submit diff。
  • E2E 没有正式用例、execution manifest 或本轮证据。