S34：为 Use-case Manifest 增加轻量 Validator

内容类型：预习教材（不代表已完成）
日期：2026-12-26
阶段：P2 · AI Systems Engineering 90
总路线：Day 124 / 360
周次：W5 · AI Platform Engineering & Golden Path
节奏：周六可选探索 / 补学
状态：教材已备；学习未完成
标签：manifest、validator、service-catalog、schema、optional

一句话定义

Manifest validator 用机器可读的轻量规则检查声明是否完整且内部一致，让平台尽早给出可解释反馈，但它不能证明用例安全、有效或适合上线。

学习目标

1. 能把 use-case manifest 分成身份、依赖、运行、风险和证据几个字段组。
2. 区分 schema validation、语义 validation、策略判定与运行时检查。
3. 能设计“错误、警告、建议”三类反馈，避免所有问题都变成阻断。
4. 理解 catalog entity 与部署配置的联系和边界。

核心知识

• Manifest 是期望状态声明，不是运行事实。它可以写 owner、modelRef、toolRefs、dataClass、riskTier、sloRef 和 evidenceProfile，但不能宣称某次运行已经满足 SLO。
• 结构校验检查类型、必填、枚举和格式；引用校验确认所指版本存在且状态允许；语义校验检查字段组合，例如高风险用例必须声明人工升级；策略判定还要加入 actor、purpose 等请求上下文；运行时检查处理当时的容量、secret 和依赖可用性。
• Validator 输出应包含稳定代码、字段路径、原因和修复提示。只返回 invalid 会把认知负担转移给用户。
• 过度严格的 schema 会冻结演进；过度宽松的自由文本则无法自动发现、比较与治理。可以用核心稳定字段加可版本化扩展字段。
• Catalog 将 manifest 转化为可发现实体，并建立 owner、system、component、API 与依赖关系；它不应该复制每个运行系统的全部状态。

机制与推导

一个轻量状态流可以是：

draft -> parsed -> structurally_valid
                 -> reference_checked
                 -> semantic_warnings
                 -> registered

校验器应尽量是纯函数：validate(manifest, catalogSnapshot) -> issues[]。每个 issue 包含 severity、code、path、message 与可选 suggestion。纯函数便于重复执行和解释，但引用检查使用的 catalog snapshot 必须记录版本或时间，否则同一 manifest 在不同时间可能给出不同结果。

版本演进可采用显式 apiVersion。新增可选字段通常向后兼容；删除字段、改变枚举语义或把可选改成必填可能破坏旧实体。迁移策略至少要回答：旧版本读多久、由谁迁移、失败怎样呈现、能否回滚。

最小练习或观察步骤

1. 从 S30 的 manifest 取一个合成样例；若未做 S30，可手写不超过 15 行的 JSON。
2. 定义五条规则：owner 必填、modelRef 有版本、toolRefs 不重复、高风险声明 approval、数据分类属于枚举。
3. 为每条规则写 code/path/message，再区分 error、warning、suggestion。
4. 构造三个小反例：缺 owner、引用已废弃模型、高风险但无人工路径；只观察输出。
5. 画 manifest→validator→catalog→runtime 的关系，标明 runtime 事实不应回写覆盖声明。
6. 周六练习完全可跳过；不需要安装 portal、创建 CI gate 或补齐生产 schema。

常见误区与边界

• 把通过 schema 校验写成“用例合规/安全/高质量”。
• 把动态容量、在线授权或模型可用性固化进静态 manifest。
• 错误消息只暴露内部堆栈，用户不知道哪个字段怎样修复。
• 每个团队随意扩展同名字段，久而久之 catalog 无法比较实体。
• validator 自动修正高风险字段却不留下原值与变更证据。
• 本日是可选探索，完成与否不影响 W5 学习；没有运行就不填写校验结果。

系统 / 金融 / Web3 场景连接

金融用例 manifest 可声明 dataClass: restricted、purpose: aml-investigation 与 approvalMode: supervisor。Validator 能检查字段组合完整，却不能判断某个具体调查是否具有合法目的。Web3 工具 manifest 可声明支持链、只读/写入能力、签名要求和最大价值范围；schema 能阻止漏填 chain ID，却不能证明智能合约本身没有风险。

自检问题

1. 结构、引用、语义、策略与运行时校验的上下文有什么不同？
2. 为什么 catalog snapshot 版本会影响可复现性？
3. 什么字段适合成为 error，什么更适合 warning？
4. manifest 为什么不能记录“当前服务健康”？

专业课程对齐

• 阅读 Backstage 官方文档 中 Descriptor Format 与 Software Catalog 概念，重点观察 apiVersion/kind/metadata/spec 如何区分通用身份与实体专有声明。
• 阅读 Kubernetes 官方文档 的 API concepts 与 declarative management 概览，关注期望状态、API 版本和 controller 观察之间的关系，不要求搭建集群。
• 阅读 OpenAPI Specification 的 Schema Object 和版本说明目录，将字段约束、描述和兼容性思想映射到本日 manifest，而非编写完整 API。

深入学习提示

先写反例，再写规则，能避免 validator 沦为字段清单。深入时分别标注“静态可知”“需要目录快照”“需要请求上下文”“只能运行时知道”。若一条规则需要访问许多在线系统，应考虑它是否真的属于 validator。保持练习小而可解释，不把可选探索升级成强制 gate。

学后填写区

• 实际选择的 manifest 字段：
• 三类校验及示例：
• 一个兼容性风险：
• 未运行或未验证的部分：
• 下次想继续的问题：