从本地到云端：AI Agent Skill开发实战与避坑总结

大概三个月前我在本地把第一个 Skill 跑通的时候以为最难的部分已经结束了。结果真正开始往云端迁移的那一周才体会到“能跑”和“能稳定跑”之间差得有多远。这篇就来复盘这段从本地实操到云端落地的 Skill 开发实践聊聊选型判断、本地调试踩过的坑、上云前必须改的清单以及我对 Skill 这件事的认知深化。如果你正在做 Agent 应用准备把一个本地验证过的能力模块搬到云端这篇应该能帮你少走不少弯路。1. 为什么需要 Skill把“会聊天”变成“能交付的模块”1.1 一次很典型的“对话完成不了任务”现场先说我们最初遇到的真实问题。团队一直在做 Agent 应用早期习惯是给大模型写很长的一段系统指令然后在对话里直接丢一段客户反馈原文让它“提取要点、判断类别、生成工单描述”。听起来没什么问题但实际用起来全是毛病。首先是每次对话的指令都得重新强调一遍换个场景就漏掉某条规则。其次是上下文互相污染上一轮聊天记录里如果出现了“按之前的格式来”下一轮输出格式就可能变样。最要命的是输出质量不稳定同样一段文本有时候返回 JSON有时候返回 Markdown还有一次直接在最前面多了一句“好的我来帮你分析这段文档”。这其实就是典型的“裸对话完成任务”的瓶颈模型的泛化能力很强但业务逻辑没有固化。后来我们开始把这类任务封装成 Skill本质上是把一段业务流程、一组参数约束、一份提示词、一段工具调用代码打包成一个可以被 Agent 按需调用的模块。实际跑下来以后输出稳定性明显提升下游解析代码也不用天天改正则了。1.2 Skill 到底封装了什么我之前跟朋友解释 Skill用的类比是“料理包”。你可以把大模型想象成一个厨师厨艺很好但每次做菜前都得重新翻菜谱、找食材、挑厨具。Skill 的作用就是把菜谱、处理好的食材、专用厨具打包成一盒半成品料理包。Agent 看到这份料理包的描述之后只要判断“这个场景适不适用”适用就直接拆包下锅不用每次从零开始准备。具体到实现层面一个 Skill 通常包含这几个部分一个机器可读的描述文件里面写了 Skill 叫什么、能干什么、输入参数有哪些、输出结构是什么一份提示词模板定义了模型在处理输入时应该遵守的规则一个处理函数做参数校验、文本预处理、调用外部工具、组织返回结果可能还有一组辅助代码比如分块工具、缓存逻辑、第三方 API 的封装。这里有个顺序容易搞反Skill 的开发重点不是“提示词写得多华丽”而是“接口边界是否清晰”。提示词决定效果上限接口设计决定这个 Skill 能不能被别人复用、能不能稳定上线。这也是后边我们会反复提到的一条主线。1.3 什么情况下才值得开发 Skill不是所有任务都值得做成 Skill。给模型说一句“把这句翻译成英文”直接写在指令里就够了。真正适合做 Skill 的任务我总结有三个特征。第一是重复发生同一个任务每周、每天都会出现不是一次性问答。第二是输入输出可以结构化定义输入有明确的参数边界比如“一段文档 最多提取多少条要点”输出也有固定的格式要求。第三是任务内部有复杂的处理链不是一次模型调用就能完成需要分块、合并、校验、调用外部服务这些步骤。如果一条任务连输入参数都说不清楚那先别急着上 Skill说明业务需求还没想明白。我们当时把客户反馈长文本处理做成 Skill就是因为这三个条件都满足每天几百条反馈输入输出边界清楚而且需要做分块提取和去重合并不是一句指令能搞定的。2. 本地开发实操从空白目录到一个可运行 Skill2.1 Skill 的最小目录骨架当时我们做的是一个叫 doc_distiller 的 Skill功能是“从长文档中提取结构化要点按主题去重合并输出摘要与关键点列表”。这个场景选得很合适因为它的处理链足够有代表性。先看目录结构doc_distiller/ ├── manifest.yaml ├── prompt.md ├── handler.py └── requirements.txt四个文件职责分得很清楚。manifest.yaml 给 Agent 框架看的这个 Skill 叫什么、在什么场景下应该被调用、参数怎么定义。prompt.md 给模型看的拿到输入之后按什么规则整理。handler.py 给自己看的输入校验、预处理、后处理、外部调用都写在这儿。requirements.txt 负责把依赖钉死后边上云全靠它。我写 manifest 的时候有一个教训description 字段不能写得太抽象也不能写得太宽。最开始我写的是“处理文档并提取信息”Agent 会在一些完全不相关的场景下把它调出来比如用户问“帮我写个周报总结”也会触发它。后来改成“从客户反馈、会议纪要等长文中提取核心要点按主题去重合并生成摘要与关键点列表适用于需要结构化整理长文本的场景”命中率立刻上来了。描述写得太窄则相反该用的时候 Agent 不敢用。这个分寸需要反复调。name: doc_distiller description: 从长文档中提取结构化要点按主题去重合并输出摘要与关键点列表。适用于客户反馈分析、会议纪要整理、长文阅读等场景。 version: 1.0.0 inputs: - name: document type: string required: true description: 原始文档内容建议不超过 30000 字符 - name: max_points type: integer required: false default: 10 description: 最多输出多少条核心要点 - name: output_style type: string required: false enum: [concise, detailed] default: concise description: concise 输出一句话要点detailed 输出带原文依据的要点 outputs: type: object properties: summary: type: string key_points: type: array items: type: object properties: title: type: string detail: type: string required: [title, detail] open_issues: type: array items: type: string description: 文档中存在的矛盾信息或未决问题2.2 让 Agent 真正用上 Skill 的最小闭环在本地把 Skill“跑起来”这件事很多新手会误以为只要把目录建好就算完成了。真正的跑通要满足一个闭环构造一个输入样本让 Agent 在正确场景下调用这个 SkillSkill 返回结构化结果模型基于结果完成最终回答。我当时的验证方式是写一个本地调试脚本直接调框架的本地运行器import json from local_runner import LocalRunner runner LocalRunner(skill_path./doc_distiller) result runner.run({ document: sample_doc, max_points: 10, output_style: concise, }) print(json.dumps(result, ensure_asciiFalse, indent2))第一次跑的时候框架报了“input.validation_failed”原因是 manifest 里把 max_points 定义成 integer但调试脚本里传的是字符串 10。这个细节提醒了我一件事本地跑通 Skill 的验收标准不只是“模型明白了”还包括“参数完全匹配”。Agent 框架在决定调用 Skill 的时候会根据用户输入自动生成参数如果参数校验没做好后续所有的质量保证都是空中楼阁。2.3 输出规范从一开始就定好 schema输出规范这件事我建议在写第一版 prompt 之前就定下来而不是跑通了再补。原因很简单模型的输出格式如果没有强约束它会按它的“习惯”自由发挥。可能这轮输出全字段都有下一轮少了一个嵌套层级下游解析代码就得写各种兼容分支。我们在 doc_distiller 里把输出结构固化成 summary、key_points、open_issues 三个部分。key_points 内部又分 title 和 detailtitle 是一句话概括detail 是展开说明。这样的设计有一个好处既方便人看也方便下游程序直接把 key_points 里的 title 全部抓出来生成工单标题。为了让模型稳定输出这个结构prompt.md 里的规则要写得很死板。我摘两句给你们感受一下你必须输出合法 JSON 对象包含 summary、key_points、open_issues 三个字段不得输出任何额外说明文字。key_points 数量不得超过用户传入的 max_points 参数值。当原文存在矛盾信息时将矛盾双方各自写入 open_issues不要擅自判断谁对谁错。写清楚这些规则以后本地调试的通过率高了不少也不再出现“模型在前边加了一段解释文字”这类情况。3. 本地调试踩过的三个坑上下文、参数边界与效果评估3.1 大文档输入导致的“要点漂移”第一个坑出现在输入比较长的时候。doc_distiller 设计的应用场景是处理客户反馈长文一篇下来可能几千字甚至上万字。一开始我直接把整篇文档丢给模型输出结果看着还行但仔细对照原文就发现问题了模型归纳的要点偏向文档开头和结尾中间部分经常被“概括性错误”覆盖或者直接丢失一整段的重要信息。这就是典型的上下文窗口压力导致的“要点漂移”。当输入过长模型在做 Attention 的时候中间位置的权重会被挤压导致中间内容被压缩甚至忽略。这个现象在短文本测试里根本复现不出来一上长文本就暴露。解决思路是不要让模型一次性看完整个文档而是分块提取再把各块结果合并。我们在 handler.py 里加了分块逻辑def split_document(doc: str, chunk_size4000, overlap200): if len(doc) chunk_size: return [doc] chunks [] start 0 while start len(doc): end start chunk_size chunks.append(doc[start:end]) start max(end - overlap, 0) if end len(doc): break return chunkschunk_size 设成 4000 字符overlap 设成 200 字符是为了避免跨在边界上的重要信息被截断。每块提取出局部要点之后再进入一个合并去重阶段。如果某两块内容高度相似保留信息更完整的那一条。这个分块提取 合并去重的结构后来被我用在好几个场景里都成立。3.2 参数校验让 Skill 学会拒绝第二个坑是输入校验太宽松。早期 handler 里只做了最简单的非空判断结果上线前测试的时候就收到了各种奇怪的输入有人传了空字符串有人传了全是空白字符的文本还有人把 output_style 传成了 medium而 manifest 里明明只允许 concise 和 detailed 两个值。在 Agent 场景里参数不是用户手敲的而是大模型根据对话内容自动生成的所以更容易出现格式偏差。模型可能觉得 “medium” 是一个合理的详细程度但它不在枚举值里。正确的做法是在 handler 开头做严格校验遇到非法输入返回明确错误而不是硬着头皮处理。class SkillValidationError(Exception): pass def validate_input(args: dict): document args.get(document) if not isinstance(document, str) or len(document.strip()) 0: raise SkillValidationError(document must be a non-empty string) if len(document) 30000: raise SkillValidationError(document length exceeds limit 30000) max_points args.get(max_points, 10) if not isinstance(max_points, int) or max_points 1 or max_points 50: raise SkillValidationError(max_points must be integer between 1 and 50) output_style args.get(output_style, concise) if output_style not in (concise, detailed): raise SkillValidationError(output_style must be one of: concise, detailed)这段代码的核心思想是“让 Skill 学会拒绝”。宁可返回明确的参数错误让 Agent 重新组织输入也不要在一个不合法输入上浪费一次模型调用。因为非法输入即使硬处理了得到的结果也没有可信度还不如让调用方早点重试。3.3 效果评估用真实样本集替代“感觉还行”第三个坑是关于评估方式的。最开始我调试完一两个样本感觉输出内容挺像那么回事就觉得这个 Skill 可以交付了。后来跟同事讨论才发现这种“感觉靠谱”的评估方式问题很大——因为你觉得准的那几个样本恰好都是你自己挑的偏向性太明显。后来我们做了一个很朴素的评估集从历史真实数据里抽了 20 条客户反馈每条由人工标注出“应该提取哪些核心要点”。然后让 Skill 分别跑这些样本统计输出要点跟人工要点的重合度。样本人工要点数Skill 提取数正常命中数命中率备注样例 0187787.5%漏了一条关于账单的要点样例 02555100%-样例 03676100%多输出一条重复信息样例 0443375%漏了附件信息这一轮跑下来平均命中率只有 82%。问题集中出现在两个类型上一种是文档中间位置的信息被遗漏另一种是多个相似要点没有被合并重复输出。这两类问题在人工看单个样本的时候都不容易察觉但放到 20 条样本里跑一遍规律就非常明显了。评估完以后我们针对性做了两件事微调 prompt 规则强制要求“先按段落提取再合并同类项”同时把分块逻辑的 overlap 从 200 调到了 300。改完再跑同一批样本命中率升到了 93%。没有这套样本集这个提升是不可能的。4. 上云前的改造本地能跑不等于云端能跑4.1 依赖锁定与最小化本地跑通以后我们都觉得可以上线了。结果第一次部署到云端测试环境直接失败。报错信息是缺了一个 Python 包本地没问题云端没有。这一下让我意识到本地开发环境里往往隐藏着大量隐式依赖——可能是之前其他项目往同一个 Python 环境里装过包也可能是某个工具链自带的库。这些依赖在 requirements.txt 里根本没写。云端环境是干净的新环境缺了就是缺了。解决办法有两个。第一把 requirements.txt 里每个包都钉到精确版本不要用大于号去指定宽松版本因为新版本可能带来意料之外的行为变化。第二尽量删掉非必要的依赖。我当时为了做一个简单的文本相似度判断引入了一个很大的自然语言处理库后来发现这个库太重了在云端冷启动时加载要好几秒果断换成了纯 Python 实现。Skill 不是越重越好依赖越小启动越快故障面也越窄。4.2 配置与密钥管理不要躺在 .env 里本地开发的时候密钥放在项目根目录的 .env 文件里写代码的时候直接加载环境变量非常方便。但这个习惯带到云端就会出问题。云端环境的配置管理和本地完全不同。在本地你可以随意创建文件、写入变量、修改内容但云端通常有独立的密钥管理服务需要用对应的读取方式来获取而不是在代码里硬编码地址和密钥。更关键的是密钥会轮换、会失效本地 .env 里写死一个永远有效的 key云端可能三天就要换一次。我们当时踩的坑是把本地 .env 整个内容带上去了然后在云端测试时发现某些变量读取不到。查了半天才发现是云端平台对配置项名称有额外的规范比如不允许某些特殊字符、长度有限制。这告诉我们一个原则配置和代码要分离Skill 代码里不应该出现任何真实地址、密钥、账号信息全部通过环境变量或配置中心注入。本地和云端的配置差异可以用一张表简单对比配置维度本地开发云端运行模型密钥本机 .env 文件云端密钥管理可轮换环境变量随时修改重启即生效需走配置变更流程超时上限没有严格限制受平台配额约束临时文件任意路径可写只能写临时目录且可能被回收4.3 超时与内存资源配额下的重新估算上云之前我对超时这事几乎没概念。本地调一个函数跑二十秒也无所谓反正没有人在等着。云端不一样Serverless 环境通常有严格的执行超时限制默认可能只有几秒到几十秒超过就强制终止。doc_distiller 处理一篇超长文档分块提取加上合并去重本地测下来平均要 8 到 15 秒。如果云端超时上限是 10 秒那大概率有一半请求会超时。再加上冷启动时间第一次调用可能要多加载两秒的依赖。所以上云前要做一次真实的边界测试用最大允许的输入长度、最差的输入内容测出最坏情况下的执行时长然后对比平台的超时配额做调整。内存也要重新估算。本地机器通常内存充足但云端的默认内存配额可能只有 128 兆或 256 兆。处理大文档的时候如果一次性把全文拆成多个分块每个分块都要经过模型提示词处理中间会产生大量临时字符串内存很容易顶到上限。我们最后是把最大允许输入从 30000 字符降到了 20000同时调整了分块大小避免出现内存压力。4.4 日志与观测设计给每次调用一个 requestId本地调试的时候发现问题可以直接加打印盯着控制台看。到了云端所有请求都是异步、并发的用户请求进来后可能横跨多个服务、多个实例。如果没有一个贯穿的标识出了问题根本说不清是哪一步挂了。我们很早就做了这样的设计每次 Skill 调用拿一个 requestId在 handler 入口把它打进日志后续每一步处理、每一次外部调用、最终返回结果都带上这个标识。这样在云端日志平台里输入一个 requestId就能把一次完整调用的全过程串起来。def handler(args: dict) - dict: request_id args.pop(_request_id, unknown) logger.info(skill start, extra{request_id: request_id}) try: validate_input(args) chunked split_document(args[document]) points [extract_points(chunk, args) for chunk in chunked] merged merge_points(points, args.get(output_style, concise)) result {summary: build_summary(merged), key_points: merged} logger.info(skill success, extra{request_id: request_id}) return result except SkillValidationError as e: logger.warning(skill validation failed, exc_infoe, extra{request_id: request_id}) raise这套日志设计在本地看起来有点“过度”但对云端来说必要。后边遇到线上问题时它帮了大忙。5. 云端落地后的实测复盘并发、重试与服务治理5.1 并发场景下暴露的全局状态问题上线第一天我们做了一个小规模的并发压测50 个请求同时进来。结果还没跑到一半就有大量返回结果异常了——两个不同用户的请求居然共享了同一个输出结果A 用户的提取结果里出现了 B 用户的原文片段。排查过程还算快。我第一反应是模型响应问题结果检查了请求日志发现并不是模型幻觉。后来定位到 handler.py 里一个历史遗留问题我在模块级别定义了一个全局列表用来做合并去重的缓存。本地串行调用的时候一个请求处理完再进下一个这个全局列表没出过问题。并发一上来多个请求同时读写同一个全局列表数据就串了。# 错误的写法全局可变状态 _shared_buffer [] def handler(args: dict) - dict: _shared_buffer.append(args[document]) merged merge_points(_shared_buffer) # 这里会读到别人的数据 ...这个问题的根源是本地开发默认是“单请求模式”你脑子里想的是“一个输入对应一个输出”。但云端是“多实例 多请求并发”任何全局可变状态都会变成共享污染源。修复方法很简单把所有状态收进函数内部不要有任何模块级的可变对象。如果是需要缓存用带 key 的独立缓存服务而不是全局变量。5.2 第三方接口失败重试与降级设计doc_distiller 依赖一个外部的语义去重服务用来判断两条要点是不是同一个主题。本地测试的时候这个服务非常稳定基本没想过它会挂。云端实测第一天这个服务就开始响应变慢偶尔超时。原因也很常见出口网络路径更长、账号配额限制更严格、限流策略更敏感。一开始我们用的是“失败就报错”的策略结果就是整个 Skill 也跟着挂了一小段时间。后来改成两段式面对第三方接口的临时故障先做有限次数的重试重试间隔指数退避如果重试耗尽还是失败就启动降级逻辑改用基于编辑距离的本地去重宁可去重质量差一点也不能让整个 Skill 直接不可用。这里有个容易被忽略的细节重试成本不低。如果第三方服务已经过载你再疯狂重试只会让问题更严重。所以重试间隔要拉开。我们用的参数是 200 毫秒、800 毫秒、2400 毫秒最多三次三次都不行就走降级。这个参数再大就影响用户体验了。5.3 从日志到指标持续观测 Skill 的健康度上线稳定运行以后再回头看我发现一个挺有意思的事本地调试关注的是“正确性”云端运维关注的是“健康度”。正确性是这次调用结果对不对健康度是整段时间内服务的成功率、延迟、错误率是不是在可接受范围。我们把日志系统搭好之后开始统计每个 Skill 的指标。重点关注三个东西调用成功率、P95 延迟、错误类型分布。成功率低说明有系统性问题P95 延迟高可能是某些特定输入导致执行时间特别长错误类型分布能帮我们快速判断是参数错误、外部接口错误还是模型返回解析错误。有一次线上告警错误率从正常的 0.5% 跳到了 8%查日志发现全是同一种错误open_issues 字段在模型输出里变成了 null而我们的解析代码只接受数组。根源在于 prompt 规则里没有明确说“open_issues 如果为空输出空数组不要输出 null”。这类问题单靠本地测试很难发现因为本地测试用的提示词版本和云端线上的提示词版本可能不完全一致。这又引出一个经验Skill 的版本管理必须跟上prompt 的改动和生产环境要严格对齐。6. 这次实践改变了我对 Skill 开发的认知6.1 Skill 首先是软件模块其次才是“技能”在真正经历一轮本地到云端的完整流程之前我对 Skill 的理解停留在“它是一段比较复杂的提示词”上。现在我的看法完全变了Skill 首先是一个软件模块它有接口定义、有输入输出契约、有错误处理、有日志、有依赖管理、有版本号必须按软件工程的标准来对待。提示词只是这个模块里最上层的一小部分底下的结构、边界、可测试性、可观测性才是决定它能走多远的东西。如果只把 Skill 当成“提示词工程”那你永远不会去设计参数校验、不会去想全局状态污染、不会为它写样本集做回归测试。这些不是附加项是一个线上模块的基本配置。6.2 可测试性设计的位置应该前移在本地开发阶段我总觉得改代码很容易跑了不对就再改一下。这种心态导致测试意识很薄弱。等到上了云端每一次验证都要走完整的部署流程来回成本高了好几倍我才真切体会到可测试性设计的重要性。现在再看效果评估集应该在写第一版代码的时候就建好本地跑通以后就纳入回归范围。每次改 prompt、改分块逻辑、改合并策略都拿同一批样本跑一遍对比指标变化。这种做法在本地开发阶段看起来多花了一点时间但换来的是无数次云端测试的节省。可测试性是 Skill 开发效率的放大器。6.3 边界感不是所有逻辑都需要做成 Skill最后聊点关于“过度设计”的体会。做完了 doc_distiller 之后有一段时间我们陷入了“万物皆可 Skill”的状态觉得什么功能都该封装成 Skill。后来做了两个不太成功的尝试发现有些功能根本不值得做。判断标准其实还是回到最开始那三条任务是否重复发生、输入输出是否能结构化定义、处理链是否足够复杂。如果你面临的任务只是“把这句话换个说法”直接写进 Agent 的指令就好了做成 Skill 反而增加调度开销还可能在某些不该触发的场景被误调用。Skill 的粒度应该以“一个明确的业务能力”为单位而不是以“一个功能点”为单位。这次实践走完之后我最大的收获不是某个具体的技术细节而是一个很朴素的道理增强大模型应用的能力不只是给它更强的模型而是给它一套边界清晰、可测试、可运维的模块化能力。Skill 这种形态刚好提供了这种路径但路径走不走得通取决于你以什么样的工程标准去对待它。现在如果再让我从零开始做一个 Skill我会先写好 manifest 的 schema再建好评估样本集然后才动笔写 prompt——顺序对了后面就顺了。