企业官网建设流程全解析

1. 从"会聊天的机器人"到"能干活的工作流"：agent-skills解决的核心矛盾

先说个我最近的真实感受。以前我给智能体写功能，脑子里默认的思路就是"把提示词写长一点，再多给它几个例子"。结果是什么呢？提示词膨胀到两三万字，模型一长就乱，改一个需求得从头调一遍，不同场景之间逻辑互相串味。最崩溃的是，同一个动作——比如从PDF里抽表格——在A任务里能用，换到B任务里因为请求格式不一样又得重写一遍。

后来我尝试换了个思路：不再把能力"写死在提示词里"，而是把能力拆成一个个独立、可复用、有明确输入输出定义的技能（skills）。这个思路现在是我构建智能体的核心方法论，我管它叫agent-skills。通俗点说，就像软件开发里"函数"和"模块"的概念，你写一堆小工具函数，然后让智能体在需要的时候自己选择调用哪个。区别在于，这些技能不是给程序员调用的，而是给大模型判断和调用的。

这件事的价值在于，它把"智能体"从一个黑盒变成了一个可以被拆解、测试、维护的系统。你可以单独验证"翻译技能"好不好使，也可以让它在多个工作流里共享，甚至可以让非技术同事通过配置来扩展新技能，不用改一行提示词。如果你也在做Agent类的产品，或者经常被"提示词越写越长但效果越来越不稳"困扰，这篇文章就是为你准备的。我会从为什么、怎么设计、怎么实现、怎么测，一路聊到踩坑经验。

2. 技能拆分的边界：从任务到子技能的方法论

2.1 别把"技能"做成"超能力"

很多人第一次设计技能时，容易走向两个极端。一个极端是技能粒度太粗，比如"文档处理技能"——这根本不是一个能力，而是十几个能力的集合；另一个极端是粒度太细，比如"将字符串转为小写"——这种基础操作不需要模型来判断，直接在代码里做就行。

我在设计技能时脑子里有个简单的标准：一个技能必须是一个可以被自然语言描述、且输入输出边界清晰的原子操作。什么叫"原子"？就是你很难再把这件事拆成更小且更有意义的步骤。当然，具体粒度取决于你的场景，但有一个通用判断标准：如果你发现在多个任务里，某个能力总是"连着出现"或者"换个参数就能复用"，那它就该独立成一个技能。

打个比方。你家里有工具箱，技能就是里面的螺丝刀、扳手、卷尺，而不是一个"修家具工具箱"。工具箱本身是智能体的系统提示词和候选技能列表，里面的每个工具必须能被单独抽出使用。

2.2 从任务描述反推技能清单

具体怎么拆？我的做法是拿着一个"典型任务"从头到尾走一遍，把每一步涉及到"需要模型做一些特定动作"的地方标出来。举个例子：一个企业周报生成任务，拆出来可能是——读取数据源、按指标维度汇总、生成趋势描述、选择图表类型、格式化输出。其中"读取数据源""生成趋势描述""选择图表类型"这三个动作可以提炼为技能；"按指标维度汇总"如果数据格式固定，可以直接写在代码流程里，未必需要模型参与。这样一拆，你不仅得到了技能清单，还顺带明确了哪些步骤该交给模型、哪些步骤该走规则逻辑。

对了，还有个重要的反向操作：合并技能。如果两个技能总是被同时调用，且先后顺序固定，就把它们合并成一个复合技能，减少一次模型决策的调用，也能降低出错的概率。比如"解析PDF"和"抽取表格"如果总是连着用，干脆合成"解析PDF并抽取表格"一个技能。

2.3 技能描述：写给模型的"使用说明书"

一个技能的灵魂不是它的实现代码，而是它的描述文档。因为模型是靠着描述来决策的，描述写得好不好，直接决定了调用准确率。

我一般会为每个技能写结构化描述，包含以下几部分：

当初我把description写成"解析PDF并返回内容"，模型就经常在不需要这个工具的时候乱调用。后来改成上面这种带"适用场景+禁止场景"的描述，精确度大幅提升。所以记住：描述不是给人看的注释，是给模型看的指令，写得越专业，调用越准确。

3. 接口即契约：定义技能时的关键决策

3.1 参数类型越严格，后期越省心

技能接口设计中，我最想强调的就是参数类型。很多demo里都用"kwargs字典+自由字符串"来传参，这在原型阶段很爽，但一旦进入生产环境就变成灾难。模型在自由文本参数里填错格式的概率远比你想象的高。比如你定义了一个"发送邮件"技能，要求传入recipient字段，如果你不规定它是string还是array，模型就可能填一个逗号分隔的字符串，又或者填一个列表，前端代码两个都得兼容。

因此我在设计输入schema时会严格采用JSON Schema规范，枚举值、正则、最小最大长度都写得清清楚楚。模型虽然不能保证百分之百遵守，但有了约束之后，出错的概率会大幅下降，而且出错时可以很方便地通过schema校验并把校验错误回传给模型，让它自己纠正。这一招在实践里非常管用。

3.2 返回值结构化：让模型少做"猜测题"

技能的输出同样要结构化。常见错误是技能返回一大段纯文本，让模型自己去找关键信息。结果就是模型可能漏看、瞎猜。正确做法是：技能返回值里直接给模型完全精确的数据结构。比如一个"查询库存"技能，不要返回"还有123件"，而是返回{"sku": "ABC", "quantity": 123, "warehouse": "shanghai"}这种标准JSON。这样模型后续无论是要做判断还是做摘要，都有据可依。

3.3 错误信息的"自我修复闭环"

技能不可能永远成功。文件不存在、网络超时、权限被拒，这些都是家常便饭。关键区别在于你的错误处理方式。你可以在错误时返回{"success": false, "error_code": "FILE_NOT_FOUND", "message": "..."}。这个结构本身不稀奇，更重要的技巧是，在message里写上模型可以执行哪些补偿动作。

举个例子，技能"读取文件"失败时，返回的消息可以是："文件不存在，请检查file_path是否正确。你可以调用list_dir技能查看目录内容，或者询问用户重新提供路径。" 这样一来，模型就知道下一步该干什么，而不是含糊地说"抱歉我遇到了问题"。这个小设计让我的智能体自主修复成功率提升了非常多，也大大减少了用户对话轮数。

4. 注册、发现与调用：把技能跑起来的代码骨架

4.1 技能注册表

聊完设计，来看实际工程。我做的agent-skills是一个轻量级框架，核心思路就三件事：注册、发现、执行。代码不算复杂，但够用。

注册部分，我用的是装饰器模式。给每个技能绑定name、description、输入schema和实现函数，然后塞进一个全局注册表。类似这样：

# registry.py SKILL_REGISTRY = {} def skill(name, description, input_schema, output_schema=None, usage_notes=None): def decorator(func): SKILL_REGISTRY[name] = { "name": name, "description": description, "input_schema": input_schema, "output_schema": output_schema, "usage_notes": usage_notes, "func": func, } return func return decorator

然后，具体的技能实现长这样：

# skills/pdf_skills.py from registry import skill @skill( name="extract_tables_from_pdf", description="从PDF文件中提取所有表格，返回Markdown格式。适用含数据表格的财务报告、研究论文等。如果PDF是扫描件，请勿使用。", input_schema={ "type": "object", "properties": { "file_path": {"type": "string", "description": "PDF文件的完整路径"}, "page_range": {"type": "array", "items": {"type": "integer"}, "description": "页码范围，如[1,3]表示第1页到第3页，默认全部页"} }, "required": ["file_path"] }, output_schema={ "type": "object", "properties": { "tables": {"type": "array", "items": {"type": "string"}}, "count": {"type": "integer"} } } ) def extract_tables_from_pdf(file_path, page_range=None): # 这里是解析PDF的具体实现 ... return {"tables": table_list, "count": len(table_list)}

4.2 模型如何与技能列表交互

目前的智能体通常通过function calling机制或tool calling机制来调用技能。训练模型时，系统提示词会带上技能列表的JSON描述。在执行流程里，我的主循环大致是：

1. 从注册表里取全部技能元信息，转成模型API要求的tools格式。
2. 把用户请求 + 当前上下文发给模型。
3. 模型如果认为需要调用某个技能，会返回一个tool_call，包含技能name和参数。
4. 代码侧按参数调用相应的函数，拿到结果。
5. 把结果作为新的消息回传给模型，让模型继续。
6. 循环直到模型给出最终回答。

这套流程本身不特殊，但有几个细节我踩过坑。第一，不要一次性把所有技能全塞给模型，尤其是技能超过十个以后，模型的选择准确率会下降。我会先让一个轻量级的"路由器"模型根据用户意图筛选相关技能子集，再把子集传给主模型。你也可以在注册表里给技能打上标签，按域（domain）动态加载。第二，调用函数时要对参数做schema校验，不允许模型传什么就信什么，校验不通过就把错误信息回给模型让它重新生成参数。

4.3 一个可复用的执行器封装

为了方便集成，我封装了一个执行器，它负责把模型返回的tool_call映射到注册表里的函数，同时做异常兜底：

# executor.py import json from registry import SKILL_REGISTRY from validator import validate_input def execute_tool_call(tool_call): name = tool_call["name"] arguments = json.loads(tool_call["arguments"]) if name not in SKILL_REGISTRY: return {"success": False, "error": f"Skill '{name}' not found"} skill_meta = SKILL_REGISTRY[name] validation_error = validate_input(skill_meta["input_schema"], arguments) if validation_error: return { "success": False, "error_code": "INVALID_PARAMETER", "message": f"参数校验错误: {validation_error}。请重新生成参数" } try: result = skill_meta["func"](**arguments) if "success" not in result: result["success"] = True return result except Exception as e: return { "success": False, "error_code": "EXECUTION_FAILED", "message": f"技能执行异常: {str(e)}" }

这个执行器不是万能，但胜在简单可靠。你完全可以照着这个骨架改造成适合自己项目的工具链。

5. 技能生命周期管理：测试、版本与灰度

5.1 给每个技能写专门的"评测集"

一旦技能变成了独立组件，你就能像给后端接口做测试一样给技能做评测。这一步我在早期做Agent时完全没做，所以频繁翻车。后来我给每个技能维护一份评测集，包含三类用例：

• 标准用例：正常输入，期望输出符合预期结构。
• 边界用例：空值、超长文本、缺失字段、错误类型。
• 对抗用例：故意给出模糊或冲突的描述，看模型是否调用错误技能。

评测集不是给函数跑单元测试——那是另一部分——而是让模型用自然语言描述调用场景，再由模型或人判断技能调用决策是否正确。比如我把一堆用户query丢给评测系统，让带技能列表的模型去决策调用哪个技能，然后和正确答案比对。这样测的不只是技能实现，还包括技能描述的清晰度。

5.2 技能版本与仓库目录

技能一定会迭代。我习惯把每个技能实现为一个独立函数并采用语义化版本。注册表里存储版本号，模型可见的技能版本则固定一个。当新版本上线后，先在仿真环境里跑评测集，通过率达标才更新注册表。同时保留历史版本的回滚入口。这样能避免那种"上一个技能逻辑变了，老用户流程突然崩掉"的问题。

5.3 动态加载与"技能商店"

如果你希望系统具备扩展性，可以把技能注册表从代码里抽出来放到配置中心或数据库里，让运营人员通过配置界面新增技能，而不用改代码。这本质上是一个"技能商店"的思路。每个技能条目包含name、description、schema、是否启用、路由标签等信息。模型调用时，系统动态读取启用的技能列表并执行。这套机制让非技术人员也能扩展智能体的能力，扩展新技能变成了"填一张表单"而不是"写一段提示词"。

6. 实战案例：把多轮对话变成标准化流水线

为了让你更直观理解agent-skills的落地效果，我分享一下最近搭建的一个"投标文档初稿生成"流程。以前这活儿靠人整，一套流程下来至少要几小时。现在我把它拆成6个技能：上传并解析文档、提取关键技术指标、检索历史案例库、生成合规性检查清单、撰写章节草稿、输出规范化文档。

每个技能都是独立函数，有各自的输入输出。比如"检索历史案例库"技能：模型首先调用"上传并解析文档"得到需求文档的文本结构，再从中提炼出技术要点，然后调用"检索历史案例库"传入关键词数组，返回相关案例的引用。整个流程由模型自主决定调用顺序，而不是预先写死。好处是两个项目就算流程顺序不同，模型也能组出来。我有一次故意把调用顺序打乱，只给定技能列表，模型依然能自己安排出一条合理路径。这就是技能化相比固定工作流的最大优势：具备动态编排能力，同时每个环节可独立测试。

过程中也发现，有些步骤单靠技能还不够。比如"生成合规性检查清单"技能返回的清单中间有缺漏，后来我在技能的usage_notes里补充了"必须逐条比对招标文件中的否决项，如任一条不满足需在结果warning字段中标明"。再跑评测集，正确率上升了不少。这说明技能描述本身就是一个可以通过评测集持续微调的对象。

7. 那些文档里不会写的坑，以及我的最终建议

最后聊几个真正的经验教训。

第一个坑：过度抽象。我最初热衷于设计一套跨任务通用的基础技能，结果每个任务用起来都要传一堆奇怪的参数，模型犯晕，代码也难维护。后来我接受了一个现实：技能可以有一些业务相关性，通用型和专用型技能混着来，别强求所有技能都通用。

第二个坑：忽略上下文占用。技能描述和调用记录都会占用上下文窗口。技能很多时，每次把调用结果全部塞回去，没两轮对话就把窗口撑爆了。我后来给输出schema加上了"summary"或"compressed"字段，让技能在返回大量数据的同时提供摘要版本，模型默认读摘要，需要细节时再触发另一个技能取详细数据。这一招能显著延长多轮对话的稳定长度。

第三个坑：忽略了技能失败后的"引导信息"。一开始我的错误返回就是简单的{"error": "failed"}，模型只会跟你道歉，解决问题毫无进展。后来改成带错误码和修复提示的结构，情况才好转。记住，大模型是靠着你给的信息在做推理，错误信息里不给对策，它真的就无脑道歉。

如果你正打算给智能体搭建能力体系，我的建议很直接：不要在提示词里堆砌万能话术，从最小的技能拆起，把接口当契约，把评测当质量门禁，让每个技能能独立进化。agent-skills不是一个固定的现成工具，而是一套组织智能体能力的思想。而且这套思想跟具体的大模型厂商无关，无论底层换成什么模型，技能层都能保留下来，这大概是它最值得投入的原因。

最后分享一个小技巧：在技能描述的开头加上"这个技能是什么"的简短说明，在末尾加上"什么情况下不使用"的句子。这两句话加起来不过几十个字，却能让技能调用的准确率上一个台阶。我试过多次，屡试不爽。你也试试看。