企业官网建设流程全解析

做Agent开发有一段日子了，我越来越觉得“工具”这个词被高估了。很多人以为把函数列表丢给大模型，它就会乖乖按需调用，结果实际跑起来全是意外：模型连续三次调用同一个接口、把字符串塞进整数参数、甚至把一个报错信息当成正常结论输出给用户。我一度以为是模型不够聪明，后来才意识到，缺的根本不是模型能力，而是一个能把“工具”包装成“岗位说明书”的中间层。于是就有了 agent-skills 这个项目，一套面向大模型应用开发的技能库设计与实践。

这篇文章会完整回顾我设计和落地 agent-skills 的过程，包括技能注册机制、技能描述怎么写、调用循环怎么容错、多Agent场景下怎么共享与隔离，以及我真实踩过的几个坑。如果你正在做聊天机器人、自动化助手、或者任何依赖大模型工具调用的应用，这篇文章应该能帮你少走不少弯路。

1. 为什么“技能库”比“一堆工具函数”更适合真实Agent项目

1.1 从一次“工具失控”说起

有段时间我在调一个内部用的资料查询助手，给它接入了四个工具：查文档、查目录、发邮件、写会议纪要。头一轮测试就翻车了——用户问“上周的周报存在哪”，助手直接调用了发邮件工具，差点把一封空白邮件发出去。我检查日志，发现模型在决策时把“查文档目录”和“发邮件”两个工具的调用理由完全搞混了。

问题出在哪？我翻了当时的工具定义，发现每个函数都只写了“工具名称 + 一句话描述 + 两个参数”，比如“send_mail：发送邮件，参数：to, content”。这本质上不是在帮模型做决策，而是在为难它。模型根本不知道什么情况下该用这个工具、参数值怎么从对话里抽取、调完以后结果要怎么处理。它只能靠猜。

那之后我意识到：工具函数面向的是代码，而模型真正需要的是“技能”——一个包含触发条件、参数模板、执行逻辑、结果处理和边界约束的完整封装。

1.2 “技能”和“工具”到底有什么区别

很多人觉得这是咬文嚼字，其实区别非常大。工具是一个原子操作，技能是一个完整的行为单元。举个生活化的例子：厨刀是工具，但“把土豆切成均匀薄片”是技能。切片的技能不仅包含厨刀本身，还包括菜板的选择、手指的握法、下刀的力度、切完后的收纳方式。模型调用的不是“刀”，而是“切片”这个行为。

放到大模型应用里也一样，一个技能 = 工具函数 + 参数模板 + 使用场景描述 + 触发/不触发的条件 + 结果后处理逻辑 + 权限约束。把这一整套打包以后，模型拿到的不再是一个孤立的函数签名，而是一个“什么情况能用、怎么用、用完怎么收尾”的完整说明书。

我后来把两者的差异整理成一张表，团队新同学看一遍就懂了：

这个对比基本定义了我做 agent-skills 的方向：它不是一个函数装饰器，而是一个完整的技能生命周期管理框架。

1.3 agent-skills想解决的问题清单

动手之前，我给自己列了一个问题清单，后面所有设计都是围绕这四件事展开的：

• 工具不可复用：上个项目调好的工具描述，下个项目又得重新写一遍，而且经常写得不如上次好。
• 描述质量参差：大家都是凭感觉写description，没有统一规范，模型调用成功率完全看运气。
• 参数校验缺失：模型填什么就执行什么，没有类型检查和必填校验，出错后只能靠超时兜底。
• 结果处理粗糙：API返回的长文本、错误堆栈，一股脑回填给模型，既浪费上下文又容易误导模型。

这些问题单看都不致命，但叠加在一起，Agent应用的天花板就变得非常低。做 agent-skills 的目标，就是把这些杂事变成框架级的默认能力，让开发者只需要关心自己的业务功能。

2. 拆分agent-skills的整体骨架：技能注册、技能执行与技能调度

2.1 四层结构：从技能定义到实际调用的距离

agent-skills 的整体架构被我拆成了四个层次：技能注册表、技能描述层、技能执行层、技能调度层。这个拆分不是拍脑袋定的，而是根据调用链路中“谁需要知道什么”来划分的。

• 注册表层：维护所有可用技能的唯一索引，负责技能的新增、查找、版本管理。
• 描述层：生成面向模型的说明书，也就是喂给大模型的工具列表。
• 执行层：真正调用本地函数、HTTP接口，或执行脚本，负责和外部世界打交道。
• 调度层：解析模型的工具调用请求，校验参数，分配权限，触发执行，并把结果回填给模型。

这四层各司其职以后，一个最直观的变化是：模型看到的“工具列表”和执行逻辑之间彻底解耦了。我可以随时调整某个技能的描述文本，而不需要改任何业务函数；反过来，底层接口升级了，只要保持技能描述不变，模型侧完全无感。

2.2 技能注册：不要用if-else堆技能，用声明式注册

很多初级的Agent项目里，工具调用是靠一个巨大的if-else写在代码里的，每加一个工具就要改一遍主流程。agent-skills 改成了声明式注册，每个技能是一个独立对象，通过装饰器或者配置文件注册进技能库。

我简单写一下注册的核心数据结构：

@register_skill( name="search_project_docs", version="1.2.0", description="在项目文档库中按关键词搜索资料，适用于用户询问方案、规范、历史记录等场景", parameters={ "type": "object", "properties": { "query": {"type": "string", "description": "搜索关键词，建议提取用户原话中的核心名词"}, "max_results": {"type": "integer", "description": "返回条数，默认5", "default": 5} }, "required": ["query"] }, usage_constraints="当用户只是闲聊时不要调用；当用户提及具体文档标题时优先调用", ) def search_project_docs(query: str, max_results: int = 5): # 实际检索逻辑 return search_engine(query, max_results)

为什么用声明式而不是硬编码？因为有三个实际好处。第一，运行时可以遍历技能库，自动生成模型可见的工具描述，不需要手工维护列表。第二，可以做启动时校验，比如检查参数Schema是否合法、技能名是否重复。第三，为后面的热更新和权限管理留了口子，这些在纯if-else方案里几乎不可能实现。

2.3 技能调度：模型负责决策，代码负责安全

模型在对话过程中会输出一个工具调用请求，但请求里带着模型的“自由发挥”，不能直接拿来执行。调度层就是在这时候做安全翻译的。

调度层至少要处理四件事。第一，技能白名单校验，确认模型请求的技能确实存在，且当前Agent有权限调用。第二，参数校验，用JSON Schema约束检查类型和必填项，缺参数就尝试从对话上下文补，补不上就返回错误让模型重新组织语言。第三，执行超时控制，防止某个技能卡住整个响应流程。第四，结果标准化，把执行结果统一包装成一条消息回填给模型，而不是直接把Python对象裸塞回去。

这里有个很容易被忽略的设计：调度层不能替模型做“是否调用”的决定。它只能负责“可不可以调”和“怎么安全地调”。“要不要调”这件事，在单Agent场景下主导权就是模型的，我们应该通过优化技能描述来提升决策准确率，而不是用代码去猜测模型意图。

2.4 技能生命周期的五个阶段

一个技能从进入注册表到真正执行完，我拆成五个阶段：初始化、校验、执行、后处理、清理。

• 初始化：加载技能配置、建立连接池、实例化客户端。
• 校验：参数合法性、权限、调用频率限制。
• 执行：调用核心函数，实时记录耗时和日志。
• 后处理：结果截断、脱敏、格式转换、错误分类。
• 清理：释放连接、记录审计日志、更新统计指标。

每个阶段都设计成可以挂载额外逻辑的，比如后处理阶段默认会做一件事：把超过2000字的执行结果截断到适合回填的长度，同时保留原文摘要。这个设计让技能库在不同项目里复用的时候，不需要改内核，只需要加自己需要的钩子。

3. 写技能描述的前30分钟，决定模型调用成功率的一半

3.1 模型读技能描述的方式，和人读说明书差不多

我见过太多人把技能描述当成“写给后端同事看的注释”，这是最大的认知误区。模型不会先运行你的代码再决定怎么调用，它只能在有限的上下文里，通过description和参数Schema来“脑补”这个技能是什么。这个过程和人看一份陌生产品的使用说明书非常像：说明书写得不清楚，用户就不会用；写得过于复杂，用户就更倾向于不用。

所以我把技能描述的目标定义成一句话：让模型在读到描述后的三秒内，明确知道三个问题——这个技能是干什么的？什么情况下该用？参数值应该从哪来？

3.2 一个“让人顺手的技能描述”长什么样

下面是一份我后来梳理出来的技能描述模板，所有新技能都会先填这个结构：

{ "name": "query_employee_contact", "description": "查询公司员工的邮箱和电话。当用户询问'某人的联系方式'、'怎么联系某人'、'发邮件给谁'时使用此技能。只能查询在职员工信息，离职员工返回'信息不可用'。", "parameters": { "type": "object", "properties": { "employee_name": { "type": "string", "description": "员工姓名或花名。优先从用户原话中直接抽取，不要拼接额外文字" } }, "required": ["employee_name"] }, "examples": [ {"input": "帮我找一下张三的邮箱", "params": {"employee_name": "张三"}}, {"input": "我想联系产品部的李四，有他电话吗", "params": {"employee_name": "李四"}} ], "negative_constraints": "当用户只提到部门名称而没有具体人名时，不要调用此技能" }

我重点说下 description 的写法。它分成了三段：第一段说明技能本身的功能，第二段写常见的用户问法，第三段交代边界和特殊情况。这样做的好处是，模型在意图识别阶段就能通过问法匹配快速联想到这个技能，而不是靠模糊的语义相似度去猜。

3.3 参数Schema设计的两个关键细节

参数Schema是模型填参的唯一依据，写得好不好直接决定执行层拿到的数据质量。我有两个经验特别想分享。

第一，必填参数要克制。很多开发者习惯把所有参数都设为必填，觉得“反正模型会抽”。但实测下来，必填参数越多，模型瞎编的概率越大。正确的做法是：把真正业务上不能缺的字段设为必填，其余全部设默认值或者允许缺省。比如搜索技能，query是必填，分页大小就不是。

第二，参数描述里要指明值的来源。这是最容易被忽略的。“用户原话中的核心名词”“对话历史里提到的日期”“上次回复中出现的订单号”，这类来源说明能大幅减少模型编造参数的概率。我见过一个糟糕的案例：某技能有个“report_type”参数，描述只写了“报表类型”，模型每次都在瞎猜，后来我把描述改成“从用户问题中提取，用户说日报就填daily，周报就填weekly”，准确率立刻上来了。

3.4 给模型喂“负面约束”：什么情况下不要调用

只告诉模型“什么时候该用”还不够，还必须告诉它“什么时候别用”。这就是我字段里加 negative_constraints 的原因。模型在犹豫时，负面约束是最强的决策信号。

举两个实际例子。一个天气查询技能，我会在约束里写：“不要根据用户提到的日期推测天气，你只能调用实时数据接口，历史天气无法返回。”另一个是文档翻译技能，约束里写：“当用户只是想改写措辞而不是翻译语言时，不要调用此技能。”这些规则看起来很小，但能挡住大量边界误调用。

我把技能描述里的字段整理成一张表，方便大家对照检查：

4. 调用链路实战：从用户提问到技能结果回填的完整流程

4.1 一轮调用的标准时序

把理论说完，我们来走一遍真实调用链路。用户问了一个问题，背后到底发生了什么？我用一个七步时序来描述：

1. 用户提问进入对话系统，系统把历史消息和当前问题拼接成模型请求。
2. 模型根据技能描述层生成的工具清单，决定是否需要调用技能；如果需要，返回一个结构化的工具调用请求。
3. 调度层收到请求后，先做技能存在性校验和白名单检查。
4. 参数校验通过后，执行层真正运行技能逻辑，调用底层接口。
5. 后处理阶段对执行结果做截断、脱敏、错误分类等操作。
6. 系统把执行结果作为一条“工具消息”回填给模型。
7. 模型结合工具结果组织最终答案，返回给用户。

很多人会问：第一步模型返回工具调用之后，能不能直接把结果丢给用户，还要不要回填给模型？我的答案是必须回填。因为工具返回的数据往往是结构化的、冷冰冰的，比如JSON或者原始文本，用户真正需要的是自然流畅的答案。回填这步让模型有机会解释、归纳、缝合上下文，而不是把一段日志直接贴给用户。

4.2 核心代码：一次安全的技能调用循环

我贴一段简化过的调度循环代码，它基本反映了 agent-skills 里核心循环的骨架：

def run_agent_with_skills(user_input: str, skill_registry, max_iterations: int = 5): messages = [{"role": "user", "content": user_input}] tool_descriptions = skill_registry.build_model_view() for step in range(max_iterations): response = llm.chat(messages=messages, tools=tool_descriptions) message = response.message if not message.tool_calls: return message.content messages.append(message.to_dict()) for tool_call in message.tool_calls: skill = skill_registry.get(tool_call.function.name) if skill is None or not skill.allowed_in_current_scope(): tool_result = { "error": "当前技能不可用，请向用户说明无法完成请求" } else: try: args = validate_parameters(tool_call.function.arguments, skill.schema) raw_result = skill.execute(**args) tool_result = skill.postprocess(raw_result) except ValidationError as e: tool_result = {"error": f"参数不完整：{e}", "hint": "请根据用户原始请求重新提供参数"} except TimeoutError: tool_result = {"error": "技能执行超时，请告知用户稍后重试"} messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(tool_result, ensure_ascii=False) }) return "抱歉，我尝试了多次仍然没有完成您的请求。"

这段代码里的 try-except 结构不是防御性写法的炫技，它对应的是真实世界里最常见的三类失败：参数问题、执行问题、业务不可用问题。每一类失败的错误提示都经过设计，目的是让模型知道自己错在哪，并且有能力修正后继续尝试，而不是破罐子破摔直接向用户道歉。

4.3 结果截断与上下文清洗

执行结果回填给模型之前，必须过一次“清洗流水线”。我见过一个真实事故：某个技能把一份50页的PDF解析文本原样返回，模型在下一轮直接内存溢出。所以在后处理里，默认做了长度硬控——超过2000字符就保留前500字符加上一个AI生成的摘要，同时附上“完整结果已超出上下文窗口”的提示。

清洗还不只是截断。比如技能内部调用了第三方接口，返回的原始JSON里可能包含服务商请求ID、内部错误堆栈，这些不能让模型看到，因为模型可能会把错误信息当成事实告诉用户。清洗阶段会把这些字段替换成“内部错误，详情请查看日志”。用户看到的永远是安全、可解释的信息，而不是技术债。

5. 踩坑实录：参数校验、技能冲突和上下文污染的排查过程

5.1 最坑的问题一：模型在多个相似技能之间反复横跳

某个版本里我加了两个技能，一个叫“查询项目进度”，一个叫“查询项目风险”。结果测试时发现，模型对“项目最近怎么样”这类问题反复横跳，一会儿调进度，一会儿调风险，甚至同一次会话里两个技能各调一遍，浪费了大量token和时间。

排查过程是这样的：我先把两个技能的完整描述打印出来对比，发现问题出在它们的description都写了“当用户询问项目状态时使用”，而“状态”这个词被两个技能同时抢。根因是技能边界重叠。修复方案不是靠模型，而是重写两个技能的描述，明确分工：进度技能绑定“时间、里程碑、完成百分比”等词，风险技能绑定“阻塞、问题、隐患、可能延期”等词。同时在每个描述最后加一句“如果用户同时提到风险和进度，优先调用风险技能，并在结果中说明。”

这个坑让我明白一个道理：技能库里的技能越多，描述之间的“冲突检测”就越重要。后来我加了一个启动检查脚本，自动扫描所有技能描述里的高频触发词，如果两个技能共享了三个以上的触发词，就在日志里提醒开发者检查边界。

5.2 最坑的问题二：参数解析永远差一个类型

有一阵子用户反馈，搜索技能的翻页老是失效。我去查日志，发现模型传来的参数值是字符串，比如“page_2”，而底层接口要求整数，模型是把Python语法幻觉出来了。更麻烦的是，这个问题不是偶发的，几乎每次都会出现。

排查之后我确认了根因：参数Schema里“type”字段写得不够严格，示例里又用了字符串，模型就学坏了。修复分两层：第一层，在Schema里把类型标注清晰，并给出正确示例；第二层，在调度层做一次宽容解析，如果检测到字符串里全是数字，自动转成整数，如果检测到布尔值写成了“是/否”，也自动映射。这个宽容解析不是为了放任，而是为了兜底。

我把这个策略叫作“先纠正，再报错”。只有纠正不了的时候才把ValidationError回传给模型。实测这个组合策略让参数解析失败率从大概12%降到了2%以下。

5.3 最坑的问题三：错误信息被当成“工具结论”回填

这是我最深刻的一次教训。某个技能底层依赖的存储服务偶发超时，返回的错误文本里带了一行“connection refused”。结果模型拿到这行文本后，直接对用户说：“你的连接被拒绝，请检查你的网络权限。”用户一脸懵，明明是公司内部服务，怎么变成用户问题了。

问题出在后处理阶段缺乏错误分类。我当时的处理是把原始错误原封不动回填给模型，模型没有能力判断这是服务端问题还是客户端问题。修复方案是建立一套错误分级框架：

这套分级表后来成了技能库后处理阶段的标准配置。它的核心思想是：用户能感知的错误信息，和内部调试日志必须分离。模型回填的是面向用户的解释，而不是技术堆栈。

5.4 复盘：这些问题暴露了技能库缺少的四个机制

踩完这些坑，我给 agent-skills 补上了四个机制，现在回头看都是必需品。

• 技能冲突检测：启动时扫描描述重叠，提前发现边界模糊。
• 参数宽容解析：先纠正类型，再返回校验错误。
• 错误三级分类：参数错误、业务错误、基础设施错误，各自有独立的回填模板。
• 执行审计日志：每次调用都完整记录输入、输出、耗时、错误分类，用于后续优化。

有了这四个机制以后，技能库的稳定性才真正达到“可以对外提供服务”的程度。

6. 从单Agent到多Agent：技能共享、热更新与权限隔离

6.1 技能共享：注册中心比“复制代码”优雅

当项目从单个Agent扩展到多个Agent时，第一种直觉是把技能代码复制到各个Agent工程里，但很快就会被维护成本淹没。一个技能改了逻辑，所有地方都要同步，漏掉任何一个都是隐患。

agent-skills 的做法是让技能库变成一个独立服务，提供注册和查询接口，各Agent通过订阅的方式获取技能列表。这样“技能定义”和“Agent使用”之间变成了一对多的关系。比如查询联系人技能被三个Agent订阅，我只需要在技能库里升级一次，所有Agent下一个请求就会自动使用新版本。

当然，共享不等于无条件同步。每个Agent可以订阅不同版本，比如内部工具Agent订阅2.0版本，对外演示Agent锁定1.8版本。这就像移动应用依赖库的版本锁定，避免一个升级导致所有下游一起出问题。

6.2 热更新的实现思路：不重启服务也能换技能

技能库作为服务以后，热更新就变得很有价值。业务方经常会提出“能不能临时加一个技能跑一次活动”的需求，如果每次都要重新发版，响应太慢。

我实现的思路是：注册表不直接持有技能对象，而是持有技能对象的“工厂函数”。每次请求到达时，调度层从工厂获取当前版本实例。这样发布新技能或者修复旧技能时，只需要更新注册中心里的工厂映射，不需要重启任何Agent进程。

热更新真正难的不是技术，而是版本一致性。我见过因为版本不同步导致的脏数据问题，比如两个Agent一个用了新参数格式，一个用了旧格式，结果下游接口格式错乱了。所以我坚持给每个技能打上版本号，并在执行结果里附带版本信息，这样排查问题时一眼就能看出是哪个版本产出的数据。

6.3 权限隔离：同一个技能，不同Agent不同权限

技能共享之后，权限就成了绕不开的话题。不是所有Agent都应该能调用所有技能，也不是一个技能对所有人暴露同样的参数。我参考了最小权限原则，给技能加了一个scope字段，每个技能定义自己允许的调用范围。

{ "name": "send_scheduled_message", "scope": ["ops_agent", "admin_agent"], "denied_scope": ["public_chatbot"], "parameter_policies": { "recipient": "must_be_internal" } }

调度层在执行前会检查当前Agent的标识是否在允许范围内。比如前台展示用的聊天机器人，它可以查询商品库，但绝不能调用“发送私信”技能。这种隔离不是靠开发者自觉，而是靠注册中心的强制校验。

权限隔离还有一个容易被忽视的维度：参数级脱敏。同一个“查询客户信息”技能，客服Agent可以看到手机号，而分析Agent的手机号字段会被自动替换成“已隐藏”。我在后处理阶段实现了这个能力，根据技能调用上下文决定哪些字段需要脱敏，实测对数据安全很有帮助。

6.4 让技能库成为一个可迭代的产品

技能库搭建完成只是开始，真正的价值在于持续的迭代优化。我会定期看技能调用日志，重点关注三个指标：调用成功率、平均响应耗时、模型误调用次数。任何一个指标异常，都是技能描述或者执行逻辑需要优化的信号。

比如我发现某个技能的成功率在某个时间段突然下滑，点进日志发现是底层接口在那个时段限流了，于是给这个技能加了缓存策略。又比如某个技能频繁被模型误调用，我会重新审视它的描述是不是和别的技能重叠了。这些优化都不是一次性的，而是随着技能库的使用不断发生。

所以我的最后一条经验是：把技能库当成产品来做，而不是当成工具来做。它有用户（Agent）、有需求（业务方）、有指标（成功率/耗时）、有迭代（版本发布）。只有站在这个角度，技能库才能从一个“能跑的代码库”变成一个真正提升AI应用质量的基座设施。

我在实际使用中最深的一个体会是，技能库的设计缺陷往往要在真实流量下才会暴露，因此与其追求一开始的完美架构，不如早点把注册、调度、校验、审计这套骨架跑起来，然后在踩坑中完善细节。agent-skills 这个项目让我印象最深的不是某个技术亮点，而是它把“给模型用好工具”这件抽象的事，变成了可设计、可测试、可度量的工程实践。如果看完这篇你也准备动手，我建议先挑一个你手上最常用的工具函数，按文中的技能描述模板重写一遍，观察模型调用的变化，你大概率会发现，问题真的不完全出在模型身上。