企业官网建设流程全解析

多智能体协作这个词这两年出现的频率越来越高，但真正动手搭过一套能跑起来的协作框架的人并不多。大多数人卡在两个地方：一是起步门槛，光是环境配置和概念理解就能耗掉一整天；二是架构认知，跑通了 Demo 却说不清楚各个模块之间到底怎么协作、为什么这么设计。oh-my-claudecode 这个项目恰好在这两个点上做了不少工程化的取舍，它的快速开始流程被压缩到五分钟级别，架构上也把"编排层"和"执行层"做了明确切分。我前后花了大概两周时间把它从零跑通，又拆了一遍源码结构，这篇就把起步流程和架构设计这两块掰开揉碎讲清楚，适合想快速上手多智能体协作、又不想被一堆抽象概念劝退的开发者参考。

1. 先搞清楚这套东西到底在解决什么问题

1.1 从单智能体的天花板说起

单个智能体干活，本质上就是"一个大脑配一套工具"。你给它一个任务，它规划、调用工具、拿结果、再规划，循环到任务完成。这套模式在简单场景下很好用，比如查个资料、改段代码、写个摘要。但任务一旦复杂起来，问题就暴露了：上下文窗口是有限的，一个智能体既要记住任务目标，又要记住中间每一步的工具返回，还要维护自己的推理链条，很快就会被撑爆。更麻烦的是，单智能体的规划能力和执行能力是耦合在一起的，它规划得好不一定执行得细，执行得细又容易在长链条里跑偏。

我实测过一个典型场景：让单智能体完成"读取一个项目目录、分析依赖关系、生成重构建议、再逐文件落地修改"这样的任务。前两步还行，到第三步开始明显吃力，它会把前面读过的文件内容忘掉一部分，生成的建议和实际文件对不上号。这不是模型能力的问题，是单智能体架构本身的结构性瓶颈。

1.2 多智能体协作的核心价值在哪

多智能体协作的思路很直接：把一个大任务拆成若干子任务，每个子任务交给专门的智能体去做，智能体之间通过某种协议交换信息。这样做的好处有三层。第一层是上下文隔离，每个智能体只关心自己那部分上下文，窗口压力小很多。第二层是能力专精，负责规划的智能体可以专注于拆解任务，负责执行的智能体可以专注于调工具，各司其职。第三层是可并行，互不依赖的子任务可以同时跑，整体耗时能压下来。

oh-my-claudecode 这个项目就是围绕这三层价值来设计的。它没有去造一个新的模型，而是在模型之上搭了一套编排框架，把"谁来做、做什么、怎么交接"这三件事用代码固化下来。理解这一点很关键，因为很多人一上来就去找"它的智能体有多强"，其实它的强项在编排，不在单个智能体的能力。

1.3 适合谁来读这篇

如果你是完全没接触过多智能体协作的新手，这篇的快速开始部分能让你在五分钟内跑起第一个协作任务，架构部分能帮你建立整体认知，不至于跑通了还一头雾水。如果你已经用过类似的编排框架，那架构设计那几节更值得看，尤其是编排层和执行层的切分方式、消息传递的约定，这些是决定你能不能把它改造成自己业务形态的关键。代码层面的细节我会尽量给到可直接复现的程度，但不会逐行念源码，重点放在"为什么这么设计"上。

2. 五分钟起步：从零到第一个协作任务

2.1 环境准备与依赖安装

起步阶段最容易劝退人的就是环境。oh-my-claudecode 的依赖不算多，但版本要求比较严格，我踩过一次版本不匹配的坑，折腾了快一个小时才发现是某个依赖的小版本号不对。下面是我实测下来最稳的一套流程。

先确认基础环境。Node.js 建议用 18 以上的 LTS 版本，Python 侧如果是走脚本方式调用，3.10 以上比较稳妥。这两项是硬性前提，版本低了会在安装阶段就报错，而且报错信息往往不直观，容易误判成网络问题。

node -v python3 --version

确认版本没问题后，拉取项目并安装依赖。这里有个细节：项目根目录下通常会有多个子包，安装时建议在根目录统一执行，不要进到子目录单独装，否则容易出现依赖提升不一致的问题。

git clone <项目地址> cd oh-my-claudecode npm install

安装过程中如果卡在某个包上超过两分钟，大概率是源的问题，换一个镜像源重试即可。这一步不需要额外配置什么环境变量，装完就能用。

2.2 最小可运行配置

依赖装完之后，需要一份最小配置才能跑起来。配置文件一般放在项目根目录，命名上遵循项目约定。最小配置只需要填三样东西：模型接入信息、工作目录、日志级别。模型接入这块按项目文档给的字段填就行，工作目录建议单独建一个空目录，不要指向项目自身，避免智能体读写时把源码搅乱。

{ "model": { "provider": "default", "name": "standard" }, "workspace": "./workspace", "logLevel": "info" }

提示：workspace 目录一定要提前建好，部分版本不会自动创建，缺失时启动会直接抛错，报错信息里不一定明确指向这个原因。

日志级别起步阶段建议用 info，能看到每个智能体的调度过程，方便你理解协作是怎么发生的。等跑顺了再调到 warn，减少输出噪音。

2.3 跑通第一个协作任务

配置就绪后，用项目自带的最小示例跑一遍。示例通常是一个"分析任务 + 执行任务"的两智能体协作，输入一句话需求，编排层会把它拆给分析智能体，分析结果再交给执行智能体落地。命令大致如下：

npm run demo -- --task "分析当前工作目录结构并生成一份说明文档"

跑起来之后，终端会依次打印编排层的调度日志、分析智能体的输出、执行智能体的动作。第一次跑建议全程盯着日志看，重点观察三件事：编排层是怎么把任务拆开的、两个智能体之间传了什么、执行智能体拿到的是原始需求还是加工后的指令。这三件事看明白了，架构的基本轮廓就有了。

实测下来，从 clone 到看到第一个任务跑完，熟练的话三分钟左右，第一次跑因为要下载依赖和模型响应，五分钟上下是正常水平。如果超过十分钟还没出结果，先检查 workspace 目录是否存在、模型配置是否填对，这两个是最常见的卡点。

3. 架构设计拆解：编排层与执行层怎么分工

3.1 整体分层结构

oh-my-claudecode 的架构可以粗略分成三层：接入层、编排层、执行层。接入层负责接收外部输入、做参数校验和格式转换；编排层是核心，负责任务拆解、智能体调度、消息路由；执行层是真正干活的智能体集合，每个智能体封装了自己的提示词、工具集和输出约定。

这个分层不是随便划的，它对应了一个很实际的工程需求：让编排逻辑和执行逻辑可以独立演进。编排层改调度策略，不需要动执行层的智能体；执行层加一个新智能体，只要遵守消息约定，编排层几乎不用改。我在改造这套框架适配自己业务时，最深的体会就是这个切分带来的便利——加一个"代码审查"智能体，只写了执行层的封装，编排层只加了一行注册，就跑通了。

3.2 编排层的职责边界

编排层做的事情听起来简单，实际边界很讲究。它负责三件事：任务拆解、智能体选择、消息路由。任务拆解是把用户输入变成一组有依赖关系的子任务；智能体选择是根据子任务类型匹配最合适的执行者；消息路由是把上游输出按约定格式传给下游。

关键在于，编排层不碰具体业务逻辑。它不知道"分析目录结构"具体该怎么分析，它只知道这个子任务该交给分析类智能体。这个边界一旦模糊，编排层就会膨胀成一个什么都管的上帝对象，后续维护会非常痛苦。我见过一些改造版本，把工具调用逻辑直接写进编排层，短期看省事，长期看每次加功能都要动核心调度代码，风险很高。

3.3 执行层的智能体封装约定

执行层的每个智能体都是一个独立单元，封装了四样东西：角色提示词、可用工具集、输入输出格式约定、失败重试策略。这四样里，输入输出格式约定是最容易被忽视但最影响协作顺畅度的。如果上游智能体输出的是一段自由文本，下游智能体就得靠猜来解析，协作链条越长，误差累积越严重。

项目里的做法是给每个智能体定义结构化的输出契约，上游必须按契约输出，下游按契约解析。这个设计牺牲了一点灵活性，换来的是协作链路的稳定性。我实测对比过结构化输出和自由文本输出两种方式，在三个智能体串联的任务里，结构化输出的任务成功率明显更高，主要差在中间环节的解析失败率上。

3.4 消息传递机制的设计考量

智能体之间怎么传消息，是架构里最需要想清楚的一环。oh-my-claudecode 采用的是显式的消息对象，每条消息包含发送者、接收者、类型、载荷四部分。类型字段区分了"任务下发""结果回传""异常上报"等几种语义，载荷则是结构化数据。

为什么不用简单的函数调用或者共享内存？因为多智能体协作里，消息是需要被记录和回溯的。显式消息对象天然适合打日志，出问题时能完整还原协作过程。我在排查一次协作死循环时，就是靠消息日志定位到某个智能体的输出触发了上游的重复调度。如果消息是隐式的函数调用，这个排查会困难得多。

4. 核心环节实操：把协作链路跑通并调优

4.1 定义一个自己的智能体

跑通示例之后，下一步就是加自己的智能体。定义一个智能体的最小单元包括：唯一标识、角色描述、工具列表、输出契约。下面是一个虚构的"文档整理"智能体的定义示例，字段名按项目约定来。

{ "id": "doc-organizer", "role": "负责将零散文档按主题归类并生成索引", "tools": ["readFile", "writeFile", "listDir"], "outputContract": { "type": "object", "properties": { "categories": { "type": "array" }, "indexPath": { "type": "string" } } } }

角色描述要写得具体，不要写"负责文档相关任务"这种模糊表述。角色描述直接影响智能体对自身职责的理解，写得越具体，它在边界情况下的判断越靠谱。工具列表按最小必要原则给，给多了会增加误用概率，给少了又干不了活，这个平衡需要根据实际任务调。

4.2 编排流程的配置方式

编排流程的配置决定了子任务之间的依赖关系。项目里用声明式的方式描述流程，每个节点是一个子任务，节点之间用依赖字段连接。下面是一个两节点串联的配置示例。

{ "flow": [ { "id": "analyze", "agent": "doc-organizer", "input": "${userInput}", "next": ["index"] }, { "id": "index", "agent": "doc-organizer", "input": "${analyze.output}", "next": [] } ] }

${analyze.output}这种引用语法是编排层解析依赖的关键，它让下游节点能直接拿到上游的结构化输出。配置时要注意，引用的字段必须在上游的输出契约里存在，否则运行时会解析失败。我建议每次改完流程配置，先用一个简单输入跑一遍，确认引用链路通不通，再上真实任务。

4.3 并行与串行的取舍

不是所有子任务都适合串行。互不依赖的子任务并行跑，能明显压缩整体耗时。项目支持在流程配置里声明并行组，同一组内的节点会同时调度。但并行不是免费的，它带来两个代价：一是资源占用上升，同时跑的智能体越多，模型调用和工具调用的并发压力越大；二是调试复杂度上升，并行节点的日志会交错，排查问题更费劲。

我的经验是，起步阶段一律串行，把链路跑通、输出契约调稳之后，再挑那些确实互不依赖的节点改成并行。判断标准很简单：如果两个节点的输入都不依赖对方的输出，且它们操作的文件或资源不重叠，就可以并行。资源重叠的节点强行并行，容易出现写冲突，这类问题排查起来非常耗时。

4.4 日志与可观测性配置

协作链路一长，没有好的日志基本没法调。项目默认的日志会记录每次调度的入参出参，但默认级别下信息量偏少。调试阶段建议把日志级别调到 debug，同时开启消息追踪，这样每条消息的完整生命周期都能看到。

LOG_LEVEL=debug TRACE_MESSAGES=true npm run demo -- --task "..."

日志里重点看三个时间点：任务下发时间、智能体开始执行时间、结果回传时间。这三个时间点能帮你判断瓶颈在调度还是在执行。如果下发到开始执行之间间隔很长，说明调度层有排队；如果开始执行到回传间隔很长，说明智能体本身在工具调用或推理上耗时多。这两种情况的优化方向完全不同，前者调并发度，后者调提示词或工具集。

5. 常见问题与排查实录

5.1 协作链路卡死或死循环

这是多智能体协作里最常见也最头疼的问题。表现是任务跑着跑着不动了，或者日志里同一个调度反复出现。根因通常是某个智能体的输出没有满足下游的输入契约，导致下游反复请求上游重发，形成循环。

排查思路是先看消息日志里最后几条消息的类型，如果是"任务下发"和"异常上报"交替出现，基本可以确定是契约不匹配。解决办法有两个方向：一是修上游的输出契约，让它稳定产出下游要的格式；二是给编排层加最大重试次数，超过阈值直接失败并上报，避免无限循环。我倾向于两个都做，契约修好是治本，重试上限是兜底。

5.2 智能体输出格式不稳定

结构化输出契约能大幅提升稳定性，但不能保证百分百稳定。模型在某些边界输入下仍可能输出不符合契约的内容。项目里对这种情况的处理是解析失败后触发一次重试，重试时会把解析错误信息一并带给智能体，让它自我修正。

实测下来，单次重试能解决大部分格式问题，但重试次数不宜超过两次，否则会显著拉长任务耗时。如果某个智能体频繁触发重试，说明它的角色描述或输出契约本身有问题，应该回头改定义，而不是靠重试硬扛。

5.3 上下文超限与信息丢失

多智能体协作虽然做了上下文隔离，但单个智能体处理大任务时仍可能超限。典型表现是智能体在中途开始"忘记"前面的指令，输出质量断崖式下降。排查时看日志里该智能体的输入长度，接近模型上限就要警惕。

应对办法是拆分任务粒度，把一个大子任务再拆成几个更小的。另一个办法是在智能体的输入里做信息裁剪，只传当前步骤真正需要的上下文，而不是把上游全部输出一股脑塞进去。后者需要你在编排配置里精确控制引用字段，前期多花点功夫，后期稳定性收益很大。

5.4 常见问题速查表

注意：速查表里的"解决方向"是通用思路，具体到你的业务场景，可能还需要结合智能体的实际职责做调整，不要照搬。

6. 我踩过的坑与实操心得

6.1 角色描述写太宽泛的代价

刚开始加智能体时，我图省事，角色描述写得很宽，比如"负责处理各类文本任务"。结果这个智能体在协作链路里表现很不稳定，有时候该它出手时它不动，不该它出手时它抢着干。后来把角色描述收窄到"负责将结构化数据转成自然语言摘要，不处理原始文件读取"，行为立刻稳定下来。

这件事让我意识到，角色描述不只是给模型看的提示，它实际上是智能体在协作中的"岗位说明书"。岗位说明书越清晰，智能体越知道自己的边界在哪，越不容易越界或推诿。写角色描述时，我现在的习惯是同时写清楚"做什么"和"不做什么"，后者往往比前者更重要。

6.2 别急着上并行

并行很诱人，谁不想让任务跑得快一点。但我建议起步阶段忍住这个冲动。并行的前提是资源隔离和依赖清晰，这两点在项目初期往往都没调好。我早期强行把一个三节点流程改成并行，结果两个节点同时写同一个索引文件，内容互相覆盖，排查了大半天才发现是写冲突。

正确的顺序是：先串行跑通，把每个节点的输入输出契约调稳，确认节点之间没有隐藏的资源依赖，再挑真正独立的节点并行。判断资源是否重叠，不能只看文件路径，还要看它们是否操作同一类外部资源，比如同一个数据库连接、同一个缓存键。这些隐式依赖比文件冲突更隐蔽。

6.3 日志要当成一等公民

我见过不少人在调试协作任务时，靠加 print 来定位问题，加了一堆又忘了删。这种做法在单智能体场景下勉强能用，在多智能体场景下基本失效，因为日志是交错的，print 出来的东西根本对不上是哪个智能体打的。

项目自带的日志体系已经够用，关键是你要主动去配置它、读它。我的习惯是每次新增或修改智能体，第一件事就是把日志级别调到 debug 跑一遍，确认调度顺序、消息内容、输出格式都符合预期，再调回正常级别。这个习惯帮我省下了大量事后排查的时间。日志里的消息追踪尤其值得看，它把协作过程完整串起来了，比任何事后回忆都可靠。

6.4 契约先行，代码后行

最后一个心得是关于开发顺序的。我现在的做法是，加任何新智能体之前，先把它的输入输出契约写出来，和上下游对一遍，确认字段对得上，再动手写实现。这个顺序看起来慢，实际快很多。因为契约阶段发现的问题，改起来只是改几行配置；等实现写完再发现契约对不上，往往要动编排流程，牵一发动全身。

契约先行还有个隐性好处：它强迫你想清楚这个智能体到底要产出什么。很多时候我们以为想清楚了，一写契约就发现字段定义含糊、边界情况没考虑。这种"写不下去"的感觉，恰恰说明设计还没到位，早点暴露比晚点暴露好。

这套框架我目前用在几个内部工具上，跑得还算稳。后续打算把智能体的注册做成插件式，让新增智能体不用改编排层代码，直接放进去就能被识别。这个改造的关键还是契约，只要契约统一，插件化就是水到渠成的事。