附录 C：Workflow Library

工作流（Workflow）把多个可验收步骤组织为有状态、可恢复、可交接的过程。它不等于一串自然语言步骤：每个状态都要有进入条件、允许动作、成功与失败迁移和证据。

概念与状态设计见第 10 章，模板源见 templates/workflow-template.md。本附录提供读者可裁剪的工作流样例；项目状态或模板变化时先更新权威工件，再刷新本页，不能让样例表成为第二份项目状态。

通用工作流契约

# 工作流名称

## 目标和非范围

- 起点：
- 终点：
- 读者或系统价值：
- 不负责：

## 状态和迁移

| 状态 | 进入条件 | 允许动作 | 成功迁移 | 失败迁移 | 证据 |
| --- | --- | --- | --- | --- | --- |
| `planned` | 范围已确认 | 收集输入 | `ready` | `blocked` | 任务契约 |

## 角色和所有权

| 角色 | 专属工件 | 权限 | 交接输入 | 交接输出 |
| --- | --- | --- | --- | --- |

## 恢复、回滚和升级

- 可重试条件：
- 检查点：
- 幂等键或输入版本：
- 回滚动作：
- 人工升级阈值：

C1：技术章节生产

本书实际采用的章节工作流如下：

状态	主要工件	进入条件	通过证据	失败出口
researched	Research Brief	目标和来源范围已定	一手来源与待核验项	返回补证
outlined	Chapter Outline	研究已审查	每节问题和证据映射	缩小或重组范围
drafted	正文草稿	提纲稳定	原创内容与边界完整	返回研究/提纲
technical_reviewed	技术审查	正文可定位	must/should 问题已解决	返回草稿
example_verified	示例、测试	接口和边界明确	实际测试与未运行说明	修复或标记阻塞
diagram_reviewed	Mermaid 与导出图	图要回答的问题明确	源码一致、渲染可读	重画或拆图
fact_checked	事实核验	可归因陈述稳定	来源与运行证据逐项支持	缩小、删除或待核验
language_edited	语言记录	技术含义已稳定	术语、主语、时态一致	返回局部修改
final_reviewed	Final Review	前述阶段工件齐全	来源、正文、示例、图示、审查和边界一致	返回责任阶段修复
validated	全仓验证记录	Final Review 已接受章节专属工件	lint、链接、测试、状态均通过	修复后重跑全量
completed	状态和交接	验证新鲜	进度、上下文、交接同步	保持未完成

这一顺序允许回流，但不允许跳过证据。例如事实核验发现来源不支持正文时，应回到正文修改并重新执行受影响审查，而不是在核验记录里解释掉问题。

C2：受控软件变更

下表适用于需要改变可观察软件行为或修复缺陷的任务。文档、配置和格式调整使用对应现有检查，不为满足状态名而伪造失败测试。

状态	必须回答的问题	证据	下一步
scoped	请求、非范围和完成定义是什么？	Task Contract	建立复现或验收
red	当前行为为何不满足目标？	最小失败测试/复现	实现最小改变
green	改变是否满足目标？	专用测试	回归与执行验证
reviewed	是否引入范围、安全或维护风险？	diff 与审查发现	修复或进入集成
validated	真实入口是否产生正确结果？	全量检查与执行观察	人工决定是否发布

停止条件： 输入不明、变更需新权限、涉及不可逆外部状态、三次修复仍失败或验证范围无法覆盖目标。停止时交付已知事实和最小下一步，不把“未发现问题”写成成功。

C3：研究—写作—审查队列

多角色可以并行处理互不重叠的专属工件，但共享文件必须有唯一集成者。

1. Research 角色输出来源范围和事实卡。
2. Writing 角色只读取已批准的 Research/Outline，不直接修改全局引用。
3. Review 角色输出 findings/verdict，不把审查和发布混为一体。
4. Fact Check 角色重新访问来源并核对运行声称。
5. 唯一集成者解决冲突、同步队列和运行全仓验证。
6. 人类责任者处理范围、版权、发布和无法自动裁决的冲突。

队列项至少携带 workId、输入版本、所有者、目标路径、当前状态、证据路径、阻塞原因和下一责任者。输入版本变化时，旧结果应进入 stale_input，不能只按修改时间合并。

C4：失败恢复

观察失败
  → 冻结原输入、状态和错误
  → 核对效果身份、上次观察和声明的重试预算
    → 效果已确认未发生且动作可安全重复：在预算内重试并重新观察
    → 效果未知：先补证、停止或交具名责任者决定
    → 不可重试：恢复最近检查点或执行已批准回滚
  → 验证外部状态和本地状态是否一致
  → 保存状态记录、尝试证据与恢复结论
  → 决定继续、升级或停止

恢复工作流必须区分：

• 重试： 同一意图再次执行，要求副作用可识别或幂等。
• 恢复： 从检查点重建可继续状态，要求输入版本仍有效。
• 回滚： 撤销已知改变，要求明确目标和验证方式。
• 升级： 把未知、冲突或新权限交给具名责任者。

并行安全清单

• 每个工作者拥有互不重叠的目标路径。
• 共享进度、引用、目录和发布状态只有一个写入者。
• 浏览器、数据库、设备和远端环境另行隔离；目录隔离不等于外部状态隔离。
• 每项局部完成都产生证据包，不直接声明全局完成。
• 集成者在所有局部结果到齐后重跑全量验证。

完成判断

工作流完成不是“最后一步运行过”，而是：终态条件成立、失败出口已关闭、证据仍新鲜、共享状态同步、下一责任明确。任一项缺失时使用 blocked、needs_evidence、requires_approval 或其他明确状态，而不是 completed。