BLOG / schema-valid-but-not-published-ready.mdx
Schema 通过但还不能发布：SKU.md 十类交付错误
诊断本地 Schema 成功到线上有效资源之间的十类精确失败，并提供可重复的修复流程。
文档通过 Schema 校验，仍可能在线上发布时失败。本地解析器看不到公开交付新增的 HTTP、身份、正文、链接、版本和文档图合同。
SKU.md 是由商家托管的商品发现与稳定商品知识：agent 可以找到商品、理解有来源的事实，并知道去哪里复查实时商业状态；它不是新的结账协议。
十类交付错误
| # | 失败类型 | 确定性检查 |
|---|---|---|
| 1 | 状态码错误 | 要求精确 HTTP 200 |
| 2 | 发生跳转 | 禁止自动跟随，并要求请求 URL 不变 |
| 3 | MIME 错误 | 要求带合法可选参数的 text/markdown |
| 4 | Soft fallback | 拒绝以成功状态返回的通用 HTML 或首页字节 |
| 5 | canonical 错误或缺失 | frontmatter canonical 必须等于请求 URL |
| 6 | 正文或派生内容不一致 | 对比已接受字节与正文/frontmatter 对齐 |
| 7 | 链接损坏 | 安全抓取必需链接资源 |
| 8 | parent 链或发现损坏 | 从 /sku.md 有界遍历并核对 parent |
| 9 | 版本错误 | 要求目标 sku.md/0.10-draft 合同与 Schema |
| 10 | 跳过线上验证 | 运行 published_resource 和 document_graph |
这里严格保持十类。超时、跳转次数、最大字节、私网拦截与遍历深度，是安全执行这些检查的限制，不是合并错误类别或跳过检查的理由。
故障排查流程
- 禁止跳转地请求精确 URL，遇到非 200 立即停止。
- 检查
Content-Type，拒绝 HTML fallback 与无效 UTF-8。 - 安全解析 frontmatter，再比较 canonical、语言、文档类型和版本。
- 对比线上响应、已接受字节与派生正文。
- 有界跟随同源链接，检查 parent、canonical 与发现。
- 保存线上报告，并在路由、CDN 或内容变化后重跑。
传输层失败时，不要靠放松文档 Schema 来修复。应直接处理发生故障的那一层。
为什么常见本地检查会漏掉
编辑器可以验证 YAML 和 JSON Schema，却不发 HTTP 请求；静态构建能生成正确字节，生产 /sku.md 却可能用 200 返回品牌 404；浏览器会无声跟随 301；CDN 也可能继续提供旧文件。
| 本地信号 | 隐藏线上风险 |
|---|---|
| Schema 通过 | URL、状态、MIME 或 canonical 错误 |
| 浏览器看起来可读 | 跳转或 HTML 兼容视图 |
| 一个商品 URL 可用 | 根 parent 或同级文档图损坏 |
| 部署命令完成 | 缓存或转换后的字节 |
修复时保住最后有效版本
先生成并验证，再原子替换已接受字节；新文档或路由失败时保留最后有效资源。未知资源应返回精确 404，不能 soft fallback。v0.10 合规范围把离线、单资源和文档图证据分开，避免把部分结果误写成完成。
延伸阅读
按照发布第一份 SKU.md走完整流程，并在映射报价前阅读稳定知识与实时商业数据。