> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WakerFlow 工作流编排
> 创建、运行和排查可重复执行的多阶段流程：从自然语言生成画布和脚本，到配置运行输入、处理等待输入、理解业务日志，再到设置自动触发。
**本章目标：** 创建、运行和排查可重复执行的多阶段流程。只运行现有流程时，可直接进入执行记录；需要调整流程时，再检查输入表单、Worker 和返回结构。
WakerFlow 用于编排多角色、多阶段或需要人工确认的流程。单个 Waker 定时重复执行固定任务时，使用「自动任务」。
## 打开或创建 WakerFlow
在左侧主导航点击「WakerFlow」，进入 WakerFlow 管理页。
打开已有流程时，先按名称和描述确认目标；修改正在运行的流程前查看执行记录。列表为空或加载失败时，刷新页面并检查本地服务和网络状态。
**创建新流程：** 当前版本先创建草稿，再通过对话生成流程。
**操作步骤：**
1. 在 WakerFlow 列表页点击「新建 WakerFlow」。
2. 在空白工作区输入目标，并写清运行输入、处理步骤、角色分工、异常处理和输出格式。
3. 等待系统生成画布和脚本；打开「脚本」，检查输入字段、目标 Waker 和最后的 `return`。
4. 修改顶部名称，并在「详情配置」中补充用途说明。
5. 点击右上角「运行」，完成一次手动试运行。
描述流程时建议依次写明：目标、运行输入、处理步骤、异常处理和最终输出。需要人工判断时，还要说明确认节点、问题内容以及超时或跳过后的处理方式。
**完成判断：**
* 画布已生成阶段和节点，脚本不为空。
* 运行表单包含所需字段，每个 Worker 均指向当前环境中的 Waker。
* 脚本有明确的 `return`，其内容符合交付要求。
**生成结果不符合预期时：**
在左侧定制对话中说明要调整的节点、执行顺序、输入或输出。一次只调整一类问题，修改后重新检查画布、脚本和运行表单。
## 认识详情页
WakerFlow 详情页分为三个区域：
| 区域 | 主要用途 |
| --------- | --------------- |
| WakerFlow | 查看或调整画布、脚本和版本 |
| 执行记录 | 查看运行状态、日志、结果和错误 |
| 详情配置 | 修改说明、触发方式和默认参数 |
右上角「运行」用于手动执行当前流程；「添加触发方式」或「管理触发方式」用于配置自动运行。两者不是同一个操作。
### 画布
画布把脚本解析为阶段和节点关系，适合快速理解流程结构。
常见节点如下：
| 节点 | 含义 |
| ------------------- | -------------- |
| Phase | 业务阶段 |
| Worker | 交给 Waker 执行的任务 |
| Parallel / Pipeline | 并行处理或批量多阶段处理 |
| Ask User | 暂停并等待人工输入 |
| Action / 子流程 | 执行动作或调用其他流程 |
画布未展示的条件、异常处理和返回结构以脚本为准。「运行配置」是可填写字段，不是某次历史运行的实际参数。
### 调整脚本和版本
1. 在左侧定制对话中说明修改要求，或直接编辑「脚本」。
2. 保存后检查画布、运行输入和 `return`，再手动试运行。
3. 需要恢复时，在「版本历史」中预览并回滚。
### 执行记录
执行记录展示运行 ID、触发方式和节点状态。点击节点可查看输入、会话、结果或错误；整条流程的日志和最终返回值在运行详情中查看。
## 配置运行输入和最终输出
运行表单由脚本中的 `meta.inputSchema` 生成，填写值通过 `args` 传入；最终交付内容由 `return` 决定。
1. 在 `inputSchema` 中设置字段类型、说明、默认值和必填项。
2. 点击「运行」，检查表单字段及默认值是否正确。
3. 运行后检查「最终返回值」是否符合预期。
对象或数组必须填写合法 JSON。字段缺失、格式错误或类型不匹配时，页面会阻止提交或提示校验失败。
## 编排能力速查
修改脚本时，可按需使用以下能力：
| 能力 | 作用 |
| ----------------------- | ----------------- |
| `phase` / `log` | 标记阶段、记录业务日志 |
| `worker` | 派发 Waker 任务并等待结果 |
| `parallel` / `pipeline` | 并行处理或批量多阶段处理 |
| `askUser` | 暂停流程并等待人工输入 |
| `workflow` | 调用另一条 WakerFlow |
| `action` | 执行已声明的 HTTP 或本地动作 |
保存前检查 Waker ID、子流程 ID、Action 地址和本地路径是否属于当前环境。密钥不得硬编码在脚本中。
## 手动运行并处理等待输入
### 手动运行
1. 点击详情页右上角「运行」。
2. 填写运行参数；必填项不能为空，对象和数组需使用合法 JSON。
3. 提交后在「执行记录」中查看节点进度。
4. 运行结束后检查状态和「最终返回值」。
**运行状态：**
| 状态 | 含义 | 应采取的动作 |
| --------- | -------- | ---------------- |
| 排队中 / 运行中 | 已创建并正在推进 | 持续不动时检查当前节点和服务状态 |
| 等待输入 | 流程等待人工回答 | 打开问题并提交或跳过 |
| 已完成 | 脚本已结束 | 检查最终返回值是否正确 |
| 失败 / 已终止 | 运行出错或被取消 | 查看失败节点，修复后重试 |
"已完成"只说明脚本成功结束，不自动证明业务内容正确。仍需检查最终返回值是否包含预期字段、数量和证据。
### 等待用户输入
`askUser()` 可生成文本、选项或审批卡片。脚本中应写清问题、选项、超时和默认处理方式。
流程进入「等待输入」后，在执行记录或审批工作台提交答案。无人值守流程应谨慎使用该节点，避免长期停在等待状态。
「终止」不会撤销已写入文件、已发送消息或已执行的外部动作。「重试」可能复用上一轮已完成的节点；输入或脚本已修改时，应重新发起运行。
## 正确理解运行配置、业务日志和结果
这是阅读 WakerFlow 运行记录时最容易混淆的部分。
### 六类信息分别来自哪里
| 信息 | 来源与含义 | 不是 |
| ------------------ | -------------------- | --------------- |
| 运行配置 | 表单字段及本次填写值 | 最终输出 |
| 业务日志 | 脚本用 `log()` 记录的进度或摘要 | 完整输入和最终结果 |
| Worker Instruction | 单个 Worker 的任务指令 | 整条流程的全部输入 |
| Worker Result | 单个 Worker 的返回值 | Worker 的完整执行过程 |
| 最终返回值 | 脚本 `return` 的内容 | 必然是完整明细；内容由脚本决定 |
| 原始事件 | 阶段、派发、日志、结果和失败等事件流 | Worker 内部全量记录 |
脚本未显式 `return` 时，运行仍可能成功，但最终返回值为 `null`。
页面中相邻的两组「日志」不等于"输入配置"和"完整输出"，它们都可能只是脚本主动写入的业务摘要。
截图中的三条内容来自类似的 `log()` 调用：
```javascript theme={null}
log(`运行模式：${args.mode} | 运行 ID：${runLabel}`)
log(`竞品扫描：有 | 待评审需求：${pendingCount}条 | 现有能力：${capabilityCount}条`)
log(`代码仓库：${repoPath} | 生成方案：是 | 持久化：是`)
```
这些内容均为脚本设计的摘要，不代表完整输入或输出。右侧的 `+2分33秒` 是事件相对流程启动的时间，不是该条日志的耗时。
### 到哪里查看真正的结果
| 需要查看 | 入口 |
| ---------------- | -------------------------------------------------------------------- |
| 单个 Worker 的输入和结果 | 执行记录 → 目标运行 → Phase → Worker → `Instruction / Session / Result / 错误` |
| 整条流程交付 | 运行详情 → 「最终返回值」；失败或取消时查看对应原因 |
| 全过程诊断 | 运行详情 → 「原始事件」，从最后一个成功事件和第一个失败事件定位问题 |
**日志编写建议：**
* 日志只记录阶段、数量、关键决策和异常，不写入完整大对象或凭据。
* 日志级别使用 `info`、`warn`、`error`。
* 需要交付的内容必须显式 `return`，不能只写入日志。
## 配置自动运行
一条 WakerFlow 可添加多个触发方式，数量及类型上限以当前页面提示为准。
1. 先完成一次手动试运行并确认最终返回值正确。
2. 点击右上角「添加触发方式」，或进入「详情配置」→「管理触发方式」。
3. 配置默认参数，并添加定时、API、GitHub 或页面提供的事件触发方式。
4. 保存并启用，等待真实触发或使用页面提供的测试入口。
5. 回到「执行记录」，核对触发方式、运行 ID、状态和最终返回值。
触发方式中设置的字段值会覆盖自动运行默认参数，自动运行默认参数又会覆盖脚本默认值。同一字段只选择固定值或 Payload 映射中的一种。自动触发异常时，先核对触发配置、默认参数和执行记录。
**上线前检查：**
* 保持阶段和节点名称清晰，使用 Schema 约束下游数据。
* 外部写入、发消息或发布前保留人工确认。
* 重要修改先保留版本并手动试运行；重试不会撤销已产生的外部操作。