Schema 通過但還不能發布：SKU.md 十類交付錯誤
BLOG / schema-valid-but-not-published-ready.mdx
診斷本機 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走完整流程，並在整理報價對應前閱讀穩定知識與即時商業資料。