跳到主要内容

第 1.9.2 节：用 Schema 版本和字段语义控制契约演进

Schema 版本和字段语义不能只停留在口头约定，还需要落实为字段、校验和失败处理。完成本节后，你应该能够把 Schema 版本和字段语义落成字段表、校验规则、错误处理和验收样例。

核心概念四层解释法​

数据契约​

层级解释
人话解释数据契约就是团队提前说清楚：这个字段叫什么、表示什么、允许哪些值、谁能用它、错了怎么办。
项目位置在客服工作台里，数据契约贯穿模型输出、工具调用、API（应用程序接口）、前端页面、日志和测试样例。
工程动作定义字段、枚举值、必填规则、默认兜底、版本号、错误状态、权限状态和追踪编号。
面试说法我不会让模型输出自由文本直接驱动流程，而是用数据契约把模型结果先校验，再交给工具、前端和日志系统使用。

Pydantic（数据校验库）​

层级解释
人话解释Pydantic（数据校验库）可以把“应该长什么样的数据”变成可检查的规则，不合格的数据不能悄悄流进系统。
项目位置在客服工作台里，它主要站在边界上：模型输出进入后端时、工具执行前、API 返回前、日志写入前。
工程动作用它表达字段契约、限制枚举、识别缺失字段、生成清晰错误，并把失败结果交给重试、降级、转人工或拒绝执行流程。
面试说法Pydantic（数据校验库）不是为了写得优雅，而是为了让 AI（人工智能）系统的边界数据可校验、可追踪、可验收。

schema（结构定义）版本​

层级解释
人话解释schema（结构定义）版本就是给数据契约打版本号，避免今天的字段规则悄悄破坏昨天的流程。
项目位置客服工作台的模型输出、工具结果和日志都应该记录 schema_version（契约版本）。
工程动作新增字段、修改枚举或改变状态含义时，要标记版本，并准备兼容策略和回归样例。
面试说法AI 项目的字段契约会随着业务演进，所以我会记录契约版本，避免模型、后端、前端和测试不同步。

validation（校验）​

层级解释
人话解释校验就是在数据进入下一步之前先检查：该有的有没有，该受限的有没有越界，该拒绝的有没有被放行。
项目位置用户问题被模型处理后、工具调用前、API 返回前、日志入库前都需要校验。
工程动作输出 validation_status（校验状态）、validation_error（校验错误）、retry_allowed（是否允许重试）和 fallback_action（兜底动作）。
面试说法我会把校验失败当成业务分支处理，而不是当成普通异常吞掉；尤其是工具和高风险动作，失败时宁可拒绝执行或转人工。

本章在客服工作台中的位置​

如果把客服 Agent（智能体）工作台拆成几层，本章位于“数据边界治理层”。

工作台层级主要职责本章关系
用户入口接收用户问题、登录身份、业务对象入口请求需要字段契约，不能只传一段自由文本。
模型理解层识别意图、风险、缺失信息和下一步动作模型输出必须校验后才能进入流程。
工具治理层判断工具、校验参数、控制权限和风险工具输入必须通过契约校验，失败时拒绝执行或兜底。
API 层给前端返回状态、草稿、错误和下一步请求响应字段要稳定，前端不能猜状态。
前端工作台展示回答、草稿、追问、工单和人工接管前端消费同一套 next_action（下一步动作）和 validation_status（校验状态）。
日志审计层记录追踪编号、工具、错误和人工处理日志字段和业务字段要能对齐复盘。
验收测试层验证正常、异常、越权和兜底路径测试样例应直接使用字段契约表达期望。

Pydantic（数据校验库）不是单独的一层业务能力，它更像每个边界处的检查闸门。它不负责决定业务应该怎么做，但它能阻止“不合格的数据”假装成“可以执行的业务动作”。

系统流程图​

这个流程图要强调 4 个判断：

读图重点：第一层校验决定结果能否路由，第二层校验决定工具能否执行；任何失败都不能伪装成成功，并必须留下 trace 日志。

  • 模型结构化输出不是直接可信数据，必须先校验。
  • 工具调用前还要单独校验 tool_name（工具名称）和 tool_args（工具参数）。
  • 校验失败不是只有“报错”一种结果，而是进入重试、降级、转人工或拒绝执行。
  • 每条路径都要记录 trace_id（追踪编号），否则上线后无法复盘。

模块拆分​

在客服工作台里，数据契约不要散落在各个功能里。即使本章不写源码，也要知道模块边界应该怎么拆。

模块负责什么不应该负责什么
契约定义模块统一字段名、字段含义、枚举值、版本号和校验规则不写具体业务流程。
模型输出适配模块接收模型结构化输出，转换成系统内部可校验数据不直接调用工具。
校验与错误模块生成校验状态、错误原因、是否允许重试和兜底动作不吞掉错误，不伪造成功。
工具输入契约模块规定工具名称、参数、权限字段和风险等级不把高风险工具暴露成自由调用。
API 响应契约模块规定前端能看到的状态、回复草稿、错误提示和下一步动作不泄露内部错误和敏感字段。
日志契约模块记录追踪编号、契约版本、校验状态、工具、兜底和人工处理不记录密钥、完整隐私原文和无关敏感信息。
验收样例模块用业务样例固定字段期望和失败路径不只测成功样例。

这种拆分的好处是：后续你改 Prompt（提示词）、换模型、加工具、改前端页面时，不需要每一层重新解释字段含义。大家围绕同一份契约工作。

继续学习​