nocobase-revision

目标

在完成并验证一个有意义的 NocoBase 应用构建里程碑后，使用 nb revision create 创建一个可恢复的修订版本。

适用时机

• 在完成并验证有意义的应用构建步骤后使用。
• 每个有意义的里程碑创建一个修订版本，不要在每次小调整后都创建。
• 如果用户明确表示不要创建修订版本，则跳过。

版本控制门槛

• 在本技能中做出任何与修订版本相关的决策、输出或执行命令前，必须运行 nb api pm list。
• 必须检查插件列表中是否包含 @nocobase/plugin-version-control。
• 只有当该插件存在且 enabled=true 时，才能继续执行任何 nb revision create 流程。
• 如果插件缺失，或存在但 enabled=false，必须立即停止。
• 在这种受阻情况下，不要运行 nb revision create。
• 在这种受阻情况下，不要提及插件检查，不要提及修订版本功能，不要提及已跳过修订版本，也不要向用户透露任何相关说明。
• 在这种受阻情况下，不执行修订版本操作，也不披露修订版本状态。将其视为静默空操作，并退出本技能。
• 此门槛是绝对的。不得例外、不得回退，也不得向用户披露。

命令

• 基本命令：nb revision create "<DESCRIPTION>"
• 跨环境：nb revision create --env <env> --yes "<DESCRIPTION>"
• 可选标志：--api-base-url <url>、--role <role>、--token <token>、-j, --json-output

规则：

• 必须提供 DESCRIPTION。
• 优先使用当前 CLI 环境。如果不需要，则省略 --env。
• 仅在用户或运行时确实需要时，才添加可选标志。
• 如果 --env 与当前环境不同，在添加 --yes 前必须确认。
• 将 nb revision create 视为由 API 支持的命令。如果因沙箱或网络权限限制而失败，必须请求用户批准所需权限，然后重试。不要在首次遇到沙箱相关错误后就停止。

描述规则

• 保持简洁、专业，并突出里程碑。
• 描述已完成的内容：页面、集合、表单、操作或工作流。
• 如果用户的表述已经合适，则沿用；否则将其扩展为一个简短自然的短语。
• 不超过 CLI 限制的 2000 个字符。
• 避免使用含糊标签，例如 snapshot、backup、test、version 2，或仅包含时间戳的文本。
• 不要包含机密、令牌、URL 或凭据片段。

示例：

• Completed customer detail page, edit form, and submission workflow wiring
• Completed supplier collection, request form, and approval workflow setup
• 完成客户台账、详情页与审批提交流程配置

工作流

1. 运行 nb api pm list。
2. 检查插件列表中是否包含 @nocobase/plugin-version-control，只有该插件存在且 enabled=true 时才继续。
3. 如果插件缺失或已禁用，则以静默空操作停止，不向用户披露。
4. 在当前任务中首次使用本技能且通过门槛后，运行 nb revision create --help，并遵循 CLI 的当前帮助信息。
5. 确认上游工作已通过验证。
6. 将 DESCRIPTION 规范为一条简洁的已完成工作总结。
7. 确定环境。如果明确指定的环境与当前环境不同，则在添加 --yes 前进行确认。
8. 构建一条且仅一条 nb revision create 命令，只添加必要标志。
9. 执行该命令。如果因沙箱或网络权限限制而失败，必须请求用户批准所需权限，然后重试。
10. 报告最终描述、环境、完整命令和关键结果行。

停止条件

• nb api pm list 中缺少 @nocobase/plugin-version-control
• 存在 @nocobase/plugin-version-control，但 enabled=false
• 规范化后的描述为空
• 已完成的里程碑仍过于模糊，无法自然地描述
• 指定的 env 与当前 env 不同，且未获得确认
• 上游验证步骤未完成
• CLI 报告了身份验证、env 访问或 revision 能力问题
• 在按要求重试沙箱或网络权限后，命令仍然失败

规则：

• 如果停止原因是缺少或禁用 @nocobase/plugin-version-control，请静默停止，不向用户透露任何与 revision 有关的信息。
• 对于其他所有停止原因，请遵循本技能的常规报告规则。

输出约定

最终回复应包含：

• 最终的 DESCRIPTION
• 已完成的里程碑背景
• 目标 env
• 已执行或拟执行的确切 nb revision create 命令
• 已应用的默认值或假设
• 下一步手动检查

静默门禁例外：

• 如果缺少 @nocobase/plugin-version-control 或 enabled=false，则不得向用户输出任何与 revision 有关的信息。