文档目录与维护规范

本页定义 bpmax-cli 文档的读者、目录职责和后续演进方式，避免每次新增能力都继续堆入单个 README。

读者分层

人类用户

主要阅读 README.md、能力索引、配置、Agent 用法和 E2E 页面。正文应从业务目标和可复制提示词开始，不要求用户先理解 CLI 参数。

Agent

agent-quickstart.md 主要提供给 OpenClaw、Codex 等 Agent，使用明确的必须、禁止、停止条件和可执行命令。它不是面向普通用户的宣传或教程页面。

高级实施与开发人员

可以阅读各专题末尾的高级命令、对象身份、证据结构和排障说明。

本轮兼容目录

docs/develop/bpmax-cli/
├── README.md
├── agent-quickstart.md
├── capabilities.md
├── configuration-workflow.md
├── agent-usage.md
├── e2e-testing.md
├── business-skill.md
├── documentation-architecture.md
└── images/

本轮不移动 README.md、agent-quickstart.md 和 business-skill.md，避免已有公开 URL 和外部 Agent 提示词失效。

页面职责

页面主要读者只放什么
README人类场景入口、职责边界、对话示例
agent-quickstartAgent安装前必须读取的执行契约、初始化顺序、MUST/禁止项、停止条件
capabilities人类与实施“我想做什么”到能力的映射
configuration-workflow人类与实施安全配置闭环和各配置对象场景
agent-usage人类memory、taskbook、matrix、plugin、issue
e2e-testing人类与测试人员正式用例、真实页面和本轮证据
business-skill人类与 Skill 作者BBS/plugin Skill 发现、gate 和版本
documentation-architecture维护者信息架构和内容质量门禁

二期目标目录

当 VuePress 支持 redirect 或 alias，并为旧 URL 配置永久兼容后，可以迁移为：

bpmax-cli/
├── getting-started/
├── configuration/
├── agent-workflows/
├── testing/
├── extensions/
└── reference/

建议归属：

  • getting-started/：人类首次使用、Agent 接入和授权。
  • configuration/：typed adapters、domain 工作流和配置仓库。
  • agent-workflows/：memory、taskbook、matrix 和 issue。
  • testing/：test-suite、E2E、缓存和报告。
  • extensions/：BBS、plugin skills 和 recipe。
  • reference/：命令、schema、错误代码和兼容矩阵。

没有 redirect 能力前不得直接移动公开页面。

新能力的文档门禁

每个新增 CLI 能力至少补充：

  1. 一个用户能理解的业务场景。
  2. 一段可直接发送给 Agent 的提示词。
  3. 用户需要提供的信息。
  4. Agent 必须执行的安全门禁。
  5. 至少一个人类确认点。
  6. 最终结果和证据示例。
  7. 必要时提供高级 CLI 命令。

只增加 --help 参数说明不算完成文档。

提示词规范

提示词应采用“最短有效输入”原则：只要求用户说明业务目标、目标对象、允许修改范围和非默认验收要求。已经由 Agent 执行契约、BPMAX Skill 或 CLI lint 强制保证的步骤，不得要求用户在提示词中重复背诵。

例如，用户说“请重新运行采购申请完整测试”已经足够。逐步骤正式用例、真实用户页面、本轮证据隔离、禁止复用旧报告和缓存自动更新，均由 E2E Skill 自动执行，不应继续堆进用户提示词。

好的提示词应包含：

  • 目标环境或当前目录边界。
  • 业务对象和目标。
  • 允许修改的范围。
  • 用户额外要求的停止点或验收结果。

示例：

请读取线上最新采购申请表单，只优化布局。
不允许改字段、脚本、校验和联动。
先列出准备调整的布局和业务逻辑零变化证明，等我确认后再继续。

避免只有命令或内部字段：

错误示例：export 990702139 然后改 JSON 并 submit。

内容边界

  • 人类正文解释“为什么”和“何时确认”。
  • Agent 规范解释“必须怎么执行”和“何时停止”。
  • CLI 命令解释“高级用户如何复现”。
  • 平台内部 API、完整 payload 和实现细节只在确有排障价值时出现。
  • 任何示例不得包含真实 token、手机号、Cookie、客户敏感数据或本机绝对路径。

发布检查

文档发布前必须：

  • 用当前源码 --help 核对命令名称。
  • 检查内部链接和 sidebar。
  • 运行 changelog、构建和 git diff --check。
  • 打开构建后的本地站点检查新增页面。
  • 保存本轮浏览器截图。
  • 确认旧公开 URL 仍可访问。