workflow-guide

# Workflow 操作指南 ## 先确定操作层级 DeterminFlow 有两个工作流对象： - `definition.json` 是可复用的工作流模板。 - Task 是创建时冻结模板快照的运行实例；之后修改模板不会影响已有 Task。 版本化 Core Skill 位于 `src/core/defaults/skills/`，运行实例由启动时同步到 `data/skills/`。工作流业务数据始终位于 `data/workflows/{workflow_id}/`。 ## 操作前检查 1. 先用 `list_workflows` 与 `get_workflow` 读取现状，不根据名称猜结构。 2. Agent 节点先用 `list_agent_types` 确认 `agent_type` 仍存在；详细定义规则见 `agent-definition-guide`。 3. Script Library 节点先核对脚本身份、类型与分组；详细规则见 `script-library-guide`。 4. 每个节点和网关都提供唯一 ID、可读 `label` 与 `position`。并行分支错开 x 坐标， 主链按 y 坐标递增。 5. 修改前确认目标是模板、已有 Task，还是新 Task；不要把三者混为一谈。 ## 首选操作面 工作流模板优先通过 Web 或 Workflow API 管理，因为 API 会在保存前校验： | 操作 | API | |---|---| | 列出/读取 | `GET /api/workflows`、`GET /api/workflows/{id}` | | 创建/更新 | `POST /api/workflows`、`PUT /api/workflows/{id}` | | 仅校验 | `POST /api/workflows/validate` | | 删除 | `DELETE /api/workflows/{id}` | | 创建 Task | `POST /api/workflows/{id}/tasks` | | 启动 Task | `POST /api/workflows/{id}/tasks/{task_id}/start` | | 停止 Task | `POST /api/workflows/{id}/tasks/{task_id}/stop` | 主会话中已有工具覆盖读取与 Task 生命周期：`list_workflows`、`get_workflow`、 `create_and_attach_task`、`set_workflow_variable`、`start_workflow_task`、 `get_task_status`、`get_task_result`、`read_task_artifact`、`get_node_messages`、`list_tasks`、 `approve_node`、`retry_node`、`skip_node`、`stop_task`。 Main 可以同时管理多个后台 Task。`main_session_id` 是所有权事实来源；会话上的 `workflow_id/task_id` 只是最近任务的兼容默认值。除发现类工具外，所有任务修改、启动、 审批、恢复和结果查询都应显式携带完整 TaskRef：`workflow_id + task_id`。只提供其中一个 会失败，其他 Main 的任务也不可操作。 Main 所有权与逐节点审批是两个独立契约。`create_and_attach_task` 的可选参数 `main_takeover` 默认 `false`：Main 可以持续跟踪任务，但 Agent 节点完成后正常自动流转。 只有显式设为 `true` 时，每个 Agent 节点的产出才进入 Main 审批；工作流中显式定义的 Approval 节点不受该参数影响。 HTTP 创建 Task 时可用 `node_model_overrides` 为指定 Agent 节点选择 Core 已配置的 Provider 与预定义模型，并用 `node_model_params_overrides` 叠加本次 Task 的临时 Agent `model_params`： ```json { "node_model_overrides": { "writer": "provider_id:model_name" }, "node_model_params_overrides": { "writer": { "temperature": 0.4, "reasoning_effort": "high" } } } ``` 节点 ID 必须存在且 `node_type=agent`，模型引用必须出现在 Core 当前模型列表中。选择结果会 写入 Task 的定义快照和运行身份守卫，因此重试与恢复继续使用同一模型；Workflow 模板不会 被修改。Core 只校验参数覆盖的外层结构，不校验参数名、类型或取值；调用方负责语义校验， Provider Adapter 继续按现有声明认领支持的字段。该接口不接收 API Key、Base URL、 Provider 类型或回退模型。 `get_task_status` 和 `get_task_result` 支持事件驱动等待： - `wait_for=none`：立即返回，是兼容默认值。 - `wait_for=change`：已持久化 Task 快照变化或超时后返回。 - `wait_for=terminal_or_attention`：Task 完成、失败、停止、取消，或进入 审批/未启动等需要 Main 介入的状态时返回。 - `timeout_seconds` 是最长等待时间；`null` 表示不设截止时间，但当前调用仍可取消。 等待结果通过 `wait_outcome` 区分 `changed`、`terminal`、 `attention_required` 与 `timeout`，并返回 `terminal`、`attention_required` 和 `elapsed_seconds`。状态事件只负责唤醒，工具会重新读取持久化 Task 快照。 对结果导向的等待优先直接使用 `get_task_result`，避免终态后再调用一次结果工具。 只有 API 不可用且任务明确要求直接维护资源时，才编辑 `data/workflows/{workflow_id}/definition.json`。直接编辑后必须运行： ```bash python data/skills/workflow-guide/scripts/validate_definition.py data/workflows/{workflow_id}/definition.json ``` 可用目录或 `--all` 代替单个文件。退出码 `0` 表示通过（可含 warning），`1` 表示存在 必须修复的 error。 ## 定义结构 工作流目录由模板、内联脚本和引擎生成的运行记录组成： ```text data/workflows/{workflow_id}/ ├── definition.json ├── script/ ├── tasks/ └── runs/ ``` 定义的核心字段是 `workflow_id`、`name`、`version`、`nodes`、`edges`、`gateways`、 `variables` 和 `execution_schemes`。普通节点不能有多条出边；分支必须使用网关。 ### 节点类型 | `node_type` | 用途 | 关键字段 | |---|---|---| | `agent` | 创建 LLM 子会话 | `agent_type`、`first_message`、`output_variable`、`auto_flow` | | `script` | 确定性 subprocess | `node_params.script_source/script_type/script_name/script_argv` | | `approval` | 人工审批标记 | 通用节点字段 | | `subprocess` | 调用另一个工作流 | `sub_workflow_id`、`sub_scheme_id`、`sub_workflow_params` | Agent 节点的常用输出控制： - `output_variable` 把最后回复写入运行时变量池。 - `save_output_to_file` 与 `output_file_path` 把最后回复保存到共享 workspace；两者可同时用。 - `require_non_empty_output=true` 要求最后一条 LLM 回复去除首尾空白后非空。 - `retry_empty_output_in_session=true` 只能与 `require_non_empty_output=true` 同时使用： 最新回复为空时在原子会话追加一次固定追问，并用无工具 Graph 防止重复副作用；追问消耗 重新计入节点 token。追问后仍为空才进入 `auto_retry_count` 节点重试。 - `json_output_field` 与 `json_output_field_min_chars` 必须同时配置；前者支持 `body`、`data.chapters.0.body` 形式的字段路径，目标必须是字符串，字数必须严格大于阈值。 校验发生在变量赋值和文件写入前；失败统一进入节点的 `auto_retry_count` 策略。 - `auto_flow=true` 让 LLM 输出结束即成功，通常配合 `enable_complete_node_task=false`。 - `enable_reject_upstream` 与 `max_reject_count` 允许下游有限次打回上游。 - `auto_retry_count`、`auto_retry_interval_seconds`、`fail_auto_skip` 是失败策略；必须显式评估 重复副作用后再启用。 所有最终输出消费者只读取最新一条 assistant 消息。最新消息为空时不得向前寻找旧正文； 未启用非空门禁时节点可完成但不写输出变量，文件输出仍因无正文而失败。 终态 Task 的 Workflow Agent 节点会话可在消息抽屉或会话页继续对话。首次续聊会按当前 AgentDefinition 重建通用 Agent Graph，保留原 system prompt、上下文、模型与 workspace， 但不提供 `complete_node_task` 或 `reject_upstream`。续聊只更新会话历史，不改变原 Task 的 节点结果；每轮结束严格保存并重新冷却。运行中 Task 的节点会话不可升级。 Script 节点新定义使用 `script_argv` 字符串数组，不使用兼容字段 `script_args`。脚本节点 的详细目录、输出协议和身份冻结规则见 `script-library-guide`。 ## 变量与共享 workspace 输入变量支持 `text`、`textarea`、`select`、`file`、`list`、`dict`。变量 key 不得以 `_` 开头；该前缀保留给系统变量。 常用引用形式： - `{{key}}` - `{{list_var[0]}}` 或 `{{list_var[index_var]}}` - `{{dict_var.key}}` `list` 与 `dict` 的值必须是合法 JSON，不能使用 Python 单引号表示。运行时变量可来自： - Task 创建或 `set_workflow_variable` 填入的输入值； - Agent 节点 `output_variable`； - Script stdout 中的 `<WF_VAR>key:value</WF_VAR>`； - 声明为 `source_type: output` 的节点产出变量。 同一个 Task 内的 Agent 和 Script 节点共享 workspace。通过 Chat Main 创建时，默认 `workspace_mode=task_isolated`，路径位于 `data/workspaces/_main/{session_id}/tasks/{task_id}/`；需要多个 Task 共享资料时，显式使用 `named_shared` 与安全的 `workspace_ref`。`legacy_shared` 保留 `data/workspaces/{workflow_id}/` 兼容行为。相对文件路径均基于实际 workspace，系统通过 以下变量暴露运行上下文： | 系统变量 | 含义 | |---|---| | `_system.workspace_path` | 实际共享 workspace | | `_system.workflow_id` | 工作流 ID | | `_system.task_id` | Task ID | | `_system.task_name` | Task 名称 | | `_system.current_time` | 每节点重新计算的 ISO 时间 | | `_system.operator` | 当前执行人标识 | ## 网关与执行方案 | `gateway_type` | 约束 | |---|---| | `parallel` | 至少两条出边，必须有对应 `converge` | | `converge` | 至少两条入边，恰好一条出边 | | `condition` | 至少两条出边，非默认边有表达式，至少一条默认边 | | `loop` | 恰好两条出边：循环体与默认退出边；不支持嵌套循环 | 条件表达式支持 `==`、`!=`、`>=`、`<=`、`>`、`<` 与 `contains`。Loop 常用表达式是 `for item in items`、`for key, value in config`、`for i in range(5)`。 执行方案只保存 `selected_node_ids`。创建 Task 时，`selected_node_ids` 优先于 `scheme_id`， `disabled_node_ids` 仅用于兼容旧调用。子流程通过 `sub_scheme_id` 选择目标工作流方案。 ## Task 安全顺序 ```text create_and_attach_task（按需显式 main_takeover=true，默认只跟踪） -> 保存返回的 workflow_id + task_id -> set_workflow_variable（显式 TaskRef，必要时重复） -> start_workflow_task（显式 TaskRef，后台执行） -> get_task_status（必要时 wait_for=change） -> approve_node / retry_node / skip_node（显式 TaskRef + 最新 attempt_count） -> get_task_result（可 wait_for=terminal_or_attention） -> 必要时 read_task_artifact 或 stop_task ``` 启动前检查所有 `required` 输入和 file 路径。运行中不要修改 definition 并期待当前 Task 变化；需要新定义时创建新 Task。一个 Main 可继续创建其他 Task，旧 Task 不会被解绑或 停止。Agent 节点可能产生审批请求，审批消息会提供完整 TaskRef 与 `attempt_count`；调用 控制工具时原样携带，过期操作会返回 `node_control_stale`。拒绝时提供可执行反馈。 ## 验收清单 - 模板 API 校验通过，或直接编辑后校验脚本返回 0。 - START 到 END 完整可达，无孤立节点、悬空边或重复 ID。 - 节点位置可读，变量均已定义或明确由上游产出。 - Agent 类型、Prompt 模板和 Script Library 身份真实存在。 - 新建 Task 使用了最新模板快照，启动后状态与节点摘要可查询。 - 同一 Main 的多个 Task 可独立寻址，默认工作空间互不污染，其他 Main 不能越权控制。 - 终态 Task 可通过 `get_task_result` 返回节点摘要、公开输出和受控产物描述符。 - 失败策略不会把有外部副作用的节点静默重复执行。 ## 常见故障定位 - 节点重叠：检查 `position`。 - `{{key}}` 保留原样：检查 Task 参数、上游输出和 key 拼写。 - definition 更新未生效：当前 Task 使用旧快照，重新创建 Task。 - Main 所属任务在每个 Agent 后等待：检查 Task 的 `main_takeover` 是否被显式启用；默认值应为 `false`，显式 Approval 节点除外。 - file 变量为空或失败：检查实际 workspace、路径和 `required`。 - Loop 失败：检查 JSON 值、两条出边、默认退出边与循环表达式。 - 并行保存失败：检查 parallel/converge 配对和嵌套限制。 - Prompt section 变量未渲染：加载 `prompt-template-guide` 检查系统变量或 `template_variables` 声明。