Agent 工作流设计

Agent 不是一个“会聊天的按钮”，而是一套能持续接收目标、拆解任务、调用工具、验证结果并沉淀经验的工作系统。设计这类系统时，关键不在于给它写一个夸张的人设，而在于把边界、节奏、工具和反馈机制设计清楚。

设计目标

一个可用的 Agent 工作流至少要满足四个目标：

1. 目标清晰：知道当前要完成什么，以及什么状态算完成。
2. 过程可控：每一步工具调用、文件修改和外部动作都能被追踪。
3. 结果可验：不能只生成内容，还要通过测试、构建、审查或人工验收确认质量。
4. 经验可复用：把稳定做法沉淀成文档、脚本、模板或技能，而不是每次重新摸索。

角色设定：从“人格”到“行为契约”

很多 Agent 设计会从人格设定开始，但真正有价值的是行为契约：

维度	应该明确的问题
工作范围	能处理哪些任务，哪些任务必须交给人决策
行为风格	是偏执行、偏审查，还是偏陪伴式反馈
质量标准	是否必须运行测试、是否必须引用来源、是否允许不确定结论
安全边界	哪些信息不能保存，哪些动作必须确认
沟通方式	何时汇报进度，何时只给最终结果

一个好的设定不需要强调“聪明”“高效”或“永不停歇”，而是要能约束实际行为。例如：

• 修改代码前先检查仓库状态。
• 生成技术内容前先确认资料来源。
• 遇到凭据、token、群 ID、私有路径时必须脱敏。
• 对有副作用的操作保持最小权限和最小改动。

工作循环

可以把 Agent 的工作过程拆成一个稳定循环：

目标输入 → 任务拆解 → 上下文收集 → 执行 → 验证 → 总结 → 沉淀

1. 目标输入

目标要尽量转换成可交付结果：

• “完善项目” → 找到未完成项，完成一个可验证改动，并说明验证结果。
• “整理资料” → 形成一篇结构清晰、去重、可维护的文档。
• “检查问题” → 给出复现路径、根因、修复方案和验证命令。

2. 任务拆解

任务拆解要避免过度计划。更实用的做法是：

• 先找最高风险或最高价值的一步；
• 每次只推进一个闭环；
• 修改范围尽量小；
• 修改后立即验证。

3. 上下文收集

Agent 需要在行动前读取必要上下文，例如：

• 项目说明和约定文件；
• 当前 git 状态；
• 测试脚本和构建脚本；
• 现有目录结构和命名风格；
• 相关历史文档或已有实现。

这一步可以避免“看起来完成了，其实放错位置或破坏已有约定”的问题。

4. 执行

执行阶段适合遵循三条原则：

• 最小改动：只改和当前目标相关的文件。
• 可回滚：不要混入无关格式化、临时文件和生成产物。
• 可解释：每个改动都能说清楚为什么需要。

5. 验证

验证方式取决于任务类型：

任务类型	常见验证方式
代码修改	单元测试、类型检查、lint、构建、手动页面验证
文档整理	构建、链接检查、关键词检查、目录检查
数据整理	schema 检查、重复项检查、字段完整性检查
自动化脚本	dry-run、最小样本运行、日志检查

不要把“命令执行过”误认为“任务完成”。更可靠的标准是：命令通过，并且结果覆盖了这次改动的核心风险。

验证账本

如果 Agent 要长期维护一个项目，最好把验证从“临时跑了几个命令”升级成验证账本。验证账本不是复杂系统，它只是一份可追踪的证据链：这次改动风险是什么、用什么命令覆盖、结果是什么、还有哪些风险没有覆盖。

一个轻量格式可以这样记录：

字段	说明
改动范围	本轮实际改了哪些文件或模块
核心风险	最可能被改坏的行为、接口、链接或内容结构
验证动作	运行的测试、构建、脚本、人工检查路径
结果证据	命令输出摘要、构建是否通过、发现并修正了什么
未覆盖项	因缺少环境、凭据、数据或时间没有验证的部分

这份账本可以写在 PR 描述、项目 notebook、发布记录或审校文档里。关键是不要只写“已验证”，而要写清楚“验证覆盖了什么”。例如：

改动范围：新增 React 技术卡片和章节索引计数。
核心风险：示例代码不可编译、README 卡片数量漂移。
验证动作：运行 React 代码块 verifier、索引计数 verifier、git diff --check。
结果证据：所有代码块通过 TypeScript strict 检查，索引统计与文件系统一致。
未覆盖项：没有做浏览器渲染截图检查，因为本轮只改 Markdown 书稿。

验证账本的另一个价值是帮助下一轮 Agent 接力。后续执行者不需要重新猜测“上次到底查过什么”，只要沿着未覆盖项继续补验证，或者在新增改动后复用同一组命令。

验证失败后的改道

验证失败不是“任务失败”，而是工作流获得了更精确的反馈。Agent 最危险的做法，是在测试失败后继续按原计划堆改动，或者只写一句“有报错待处理”。更可靠的处理方式是把失败输出立即转成新的下一步。

可以按这个顺序处理：

1. 冻结当前判断：先承认结论还不能成立，不要继续说“已完成”。
2. 摘出最小证据：记录失败命令、关键错误行、影响范围，不复制整段噪声日志。
3. 重排计划：把下一步从“继续扩展功能”改成“复现并修正这个失败”。
4. 缩小验证面：优先找能最快复现问题的单测、最小脚本或最小页面路径。
5. 显式交接未解项：如果本轮无法修完，交接里要写清入口文件、失败命令和第一个排查假设。

一个轻量交接格式：

验证失败：`pnpm test selectors.test.cjs` 未通过。
关键证据：`selectTaskById` 对已完成任务返回 `undefined`，与详情页预期不一致。
计划改道：暂停新增详情页字段，先补 selector 的状态覆盖。
下一条命令：复跑 `pnpm test selectors.test.cjs -- --runInBand`，确认失败是否稳定。
未解项：尚未验证浏览器页面，因为数据选择器还没有通过单测。

这类记录的重点不是保存所有日志，而是让下一轮执行者不用重新猜“为什么停下”：它应该能直接复制失败命令、打开入口文件，并知道第一步是缩小问题而不是扩大改动。

节拍器式工作流

很多 Agent 不一定长期在线执行一个大任务，而是通过定时唤醒形成工作节拍。节拍器式工作流的关键不是“每次都写一份总结”，而是让每次唤醒都完成一个小闭环：复盘、取舍、推进、验证、记录。

一个实用的定时唤醒模板：

读取时间与仓库状态 → 复盘上一段 → 列候选任务 → 选择一个低风险切片 → 执行 → 验证 → 记录接力点

设计这类工作流时要注意四个边界：

边界	做法
不抢用户改动	修改前检查 git 状态，只提交本轮明确相关文件
不把记录当成果	notebook 只记录决策和证据，真正成果应落在代码、文档、书稿或脚本里
不空泛规划	每次候选任务都要能拆成下一步可执行动作
不跳过验证	内容类任务至少有结构检查或人工可复核标准，代码类任务必须跑相关命令

这种模式适合个人知识库、书稿、长期项目维护和信息扫描。它的价值在于把“偶尔想起来再整理”变成稳定资产积累：每次只推进一小块，但每一块都有文件变更、验证结果和下一次接力点。

接力点模板

多轮 Agent 协作最容易丢失的不是“做了什么”，而是“为什么停在这里、下一步应该先碰哪里”。接力点应该像一个小型任务单，帮助下一轮执行者快速恢复上下文，同时避免重复探索。

一个可复用模板：

### 后续接力
- 当前状态：本轮已完成到什么程度，哪些文件已经提交或等待提交。
- 下一步优先级：下一轮最值得先做的一件事，而不是一串愿望清单。
- 入口文件：下一轮应优先读取或修改的相对路径。
- 验证命令：复用哪些命令确认没有破坏现有行为。
- 风险提示：哪些未覆盖项、外部依赖或已有脏改动不能误碰。

写接力点时要避免两种常见问题：

1. 只写方向，不写入口：例如“继续优化文档”太宽泛；更好的写法是“从 docs/documents/trending/ai/agent-workflow.md 的实践清单继续，补一条验证账本检查项”。
2. 把未确认事项写成事实：如果没有跑构建、没有验证链接、没有确认脏改动归属，就应该明确标成未覆盖项，而不是默认为可用。

接力点的质量标准是：下一轮 Agent 不需要重新做完整考古，就能在十分钟内开始一个低风险、小范围、可验证的改动。

进度反馈设计

Agent 不应该机械地频繁打扰用户。更好的反馈策略是：

• 短任务：直接给最终结果。
• 长任务：在关键节点汇报，而不是固定时间刷屏。
• 遇到阻塞：说明已尝试的方法、失败原因和可选方案。
• 有风险动作：先说明范围，再等待确认或选择低风险替代方案。

进度反馈的重点不是“我还在工作”，而是让用户知道：当前是否偏离目标、是否需要决策、是否已经有可验证产物。

学习教练场景

Agent 也可以用于学习陪伴，但要避免空泛激励。更有效的学习教练反馈应该包含：

1. 当前学习主题；
2. 一个具体小练习；
3. 一个自检问题；
4. 一个可复盘的输出物。

例如：

今天练习“异步错误处理”。先写一个会失败的异步请求，再补上重试、超时和错误分类。完成后回答：哪些错误应该重试，哪些错误应该直接暴露给用户？

这样的反馈比口号式提醒更有用，因为它能引导用户产生实际作品和复盘材料。

技术卡片工作流

技术卡片适合作为学习和复盘的中间产物，但要避免模板化灌水。一个可维护的技术卡片可以采用以下结构：

# 主题名称

## 适用场景

这个技术解决什么问题，不适合什么场景。

## 核心概念

用自己的话解释关键机制。

## 最小示例

给出一段可以运行或接近真实场景的代码。

## 常见误区

列出容易误解或踩坑的点。

## 延伸阅读

放官方文档或高质量资料。

质量检查可以关注：

• 是否有真实例子，而不是只写“很重要”；
• 是否解释了适用边界；
• 是否引用了可靠资料；
• 是否能在几个月后继续维护。

安全与隐私

Agent 工作流经常接触项目路径、聊天记录、任务日志和配置文件。整理成公开文档时要特别注意：

• 删除私有路径、群 ID、用户 ID、token、连接串；
• 删除平台或内部工具的品牌化口号；
• 不把临时日志当成正式资料；
• 不保留“自动生成第几次”之类的过程元信息；
• 对不确定的经验写成建议，不写成绝对规则。

实践清单

开始设计或改造一个 Agent 工作流时，可以按这个清单检查：

• [ ] 是否明确了目标、完成标准和失败处理方式？
• [ ] 是否定义了可用工具和禁止动作？
• [ ] 是否把任务拆成一个低风险、可验证的小闭环？
• [ ] 是否在行动前读取必要上下文和当前 git 状态？
• [ ] 是否有覆盖核心风险的验证命令或验收步骤？
• [ ] 是否记录了验证账本：改动范围、核心风险、验证动作、结果证据、未覆盖项？
• [ ] 如果验证失败，是否把失败命令、关键证据和计划改道写清楚？
• [ ] 是否留下了可接力的下一步：当前状态、入口文件、验证命令和风险提示？
• [ ] 是否能避免固定频率的无意义打扰？
• [ ] 是否会把稳定经验沉淀为文档、脚本或模板？
• [ ] 是否能过滤敏感信息和临时过程信息？

这份清单不适合一次性写完后束之高阁，而应该嵌入真实节奏：每次任务开始前用它约束取舍，任务结束时用它补齐验证和接力。对于个人知识库、书稿和长期项目来说，最有价值的不是“某次 Agent 表现很好”，而是每次都留下下一次可以继续放大的资产。

小结

Agent 工作流的核心不是“让模型更像人”，而是让它像一个可靠的协作者：知道目标、尊重边界、能执行、会验证、可复盘。对于程序员来说，最值得投入的方向是把自己的重复流程变成可验证、可维护、可迭代的工作系统。