企业官网建设流程全解析

做Agent开发久了，你会发现一个很微妙的事实：真正让Agent"有用"的关键，往往不是模型本身多聪明，而是它能调用多少稳定、可靠、可复用的"技能"。我去年经手过好几个项目，团队从零开始搭Agent，前两周还在兴奋地聊规划和记忆，第三周开始就全员陷入"能力怎么写才不重复造轮子"的泥潭。不同Agent要用的能力高度重叠——网页抓取、文档解析、代码执行、API调用、内容总结——但代码散落在各个业务模块里，改一处要牵连三四个文件。后来我们把整层能力抽出来，单独做了一套agent-skills体系，所有Agent的能力都从这层动态加载，整体维护成本降了一个量级。这篇就是把当时的设计思路、踩过的坑、以及目前跑得很稳的实践方案整理出来，给同样在做Agent能力层建设的团队一个参考。

1. 为什么需要一套独立的Skills层：从几段痛苦的Agent开发经历说起

1.1 第一次做Agent时，我把能力写死在代码里

最早我做的Agent很简单：一个对话机器人，需要联网查资料。我当时直接在Agent的execute()方法里写了请求外部搜索API的逻辑，然后让模型在回复时调用。功能跑通了，但问题马上来了：第二个Agent要查数据库，第三个Agent要操作本地文件，于是每个Agent都各自复制了一份"调用外部资源"的代码，只是改了下URL和参数格式。

这还不算最要命的。最要命的是，同样的能力在两个Agent里的行为不一致。搜索这个动作，Agent A做了超时重试，Agent B没有；Agent A限制了返回条数，Agent B没有。模型的Prompt里对工具的描述也是各写各的，有的写"搜索网络获取信息"，有的写"查询互联网内容"，模型经常因为描述含糊而误选工具。

到这一步，问题已经不是"代码重复"这么简单了，而是Agent的行为不可预期。我去追根因，发现本质是我们把"能力"和"业务"混在了一起。能力是通用的，业务是具体的，两者应该分层。工具函数能被多少Agent复用、怎么被复用，取决于能力层设计得好不好。所以后面我重构时做的第一件事，就是把所有通用能力抽出来，单独成一个Skills层。

1.2 Skills层要解决的三个核心问题

重做Skills层之前，我给自己列了三个必须解决的问题，后来发现这也是所有Agent系统绕不开的三个问题：

第一，能力的标准化描述。模型需要通过自然语言理解"这个技能是干什么的"，然后决定是否调用。所以每个Skill必须有一份标准化的描述信息，包括名称、功能说明、输入参数、输出格式。这份描述最终会拼进Prompt里，描述质量直接决定模型调用的准确率。

第二，能力的动态加载。我不希望把几十个Skill全部塞进每个Agent的Prompt里，那会冲散模型的注意力，还会浪费上下文窗口。更合理的做法是，Agent启动时按需加载一部分Skill，运行中根据任务动态补加载其他Skill。这就要求Skill层具备"注册-发现-加载"的完整机制。

第三，能力的运行隔离。Skill不应该和Agent的主流程强耦合，也不应该和某个具体的业务数据结构强绑定。每个Skill应该是一个独立的执行单元，有自己的输入校验、错误处理、返回协议。这样即使某个Skill内部崩溃，也不会拖垮整个Agent。

这三个问题想清楚，Skills层的边界就划定了。剩下的都是实现细节。

2. Skill的定义模型与目录结构：先想清楚"一个技能到底是什么"

2.1 元信息、输入输出约定与资源依赖

我花了不少时间定义Skill的"标准长相"。一个Skill本质上是一个可复用的能力封装，它包含四部分：元信息、执行逻辑、输入输出约定、资源依赖。

元信息是给模型和调度器看的，包含name（技能名）、description（做什么用）、parameters（参数Schema）、returns（返回结构）。其中description是给LLM看的，要写得具体、能区分边界，比如"搜索互联网获取实时信息并返回结果列表"就比"搜索"好得多。parameters我直接沿用JSON Schema格式，这样既能校验输入，也能把Schema转成模型需要的工具参数格式。

执行逻辑是Skill真正干活的代码。我最初用Python写，后来为了跨语言调用，把每个Skill封装成独立的可执行模块，通过标准输入输出或HTTP接口对外暴露。这个决定在后期帮了大忙，因为团队里有人用TypeScript写Agent，有人用Python，统一走接口协议谁都能调。

输入输出约定是Skill的"契约"。每个Skill必须声明自己接收什么、返回什么。我踩过的教训是：输出格式一定要稳定，最好是一个固定的JSON结构，包含status（成功/失败）、data（业务数据）、error（错误信息）三块。因为Agent拿到Skill的结果后还要交给LLM做进一步推理，如果每次返回的结构都不一样，LLM的理解成本会急剧上升，推理错误率也会肉眼可见地增加。

资源依赖是指Skill运行需要的外部条件，比如API Key、数据库连接、文件系统权限。这部分必须显式声明，不能藏在代码里。我是通过一个manifest.json统一声明的，Skill在注册时就会检查依赖是否满足，不满足就直接标记为不可用，而不是等运行时报错才发现问题。

2.2 目录规范与命名约定

Skills层的目录结构我采用了"一个技能一个文件夹"的约定：

skills/ web_search/ manifest.json skill.py requirements.txt web_extract/ manifest.json skill.py requirements.txt code_exec/ manifest.json skill.py requirements.txt

每个文件夹就是一个独立Skill，manifest.json描述元信息和依赖，skill.py是执行入口，requirements.txt列出依赖包。这个结构的优点有两个：一是每个Skill可以独立开发、独立测试，甚至独立发布；二是扫描器可以很方便地遍历目录完成注册。

命名上我也定了规矩：Skill名统一用动词_对象或者领域_动作的格式，比如web_search、doc_summarize、api_call。不要用tool1、func2这种没语义的名字，因为Skill名会出现在模型可调用的工具列表里，名字起得含糊，模型就容易选错。

3. 核心机制：技能如何被发现、注册与加载

3.1 扫描、加载与注册流程

Skills层最核心的机制是"注册中心"。我把注册中心实现成一个轻量的服务，启动时扫描Skills目录，逐个读取manifest.json，校验依赖，然后注册到内存中的一张技能表里。注册完成后，Agent可以通过注册中心查询当前可用的Skill列表，也可以单独查询某个Skill的详细信息。

class SkillRegistry: def __init__(self, skills_dir: str): self._skills_dir = skills_dir self._skills = {} self._scan_and_register() def _scan_and_register(self): for entry in os.listdir(self._skills_dir): skill_path = os.path.join(self._skills_dir, entry) manifest_path = os.path.join(skill_path, "manifest.json") if not os.path.isfile(manifest_path): continue manifest = self._load_manifest(manifest_path) if self._check_dependencies(manifest): self._skills[manifest["name"]] = { "manifest": manifest, "path": skill_path, "status": "ready", } else: self._skills[manifest["name"]] = { "manifest": manifest, "path": skill_path, "status": "dependency_missing", } def list_skills(self) -> list: return [ {"name": name, "description": info["manifest"]["description"]} for name, info in self._skills.items() if info["status"] == "ready" ] def get_skill(self, name: str) -> dict: info = self._skills.get(name) if not info or info["status"] != "ready": raise SkillUnavailableError(f"Skill {name} is not ready") return info

这个流程看起来简单，但有一个细节值得强调：注册时只加载元信息，不加载执行代码。也就是说，Skill的执行模块是懒加载的，只有真正被调用时才导入。原因很简单，有些Skill依赖的第三方库很重（比如数据处理类的库），启动时全部导入会让Agent的冷启动时间翻几倍。懒加载能让注册中心轻量，也能让Agent启动更快。

3.2 运行时动态绑定：LLM怎么知道该调用哪个Skill

注册中心只是地基，真正的关键是运行时怎么让LLM选对Skill并且调用它。

我在实践中采用的是"两级候选"策略。第一级，根据Agent当前任务的关键词做粗筛，比如任务里出现"查一下""找资料"，就把搜索、抽取类Skill提到候选列表前面。第二级，把候选Skill的描述和参数Schema拼进Prompt，让LLM基于语义选择最匹配的一个。粗筛是为了缩短候选列表、减少LLM的决策负担，细选则是发挥LLM对自然语言的理解优势。

调用流程上，我用了一个统一的中介层SkillRunner。LLM按约定的JSON格式返回"要调用哪个Skill、传什么参数"，SkillRunner负责解析、路由、执行、返回结果。这里有个很实用的技巧：执行结果返回给LLM时，我会同时附上Skill自带的result_summary字段，让LLM不用重新读一遍原始数据就能理解结果。举个例子，web_search返回的不只是一串链接，还会自动生成一段"共找到X条结果，前3条标题分别为…"的摘要。这个摘要直接给LLM，原始链接给用户或后续流程。实测下来，这种"摘要先行"的方式能把LLM的后续推理质量提升不少，因为它减少了长上下文中的信息噪音。

4. 从零实现一个可复用的Skill：我踩过的细节坑

4.1 写一个"网页内容提取并总结"的Skill全过程

空谈设计太虚，我拿一个真实的Skill举例：web_extract，功能是抓取指定网页并生成内容摘要。

第一步，写manifest.json：

{ "name": "web_extract", "description": "抓取指定URL的网页正文，提取主要文本内容并生成摘要。适用于查看文章、新闻、博客等内容型页面。", "version": "1.0.0", "parameters": { "type": "object", "properties": { "url": { "type": "string", "description": "需要抓取的网页URL" }, "max_chars": { "type": "integer", "description": "最多返回的文本长度，默认8000", "default": 8000 }, "summarize": { "type": "boolean", "description": "是否生成摘要，默认true", "default": true } }, "required": ["url"] }, "returns": { "type": "object", "properties": { "status": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "summary": { "type": "string" } } }, "dependencies": { "python": "3.9+", "packages": ["requests", "beautifulsoup4"], "env_keys": [] } }

description这里有个容易忽略的点：不要只写"抓取网页"，而要写清楚"什么场景适合用、什么场景不适合"。我在这个字段里加了"适用于查看文章、新闻、博客等内容型页面"，就是想让模型明白，如果用户问的是"某个页面里的登录框怎么填"，这个Skill并不合适。

第二步，写执行代码。核心逻辑很简单：发请求、解析正文、清洗HTML标签、截断长度、可选生成摘要。但我在这里踩了一个很典型的坑：最初我直接用requests.get(url)去抓，结果很多网站返回的是反爬页面，正文提取出来全是验证码提示。后来我改成自定义UA头、加超时和重试、用beautifulsoup4去定位article标签或main标签，提取成功率才从六成提到九成以上。

第三步，本地测试。我给每个Skill配了一个简单的自测入口，直接用命令行传参运行，验证特定URL的抓取效果。这一步看似朴素，但对排查问题特别有用——不用启动整个Agent就能单独调试一个能力。

4.2 参数校验与错误处理，比功能本身更影响体验

做Skills层时，有一句话我一直挂在嘴边：不要相信LLM传进来的参数。LLM生成参数时经常会出现漏传、传错类型、传了不存在的枚举值的情况。所以每个Skill执行前必须做严格的参数校验，校验不过就返回结构化的错误信息，让上层决定是纠正参数后重试还是告知用户。

def validate_and_run(skill_func, params_schema, raw_params): validator = jsonschema.Draft7Validator(params_schema) errors = list(validator.iter_errors(raw_params)) if errors: return { "status": "error", "error": { "type": "invalid_params", "message": str(errors[0].message) } } return skill_func(**raw_params)

错误处理也一样，每个Skill的输出都必须遵守"失败也是结构化"的原则。我见过很多Agent翻车就是因为工具异常时返回了一段长长的traceback，把LLM直接绕晕了。正确的做法是，抛异常时统一捕获，转成{"status": "error", "error": {"type": "timeout"}}这种简洁结构。LLM看到timeout就知道该提示用户稍后重试，而不是对着一屏报错发呆。

5. Skill间的组合与隔离：不是所有能力都应该揉在一起

5.1 技能组合的三种模式：链式、并行、路由

单独的一个Skill能解决单点问题，但一个复杂的Agent任务往往需要多个Skill协作。我在实践中总结出三种组合模式，分别应对不同场景：

链式组合是最常见的。比如"总结这篇新闻并发送到邮箱"这个任务，需要web_extract先抓取内容，再由doc_summarize生成摘要，最后由email_send发送。前一个Skill的输出是后一个Skill的输入，必须保证输出结构完全可对接。这也就是为什么我强调输出协议要固定，链式组合中对协议的一致性要求远高于单个Skill。

并行组合用于几个互不依赖的子任务。比如用户问"对比A公司和B公司的市值"，可以同时调用两个搜索Skill，分别查A和B，最后合起来给LLM做比较分析。并行能显著缩短整体耗时，但要注意控制并发数量，我在SkillRunner里设置了最大并发数5，防止大量Skill同时执行拖垮资源。

路由组合是根据任务类型动态选择不同的Skill分支。比如Agent检测到用户发来一段代码，就路由到code_exec；检测到用户发来一个文件路径，就路由到file_read。路由的判断我倾向于让LLM来做，但会给它一个固定的决策规则提示，而不是让它自由发挥。

这三种模式不是互斥的，实际任务经常是它们的混合体。关键是在设计Skill接口时就要考虑"被组合"的可能性，每个Skill的输入输出都要做到能被其他Skill安全地消费。

5.2 安全边界与权限控制

Skill越丰富，权限边界越重要。我在Skills层里给每个Skill配置了执行级别：

• safe：只读操作，不接触用户隐私，不产生副作用。比如web_search。
• medium：会写数据或调用外部API，但影响范围有限。比如file_write。
• high：执行代码、操作系统操作、访问敏感信息。比如code_exec。

Agent默认只启用safe级别的Skill，medium和high需要用户在会话中显式授权，或者由Agent的行为策略触发授权请求。这个设计能挡住大部分"Agent被诱导执行危险操作"的问题。

另外还有一个常被忽略的点：Skill访问外部服务时，不应该直接使用Agent进程的全局凭证。每个Skill应该从自己的配置中读取专属凭证，并且这个凭证的权限范围要尽量小。比如web_extract只需要一个读权限的API Key，不给写权限。我意识到这一点，是在一次排查"Agent为什么删掉了用户云存储里的文件"之后。根因就是某个Skill复用了全局密钥，而该密钥拥有过高的权限。从那以后，凭证最小化成了硬性规范。

6. 测试、调试与效果评估：上线前必须做的事

6.1 离线测试集怎么建

Agent的Skill不太适合用传统的单元测试思路去覆盖，因为LLM的行为有随机性，同样的输入可能产生不同的调用。但Skill本身是确定性代码，是可以严格测试的。我把测试分成两层：

第一层是Skill逻辑层的单元测试。每个Skill都有固定的输入输出，我针对正常输入、边界参数（如空字符串、超长文本、非法URL）、外部服务异常（超时、返回500、被反爬）分别写测试用例，确保Skill的执行逻辑稳定。

第二层是Agent集成层的回归测试。我会准备一组典型任务，比如"查询明天的天气""总结这篇文档""计算某段代码的运行结果"，然后把任务跑一遍，记录Agent是否选择了正确的Skill、参数是否合理、最终答案是否让人满意。这一层我允许一定比例的波动，但核心任务是必须稳定通过的。我自己的经验是，核心任务集别贪多，20到30条能覆盖大多数业务场景就够了，跑一次大概三五分钟，每次改完代码都跑一遍，能拦住大部分回归问题。

6.2 线上日志与追溯

调试Agent的Skill调用链，比调试传统代码麻烦得多，因为你面对的不只是代码栈，还有一次LLM的决策过程。为了能事后追溯，我给每个Skill调用设计了结构化的日志格式：

{ "request_id": "abc123", "agent_id": "assistant_01", "skill": "web_search", "params": {"query": "2024年新能源汽车销量"}, "result_status": "success", "result_summary": "共找到12条结果，前3条来自…", "latency_ms": 842, "model": "gpt-4o", "timestamp": "2024-05-20T10:00:00Z" }

每条日志都关联了request_id，这样当Agent最终回复出错时，我可以沿着request_id把整条调用链拉出来看：模型在哪一步选了错Skill、参数是怎么生成的、Skill返回了什么、LLM基于这个结果做了什么判断。这套追溯体系帮我解决了很多"看起来莫名其妙"的问题。比如说，有一次Agent在总结文档时反复输出空内容，排查到最后发现是doc_summarize在输入超过2万字符时静默截断了文本，导致LLM拿到的内容不完整。这种问题不靠日志追溯，几乎不可能定位。

7. 我的一些幕后心得：哪些设计当初觉得对、后来发现要改

做Skills层这段时间，有几个设计决策是我回看时觉得特别想分享的，因为它们在事后被证明至关重要。

第一个是关于"描述即文档"的认知。Skill的description是给LLM看的接口文档，它的重要性远高于给程序员看的注释。我后来专门安排人逐条打磨每个Skill的描述，把模糊的"处理数据"改成精确的"从上传的CSV文件中提取指定列并计算统计指标"。描述改完之后，模型选错Skill的概率肉眼可见地下降了。如果你的Agent经常选错工具，优先检查的不是模型，而是工具描述的质量。

第二个是"不要追求Skill数量多，要追求场景覆盖准"。我见过一些团队把Skill堆到上百个，但真正被频繁调用的可能只有十几个。Skill数量太多还会拖慢扫描注册时间，并且让LLM在决策时更难选择。我现在倾向于控制核心Skill在二三十个以内，并且定期用调用日志分析哪些Skill是僵尸Skill，该删就删。

第三个是关于"失败反馈要带下一步建议"。Skill返回给LLM的错误信息里，最好包含"这个错误大概是什么原因、建议怎么做"。比如web_search超时了，错误信息里建议"可以尝试缩小搜索范围或稍后重试"。这个细节让LLM在面对失败时不再反复尝试同一个错误操作，而是能给出合理的用户提示或备选方案。

第四个是关于"版本与灰度"。Skill不是写一次就永远不变的，外部API会更新，爬虫策略要调整，LLM对工具描述的理解也在变化。我后来给Skill加了简单的版本号，并在注册中心保留了启用/停用开关。要做改动时，先小流量灰度一个版本，确认没有引入回归再把旧版本停掉。这个流程虽然听起来很常规，但对Agent系统尤其重要，因为一个Skill的错误会通过LLM的决策被放大到整个任务链路里。

最后再分享一个小技巧：给每个Skill配一个"最典型使用场景"的示例，写在manifest.json里。比如web_extract的示例是"用户提供一个新闻链接，要求总结新闻内容"。这个示例有两个用处：一是让Skill开发者自己确认技能定位没有跑偏，二是可以自动生成测试用例反复验证。很多时候我们以为Skill写完了，结果一跑示例发现连最典型的场景都处理不好。这个最朴素的检查，反而帮我拦住了最多的隐性缺陷。