企业官网建设流程全解析

1. 项目概述：Agent-Skills 不是新概念，而是工程落地的临界点

“Agent-Skills”这个词最近在技术社区里频繁冒头，但你翻遍主流文档、开源仓库和论文摘要，几乎找不到一个官方定义——它压根就不是某个框架的内置模块，也不是某家大厂刚发布的标准协议。它是一个从业者自发形成的工程共识性术语，指向一个非常具体、非常务实的问题：当一个智能体（Agent）不再只是调用几个API、生成几段文字，而是要真正走进业务流程、接管真实任务时，它必须具备哪些可拆解、可测试、可复用、可版本管理的“技能单元”？我带过三个不同行业的Agent落地项目，从某高校实验室的科研辅助系统，到某公司内部的跨系统工单调度平台，再到一个面向中小企业的合同条款比对工具，所有团队在第二周都会不约而同地卡在一个地方：我们写的那个“能查数据库+能写报告+能发邮件”的Agent，为什么一上线就出错？为什么改一个字段要动三处代码？为什么测试人员说“这个功能昨天还行，今天就不认人了”？答案最后都收束到一点：我们缺的不是大模型，而是清晰定义的、边界明确的、有输入输出契约的Agent-Skills。

它解决的不是“能不能做”，而是“能不能稳、能不能测、能不能换、能不能审”。比如，“从PDF提取结构化合同条款”这个动作，如果直接塞进Agent主循环里，它就是一团黑盒逻辑；但如果把它封装成一个名为extract_contract_clauses的Skill，它就必须明确定义：输入是PDF二进制流或S3路径，输出是JSON Schema约束的条款列表，失败时抛出预设错误码（如MISSING_SIGNATURE_FIELD），且自带单元测试覆盖率报告。这才是“Skills”的本质——把AI能力降维成软件工程里的函数接口。它适合两类人：一类是正在把LLM接入生产系统的后端/全栈工程师，你们需要可交付、可运维的模块；另一类是技术决策者，你们需要评估一个Agent方案是否真的具备长期演进能力，而不是又一个炫技Demo。别被名字唬住，它不依赖任何特定模型，GPT-4、Claude、本地部署的Qwen2.5，甚至未来某天你换成自研小模型，只要Skill接口不变，整个Agent骨架就能原地升级。

2. 核心设计思路：为什么必须放弃“全能Agent”，转向Skill驱动架构

2.1 传统Agent架构的三大硬伤，全是血泪教训

我参与的第一个Agent项目，目标是自动处理客户投诉邮件。团队信心满满，用LangChain搭了个“ReAct”风格的Agent：它能读邮件、能查CRM、能调用知识库、能生成回复草稿。上线三天，客服主管打电话来：“你们那个机器人，把‘退款已处理’的邮件，当成‘未处理’又催了客户三次。”我们花了整整两天才定位到问题——Agent在调用CRM API时，因网络抖动返回了空响应，它没做任何错误判断，直接把空数据喂给了后续的“生成回复”步骤，结果模型基于“无信息”胡编了一通。这就是典型“全能Agent”的脆弱性：所有能力耦合在一条执行链上，一处失守，全盘崩坏。后来我们复盘，发现这种架构天然存在三个无法绕开的缺陷：

第一是可观测性黑洞。当你只看到“Agent.run(input)”这个入口和最终输出，中间发生了什么？是知识检索失效？是工具调用超时？还是模型在模糊语义下做了错误推理？没有Skill边界，日志里只有一堆token流和HTTP状态码，根本没法做归因分析。某次线上故障，我们花了六小时翻日志，最后发现是某个嵌套在提示词里的正则表达式，在特定日期格式下永远匹配失败——这种细节，藏在“全能Agent”的提示工程里，连测试用例都写不出来。

第二是测试成本指数级飙升。一个包含5个工具调用、3层条件分支、2种模型路由的Agent，其状态空间是组合爆炸的。我们曾试图为它写端到端测试，光是覆盖“用户问退款+CRM返回超时+知识库命中率低”这一条路径，就要mock至少7个外部依赖。更可怕的是，每次模型微调或提示词修改，所有测试都要重跑，CI流水线动辄40分钟。而当我们把每个工具调用剥离成独立Skill后，测试立刻变得轻量：test_extract_order_id_from_email()只需传入一封模拟邮件文本，断言返回的order_id是否符合正则；test_query_crm_by_id()只需mock一个HTTP client，验证请求参数和返回结构。单个Skill的单元测试，平均执行时间从47秒降到0.8秒。

第三是演进与替换的锁死效应。项目中期，客户要求把“查询库存”功能从调用旧ERP接口，切换到新微服务。在原架构下，这意味要找到所有调用旧API的地方——它们散落在提示词模板、自定义Tool类、甚至某些条件判断的if语句里。我们改了11个文件，测试失败23次，上线后才发现漏改了一个异常处理分支。而Skill架构下，这件事变成三步：1）写一个新的query_inventory_v2Skill，实现新接口；2）在Agent配置中，把旧Skill名query_inventory_v1替换为新名；3）运行回归测试。全程不到20分钟，且所有改动都在一个文件内，Code Review一目了然。

提示：不要试图用“更好的提示词”去修复架构缺陷。我见过团队花三个月优化ReAct提示词，想让Agent更鲁棒地处理错误，结果只是把崩溃点从“API失败”推迟到“模型误判错误类型”。真正的鲁棒性来自分层：Skill层负责处理确定性错误（网络、格式、权限），Agent层只处理不确定性推理（该调哪个Skill、如何组合结果）。这是软件工程里“关注点分离”原则在AI时代的必然回归。

2.2 Skill驱动架构的四大设计支柱，每一条都踩过坑

基于上述教训，我们提炼出构建可靠Agent-Skills体系的四个不可妥协的设计支柱。它们不是理论推导，而是从三次项目重构中抠出来的经验：

支柱一：Skill必须是纯函数（Pure Function）
这不是指编程语言里的pure function，而是指行为契约上的纯净性：给定相同输入、相同环境（如配置、密钥），Skill必须产生完全相同、可预测的输出。这意味着Skill内部严禁有隐式状态（如缓存未声明的全局变量）、严禁依赖当前时间（datetime.now()必须作为参数注入）、严禁在执行中修改外部系统状态（写DB、发消息等副作用必须显式声明并隔离）。我们曾有个Skill叫send_notification，它内部悄悄记录了“今日已发送次数”用于限流，结果在分布式部署下，各实例计数不一致，导致通知时有时无。后来我们把它拆成两个Skill：check_rate_limit（纯函数，输入用户ID和时间窗口，输出是否允许）和send_notification_raw（纯函数，输入内容和接收方，输出发送结果）。副作用被推到最外层，由统一的Orchestrator管理。

支柱二：Skill必须自带契约（Contract）
契约不是口头约定，而是机器可读的强制规范。我们强制每个Skill提供三样东西：

• Input Schema：用JSON Schema定义合法输入，精确到字段类型、长度、枚举值。例如extract_invoice_amount的输入Schema会规定pdf_content必须是base64字符串，且长度<10MB；currency字段必须是["CNY", "USD", "EUR"]之一。
• Output Schema：同样用JSON Schema，且必须包含success: boolean字段。成功时data字段承载业务结果；失败时error_code（预定义枚举）和error_message（面向开发者的调试信息）必须存在。
• Side Effects Declaration：一个YAML清单，明确列出该Skill可能触发的所有外部操作，如- write_to_db: orders_table、- send_http_request: https://api.payment.com/v1/charge。这不仅是文档，更是安全审计的依据——CI流水线会扫描所有Skill的Side Effects，自动拦截未经审批的send_email调用。

支柱三：Skill生命周期必须独立于Agent
Skill不是Agent的子程序，而是可独立部署、独立版本、独立监控的微服务。我们采用“Skill Registry”模式：所有Skill打包为Docker镜像，推送到私有Registry，通过统一API网关暴露。Agent不直接调用Python函数，而是通过HTTP POST向/skills/extract_contract_clauses:1.2.0发起请求。好处立竿见影：

• 版本回滚：1.2.0版出问题，Agent配置里把版本号改成1.1.3，5秒生效，无需重启Agent服务；
• 灰度发布：新Skillsummarize_meeting_v2上线后，先让10%的Agent流量走它，监控成功率、延迟、错误码分布，达标后再全量；
• 资源隔离：某个Skill因PDF解析内存泄漏，只会拖垮自己的容器，不会让整个Agent进程OOM。

支柱四：Skill组合必须通过显式编排（Orchestration），而非隐式推理
这是最容易被忽视，也最致命的一条。很多团队以为“让Agent自己决定调哪个Skill”很酷，结果换来的是不可控的组合爆炸。我们的做法是：Agent的核心职责，仅限于根据用户输入，从预定义的Skill Flow图中，选择一条最短、最确定的执行路径。Flow图是静态的、可审查的、带业务语义的。例如“处理退货请求”这个场景，Flow图只有三条路径：

1. validate_return_request→check_inventory_stock→generate_refund_order
2. validate_return_request→flag_high_risk_customer→escalate_to_human
3. validate_return_request→return_policy_violation→send_rejection_notice
   Agent的任务，就是用分类模型（轻量级，如DistilBERT微调）判断用户输入属于哪一类，然后严格按图索骥。我们禁止Agent在Flow图之外“自由发挥”，所有新路径都必须走产品评审+Flow图更新+全链路测试的流程。这牺牲了一点“灵活性”，但换来了99.99%的可预测性和可审计性。

3. 核心细节解析：从零开始定义一个Production-Ready Skill

3.1 Skill的物理形态：为什么我们坚持用HTTP API + OpenAPI，而不是SDK或Framework绑定

当团队第一次讨论“Skill怎么实现”时，有人提议用LangChain的Tool类，有人建议封装成Python包供Agent import。我们花了整整一天做对比实验，结论很明确：必须采用独立HTTP服务 + OpenAPI 3.0规范。原因不是技术教条，而是四个硬性生产需求倒逼的结果：

第一是语言无关性。我们的Agent核心用Python，但“语音转文字”Skill由另一个团队用Rust开发（追求低延迟），而“财务合规检查”Skill则调用某第三方Java微服务。如果强制所有Skill写成Python Tool，要么Rust团队要写Python胶水层（性能损耗），要么Java团队要暴露JVM接口（安全风险）。HTTP API是唯一被所有语言、所有云环境、所有安全策略广泛支持的通用协议。我们甚至用curl手动测试过每个Skill的健康端点，这是任何SDK都无法提供的底层可控性。

第二是部署弹性。某次大促期间，“生成营销文案”Skill的QPS暴涨10倍，我们只需在K8s里将它的副本数从3扩到12，Agent完全无感。如果是SDK模式，扩容意味着要重新打包整个Agent镜像，再滚动更新——这在高峰期是不可接受的风险。HTTP服务的水平伸缩，是云原生基础设施最成熟的自动化能力。

第三是安全边界清晰。每个Skill服务运行在独立的Pod里，我们通过Istio Service Mesh实施细粒度策略：extract_piiSkill只能访问>{ "type": "object", "required": ["user_input", "session_context"], "properties": { "user_input": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "用户原始输入文本，已做过基础清洗（去除控制字符、多余空格）" }, "session_context": { "type": "object", "required": ["user_id", "device_type", "language"], "properties": { "user_id": { "type": "string", "pattern": "^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$", "description": "UUID v4格式，用于关联用户历史" }, "device_type": { "type": "string", "enum": ["mobile", "desktop", "tablet", "voice_assistant"], "description": "设备类型，影响回复长度和格式" }, "language": { "type": "string", "enum": ["zh-CN", "en-US", "ja-JP", "ko-KR"], "description": "用户首选语言，Skill必须据此返回对应语言的错误信息" } } }, "metadata": { "type": "object", "additionalProperties": true, "description": "预留字段，供未来扩展，如语音识别置信度、输入来源渠道等" } } }

这个Schema看似复杂，但每一行都是为了解决一个真实痛点：

• minLength/maxLength：防止恶意超长输入耗尽Skill内存，也避免Agent传入空字符串导致Skill崩溃；
• patternforuser_id：确保下游服务拿到的ID格式统一，不用再做正则校验，减少重复逻辑；
• enumfordevice_typeandlanguage：强制Agent在调用前必须做一次语义理解，把模糊的“手机”、“iPhone”、“iOS”都映射到标准枚举值，堵死了因字符串拼写差异导致的路由错误；
• additionalProperties: trueinmetadata：为未来埋点留白，但明确告知调用方“这里可以加，但别乱加”，避免metadata变成垃圾场。

输出Schema同样严苛。parse_user_intent的输出必须是：

{ "type": "object", "required": ["success", "intent", "confidence_score"], "properties": { "success": {"type": "boolean"}, "intent": { "type": "string", "enum": ["ask_refund", "check_status", "complain_service", "praise_product", "unknown"] }, "confidence_score": { "type": "number", "minimum": 0.0, "maximum": 1.0, "multipleOf": 0.01 }, "fallback_reason": { "type": "string", "description": "仅当 success=false 时存在，说明为何无法识别意图" } } }

关键点在于confidence_score的multipleOf: 0.01——这强制Skill返回两位小数的置信度（如0.92），而不是浮点数0.9199999999999999。Agent侧的阈值判断（如if confidence_score > 0.85）才能稳定可靠。我们吃过亏：早期一个Skill返回float32，在不同CPU架构上计算结果有微小差异，导致在A服务器上0.851被判定为高置信，在B服务器上却成了0.849被降级，引发一致性问题。

3.3 Side Effects声明与治理：让每个Skill的“破坏力”都透明可见

Side Effects（副作用）是Skill最危险也最重要的部分。一个Skill声称自己“安全”，却在后台偷偷删了数据库，这是灾难。我们的治理策略是“声明即契约，契约即法律”：

第一步：强制声明
每个Skill的/openapi.json中，必须有一个x-side-effects扩展字段，以YAML格式列出所有可能的副作用。例如process_paymentSkill的声明：

x-side-effects: - type: "write_to_database" target: "payments" description: "插入支付记录，包含金额、币种、状态" - type: "send_http_request" target: "https://api.payment-gateway.com/v2/charge" description: "向支付网关发起扣款请求" - type: "send_email" target: "customer@domain.com" description: "向客户发送支付成功通知"

注意，target字段必须精确到最小操作单元：不是“写数据库”，而是“写payments表”；不是“发邮件”，而是“发给customer@domain.com”。这为后续审计提供了原子粒度。

第二步：自动化拦截
我们在CI流水线中加入一道门禁：所有提交的Skill代码，必须通过side-effect-scanner工具扫描。该工具会：

• 解析x-side-effects声明；
• 静态分析Skill源码（Python AST或Rust AST），查找所有可能触发副作用的代码模式（如requests.post、cursor.execute、smtplib.sendmail）；
• 比对两者是否一致。若发现代码里有os.remove("/tmp/cache")但声明里没提delete_file，则CI直接失败，并给出精准行号。

第三步：运行时沙箱
即使声明和代码一致，我们也不信任。所有Skill容器启动时，都加载一个eBPF沙箱规则：

• 禁止任何execve系统调用（杜绝执行shell命令）；
• 限制connect系统调用的目标IP和端口，只允许连接白名单内的服务（如payment-gateway:443,db-main:5432）；
• 监控write系统调用，若向/etc/或/root/目录写入，立即kill进程并告警。

这套组合拳下来，我们实现了“所见即所得”：你在OpenAPI里看到的副作用，就是这个Skill在生产环境里唯一能做的坏事。没有隐藏通道，没有意外惊喜。

4. 实操过程：手把手搭建一个可上线的extract_contract_clausesSkill

4.1 技术选型与环境准备：为什么选FastAPI + Pydantic + Unstructured，而不是LangChain

搭建一个Production-Ready Skill，技术栈选择不是比谁新，而是比谁稳、谁薄、谁易维护。我们最终选定：FastAPI（Web框架） + Pydantic（数据验证） + Unstructured（PDF解析） + PostgreSQL（元数据存储）。这个组合看起来平平无奇，但每一个选择背后，都是对生产环境的敬畏：

• FastAPI：它不是因为“快”而被选中（虽然确实快），而是因为它的类型驱动开发范式与Skill契约完美契合。Pydantic模型直接定义Input/Output Schema，FastAPI自动生成OpenAPI文档、自动做输入校验、自动返回结构化错误（如422 Unprocessable Entity带详细字段错误）。我们不需要写一行校验代码，错误处理就已内建。相比之下，Flask需要手动request.get_json()再try/except，Express.js的Joi校验库配置繁琐，而LangChain的Tool类根本没有输入校验机制。

• Pydantic：它是契约的物理载体。我们把前面定义的JSON Schema，直接翻译成Pydantic V2模型：

from pydantic import BaseModel, Field, field_validator from typing import List, Optional, Literal class ContractClause(BaseModel): clause_id: str = Field(..., pattern=r'^[A-Z]{2}-\d{4}-\d{3}$', description="条款ID，如'ND-2024-001'") clause_type: Literal["confidentiality", "payment", "termination", "liability"] = Field(..., description="条款类型") content: str = Field(..., min_length=10, max_length=5000, description="条款正文") page_number: int = Field(..., ge=1, le=1000, description="所在页码") class ExtractInput(BaseModel): pdf_content: bytes = Field(..., description="PDF文件二进制内容") pdf_filename: str = Field(..., pattern=r'^[a-zA-Z0-9._-]+\.pdf$', description="PDF文件名，必须以.pdf结尾") target_language: Literal["zh-CN", "en-US"] = Field(default="zh-CN", description="输出语言") class ExtractOutput(BaseModel): success: bool = Field(..., description="是否成功") data: Optional[List[ContractClause]] = Field(default=None, description="提取的条款列表") error_code: Optional[str] = Field(default=None, description="错误码，仅当success=False时存在") error_message: Optional[str] = Field(default=None, description="错误信息，仅当success=False时存在")

这段代码，既是运行时的数据模型，也是/openapi.json的源头。field_validator可以添加自定义逻辑，比如@field_validator('pdf_content') def check_pdf_size(cls, v): if len(v) > 10 * 1024 * 1024: raise ValueError('PDF size exceeds 10MB')——这比在OpenAPI里写maxLength更灵活，能做实际的字节计算。

• Unstructured：我们试过PyPDF2、pdfplumber、pdfminer，甚至自己写OCR pipeline。最终Unstructured胜出，不是因为它最准，而是因为它最可控、最可调试。它把PDF解析拆成清晰的Pipeline：partition_pdf（布局分析）→clean（文本清洗）→chunk（分块）。每个环节都有参数可调，且能输出中间结果。当某个PDF解析失败时，我们能精确指出是“布局分析没识别出表格边框”，而不是笼统地说“解析失败”。更重要的是，Unstructured的partition_pdf函数，输入是bytes，输出是结构化的Element列表（含text,category,metadata），这与我们的ContractClause模型天然契合，转换代码只有3行。

• PostgreSQL：它不处理PDF，只存Skill的元数据和审计日志。每条extract_contract_clauses调用，无论成功失败，都会在skill_audit_log表里记一笔：request_id,input_hash（PDF内容SHA256）,output_hash,duration_ms,error_code,created_at。这让我们能回答所有灵魂拷问：“这个错误是偶发还是持续？”、“哪些PDF文件总是失败？”、“这个Skill的P99延迟是多少？”。没有日志，就没有真相。

实操心得：不要在Skill里做“智能”决策。我们曾有个版本，想让Skill自动判断PDF是“采购合同”还是“保密协议”，再用不同规则提取。结果模型判断不准，导致大量条款漏提。后来我们砍掉这个“智能”，改为强制Agent在调用前，通过parse_document_typeSkill先识别类型，再把document_type作为参数传给extract_contract_clauses。Skill只做一件事：把指定类型的PDF，按指定规则，干净利落地提取出来。专注，才是生产力。

4.2 核心代码实现：从PDF到结构化条款的7步精炼流水线

一个健壮的Skill，代码不在多，而在每一步都经得起推敲。extract_contract_clauses的主逻辑，我们严格控制在7个原子步骤内，每步都有明确的输入、输出、失败处理：

Step 1: 输入校验与预处理
接收FastAPI传来的ExtractInput模型，首先做两件事：

• 计算pdf_content的SHA256哈希，作为本次请求的唯一指纹，存入审计日志；
• 检查pdf_content是否真的是PDF：读取前4字节，必须是%PDF。如果不是，直接返回error_code: "INVALID_PDF_HEADER"。这一步过滤了99%的误传文件（如用户上传了.docx却改名为.pdf）。

Step 2: 大小与页数限制
调用fitz.open(stream=pdf_content)（PyMuPDF）快速获取PDF元数据：

• 若总页数>100，返回error_code: "PDF_PAGE_COUNT_EXCEEDED"；
• 若单页文本量预估>50KB（通过采样前三页计算平均密度），返回error_code: "PDF_TEXT_DENSITY_TOO_HIGH"。
  这避免了后续解析陷入“文本海洋”。

Step 3: 布局解析（Unstructured Pipeline）
调用partition_pdf(file=BytesIO(pdf_content), strategy="hi_res", hi_res_model_name="yolox")。strategy="hi_res"启用高精度OCR，hi_res_model_name指定YOLOX模型，专为合同类文档的表格、印章、手写签名优化。这一步耗时最长，但它是所有后续步骤的基础。

Step 4: 文本清洗与归一化
对Unstructured返回的Element列表，进行三轮清洗：

• 移除页眉页脚：基于element.metadata.page_number和element.metadata.coordinates，识别出所有出现在页面顶部/底部、字体小、内容重复（如“第1页 共10页”）的元素，直接丢弃；
• 合并断裂条款：合同条款常被PDF分割成多段（如“第1条 甲方责任”在一页，“1.1 付款义务”在下一页），我们用规则合并：若前一段以“第N条”开头，后一段以数字编号（“1.1”、“1.2”）开头，且间隔页数≤1，则合并；
• 统一编码：将所有文本转为UTF-8，替换掉PDF中常见的乱码字符（如``）为占位符[REPLACED]，并在error_message中记录。

Step 5: 条款识别与抽取
这是最核心的业务逻辑，我们不用大模型，而用规则+轻量模型：

• 规则引擎：匹配正则r'^第\s*[零一二三四五六七八九十百千\d]+\s*条\s*'识别条款标题；
• 轻量分类器：对每个标题后的文本块，用一个微调过的DistilBERT模型（仅2MB）判断是否属于confidentiality/payment等类型；
• 关键信息抽取：对payment类条款，用预定义正则r'金额.*?([¥$€]\s*\d+(?:,\d{3})*(?:\.\d{2})?)'提取金额；对termination类，用r'提前\s*(\d+)\s*日'提取通知天数。
  所有规则和模型都固化在Skill容器内，不依赖外部API，保证低延迟和高可用。

Step 6: 结构化输出与Schema验证
将抽取结果组装成List[ContractClause]，传给Pydantic模型ExtractOutput(data=clauses)。Pydantic会自动：

• 检查每个clause_id是否符合XX-YYYY-NNN格式；
• 验证page_number是否在PDF总页数范围内；
• 确保content长度在10-5000字符之间。
  若任何一项失败，Pydantic抛出ValidationError，FastAPI自动捕获，返回标准的422错误，带详细字段信息。

Step 7: 审计日志与响应
无论成功失败，都向PostgreSQL写入审计日志。成功时，output_hash是data列表的JSON序列化SHA256；失败时，output_hash为空，error_code和error_message填入。最后，FastAPI返回ExtractOutput模型实例，Pydantic自动序列化为JSON。

整个流程，代码量不到300行，但每一步都可测试、可监控、可替换。我们为每一步都写了单元测试，例如test_step4_merge_broken_clauses()，用模拟的Element列表验证合并逻辑是否正确。这才是工程化的底气。

4.3 部署与CI/CD：从Git Push到K8s Pod上线的5分钟自动化流水线

一个再好的Skill，如果部署流程繁琐，就会在生产中迅速腐化。我们的目标是：开发者git push后，5分钟内，新版本Skill自动上线，且通过全链路健康检查。流水线设计如下：

Stage 1: 代码扫描（1分钟）

• pylint检查代码质量（禁用too-many-arguments等不相关规则，聚焦undefined-variable,import-error）；
• bandit扫描安全漏洞（重点检查subprocess,eval,pickle）；
• side-effect-scanner验证声明与代码一致性；
• openapi-validator检查/openapi.json是否符合OpenAPI 3.0规范。

Stage 2: 构建与测试（2分钟）

• docker build -t skill-extract-contract-clauses:1.3.0 .；
• 运行容器内单元测试：docker run --rm skill-extract-contract-clauses:1.3.0 pytest tests/；
• 运行集成测试：启动一个临时PostgreSQL容器，运行test_integration_with_db.py，验证审计日志写入是否正确。

Stage 3: 镜像推送与K8s部署（1分钟）

• docker push registry.internal/skill-extract-contract-clauses:1.3.0；
• 更新K8s Helm Chart的values.yaml，将image.tag设为1.3.0；
• helm upgrade --install extract-contract-clauses ./helm-chart --namespace skills；
• K8s自动滚动更新Pod，旧Pod在新Pod就绪后才终止。

Stage 4: 健康检查与金丝雀（1分钟）

• 新Pod启动后，自动调用/healthz端点，检查数据库连接、Unstructured模型加载是否成功；
• 通过Istio VirtualService，将1%的流量切到新版本；
• Grafana看板实时监控新版本的success_rate、duration_p95、error_code_distribution；
• 若5分钟内success_rate< 99.5%，自动触发helm rollback，回退到上一版。

这个流水线，我们迭代了17次才稳定。最大的教训是：健康检查不能只看HTTP 200。早期我们只检查/healthz返回200，结果新版本Pod虽然起来了，但Unstructured的YOLOX模型加载失败，/skill端点一直500。后来我们把模型加载状态、数据库连接池健康度、甚至PDF解析缓存命中率，都纳入/healthz的检查项，才算真正靠谱。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 PDF解析类Skill的“玄学失败”：90%的问题出在字体和编码

PDF不是图片，也不是纯文本，它是描述性的页面布局语言。extract_contract_clauses上线初期，我们收到最多反馈是：“这个PDF能解析，那个PDF就失败”。排查了两周，发现90%的根源在字体嵌入和字符编码。以下是真实案例和解决方案：

问题1：中文PDF显示为方块或乱码
现象：PDF打开正常，但Skill解析出的文本全是□□□或????。
原因：PDF中嵌入了非标准中文字体（如“仿宋_GB2312”），而Unstructured默认的pdfminer后端不支持该字体的字形映射。
解决方案：强制使用pymupdf后端。在partition_pdf调用中，添加参数pdf_infer_table_structure=True, strategy="hi_res", pdf_backend="pymupdf"。PyMuPDF对中文字体兼容性极好，且能直接从PDF流中提取原始Unicode文本，绕过字体映射。

问题2：条款编号识别失败
现象：合同里明明写着“第1条