企业官网建设流程全解析

1. 从零拆解一个 AI 代理营销技能库到底在解决什么问题

第一次看到“AI 代理营销技能库”这个说法，很多人脑子里冒出来的画面可能是：给聊天机器人塞一堆营销话术模板，然后让它自动发广告。如果你也这么想，那基本就把这个项目理解偏了。我接触过几个类似方向的开源项目，也自己动手搭过几套面向营销场景的代理系统，踩过的坑不算少。今天要聊的这个 Marketingskills 项目，核心思路其实完全不是“话术模板库”，而是一套让 AI 代理真正具备营销执行能力的技能封装体系。

先把概念说清楚。所谓“AI 代理”，你可以理解为一个能自主调用工具、分步骤完成任务的智能体。它和普通聊天机器人的最大区别在于：聊天机器人只负责“说”，代理负责“做”。而“技能库”就是代理可以调用的能力集合，每一项技能对应一个具体的营销动作，比如生成落地页文案、分析竞品关键词、拆解用户评论情绪、批量产出多平台内容变体等等。Marketingskills 项目要做的，就是把这些零散的营销动作标准化、模块化，让代理能够像搭积木一样组合使用。

这个项目解决的核心痛点非常现实。在没有技能库的情况下，你要让 AI 完成一个完整的营销任务，比如“为一款新上线的效率工具做一轮冷启动内容投放”，你得在提示词里把所有要求、格式、约束、输出规范全部写清楚。提示词动辄几千字，维护成本极高，换个产品就得重写一遍。更麻烦的是，不同任务之间无法复用，每次都是从零开始。技能库的思路是把这些能力拆开、沉淀下来，每个技能有明确的输入输出定义、有独立的提示词模板、有可配置的参数，代理只需要根据任务目标去调用对应技能就行。

从技术架构上看，这类项目通常包含几个关键层。最底层是技能定义层，用结构化的方式描述每个技能的名称、功能、输入参数、输出格式、适用场景。中间层是技能执行层，负责把技能定义转换成实际的模型调用，处理上下文注入、参数校验、结果解析。最上层是技能编排层，让代理能够根据任务目标自主决定调用哪些技能、以什么顺序调用、如何处理中间结果。Marketingskills 在这三层之上还加了一个技能注册与发现机制，让技能库可以持续扩展，新技能加入后代理能自动识别并纳入可用范围。

适合关注这个项目的人其实比想象中要多。如果你是在做营销自动化工具的产品经理，这套技能库的设计思路可以直接借鉴到你的产品架构里。如果你是开发者，想给自己的 AI 应用加上营销能力，这个项目提供了现成的技能定义规范和参考实现。如果你是营销从业者，想理解 AI 代理到底能帮你做什么、边界在哪里，拆解这个项目能让你对“AI 能替代哪些营销工作”有一个清醒的认知。甚至如果你是做提示词工程的，这里面的技能封装思路也能给你不少启发。

我个人的判断是，这类项目的价值不在于它现在覆盖了多少个技能，而在于它提出了一套让营销能力可复用、可组合、可扩展的组织方式。这就像早期操作系统刚出现时，大家还在争论“为什么要用操作系统而不是直接写汇编”，但方向一旦对了，后面的生态爆发只是时间问题。接下来我会从设计思路、核心细节、实操落地、问题排查几个维度，把这个项目彻底拆开讲透。

2. 技能库的整体设计思路与架构选型考量

2.1 为什么选择“技能”而不是“提示词模板”作为基本单元

这是整个项目最核心的设计决策，值得花时间讲清楚。提示词模板的思路是：针对一个具体任务，写一段精心调优的提示词，用户填入变量后发给模型，得到结果。这种方式在单一任务上效果很好，但一旦任务变多、变复杂，就会暴露出几个致命问题。

第一个问题是组合爆炸。假设你有 10 个营销任务，每个任务需要 3 个不同的输出格式，那就是 30 个提示词模板。如果任务之间还需要串联，比如先分析竞品再生成文案再适配多平台，组合数量会指数级增长。第二个问题是上下文污染。当多个任务的提示词拼在一起时，模型很容易混淆指令，把 A 任务的要求应用到 B 任务上。第三个问题是无法复用。一个精心调优的“小红书文案生成”提示词，很难直接用在“知乎回答生成”上，尽管两者底层能力高度重叠。

技能库的思路是把“能力”和“任务”解耦。一个技能定义的是“能做什么”，而不是“为谁做什么”。比如“关键词提取”是一个技能，“情绪分析”是一个技能，“文案变体生成”是一个技能。代理接到“为新产品做一轮内容投放”这个任务后，会自主拆解：先调用关键词提取技能找出核心卖点词，再调用情绪分析技能判断目标用户的情感倾向，然后调用文案变体生成技能产出多个版本，最后调用平台适配技能调整格式。每个技能只负责一件事，组合逻辑由代理动态决定。

这种设计带来的好处是显而易见的。技能可以独立迭代，优化“关键词提取”不会影响“文案生成”。技能可以跨任务复用，同一个情绪分析技能既可以用在评论分析场景，也可以用在竞品文案拆解场景。技能可以按需组合，代理根据任务复杂度灵活编排，不需要预先穷举所有组合。

注意：技能粒度的把握是这类项目最容易翻车的地方。粒度太粗，技能就退化成提示词模板，失去复用价值；粒度太细，代理编排负担过重，调用链路过长容易出错。我的经验是，一个技能应该对应一个“原子级营销动作”，即无法再拆分且具有独立语义的操作。

2.2 技能定义的结构化规范设计

Marketingskills 项目在技能定义上采用了一套结构化规范，这是保证技能可被代理正确理解和调用的基础。一个完整的技能定义通常包含以下几个部分。

技能元信息包括名称、唯一标识、版本号、功能描述、适用场景标签。这部分看起来简单，但实际设计时有很多讲究。名称要足够具体，“生成文案”就不如“生成电商详情页卖点文案”清晰。功能描述要同时面向人和代理，既要让开发者一眼看懂，也要让代理能准确判断何时该调用这个技能。适用场景标签则是给代理做技能发现用的，当任务描述匹配到某个标签时，代理会优先考虑该技能。

输入参数定义是技能定义中最关键的部分。每个参数需要明确类型、是否必填、默认值、取值范围、以及最重要的——参数说明。参数说明不是写给人看的注释，而是会直接进入模型上下文，帮助模型理解该填什么。我见过很多项目在这里偷懒，参数说明写得含糊，结果代理调用时经常传错值。好的参数说明应该包含：这个参数影响输出的哪个方面、什么样的值算好、有没有推荐值。

输出格式定义决定了技能执行结果如何被解析和传递给下游。常见的有纯文本、JSON、Markdown 表格等。如果技能输出需要被其他技能消费，强烈建议用 JSON 并定义清晰的 schema。如果输出是给人看的最终结果，Markdown 或纯文本更合适。这里有一个容易忽略的点：输出格式定义里最好包含一个“示例输出”，这对代理理解期望结果非常有帮助。

执行配置包括模型选择、温度参数、最大 token 数、超时时间等。不同技能对这些参数的要求差异很大。创意类技能如文案生成，温度可以设高一些，0.7 到 0.9 之间比较合适，让输出有多样性。分析类技能如关键词提取，温度应该设低，0.1 到 0.3 之间，保证结果稳定可复现。这个细节很多项目没有处理好，导致同一个技能时而稳定时而不稳定。

2.3 技能注册与发现机制的设计

技能库要能持续扩展，就必须有一套注册与发现机制。Marketingskills 的做法是维护一个技能注册表，每个技能以独立文件或独立模块的形式存在，启动时自动扫描并加载。注册表里记录每个技能的元信息、参数 schema、执行入口，代理通过查询注册表来发现可用技能。

这里有一个设计上的权衡：技能是静态注册还是动态发现。静态注册是在代码里硬编码技能列表，简单直接但扩展需要改代码。动态发现是扫描指定目录下的技能定义文件，扩展只需新增文件，但需要处理加载失败、版本冲突等问题。Marketingskills 选择了动态发现为主、静态注册为辅的混合模式。核心技能静态注册保证稳定性，扩展技能动态发现保证灵活性。

技能发现的实际使用场景是这样的：代理接到任务后，先把任务描述向量化，然后与技能注册表中每个技能的功能描述和场景标签做相似度匹配，召回 top N 个候选技能。接着代理会读取这些候选技能的详细定义，判断哪些真正适用，最终确定调用计划。这个过程听起来复杂，但实际执行时模型能很好地完成，关键在于技能描述要写得准确、区分度要高。

提示：技能描述之间的区分度直接决定了发现机制的准确率。如果你的技能库里有两个技能描述都是“分析用户反馈”，代理大概率会选错。解决办法是在描述里加入更具体的限定词，比如“分析电商评论中的物流满意度”和“分析社区帖子中的产品功能建议”，区分度立刻就上来了。

2.4 与主流代理框架的集成方式

Marketingskills 本身不绑定特定的代理框架，它提供的是一套技能定义规范和执行接口，可以适配多种代理运行时。在实际集成时，通常有两种模式。

第一种是工具调用模式。把每个技能包装成一个工具函数，代理通过标准的工具调用协议来使用。这种模式的好处是兼容性好，主流代理框架都支持工具调用。缺点是技能之间的上下文传递需要代理自己管理，复杂任务下容易丢失中间状态。

第二种是工作流模式。把技能编排成预定义的工作流，代理按照工作流节点依次执行。这种模式适合流程相对固定的营销任务，比如“竞品分析报告生成”这种有明确步骤的场景。好处是执行稳定、结果可预期，缺点是灵活性差，遇到流程外的需求无法处理。

我的建议是两种模式结合使用。对于高频、流程固定的任务，用工作流模式保证效率和稳定性。对于探索性、需求多变的任务，用工具调用模式给代理更大的自主权。Marketingskills 的技能定义规范同时支持这两种模式，关键在于技能的执行入口设计要足够通用。

3. 核心技能模块的细节拆解与实操要点

3.1 内容生成类技能的参数设计与调优

内容生成是营销技能库里最基础也最常用的能力。Marketingskills 把内容生成拆成了几个独立技能：卖点提炼、文案变体生成、平台格式适配、语气风格调整。每个技能都有明确的职责边界，组合起来才能完成一个完整的内容生产流程。

卖点提炼技能的输入是产品信息，输出是结构化的卖点列表。这个技能的关键参数是“卖点维度”，常见的有功能维度、情感维度、场景维度、对比维度。功能维度强调产品能做什么，情感维度强调用了之后什么感受，场景维度强调在什么情况下用，对比维度强调比替代方案好在哪里。实操中我发现，一次只让模型聚焦一个维度，输出质量明显高于让它同时考虑多个维度。所以这个技能的设计是每次调用只处理一个维度，需要多维度卖点时调用多次。

文案变体生成技能的输入是卖点列表和目标平台，输出是多个文案版本。这里有一个关键参数是“变体策略”，决定了多个版本之间如何差异化。常见的策略有：开头钩子不同、叙事结构不同、行动号召不同、目标人群不同。我实测下来，同时变化多个维度容易导致版本之间差异过大，反而不好筛选。建议一次只变一个维度，比如固定叙事结构，只变开头钩子，这样产出的版本既有差异又可控。

平台格式适配技能负责把通用文案转换成特定平台的格式要求。不同平台对文案长度、段落结构、话题标签、互动引导的要求差异很大。这个技能的核心是一套平台规则库，每个平台定义一组格式约束。比如有的平台标题限制在 20 字以内，有的平台需要每段不超过 3 行，有的平台必须在结尾加互动提问。这些规则如果靠提示词临时描述，很容易遗漏，做成结构化的规则库后，代理调用时自动注入，准确率大幅提升。

语气风格调整技能是最容易被低估的一个。很多人觉得语气调整就是加一句“用轻松的语气”，实际远不止如此。这个技能需要定义一套风格维度，比如正式度、热情度、专业度、亲和度，每个维度用 1 到 5 分量化。调整时不是笼统地说“改轻松点”，而是明确“正式度从 4 降到 2，亲和度从 2 升到 4”。这种量化描述让模型有明确的调整方向，输出结果更符合预期。

实操心得：内容生成类技能的温度参数建议设在 0.7 到 0.8 之间。太低会导致每次输出雷同，失去变体意义；太高会出现事实性错误或逻辑混乱。另外，在技能定义里加入“禁止编造产品功能”这类硬约束，能有效减少模型幻觉。

3.2 数据分析类技能的输入输出规范

数据分析类技能在营销场景中主要负责从原始数据中提取洞察，包括评论情绪分析、竞品文案拆解、关键词聚类、用户画像归纳等。这类技能和内容生成类有一个本质区别：它们对准确性和可复现性的要求远高于创造性。

评论情绪分析技能的输入是一批用户评论，输出是情绪分布和典型评论摘录。这个技能的关键在于分类体系的设计。简单的正面/负面/中性三分法往往不够用，实际营销场景中需要更细的维度，比如对产品功能的满意度、对价格的接受度、对售后服务的评价、对物流速度的感受。每个维度独立打分，最后汇总成一份完整的情绪画像。我建议分类维度不要超过 6 个，太多会导致模型判断困难，准确率下降。

竞品文案拆解技能的输入是竞品的营销文案，输出是结构化的拆解报告，包括核心卖点、叙事结构、目标人群、情感诉求、行动号召方式等。这个技能的价值在于帮营销团队快速理解竞品的策略，而不是简单模仿。所以在输出规范里，除了客观拆解，还应该包含一个“可借鉴点”和“差异化机会”的分析部分。实操中我发现，让模型先做客观拆解再做主观分析，比让它一步到位直接给分析结论要准确得多。

关键词聚类技能的输入是一批关键词，输出是聚类后的主题分组。这个技能通常需要配合向量化模型使用，先计算关键词之间的语义相似度，再聚类。但纯算法聚类的结果往往不够“营销友好”，所以 Marketingskills 的做法是算法聚类加模型命名的组合。算法负责分组，模型负责给每组起一个营销人能理解的主题名称。这个组合方案实测下来比纯算法或纯模型都要好。

用户画像归纳技能的输入是用户行为数据或调研数据，输出是结构化的画像描述。这个技能最容易出现的问题是输出过于笼统，比如“年轻女性，注重性价比”这种放之四海皆准的描述。解决办法是在技能定义里强制要求输出包含“具体行为证据”，即每个画像特征都必须有对应的数据支撑。比如“注重性价比”后面要跟上“在 3 次购买决策中均对比了至少 2 个替代品价格”。这个约束能显著提升画像的可用性。

3.3 策略规划类技能的编排逻辑

策略规划类技能是技能库里层级最高的，它们不直接产出内容或分析结果，而是负责制定执行计划。Marketingskills 里这类技能包括投放节奏规划、内容矩阵设计、渠道组合建议等。

投放节奏规划技能的输入是营销目标、预算范围、时间窗口，输出是分阶段的投放计划。这个技能的核心是一套节奏模板，比如预热期、爆发期、延续期的经典三段式，或者针对不同产品类型的变体。技能执行时，模型根据输入参数选择合适的模板，再填充具体的时间和资源分配。这里有一个关键设计：节奏模板不是硬编码的，而是作为技能的可配置参数存在，不同行业、不同产品类型可以加载不同的模板库。

内容矩阵设计技能的输入是目标人群和平台列表，输出是内容主题与平台的匹配矩阵。这个技能需要处理的核心问题是：同一个主题在不同平台上应该用什么形式呈现。比如一个产品测评主题，在短视频平台适合做开箱体验，在图文平台适合做深度对比，在问答平台适合做选购指南。技能定义里需要包含一套“主题-平台-形式”的映射规则，代理根据规则生成矩阵。

渠道组合建议技能的输入是预算和目标，输出是各渠道的投入比例建议。这个技能涉及较多的经验性判断，纯靠模型容易给出不切实际的建议。Marketingskills 的做法是在技能里内置一套基准比例，模型在此基础上根据具体情况进行调整。比如基准是短视频 40%、图文 30%、问答 20%、其他 10%，如果目标人群偏年轻，模型会建议提高短视频比例。这种“基准加调整”的方式比让模型从零开始建议要靠谱得多。

注意：策略规划类技能的输出通常会被下游技能消费，所以输出格式的稳定性至关重要。建议强制使用 JSON schema，并在技能定义里加入输出校验逻辑。我遇到过因为策略技能输出格式偶尔漂移，导致下游内容生成技能解析失败的情况，加了 schema 校验后问题彻底解决。

3.4 技能间的上下文传递与状态管理

多个技能串联执行时，上下文传递是最容易出问题的环节。一个典型的内容生产流程可能涉及：卖点提炼 → 文案生成 → 平台适配 → 质量检查，四个技能依次执行，每个技能的输出是下一个技能的输入。如果上下文管理不当，就会出现信息丢失或污染。

Marketingskills 采用的方案是显式的上下文对象。每个技能执行完毕后，不是简单地把输出文本传给下一个技能，而是把输出写入一个结构化的上下文对象，下一个技能从上下文对象中按需读取。这样做的好处是：信息不会在传递过程中被意外修改，每个技能都能访问到完整的上下文，而不仅仅是上一个技能的输出。

上下文对象的设计有几个要点。首先要有明确的命名空间，不同技能写入的数据放在不同的键下，避免冲突。其次要有版本标记，当某个技能的输出格式升级时，下游技能能感知到并做兼容处理。最后要有大小控制，上下文对象不能无限增长，需要定期清理不再需要的中间结果。我见过一个项目因为上下文对象累积了太多历史数据，导致后期技能调用时 token 超限，整个流程崩溃。

状态管理方面，长流程任务需要支持断点续传。比如一个包含 10 个技能调用的营销活动策划流程，执行到第 6 个技能时失败了，理想情况下应该能从第 6 个技能重新开始，而不是从头再来。Marketingskills 通过持久化上下文对象来实现这一点，每个技能执行成功后就把上下文快照存下来，失败重试时加载最近的快照继续执行。

4. 从零搭建一个营销技能库的完整实操过程

4.1 环境准备与项目结构规划

动手之前先把项目结构规划清楚，后面扩展会省很多事。我推荐的结构是这样的：根目录下分四个主要文件夹，skills 存放技能定义文件，engine 存放执行引擎代码，registry 存放技能注册表，examples 存放使用示例。每个技能在 skills 下有自己的子目录，包含 skill.json 定义文件和 prompt.md 提示词模板。

技能定义文件用 JSON 格式，因为 JSON 的解析生态最成熟，各种语言都能方便处理。定义文件里包含前面说的元信息、参数 schema、输出 schema、执行配置。提示词模板单独放在 markdown 文件里，好处是可以利用 markdown 的格式来组织提示词，比塞在 JSON 字符串里可读性高得多。

执行引擎的核心是一个调度器和一个执行器。调度器负责接收任务、发现技能、编排调用顺序。执行器负责实际调用模型、处理输入输出、管理上下文。这两个组件建议分开实现，调度逻辑和执行逻辑解耦后，替换模型提供商或调整编排策略都不会互相影响。

注册表可以先用一个简单的 JSON 文件维护，记录每个技能的路径和基本信息。技能数量超过 50 个后，建议换成轻量数据库，支持按标签、按场景的快速检索。不过对于大多数团队来说，50 个技能已经能覆盖绝大部分营销场景了，不用过早优化。

4.2 定义第一个技能：从卖点提炼开始

卖点提炼适合作为第一个技能来练手，因为它逻辑清晰、输入输出明确、不依赖其他技能。下面是一个技能定义的示例结构。

{ "name": "selling_point_extraction", "version": "1.0.0", "description": "从产品信息中提取结构化卖点，每次聚焦一个维度", "tags": ["内容生成", "卖点分析", "产品营销"], "parameters": { "product_info": { "type": "string", "required": true, "description": "产品的基本信息，包括功能、价格、目标人群" }, "dimension": { "type": "string", "required": true, "enum": ["功能", "情感", "场景", "对比"], "description": "本次提取聚焦的卖点维度" }, "count": { "type": "integer", "required": false, "default": 5, "description": "期望输出的卖点数量，建议 3 到 8 个" } }, "output": { "format": "json", "schema": { "points": [ { "content": "string", "evidence": "string", "priority": "integer" } ] } }, "execution": { "temperature": 0.4, "max_tokens": 1500 } }

对应的提示词模板放在 prompt.md 里，核心结构是：角色设定、任务说明、输入注入、输出格式要求、约束条件。角色设定要具体，不要写“你是一个营销专家”，而是写“你是一个有 10 年消费品营销经验的卖点策划师，擅长从产品细节中挖掘打动用户的点”。任务说明要明确本次聚焦的维度，并解释这个维度的含义。输出格式要求直接引用 schema，并给一个示例输出。约束条件包括禁止编造、每个卖点必须有依据、按优先级排序等。

定义好之后，写一个简单的测试脚本，用几个不同产品的信息跑一遍，检查输出是否符合 schema、卖点质量是否达标、不同维度切换是否正常。这一步不要偷懒，第一个技能调通后，后面的技能都可以参照这个模式来定义，效率会高很多。

4.3 技能执行引擎的核心实现

执行引擎的核心流程可以概括为：接收任务 → 发现技能 → 构建调用计划 → 依次执行 → 汇总结果。下面重点讲几个关键环节的实现要点。

技能发现环节，我建议用“标签匹配 + 语义相似度”的两级召回。先用任务描述中的关键词匹配技能标签，召回一批候选。再用向量相似度对候选排序，取 top 5 进入下一步。纯标签匹配召回率不够，纯语义匹配准确率不够，两者结合效果最好。向量化可以用轻量模型，不需要太高的精度，因为后面还有模型做最终判断。

调用计划构建环节，把候选技能的定义和任务描述一起发给模型，让模型输出一个调用序列。这里的关键是给模型足够的约束，比如“最多调用 5 个技能”、“每个技能只能调用一次”、“技能之间要有明确的输入输出依赖关系”。不加约束的话，模型容易生成过于复杂或循环依赖的计划。

执行环节要处理几个实际问题。第一个是超时控制，每个技能调用设置独立的超时时间，超时后根据配置决定是重试还是跳过。第二个是错误处理，技能执行失败时，把错误信息写入上下文，让后续技能或最终汇总环节能感知到。第三个是结果缓存，相同输入和参数的技能调用结果可以缓存，避免重复消耗。

结果汇总环节，把所有技能的输出按调用顺序整理成一份完整的执行报告。报告里除了最终结果，还应该包含每个技能的调用状态、耗时、token 消耗。这些信息对后续优化技能库非常有价值。

4.4 技能库的测试与迭代方法

技能库建好之后，怎么知道它好不好用？我总结了一套测试方法，分三个层次。

单元测试针对单个技能，用固定的输入跑多次，检查输出是否稳定、是否符合 schema、是否满足约束条件。这个层次的测试要自动化，每次修改技能定义后都跑一遍。重点关注的指标是输出格式合规率和内容质量评分。内容质量评分可以人工抽检，也可以用一个专门的评估技能来打分。

集成测试针对技能组合，模拟真实的营销任务，检查多个技能串联执行时上下文传递是否正确、调用顺序是否合理、最终结果是否可用。这个层次的测试用例要覆盖典型场景，比如“新品内容投放”、“竞品分析报告”、“用户反馈洞察”等。每个用例记录执行链路和最终结果，便于对比不同版本的表现。

回归测试在技能库迭代时使用，每次新增或修改技能后，跑一遍全部测试用例，确保没有破坏已有功能。回归测试最容易忽略的是技能发现问题，新增技能后可能导致原本匹配到 A 技能的任务现在匹配到了 B 技能，这种变化不一定是坏事，但需要被感知和评估。

迭代方面，我建议建立一套技能使用数据收集机制。记录每个技能的调用次数、成功率、平均耗时、用户反馈评分。调用次数高但评分低的技能优先优化，调用次数低但评分高的技能考虑如何提升曝光，调用失败率高的技能排查是定义问题还是执行问题。这套数据驱动的方法比凭感觉优化要有效得多。

5. 实操中遇到的典型问题与排查技巧

5.1 技能调用错位与参数传递错误的排查

技能调用错位是最高频的问题，表现是代理调用了不相关的技能，或者该调用 A 技能时调用了 B 技能。排查这类问题，我通常按以下顺序检查。

先看技能描述是否有歧义。把技能注册表里所有技能的 description 和 tags 列出来，逐对比较，看有没有两个技能在语义上过于接近。如果有，要么合并，要么在描述里加入更强的区分词。我遇到过一个案例，“文案生成”和“内容创作”两个技能描述几乎一样，代理每次都是随机选，后来把前者改成“生成电商平台商品文案”，后者改成“生成社交媒体帖子内容”，问题立刻解决。

再看任务描述是否足够明确。如果用户输入的任务描述本身就很模糊，比如“帮我做点营销”，代理选错技能几乎是必然的。解决办法是在任务入口加一层意图澄清，让用户补充关键信息后再进入技能发现流程。或者让代理在发现阶段输出候选技能和选择理由，人工确认后再执行。

参数传递错误通常表现为技能执行报错或输出不符合预期。排查时先检查参数 schema 定义是否准确，特别是类型和枚举值。我见过把 integer 写成 string 导致模型传了“5”而不是 5，执行时报类型错误。还见过枚举值定义不全，模型传了一个不在枚举里的值，校验直接失败。建议在技能定义里加入参数示例，模型看到示例后传错值的概率会明显降低。

避坑技巧：在技能执行前加一层参数预校验，把校验失败的信息返回给代理，让代理重新生成参数。这比直接报错终止流程要友好得多，实测能挽回大约 70% 的参数错误。

5.2 输出格式漂移的预防与修复

输出格式漂移是指技能实际输出与定义的 schema 不一致，比如该输出 JSON 却输出了 markdown，该有 5 个字段却只有 3 个。这个问题在内容生成类技能中尤其常见，因为模型有“自由发挥”的倾向。

预防措施有几个。第一，在提示词里明确要求“只输出 JSON，不要有任何其他文字”，并且把这句话放在提示词的最后，因为模型对末尾指令的遵循度更高。第二，给一个完整的示例输出，示例要覆盖所有字段，包括可选字段。第三，在技能定义里设置较低的 temperature，减少随机性。第四，如果模型支持结构化输出功能，直接启用，这是最可靠的方式。

修复措施方面，如果已经出现了格式漂移，可以在执行器里加一层解析容错。比如输出被 markdown 代码块包裹了，解析时先剥离代码块标记。比如字段名大小写不一致，解析时做归一化处理。比如缺少可选字段，用默认值填充。这些容错逻辑能解决大部分轻微漂移问题。

对于严重漂移，比如输出完全不是 JSON，我的做法是触发一次重试，在重试提示词里加入“上次输出格式错误，请严格按照 schema 输出”的提醒。如果重试仍然失败，就把这个案例记录下来，作为技能定义优化的依据。连续多次失败说明技能定义本身有问题，需要重新设计。

5.3 长流程任务的超时与中断处理

营销任务往往涉及多个技能串联，流程一长，超时和中断的概率就上来了。我处理过的案例中，一个完整的竞品分析流程涉及 7 个技能调用，总耗时超过 3 分钟，中间任何一步网络抖动都可能导致整个流程失败。

超时处理的核心是分级设置。单个技能调用的超时时间根据技能复杂度设置，简单技能 30 秒，复杂技能 120 秒。整个流程的总超时时间根据技能数量估算，一般留出 50% 的余量。超时后不要直接失败，而是根据当前进度决定策略：如果关键技能已完成，可以跳过剩余非关键技能，输出部分结果；如果关键技能未完成，则整体失败并返回已完成的部分。

中断处理的核心是状态持久化。每完成一个技能调用，就把上下文对象序列化存下来。中断后重新启动时，加载最近的上下文快照，从下一个技能继续执行。这里要注意上下文的版本兼容性，如果技能定义在中断期间发生了变更，加载旧上下文可能会出问题。解决办法是在上下文里记录每个技能的定义版本，加载时校验版本，不匹配则提示需要重新执行。

实操心得：长流程任务建议加一个进度回调机制，每完成一个技能就回调通知调用方。这样即使最终失败，调用方也能知道执行到了哪一步，便于人工介入或调整策略。我负责过的一个项目加了进度回调后，问题定位效率提升了一倍以上。

5.4 常见问题速查表

这张表里的每一条都是我在实际项目中真实遇到过的，有些问题排查了大半天才找到原因。建议把这张表打印出来贴在工位上，遇到问题先对照排查，能省不少时间。

6. 技能库的扩展方向与个人实践体会

技能库建起来之后，扩展方向其实比初始搭建更值得思考。我个人的经验是，扩展不要贪多，要沿着“高频场景做深、低频场景做通”的原则来。高频场景比如内容生成、数据分析，值得投入精力把技能做细做精，参数调优、提示词打磨、输出校验都做到位。低频场景比如某些特定平台的格式适配，做一个通用技能能覆盖就行，不必为每个平台单独开发。

另一个扩展方向是技能的组合封装。当某些技能总是成组出现时，可以把它们封装成一个复合技能，对外暴露更简单的接口。比如“卖点提炼 + 文案生成 + 平台适配”经常一起用，就可以封装成“内容生产”复合技能，内部还是调用三个原子技能，但对外只需要一个调用入口。这样既保留了原子技能的灵活性，又降低了常用场景的使用复杂度。

我还想分享一个关于技能库维护的体会。技能库不是建完就完了，它需要持续维护。模型在迭代，平台规则在变化，用户需求在演进，技能定义也需要跟着更新。我建议建立一个技能健康度看板，跟踪每个技能的调用量、成功率、用户评分、最近更新时间。健康度低的技能优先处理，长期无人调用的技能考虑下线。保持技能库的精简和活跃，比盲目扩张更重要。

最后说一个我踩过的坑。早期我总想把技能定义写得特别详细，参数特别多，觉得这样代理调用时更准确。结果发现参数太多反而导致代理不知道该传什么，调用失败率上升。后来我把参数精简到 3 到 5 个核心参数，其他都用默认值或从上下文推断，调用成功率明显提升。技能定义的原则应该是“够用就好”，而不是“越多越好”。这个教训让我在后来的项目中少走了很多弯路。