可视化工作流
xopc 工作流把可重复的多步骤工作变成可视化任务方案。用户在画布上编排步骤、用自然语言描述修改、实时查看每一步，并直接使用最终结果，不需要阅读代码。
工作流定义是带版本的有向无环图。系统不再提供脚本格式和脚本执行路径。
产品模型
- 模板：描述一类任务如何完成。
- 草稿：尚未发布的可视化修改，会自动保存。
- 版本：一次不可变的已发布定义。
- 运行：执行启动时锁定的图和版本。
- 自动化：决定已发布工作流何时运行。
因此，工作流只负责“怎么做”，自动化只负责“什么时候做”。
创建与编辑
打开 #/workflows，选择“创建任务模板”，然后可以：
- 用自然语言描述想要的结果，由 xopc 生成可视化草稿；
- 在画布上直接添加、连接和调整步骤。
| 步骤 | 用途 |
|---|---|
| 输入 | 接收目标和结构化输入；每个流程必须且只能有一个。 |
| AI 任务 | 让独立 Agent 完成一个聚焦任务；互不依赖的任务会并行执行。 |
| 判断 | 用简单规则选择“是”或“否”分支。 |
| 合并 | 汇总所有实际执行分支的结果。 |
| 结果 | 生成最终摘要和结构化结果；每个流程必须且只能有一个。 |
选择步骤后可编辑名称、用途和自然语言指令。模型、工具、结构化输出和迭代次数属于高级设置，不应干扰普通用户。
草稿自动保存。发布时服务端会校验完整流程并创建新版本。如果其他编辑者已先发布，旧编辑器的保存会被拒绝，不会静默覆盖。
校验规则
服务端会一次返回所有已发现问题。可发布的流程必须满足：
- 恰好一个输入和一个结果；
- 节点、连线 ID 唯一；
- 连线有效，不允许自连和环路；
- 所有步骤都能从输入到达；
- 所有步骤最终都能到达结果；
- 每个判断都有“是”和“否”两条分支；
- 每个 AI 任务都有明确指令。
编辑过程可以暂时不完整，因为拖拽时出现断开的节点很正常；但无效流程不能发布或运行。
运行与排障
启动工作流后，系统会创建独立工作流会话，并保存所执行图和版本的快照。以后修改模板不会改变历史运行。
运行页会在同一张图上显示每个节点的状态：等待、执行中、已完成、因未选择该分支而跳过、失败。
点击节点可查看输入、输出、耗时、模型/工具详情和错误。运行失败时，“修复这个工作流”会打开同一张图，并自动填入针对失败节点的修改要求。
所有已就绪且互不依赖的节点会并行运行。判断只激活选中的分支；合并等待实际激活的前置步骤并忽略跳过分支。活动 AI 节点失败或图无法继续推进时，本次运行失败。
使用入口
| 入口 | 行为 |
|---|---|
| 工作流中心 | 选择模板、填写目标、查看实时流程图。 |
| Chat | workflow 工具按名称启动已发布模板。 |
| 自动化 | 定时、Webhook 或手动触发器直接启动模板。 |
| REST API | 不经过 Assistant turn，直接创建和监控运行。 |
| TUI / 消息渠道 | 接收精简进度和最终结果。 |
工作流工具只接受模板名称和运行输入，不接受内联可执行定义。
内置模板与自动化
内置模板覆盖仓库审计、调研、规划、决策、会议准备、周复盘、内容创作和竞品分析等常见场景。内置与自定义模板使用完全相同的图模型和运行时。复制内置模板后可以独立编辑，不会修改原模板。
周期性任务应创建自动化并选择一个已发布工作流。自动化保存触发条件和可靠性策略，工作流保存任务逻辑；自动化历史会链接到对应运行，以便查看准确版本、流程和结果。
只有在模型需要临时决定是否运行工作流时，才使用 Agent 指令型自动化。固定周期任务优先直接运行工作流，更简单也更易审计。详见 自动化。
存储
自定义定义以 JSON 保存到 ~/.xopc/workflows/。版本快照和草稿位于同一工作流存储下的私有子目录。写入采用临时文件加原子重命名。
删除自定义工作流会同时删除当前定义、版本历史和相关草稿。内置模板不能删除。
REST API
所有路由使用网关控制台相同的 Bearer token。
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/workflows/definitions | 列出模板。 |
GET | /api/workflows/definitions/:id | 读取当前流程图。 |
POST | /api/workflows/definitions/validate | 不发布，仅校验流程图。 |
POST | /api/workflows/definitions/generate | 根据自然语言生成或修改流程图。 |
POST | /api/workflows/definitions | 携带 expectedRevision 发布。 |
DELETE | /api/workflows/definitions/:id | 删除自定义模板及历史。 |
GET | /api/workflows/definitions/:id/revisions | 列出已发布版本。 |
GET | /api/workflows/definitions/:id/revisions/:revision | 读取指定版本。 |
POST | /api/workflows/definitions/:id/revisions/:revision/restore | 将旧版恢复为一个新版本。 |
GET | /api/workflows/drafts | 列出可视化草稿。 |
GET | /api/workflows/drafts/:draftId | 读取草稿。 |
POST | /api/workflows/drafts | 用乐观并发创建或更新草稿。 |
DELETE | /api/workflows/drafts/:draftId | 丢弃草稿。 |
POST | /api/workflows/runs | 启动运行并返回运行/会话 ID。 |
GET | /api/workflows/runs | 列出运行。 |
GET | /api/workflows/runs/:runId | 获取实时投影后的运行视图。 |
POST | /api/workflows/runs/:runId/cancel | 停止活动运行。 |
POST | /api/workflows/runs/:runId/retry | 启动一次全新重试。 |
POST | /api/workflows/runs/:runId/replay | 重放失败检查项或阶段。 |
配置与边界
工作流是否可用及运行限制由所选 Agent 的能力清单决定。AI 节点可以选择 small、large 等模型用途；无法解析的用途会明确失败，不会静默改变行为。
当前边界：
- 工作流必须无环；
- AI 节点内部不能嵌套启动工作流；
- 已取消运行重试时从头开始；
- 各消息渠道的进度展示受渠道能力限制，网关始终提供完整节点图。