flow-code.md

要做到 Flow as Code，核心是：把“流程”拆成可执行的 图（Graph）+ 状态（State）+ 节点（Node）+ 路由规则（Edge）+ 运行时（Runtime），并像代码一样版本化、测试、发布、观测。

下面给你一套可落地的做法（从 0 到可上线）。

---

1) 定义“状态 State”：流程里唯一的事实来源

原则：节点只读写 State，不靠隐式上下文。

最小 State 结构建议：

• input：原始需求/任务描述
• artifacts：产物（PRD、代码 patch、测试报告、部署记录）
• signals：指标与风险（置信度、失败原因、风险等级）
• routing：路由需要的标记（是否需要人工、是否重试、下一步节点名）
• trace：链路追踪（节点耗时、token、工具调用、版本号）

用 JSON Schema 固定它：可验证、可回放、可演进。

---

2) 把流程拆成“节点 Node”：每个节点是可替换的能力插件

节点类型通常就这几类：

1. LLM 节点：生成/改写/评审（输入 State → 输出 State）
2. 工具节点：调用外部系统（Git、CI、DB、搜索、部署）
3. 规则节点：做判定（风险评分、质量门禁、是否升级人工）
4. 人工节点：Human-in-the-loop（等待批准/补充信息）

关键约束：节点必须是“纯函数式接口”（尽量无副作用；副作用放工具节点里），方便测试与替换。

---

3) 定义“边 Edge”：用显式路由规则取代口头协作

边就是：在什么条件下从 A 到 B。

常见模式：

• if test_failed -> back_to_codegen
• if risk_high -> human_approval
• if quality_pass -> deploy_staging
• else -> end

路由条件必须只依赖 State（比如 signals.risk_level、artifacts.test.pass_rate）。

---

4) 引入“运行时 Runtime”：让流程能跑、能暂停、能恢复、能回放

Flow as Code 不只是“写出来”，还要能 可靠运行：

• 可暂停：等人工、等外部系统
• 可恢复：进程挂了能续跑
• 可重放：同样输入+版本能复现行为
• 可观测：每个节点的耗时、失败率、成本、产物质量

这需要两件事：

1. Checkpoint/State 存储（数据库/对象存储）
2. 事件日志/trace（OpenTelemetry / 自建日志）

---

5) 加上“质量门禁 Quality Gates”：让它可控，而不是“自动乱跑”

建议把门禁当作节点插在关键位置：

• 代码生成后：lint / typecheck / unit test
• 部署前：安全扫描 / 变更影响评估
• 发布前：回归 / SLO 风险评估
• 失败策略：重试次数、回滚、升级人工

这样你可以逐步放权（你之前的 1A→2A→…），而不是一次性全自动。

---

6) 工程化落地：像写软件一样写流程

目录结构建议（最小可用）：

• flows/：流程定义（图结构 + 节点编排）
• nodes/：节点实现（可插拔）
• schemas/：State 与 artifacts 的 JSON Schema
• tests/：流程单测/回放测试/属性测试
• configs/：环境配置（模型、工具权限、超时、重试）
• observability/：日志、指标、trace

CI 里跑三类测试：

1. 节点单测（mock 外部工具）
2. 流程回放测试（固定输入、固定模型版本/seed）
3. 门禁测试（失败必须走到正确分支）

---

7) 选型建议：生产级优先“图编排 + 可恢复 + 可观测”

你提到的趋势里：

• LangGraph：最贴近 Flow as Code（图、条件边、Checkpoint）
• CrewAI：偏“角色协作编排”，更像流程的语法糖
• AutoGPT：偏探索型循环，不适合做强门禁的生产流程

你如果目标是“可上线的研发/运营闭环”，优先图式编排。

---

8) 最小可行版本 MVP（1 周内能落地的那种）

做一个 6 节点的闭环：

1. intake（输入规范化）
2. plan（生成执行计划）
3. execute（工具/代码/操作）
4. self_check（自动测试/检查）
5. gate（风险评分 + 是否人工）
6. deploy_staging（仅预发）→ observe → end