nocobase-workflow-manage

目标

通过 nb api workflow 端到端管理 NocoBase 工作流。

1. 要求已通过身份验证的 nb CLI。
2. 在当前任务中首次使用某个子命令前，先运行一次 -h。
3. 仅使用工作流专用 CLI 接口；不要改用通用 CRUD 或源代码编辑。

范围

• 检查、创建、更新工作流，管理版本、复制、启用并诊断工作流。
• 配置触发器和顺序节点链。
• 移动、复制、测试或删除节点和分支。
• 检查执行记录和失败的作业。
• 通过 flowSurfaces 创建绑定工作流的审批界面。

非目标

• 安装或设置 nb 身份验证。
• 数据模型设计；请使用 nocobase-data-modeling。
• 普通页面、选项卡、弹窗或路由；请使用 nocobase-ui-builder。
• 删除整个工作流。
• 审批模式配置。
• 虚构类型、字段、键、筛选条件或求值函数。

输入约定

环境与工具

• 遇到身份验证或授权错误时停止。
• 对于 expression，加载相应的 formula.js 或 math.js 参考文档；绝不虚构函数。

筛选条件编写门槛

在编写任何工作流节点/触发器 filter 或 condition，或任何用户/受派人查询对象之前，先加载 nocobase-utils 技能的 filter 主题，然后在当前任务中阅读 筛选条件格式。无论自然语言中的比较看起来多么直观，这一步都不可省略；相对链接仅指向确切的文档位置，不能替代技能调用。

1. 阅读目标集合的字段元数据，并确定末端字段的前端接口/类型。
2. 仅从该字段组的文档允许列表中选择运算符。
3. 对于日期字段，将“早于/小于”映射为 $dateBefore，“晚于/大于”映射为 $dateAfter，“不早于/至少/大于或等于”映射为 $dateNotBefore，“不晚于/至多/小于或等于”映射为 $dateNotAfter。绝不要在日期字段上使用 $lt、$lte、$gt 或 $gte。
4. 保持配置中有文档说明的筛选条件格式，并在变更前核对最终的字段/运算符组合。

商业插件能力门槛

变更前，确认所需插件已安装并启用：

能力	插件
审批和审批界面	@nocobase/plugin-workflow-approval
Webhook	@nocobase/plugin-workflow-webhook
子流程	@nocobase/plugin-workflow-subflow

如果插件不可用，请指出所需前置条件并停止该操作。绝不要用 manual 节点替代用户要求的审批语义。请参阅商业插件门槛。

强制澄清门槛

• 只询问尚未明确的创建时选项、破坏性操作、高风险事项或负责人选择；最多进行两轮，每轮最多三个问题。
• 对于之后可以编辑且确定性至少达到 70% 的细节，继续操作；变更后再核实。
• 变更前必须确定唯一目标和准确的预期最终状态。
• 不要询问用户指的是哪种复制模式；根据以下门槛推断，并在变更前说明所选结果。

工作流更新与复制意图判断

用户通常描述的是变更，而非技术修订。根据期望结果选择处理方式：

意图	特征	处理方式与结果
修改现有工作流	更新/调整逻辑、触发器、条件或节点	获取 nodes 和 versionStats。如果 versionStats.executed > 0，先为同一工作流创建修订；否则直接编辑。绝不创建独立工作流。
创建新版本	明确提出新版本/修订、保留历史记录或后续版本	使用相同的 key 创建修订。版本的执行次数从零开始；历史记录和 key 级汇总统计会保留。
复制工作流实体	复制/克隆/另存为、另一个流程/模板、重命名副本、重置统计信息，或仅说“复制此工作流”	使用新的 key 创建独立工作流；执行次数和历史记录从空开始。

优先级：明确要求版本连续性 → 修订；明确要求独立身份 → 独立副本；具体行为变更 → 更新；只说复制工作流 → 独立副本。

仅使用以下修订调用：

# Same workflow, new version
nb api workflow workflows revision \
  --filter-by-tk <source-id> \
  --filter '{"key":"<source-key>"}'

# Independent workflow
nb api workflow workflows revision \
  --filter-by-tk <source-id>

• 同一工作流模式要求使用精确的顶层控制对象 {"key":"..."}。绝不将其嵌套在 $and/$or 中、放入请求正文，或使用空筛选条件。
• 创建独立副本时省略 filter。
• 继续修改前先读取结果：修订意味着 id 变更而 key 不变；独立副本意味着两者都变更。
• CLI 会将 filter 作为一个 JSON 查询对象发送；仓库仅在直接读取 filter.key 时切换模式。

集合解析判断

对于任何必需但不明确的 collection：

1. 使用 nocobase-data-modeling 检查现有集合和字段。
2. 置信度达到或超过 70% 时使用匹配结果。
3. 否则询问用户要识别或创建哪个集合。

这适用于绑定集合的触发器、操作、计划任务和节点。请参阅工作流约定。

参考资料加载指南

• 版本和复制操作：工作流 CLI
• HTTP 传输：工作流 HTTP API
• 键、版本和统计信息：工作流模型
• 编写配置：触发器、节点和约定
• 任何节点/触发器筛选条件、条件表达式或负责人查询：加载主题为 filter 的 nocobase-utils，然后在选择运算符前阅读筛选条件格式
• 审批 UI：审批 UI 索引和界面约束

最终命令范围

• 工作流：workflows list|get|create|update|revision|sync|execute
• 节点：workflows nodes create；flow-nodes get|update|destroy|destroy-branch|move|duplicate|test
• 诊断：executions list|get；jobs list|get|resume
• 审批界面：flowSurfaces get|catalog|applyApprovalBlueprint|addBlock|addField|addAction|compose|configure|setLayout

标志请参阅 CLI 索引，底层请求格式请仅参阅 HTTP API 索引。

审批界面入口

• 审批界面由 approvalUid 或 taskCardUid 绑定；它们不是普通页面。
• 发起人界面需要 ApplyFormModel；审批人界面需要同时具备 ApprovalDetailsModel 和 ProcessFormModel。
• 只能使用实时目录返回的操作和区块；不要手动修改已协调节点的操作配置。
• 首次设置或替换时使用 applyApprovalBlueprint。
• 执行局部操作前，先解析绑定的根节点。
• 任务卡支持 fields + layout；仅编辑布局时使用 setLayout。
• 从 catalog.node.configureOptions.fieldComponent.enum 读取字段组件选项。
• 编写前先加载审批界面索引；对于载荷规则，加载界面约束。

安全门槛

1. 创建工作流时将其设为禁用；启用前必须获得确认。
2. 编辑或复制前，先执行更新与复制门槛。
3. 每次变更或破坏性调用都必须指定具体目标。
4. 按顺序创建节点，并使用 upstreamId 将它们串联起来。
5. 对每个已持久化的节点/触发器筛选条件应用筛选条件编写门槛；将工作流数据/查询筛选条件包装在 $and 或 $or 中。修订控制请参阅意图门槛。
6. 使用返回的节点 key 引用节点结果，绝不使用其数字 id。
7. 在下游使用原始 JSON 前，先用 json-variable-mapping 或 json-query 对其建模。
8. 回读每次变更。
9. 手动执行前必须获得确认。

工作流

规划阶段

明确意图、触发器、节点链、同步模式、集合、筛选条件、映射、变量和原始 JSON 建模方式。如果需要任何已持久化的筛选条件，使用主题 filter 加载 nocobase-utils，阅读筛选条件参考文档，并在起草操作符前解析每个末端字段的类型。说明计划以及对历史记录/统计数据的影响。

对于审批界面，将请求分类为整个界面的设置/替换或局部编辑，然后加载审批界面参考文档。

创建新工作流

1. 解析集合。
2. 创建时设置 enabled: false。
3. 配置触发器。
4. 按照安全门槛构建节点链。
5. 完成验证清单。

编辑现有工作流

1. 获取包含 nodes 和 versionStats 的工作流。
2. 执行更新与复制门槛。
3. 仅变更已解析的可编辑 id。
4. 完成验证清单。

诊断失败的执行

1. 按 workflowId 列出执行记录，最新记录排在前面。
2. 获取包含任务、工作流和节点的执行记录；初始时省略任务结果。
3. 查找状态为 -1（失败）、-2（错误）或 -3（已中止）的记录。
4. 获取失败任务并检查 result。
5. 修复配置，然后遵循安全门槛。

错误处理

• 400/422：修正报告的类型、字段或关联错误，然后重试。
• 身份验证错误：停止并请求恢复访问权限。
• 节点创建失败：修复或移除该节点后，再创建下游节点。
• 修订失败：重试前重新获取状态。

验证清单

验证以下内容：

1. 工作流类型、标题、同步模式和启用状态。
2. 触发器配置。
3. 节点数量、顺序、类型、配置和 upstreamId 链。
4. 必需的变更筛选条件非空。
5. 修订/复制的 id 和 key 与所选模式相符。
6. 审批根节点和界面回读结果与预期路由相符。
7. 在下游使用原始 JSON 前已对其建模。
8. 必需的商业插件已启用。
9. 返回的变更状态与请求的结果相符。
10. 已根据末端字段的前端操作符组，检查每个已持久化筛选条件的字段/操作符组合；日期字段不包含数字比较操作符。

插件版本控制修订规则

• 每轮都加载 nocobase-revision。如果不可用，请忽略本节，且不要提及此事。
• 在该技能确认 nb revision create 可用之前，不得透露任何修订信息。
• 如果可用，请在最终回复前立即作出一次修订决定；报告已创建的修订，或说明未创建修订的具体原因。

参考资料

• 商业插件准入门槛
• 审批界面索引和界面约束
• 工作流模型和工作流字段
• 约定
• CLI和HTTP API
• 触发器和节点
• 筛选器格式和求值器
• 数据建模技能
• 官方工作流手册和修订指南 [已验证：2026-04-09]