## 说清需求：从一句话到可创建的提示词

<!-- slot: 目标 -->
创建 Workflow 之前，最容易踩的坑不是“不会用工具”，而是“没想清楚要什么”。一个模糊的需求，会换来一份需要反复返工的草稿。本章给你一个固定的“六问法”，帮你在动手前把需求想透——包括正常路径、异常路径，以及最容易被忽略的超时与人工兜底——最后把它浓缩成一段可以直接用来创建 Workflow 的提示词。

我们继续用“每天分诊新 Bug”这个例子，但本章的重点是“怎么把需求说清楚”，而不是“怎么点界面”。

<!-- slot: 边界 -->
本章只讲需求梳理，产物是一张“需求卡”和一段提示词；不创建 Workflow（第 5 章）、不编辑或诊断（第 6 章）、不发布（第 7 章）。本章不产出可运行的 Plan。

<!-- slot: 流程 -->
用“六问法”把需求拆成六个必答项，逐项想清楚：

1. **目标与衡量**：要解决什么问题？怎么算做好？（例：把新 Bug 自动分诊，从分诊 Agent 收到请求起算，到返回 `assignee_team` 的响应中位数 < 10 分钟。）
2. **触发**：什么时候开始？手动，还是到点自动？（例：每天 9:00 按 `Asia/Shanghai` 时区自动跑一次。）
3. **输入**：需要哪些输入，从哪来？（例：`bug_summary` 来自工单，`destination` 是目标频道。）
4. **参与者**：谁来做？哪些步骤给人、哪些给 Agent？（例：分诊交给分诊 Agent，确认交给 owner。）
5. **审批与人工兜底**：哪些步骤必须有人拍板？Agent 不确定时怎么办？（例：每条结果都要 owner 确认才通知。）
6. **异常与完成**：出错怎么办？什么算完成？（例：Agent 回传不合结构就停在等待；通知发出即完成。）

把这六项填进一张“需求卡”，再分别画出**正常路径**（一切顺利时怎么走）和**异常路径**（Agent 失败、审批驳回、长时间无响应时分别怎么收口）。这里要特别盯住**超时与人工兜底**，并分清两类超时：`wait` 节点有创作期 `timeout`，到点会走 `timed_out` 路由，这是平台保证的运行时能力；而 `request_approval` 和等 Agent 回调**没有平台强制的响应时限**——这两类的“多久没响应算超时、超时后升级给谁”属于业务 SLA / 运营策略，要写进需求卡，不能指望节点自动升级。

用 Bug 分诊这个例子，把路径画清楚再动手。**正常路径**：到 9:00（`Asia/Shanghai`）→ 拿到要分诊的 Bug（`bug_summary`）→ 分诊 Agent 返回 `assignee_team` → 审批人（`approver`）确认 → 把“已指派给 X”通知到频道 → 成功结束。**异常路径**至少有三条，要预先想好：分诊 Agent 回传的结构不对 → 停在等待、等它修正后重交，不自动重跑整个节点；审批人驳回 → 走失败结束、并在审批收件箱留记录；长时间没人确认 → Run 停在等待，由运维按约定的 SLA 介入（审批与回调等待没有平台强制超时，所以“等多久、超时转给谁”必须写进需求卡）。把这三条异常路径都落到纸上，第 5 章生成草稿、第 6 章编辑诊断时，你才知道每个 Node 失败后该连到哪条边。

这里有一个最容易踩的坑：**“每天 9:00 取新 Bug”里的“取新 Bug”不是触发器自己能做的**。两条合法路径必须分开：若外部调度器或调用方能按批次提供动态 Bug 数据，就由它每批启动一次手动 Run 并传入 `bug_summary`，而不是使用 Binding schedule；若要由 Binding 每天 9:00 自动运行，schedule 只能重放不可变 revision 中的固定 `schedule.inputs`，须在 Plan 内加一个 Agent 步骤，经 App / Extension 查询当天工单。不写清这一步，生成的草稿就会缺“数据从哪来”，跑起来拿不到输入。

还有几类常见的需求错误，值得在动手前自查。其一是把“偶尔的一次性操作”当成“需要持久编排的流程”——那种用 Task 或普通对话更合适（见第 1 章的边界表），用 Workflow 反而是负担。其二是只画了正常路径、完全没想异常怎么办，结果一上线就各种卡住。其三是把必须由人判断的步骤直接交给 Agent、不留任何兜底，出了错没人接得住；或者反过来，给每一步都加审批，让流程慢得没人愿意用。其四是把“外部系统能做”误当成“Workflow 直接做”——比如以为 Workflow 能直接调代码托管 API，其实那是 Agent 经 App / Extension 完成的事。六问法的好处，就是逼你在动手前把这些坑暴露在纸上，而不是留到草稿生成后反复返工。

<!-- slot: 提示词 -->
把填好的需求卡转成一段提示词，按“目标 / 输入 / 角色 / 审批 / 异常 / 完成”组织。下面是 Bug 分诊例子的提示词，可直接复制：

```text
帮我创建一个 Workflow：对一条给定的 Bug（bug_summary），交给分诊 Agent（triage_agent）
返回 assignee_team；由审批人（approver）确认后，把“已指派给 X”的通知发到目标频道（destination）。
输入：bug_summary（Bug 摘要）、destination（目标频道）、triage_agent（分诊 Agent）、approver（审批人）。
审批：approver 确认后才通知；被驳回则失败结束并留记录。
异常：分诊 Agent 回传不符合结构时，停在等待，等它修正重交；若长时间无响应，按 SLA 由运维介入（审批与回调等待无平台强制超时）。
完成：通知发出后成功结束。
注：动态 Bug 批次由外部调度器或调用方每批启动一次手动 Run 并传入，不是 Binding schedule；若要“每天 9:00（Asia/Shanghai）自动跑”，schedule 只带固定输入，“取新 Bug”须在流程内由 Agent 经 App / Extension 查询。
```

提示词越贴近六问的答案，生成的草稿就越接近可用。

第一次生成的草稿很少完美，这很正常。把提示词当作和 Loop 的一次对话：先生成，再看草稿哪里不对，回去把提示词里模糊的地方说得更具体，再重新生成。最常见的补强点有两个：把“出错时具体怎么办”写死（而不是笼统说“要处理异常”），以及把“哪一步必须经谁确认”写死（而不是笼统说“需要审批”）。这两项最容易被草稿省略，也最影响线上能不能稳定跑。把它们在提示词里讲透，能省下后面大量编辑与诊断的时间。

<!-- slot: 配置 -->
本章不涉及 Plan 配置；提示词转成 Plan 草稿在第 5 章。

<!-- slot: 异常 -->
本章讲的就是“把异常路径想清楚”。落到 Plan 上的异常处理（重试、回调拒绝、审批驳回、计时器超时）在第 6 章诊断与可靠流程设计篇。

<!-- slot: 审批 -->
本章在“审批与人工兜底”里确定哪些步骤需要人；真正的 `request_approval` 配置在第 5、6 章。

<!-- slot: 外部系统 -->
本章不涉及外部系统对接。如果某一步要调用外部系统，在“参与者”里记成“由某个 Agent 经 App / Extension 完成”，而不是写进 Workflow 直接调用。

<!-- slot: 验收 -->
- [ ] 能用六问法把一项真实工作拆成目标 / 触发 / 输入 / 参与者 / 审批兜底 / 异常完成。
- [ ] 能为一个例子画出正常路径和至少两条异常路径，并写明超时与人工兜底。
- [ ] 能把需求卡转成一段结构化、可复制的提示词。

<!-- slot: 媒体槽位 -->
<!-- media: fig-04-01-requirement-card.png -->
图 4-1 需求卡与六问法示意（截图槽位：六问表 → 正常 / 异常路径 → 提示词）。