企业官网建设流程全解析

1. 为什么需要给 AI Agent 配一套工程工作流

1.1 从“能聊”到“能干”的鸿沟

很多人第一次接触 AI Agent 的时候，都会有一种惊艳感：你给它一句话，它能帮你查资料、写代码、整理文档，甚至还能调用外部工具。但用不了几天，热情就会迅速冷却。原因很简单——单次对话的惊艳，替代不了持续交付的稳定。

我最初用 Agent 做项目的时候，踩的第一个坑就是“每次都要重新交代一遍背景”。今天让它帮我处理一个数据清洗脚本，明天再开一个会话，它完全不记得昨天定的命名规范、目录结构、异常处理约定。结果就是：每次输出的代码风格都不一样，变量命名一会儿驼峰一会儿下划线，日志格式今天用 JSON 明天用纯文本。你没法把它当成一个靠谱的工程伙伴，只能当成一个“随机应变的临时工”。

这就是标题里说的“工程工作流”要解决的核心问题。Agent 本身的能力是原料，工作流才是把原料变成产品的流水线。没有工作流的 Agent，就像一个有天赋但没受过职业训练的实习生——偶尔灵光一现，但你不能把关键任务交给它。

1.2 什么是 Agent 的“工程工作流”

我说的工程工作流，不是指某个具体框架或者某个平台的功能，而是一套约束 Agent 行为、沉淀项目知识、保证输出一致性的机制。它至少包含四个层面：

• 角色与边界定义：这个 Agent 是谁，负责什么，不负责什么，遇到什么情况必须停下来问人。
• 知识与上下文管理：项目背景、技术栈、编码规范、历史决策，怎么让 Agent 每次都能拿到。
• 任务拆解与执行流程：一个大需求进来，怎么拆成 Agent 能一步步执行的小任务，每步的输入输出是什么。
• 质量校验与反馈闭环：Agent 的输出怎么检查，错了怎么回滚，经验怎么沉淀到下一轮。

这四层缺一不可。我见过太多人只做了第一层，给 Agent 写了一段很长的系统提示词，然后就指望它包打天下。结果就是提示词越写越长，Agent 越来越“精神分裂”，最后连你自己都搞不清楚它到底该听哪一条。

1.3 适合谁来搭建这套工作流

如果你只是偶尔用 Agent 查个资料、写个周报，那这套东西对你来说太重了，没必要。但如果你符合下面任意一条，那这套工作流就是刚需：

• 你每天有大量重复性的开发、运维、数据处理任务，希望 Agent 能接手一部分。
• 你在团队里推动 Agent 落地，但发现每个人用出来的效果天差地别。
• 你已经在用 Agent 做多步骤任务，但经常在中间某一步“跑偏”，需要反复纠正。
• 你想把 Agent 集成到现有的 CI/CD、项目管理、文档体系里，而不是让它当一个孤立的聊天窗口。

我自己的经验是，当你的 Agent 任务超过三步、涉及两个以上文件、或者需要跨会话保持一致性的时候，就必须上工作流了。否则你花在“擦屁股”上的时间，会远远超过 Agent 帮你省下来的时间。

2. 工作流的核心模块拆解与设计思路

2.1 角色定义：给 Agent 一个“岗位说明书”

很多人写 Agent 提示词，喜欢写“你是一个资深工程师”。这句话太空了，Agent 根本不知道“资深”意味着什么。我现在的做法是，把角色定义写成一份岗位说明书，包含以下字段：

这份说明书不是写一次就完事的。我一般会在项目初期写一个初版，然后在每次 Agent “犯错”之后，把新的约束补进去。角色定义是活的，它是你和 Agent 之间不断磨合出来的契约。

注意：角色定义不要超过 500 字。我试过写 2000 字的角色定义，结果 Agent 在执行任务时经常“忘记”后面的内容。后来我改成“核心角色定义 + 按需加载的规范文档”，效果好了很多。

2.2 上下文管理：让 Agent 每次都“记得”项目背景

上下文管理是工作流里最容易被忽视、但最影响效果的部分。我见过太多人把项目背景、技术规范、历史决策全部塞进系统提示词，结果就是提示词膨胀到几千字，Agent 的注意力被稀释，关键信息反而被淹没。

我的做法是分层管理上下文：

• 常驻层：角色定义、核心约束、输出规范。这部分每次对话都必须带上，但控制在 500 字以内。
• 项目层：当前项目的技术栈、目录结构、关键模块说明。这部分按项目组织成独立文档，Agent 需要时通过工具读取。
• 任务层：当前任务的具体需求、相关文件、历史讨论。这部分在每次任务开始时动态注入。
• 经验层：踩过的坑、常见错误、修复方案。这部分以“经验库”的形式存在，Agent 在遇到类似问题时主动检索。

这样做的逻辑是：Agent 的上下文窗口是有限资源，要把最相关的信息放在最前面，把可能用到的信息放在可检索的地方。就像你给一个新同事交代工作，你不会把公司所有规章制度都背给他听，而是告诉他“员工手册在共享盘里，遇到具体问题去查对应章节”。

2.3 任务拆解：把“大需求”变成“小步骤”

Agent 最怕的就是模糊的大需求。你让它“优化一下这个模块的性能”，它要么无从下手，要么给你一堆泛泛的建议。但如果你说“把这个函数里的循环查询改成批量查询，并加上缓存”，它就能干得很漂亮。

所以工作流里必须有一个任务拆解环节。我的做法是让 Agent 自己先拆，然后我来审核。具体流程是：

1. 我给出一个需求描述。
2. Agent 输出一个任务清单，每个任务包含：目标、输入、输出、验收标准。
3. 我审核这个清单，调整不合理的部分。
4. Agent 按清单逐项执行，每完成一项就标记状态。

这个流程的好处是，在动手之前就把问题暴露出来。很多时候 Agent 拆出来的任务清单，会让我发现“原来这个需求还有这个坑没考虑到”。这比它闷头干完再返工要高效得多。

2.4 质量校验：给 Agent 的输出加一道“安检”

Agent 的输出质量是不稳定的，这是事实。你不能指望它每次都一次做对，所以必须有一套校验机制。我的校验分三层：

• 自动校验：代码跑一遍 lint、单元测试、类型检查。这层是机器做的，不通过就直接打回。
• 规则校验：检查输出是否符合项目规范，比如日志格式、命名风格、注释要求。这层可以用脚本做，也可以让另一个 Agent 做。
• 人工抽检：关键决策、架构变更、涉及生产环境的操作，必须人工确认。

这三层的比例大概是 70% 自动、20% 规则、10% 人工。人工抽检的比例不能太高，否则工作流就失去了意义；但也不能没有，否则迟早出大事。

3. 实操：从零搭建一套可复用的 Agent 工作流

3.1 目录结构设计：让工作流“有地方放”

工作流不是一堆提示词，它需要物理载体。我一般会在项目根目录下建一个.agent目录，结构如下：

.agent/ ├── role.md # 角色定义 ├── context/ │ ├── project.md # 项目背景 │ ├── stack.md # 技术栈说明 │ └── conventions.md # 编码规范 ├── tasks/ │ ├── template.md # 任务模板 │ └── active/ # 进行中的任务 ├── experience/ │ ├── pitfalls.md # 踩坑记录 │ └── patterns.md # 最佳实践 └── scripts/ ├── validate.sh # 自动校验脚本 └── inject.sh # 上下文注入脚本

这个结构的好处是所有工作流相关的文件都在一个地方，方便版本管理和团队共享。新人加入项目，直接看.agent目录就知道这个项目的 Agent 是怎么用的。

3.2 角色定义文件怎么写

role.md是整个工作流的入口。我一般按下面的模板写：

# 角色：数据管道维护工程师 ## 核心职责 - 编写和修改 ETL 脚本 - 排查数据异常并生成报告 - 维护数据质量监控规则 ## 技术约束 - 语言：Python 3.10+ - 依赖：仅使用项目已有依赖，禁止新增 - 数据库：只读权限，禁止执行 DDL ## 输出规范 - 代码必须带类型注解 - 日志使用 structlog，禁止 print - 每个函数必须有 docstring ## 升级条件 - 涉及数据库 schema 变更 - 涉及生产环境配置修改 - 单次任务预计超过 30 分钟

这个文件我一般控制在 300 字左右。关键是要具体，不要写“保证代码质量”这种空话，要写“必须带类型注解”这种可检查的规则。

3.3 上下文注入的实操方法

上下文注入的核心是按需加载。我一般用两种方式：

方式一：启动时注入常驻上下文

在每次会话开始时，把role.md和context/project.md的内容拼接到系统提示词里。这部分是固定的，每次都要带。

方式二：任务中动态检索

当 Agent 需要了解某个具体模块的规范时，让它通过工具读取context/conventions.md的对应章节。比如它要写一个数据库查询，就让它先读“数据库操作规范”那一节。

我实测下来，方式一比方式二重要得多。因为常驻上下文决定了 Agent 的“基本盘”，如果基本盘不稳，后面怎么检索都救不回来。

3.4 任务模板与执行流程

tasks/template.md是我用来规范任务描述的。每次给 Agent 派活，我都按这个模板填：

# 任务：修复用户登录接口的超时问题 ## 背景 用户反馈登录接口在高峰期经常超时，平均响应时间从 200ms 涨到了 2s。 ## 目标 将登录接口的 P99 响应时间降到 500ms 以内。 ## 输入 - 相关文件：`src/api/auth.py` - 相关日志：`logs/auth-2024-01.log` - 相关监控：`dashboard/auth-latency` ## 输出 - 修改后的代码 - 性能对比报告 - 变更说明 ## 验收标准 - P99 响应时间 < 500ms - 单元测试全部通过 - 不引入新的依赖 ## 约束 - 禁止修改数据库 schema - 禁止修改接口签名

这个模板的关键是验收标准必须可量化。“性能优化”不是验收标准，“P99 < 500ms”才是。

3.5 自动校验脚本的编写

scripts/validate.sh是我用来做自动校验的。内容根据项目不同而不同，但核心逻辑是一样的：

#!/bin/bash set -e echo "Running lint..." ruff check src/ echo "Running type check..." mypy src/ echo "Running tests..." pytest tests/ -x echo "Checking log format..." python scripts/check_log_format.py echo "All checks passed."

这个脚本我会挂到 Agent 的工作流里，让它每次改完代码自动跑一遍。不通过就不允许提交。这比人工检查靠谱多了，而且 Agent 自己也能根据报错信息修复问题。

4. 常见问题与排查技巧实录

4.1 Agent “忘记”角色定义怎么办

这是最常见的问题。表现是 Agent 在执行任务时，突然用了禁止的依赖，或者输出格式不符合规范。原因通常是上下文太长，角色定义被“挤”到了后面，注意力权重下降。

我的解决方法有三个：

• 把角色定义放在系统提示词的最前面，并且用分隔符明确标出。比如用=== ROLE ===和=== END ROLE ===包起来。
• 在任务描述里重复关键约束。比如在任务模板的“约束”字段里，再写一遍“禁止新增依赖”。
• 用工具强制校验。比如在 CI 里加一个检查，如果发现新增了依赖就直接失败。

实测下来，方法二最有效。因为 Agent 对“最近看到的内容”注意力最高，在任务描述里重复约束，相当于给它“划重点”。

4.2 任务拆解太粗或太细怎么办

任务拆解太粗，Agent 执行时容易跑偏；太细，又会导致任务数量爆炸，管理成本太高。我的经验是按“可独立验证”的原则来拆。

具体来说，每个任务应该满足：

• 有明确的输入和输出
• 可以在 10 分钟内完成
• 完成后可以独立验证（跑测试、看日志、检查输出文件）

如果一个任务需要 30 分钟以上，就继续拆；如果一个任务完成后没法独立验证，就合并到相邻任务里。

4.3 常见问题速查表

4.4 几个我踩过的坑

坑一：角色定义写太长。我一开始写了 2000 字的角色定义，结果 Agent 经常“忘记”后面的内容。后来改成 300 字的核心定义 + 按需加载的规范文档，效果好多了。

坑二：任务模板太复杂。我一开始设计了 10 个字段的任务模板，结果每次填模板就要花 5 分钟。后来精简到 6 个字段，效率提升明显。

坑三：校验脚本太严格。我一开始把 lint 规则设得很严，结果 Agent 每次改代码都要花大量时间修 lint 问题。后来把规则分成“必须通过”和“建议通过”两档，效率高了很多。

坑四：经验库不更新。我一开始没重视经验库，结果 Agent 反复犯同一个错。后来规定每次 Agent 犯错，必须把问题和解决方案写进pitfalls.md，情况才好转。

5. 工作流的迭代与扩展

5.1 从单 Agent 到多 Agent 协作

当任务复杂度上来之后，单 Agent 会力不从心。这时候可以考虑多 Agent 协作。我的做法是按职能拆分：

• 规划 Agent：负责拆解任务、制定计划
• 执行 Agent：负责具体操作
• 校验 Agent：负责检查输出质量

这三个 Agent 共享同一套上下文，但角色定义不同。规划 Agent 关注“做什么”，执行 Agent 关注“怎么做”，校验 Agent 关注“做得对不对”。

5.2 工作流的版本管理

.agent目录我会纳入 Git 管理，每次修改都提交。这样做的好处是：

• 可以追溯每次修改的原因
• 可以回滚到之前的版本
• 团队成员可以共享同一套工作流

我一般会在 commit message 里写清楚修改原因，比如“修复 Agent 忘记日志格式的问题”。

5.3 工作流的度量

工作流好不好，不能凭感觉，要有数据。我一般关注这几个指标：

• 一次通过率：Agent 输出不需要返工的比例
• 平均任务时长：从派活到验收通过的时间
• 人工干预率：需要人工介入的任务比例
• 经验库命中率：Agent 遇到问题时，经验库里有对应记录的比例

这些指标我一般每周统计一次，用来判断工作流是否需要调整。

6. 一些个人体会

我搭这套工作流大概花了三个月，中间推翻重来了两次。最大的体会是：工作流不是设计出来的，是磨出来的。你不可能一开始就设计出一套完美的工作流，只能在实践中不断调整。

另一个体会是：不要追求自动化一切。有些环节人工介入反而更高效，比如关键决策、架构变更、涉及生产环境的操作。工作流的目标是“让 Agent 做它擅长的事，让人做人擅长的事”，而不是“让人完全放手”。

最后分享一个小技巧：每次 Agent 犯错，不要只修当前的问题，要把这个错误写进经验库。这样下次遇到类似问题，Agent 就能自己查经验库解决。我现在的经验库里有 50 多条记录，Agent 的自主解决率从最初的 30% 提升到了 70% 以上。

这个工作流后续还可以这样扩展：把经验库做成向量数据库，让 Agent 通过语义检索找到相关经验；把任务模板做成可视化表单，降低填写成本；把校验脚本集成到 CI/CD 流水线，实现全自动校验。这些都是我接下来打算尝试的方向。