#工作流快速开始

本教程从一段业务需求出发，由应用 Agent 判断实现方式并完成开发，再由业务管理员启用、手动运行和查看执行记录。

#案例目标

我们要为一个已有库存模块的应用增加自动补货处理：

1. 商品库存发生变化后，在后台检查当前库存；
2. 目标库存由业务管理员设置，默认值为 100；
3. 库存不足时创建补货记录，否则只记录检查结果；
4. 管理员可以查看每次处理经过的步骤和结果；
5. 同一次库存变化被重复通知时，不能重复创建补货记录。

如果需求只是“读取库存，判断后写入一条记录”，普通 Service 或后台任务会更简单。本教程选择工作流，是因为业务还明确要求管理员参数、版本化流程、每次运行的独立记录、路径观测和重复事件处理。缺少这些生命周期要求时，不应仅因代码包含多个步骤或条件分支就采用工作流。

#开始之前

• 当前目录是一个基于 NocoBase 3 应用模板创建的应用；
• 应用配置使用根目录的 config.yml（如需密钥，请在其中引用环境变量）；
• 应用已经安装并注册 @nocobase/app-plugin-workflow；
• 应用已有库存与补货相关的 Collection 或 Service，或者允许 Agent 在确认后补齐；
• 开发者可以让应用 Agent 读取和修改源码；
• 业务管理员能够登录应用并进入“自动化”设置。

如果应用的 .agents/skills/ 中没有工作流 Skill，先在应用根目录运行：

pnpm nocobase skills sync

.agents/skills/ 是同步生成的本地内容，不要直接修改。

#1. 向应用 Agent 描述业务需求

不需要先学习工作流 DSL，也不需要替 Agent 设计内部标识。直接描述业务：

我们的应用需要增加库存补货处理：

• 当商品库存发生变化时，判断当前库存是否低于目标库存；
• 目标库存允许业务管理员配置，默认值为 100；
• 如果库存不足，创建一条补货记录，记录商品、当前库存和需要补充的数量；
• 如果库存充足，只记录本次检查结果，不创建补货记录；
• 处理需要在后台执行，管理员要能查看每次处理经过了哪些步骤、最终结果是什么；
• 同一次库存变化即使重复通知，也不能重复创建补货记录。

请先检查当前应用已有的数据结构、Service、插件和 Skill，判断是否确实需要工作流并说明理由，再完成实现和验证。遇到会改变业务设计的信息缺口时先向我确认。

提示词只需准确表达业务事件、规则、可配置项、副作用、观测和去重要求。检查真实代码、不虚构节点、选择稳定标识以及报告验证结果属于 Workflow Skill 的职责，不需要在每次需求中重复完整的技术规程。

#2. 审核 Agent 给出的实现方案

合理的方案应类似：

库存变化
  ↓
评估补货需求
  ↓
需要补货？
  ├─ 是 → 创建补货记录
  └─ 否 → 记录库存充足
  ↓
完成

先确认 Agent 没有因为“后台执行”或“存在条件分支”就直接选择工作流；它应指出本例需要独立运行记录、版本、运营参数和路径观测。然后重点确认：

• 流程节点是否表达业务阶段，而不是把每个查询都拆成节点；
• 库存读取和补货写入是否复用现有类型化 Service；
• 商品或库存变更标识属于每次运行的输入，目标库存属于管理员参数；
• 同一次库存变化是否使用稳定事件标识；
• 补货写入本身是否还有唯一约束或幂等检查；
• Agent 是否只使用目标应用已经注册的节点类型。

如果应用不存在补货 Collection 或写入 Service，Agent 应先说明缺口。不要让示例名称替代真实 Schema 设计。

#3. 查看生成的应用代码

默认应用的工作流位于 workflows。Agent 可能生成如下结构：

workflows/inventory-replenishment/
├── workflow.ts
└── server/
    ├── calculate-shortage.ts
    ├── create-replenishment.ts
    └── record-stock-sufficient.ts

• workflow.ts 描述输入、管理员参数、节点顺序和条件分支；
• server/*.ts 调用当前应用已有的 Service，完成计算或写入；
• 目录名是应用代码触发流程时使用的稳定标识，通常由 Agent 生成并维护，业务管理员不需要操作它。

详细语法见工作流定义 DSL。

#4. 检查并启动应用

要求 Agent 报告实际执行的验证命令和结果，至少包括：

pnpm nocobase workflow check workflows/inventory-replenishment
pnpm typecheck
pnpm test
pnpm build

workflow check 检查声明式流程本身，但不会加载 Run 节点引用的模块；应用的类型检查、测试和构建负责覆盖这些运行模块。默认应用的正常构建会同时生成 Workflow Artifact。

启动应用后，确认服务端工作流运行时和队列均已启动。构建产物存在并不等于工作流已经启用。

#5. 配置并启用工作流

业务管理员登录应用后：

1. 进入“设置 → 自动化 → 工作流”；
2. 找到“库存补货处理”；
3. 打开“更多操作 → 参数设置”；
4. 将目标库存设为测试需要的数值并保存；
5. 打开工作流的启用开关。

首次启用会把已部署的工作流产物激活为可运行版本。以后开发者发布新版本时，管理员需要确认新版本后再切换，具体行为见参数、启停与版本。

#6. 手动运行一次

1. 打开工作流详情；
2. 从“更多操作”选择“手动运行”；
3. 填写测试商品和当前库存；
4. 提交后进入本次执行详情。

#7. 查看执行记录

在执行详情中检查：

• 整体状态是排队中、运行中还是已完成；
• 本次运行使用的工作流版本；
• “需要补货”条件实际选择了哪条分支；
• 缺口计算节点返回的数量；
• 补货记录节点是否成功；
• 节点是否有错误、日志截断或敏感字段脱敏提示。

还可以从“自动化 → 工作流执行”查看全局执行列表。详细说明见执行记录与诊断。

#8. 接入真实库存变更事件

手动运行只完成验证闭环。正式业务应在库存变更成功后，由应用代码调用 Workflow Service。继续向 Agent 描述：

现在请把库存补货处理接入实际库存变更逻辑。重复投递同一次库存变更时，应复用同一个业务事件标识，且补货写入本身也不能重复。补充相应测试，并告诉我哪项业务操作会触发它、触发被跳过时如何处理，以及如何在管理界面确认结果。

应用代码的接入方式见 Service API。

#常见问题

#为什么生成代码后，管理界面还看不到工作流

先确认应用构建已经生成工作流产物、服务端正在读取正确的产物目录，并刷新列表。工作流定义检查不会自动把定义写入数据库；首次出现的产物还需要管理员启用。

#为什么工作流已启用，但业务操作没有触发它

确认 Agent 已将真实业务事件接入 Workflow Service，而不只是创建了工作流源码。同时检查调用使用的稳定标识、输入是否符合定义，以及触发结果是否为 skipped。

#为什么手动运行提交后没有立即完成

工作流在队列中异步执行。提交成功只说明运行已经创建或被接受，应在执行详情中观察状态变化。

#为什么重复通知只产生了一次执行

同一个业务事件复用相同 eventKey 时会被去重，这是预期行为。不同的真实库存变化应使用不同的事件标识。

#下一步

• 使用 Workflow Skill
• 从业务需求到工作流
• 工作流管理