BPMAX Business Skill（BBS）

BPMAX Business Skill（BBS）是面向 BPMAX 业务场景的可安装 Skill 包。它把流程查询、表单填写、审批处理、数据分析、跨页面操作等能力沉淀为标准化说明和命令，让 Agent 可以按稳定规则完成重复业务任务。

BBS 通常由业务人员、实施人员或开发者维护，通过 bpmax-cli 发布到 BPMAX 远端，再由使用端按需同步和懒加载安装。

BBS 是什么

BBS 本质上是一个标准 Skill zip 包，根目录包含 SKILL.md，可选包含 bbs.json、脚本、示例输入和测试文件。

  • SKILL.md 描述这个业务能力的触发场景、操作步骤、命令和注意事项。
  • bbs.json 用于声明 lint 和业务 gate，约束发布质量和关键业务动作。
  • zip 包发布到 BPMAX 后，会形成可版本化管理、可安装、可升级、可卸载的组织级业务能力。

BBS 不替代 BPMAX 的流程、表单和权限体系。它是在这些能力之上，为 Agent 增加一层可复用的业务操作说明。

适用场景

BBS 适合沉淀稳定、可重复、需要上下文判断的 BPMAX 操作：

  • 审批批量处理，例如清单外入库审批、预算审批、合同审批。
  • 流程单创建引导，例如出差申请、报销申请、供应商创建。
  • 业务查询和统计，例如预算使用情况、库存异常、销售数据汇总。
  • 跨页面操作沉淀，例如先查流程、再读详情、再打开页面确认字段。
  • 组织内能力复用，例如总部维护一个业务 Skill，各部门 Agent 按需安装。

不建议把 BBS 用于一次性临时脚本、规则尚不稳定的探索任务，或需要直接修改 BPMAX 平台代码的功能。平台功能改造应通过正常前后端开发完成，BBS 只负责把已有业务能力组织成可执行的 Agent 操作规范。

推荐开发方式

推荐使用 Codex + GPT 模型开发 BBS。BBS 的价值不只是写一份说明，而是把真实页面、接口、字段、权限和异常路径分析清楚，再沉淀为 Agent 可以稳定执行的 Skill。

推荐使用 Codex，是因为 BBS 开发通常需要同时完成代码阅读、CLI 调用、浏览器观察、接口分析、Skill 编写和回归验证。Codex 可以在同一个上下文中连接本地仓库、运行 bpmax-cli、查看页面行为，并把发现的问题直接沉淀到 SKILL.md 和 bbs.json 中，减少“只写说明但没有验证真实业务链路”的风险。

开发前，先在 Codex 中初始化 bpmax-cli 并连接目标环境。Agent 场景必须完成隔离初始化，避免不同用户、会话或 Agent 共享 BBS 安装记录：

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

初始化后只使用 init 返回的 config_dir 和 profile。BBS state、安装记录、Skill stamp 和 profile recipes 都会落在隔离 config_dir 下。

从 bpmax-cli@0.1.43 起，BBS 开发和执行中的远端业务命令还会进入 CLI 终端管控链路。CLI 会注册终端、刷新服务端能力白名单，并把每次命令写入审计。BBS 文档和脚本应继续使用 typed command，让平台能识别稳定 capability，例如 project.search、project.create、step.submit、bbs.ensure。

连接完成后，让 Codex 结合浏览器能力分析 BPMAX 页面：

  • 打开目标业务页面，确认入口、列表、详情、创建页和审批页。
  • 观察页面请求，识别真实接口、请求参数、返回字段和错误信息。
  • 使用 Chrome DevTools MCP 或 Playwright 调试自动化产生的问题，例如表单预填失败、关联字段未选中、金额或日期数值错误、提交后校验不通过。
  • 对照 bpmax-cli 能力，优先使用 CLI 已封装命令；缺失能力再补 CLI 或通过页面交接。
  • 遇到 capability 缺失、终端禁用或平台版本不支持 CLI 治理时，停止 BBS 执行并提示管理员处理，不要改用 raw API 绕过。
  • 明确哪些字段可以自动填写，哪些字段必须让用户确认或在页面中选择。
  • 把高风险动作写入 guardrail，例如审批前必须展示 step context、读取 step actions 和 step requirements、批量处理必须确认范围。

开发流程

  1. 连接环境：在 Codex 中完成带 --profile-scope <TRUSTED_RUNTIME_SCOPE> 的 bpmax-cli init，确认返回 config_dir/profile/next_commands。
  2. 验证授权：复制 next_commands.auth_status，不要裸跑共享 auth status。
  3. 验证治理能力：必要时执行 capabilities refresh，确认目标场景具备 project.search、project.create、step.submit、bbs.ensure 等 capability。
  4. 分析业务：通过浏览器和带 --config-dir 的 CLI 查询流程、项目、表单模板、审批环节和接口数据。
  5. 定义 Skill：编写 SKILL.md，明确触发条件、输入信息、执行步骤、失败处理和用户确认点。审批或推进类 BBS 必须使用 step context/actions/requirements/submit 安全链路，不要让 Agent 裸调 api PUT /step/:id。
  6. 增加 gate：审批、批量修改、提交类 BBS 建议增加 bbs.json，声明 preflight 和 verify。
  7. 本地检查：运行 bpmax-cli bbs lint --zip ./skill.zip --format json。
  8. 发布升级：使用带 --config-dir 的 bpmax-cli bbs create 或 bpmax-cli bbs upgrade 上传到 BPMAX。
  9. 安装验证：使用带 --config-dir 的 bpmax-cli bbs sync 更新 Catalog，再通过 bpmax-cli bbs ensure 安装并测试真实场景。

发布与使用

发布前先 lint：

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

创建或升级 BBS。Agent 场景使用隔离目录：

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

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

本地单用户终端可以继续省略 --config-dir 并使用默认 profile。

使用端先同步 Catalog，再按需安装具体 BBS：

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

需要业务 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

审批、通过、拒绝、推进一步等环节状态变更，应先在 BBS 中要求 Agent 执行：

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 返回 identity_unverified: true，说明项目或环节表单缺少可确认身份的字段，即使 ES 或简历附件文本命中了关键词，也不能自动推进。BBS 应要求 Agent 停止并展示项目/环节 URL 让用户确认。

如果 step requirements 或 step context.requirements 返回 missing_required_inputs，说明当前环节绑定表单仍有必填项缺失。BBS 应要求 Agent 先向用户确认这些字段，并通过 --data 补齐 payload，不得直接追加 --confirm。

真实提交必须先 dry-run，再在用户确认后追加 --confirm：

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、项目 ID、环节 ID、动作 label、requirements.can_submit 和风险提示都确认无误，才允许执行带 --confirm <confirmation-text> 的真实提交。未封装接口可用 bpmax-cli api --data @file.json --confirm-mutating 兜底，但审批推进类 BBS 应优先补 CLI 封装或使用 step submit。

Agent 后续不应自行改写这些命令。应复制 init 返回命令链或 BBS 文档中的命令，并保留 --config-dir <config_dir>。

CLI 治理对 BBS 的要求

BBS 发布包和运行说明需要遵守平台治理边界：

  • 项目查询使用 bpmax-cli project search --body @query.json，该命令会走 huanpingtong POST /api/project/list 的 ES 模式，并按 project.search capability 审计。
  • 项目创建使用 bpmax-cli project create --flow-id/--flow-type --json ...，让 CLI 先检查表单模板、复杂控件、流水号和 handoff 风险。
  • 环节推进使用 step context/actions/requirements/submit，不要用 raw API 拼 PUT /step/:id 作为 BBS 主路径。
  • BBS 下载、安装、升级使用 bbs sync/ensure/create/upgrade，不要手动复制远端 Skill 包。
  • raw API 仅用于排查未封装接口；POST /project 和 POST /project/<anything> 在 raw 模式下被硬阻断，不能作为项目创建或项目搜索方案。
  • 如果 capabilities refresh 缺少目标能力，BBS 应提示用户补权限或联系管理员，不应继续执行状态变更。
  • 命令审计会保存脱敏摘要。BBS 示例不要把真实 API Key、手机号、验证码、token 写入命令行或文档。

更多 CLI 命令和管理页面说明见 BPMAX CLI 使用说明。