这段时间我在推进“闪学it”的Agent Skills多平台应用实战项目核心目标就一句话让同一套AI能力拆成独立的技能单元在Web后台、办公IM机器人、移动端和定时任务里都能稳定跑起来。做过这类事的人应该都有体会单独写一个Agent Demo不难难的是当你发现Web端要一个结果、机器人要一段富文本、移动端要一个流式返回的时候同一个逻辑被迫复制了三份prompt各改各的工具配置越来越乱。这篇文章我会把整个拆解过程和实操路径完整讲清楚适合那些已经把Agent跑通但想上多平台、又不想被维护成本拖死的开发者参考。1. 为什么Agent项目必须拆成Skills一次多平台重构的复盘1.1 单体Agent在多平台场景下的失控过程先说一个我踩过的典型场景。最初我做了一个完整的Agent应用把大模型对话、上下文记忆、工具调用、权限判断全揉在一起接在办公IM机器人上。当时想得很简单用户发消息Agent自动理解意图调用工具返回回答。单平台跑通之后需求立刻来了——管理后台要一个操作界面移动端要一个快捷入口日报定时任务还要自动汇总信息。这时候问题全部浮出来了。首先是状态管理IM机器人的对话上下文和Web页面里的会话上下文根本不是一回事强行复用导致同一个用户在两边的记忆互相错乱。其次是prompt膨胀为了适配不同的输入格式和输出要求我在同一个Agent里堆满了条件分支最终那段system prompt超过两千字改动一处就牵一发动全身。最要命的是工具调用有些平台需要异步回调有些平台只接受同步返回单体Agent根本没法对不同平台分别处理超时和重试。复盘下来问题的根源不是模型不行而是能力单元的粒度错了。一个完整的Agent是“带状态的对话系统”但Web按钮、机器人指令、定时任务根本不需要对话状态它们需要的是“把一段输入变成一段输出”的确定性能力。如果把这些能力从Agent里剥离出来各自定义好输入输出再让不同平台去调用维护复杂度会断崖式下降。这就是我决定把项目重心转向Agent Skills的原因。1.2 Skills的定义与生活化类比Agent Skills的核心思想是把Agent具备的某种能力封装成一个独立的、可复用的、声明式描述的技能单元。一个Skill不关心调用方是聊天窗口还是HTTP接口它只接收标准化的输入参数执行内部逻辑返回标准化的输出结果。说得直白一点一个Skill有点像“函数”但它比普通函数的边界更严格——不仅要有清晰的入参出参还要有对应的自然语言描述、参数校验规则、超时策略和运行配置。用一个生活化的类比来理解做一桌菜需要菜谱菜谱是完整的应用流程它规定了先做什么后做什么、放多少盐、焖几分钟但刀工、火候控制、酱汁调制这些基本功是可以独立存在的技能。你换了餐厅、换了菜单这些基本功照样能用。Agent项目同理完整流程可能因平台而异但“文本摘要”“关键字提取”“意图识别”“数据查询”这些基本功应该沉淀成Skills在任何平台都能被直接调用。这个思路带来的直接好处是开发模式从“每个平台单独做一个Agent”变成了“先建设技能库再在各个平台调用技能”。当有新平台要接入时不需要重写Agent逻辑只需要做适配层把平台的输入格式转成技能标准参数再把技能输出转成平台展示格式。1.3 三层架构技能层、接入层、表现层实际操作时我把整个系统分成了三层这个分层对控制复杂度非常关键。技能层Skill Layer所有Skills的注册与实现完全平台无关只处理业务逻辑。接入层Bridge Layer统一的调用入口负责鉴权、参数校验、路由分发以HTTP/SSE接口对外暴露。表现层Channel Layer面向具体平台的适配器把平台的消息格式解析成技能参数再把技能结果渲染成平台支持的格式。之所以把平台差异隔离在表现层是因为平台差异主要集中在消息格式、渲染语法、回调方式、超时限制这些“外围”属性上。技能层一旦被平台细节污染复用性就没了。所以我在项目里立了一条规矩技能层代码里不允许出现任何平台关键字连“IM”“小程序”“Web”这样的词都不准出现在业务逻辑里。接入层选择HTTP/SSE而不是重型RPC框架原因很简单技能调用需要兼容的客户端形态太多了浏览器、机器人服务器、移动端SDK、脚本工具HTTP是最通用的协议。流式返回用SSE处理可以解决长耗时任务在部分平台上的等待超时问题。这套分层方案经受住了后续多个渠道的接入考验是目前我觉得最稳妥的起点。2. 技能定义与运行机制把“会做什么”变成机器可读的契约2.1 技能注册表为什么用JSON Schema做契约技能要能跨平台复用第一步就是把它描述清楚。我参照软件接口设计的原则为每个Skill定义了一份注册清单用JSON Schema描述输入输出。这样无论是人工查看还是让代码做自动化校验都能基于同一份契约。下面是一份技能注册表的示例我把关键字段都写了注释{ skill_name: meeting_minutes, version: 1.2.0, description: 将会议语音转写文本整理为结构化会议纪要, input_schema: { type: object, properties: { transcript: { type: string, description: 会议转写的纯文本内容, maxLength: 200000 }, language: { type: string, enum: [zh, en], default: zh }, include_action_items: { type: boolean, default: true } }, required: [transcript] }, output_schema: { type: object, properties: { summary: { type: string }, action_items: { type: array, items: { type: string } }, risks: { type: array, items: { type: string } }, timeline: { type: array, items: { type: object } } }, required: [summary, action_items, risks, timeline] }, timeout_ms: 30000, is_streamable: true, capabilities: [text_chunking, semantic_analysis] }每个字段都不是随意设计的。timeout_ms看起来只是数字但它直接影响多平台体验Web端用户可以接受等待IM机器人如果超过响应时限可能会直接报错移动端弱网环境下就更敏感。is_streamable对应是否支持SSE流式返回不支持流式的Skill在IM和移动端会被迫使用等待轮询方案体验差距很大。input_schema里的maxLength也重要大模型接口通常有Token上限提前在契约层声明比在调用端报错要友好得多。还有一点需要特别注意注册表的description不要写得含糊比如“处理会议文本”这种描述就没有意义。要写清楚这个Skill适合什么输入、不适合什么输入、输出中的字段各代表什么含义。因为这个描述不仅给人看也会被上游的意图识别模块使用。描述不好后续做技能组合时路由就会出错。2.2 运行上下文Skill不记忆、不感知用户这是整个项目里最反直觉也最重要的一条原则Skill不应该维护对话历史也不该感知用户的身份和会话状态。它就像一个公开的API函数你给我参数我还你结果不带任何记忆。一旦Skill内部悄悄记住了“上次的调用结果”跨平台复用就彻底完蛋了。我见过一个团队踩了坑他们在技能内部缓存了用户的上一轮输入希望实现“上下文自动连接”的效果。结果同一个用户在Web上问过的问题跑到IM机器人那边再次触发同一技能时返回了完全无关的内容。原因是Web端和IM端的会话状态没有共享Skill内部自以为是地“补全”了上下文。所以我的铁律是所有上下文信息必须显式作为参数传入SkillSkill自身保持无状态。需要多轮对话那是Agent编排层的事不是Skill的事。无状态设计的另一个好处是便于缓存和并发控制。相同输入可以安全地复用缓存结果不需要担心不同用户之间的数据串扰。并发请求也只需要按Skill维度做限流不需要按用户会话加锁。2.3 Prompt与模型参数的管理策略Skills跑在模型之上prompt和模型参数的管理直接影响输出质量。我的做法是prompt模板内嵌在Skill里作为技能的默认配置但调用方可以通过参数临时覆盖部分内容比如输出语言、语气风格等。模型参数如temperature、max_tokens则放在调用层控制。为什么这样拆分因为不同平台对输出要求的严格程度差异很大。Web后台可以接受模型自由发挥富有个性的表述反而加分但定时任务生成的报表如果格式不稳定下游脚本解析就直接失败。所以我在定时任务调用Skill时会把temperature压到0.2左右在IM对话场景则允许0.7以上。prompt模板的设计也有讲究。我习惯把prompt拆成四部分角色描述、输入数据、输出格式约束、附加规则。附加规则里明确写“不要输出list以外的字段”“内容超过X字时截断”这类机器可检查的约束。这样模板改动时可以准确定位不会因为一个业务规则变动而重写整个prompt。绝对不要做的事允许客户端直接传“system prompt”覆盖。很多人图省事让调用方把自定义指令拼进请求里结果就是技能行为完全不可控被人注入一段提示词后输出格式就崩了。我的做法是定义少量可覆盖的“参数化指令槽”比如output_style、tone但底层的角色和约束固定。这样既保留了灵活性又不至于让Skill变成一个谁都能改的裸奔prompt。3. 从零实现一个跨平台技能会议纪要整理全流程3.1 场景设定与需求拆解为了让整个流程更有实感我拿一个实际做过的功能举例会议纪要整理技能。需求来源是团队里每周都有大量例会语音转写文本少则几千字、多则几万字读一遍要十分钟整理纪要又要二十分钟。我们希望做一个Skill输入会议转写文本直接输出结构化纪要包含结论摘要、待办事项、风险点和时间线。最初的需求描述就一句话“帮我总结会议内容”。这句话信息量太小。我拆解之后明确了四个输出板块结论摘要全会的核心结论不超过300字待办事项每项待办包含负责人、截止时间、具体任务风险点讨论中暴露的风险或阻塞点时间线会议关键事件按时间顺序排列。这四类输出对应到业务侧的实际使用场景。摘要给管理层快速浏览待办下发给执行人风险点同步给项目组时间线用于回溯。需求拆到这个粒度Skill的输入输出契约就能定下来了也就是上一节那张注册表。3.2 输入预处理文本切片的实现逻辑大模型对单次输入长度有限制几万字的转写文本不能直接塞进去。所以这个Skill的第一步必须做文本切片。这里的核心不是死板地按字数切而是按语义边界切。我实现了一个简单的切片方法先把文本按标点符号切分成句子然后累计句子长度当累计长度接近预设阈值时优先在段落边界或语义完整处切开。这里有一个关键参数——切片重叠。如果完全无重叠相邻切片之间的语义关系会断裂影响后续汇总的质量。我通常设10%到15%的重叠比例让前后两个片段在衔接处有部分重复信息。下面是参考实现def chunk_text(text, max_chars8000, overlap_ratio0.1): sentences split_by_punctuation(text) chunks [] current [] current_len 0 for sentence in sentences: sentence_len len(sentence) if current_len sentence_len max_chars and current: chunk_text .join(current) chunks.append(chunk_text) overlap_len int(max_chars * overlap_ratio) current trim_tail_to_len(current, overlap_len) current_len sum(len(s) for s in current) current.append(sentence) current_len sentence_len if current: chunks.append(.join(current)) return chunks切片之后先让模型对每个切片生成独立摘要和要点再把所有切片的摘要汇总成一份最终纪要。这种“先分段总结再汇总”的流程比一次性塞入全部文本稳定得多也让输出信息密度更高。代价是Token开销会多出约20%但对纪要质量要求高的场景完全值得。3.3 模型调用封装与流式输出模型调用我走的是一个统一模型网关没有在Skill里直接写死某个SDK。这样切换模型版本、做降级方案都更灵活。Skill通过一个call_model函数向网关发送请求网关根据配置决定路由到哪个具体模型。对于长文本处理耗时通常超过30秒所以技能接口从一开始就支持SSE流式输出。流程是先返回一个事件流逐步推送“切片处理中”“汇总生成中”“完成”等阶段状态最后推送完整结果。这样做有三个实际好处第一移动端和Web端可以通过进度状态给用户反馈而不是干等第二IM机器人可以在超时前先回复一句“我正在处理预计需要一分钟”再异步推送结果第三服务端可以实时记录处理进度排查问题时不需要盲猜卡在哪个阶段。// 前端通过SSE接收技能执行状态 const source new EventSource(/api/skills/meeting_minutes/invoke?task_idabc123); source.onmessage (event) { const data JSON.parse(event.data); if (data.status complete) { renderMinutes(data.result); source.close(); } else { updateProgress(data.status); } };有一点值得提醒SSE在部分网络代理环境下会被缓冲导致客户端迟迟收不到事件。我在接入层对SSE响应加了显式的刷新头和禁止缓冲配置同时在客户端做兜底——如果连续15秒没有收到任何事件就自动切到轮询接口查询任务状态。这个兜底在移动端弱网环境下帮了大忙。3.4 技能注册与自动化验证实现完毕之后把Skill注册到注册中心同时写一份自动化验证集。验证集包含三类样本短文本、超长文本、空输入和异常输入。每次更新Skill后跑一遍验证集比较输出结构是否符合schema、关键信息是否丢失、处理耗时是否在预期范围内。这一步非常值得投入因为它能在多平台接入之前就把大部分回归问题挡在门外。我还加了一个快照对比机制把验证集的输出结果存下来下一次运行后自动对比关键字段的差异。模型输出天然有随机性所以对比不追求逐字一致而是检查结构完整性。一旦发现某个必填字段缺失或者出现非法枚举值就说明prompt或解析逻辑出了问题。4. 多平台接入的四种典型形态从Web到定时任务4.1 接入层的统一网关设计平台接入的第一步是搭建一个统一网关。这个网关做的事情看起来简单实际很容易做错它不只做请求转发还负责鉴权、参数校验、配额控制、请求日志。我在网关层为每个调用方生成一个trace_id整个链路上的日志都带着这个ID。多平台排查问题的时候请求日志一拉就能看到同一个任务从哪个平台进来、耗时多少、哪一步出错。网关对外暴露两类接口同步调用接口和异步任务接口。同步调用适合耗时短、用户在线等待的场景异步任务接口返回一个task_id适合处理耗时长、需要轮询或回调的场景。会议纪要这个Skill两类接口都需要所以我为它单独设计了“提交任务→查询进度→获取结果”的接口组合而不是简单只用同步POST。4.2 Web后台最标准但也最容易忽略超时Web后台的接入看起来是最简单的前端直接用AJAX或者Fetch调用网关即可。但有一个问题我一开始没注意部分Web服务器和网关的默认超时设置只有30秒而会议纪要处理经常超过这个时间。如果你用同步接口前端就会收到一个网关返回的超时错误但实际任务还在后端跑。解决办法有两种一种是用异步任务加轮询另一种是把同步接口的超时时间调大。我的建议是优先用异步任务模式因为同步长连接会占用网关的连接池高并发下容易拖垮整个网关。Web后台配合进度条展示任务状态体验反而更好。4.3 办公IM机器人格式转换是最大坑点办公IM机器人的接入是我踩坑最多的环节。表面上流程很清晰机器人收到消息→解析指令和参数→调用网关→把结果返回聊天窗口。但实际做的时候平台之间的富文本语法差异让我头疼了很久。有的平台用Markdown有的平台用私有标签还有的平台对消息长度有严格限制。给一个具体教训我在某个平台群里发会议纪要直接用了统一生成的Markdown表格结果在客户端里表格完全乱掉变成一行行挤在一起的文本。排查到最后发现那个平台要求表格必须用特定的卡片语法而且单条消息不能超过一个定长范围。解决方式是在表现层增加一个按平台注册的渲染器每个平台选择自己的渲染模板技能输出的JSON结构保持不变渲染完全隔离在表现层。IM场景还有一个特殊需求异步主动推送。用户提交任务后机器人先回复“已收到正在整理”处理完成后通过WEBHOOK或者主动消息接口把结果推送到聊天窗口。这个能力需要在接入层注册回调地址并保证回调消息能对应到原始会话。我建议在所有异步任务结果里都携带原始消息的ID这样即使回调延迟也不怕找不到上下文。4.4 移动端与小程序的轻量接入移动端和微信小程序的接入思路相似核心限制是网络环境不稳定、前后台切换频繁。我把移动端调用方式设计成发起异步任务→本地轮询或通过推送通知接收结果。移动端不做SSE长连接原因是公共Wi-Fi和运营商网关对长连接不友好断线恢复的成本比轮询高得多。我给移动端封装了一个轻量SDK核心只有三个函数提交任务、查询状态、获取结果。SDK内部自动处理token刷新和失败重试。重试策略用的是指数退避第一次失败等1秒第二次等2秒最多到10秒连续重试三次后放弃并明确提示用户检查网络。这套逻辑不复杂但很实用避免了一哄而上的重复请求打爆网关。还有一个细节移动端请求往往以用户的身份发起服务端需要根据用户身份做权限控制。我在网关层把用户身份和Skill的授权绑定确保用户只能调用他有权限的技能。这个在Web端也许无所谓但移动端一旦放开很容易出现越权调用的问题。4.5 定时任务把技能当成命令行工具最后一类平台是定时任务。比如每天早上九点自动总结昨天所有未读会议。定时任务其实是最简单的接入方式因为不需要交互界面。我写了一个命令行工具直接传递JSON参数调用技能接口把结果写入指定文档或数据库。特殊之处在于定时任务对输出格式的稳定性要求极高因为后续管道程序要解析结果。我把定时任务的调用参数固定设置成低temperature、严格schema校验并且关闭所有自由发挥的选项。同时增加了失败重试和告警如果技能连续三次调用失败就发一条告警到运维群。不要觉得这是小题大做——定时任务失败往往意味着一批数据缺失越早发现损失越小。5. 踩坑实录跨平台技能的五个高频问题与排查思路5.1 问题速查表我把这个项目里遇到的典型问题整理成了速查表方便直接对照排查问题现象可能根因排查方法解决建议同一技能在Web正常在机器人里输出乱码平台富文本渲染语法不兼容对比原始JSON输出和平台渲染后文本按平台注册独立渲染模板移动端请求频繁中断技能结果丢失异步任务状态没有持久化查看任务表中task状态变迁任务状态落库支持断点续查长文本输入偶尔触发网关超时同步接口连接占用过长查看网关超时设置和后端耗时统计切换到异步任务轮询模式定时任务产出格式不稳定temperature过高或prompt约束不足对比多批次输出结构完整率压低temperature加强输出schema校验某个平台占用全部技能调用配额缺少分平台限流查看网关访问日志平台分布按平台维度设置独立配额与优先级5.2 三个印象深刻的实战复盘第一个印象深刻的问题是IM平台的换行吞掉事件。现象是长文本纪要发送到聊天窗口后所有换行符消失整个内容揉成一大团。排查发现不是技能的问题是平台在渲染时对连续换行的处理规则不同。解决方式是针对该平台把结构化输出改成卡片式分段渲染而不是单条长文本。这个问题的教训很简单越是看起来“应该通用”的文本格式越要在每个平台上实测渲染效果。第二个问题是移动端弱网环境下SSE流被运营商网关缓冲了整整四十秒用户那边完全看不到任何进度。后来我增加了客户端15秒事件监听兜底一旦发现长时间没有消息就切轮询。这个案例告诉我们技术方案的取舍要结合真实网络环境不能只看实验室状态。第三个问题比较隐蔽某天定时任务忽然大量失败查了半天发现是有人在另一个平台上手动调用了大量高耗时技能把模型网关的并发配额耗尽了。定时任务这种“夜间管道”优先级不高直接被排队超时。解决方式是给网关加上按平台和按时段的双层配额控制定时任务使用独立配额池确保核心管道不受突发流量影响。5.3 关于稳定性的三条心得经过这些实战我沉淀出三条稳定性经验。第一所有Skill调用必须记录trace_id并且日志里包含输入长度、耗时、输出结构校验结果。这套日志体系在问题排查时远比看代码高效因为多平台问题往往不是逻辑错误而是环境差异。第二输出结构必须做硬性校验。即使模型返回的字段不全也要由接入层补全成一个合法结构缺失字段用空值或者错误码代替而不是让异常直接抛出。这样上游组件不会因为字段缺失整个崩溃。第三任何新平台接入之前先做一次“最小可用链路”验证。只跑一个最简单的技能比如输入一句话返回一句话确认整条链路通了之后再接入复杂技能。这能避免把平台适配问题和技能逻辑问题混在一起排查。6. 往后怎么走技能组合、内部技能市场与成本优化6.1 从单个技能到技能编排当技能数量多起来之后下一个自然的方向是技能编排。比如一个“智能会议助理”流程需要会议纪要技能、待办提取技能、风险提醒技能按顺序配合。编排层可以简单做成一个工作流定义文件声明每一步调用哪个Skill、输入输出如何衔接。我建议编排结果本身也应该是一个“技能”它拥有自己的输入输出契约内部调用底层技能。这样对上层完全透明比如我编排了一个“周报自动生成”技能内部调用会议纪要、任务统计、日报汇总三个技能但调用方只需要传一个时间范围拿到的就是完整周报。这种递归分层让能力复用的粒度可以一直往上生长。6.2 内部技能市场与可观测性技能数量达到几十个之后团队内部需要一个技能市场来管理。每个技能有独立的版本号、维护人、调用量统计和健康状态检查。这个市场不一定要做得特别复杂一个支持检索和查看详情的内部管理界面就够了。核心是强制所有技能经过注册才能被调用避免有人绕过网关直接调用底层模型。可观测性三件套要配齐日志用于排查单次调用问题指标用于监控技能成功率和耗时趋势链路追踪用于分析一次编排调用涉及哪些技能。我特别推荐关注两个指标p95耗时和输出结构校验失败率。前者反映用户体验后者直接对应模型输出质量。只要这两个指标稳定技能整体就不会出大问题。6.3 成本与性能的优化空间Skill架构还有一个隐形优势成本优化可以按技能粒度做。会议纪要这种高Token消耗技能可以优先使用高性价比模型而意图识别这种简单技能用小模型就能跑得很好。在模型网关层配置好每个Skill可接受的模型范围并支持按调用方区分就能在成本和效果之间做精细平衡。另外一个实用优化是结果缓存。对于相同输入、相同参数、版本未变化的调用直接返回缓存结果。我发现会议纪要这种技能同一个会议转写文本经常被多个人重复调用缓存命中率能到三成以上。缓存的key设计很简单就是技能名加参数哈希。缓存时注意设置合理的失效时间避免模型升级后旧版本结果一直在被用到。最后是流式处理和并行切片的优化空间。切片之间相互独立可以并行调用模型网关减少总体耗时。我在实际项目中把串行切片汇总改成了并行处理再统一汇总会议纪要技能的整体耗时从近一分钟降到了三十秒左右体感提升非常明显。并行度设置需要根据模型网关的并发配额来定一般控制在2到3个并行请求比较稳妥。关于这个项目我个人最大的体会是Agent项目烂尾的常见原因往往不是模型能力不够而是能力单元没有边界。如果你一开始就追求“一个智能体干所有事”那后期每个平台都要维护一坨自动化程度很高但没人敢动的代码。先把一个技能做到能跨平台稳定运行再考虑编排和组合这条路跑起来会顺很多。另外有个小技巧分享给准备动手的人每个Skill的输出结构里都加一个status字段成功是success失败就返回结构化的错误码和原因。这个字段能让你在多平台排查时少浪费大量时间因为上层渠道只需要按状态字段做展示分支不需要自己try catch解析各种异常文本。
这段时间我在推进“闪学it”的Agent Skills多平台应用实战项目核心目标就一句话让同一套AI能力拆成独立的技能单元在Web后台、办公IM机器人、移动端和定时任务里都能稳定跑起来。做过这类事的人应该都有体会单独写一个Agent Demo不难难的是当你发现Web端要一个结果、机器人要一段富文本、移动端要一个流式返回的时候同一个逻辑被迫复制了三份prompt各改各的工具配置越来越乱。这篇文章我会把整个拆解过程和实操路径完整讲清楚适合那些已经把Agent跑通但想上多平台、又不想被维护成本拖死的开发者参考。1. 为什么Agent项目必须拆成Skills一次多平台重构的复盘1.1 单体Agent在多平台场景下的失控过程先说一个我踩过的典型场景。最初我做了一个完整的Agent应用把大模型对话、上下文记忆、工具调用、权限判断全揉在一起接在办公IM机器人上。当时想得很简单用户发消息Agent自动理解意图调用工具返回回答。单平台跑通之后需求立刻来了——管理后台要一个操作界面移动端要一个快捷入口日报定时任务还要自动汇总信息。这时候问题全部浮出来了。首先是状态管理IM机器人的对话上下文和Web页面里的会话上下文根本不是一回事强行复用导致同一个用户在两边的记忆互相错乱。其次是prompt膨胀为了适配不同的输入格式和输出要求我在同一个Agent里堆满了条件分支最终那段system prompt超过两千字改动一处就牵一发动全身。最要命的是工具调用有些平台需要异步回调有些平台只接受同步返回单体Agent根本没法对不同平台分别处理超时和重试。复盘下来问题的根源不是模型不行而是能力单元的粒度错了。一个完整的Agent是“带状态的对话系统”但Web按钮、机器人指令、定时任务根本不需要对话状态它们需要的是“把一段输入变成一段输出”的确定性能力。如果把这些能力从Agent里剥离出来各自定义好输入输出再让不同平台去调用维护复杂度会断崖式下降。这就是我决定把项目重心转向Agent Skills的原因。1.2 Skills的定义与生活化类比Agent Skills的核心思想是把Agent具备的某种能力封装成一个独立的、可复用的、声明式描述的技能单元。一个Skill不关心调用方是聊天窗口还是HTTP接口它只接收标准化的输入参数执行内部逻辑返回标准化的输出结果。说得直白一点一个Skill有点像“函数”但它比普通函数的边界更严格——不仅要有清晰的入参出参还要有对应的自然语言描述、参数校验规则、超时策略和运行配置。用一个生活化的类比来理解做一桌菜需要菜谱菜谱是完整的应用流程它规定了先做什么后做什么、放多少盐、焖几分钟但刀工、火候控制、酱汁调制这些基本功是可以独立存在的技能。你换了餐厅、换了菜单这些基本功照样能用。Agent项目同理完整流程可能因平台而异但“文本摘要”“关键字提取”“意图识别”“数据查询”这些基本功应该沉淀成Skills在任何平台都能被直接调用。这个思路带来的直接好处是开发模式从“每个平台单独做一个Agent”变成了“先建设技能库再在各个平台调用技能”。当有新平台要接入时不需要重写Agent逻辑只需要做适配层把平台的输入格式转成技能标准参数再把技能输出转成平台展示格式。1.3 三层架构技能层、接入层、表现层实际操作时我把整个系统分成了三层这个分层对控制复杂度非常关键。技能层Skill Layer所有Skills的注册与实现完全平台无关只处理业务逻辑。接入层Bridge Layer统一的调用入口负责鉴权、参数校验、路由分发以HTTP/SSE接口对外暴露。表现层Channel Layer面向具体平台的适配器把平台的消息格式解析成技能参数再把技能结果渲染成平台支持的格式。之所以把平台差异隔离在表现层是因为平台差异主要集中在消息格式、渲染语法、回调方式、超时限制这些“外围”属性上。技能层一旦被平台细节污染复用性就没了。所以我在项目里立了一条规矩技能层代码里不允许出现任何平台关键字连“IM”“小程序”“Web”这样的词都不准出现在业务逻辑里。接入层选择HTTP/SSE而不是重型RPC框架原因很简单技能调用需要兼容的客户端形态太多了浏览器、机器人服务器、移动端SDK、脚本工具HTTP是最通用的协议。流式返回用SSE处理可以解决长耗时任务在部分平台上的等待超时问题。这套分层方案经受住了后续多个渠道的接入考验是目前我觉得最稳妥的起点。2. 技能定义与运行机制把“会做什么”变成机器可读的契约2.1 技能注册表为什么用JSON Schema做契约技能要能跨平台复用第一步就是把它描述清楚。我参照软件接口设计的原则为每个Skill定义了一份注册清单用JSON Schema描述输入输出。这样无论是人工查看还是让代码做自动化校验都能基于同一份契约。下面是一份技能注册表的示例我把关键字段都写了注释{ skill_name: meeting_minutes, version: 1.2.0, description: 将会议语音转写文本整理为结构化会议纪要, input_schema: { type: object, properties: { transcript: { type: string, description: 会议转写的纯文本内容, maxLength: 200000 }, language: { type: string, enum: [zh, en], default: zh }, include_action_items: { type: boolean, default: true } }, required: [transcript] }, output_schema: { type: object, properties: { summary: { type: string }, action_items: { type: array, items: { type: string } }, risks: { type: array, items: { type: string } }, timeline: { type: array, items: { type: object } } }, required: [summary, action_items, risks, timeline] }, timeout_ms: 30000, is_streamable: true, capabilities: [text_chunking, semantic_analysis] }每个字段都不是随意设计的。timeout_ms看起来只是数字但它直接影响多平台体验Web端用户可以接受等待IM机器人如果超过响应时限可能会直接报错移动端弱网环境下就更敏感。is_streamable对应是否支持SSE流式返回不支持流式的Skill在IM和移动端会被迫使用等待轮询方案体验差距很大。input_schema里的maxLength也重要大模型接口通常有Token上限提前在契约层声明比在调用端报错要友好得多。还有一点需要特别注意注册表的description不要写得含糊比如“处理会议文本”这种描述就没有意义。要写清楚这个Skill适合什么输入、不适合什么输入、输出中的字段各代表什么含义。因为这个描述不仅给人看也会被上游的意图识别模块使用。描述不好后续做技能组合时路由就会出错。2.2 运行上下文Skill不记忆、不感知用户这是整个项目里最反直觉也最重要的一条原则Skill不应该维护对话历史也不该感知用户的身份和会话状态。它就像一个公开的API函数你给我参数我还你结果不带任何记忆。一旦Skill内部悄悄记住了“上次的调用结果”跨平台复用就彻底完蛋了。我见过一个团队踩了坑他们在技能内部缓存了用户的上一轮输入希望实现“上下文自动连接”的效果。结果同一个用户在Web上问过的问题跑到IM机器人那边再次触发同一技能时返回了完全无关的内容。原因是Web端和IM端的会话状态没有共享Skill内部自以为是地“补全”了上下文。所以我的铁律是所有上下文信息必须显式作为参数传入SkillSkill自身保持无状态。需要多轮对话那是Agent编排层的事不是Skill的事。无状态设计的另一个好处是便于缓存和并发控制。相同输入可以安全地复用缓存结果不需要担心不同用户之间的数据串扰。并发请求也只需要按Skill维度做限流不需要按用户会话加锁。2.3 Prompt与模型参数的管理策略Skills跑在模型之上prompt和模型参数的管理直接影响输出质量。我的做法是prompt模板内嵌在Skill里作为技能的默认配置但调用方可以通过参数临时覆盖部分内容比如输出语言、语气风格等。模型参数如temperature、max_tokens则放在调用层控制。为什么这样拆分因为不同平台对输出要求的严格程度差异很大。Web后台可以接受模型自由发挥富有个性的表述反而加分但定时任务生成的报表如果格式不稳定下游脚本解析就直接失败。所以我在定时任务调用Skill时会把temperature压到0.2左右在IM对话场景则允许0.7以上。prompt模板的设计也有讲究。我习惯把prompt拆成四部分角色描述、输入数据、输出格式约束、附加规则。附加规则里明确写“不要输出list以外的字段”“内容超过X字时截断”这类机器可检查的约束。这样模板改动时可以准确定位不会因为一个业务规则变动而重写整个prompt。绝对不要做的事允许客户端直接传“system prompt”覆盖。很多人图省事让调用方把自定义指令拼进请求里结果就是技能行为完全不可控被人注入一段提示词后输出格式就崩了。我的做法是定义少量可覆盖的“参数化指令槽”比如output_style、tone但底层的角色和约束固定。这样既保留了灵活性又不至于让Skill变成一个谁都能改的裸奔prompt。3. 从零实现一个跨平台技能会议纪要整理全流程3.1 场景设定与需求拆解为了让整个流程更有实感我拿一个实际做过的功能举例会议纪要整理技能。需求来源是团队里每周都有大量例会语音转写文本少则几千字、多则几万字读一遍要十分钟整理纪要又要二十分钟。我们希望做一个Skill输入会议转写文本直接输出结构化纪要包含结论摘要、待办事项、风险点和时间线。最初的需求描述就一句话“帮我总结会议内容”。这句话信息量太小。我拆解之后明确了四个输出板块结论摘要全会的核心结论不超过300字待办事项每项待办包含负责人、截止时间、具体任务风险点讨论中暴露的风险或阻塞点时间线会议关键事件按时间顺序排列。这四类输出对应到业务侧的实际使用场景。摘要给管理层快速浏览待办下发给执行人风险点同步给项目组时间线用于回溯。需求拆到这个粒度Skill的输入输出契约就能定下来了也就是上一节那张注册表。3.2 输入预处理文本切片的实现逻辑大模型对单次输入长度有限制几万字的转写文本不能直接塞进去。所以这个Skill的第一步必须做文本切片。这里的核心不是死板地按字数切而是按语义边界切。我实现了一个简单的切片方法先把文本按标点符号切分成句子然后累计句子长度当累计长度接近预设阈值时优先在段落边界或语义完整处切开。这里有一个关键参数——切片重叠。如果完全无重叠相邻切片之间的语义关系会断裂影响后续汇总的质量。我通常设10%到15%的重叠比例让前后两个片段在衔接处有部分重复信息。下面是参考实现def chunk_text(text, max_chars8000, overlap_ratio0.1): sentences split_by_punctuation(text) chunks [] current [] current_len 0 for sentence in sentences: sentence_len len(sentence) if current_len sentence_len max_chars and current: chunk_text .join(current) chunks.append(chunk_text) overlap_len int(max_chars * overlap_ratio) current trim_tail_to_len(current, overlap_len) current_len sum(len(s) for s in current) current.append(sentence) current_len sentence_len if current: chunks.append(.join(current)) return chunks切片之后先让模型对每个切片生成独立摘要和要点再把所有切片的摘要汇总成一份最终纪要。这种“先分段总结再汇总”的流程比一次性塞入全部文本稳定得多也让输出信息密度更高。代价是Token开销会多出约20%但对纪要质量要求高的场景完全值得。3.3 模型调用封装与流式输出模型调用我走的是一个统一模型网关没有在Skill里直接写死某个SDK。这样切换模型版本、做降级方案都更灵活。Skill通过一个call_model函数向网关发送请求网关根据配置决定路由到哪个具体模型。对于长文本处理耗时通常超过30秒所以技能接口从一开始就支持SSE流式输出。流程是先返回一个事件流逐步推送“切片处理中”“汇总生成中”“完成”等阶段状态最后推送完整结果。这样做有三个实际好处第一移动端和Web端可以通过进度状态给用户反馈而不是干等第二IM机器人可以在超时前先回复一句“我正在处理预计需要一分钟”再异步推送结果第三服务端可以实时记录处理进度排查问题时不需要盲猜卡在哪个阶段。// 前端通过SSE接收技能执行状态 const source new EventSource(/api/skills/meeting_minutes/invoke?task_idabc123); source.onmessage (event) { const data JSON.parse(event.data); if (data.status complete) { renderMinutes(data.result); source.close(); } else { updateProgress(data.status); } };有一点值得提醒SSE在部分网络代理环境下会被缓冲导致客户端迟迟收不到事件。我在接入层对SSE响应加了显式的刷新头和禁止缓冲配置同时在客户端做兜底——如果连续15秒没有收到任何事件就自动切到轮询接口查询任务状态。这个兜底在移动端弱网环境下帮了大忙。3.4 技能注册与自动化验证实现完毕之后把Skill注册到注册中心同时写一份自动化验证集。验证集包含三类样本短文本、超长文本、空输入和异常输入。每次更新Skill后跑一遍验证集比较输出结构是否符合schema、关键信息是否丢失、处理耗时是否在预期范围内。这一步非常值得投入因为它能在多平台接入之前就把大部分回归问题挡在门外。我还加了一个快照对比机制把验证集的输出结果存下来下一次运行后自动对比关键字段的差异。模型输出天然有随机性所以对比不追求逐字一致而是检查结构完整性。一旦发现某个必填字段缺失或者出现非法枚举值就说明prompt或解析逻辑出了问题。4. 多平台接入的四种典型形态从Web到定时任务4.1 接入层的统一网关设计平台接入的第一步是搭建一个统一网关。这个网关做的事情看起来简单实际很容易做错它不只做请求转发还负责鉴权、参数校验、配额控制、请求日志。我在网关层为每个调用方生成一个trace_id整个链路上的日志都带着这个ID。多平台排查问题的时候请求日志一拉就能看到同一个任务从哪个平台进来、耗时多少、哪一步出错。网关对外暴露两类接口同步调用接口和异步任务接口。同步调用适合耗时短、用户在线等待的场景异步任务接口返回一个task_id适合处理耗时长、需要轮询或回调的场景。会议纪要这个Skill两类接口都需要所以我为它单独设计了“提交任务→查询进度→获取结果”的接口组合而不是简单只用同步POST。4.2 Web后台最标准但也最容易忽略超时Web后台的接入看起来是最简单的前端直接用AJAX或者Fetch调用网关即可。但有一个问题我一开始没注意部分Web服务器和网关的默认超时设置只有30秒而会议纪要处理经常超过这个时间。如果你用同步接口前端就会收到一个网关返回的超时错误但实际任务还在后端跑。解决办法有两种一种是用异步任务加轮询另一种是把同步接口的超时时间调大。我的建议是优先用异步任务模式因为同步长连接会占用网关的连接池高并发下容易拖垮整个网关。Web后台配合进度条展示任务状态体验反而更好。4.3 办公IM机器人格式转换是最大坑点办公IM机器人的接入是我踩坑最多的环节。表面上流程很清晰机器人收到消息→解析指令和参数→调用网关→把结果返回聊天窗口。但实际做的时候平台之间的富文本语法差异让我头疼了很久。有的平台用Markdown有的平台用私有标签还有的平台对消息长度有严格限制。给一个具体教训我在某个平台群里发会议纪要直接用了统一生成的Markdown表格结果在客户端里表格完全乱掉变成一行行挤在一起的文本。排查到最后发现那个平台要求表格必须用特定的卡片语法而且单条消息不能超过一个定长范围。解决方式是在表现层增加一个按平台注册的渲染器每个平台选择自己的渲染模板技能输出的JSON结构保持不变渲染完全隔离在表现层。IM场景还有一个特殊需求异步主动推送。用户提交任务后机器人先回复“已收到正在整理”处理完成后通过WEBHOOK或者主动消息接口把结果推送到聊天窗口。这个能力需要在接入层注册回调地址并保证回调消息能对应到原始会话。我建议在所有异步任务结果里都携带原始消息的ID这样即使回调延迟也不怕找不到上下文。4.4 移动端与小程序的轻量接入移动端和微信小程序的接入思路相似核心限制是网络环境不稳定、前后台切换频繁。我把移动端调用方式设计成发起异步任务→本地轮询或通过推送通知接收结果。移动端不做SSE长连接原因是公共Wi-Fi和运营商网关对长连接不友好断线恢复的成本比轮询高得多。我给移动端封装了一个轻量SDK核心只有三个函数提交任务、查询状态、获取结果。SDK内部自动处理token刷新和失败重试。重试策略用的是指数退避第一次失败等1秒第二次等2秒最多到10秒连续重试三次后放弃并明确提示用户检查网络。这套逻辑不复杂但很实用避免了一哄而上的重复请求打爆网关。还有一个细节移动端请求往往以用户的身份发起服务端需要根据用户身份做权限控制。我在网关层把用户身份和Skill的授权绑定确保用户只能调用他有权限的技能。这个在Web端也许无所谓但移动端一旦放开很容易出现越权调用的问题。4.5 定时任务把技能当成命令行工具最后一类平台是定时任务。比如每天早上九点自动总结昨天所有未读会议。定时任务其实是最简单的接入方式因为不需要交互界面。我写了一个命令行工具直接传递JSON参数调用技能接口把结果写入指定文档或数据库。特殊之处在于定时任务对输出格式的稳定性要求极高因为后续管道程序要解析结果。我把定时任务的调用参数固定设置成低temperature、严格schema校验并且关闭所有自由发挥的选项。同时增加了失败重试和告警如果技能连续三次调用失败就发一条告警到运维群。不要觉得这是小题大做——定时任务失败往往意味着一批数据缺失越早发现损失越小。5. 踩坑实录跨平台技能的五个高频问题与排查思路5.1 问题速查表我把这个项目里遇到的典型问题整理成了速查表方便直接对照排查问题现象可能根因排查方法解决建议同一技能在Web正常在机器人里输出乱码平台富文本渲染语法不兼容对比原始JSON输出和平台渲染后文本按平台注册独立渲染模板移动端请求频繁中断技能结果丢失异步任务状态没有持久化查看任务表中task状态变迁任务状态落库支持断点续查长文本输入偶尔触发网关超时同步接口连接占用过长查看网关超时设置和后端耗时统计切换到异步任务轮询模式定时任务产出格式不稳定temperature过高或prompt约束不足对比多批次输出结构完整率压低temperature加强输出schema校验某个平台占用全部技能调用配额缺少分平台限流查看网关访问日志平台分布按平台维度设置独立配额与优先级5.2 三个印象深刻的实战复盘第一个印象深刻的问题是IM平台的换行吞掉事件。现象是长文本纪要发送到聊天窗口后所有换行符消失整个内容揉成一大团。排查发现不是技能的问题是平台在渲染时对连续换行的处理规则不同。解决方式是针对该平台把结构化输出改成卡片式分段渲染而不是单条长文本。这个问题的教训很简单越是看起来“应该通用”的文本格式越要在每个平台上实测渲染效果。第二个问题是移动端弱网环境下SSE流被运营商网关缓冲了整整四十秒用户那边完全看不到任何进度。后来我增加了客户端15秒事件监听兜底一旦发现长时间没有消息就切轮询。这个案例告诉我们技术方案的取舍要结合真实网络环境不能只看实验室状态。第三个问题比较隐蔽某天定时任务忽然大量失败查了半天发现是有人在另一个平台上手动调用了大量高耗时技能把模型网关的并发配额耗尽了。定时任务这种“夜间管道”优先级不高直接被排队超时。解决方式是给网关加上按平台和按时段的双层配额控制定时任务使用独立配额池确保核心管道不受突发流量影响。5.3 关于稳定性的三条心得经过这些实战我沉淀出三条稳定性经验。第一所有Skill调用必须记录trace_id并且日志里包含输入长度、耗时、输出结构校验结果。这套日志体系在问题排查时远比看代码高效因为多平台问题往往不是逻辑错误而是环境差异。第二输出结构必须做硬性校验。即使模型返回的字段不全也要由接入层补全成一个合法结构缺失字段用空值或者错误码代替而不是让异常直接抛出。这样上游组件不会因为字段缺失整个崩溃。第三任何新平台接入之前先做一次“最小可用链路”验证。只跑一个最简单的技能比如输入一句话返回一句话确认整条链路通了之后再接入复杂技能。这能避免把平台适配问题和技能逻辑问题混在一起排查。6. 往后怎么走技能组合、内部技能市场与成本优化6.1 从单个技能到技能编排当技能数量多起来之后下一个自然的方向是技能编排。比如一个“智能会议助理”流程需要会议纪要技能、待办提取技能、风险提醒技能按顺序配合。编排层可以简单做成一个工作流定义文件声明每一步调用哪个Skill、输入输出如何衔接。我建议编排结果本身也应该是一个“技能”它拥有自己的输入输出契约内部调用底层技能。这样对上层完全透明比如我编排了一个“周报自动生成”技能内部调用会议纪要、任务统计、日报汇总三个技能但调用方只需要传一个时间范围拿到的就是完整周报。这种递归分层让能力复用的粒度可以一直往上生长。6.2 内部技能市场与可观测性技能数量达到几十个之后团队内部需要一个技能市场来管理。每个技能有独立的版本号、维护人、调用量统计和健康状态检查。这个市场不一定要做得特别复杂一个支持检索和查看详情的内部管理界面就够了。核心是强制所有技能经过注册才能被调用避免有人绕过网关直接调用底层模型。可观测性三件套要配齐日志用于排查单次调用问题指标用于监控技能成功率和耗时趋势链路追踪用于分析一次编排调用涉及哪些技能。我特别推荐关注两个指标p95耗时和输出结构校验失败率。前者反映用户体验后者直接对应模型输出质量。只要这两个指标稳定技能整体就不会出大问题。6.3 成本与性能的优化空间Skill架构还有一个隐形优势成本优化可以按技能粒度做。会议纪要这种高Token消耗技能可以优先使用高性价比模型而意图识别这种简单技能用小模型就能跑得很好。在模型网关层配置好每个Skill可接受的模型范围并支持按调用方区分就能在成本和效果之间做精细平衡。另外一个实用优化是结果缓存。对于相同输入、相同参数、版本未变化的调用直接返回缓存结果。我发现会议纪要这种技能同一个会议转写文本经常被多个人重复调用缓存命中率能到三成以上。缓存的key设计很简单就是技能名加参数哈希。缓存时注意设置合理的失效时间避免模型升级后旧版本结果一直在被用到。最后是流式处理和并行切片的优化空间。切片之间相互独立可以并行调用模型网关减少总体耗时。我在实际项目中把串行切片汇总改成了并行处理再统一汇总会议纪要技能的整体耗时从近一分钟降到了三十秒左右体感提升非常明显。并行度设置需要根据模型网关的并发配额来定一般控制在2到3个并行请求比较稳妥。关于这个项目我个人最大的体会是Agent项目烂尾的常见原因往往不是模型能力不够而是能力单元没有边界。如果你一开始就追求“一个智能体干所有事”那后期每个平台都要维护一坨自动化程度很高但没人敢动的代码。先把一个技能做到能跨平台稳定运行再考虑编排和组合这条路跑起来会顺很多。另外有个小技巧分享给准备动手的人每个Skill的输出结构里都加一个status字段成功是success失败就返回结构化的错误码和原因。这个字段能让你在多平台排查时少浪费大量时间因为上层渠道只需要按状态字段做展示分支不需要自己try catch解析各种异常文本。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
