Agent 工程化用法

当任务不只是执行一条命令，而是需要长期上下文、任务拆解、多轮 review、矩阵调试或缺陷提报时，可以让 OpenClaw、Codex 等 Agent 使用 bpmax-cli 的工程化能力。

配置任务的工程目录

配置工程必须先通过 config workspace init 初始化本地 sysconfig 目录，并在该目录或其子目录中执行。CLI 会自动检查 AGENTS.md、核心 think_* 目录和当前 profile 的初始化绑定；用户不需要在提示词中重复要求检查 cwd。

这个工程目录不是 BPMAX 的 w:xxx 业务工作区。目录门禁失败时应修复初始化绑定，不得切换 profile 猜测环境，也不得直接编辑 think_* 文件绕过 typed CLI。

先搜索 BPMAX Memory

用户通常无需专门提示。非简单 BPMAX 任务开始前，Agent 应自动搜索当前环境和类似任务的历史经验。

Agent 会使用：

bpmax-cli memory search \
  --query "<环境 flow_type 任务>" \
  --scope all \
  --profile <profile> \
  --format json

完成后只写可复用的 decision、task_learning、anti_pattern、environmental 或 convention。未完成任务只能写 session_state。

禁止写入 token、Authorization、验证码、手机号、完整 payload 和大段 API 响应。

先生成任务书

适合以下情况：

  • 涉及多个配置对象。
  • 需要多个 Agent 并行工作。
  • 有严格顺序、对象锁或停机点。
  • 用户要求先 review 再执行。

直接对 Agent 说：

先为这次 BPMAX 改造生成任务书，不要直接修改配置。

高级命令：

bpmax-cli taskbook init --out TASKBOOK.md --title "<标题>"
bpmax-cli taskbook lint --source TASKBOOK.md --format json
bpmax-cli taskbook lint-prompt --source <prompt.md> --format json

配置任务不能只写“修改流程”或“回读 hash”。必须引用对应配置 Skill 和该 domain 的专项约束。

多 Agent review

需要多 Agent 的场景：

  • 跨流程、表单、列表、数据集和导航的改造。
  • 安全门禁或 lint 实现 review。
  • 用户明确要求循环解决 P0/P1。

提示词：

请从运行时语义、CLI 绕过路径、Skill 一致性和测试覆盖四个角度并行 review。
汇总 P0/P1 后逐项修复，跑完整测试，再重复 review，直到没有 P0/P1。

不需要多 Agent 的场景：单个只读查询、单字段文案调整、已有明确修复点的小范围改动。

审批矩阵调试

请检查项目 <项目编号> 在指定审批环节为什么没有找到审批人。

高级命令：

bpmax-cli matrix owner-resolve \
  --flow-type <flow_type> \
  --node <node-id> \
  --project-id <project-id> \
  --profile <profile> \
  --format json

不要把矩阵应用创建成功等同于规则数据存在。

插件 Skill

流程里出现插件扩展时，Agent 应先检查插件是否在全站启用，以及插件是否声明 Agent lint Skill。

请检查这个流程中的插件配置是否正确。

高级命令：

bpmax-cli plugin skills list --profile <profile> --format json
bpmax-cli plugin skills state --profile <profile> --format json
bpmax-cli plugin skills ensure <plugin> --agent <agent> --profile <profile> --format json

插件是否启用按平台全站状态判断，不应错误绑定到单个 workspace。

自动提报 bpmax-cli 问题

可以自动提报：

  • 稳定可复现的 CLI 缺陷或回归。
  • typed capability 缺失。
  • lint 漏检或误拦截。
  • 危险默认行为或误导性诊断。
  • Skill 与实际 CLI 行为不一致。

不应自动提报：

  • 客户业务配置错误。
  • 临时网络波动。
  • 用户没有授权。
  • 证据不足的猜测。

提示词：

如果确认这是 bpmax-cli 自身问题，请提报问题。

高级命令：

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

主动提报 bpmax-cli BUG 使用 issue report。issue create 是通用 GitLab issue 创建入口，不作为 BUG 提报文档的默认主路径。正式创建成功后 Agent 必须返回 issue.web_url。

人类如何控制执行节奏

以下短提示词具有明确含义：

提示词Agent 应如何响应
“先出任务书”只生成和 lint 任务书，不执行配置
“执行任务书”按已确认任务书执行并维护进度
“继续”延续当前目标，不重新开始
“只修 P0/P1”review、修复、测试并循环到 P0/P1 清零
“先不要提交”最多执行 export、work diff、lint/build dry-run
“重新运行测试”创建本轮 run，重新执行用例，禁止复用旧证据
“commit and push”完成测试、提交并推送当前明确范围

Agent 的最终汇报

最终回复应回答：

  • 实际做了什么，而不是计划做什么。
  • 哪些 gate 已通过。
  • 哪些操作由真实页面完成。
  • 哪些结果只是 diagnostic 或 dry-run。
  • 生成了哪些 ID、URL、证据和 issue。
  • 哪些事情没有完成及原因。