企业官网建设流程全解析

1. 从“agent-skills”这个命名说起：它到底指什么

第一次看到“agent-skills”这个词，很多人会下意识地把它当成某个具体框架或者某个开源库的名字。但如果你在工程一线待过一段时间就会发现，它更像是一个能力集合的抽象概念，而不是某一个可以pip install的包。我最初接触这个方向时也走过弯路，花了整整两天去找一个叫这个名字的现成项目，结果一无所获，后来才反应过来——它描述的是一类设计思路：把智能体（agent）需要具备的各项能力，拆解成可独立开发、可组合、可复用的技能模块。

这个思路其实非常朴素。你可以把它类比成手机上的 App：手机本身提供屏幕、处理器、网络这些基础能力，但真正让它有用的是一个个独立的应用。智能体也是一样，底层的大模型提供推理和生成能力，但要让它在真实场景里干活，就得给它装上一个个“技能”——读文件是一个技能，调接口是一个技能，做数据校验又是一个技能。agent-skills要解决的核心问题就是：这些技能怎么定义、怎么组织、怎么让智能体在合适的时机调用正确的技能。

适合读这篇内容的人有三类。第一类是正在做智能体应用开发、但感觉代码越写越乱、技能越加越难维护的工程师；第二类是对智能体架构感兴趣、想搞清楚“技能”这一层到底该怎么设计的技术爱好者；第三类是产品或者项目负责人，需要理解这套东西的边界在哪里，避免提出不切实际的需求。不管你是哪一类，接下来的内容都会从实际工程角度出发，把这件事讲透。

需要提前说明的是，agent-skills目前并没有一个统一的行业标准，不同团队、不同框架对“技能”的定义差异很大。我下面讲的内容，是基于我在多个实际项目中反复验证过的一套做法，属于“常见实践”层面的经验总结，不是某个官方规范。你完全可以按自己的场景做调整。

2. 技能模块的粒度怎么定：太粗和太细都是坑

2.1 粒度失控的两种典型表现

技能拆分最容易出问题的地方就是粒度。我见过两种极端情况，都让项目后期非常痛苦。

一种是粒度过粗。有人把“处理用户请求”直接做成一个技能，里面塞了几百行逻辑，包含意图识别、参数提取、数据库查询、结果格式化。这种技能表面上看起来“一个技能搞定一件事”，实际上完全没法复用——换个场景要用到数据库查询，你得把整个技能复制一遍再改。更麻烦的是调试，一旦输出不对，你根本不知道是意图识别错了还是查询条件拼错了。

另一种是粒度过细。有人把“拼接字符串”“判断是否为空”这种操作也做成独立技能，结果一个简单任务要调用十几个技能，每次调用都有开销，而且技能之间的依赖关系变成一张蜘蛛网，维护成本极高。

2.2 我用的判断标准：单一职责加可独立测试

经过几个项目的迭代，我总结出一个比较实用的判断标准：一个技能应该只负责一个明确的动作，并且能够在不依赖其他技能的情况下被单独测试。

具体来说，当你考虑要不要把某段逻辑抽成技能时，问自己三个问题：

• 这段逻辑能不能用一句话说清楚它做什么？如果一句话说不清，说明它包含多个动作，应该继续拆。
• 给它一组输入，我能不能在不启动整个智能体的情况下验证输出对不对？如果不能，说明它和其他部分耦合太紧。
• 换个场景，这段逻辑还有没有可能被用到？如果完全不可能复用，那它更适合作为主流程里的一段代码，而不是独立技能。

举个例子。在一个文档处理场景里，“从 PDF 中提取文本”是一个合理的技能粒度——动作明确、可独立测试、其他场景也可能用到。但“从 PDF 中提取文本并清洗格式并翻译成中文”就太粗了，应该拆成提取、清洗、翻译三个技能，由主流程决定要不要串联使用。

2.3 一个可参考的技能分层结构

在实际项目里，我通常会把技能分成三层，这个分层不是强制规范，但能帮你理清思路：

基础技能层尽量保持稳定，不要频繁改动；领域技能层是变化最活跃的地方；编排技能层则应该尽量薄，只负责调度和结果组装，不包含具体业务逻辑。这样分层之后，当业务需求变化时，你通常只需要改动领域技能层，基础层和编排层基本不动。

注意：分层不是越多越好。我见过有人分了五层，结果一个简单功能要跨四层调用，排查问题时光是追调用链就花了半小时。三层对我来说是比较舒服的平衡点。

3. 技能注册与发现机制：让智能体知道“自己会什么”

3.1 为什么需要注册机制

技能写好了，接下来要解决的问题是：智能体怎么知道有哪些技能可用？最原始的做法是在代码里硬编码一个列表，每次新增技能就手动加一行。这种做法在技能数量少于十个的时候还能忍，一旦超过二十个，维护成本就直线上升——你很容易忘记注册某个技能，或者注册了但描述写错了，导致智能体该调用的时候不调用。

所以需要一个技能注册与发现机制。它的核心作用是：每个技能自己声明“我是谁、我能做什么、我需要什么参数”，智能体在运行时动态获取这份清单，而不需要提前硬编码。

3.2 技能描述信息的字段设计

注册机制的关键在于技能描述信息的设计。这份描述直接决定了智能体能不能正确选择技能，所以字段要足够清晰。我通常会用这几个字段：

• name：技能的唯一标识，用英文小写加下划线，比如extract_pdf_text。不要用中文或者空格，避免调用时出问题。
• description：一句话说明这个技能做什么，用自然语言写，因为这段描述最终会被拼进提示词里让模型理解。写法上要具体，比如“从 PDF 文件中提取纯文本内容”就比“处理 PDF”好得多。
• parameters：参数列表，每个参数包含名称、类型、是否必填、描述。类型要明确，是字符串、数字还是布尔值，模型需要知道这些才能正确构造调用。
• returns：返回值的结构和含义。这一点很多人会忽略，但如果不说明返回什么，模型拿到结果后不知道怎么用。
• examples：可选的调用示例。对于参数比较复杂的技能，给一两个示例能显著提升模型调用的准确率。

下面是一个技能描述的示例结构，用 JSON 表示：

{ "name": "extract_pdf_text", "description": "从指定的 PDF 文件中提取纯文本内容，支持按页提取", "parameters": [ { "name": "file_path", "type": "string", "required": true, "description": "PDF 文件的路径" }, { "name": "page_range", "type": "string", "required": false, "description": "页码范围，如 '1-5'，不填则提取全部" } ], "returns": { "type": "string", "description": "提取出的文本内容，多页之间用换行分隔" } }

3.3 注册表的实现方式与踩坑记录

注册表的实现方式有几种常见选择。最简单的是用一个全局字典，技能在导入时自动注册进去。这种方式实现快，但有个隐患：如果技能模块没有被导入，它就不会被注册。我踩过一次坑，某个技能放在一个不常用的子目录里，主流程没有导入它，结果智能体一直说“没有这个能力”，排查了半天才发现是导入问题。

后来我改用显式扫描注册的方式：启动时扫描指定目录下的所有技能文件，自动加载并注册。这样做的好处是新增技能只需要放对目录，不需要改任何其他代码。代价是启动时会慢一点，但对于几十个技能的量级来说完全可以接受。

还有一种方式是配置文件注册，把所有技能的信息写在一个 YAML 或 JSON 文件里。这种方式最可控，但维护起来最麻烦，每次改技能都要同步改配置。我一般只在技能数量很少、或者需要严格控制可用技能列表的场景下才用。

提示：不管用哪种注册方式，都建议在启动时打印一份已注册技能的清单。这样一旦发现某个技能没被加载，你能立刻定位问题，而不是等到运行时才发现。

4. 技能调用的参数校验与错误处理：最容易被低估的环节

4.1 模型生成的参数为什么经常不对

技能注册好了，智能体也选对了技能，接下来就是把参数传进去执行。这一步看起来简单，实际上是最容易出问题的地方。因为参数是模型生成的，而模型生成的内容有几个天然的不确定性：

• 类型不对：该传数字的地方传了字符串，比如把page_range传成"1到5"而不是"1-5"。
• 格式不对：日期格式、路径格式、枚举值不符合预期。
• 缺少必填参数：模型可能漏掉某个必填项。
• 多传了不存在的参数：模型可能凭想象加了一个技能描述里没有的参数。

如果不在调用前做校验，这些问题会直接导致技能执行失败，而且错误信息往往很难懂，模型拿到之后也不知道怎么修正。

4.2 三层校验策略

我在实际项目里用的是三层校验，从松到严依次过滤：

第一层是结构校验，检查参数名是否在技能声明的参数列表里，必填参数是否都存在。这一层不检查值的具体内容，只检查“形状”对不对。发现多余参数直接丢弃，发现缺少必填参数则返回明确的错误信息，告诉模型缺了哪个。

第二层是类型校验，检查每个参数的值是否符合声明的类型。比如声明是数字的，尝试转换；转换失败就返回错误。这一层要特别注意字符串和数字的边界，模型经常把数字写成字符串，如果能安全转换就转换，不要直接拒绝。

第三层是业务校验，检查值的范围是否合理。比如页码范围是否在文档总页数之内，文件路径是否存在。这一层需要具体技能自己实现，因为不同技能的业务规则不同。

三层校验的顺序不能颠倒。如果先做业务校验，可能会因为参数类型不对而抛出奇怪的异常；先做结构和类型校验，能把大部分低级错误挡在前面，业务校验只需要处理真正有意义的边界情况。

4.3 错误信息怎么写才能让模型自我修正

错误处理的关键不在于“捕获错误”，而在于“让模型知道怎么改”。我见过很多实现，出错之后只返回一个"执行失败"，模型完全不知道下一步该干什么，只能反复重试同样的调用，浪费时间和资源。

好的错误信息应该包含三个要素：哪里错了、为什么错、应该怎么改。举个例子：

• 差的错误信息：参数错误
• 好的错误信息：参数 page_range 的值 "1到5" 格式不正确，应该使用 "起始页-结束页" 的格式，例如 "1-5"

后者明确告诉了模型问题所在和修正方向，模型下一次调用时大概率能改对。这个细节看起来小，但对整体成功率的影响非常大。我在一个项目里把错误信息从模糊改成具体之后，技能调用的首次成功率从六成多提升到了九成以上。

注意：错误信息里不要暴露内部实现细节，比如堆栈信息、数据库表名等。只告诉模型“输入哪里不对、应该怎么改”就够了，内部细节既没用又可能带来安全隐患。

5. 技能组合与编排：从单步调用到多步任务

5.1 什么时候需要编排

单个技能能解决的问题是有限的。真实场景里的任务往往需要多个技能配合，比如“读取一份合同 PDF，提取关键条款，翻译成英文，保存到指定文件”。这就涉及四个技能：读 PDF、提取条款、翻译、写文件。智能体需要知道先调哪个、再调哪个、上一步的输出怎么传给下一步。

编排的核心挑战在于：模型需要自己规划调用顺序，而不是由人提前写死流程。如果流程是固定的，那直接写代码就行了，不需要智能体。智能体的价值恰恰在于它能根据任务描述和中间结果动态决定下一步做什么。

5.2 让模型自己规划 vs 预定义流程

这两种方式各有适用场景，我在项目里会根据任务的确定性程度来选择。

预定义流程适合步骤固定、顺序明确的场景。比如“每天定时抓取数据、清洗、入库”，这种任务用编排技能把几个技能串起来就行，不需要模型参与规划。好处是稳定、可预测、出错容易定位。

模型自主规划适合步骤不固定、需要根据中间结果做判断的场景。比如“帮我分析这份销售数据里有没有异常”，模型可能需要先看数据结构，再决定用哪个统计技能，发现异常后再决定要不要深入查明细。这种任务没法提前写死流程。

实际项目里我通常会把两者结合：用预定义流程处理主干步骤，在需要判断的分支点让模型做选择。这样既有稳定性，又有灵活性。

5.3 中间结果的传递与上下文管理

多步调用时，中间结果怎么传递是个容易被忽略的问题。最直接的做法是把上一步的输出原样塞进下一步的输入，但这样做有个隐患：如果中间结果很大（比如一整篇文档的文本），全部塞进上下文会迅速消耗 token 预算，而且可能把真正重要的信息淹没。

我的做法是按需传递加摘要压缩。具体来说，每个技能执行完之后，除了保留原始输出，还会生成一份简短摘要。下一步调用时，默认只传摘要，如果某个技能明确需要完整内容，再单独传递。这样能在保证信息不丢失的前提下，把上下文控制在合理范围内。

另外，中间结果最好用一个结构化的容器来管理，而不是散落在各个变量里。我通常用一个字典，以技能名加调用序号作为键，这样排查问题时能清楚地看到每一步的输入输出。

6. 实测中暴露的三个典型问题与应对

6.1 技能选择错误：模型选了不该选的技能

这是最常见的问题。模型面对一个任务，可能选了一个名字听起来相关但实际不合适的技能。比如用户说“把这份文档转成图片”，模型可能选了“提取文档文本”而不是“文档转图片”，因为两个技能描述里都有“文档”这个词。

应对方法有两个。一是优化技能描述，让相似技能之间的差异更明显。比如“提取文档文本”的描述改成“读取文档内容并返回纯文本，不改变格式”，而“文档转图片”的描述写成“将文档每一页渲染为图片文件”。描述里明确写出“不做什么”和“做什么”，能有效减少混淆。

二是在提示词里加入选择规则。比如告诉模型“如果任务涉及格式转换，优先选择名称中包含 convert 或 render 的技能”。这种规则不需要很复杂，但能起到明显的引导作用。

6.2 参数幻觉：模型编造了不存在的参数值

模型有时候会“脑补”参数值。比如技能需要一个文件路径，用户没提供，模型就自己编了一个看起来合理的路径。这种幻觉在参数校验那一层会被挡住，但频繁发生会拖慢整体效率。

我的应对方式是在技能描述里明确标注哪些参数必须由用户提供，哪些可以自动推断。对于必须由用户提供的参数，如果缺失，不要直接报错，而是返回一个明确的追问：“请提供 PDF 文件的路径”。这样模型会把问题转达给用户，而不是自己瞎猜。

6.3 循环调用：同一个技能被反复调用

有时候模型会陷入循环，反复调用同一个技能，每次微调一点参数，但始终得不到满意结果。这种情况通常发生在技能返回的结果不符合模型预期时。

应对方法是在编排层加一个调用次数上限。同一个技能在同一个任务里连续调用超过三次，就强制中断并返回当前结果，同时提示模型“已达到调用上限，请基于现有结果给出答复”。这个机制能有效防止无限循环，也能提醒模型换一种思路。

7. 技能版本管理与灰度发布：上线之后才见真章

7.1 技能变更为什么需要版本管理

技能不是写完就一劳永逸的。业务需求变了，技能逻辑要改；模型升级了，技能描述可能要调整；发现 bug 了，得修。如果直接改线上技能，一旦改出问题，所有依赖这个技能的任务都会受影响。

所以技能需要版本管理。我的做法是给每个技能加一个版本号，注册表里同时保留多个版本。新任务默认用最新版本，但如果有任务明确指定了版本，就用指定版本。这样在技能升级时，可以先让一部分任务试用新版本，确认没问题再全量切换。

7.2 灰度发布的简单实现

灰度发布听起来很复杂，但在技能这个层面可以做得比较简单。我通常用一个比例控制：新版本注册时设置一个流量比例，比如 10%，表示 10% 的调用会路由到新版本，其余走旧版本。观察一段时间，如果新版本的错误率和旧版本持平或者更低，就逐步提高比例直到全量。

这个机制的关键是记录每个版本的调用结果。至少要记录调用次数、成功次数、平均耗时、错误类型分布。没有这些数据，灰度发布就是盲目的。

7.3 回滚策略

不管灰度做得多谨慎，都有可能出问题。所以必须准备好回滚方案。最简单的回滚就是把流量比例直接调回旧版本 100%，新版本暂时下线。这个过程应该是秒级的，不需要重新部署。

为了做到快速回滚，技能注册表最好支持运行时更新，而不是写死在配置文件里。我用的是一个内存注册表加一个管理接口，通过接口可以动态调整版本和流量比例。这样出问题时不需要重启服务，改一下比例就恢复了。

8. 一些零散但实用的经验

技能开发这块，很多东西是踩过坑之后才明白的。下面几条是我觉得比较有价值、但常规文档里不太会写的。

技能描述要用“动词开头”。比如“提取 PDF 文本”比“PDF 文本提取器”好，因为模型在选择技能时，是在匹配“要做什么动作”，动词开头的描述更容易被正确匹配。这个细节我在对比测试里验证过，动词开头的描述让技能选择准确率提升了大概一成。

参数名不要用缩写。fp不如file_path，cnt不如count。模型对完整单词的理解比对缩写的理解准确得多。而且完整单词在错误信息里也更清晰，用户看到file_path 参数缺失比看到fp 参数缺失更容易理解。

技能执行要加超时。有些技能可能因为外部依赖（比如网络请求）卡住，如果不加超时，整个任务就会挂起。我一般给每个技能设置一个默认超时，比如 30 秒，超时后返回明确的错误信息，让模型决定是重试还是换方案。

日志要记录完整的调用链。一个任务可能涉及多个技能调用，如果日志只记录单个技能的输入输出，排查问题时很难还原完整过程。我通常会给每个任务分配一个唯一 ID，所有相关技能的调用日志都带上这个 ID，这样一搜就能看到整个任务的执行轨迹。

技能数量超过五十个之后要考虑分组。当技能很多时，把所有技能描述都塞进提示词会让上下文变得很长，既慢又贵。这时候可以按领域分组，先让模型选择领域，再在领域内选择具体技能。两级选择比一级选择效率高很多。

定期清理不再使用的技能。项目迭代过程中会积累一些废弃技能，它们不仅占用注册表空间，还可能被模型误选。我一般每个季度过一遍技能清单，把最近三个月零调用的技能标记出来，确认无用后下线。

这些经验没有什么高深的理论，都是实际做项目时一点点攒下来的。agent-skills这个方向本身还在快速演进，今天好用的做法明天可能就被更好的方案替代。但底层的那套思路——拆解能力、明确描述、严格校验、可控编排——我觉得在相当长一段时间内都不会过时。把这几件事做扎实，不管底层模型怎么换、框架怎么变，你的技能层都能稳定运转。