企业官网建设流程全解析

1. 从热榜标题里读出真实信号：agency-agents 到底在解决什么问题

GitHub 热榜上每天都有新面孔，但msitarzewski/agency-agents这个仓库能在 3 月 11 日冲到榜单前列，背后反映的不是某个炫技项目，而是一个很朴素的需求：让 AI 智能体真正像一个团队一样协作干活。仓库名里的 "agency" 不是"代理"的意思，而是"机构、团队"——它想做的事情是把多个 AI 智能体组织成一个有分工、有流程、有交付标准的工作单元。

我第一时间去翻了这个仓库的结构，发现它最核心的资产不是代码，而是一整套Markdown 格式的智能体定义文件。每个.md文件描述一个"角色"：这个角色叫什么、负责什么、用什么工具、遵循什么工作流、输出什么格式。这种设计思路和市面上大多数"一个超级 Prompt 打天下"的做法完全不同，它走的是角色化拆分 + 流程编排的路线。

为什么这件事值得关注？因为过去一年我见过太多人搭智能体时踩同一个坑：把所有能力塞进一个系统提示词里，结果模型在长对话中逐渐"人格分裂"，一会儿是客服、一会儿是程序员、一会儿又变成文案，最后哪个角色都做不专业。agency-agents 的思路是把这种混乱从根上解决——一个智能体只干一件事，多个智能体通过明确的交接协议串起来。

这篇文章适合三类人看：一是正在用 Claude Code、Cursor 这类工具做自动化工作流的人；二是想理解"多智能体协作"到底怎么落地、而不是停留在概念层面的人；三是手上有重复性业务流程、想用 AI 拆解成流水线的人。我会从仓库结构、Markdown 定义规范、协作机制、实操搭建、常见坑这几个角度，把这个项目拆透。

提示：本文讨论的是公开仓库的设计思路与通用智能体编排方法，所有示例均为通用场景，不涉及任何特定平台或服务的接入细节。

2. 仓库结构拆解：为什么它选择 Markdown 而不是代码

2.1 用 Markdown 定义智能体，是一个被低估的决策

第一次看到这个仓库时我有点意外——一个智能体协作框架，核心文件居然是.md而不是.py或.ts。但仔细想过之后，我认为这是整个项目最聪明的设计决策之一。

Markdown 定义智能体有几个天然优势。第一，可读性极高。任何人打开一个角色文件，不需要懂编程就能看懂这个智能体是干什么的。第二，版本管理友好。Git diff 能清晰显示你改了哪句话、加了哪条规则，这在调试智能体行为时非常关键。第三，跨工具通用。同一份 Markdown 定义，理论上可以被不同的运行时加载，不绑定某个特定框架。

我实测过用 JSON 或 YAML 定义智能体，问题在于：当规则变复杂时，嵌套层级会深到难以维护，而且写注释很别扭。Markdown 用标题层级天然表达"角色定位 → 职责 → 工具 → 流程 → 输出规范"这种结构，比任何配置文件都直观。

2.2 一个标准角色文件包含哪些字段

根据我对仓库内多个角色文件的观察，一个完整的智能体定义通常包含这几个部分：

我特别想强调最后一项"边界与拒绝条件"。大多数人写智能体提示词时只写"你要做什么"，从不写"你不能做什么"。结果就是模型遇到超出能力范围的请求时，会硬编一个答案出来。agency-agents 的很多角色文件里明确写了类似"如果输入缺少 X 字段，直接返回错误而不是猜测"这样的规则，这是工程化思维和玩具思维的分水岭。

2.3 目录组织方式透露的协作逻辑

仓库的目录结构不是按技术类型分的，而是按职能域分的。这种组织方式暗示了它的协作模型：智能体之间不是随意调用的，而是按照业务流程的上下游关系组织的。

举个通用例子，一个内容生产流程可能被拆成：需求分析智能体 → 资料检索智能体 → 初稿撰写智能体 → 事实核查智能体 → 格式排版智能体。每个智能体只关心自己那一段，上游的输出就是下游的输入。这种流水线式协作比"一个全能智能体"稳定得多，因为每一步的输入输出都被约束住了，出错时也容易定位是哪一环的问题。

3. 多智能体协作的三种模式与 agency-agents 的取舍

3.1 三种主流协作模式对比

在动手搭之前，得先搞清楚多智能体到底有哪几种协作方式。我梳理下来主要是这三种：

• 流水线模式（Pipeline）：A 做完交给 B，B 做完交给 C，单向流动。优点是可控、易调试；缺点是慢，且上游错误会一路传下去。
• 辩论模式（Debate）：多个智能体对同一问题给出方案，再由一个裁判智能体择优或综合。优点是质量高；缺点是成本翻倍甚至翻几倍。
• 主管调度模式（Orchestrator）：一个主管智能体根据任务动态决定调用谁、调用几次。优点是灵活；缺点是主管本身容易成为瓶颈和错误源。

agency-agents 的设计明显偏向流水线为主、主管调度为辅。为什么这么选？因为流水线的可预测性在工程落地中比灵活性更重要。你给客户交付一个自动化流程，最怕的是它今天跑得通、明天因为调度逻辑变化就跑不通了。流水线的行为是确定的，这对生产环境至关重要。

3.2 交接协议才是协作的命门

我见过太多多智能体项目死在"交接"上。A 智能体输出了一段漂亮的自然语言，B 智能体却不知道怎么解析，于是开始瞎猜。agency-agents 用 Markdown 定义输出格式，本质上是在强制约定交接协议。

一个可靠的交接协议应该长这样：

## 输出格式 - task_id: 字符串，唯一标识 - status: 枚举值 [success, partial, failed] - payload: 结构化数据 - next_action: 建议的下一步 - confidence: 0-1 之间的浮点数

关键在status和confidence这两个字段。有了status，下游智能体能判断该继续还是该回退；有了confidence，主管智能体能决定是否需要人工介入。这两个字段是我在实际项目里加了之后，整个流程稳定性提升最明显的改动。

3.3 什么时候不该用多智能体

这里必须泼一盆冷水。不是所有任务都值得拆成多智能体。我的判断标准很简单：如果任务步骤少于三步，或者步骤之间没有明确的数据依赖，就别拆。

拆分的成本包括：每个智能体都要消耗一次模型调用、交接过程会损失信息、调试复杂度成倍上升。我踩过的坑是：把一个本来两步就能搞定的文案润色任务拆成了五个智能体，结果总耗时从 20 秒涨到 90 秒，质量还没提升。后来老老实实合并回一个智能体，反而更稳。

agency-agents 的价值在于它提供了拆分的方法论和模板，但用不用、拆多细，得根据你的实际任务量来定。

4. 从零搭一个可用的智能体团队：完整实操链路

4.1 环境准备与工具选型

要跑通这套东西，你需要一个能加载 Markdown 定义并调用模型的运行时。目前主流选择是 Claude Code 这类支持自定义指令的工具，或者自己用 API 写一个轻量调度器。我两种都试过，说下取舍。

用现成工具的好处是省事，它自带文件读写、命令执行等能力，你只要把角色 Markdown 放进去就行。缺点是灵活性受限，复杂的条件分支不好实现。自己写调度器的好处是完全可控，缺点是所有工具能力都得自己接。

我的建议是：先用现成工具跑通单智能体，确认角色定义有效，再考虑要不要上自研调度器。很多人一上来就写框架，结果框架写完了，智能体本身还没调好，本末倒置。

4.2 写第一个角色定义文件

假设我们要做一个"技术文档校对"智能体，文件可以这样写：

# 角色：技术文档校对员 ## 定位 你负责检查技术文档的准确性、一致性和可读性，不负责重写内容。 ## 核心职责 1. 检查术语使用是否前后一致 2. 检查代码示例是否与正文描述匹配 3. 标记模糊表述，但不擅自修改原意 ## 工作流程 1. 通读全文，建立术语表 2. 逐段检查，记录问题 3. 按严重程度分类输出 ## 输出格式 | 位置 | 问题类型 | 原文 | 建议 | 严重程度 | |------|---------|------|------|---------| ## 边界条件 - 不修改作者的技术观点 - 遇到无法判断对错的内容，标记为"待确认"而非直接改

这份定义的关键在于"边界条件"那一段。我实测发现，加上明确的拒绝规则后，智能体乱改内容的情况减少了大概七成。

4.3 把多个角色串成流水线

单角色跑通后，下一步是串联。假设流程是"资料整理 → 初稿撰写 → 校对 → 排版"，你需要一个调度逻辑：把上游的输出作为下游的输入，并在每一步检查status字段。

这里有个实操细节：每一步的中间产物都要落盘保存。不要只在内存里传递。原因是一旦下游出错，你需要回看上游到底给了什么。我吃过这个亏，中间结果没存，出问题后完全不知道是哪一步开始偏的，只能整条重跑。

4.4 用真实任务验证，而不是用玩具例子

验证阶段最忌讳用"写一首诗"这种玩具任务。要用你真实业务里的任务，哪怕它很枯燥。我通常拿三类任务测：一类是正常输入，一类是缺字段的残缺输入，一类是明显超范围的输入。看智能体在三种情况下的表现是否符合预期。

残缺输入最能暴露问题。很多智能体遇到缺字段时会自己编一个默认值，然后一路错下去。好的定义应该让它在这种情况下直接返回failed并说明缺什么。

5. 调试智能体时最容易踩的五个坑

5.1 提示词越长越好？恰恰相反

新手最容易犯的错是把角色定义写成一篇论文。我见过一个角色文件写了三千多字，结果模型执行时反而抓不住重点。原因是长提示词里规则互相冲突的概率大幅上升，模型不知道该听哪条。

我的经验是：单个角色定义控制在 500 到 800 字之间，超过就说明这个角色承担了太多职责，应该拆。agency-agents 里那些高质量的角色文件，普遍都很克制。

5.2 输出格式不固定，下游全乱套

这是最隐蔽的坑。上游智能体这次输出 JSON，下次输出 Markdown 表格，下游解析逻辑就崩了。解决办法是在角色定义里用示例锁定格式，并且明确写"必须严格按此格式输出，不要添加额外说明文字"。

我还会在调度器里加一层格式校验，格式不对就重试一次。这个重试机制救过我很多次。

5.3 忽略 token 成本，流程跑起来才发现贵

多智能体流程的 token 消耗是单智能体的数倍。一个五步流程，如果每步都塞入完整上下文，成本会爆炸。优化手段有两个：一是只传必要字段，不要把上游的全部输出无脑传给下游；二是给每个角色设定输出长度上限。

我做过对比，优化前后同样的任务，token 消耗能差三到四倍。这在规模化使用时是实打实的成本差异。

5.4 没有失败重试和降级策略

生产环境里模型调用失败是常态，不是例外。你的流程必须能处理：调用超时怎么办、返回格式错误怎么办、连续失败几次后怎么办。我的做法是每个步骤最多重试两次，两次都失败就标记为需要人工处理，而不是无限重试烧钱。

5.5 把智能体当黑盒，不做日志

调试多智能体流程，日志是命根子。我要求每个步骤都记录：输入摘要、输出摘要、耗时、token 数、status。有了这些数据，出问题时能快速定位。没有日志的话，你只能靠猜，效率极低。

6. 这套思路能延展到哪些真实场景

6.1 内容生产流水线

这是最直接的应用。把"选题 → 资料收集 → 初稿 → 事实核查 → 润色 → 排版"拆成六个角色，每个角色专注一件事。我实测下来，这种流水线产出的内容一致性比单智能体好很多，尤其是术语和风格统一性。

6.2 代码审查辅助

把代码审查拆成"逻辑检查""安全扫描""风格规范""文档完整性"几个角色，各自输出问题清单，最后汇总。好处是每个角色可以用不同的检查标准，互不干扰。

6.3 数据清洗与结构化

原始数据往往格式混乱。用"格式识别 → 字段提取 → 校验 → 标准化输出"这条流水线，比写一堆正则表达式更灵活，因为智能体能处理正则搞不定的模糊情况。

6.4 客服工单分类与路由

工单进来后，先由分类智能体判断类型，再由对应的处理智能体接手。这种场景下，主管调度模式比流水线更合适，因为工单类型是动态的。

我在实际使用中发现，agency-agents 这类项目的真正价值不在于它提供了多少现成角色，而在于它示范了一种把复杂任务工程化拆解的思维方式。角色定义文件写得好不好，本质上反映的是你对业务流程理解得清不清楚。如果连你自己都说不清一个任务分几步、每步的输入输出是什么，那再好的框架也救不了。反过来，如果你能把流程讲明白，用 Markdown 手写几个角色文件，配合任意一个支持自定义指令的工具，就能跑起来。最后分享一个小技巧：每次调整角色定义后，别急着跑完整流程，先用一个最小输入单独测这个角色，确认它的行为符合预期再接入流水线，这样能省下大量排查时间。