1. 项目概述一个被严重低估的“技能容器”概念“agent-skills”这个词组乍看像技术文档里的缩写或是某次内部会议随手记下的笔记关键词。但过去两年里我在多个跨领域项目中反复遇到它——不是作为独立产品而是作为系统能力演化的关键接口层。它不指代某个具体工具而是一种将人类可描述、可验证、可组合的执行能力映射为机器可调用、可编排、可审计的标准化单元的设计范式。简单说它解决的是“让AI不只是会聊天而是能真正做事”的最后一公里问题。我最早在某高校实验室参与一个智能运维助手项目时接触到这个概念。当时团队卡在“模型能准确识别告警日志却无法自动执行重启服务或扩容操作”这个环节。工程师写的Python脚本散落在不同服务器上调用权限混乱参数硬编码日志格式不统一。后来我们把所有运维动作抽象成一组agent-skillsrestart_service、scale_database、fetch_log_segment每个技能都强制定义输入schema如service_name: str, timeout_sec: int、输出schemastatus: str, duration_ms: float、执行超时、重试策略、权限标签和人工确认开关。结果是LLM只需生成JSON格式的技能调用请求调度器就能安全执行错误时自动回滚并生成可读报告。整个过程不再依赖“模型是否理解自然语言”而是依赖“技能定义是否严谨”。这个词之所以成为热搜并非因为技术多新而是因为它精准戳中了当前AI落地的集体焦虑——模型能力越来越强但生产环境中的“行动鸿沟”反而更宽了。它适合三类人一线开发者需要快速封装业务逻辑、产品经理需定义AI能做什么不能做什么、以及技术决策者评估AI系统是否具备可扩展的执行底盘。它不教你怎么训练大模型但教你如何让大模型真正嵌入工作流。2. 核心设计逻辑为什么必须是“技能”而非“函数”或“API”2.1 技能与函数的本质区别语义完整性很多人第一反应是“这不就是写一堆函数吗”我试过直接把现有代码包改成函数暴露给LLM调用结果两周后就推翻重来。根本问题在于函数是技术契约技能是语义契约。一个函数def send_email(to: str, subject: str, body: str)只承诺“输入三个字符串返回发送成功与否”。但它不回答to字段是否支持别名如“财务组”body是否允许Markdown失败时是否重试重试几次是否记录审计日志这些都不是技术实现问题而是业务语义问题。而一个send_email技能其定义必须包含name: send_email description: 向指定收件人发送带格式的内部通知邮件支持别名解析和附件 input_schema: to: type: string description: 支持邮箱地址或预设组名如hr, devops subject: type: string max_length: 100 body: type: string format: markdown # 明确支持markdown渲染 attachments: type: array items: type: object properties: filename: {type: string} content_base64: {type: string} output_schema: status: {type: string, enum: [success, failed, pending_review]} message_id: {type: string, nullable: true} execution_policy: timeout_sec: 30 max_retries: 2 requires_approval: false # 关键业务场景设为true audit_log: true这个YAML定义本身就是一个可执行的协议。LLM生成的调用请求必须严格匹配input_schema否则被拒绝执行结果必须符合output_schema否则触发告警。这种约束力是普通函数签名永远无法提供的。提示技能定义必须通过JSON Schema校验且校验器要嵌入到调用链路最前端。我见过太多项目把校验放在执行后端导致LLM传入非法参数时服务直接崩溃而非优雅拒绝。2.2 技能与API的关键分野上下文感知能力API是无状态的技能是有上下文记忆的。这是决定AI能否真正协作的核心。举个真实案例某电商公司的客服助手需要处理“订单取消”请求。如果用传统API流程是LLM识别用户意图 → 调用/api/cancel_order?order_id123API返回{success: true}→ LLM回复“已取消”但实际业务远比这复杂用户可能说“帮我取消昨天那个没发货的订单”这里隐含了时间范围、发货状态等条件。如果强行塞进API参数URL会变成/api/cancel_order?user_id456date_rangelast_24hstatusnot_shipped而LLM必须从对话历史中精确提取这些参数——这恰恰是它最不稳定的环节。而cancel_order技能的设计思路完全不同技能定义中明确声明requires_context: [user_id, recent_orders, order_status_history]调度器在收到调用请求前自动注入这些上下文数据来自数据库查询或缓存LLM只需生成最简请求{order_id: 123}或{reason: not_shipped}其余由技能框架补全实测下来这种设计使订单取消成功率从68%提升到94%因为LLM不再需要“猜”参数而是聚焦于“理解意图”。2.3 技能系统的三层架构隔离风险的物理边界一个健壮的agent-skills系统必然包含清晰的分层这是我踩过坑后总结的铁律层级名称职责典型技术选型为什么必须分离L0技能注册中心统一管理所有技能元数据定义、版本、权限、健康状态PostgreSQL Redis防止LLM直接访问底层服务所有调用必须经注册中心鉴权路由L1技能执行沙箱在隔离环境中运行技能代码限制网络、文件、CPU、内存Docker容器 / gVisor轻量虚拟化某金融客户曾因未隔离LLM调用list_files技能意外读取到数据库配置文件L2技能编排引擎解析LLM生成的技能调用序列处理依赖、重试、超时、人工介入Temporal / Cadence工作流引擎单一技能失败时能自动回滚已执行步骤如先扣款再发券扣款失败则不发券这三层不是可选项而是安全底线。我坚持要求所有合作方在开发第一个技能前先搭好这三层骨架。看似多花3天但后续省下至少2周的线上事故排查时间。3. 技能定义与实现从白板到可运行的完整路径3.1 技能定义的黄金四要素定义一个技能不是写文档而是设计一个微型服务契约。我用“四要素检验法”确保定义质量可验证性Verifiability必须能用自动化测试覆盖。例如transfer_funds技能测试用例必须包含正常转账余额充足→ 检查双方账户变动事务一致性余额不足 → 检查返回status: insufficient_balance且无资金变动并发转账 → 检查锁机制是否生效两个请求同时操作同一账户最终余额正确可审计性Auditability每次调用必须生成不可篡改的审计日志包含调用者身份LLM session ID 或人工操作员ID完整输入参数脱敏后执行耗时、资源消耗CPU/内存输出结果摘要如转账金额、目标账户后四位注意审计日志必须写入独立存储如S3不能与业务数据库共用。某次数据库故障导致审计日志丢失引发合规审查危机。可降级性Degradability当技能不可用时系统必须有明确的fallback策略。常见方案自动转人工{status: pending_review, fallback: escalate_to_agent}降级执行send_notification技能在邮件服务宕机时自动切到企业微信推送返回结构化错误{status: unavailable, suggestion: 请稍后重试或联系技术支持}可组合性Composability技能必须能作为其他技能的输入。例如get_user_profile技能输出{ email: ab.com, preferred_language: zh }send_welcome_email技能的to字段可直接引用get_user_profile.email这要求所有技能输出必须是结构化JSON且字段命名遵循统一规范如全部小写下划线。3.2 实现一个生产级技能以process_invoice_pdf为例这个技能在某财税SaaS项目中承担核心角色将用户上传的PDF发票自动解析为结构化数据。以下是完整实现要点非伪代码而是我们线上跑着的精简版# skills/process_invoice_pdf.py import json import logging from typing import Dict, Any, Optional from pydantic import BaseModel, Field from PIL import Image import fitz # PyMuPDF # 1. 严格定义输入输出Pydantic模型自动校验 class ProcessInvoiceInput(BaseModel): pdf_content_base64: str Field(..., descriptionPDF文件base64编码) vendor_name_hint: Optional[str] Field(None, description供应商名称提示用于OCR优化) class ProcessInvoiceOutput(BaseModel): invoice_number: str Field(..., description发票号码) issue_date: str Field(..., description开票日期YYYY-MM-DD格式) total_amount: float Field(..., description总金额单位元) line_items: list[Dict[str, Any]] Field(..., description明细行列表) confidence_score: float Field(..., ge0.0, le1.0, description解析置信度) # 2. 技能主函数必须命名为execute框架自动发现 def execute(input_data: Dict[str, Any]) - Dict[str, Any]: try: # 步骤1解码PDF并验证防恶意文件 pdf_bytes base64.b64decode(input_data[pdf_content_base64]) if len(pdf_bytes) 10 * 1024 * 1024: # 10MB上限 raise ValueError(PDF file too large) # 步骤2用PyMuPDF提取文本比纯OCR快10倍精度足够发票场景 doc fitz.open(streampdf_bytes, filetypepdf) full_text for page in doc: full_text page.get_text() \n doc.close() # 步骤3规则引擎初筛关键避免全量调用大模型 # 发票号通常在发票代码、No.、Invoice No后 invoice_no_match re.search(r(?:发票代码|No\.|Invoice No)[:\s]*([A-Z0-9\-]{8,20}), full_text) if not invoice_no_match: raise ValueError(Cannot locate invoice number) # 步骤4调用专用OCR模型仅对关键区域截图非整页 # 这里省略具体OCR调用重点是只传截图不传原始PDF ocr_result call_invoice_ocr( image_bytesextract_invoice_region(pdf_bytes), vendor_hintinput_data.get(vendor_name_hint) ) # 步骤5结构化输出强制类型转换防LLM胡乱返回 output ProcessInvoiceOutput( invoice_numberocr_result[invoice_number], issue_dateparse_date(ocr_result[issue_date]), total_amountfloat(ocr_result[total_amount]), line_itemsocr_result[line_items], confidence_scoreocr_result[confidence] ).dict() return output except Exception as e: logging.error(fProcessInvoice failed: {str(e)}, exc_infoTrue) # 重要返回标准错误结构供LLM理解 return { status: failed, error_code: OCR_PROCESSING_ERROR, message: str(e) } # 3. 技能元数据框架读取此注释生成注册信息 name: process_invoice_pdf description: 解析PDF发票为结构化数据支持增值税专用/普通发票 input_schema: {pdf_content_base64: string, vendor_name_hint: string} output_schema: {invoice_number: string, issue_date: string, total_amount: number, ...} execution_policy: timeout_sec: 120 max_retries: 1 requires_approval: false audit_log: true 实操心得这个技能上线后我们发现90%的发票能被规则引擎直接提取无需调用OCR。于是我们在框架层加了“规则前置”开关当规则匹配成功且置信度0.95时跳过OCR步骤。平均处理时间从8.2秒降到1.7秒成本降低79%。这说明技能不是越“AI”越好而是越“务实”越好。3.3 技能注册与权限控制让LLM不敢越界技能注册不是把代码扔进目录就行必须有严格的准入流程。我们采用“三审制”语法审核CI流水线检查是否存在execute函数输入/输出模型是否继承自BaseModel是否包含完整元数据注释是否有硬编码密钥正则扫描sk-[a-zA-Z0-9]安全审核人工自动化扫描网络调用是否限定白名单域名如只允许api.ocr-service.com文件操作是否限定路径如只允许/tmp/invoice_uploads/是否使用危险函数eval,os.system,subprocess.Popen业务审核领域专家签字技能描述是否准确反映业务含义如refund_payment不能写成return_money权限设置是否合理delete_user_account必须requires_approval: trueFallback策略是否覆盖所有失败场景注册后每个技能获得唯一ID和版本号如process_invoice_pdfv1.2.0LLM调用时必须指定版本防止定义变更导致行为不一致。4. 技能编排与实战让多个技能像乐高一样协作4.1 编排不是写代码而是设计状态机当技能数量超过10个手动调用就不可行了。我们用状态机思想设计编排逻辑。以“新用户入职流程”为例涉及5个技能技能名触发条件前置依赖失败Fallbackcreate_user_account用户提交入职表单无人工审核assign_laptop账户创建成功create_user_account暂缓分配邮件通知ITprovision_email账户创建成功create_user_account使用临时邮箱schedule_onboarding邮箱开通成功provision_email电话通知HRsend_welcome_kit所有前置完成assign_laptopschedule_onboarding顺丰寄送纸质手册关键点在于编排逻辑不写在技能内部而由独立引擎驱动。我们用Temporal工作流定义// workflow/onboard_employee.go func OnboardEmployeeWorkflow(ctx workflow.Context, input OnboardInput) error { ao : workflow.ActivityOptions{ StartToCloseTimeout: 10 * time.Minute, RetryPolicy: temporal.RetryPolicy{MaximumAttempts: 3}, } ctx workflow.WithActivityOptions(ctx, ao) // 步骤1创建账户并行启动 createFuture : workflow.ExecuteActivity(ctx, skills.CreateUserAccount, input) // 步骤2等待账户创建完成然后并行执行后续 if err : createFuture.Get(ctx, nil); err ! nil { return workflow.NewTerminatedError(账户创建失败, err) } assignFuture : workflow.ExecuteActivity(ctx, skills.AssignLaptop, input) emailFuture : workflow.ExecuteActivity(ctx, skills.ProvisionEmail, input) // 步骤3等待邮箱开通再安排入职培训 if err : emailFuture.Get(ctx, nil); err nil { workflow.ExecuteActivity(ctx, skills.ScheduleOnboarding, input) } // 步骤4所有关键步骤完成后发欢迎包 workflow.ExecuteActivity(ctx, skills.SendWelcomeKit, input) return nil }这种设计的好处是LLM只需生成顶层指令{action: onboard_employee, user_id: U123}引擎自动展开为技能调用序列。即使某个技能失败如assign_laptop因库存不足工作流会暂停并通知管理员而不会影响provision_email的执行。4.2 LLM如何生成可靠的技能调用LLM生成技能调用不是靠“自由发挥”而是受严格模板约束。我们用以下方法确保可靠性技能目录动态注入在LLM prompt中实时插入当前可用技能列表含描述和参数可用技能 - create_user_account: 创建新员工系统账户。参数{user_id: string, name: string, department: string} - assign_laptop: 为员工分配笔记本电脑。参数{user_id: string, model: string (可选默认Dell XPS)} ...强制JSON Schema输出Prompt末尾明确要求请严格按以下JSON Schema输出不要任何额外文字 {skill_name: string, parameters: object, reason: string}双阶段校验第一阶段用JSON Schema校验器检查格式第二阶段用技能注册中心验证skill_name是否存在、parameters是否匹配该技能定义若任一阶段失败立即返回结构化错误给LLM让它重新生成。实测数据显示这种方法使技能调用成功率稳定在92%以上。对比直接让LLM自由输出错误率从47%降至8%。4.3 监控与可观测性让技能不再黑盒技能系统最大的陷阱是“不知道它怎么失败的”。我们建立三级监控层级监控项工具告警阈值作用技能级调用成功率、平均延迟、错误类型分布Prometheus Grafana成功率95%持续5分钟定位具体哪个技能异常编排级工作流完成率、各步骤耗时分布、重试次数Temporal Web UI 自定义指标单步重试3次发现编排逻辑缺陷如循环依赖语义级LLM生成的技能调用与实际业务意图匹配度人工抽样 NLP相似度计算匹配度80%优化LLM prompt或技能描述特别强调“语义级监控”我们每周随机抽取100条用户请求和对应LLM生成的技能调用由业务专家打分。发现当技能描述中出现“快速”、“智能”等模糊词时匹配度下降35%。于是我们强制要求所有技能描述用动宾结构“解析发票”、“创建账户”、“发送邮件”禁用形容词。5. 常见问题与避坑指南血泪换来的经验清单5.1 典型问题速查表问题现象根本原因解决方案我的实操备注LLM频繁调用不存在的技能名技能目录未实时同步或LLM缓存了旧列表实现技能注册中心的Webhook技能更新时自动刷新LLM缓存我们用Redis Pub/Sub更新后300ms内全量同步技能执行超时但无日志沙箱进程被OOM Killer杀死未捕获信号在Docker启动命令中添加--oom-kill-disablefalse并在技能代码中监听SIGTERM某次内存泄漏导致沙箱被杀因无日志排查了8小时同一技能并发调用数据错乱技能代码中使用了全局变量或静态缓存强制要求所有技能函数为纯函数禁止模块级状态我们CI加入静态分析检测global和static关键字LLM生成参数类型错误如传字符串给数字字段JSON Schema校验未开启或位置错误将校验器置于API网关层早于任何业务逻辑曾因校验放太晚导致非法参数进入数据库修复耗时2天技能执行成功但业务未生效技能返回{status:success}但实际未做任何事所有技能必须有副作用验证如创建账户后查DB记录我们在框架层加了“副作用断言”失败则标记为partial_success5.2 五个必须遵守的铁律技能命名必须动词开头且唯一✅send_email,calculate_tax,verify_identity❌email_service,tax_calculator,id_verification名词化导致LLM混淆动作意图所有输入参数必须有业务含义禁用技术术语✅customer_id,payment_method,shipping_address❌user_uuid,pay_type_enum,addr_jsonLLM不理解枚举值但理解“支付宝”、“微信”技能必须幂等或明确声明非幂等create_user_account是非幂等的必须在定义中标注idempotent: false框架会自动加去重Key如user_id而get_user_profile必须幂等框架可缓存结果。错误处理必须返回结构化Code而非自然语言✅{error_code: INSUFFICIENT_BALANCE, message: 余额不足请充值}❌{error: 你的钱不够快去充钱}LLM无法解析非结构化错误技能间通信必须通过输出字段引用禁用全局状态正确schedule_onboarding的user_id参数引用create_user_account.output.user_id错误在内存中存current_user_id变量分布式环境下失效5.3 性能优化的三个关键点冷启动优化技能容器启动慢我们用“预热池”——空闲时保持3个常用技能容器待命收到请求后秒级分配实测首字节延迟从2.1s降至120ms。大文件处理PDF/视频等大文件不走HTTP Body而是用预签名URL上传到对象存储技能只接收URL。既减小网络压力又避免LLM token超限。LLM Token节省技能定义不塞进每次prompt而是用RAG检索——LLM提问时系统自动检索最相关3个技能描述注入上下文Prompt长度减少65%。最后分享一个小技巧我们给每个技能加了estimated_cost字段单位毫秒LLM在生成长序列时会优先选择低成本技能。比如get_user_profile50ms比analyze_user_behavior2800ms更可能被选用这在实时性要求高的场景非常实用。这个字段不是拍脑袋而是基于1000次压测的P95延迟。
1. 项目概述一个被严重低估的“技能容器”概念“agent-skills”这个词组乍看像技术文档里的缩写或是某次内部会议随手记下的笔记关键词。但过去两年里我在多个跨领域项目中反复遇到它——不是作为独立产品而是作为系统能力演化的关键接口层。它不指代某个具体工具而是一种将人类可描述、可验证、可组合的执行能力映射为机器可调用、可编排、可审计的标准化单元的设计范式。简单说它解决的是“让AI不只是会聊天而是能真正做事”的最后一公里问题。我最早在某高校实验室参与一个智能运维助手项目时接触到这个概念。当时团队卡在“模型能准确识别告警日志却无法自动执行重启服务或扩容操作”这个环节。工程师写的Python脚本散落在不同服务器上调用权限混乱参数硬编码日志格式不统一。后来我们把所有运维动作抽象成一组agent-skillsrestart_service、scale_database、fetch_log_segment每个技能都强制定义输入schema如service_name: str, timeout_sec: int、输出schemastatus: str, duration_ms: float、执行超时、重试策略、权限标签和人工确认开关。结果是LLM只需生成JSON格式的技能调用请求调度器就能安全执行错误时自动回滚并生成可读报告。整个过程不再依赖“模型是否理解自然语言”而是依赖“技能定义是否严谨”。这个词之所以成为热搜并非因为技术多新而是因为它精准戳中了当前AI落地的集体焦虑——模型能力越来越强但生产环境中的“行动鸿沟”反而更宽了。它适合三类人一线开发者需要快速封装业务逻辑、产品经理需定义AI能做什么不能做什么、以及技术决策者评估AI系统是否具备可扩展的执行底盘。它不教你怎么训练大模型但教你如何让大模型真正嵌入工作流。2. 核心设计逻辑为什么必须是“技能”而非“函数”或“API”2.1 技能与函数的本质区别语义完整性很多人第一反应是“这不就是写一堆函数吗”我试过直接把现有代码包改成函数暴露给LLM调用结果两周后就推翻重来。根本问题在于函数是技术契约技能是语义契约。一个函数def send_email(to: str, subject: str, body: str)只承诺“输入三个字符串返回发送成功与否”。但它不回答to字段是否支持别名如“财务组”body是否允许Markdown失败时是否重试重试几次是否记录审计日志这些都不是技术实现问题而是业务语义问题。而一个send_email技能其定义必须包含name: send_email description: 向指定收件人发送带格式的内部通知邮件支持别名解析和附件 input_schema: to: type: string description: 支持邮箱地址或预设组名如hr, devops subject: type: string max_length: 100 body: type: string format: markdown # 明确支持markdown渲染 attachments: type: array items: type: object properties: filename: {type: string} content_base64: {type: string} output_schema: status: {type: string, enum: [success, failed, pending_review]} message_id: {type: string, nullable: true} execution_policy: timeout_sec: 30 max_retries: 2 requires_approval: false # 关键业务场景设为true audit_log: true这个YAML定义本身就是一个可执行的协议。LLM生成的调用请求必须严格匹配input_schema否则被拒绝执行结果必须符合output_schema否则触发告警。这种约束力是普通函数签名永远无法提供的。提示技能定义必须通过JSON Schema校验且校验器要嵌入到调用链路最前端。我见过太多项目把校验放在执行后端导致LLM传入非法参数时服务直接崩溃而非优雅拒绝。2.2 技能与API的关键分野上下文感知能力API是无状态的技能是有上下文记忆的。这是决定AI能否真正协作的核心。举个真实案例某电商公司的客服助手需要处理“订单取消”请求。如果用传统API流程是LLM识别用户意图 → 调用/api/cancel_order?order_id123API返回{success: true}→ LLM回复“已取消”但实际业务远比这复杂用户可能说“帮我取消昨天那个没发货的订单”这里隐含了时间范围、发货状态等条件。如果强行塞进API参数URL会变成/api/cancel_order?user_id456date_rangelast_24hstatusnot_shipped而LLM必须从对话历史中精确提取这些参数——这恰恰是它最不稳定的环节。而cancel_order技能的设计思路完全不同技能定义中明确声明requires_context: [user_id, recent_orders, order_status_history]调度器在收到调用请求前自动注入这些上下文数据来自数据库查询或缓存LLM只需生成最简请求{order_id: 123}或{reason: not_shipped}其余由技能框架补全实测下来这种设计使订单取消成功率从68%提升到94%因为LLM不再需要“猜”参数而是聚焦于“理解意图”。2.3 技能系统的三层架构隔离风险的物理边界一个健壮的agent-skills系统必然包含清晰的分层这是我踩过坑后总结的铁律层级名称职责典型技术选型为什么必须分离L0技能注册中心统一管理所有技能元数据定义、版本、权限、健康状态PostgreSQL Redis防止LLM直接访问底层服务所有调用必须经注册中心鉴权路由L1技能执行沙箱在隔离环境中运行技能代码限制网络、文件、CPU、内存Docker容器 / gVisor轻量虚拟化某金融客户曾因未隔离LLM调用list_files技能意外读取到数据库配置文件L2技能编排引擎解析LLM生成的技能调用序列处理依赖、重试、超时、人工介入Temporal / Cadence工作流引擎单一技能失败时能自动回滚已执行步骤如先扣款再发券扣款失败则不发券这三层不是可选项而是安全底线。我坚持要求所有合作方在开发第一个技能前先搭好这三层骨架。看似多花3天但后续省下至少2周的线上事故排查时间。3. 技能定义与实现从白板到可运行的完整路径3.1 技能定义的黄金四要素定义一个技能不是写文档而是设计一个微型服务契约。我用“四要素检验法”确保定义质量可验证性Verifiability必须能用自动化测试覆盖。例如transfer_funds技能测试用例必须包含正常转账余额充足→ 检查双方账户变动事务一致性余额不足 → 检查返回status: insufficient_balance且无资金变动并发转账 → 检查锁机制是否生效两个请求同时操作同一账户最终余额正确可审计性Auditability每次调用必须生成不可篡改的审计日志包含调用者身份LLM session ID 或人工操作员ID完整输入参数脱敏后执行耗时、资源消耗CPU/内存输出结果摘要如转账金额、目标账户后四位注意审计日志必须写入独立存储如S3不能与业务数据库共用。某次数据库故障导致审计日志丢失引发合规审查危机。可降级性Degradability当技能不可用时系统必须有明确的fallback策略。常见方案自动转人工{status: pending_review, fallback: escalate_to_agent}降级执行send_notification技能在邮件服务宕机时自动切到企业微信推送返回结构化错误{status: unavailable, suggestion: 请稍后重试或联系技术支持}可组合性Composability技能必须能作为其他技能的输入。例如get_user_profile技能输出{ email: ab.com, preferred_language: zh }send_welcome_email技能的to字段可直接引用get_user_profile.email这要求所有技能输出必须是结构化JSON且字段命名遵循统一规范如全部小写下划线。3.2 实现一个生产级技能以process_invoice_pdf为例这个技能在某财税SaaS项目中承担核心角色将用户上传的PDF发票自动解析为结构化数据。以下是完整实现要点非伪代码而是我们线上跑着的精简版# skills/process_invoice_pdf.py import json import logging from typing import Dict, Any, Optional from pydantic import BaseModel, Field from PIL import Image import fitz # PyMuPDF # 1. 严格定义输入输出Pydantic模型自动校验 class ProcessInvoiceInput(BaseModel): pdf_content_base64: str Field(..., descriptionPDF文件base64编码) vendor_name_hint: Optional[str] Field(None, description供应商名称提示用于OCR优化) class ProcessInvoiceOutput(BaseModel): invoice_number: str Field(..., description发票号码) issue_date: str Field(..., description开票日期YYYY-MM-DD格式) total_amount: float Field(..., description总金额单位元) line_items: list[Dict[str, Any]] Field(..., description明细行列表) confidence_score: float Field(..., ge0.0, le1.0, description解析置信度) # 2. 技能主函数必须命名为execute框架自动发现 def execute(input_data: Dict[str, Any]) - Dict[str, Any]: try: # 步骤1解码PDF并验证防恶意文件 pdf_bytes base64.b64decode(input_data[pdf_content_base64]) if len(pdf_bytes) 10 * 1024 * 1024: # 10MB上限 raise ValueError(PDF file too large) # 步骤2用PyMuPDF提取文本比纯OCR快10倍精度足够发票场景 doc fitz.open(streampdf_bytes, filetypepdf) full_text for page in doc: full_text page.get_text() \n doc.close() # 步骤3规则引擎初筛关键避免全量调用大模型 # 发票号通常在发票代码、No.、Invoice No后 invoice_no_match re.search(r(?:发票代码|No\.|Invoice No)[:\s]*([A-Z0-9\-]{8,20}), full_text) if not invoice_no_match: raise ValueError(Cannot locate invoice number) # 步骤4调用专用OCR模型仅对关键区域截图非整页 # 这里省略具体OCR调用重点是只传截图不传原始PDF ocr_result call_invoice_ocr( image_bytesextract_invoice_region(pdf_bytes), vendor_hintinput_data.get(vendor_name_hint) ) # 步骤5结构化输出强制类型转换防LLM胡乱返回 output ProcessInvoiceOutput( invoice_numberocr_result[invoice_number], issue_dateparse_date(ocr_result[issue_date]), total_amountfloat(ocr_result[total_amount]), line_itemsocr_result[line_items], confidence_scoreocr_result[confidence] ).dict() return output except Exception as e: logging.error(fProcessInvoice failed: {str(e)}, exc_infoTrue) # 重要返回标准错误结构供LLM理解 return { status: failed, error_code: OCR_PROCESSING_ERROR, message: str(e) } # 3. 技能元数据框架读取此注释生成注册信息 name: process_invoice_pdf description: 解析PDF发票为结构化数据支持增值税专用/普通发票 input_schema: {pdf_content_base64: string, vendor_name_hint: string} output_schema: {invoice_number: string, issue_date: string, total_amount: number, ...} execution_policy: timeout_sec: 120 max_retries: 1 requires_approval: false audit_log: true 实操心得这个技能上线后我们发现90%的发票能被规则引擎直接提取无需调用OCR。于是我们在框架层加了“规则前置”开关当规则匹配成功且置信度0.95时跳过OCR步骤。平均处理时间从8.2秒降到1.7秒成本降低79%。这说明技能不是越“AI”越好而是越“务实”越好。3.3 技能注册与权限控制让LLM不敢越界技能注册不是把代码扔进目录就行必须有严格的准入流程。我们采用“三审制”语法审核CI流水线检查是否存在execute函数输入/输出模型是否继承自BaseModel是否包含完整元数据注释是否有硬编码密钥正则扫描sk-[a-zA-Z0-9]安全审核人工自动化扫描网络调用是否限定白名单域名如只允许api.ocr-service.com文件操作是否限定路径如只允许/tmp/invoice_uploads/是否使用危险函数eval,os.system,subprocess.Popen业务审核领域专家签字技能描述是否准确反映业务含义如refund_payment不能写成return_money权限设置是否合理delete_user_account必须requires_approval: trueFallback策略是否覆盖所有失败场景注册后每个技能获得唯一ID和版本号如process_invoice_pdfv1.2.0LLM调用时必须指定版本防止定义变更导致行为不一致。4. 技能编排与实战让多个技能像乐高一样协作4.1 编排不是写代码而是设计状态机当技能数量超过10个手动调用就不可行了。我们用状态机思想设计编排逻辑。以“新用户入职流程”为例涉及5个技能技能名触发条件前置依赖失败Fallbackcreate_user_account用户提交入职表单无人工审核assign_laptop账户创建成功create_user_account暂缓分配邮件通知ITprovision_email账户创建成功create_user_account使用临时邮箱schedule_onboarding邮箱开通成功provision_email电话通知HRsend_welcome_kit所有前置完成assign_laptopschedule_onboarding顺丰寄送纸质手册关键点在于编排逻辑不写在技能内部而由独立引擎驱动。我们用Temporal工作流定义// workflow/onboard_employee.go func OnboardEmployeeWorkflow(ctx workflow.Context, input OnboardInput) error { ao : workflow.ActivityOptions{ StartToCloseTimeout: 10 * time.Minute, RetryPolicy: temporal.RetryPolicy{MaximumAttempts: 3}, } ctx workflow.WithActivityOptions(ctx, ao) // 步骤1创建账户并行启动 createFuture : workflow.ExecuteActivity(ctx, skills.CreateUserAccount, input) // 步骤2等待账户创建完成然后并行执行后续 if err : createFuture.Get(ctx, nil); err ! nil { return workflow.NewTerminatedError(账户创建失败, err) } assignFuture : workflow.ExecuteActivity(ctx, skills.AssignLaptop, input) emailFuture : workflow.ExecuteActivity(ctx, skills.ProvisionEmail, input) // 步骤3等待邮箱开通再安排入职培训 if err : emailFuture.Get(ctx, nil); err nil { workflow.ExecuteActivity(ctx, skills.ScheduleOnboarding, input) } // 步骤4所有关键步骤完成后发欢迎包 workflow.ExecuteActivity(ctx, skills.SendWelcomeKit, input) return nil }这种设计的好处是LLM只需生成顶层指令{action: onboard_employee, user_id: U123}引擎自动展开为技能调用序列。即使某个技能失败如assign_laptop因库存不足工作流会暂停并通知管理员而不会影响provision_email的执行。4.2 LLM如何生成可靠的技能调用LLM生成技能调用不是靠“自由发挥”而是受严格模板约束。我们用以下方法确保可靠性技能目录动态注入在LLM prompt中实时插入当前可用技能列表含描述和参数可用技能 - create_user_account: 创建新员工系统账户。参数{user_id: string, name: string, department: string} - assign_laptop: 为员工分配笔记本电脑。参数{user_id: string, model: string (可选默认Dell XPS)} ...强制JSON Schema输出Prompt末尾明确要求请严格按以下JSON Schema输出不要任何额外文字 {skill_name: string, parameters: object, reason: string}双阶段校验第一阶段用JSON Schema校验器检查格式第二阶段用技能注册中心验证skill_name是否存在、parameters是否匹配该技能定义若任一阶段失败立即返回结构化错误给LLM让它重新生成。实测数据显示这种方法使技能调用成功率稳定在92%以上。对比直接让LLM自由输出错误率从47%降至8%。4.3 监控与可观测性让技能不再黑盒技能系统最大的陷阱是“不知道它怎么失败的”。我们建立三级监控层级监控项工具告警阈值作用技能级调用成功率、平均延迟、错误类型分布Prometheus Grafana成功率95%持续5分钟定位具体哪个技能异常编排级工作流完成率、各步骤耗时分布、重试次数Temporal Web UI 自定义指标单步重试3次发现编排逻辑缺陷如循环依赖语义级LLM生成的技能调用与实际业务意图匹配度人工抽样 NLP相似度计算匹配度80%优化LLM prompt或技能描述特别强调“语义级监控”我们每周随机抽取100条用户请求和对应LLM生成的技能调用由业务专家打分。发现当技能描述中出现“快速”、“智能”等模糊词时匹配度下降35%。于是我们强制要求所有技能描述用动宾结构“解析发票”、“创建账户”、“发送邮件”禁用形容词。5. 常见问题与避坑指南血泪换来的经验清单5.1 典型问题速查表问题现象根本原因解决方案我的实操备注LLM频繁调用不存在的技能名技能目录未实时同步或LLM缓存了旧列表实现技能注册中心的Webhook技能更新时自动刷新LLM缓存我们用Redis Pub/Sub更新后300ms内全量同步技能执行超时但无日志沙箱进程被OOM Killer杀死未捕获信号在Docker启动命令中添加--oom-kill-disablefalse并在技能代码中监听SIGTERM某次内存泄漏导致沙箱被杀因无日志排查了8小时同一技能并发调用数据错乱技能代码中使用了全局变量或静态缓存强制要求所有技能函数为纯函数禁止模块级状态我们CI加入静态分析检测global和static关键字LLM生成参数类型错误如传字符串给数字字段JSON Schema校验未开启或位置错误将校验器置于API网关层早于任何业务逻辑曾因校验放太晚导致非法参数进入数据库修复耗时2天技能执行成功但业务未生效技能返回{status:success}但实际未做任何事所有技能必须有副作用验证如创建账户后查DB记录我们在框架层加了“副作用断言”失败则标记为partial_success5.2 五个必须遵守的铁律技能命名必须动词开头且唯一✅send_email,calculate_tax,verify_identity❌email_service,tax_calculator,id_verification名词化导致LLM混淆动作意图所有输入参数必须有业务含义禁用技术术语✅customer_id,payment_method,shipping_address❌user_uuid,pay_type_enum,addr_jsonLLM不理解枚举值但理解“支付宝”、“微信”技能必须幂等或明确声明非幂等create_user_account是非幂等的必须在定义中标注idempotent: false框架会自动加去重Key如user_id而get_user_profile必须幂等框架可缓存结果。错误处理必须返回结构化Code而非自然语言✅{error_code: INSUFFICIENT_BALANCE, message: 余额不足请充值}❌{error: 你的钱不够快去充钱}LLM无法解析非结构化错误技能间通信必须通过输出字段引用禁用全局状态正确schedule_onboarding的user_id参数引用create_user_account.output.user_id错误在内存中存current_user_id变量分布式环境下失效5.3 性能优化的三个关键点冷启动优化技能容器启动慢我们用“预热池”——空闲时保持3个常用技能容器待命收到请求后秒级分配实测首字节延迟从2.1s降至120ms。大文件处理PDF/视频等大文件不走HTTP Body而是用预签名URL上传到对象存储技能只接收URL。既减小网络压力又避免LLM token超限。LLM Token节省技能定义不塞进每次prompt而是用RAG检索——LLM提问时系统自动检索最相关3个技能描述注入上下文Prompt长度减少65%。最后分享一个小技巧我们给每个技能加了estimated_cost字段单位毫秒LLM在生成长序列时会优先选择低成本技能。比如get_user_profile50ms比analyze_user_behavior2800ms更可能被选用这在实时性要求高的场景非常实用。这个字段不是拍脑袋而是基于1000次压测的P95延迟。
