如何设计一个可维护的自动化 Agent 工作流

先让流程可读、失败点可见，再考虑抽象和复用。

任务拆解

自动化项目最容易失控的地方，是把输入、工具、输出、人工确认和失败处理混在一起。第一步不是抽象，而是把这些节点按顺序摊开。

先判断任务应该走哪条路

很多 Agent 工作流会变复杂，不是因为任务本身复杂，而是因为一开始没有判断任务类型。小改动被套上大流程，会拖慢执行；大任务没有状态文件，又会在中途丢上下文。

所以我更推荐先做一次轻量判断：能直接改就直接改，需要阶段状态才建立 TASK.md，会产生副作用的任务必须加日志、验证和人工确认。

这个决策树的价值，不是让所有任务都变正式，而是防止两种极端：一种是小事复杂化，另一种是大任务只靠对话记忆硬跑。

大任务用 TASK.md 管状态

当任务涉及多阶段迁移、多文件整理、知识库重构或规则体系调整时，不要完全依赖对话上下文。更稳的方式是先生成一个临时 TASK.md，把它作为本次任务的状态文件。

执行方式

1. 先生成 TASK.md

   • 写清目标
   • 写清阶段
   • 写清验收标准

2. 每次执行前先读 TASK.md

   • 看当前阶段
   • 看未完成项
   • 看风险点

3. 每完成一个阶段，更新 TASK.md

   • 状态改为已完成
   • 补充实际改动
   • 记录遗留问题

4. 阶段完成后再继续下一阶段

   • 不要一次性全迁移
   • 先确认结构和索引规则稳定

flowchart TD
  A[生成 TASK.md] --> B[写清目标 / 阶段 / 验收标准]
  B --> C[每次执行前读取 TASK.md]
  C --> D[确认当前阶段 / 未完成项 / 风险点]
  D --> E[执行当前阶段]
  E --> F[更新状态与实际改动]
  F --> G{结构和规则是否稳定}
  G -- 是 --> H[进入下一阶段]
  G -- 否 --> C

TASK.md 推荐结构

# 当前任务目标

整理目标、最终效果和验收标准。

## 执行阶段

- 阶段 1：结构与目录规则，状态：未开始
- 阶段 2：索引与命名规则，状态：未开始
- 阶段 3：正文迁移，状态：未开始
- 阶段 4：清理旧内容，状态：未开始

## 当前进度

当前做到哪一步。

## 未完成事项

- 还没处理的内容
- 需要继续验证的内容

## 风险 / 待确认

- 可能影响旧入口的地方
- 需要人工确认的取舍

这个文件不是聊天记录合集，而是任务看板。只保留目标、阶段、进度、未完成项、验收标准和风险点。

工具边界

工具只做确定的动作，模型负责判断和组织上下文。对于网页自动化、表格写入、文件落盘这类操作，应该让结果可验证。

# keep the flow explicit
result = agent.run(task)
if result.needs_review:
    notify_user(result.summary)
save_run_log(result)

流程图展示

文章中的 Mermaid 或架构图要放在有边界的容器里，图表下方可以保留简短说明，避免长文阅读时丢失上下文。

flowchart LR
  A[任务输入] --> B[Agent 判断]
  B --> C[工具执行]
  C --> D[结果记录]
  D --> E[人工确认]

flowchart LR
  A[输入] --> B[Agent]
  B --> C[结果]

sequenceDiagram
  participant User as 用户
  participant Agent as Agent
  participant Tool as 自动化工具
  participant Page as 页面
  User->>Agent: 提交任务
  Agent->>Tool: 调用选择器动作
  Tool->>Page: 点击并读取状态
  Page-->>Tool: 返回结果
  Tool-->>Agent: 写入执行记录
  Agent-->>User: 请求确认

flowchart TD
  A[执行任务] --> B{是否成功}
  B -- 是 --> C[保存结果]
  B -- 否 --> D[记录错误信息]
  D --> E[提示人工检查]
  C --> F[结束]
  E --> F

失败处理

不要吞异常，不要隐藏副作用。逐项处理就逐项保存，整批处理就批量末尾保存，让失败隔离粒度和落盘时机一致。