★ FEATURED ARTICLE 1. 从单体智能体到角色化协作这套架构到底在解决什么问题做过智能体项目的人大概都有过这种体验一开始图省事把所有能力塞进一个提示词里让它既能查资料、又能写代码、还能做审核。结果跑起来之后模型经常精神分裂——上一秒还在严谨地做数据校验下一秒就放飞自我开始编造内容。更麻烦的是当你想给某个环节单独加权限控制时发现根本无从下手因为所有逻辑都糊在一起了。这套Sub-Agents 角色分工与 Skills 能力封装方案核心就是解决这个一锅炖的问题。它做的事情可以概括成三句话把一个大而全的智能体拆成若干个职责单一的子智能体Sub-Agent给每个子智能体划定明确的角色与权限边界把可复用的能力抽出来做成独立的技能包Skills最后用一套V1 知识库把整个链路跑通。说白了它想干的事跟一家公司从夫妻店升级成正规团队是一个道理。夫妻店的时候老板一个人进货、收银、做饭、擦桌子忙起来必然出错。正规团队则是采购、收银、后厨、保洁各司其职每个人只对自己那一摊负责出了问题也能精准定位到人。Sub-Agents 就是这套岗位分工制Skills 就是每个岗位手里的标准作业手册而知识库则是全公司共享的资料室。这套东西适合谁来参考我梳理了一下大概三类人最用得上。第一类是正在做多智能体编排的开发者尤其是被提示词越写越长、效果越来越差折磨过的第二类是想给智能体加权限管控的团队比如需要区分只读和可写操作的场景第三类是把智能体当生产力工具、希望沉淀自己知识资产的个人因为 Skills 封装和知识库这套组合本质上就是在帮你把零散经验变成可复用的资产。接下来我会从整体设计思路、角色与权限的拆解、技能包的封装方法、知识库跑通的完整流程以及实操中踩过的坑这几个维度把这套方案掰开揉碎讲清楚。每个部分我都会说明为什么这么设计而不只是怎么配因为只有理解了背后的逻辑你才能把它迁移到自己的场景里。2. 整体架构设计为什么是角色技能知识库这三件套2.1 拆分的底层逻辑单一职责原则在智能体上的落地软件工程里有个老生常谈的原则叫单一职责原则一个函数只做一件事一个类只负责一个功能。这套方案把同样的思路搬到了智能体设计上。一个 Sub-Agent 只承担一个明确的角色比如检索员就只负责从知识库里捞相关内容审核员就只负责判断输出是否合规撰写员就只负责把素材组织成通顺的文字。为什么非要拆因为大模型在单一提示词里同时处理多个目标时注意力会被稀释。你可以把它想象成一个同时接三路电话的客服每路都听一半最后哪路都没服务好。拆成多个 Sub-Agent 之后每个智能体的提示词可以写得非常聚焦上下文窗口里全是跟当前任务强相关的信息输出的稳定性和可控性都会明显提升。还有一个容易被忽略的好处可测试性。单体智能体出问题你很难判断到底是检索环节错了、还是生成环节错了。拆开之后每个 Sub-Agent 都可以单独跑测试用例哪个环节掉链子一目了然。这一点在项目从 Demo 走向生产的过程中价值极大。2.2 角色、权限、技能三者的关系很多人第一次接触这套架构时容易把角色和技能搞混。我用一个类比说清楚角色是岗位权限是这个岗位能进哪些门技能是这个岗位会用的工具。角色决定了这个 Sub-Agent 的人设和职责范围比如它是负责检索的还是负责审核的。权限决定了它能调用哪些资源、能执行哪些操作比如检索员只能读知识库不能写审核员只能读不能改内容。技能则是它完成任务时调用的具体能力模块比如关键词提取相似度计算格式校验这些。这三者是正交的可以自由组合。同一个检索员角色配上不同的技能包就能变成文档检索员或者代码检索员。同一个技能包也可以被不同角色复用。这种解耦设计是整套方案能灵活扩展的关键。2.3 为什么知识库要单独拎出来做 V1知识库这块我特别想强调一下。很多项目会把知识直接硬编码在提示词里或者塞进一个向量库就完事。但这套方案把知识库当成一个独立的、有版本的概念来做标了个V1这背后是有讲究的。知识库独立出来意味着它可以被多个 Sub-Agent 共享检索员查它、审核员也可以查它做事实核对。同时知识库有版本意味着你可以迭代——V1 跑通了后面可以升级到 V2 而不影响已经稳定的角色和技能。这种知识和逻辑分离的思路跟传统软件里配置和代码分离是一个道理改配置不用重新编译代码改知识不用重写智能体逻辑。提示知识库的版本管理不要一上来就搞得很复杂。V1 阶段用最简单的目录文件结构就够了等真正遇到多版本并存的痛点再引入更重的方案也不迟。3. 角色与权限拆解把谁能干什么钉死3.1 角色定义的三个要素定义一个 Sub-Agent 角色我建议至少写清楚三样东西职责描述、输入输出契约、边界条件。职责描述就是一句话说清这个角色干什么比如从知识库中检索与用户问题最相关的片段。输入输出契约是它接收什么格式的数据、产出什么格式的数据这个必须严格定义因为 Sub-Agent 之间是靠数据流转衔接的格式对不上整个链路就断了。边界条件则是明确它不干什么比如检索员不负责判断内容对错只负责召回。我见过不少项目栽在边界条件没写清楚上。检索员觉得我顺手帮你判断一下相关性吧结果把本该召回的内容过滤掉了后面的撰写员拿不到素材整个链路输出质量暴跌。把不干什么写进角色定义比写干什么还重要。3.2 权限分级的实操做法权限这块V1 阶段不用搞得太复杂我推荐用最简单的读写二分法起步。权限级别可执行操作典型角色只读查询知识库、读取上下文检索员、审核员读写在只读基础上可写入中间结果、更新状态撰写员、协调员管理在读写基础上可修改知识库、调整配置调度器、维护角色这个分级的好处是简单直观实现起来也容易——在每个 Sub-Agent 调用工具前做一次权限校验就行。等业务复杂了再往细粒度拆比如把写拆成写临时区和写正式区。注意权限校验一定要放在工具调用层而不是靠提示词里写一句你没有写权限。提示词是软约束模型可能不听话工具层的硬校验才是真正的防线。3.3 角色之间的协作模式Sub-Agent 之间怎么协作常见的有两种模式流水线式和调度式。流水线式就是 A 的输出直接喂给 BB 的输出喂给 C像工厂流水线一样。这种模式简单、可预测适合步骤固定的任务比如检索→撰写→审核这种线性流程。调度式则是有一个协调员角色根据当前情况动态决定下一步叫哪个 Sub-Agent。这种模式灵活能处理分支逻辑但复杂度也高调试起来更费劲。我的建议是 V1 阶段先用流水线式跑通把每个角色的输入输出契约打磨稳定等确实遇到需要动态决策的场景再引入调度式。一上来就搞调度式很容易陷入协调员自己都不知道该干嘛的混乱。4. Skills 能力封装让能力像积木一样可插拔4.1 什么样的能力值得封装成 Skill不是所有能力都值得封装。我的判断标准是会被两个以上角色复用或者逻辑相对独立、有明确输入输出的能力才值得抽成 Skill。举个例子从文本中提取关键词这个能力检索员要用提取查询关键词审核员也可能要用检查内容是否跑题那它就值得封装。而把检索结果拼成提示词这种只在一个角色里用一次的逻辑就没必要单独抽出来直接写在角色里更省事。过度封装和封装不足都是坑。封装不足代码到处重复改一处要改十处过度封装为了抽一个只用一次的能力反而增加了理解和维护成本。V1 阶段我倾向于宁可少封装等复用真的出现了再抽。4.2 Skill 的标准结构一个封装良好的 Skill我建议包含这几个部分名称与描述一句话说清这个 Skill 干什么方便检索和复用输入参数定义每个参数的类型、是否必填、默认值输出格式定义返回什么结构的数据核心实现具体的处理逻辑错误处理输入不合法、执行失败时怎么返回这里特别说一下错误处理。很多 Skill 封装时只顾着正常路径一旦输入异常就直接抛异常导致整个链路崩掉。正确的做法是让 Skill 返回一个结构化的错误信息让调用它的角色能决定是重试、降级还是跳过。这种优雅失败的设计是生产级 Skill 和玩具级 Skill 的分水岭。4.3 技能包的组织与版本管理当 Skill 多起来之后怎么组织就成了问题。我推荐按领域分目录而不是按角色分。因为 Skill 是给多个角色复用的按角色分会导致同一个 Skill 在多个目录里重复。skills/ text/ extract_keywords.py summarize.py retrieval/ vector_search.py rerank.py validation/ format_check.py fact_check.py版本管理上V1 阶段用 Git 就够了每个 Skill 的变更走正常的代码评审流程。等 Skill 被多个项目依赖了再考虑打包成独立的库。实操心得给每个 Skill 写一个最小的测试用例哪怕只有三五行。我踩过的坑是改了一个 Skill 的实现以为只影响一个角色结果另一个角色也在用直接把它跑挂了。有了测试用例改之前跑一遍心里就有底了。5. V1 知识库跑通从零到能用的完整流程5.1 知识库的选型与结构设计V1 阶段知识库不用追求高大上我推荐文件系统 向量检索的组合。原始知识以 Markdown 或纯文本形式存在目录里同时把这些内容做向量化存进向量库检索时走向量相似度。为什么不全用向量库因为纯向量检索有个毛病它擅长语义相似但不擅长精确匹配。比如你要查一个具体的编号、一个特定的术语向量检索可能给你返回一堆意思相近但不对的结果。保留原始文件就能在需要时做精确匹配兜底。目录结构上我建议按主题分层别搞太深knowledge_base/ v1/ product/ overview.md faq.md process/ workflow.md glossary.md5.2 知识入库的完整步骤入库流程我拆成四步每步都有讲究。第一步是清洗。原始知识里往往有大量格式噪音比如多余的换行、乱码、重复段落。不清洗直接入库检索出来的内容质量会很差。清洗的目标是让每段知识都是自包含的也就是单独拿出来也能看懂。第二步是切分。把长文档切成合适大小的片段太长了检索精度低太短了语义不完整。我的经验值是每段 200 到 500 字具体看内容密度。切分时尽量按语义边界切别在句子中间断开。第三步是向量化。用嵌入模型把每个片段转成向量。这里要注意查询和入库必须用同一个嵌入模型否则向量空间对不上检索结果会莫名其妙。第四步是索引。把向量和原始片段的对应关系存好检索时能根据向量找到原文。5.3 检索链路的调优检索跑通之后你会发现结果质量参差不齐。这时候需要调优我常用的手段有三个。一是混合检索把向量检索和关键词检索的结果融合取长补短。二是重排序先召回一批候选再用一个更精细的模型重新排序把最相关的排到前面。三是查询改写用户的问题往往口语化先把它改写成更适合检索的形式再拿去查。V1 阶段我建议先只做向量检索把链路跑通等遇到明显的召回不准问题再逐个引入这些优化。一上来全上调试起来会非常痛苦因为你不知道是哪个环节的问题。6. 常见问题与排查技巧实录6.1 角色之间踢皮球或抢活干这是拆分后最常见的问题。表现是某个环节该做的事没人做或者两个角色重复做同一件事。根因通常是输入输出契约没定义清楚导致职责边界模糊。排查方法很简单把每个角色的输入输出打印出来看数据在哪个环节断了或者在哪两个环节重复了。解决方法是回到角色定义把边界条件写得更死。我一般会在契约里明确写本角色不处理 XX 情况直接透传给下游。6.2 技能包调用失败导致链路中断前面提过Skill 的错误处理很关键。但即便做了错误处理还是可能遇到某个 Skill 挂了整个链路卡住的情况。这时候需要降级策略。比如检索 Skill 挂了可以降级到返回空结果让下游角色知道这次没检索到而不是直接崩掉。撰写角色拿到空结果可以选择基于已有上下文生成或者提示用户稍后重试。这种降级设计能让系统在部分组件故障时仍然可用。6.3 知识库检索答非所问这个问题我遇到太多次了。排查时按这个顺序来先看切分是否合理是不是把不相关的内容切到了一起再看嵌入模型是否匹配查询和入库是不是用了同一个最后看检索参数返回的条数是不是太多或太少。现象可能原因排查方向返回内容完全不相关嵌入模型不一致检查查询与入库模型返回内容相关但太碎切分粒度过细调整切分大小该召回的内容没召回查询改写缺失增加查询改写环节返回一堆相似内容检索条数过多减少 top_k 或加重排序6.4 权限校验被绕过前面强调过权限校验要放在工具调用层。但实操中还是可能被绕过比如某个角色通过间接方式调用了不该调用的工具。排查时要审计所有工具调用路径确保每条路径都经过校验。避坑技巧给每个 Sub-Agent 分配独立的凭证或标识工具层根据标识判断权限。这样即使提示词被注入攻击攻击者也无法伪造身份去调用越权工具。7. 我在这套架构上的一些真实体会跑通这套 Sub-Agents Skills 知识库的组合之后我最大的感受是拆分的价值不在于多而在于清。不是拆得越细越好而是每个角色的职责越清晰越好。我见过拆了十几个 Sub-Agent 结果互相打架的项目也见过只拆三个角色但跑得非常顺的项目。关键在边界不在数量。另一个体会是知识库的质量决定了整个系统的上限。角色和技能再精巧如果知识库里的内容是错的、过时的、混乱的输出质量也好不到哪去。所以我在 V1 阶段会花大量时间在知识清洗上这部分投入的回报是最直接的。最后分享一个小技巧给每个 Sub-Agent 加一个自检环节让它输出前先自己判断一下我这个输出符不符合我的职责范围。这个自检不需要很复杂一两句话的提示词就够但能挡掉不少低级错误。实测下来这个小小的自检环节能让整个链路的稳定性提升一个档次。
阅读完成 · 觉得有帮助？
