# SKU Markdown Specification v0.8-draft

## 0. 文档状态

SKU Markdown（简称 **SKU-MD**）是一项实验性的社区提案。它不是搜索排名信号、访问控制协议或交易执行协议，也没有获得搜索引擎、模型厂商或商务平台的默认支持。

本规范定义三种由商家域名自主托管的文档：

1. 根目录 `/sku.md`：轻量商品目录与商务能力发现清单；
2. 可选的 `partition_index`：大型目录的分区发现清单；
3. 商品级 `*.sku.md`：覆盖一个商品组及其一个或多个 Variant/SKU 的可验证商品知识文档。

SKU-MD 的定位是：

> A domain-hosted discovery and product-knowledge format for AI shopping assistants and commerce agents.

它连接可阅读网页与实时商务协议，但不取代 Product JSON-LD、Merchant Feed、Sitemap、`llms.txt`、WebMCP、MCP、ACP、UCP、商家 API 或 Checkout。

规范性关键词 **MUST**、**MUST NOT**、**REQUIRED**、**SHOULD**、**SHOULD NOT** 和 **MAY** 按 RFC 2119 与 RFC 8174 的含义解释。

### 0.1 效果边界

截至 2026 年 7 月，规范维护者尚未发现主流 AI 产品公开承诺默认发现、抓取或采信 SKU-MD。发布 SKU-MD 不保证增加曝光、引用、推荐、GEO/AEO/SEO 排名或转化。

SKU-MD 的设计目标是在被正确发布和消费时，提高商品数据的：

- 实体映射准确性；
- 来源可追溯性；
- 动态报价新鲜度感知；
- 事实、声明和限制之间的边界清晰度；
- 从静态知识进入实时商务接口时的安全性。

它不保证模型输出、引用、推荐、排名或交易行为一定正确。任何宣传材料、生成向导或 Quick Start MUST NOT 暗示：

```text
已被主流 AI 产品默认抓取或采信
保证提升 GEO、AEO 或 SEO 排名
发布后即可被 AI 自动下单
usage_preferences 能技术强制模型行为
```

### 0.2 v0.7 相对 v0.6 的变化

v0.7 是纠错与一致性收敛版本，不新增新的商品业务域：

- 将普通商品页验证与结构化实时查询拆分为 `live_verification` 和 `live_lookup`；
- `live_lookup` 必须引用已声明的 `capability_id` 或 `profile_id`，并只允许 `catalog_lookup` 或 `checkout`；
- 商品文档顶层 `content_language` 升级为 MUST，`market` 只保留国家与币种；
- 正式加入 `representations`，修复规范与严格 Schema 的冲突；
- `product` 增加共享 `brand`、`description` 与 `media`；
- 商品知识必须至少包含一个非空集合；
- GTIN 结构限制为 8、12、13 或 14 位，并建议校验 GS1 校验位；
- Catalog entrypoint 新增 `html` 格式；JSON Lines 示例不再声明未注册的 `application/jsonl` 媒体类型；
- 明确 JSON Schema Format Assertion、BCP 47 语义校验和 Schema URL 映射；
- 默认根示例改为 `manifest-basic`，完整 Commerce 配置下沉为进阶示例；
- 明确字符串简写的默认语义、`verified_at` 的边界和 HTTP 新鲜度优先级。

旧版文档继续按各自版本的 Schema 解释。v0.8 消费方 SHOULD 在草案过渡期容忍 v0.5/v0.6/v0.7 文档，但不得把兼容解析标记为 v0.8 完全合规。

### 0.3 v0.8 相对 v0.7 的变化

**v0.8 是采纳工具版本，不是 Schema 变更版本**：不新增、不删除、不放宽任何必填
字段，Publisher Schema 与 v0.7 在结构上完全等价，只有 `schema_version` 与
Schema URL 更新。v0.7 已经把 `manifest-basic` 收紧到接近 `llms.txt` 的体量，
`manifest-commerce` 的 `authority` 完整性要求和 `product_document` 的
`knowledge` 非空要求都属于故意保留的安全纪律，不属于待优化的复杂度——v0.8
不再朝"继续精简正文字段"的方向走。

变化集中在两件事：把发布一份合规文档的**人工成本**进一步压低，以及补齐
v0.7 遗留的示例缺口：

- 新增第 20.5 节：从既有 `schema.org` Product/Offer JSON-LD 自动派生
  `manifest-basic` 草稿的工具规范，含字段映射表和禁止事项——目标是把接入
  成本从"回答几个问题"进一步压到"一次机械转换"，同时明确划定机器可以
  自动填什么、绝不能自动填什么；
- 明确 `offer_snapshot.live_lookup` 与 `live_verification` MAY 共存，并给出
  消费方的优先级规则（第 8.5 节）；
- 明确 `knowledge` 非空要求背后的设计意图：没有值得说的事实就不该发布
  `product_document`（第 9 节）；
- 第 6.5 节补充配套的 `live_lookup` 商品文档片段，填补 v0.7 只演示了
  `live_verification`、没有演示 `live_lookup` 完整用法的缺口。

v0.7 文档继续按 v0.7 Schema 解释。

---

## 1. 解决的问题与边界

电商网站同时面向三类使用方式：

| 层级 | 目标 | 典型机制 |
|---|---|---|
| 可阅读 Web | 发现并理解商品 | HTML、JSON-LD、Markdown、SKU-MD |
| 可查询 Web | 查询实时价格、库存和配送 | UCP Catalog、MCP、REST/GraphQL API |
| 可执行 Web | 加购、结账、支付和售后 | WebMCP、ACP/UCP Checkout、商家 API |

SKU-MD 主要解决：

- ProductGroup、Variant、SKU、图片和稳定 ID 的明确映射；
- 稳定商品事实与动态报价状态的分离；
- Facts、Claims、Disclosures、Guidance、Limitations 和证据的分层；
- 从公开商品知识进入实时目录或结账能力的发现；
- 为 AI 回答提供可引用、可审计、带时间上下文的数据快照。

SKU-MD 不解决：

- 抓取许可或访问控制；
- 搜索引擎排名；
- 实时库存锁定；
- 个性化价格、税费或运费计算；
- 用户授权、支付或不可逆交易；
- 对模型训练、引用或回答行为的技术强制。

---

## 2. 与相邻文件和协议的关系

| 文件或协议 | 主要职责 | SKU-MD 是否替代 |
|---|---|---|
| `robots.txt` | 抓取规则和 Sitemap 声明 | 否 |
| `sitemap.xml` | URL 批量发现 | 否 |
| `llms.txt` | 站点摘要和精选内容导航 | 否 |
| Product JSON-LD | 商品页面的标准结构化语义 | 否 |
| Merchant Feed | 平台商品分发 | 否 |
| 根目录 `sku.md` | 商品目录、市场、能力和权威来源入口 | 本规范定义 |
| 商品 `*.sku.md` | 商品组、变体、证据和报价快照 | 本规范定义 |
| WebMCP | 页面上下文中的可调用操作 | 否 |
| ACP/UCP/MCP/API | 实时查询、结账、支付和售后 | 否 |

`llms.txt` 与 `/sku.md` MAY 少量重复商家名和关键入口。任何一个文件都不得要求消费方必须先读取另一个提案文件。

建议在 `llms.txt` 中增加：

```markdown
## Product Catalog

- [SKU-MD catalog](https://shop.example.com/sku.md): Product discovery, variants, evidence, offer snapshots, and commerce interfaces.
```

---

## 3. 文件家族与部署

```text
https://shop.example.com/
├── robots.txt
├── llms.txt
├── sitemap-products.xml
├── sku.md
├── sku.json                         # 可选 JSON 镜像
├── sku-index.jsonl                  # 可选批量索引
├── sitemap-sku.xml                  # 可选商品知识文档 Sitemap
├── .well-known/ucp                  # 可选外部协议 Profile
├── catalog/zh-CN/CN/sku.md          # 可选分区索引
└── products/
    ├── example-product
    ├── example-product.sku.md
    └── example-product.sku.json     # 可选 JSON 镜像
```

### 3.1 根目录文件

- 路径 MUST 为 `/sku.md`；
- MUST 直接返回 HTTP `200`；
- MUST 不依赖 Cookie、登录或 JavaScript；
- SHOULD 保持 O(1) 大小，不随商品数量线性增长；
- MUST 至少提供一个 `catalog.entrypoints[]`；
- SHOULD 使用类似 `llms.txt` 的简洁 Markdown 链接正文作为降级入口。

### 3.2 商品文档

建议路径：

```text
/products/{handle}.sku.md
```

一个 `product_document` 表示一个商品或 ProductGroup，并包含 1–N 个可购买 Variant/SKU。它不是“一 SKU 一文件”。未来如需单变体文档，必须新增 `document_type`，不得改变 `product_document` 的含义。

### 3.3 可选表示

发布方 MAY 同时提供 JSON 镜像：

```yaml
representations:
  markdown: "https://shop.example.com/products/example.sku.md"
  json: "https://shop.example.com/products/example.sku.json"
```

规则：

- `representations.markdown` SHOULD 等于当前 Markdown 文档 `canonical`；
- JSON 与 Markdown MUST 由同一数据源和同一修订生成；
- JSON 镜像只包含 frontmatter 对应的数据对象，不包含 Markdown 正文；
- 冲突时发布方 MUST 修复生成流程，消费方不得仅凭文件格式猜测哪份权威。

---

## 4. 文档格式

每份文档由两部分组成：

1. YAML frontmatter：机器解析和一致性校验的规范数据；
2. Markdown 正文：frontmatter 的人类可读摘要和链接入口。

```text
---
YAML frontmatter
---

# H1 title
> Short summary

## Resource section
- [Label](https://example.com): Description
```

正文 MUST NOT 引入 frontmatter 或明确链接政策页面中不存在的新商品事实、建议、限制、价格、库存或政策。

### 4.1 YAML 安全解析

发布方和消费方 MUST 使用 YAML 1.2 安全子集，并在 JSON Schema 校验前执行：

- 重复键导致整份文档无效；
- 拒绝自定义标签、对象构造标签和 merge key `<<`；
- 拒绝锚点与别名；
- 只允许 JSON 可表达的数据类型；
- 设置文档大小、嵌套深度和集合项数量上限；
- 发布工具 SHOULD 规范化重新序列化后再执行 Schema 与语义校验。

JSON Schema 无法发现已被 YAML 解析器覆盖的重复键，因此这些规则属于必需的解析前检查。

---

## 5. 文档身份、Schema 和合规 Profiles

所有文档 MUST 在 frontmatter 顶层提供：

```yaml
schema_version: "sku.md/0.8-draft"
document_type: "catalog_manifest"
canonical: "https://shop.example.com/sku.md"
```

这些字段不得放入元信息包装对象。

以下字段一般 MAY 省略：

```yaml
generated_at: "2026-07-24T09:00:00Z"
revision: "catalog-20260724-0900"
content_language: "en-US"
generator:
  name: "sku-md-generator"
  version: "0.2.0"
  url: "https://sku.md/new"
```

例外：`product_document.content_language` MUST 在 frontmatter 中显式出现，不得仅依赖 HTTP Header。

`generator` 只描述实际生成软件，不代表规范背书或验证通过。手工编写 SHOULD 省略该字段。

### 5.1 Schema URL 映射

v0.8 的约定映射为：

```text
schema_version: sku.md/0.8-draft
→ https://sku.md/schema/sku-md/0.8/schema.json
```

发布工具 MUST 使用该严格 Publisher Schema，且 MUST 启用 JSON Schema Draft 2020-12 Format Assertion，或执行等价的 URI、date 和 date-time 验证。

### 5.2 `manifest-basic`

最低功能根清单。必填：

- 文档身份三字段；
- `profile: manifest-basic`；
- `merchant.name`、`merchant.site_url`；
- `catalog.mode`；
- 至少一个 `catalog.entrypoints[]`。

`manifest-basic` MUST NOT 声明 `authority`、`capabilities`、`protocol_profiles` 或 `identifiers`。

### 5.3 `manifest-commerce`

用于声明实时或计划中的 Agent Commerce 接口。除 Basic 字段外必须包含：

- `usage_preferences`；
- 完整 `authority`；
- 至少一个 `protocol_profiles[]` 或 `capabilities[]`；
- `identifiers.checkout_key`；
- 至少一个 `policies` 链接。

计划中或不可用的能力 MAY 被列出，但不得被设置为当前交易 Authority。

### 5.4 `partition-index`

必须包含：

- `document_type: partition_index`；
- `canonical`；
- `parent`；
- `scope.axis` 与 `scope.value`；
- 至少一个下一级 `catalog.entrypoints[]`。

MUST NOT 声明 `profile`。

### 5.5 `product-knowledge`

必须包含：

- `document_type: product_document`；
- `canonical`；
- 顶层 `content_language`；
- `parent`；
- `market`；
- `product`；
- 至少一个 `variants[]`；
- 至少一个非空知识集合；
- 每个 Variant 的 `offer_snapshot` 或 `live_offer`，二者只能选一个。

MUST NOT 声明 `profile`。

### 5.6 从 v0.6 迁移到 v0.7

1. 更新 `schema_version` 与 Schema URL；
2. 商品文档必须显式补充顶层 `content_language`；
3. 删除 `market.language`；
4. 普通商品页查询从 `live_lookup` 改为 `live_verification`；
5. 结构化 `live_lookup` 改为引用 `capability_id` 或 `profile_id`；
6. `live_lookup.function` 只允许 `catalog_lookup` 或 `checkout`；
7. 可选 JSON 镜像使用正式 `representations` 字段；
8. JSON Lines entrypoint 不再声明 `application/jsonl`；
9. 空 `knowledge` 或只含空数组的 `knowledge` 不再合规；
10. GTIN 结构长度更新为 8、12、13 或 14 位。

迁移工具不得把 `planned` Profile 自动升级为 `live`，也不得根据 Catalog Lookup 推断 Checkout。

### 5.7 从 v0.7 迁移到 v0.8

1. 更新 `schema_version` 与 Schema URL；
2. 不需要修改任何字段结构——v0.8 的 Publisher Schema 与 v0.7 等价。

已通过 v0.7 校验的文档，仅替换版本号即可获得 v0.8 合规状态。

---

## 6. 根目录 Catalog Manifest

### 6.1 商家身份

```yaml
merchant:
  name: "Example Shop"
  site_url: "https://shop.example.com/"
  legal_name: "Example Trading Ltd."
  organization_url: "https://shop.example.com/about"
  support_url: "https://shop.example.com/contact"
```

`merchant.id` MAY 省略；省略时消费方使用 `{site_url}#merchant`。显式声明后必须稳定。

### 6.2 Catalog 模式

允许：

- `discovery`：提供浏览入口，不声称完整机器索引；
- `indexed`：提供完整或分区机器索引、商品文档 Sitemap 或等价入口。

```yaml
catalog:
  mode: "indexed"
  product_count: 2180
  variant_count: 18640
  entrypoints:
    - type: "product_index"
      format: "jsonl"
      url: "https://shop.example.com/sku-index.jsonl"
    - type: "product_documents"
      format: "sitemap"
      url: "https://shop.example.com/sitemap-sku.xml"
      media_type: "application/xml"
```

`indexed` 必须至少包含 `product_index`、`product_documents` 或 `partition`。

Entry point 格式允许：

```text
html
markdown
json
jsonl
xml
sitemap
```

`media_type` MAY 省略。若声明，实际响应去除参数后的 `Content-Type` MUST 匹配。标准示例不得为 JSON Lines 声明未注册的 `application/jsonl`。

### 6.3 分区

多轴目录必须逐层嵌套，根清单 SHOULD 只列一个顶层轴：

```text
/sku.md
  → /catalog/zh-CN/CN/sku.md
    → /catalog/zh-CN/CN/tents/sku.md
```

分区正文精选商品不得超过 30 行，不得内联精确动态价格。

### 6.4 Markdown 正文

即使消费方不解析 YAML，也应该能通过标准链接继续发现资源：

```markdown
# Merchant name
> Short commerce summary.

## Catalog
- [Products](https://shop.example.com/collections/all): Storefront catalog.

## Policies
- [Returns](https://shop.example.com/policies/returns)
```

### 6.5 进阶 `manifest-commerce` 示例

以下示例假设 UCP Profile 已实际上线；如果状态只是 `planned`，Authority 必须使用 `storefront`、`checkout` 或 `unavailable`，不得指向该计划接口。

```yaml
profile: "manifest-commerce"

usage_preferences:
  model_training: "disallow"
  retrieval: "allow"
  citation: "requested"
  policy_url: "https://shop.example.com/policies/ai"

protocol_profiles:
  - id: "ucp-main"
    protocol: "ucp"
    url: "https://shop.example.com/.well-known/ucp"
    status: "live"

authority:
  identity: {source: "sku_document"}
  product_facts: {source: "sku_document"}
  offer_snapshot: {source: "sku_document"}
  live_price:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    fallback: "checkout"
  live_availability:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    fallback: "checkout"
  shipping_quote: {source: "checkout"}
  tax: {source: "checkout"}
  final_total: {source: "checkout"}
  payment: {source: "checkout"}
```

配套的商品文档片段（假设上面的 `ucp-main` Profile 确实处于 `live` 状态，且该
`product_document` 通过继承链能解析到声明它的根清单）：

```yaml
offer_snapshot:
  market: "US"
  price:
    amount: 4900
    currency: "USD"
    tax_status: "excluded"
  availability: "in_stock"
  observed_at: "2026-07-28T10:00:00Z"
  authority: "snapshot"
  live_lookup:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    identifier:
      type: "variant_id"
      value: "gid://shop.example.com/ProductVariant/100101"
```

`live_lookup.profile_id` MUST 精确匹配继承链上某一层声明的
`protocol_profiles[].id`；若引用的 Profile 状态不是 `live` 或 `beta`，发布
校验器 MUST 拒绝该文档（见第 18 节规则 11、12）。这与 `manifest-basic` 场景
下只能使用 `live_verification` 的 5.1/6.5 示例形成对照：**是否具备任何
`protocol_profiles[]` 或 `capabilities[]` 声明，直接决定商品文档能否使用
结构化的 `live_lookup`，还是只能退回普通网页级别的 `live_verification`**。

---

## 7. 商品文档

### 7.1 语言和市场

商品文档 MUST 明确：

```yaml
content_language: "zh-CN"

market:
  country: "CN"
  currency: "CNY"
```

文档语言只由顶层 `content_language` 表达，避免与 `market.language` 重复。每个报价的 `market` 与 `price.currency` 必须分别与文档市场国家和币种一致。

Schema 的语言正则只做基础语法筛选；发布校验器 MUST 使用完整 BCP 47 解析器，或明确声明并验证受支持子集。

### 7.2 商品组

```yaml
product:
  id: "gid://shop.example.com/Product/1001"
  item_group_id: "TSHIRT-001"
  title: "AirSoft T-Shirt"
  link: "https://shop.example.com/products/airsoft"
  brand: "Example Brand"
  description: "Regular-fit cotton T-shirt."
  attributes:
    - name: "fabric_weight"
      value: 180
      unit: "g/m²"
  media:
    - type: "video"
      url: "https://cdn.example.com/product-guide.mp4"
      title: "Product guide"
```

ProductGroup 层用于共享品牌、说明和通用媒体；Variant 只在不同于共享值时覆盖。

### 7.3 变体

每个 Variant MUST 包含：

- `id`；
- `sku`；
- `title`；
- 可购买 `link`；
- `offer_snapshot` 或 `live_offer`。

GTIN 如出现，必须是 GTIN-8、GTIN-12、GTIN-13 或 GTIN-14；发布校验器 SHOULD 验证 GS1 校验位。

### 7.4 媒体

- `image` 必须有非空 `alt`；
- `video` 必须有非空 `title`，并 SHOULD 有 `caption` 或 `transcript_url`；
- 尺寸必须为正整数；
- 通用媒体放 ProductGroup 层，颜色或型号特定媒体放 Variant 层。

---

## 8. 报价快照与实时状态

### 8.1 报价快照

```yaml
offer_snapshot:
  market: "CN"
  price:
    amount: 12900
    currency: "CNY"
    tax_status: "included"
  availability: "in_stock"
  inventory_signal: "normal"
  observed_at: "2026-07-24T08:25:00+08:00"
  refresh_after: "2026-07-24T08:40:00+08:00"
  authority: "snapshot"
```

金额 MUST 使用币种最小单位整数。

`tax_status` 允许：

```text
included
excluded
location_dependent
not_applicable
unknown
```

### 8.2 新鲜度

- `observed_at`：数据被读取或生成的时间，MUST；
- `refresh_after`：建议重新验证的时间，MAY；
- `offer_valid_until`：商家真实承诺报价有效的时间，MAY。

不得用“观察时间 + 缓存时间”伪造 `offer_valid_until`。

### 8.3 库存

`availability`：

```text
in_stock
out_of_stock
preorder
backorder
discontinued
unknown
```

`preorder` MUST 有 `availability_date`。

库存紧张必须写作：

```yaml
availability: "in_stock"
inventory_signal: "low"
```

### 8.4 普通网页实时验证

普通商品页不是 Catalog Lookup API。使用：

```yaml
live_verification:
  source: "storefront"
  url: "https://shop.example.com/products/example?variant=100101"
  identifier:
    type: "variant_id"
    value: "gid://shop.example.com/ProductVariant/100101"
```

`live_verification` 只表示重新打开公开页面检查显示状态，不代表机器可调用的结构化接口，也不得直接触发购买。

### 8.5 结构化实时查询

结构化查询必须引用继承链中已声明的能力或协议 Profile：

```yaml
live_lookup:
  source: "protocol_profile"
  profile_id: "ucp-main"
  function: "catalog_lookup"
  identifier:
    type: "variant_id"
    value: "gid://shop.example.com/ProductVariant/100101"
```

或者：

```yaml
live_lookup:
  source: "capability"
  capability_id: "catalog-api-main"
  function: "catalog_lookup"
  identifier:
    type: "sku"
    value: "TSHIRT-BLK-M"
```

规则：

- `source` 只能是 `capability` 或 `protocol_profile`；
- `function` 只能是 `catalog_lookup` 或 `checkout`；
- 引用对象必须存在且状态为 `live` 或 `beta`；
- 普通网页 URL 不得伪装成 `catalog_lookup`。

一个 `offer_snapshot` MAY 同时包含 `live_verification` 与 `live_lookup`：
前者面向只能访问普通网页的消费方，后者面向已经理解目标协议的消费方，二者
不冲突、也不互相替代。消费方 SHOULD 优先使用自己能够识别其 `protocol`/
`capability_id`/`profile_id` 的 `live_lookup`；只有在无法识别引用对象，或
该引用对象状态不可用时，才退回使用 `live_verification`。发布方提供两者
时，MUST 保证它们指向同一个 Variant（`identifier` 一致）。

### 8.6 仅实时报价

无法安全发布静态快照时 MAY 使用：

```yaml
live_offer:
  market: "US"
  authority: "live_lookup"
  lookup:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    identifier:
      type: "variant_id"
      value: "gid://shop.example.com/ProductVariant/100101"
```

一个 Variant 在 `offer_snapshot` 与 `live_offer` 中二选一。

---

## 9. 商品知识与证据

```yaml
knowledge:
  facts: []
  claims: []
  disclosures: []
  guidance: []
  limitations: []
  compatibility: []
```

`knowledge` MUST 至少有一个集合包含一项内容；只声明空数组不合规。

这条规则的设计意图：如果一个商品除了价格和库存之外，没有任何值得对 AI
说明的已验证事实、声明、披露、建议或限制，那么它就不该拥有一份
`product_document`——Product JSON-LD 与批量索引已经足以覆盖这种情况。
`knowledge` 非空不是为了让发布方凑数满足 Schema，而是"是否值得发布一份
商品知识文档"本身的价值门槛；自动化工具 MUST NOT 为了通过这条规则而生成
未经核实的内容（见第 20.5 节）。

### 9.1 Facts

每条事实 MUST 有稳定 `id`、`statement`、`source_url` 和 `verified_at`。

`verified_at` 只表示发布方在该日期确认陈述与所列来源一致，不表示第三方独立检测、实验室复测、监管认证或模型已完成事实核查。

用户评论、论坛帖子和模型推断不得写入 `facts`。

### 9.2 Claims

每条声明 MUST 标注：

```text
manufacturer
merchant
third_party
```

`third_party` MUST 有 `evidence_url`，`manufacturer` SHOULD 有。

### 9.3 Disclosures

字符串简写：

```yaml
disclosures:
  - "Keep away from open flame."
```

默认等价于：

```yaml
severity: "notice"
required_before_checkout: false
```

`warning`、`critical` 或 `required_before_checkout: true` MUST 使用结构化对象，不得使用字符串简写。

### 9.4 Guidance 与 Limitations

字符串 Guidance 默认 `asserted_by: merchant`。

字符串 Limitation 默认：

```yaml
category: "other"
severity: "notice"
```

安全、合规或证据相关内容 SHOULD 使用结构化对象。

`knowledge` MUST NOT 包含当前价格、库存、可购买颜色、促销、优惠码、运费、预计送达时间或临时活动规则。

### 9.5 Compatibility

```yaml
compatibility:
  - relation: "compatible_with"
    target_product_id: "gid://shop.example.com/Product/1050"
    note: "适配 XX 系列主机。"
```

允许：`compatible_with`、`requires`、`replaces`、`part_of_bundle_with`。

---

## 10. 使用偏好，不是访问权限

```yaml
usage_preferences:
  model_training: "disallow"
  retrieval: "allow"
  citation: "requested"
  policy_url: "https://shop.example.com/policies/ai"
```

它不提供访问控制、不构成模型厂商已接受的合同、不能撤回其他公开页面的可读取性、不能强制引用，也不取代 robots、认证、授权或双方协议。

---

## 11. 外部协议与商务能力

### 11.1 Protocol Profiles

协议已有权威发现 Profile 时 SHOULD 使用：

```yaml
protocol_profiles:
  - id: "ucp-main"
    protocol: "ucp"
    url: "https://shop.example.com/.well-known/ucp"
    status: "live"
```

SKU-MD 不复制外部 Profile 的版本、服务、传输、端点和 Schema。

### 11.2 Generic Capabilities

用于无权威 Profile 或页面运行时能力：

```yaml
capabilities:
  - id: "webmcp-storefront-tools"
    function: "browser_tools"
    protocol: "webmcp"
    status: "beta"
    discovery:
      mode: "page_runtime"
      scope: ["product", "cart"]
      page_url_patterns:
        - "https://shop.example.com/products/*"
        - "https://shop.example.com/cart"
      requires_user_presence: true
    access:
      mode: "page_runtime"
      authentication: "none"
```

页面工具的实际名称和输入输出 Schema 由页面运行时提供。

### 11.3 Functions

```text
catalog_lookup
cart
checkout
order_status
product_feed
browser_tools
```

### 11.4 Status

```text
live
beta
planned
deprecated
disabled
```

只有 `live` 与 `beta` 可被视为可用。缺少条目表示未声明，不等于 disabled。

### 11.5 Discovery 与 Access

- `well_known`、`directory`、`document` 必须有 URL；
- `page_runtime` 必须有 scope、页面模式和 `requires_user_presence: true`，且没有远程调用 URL；
- `public` 必须 `authentication: none`；
- `authenticated` 不得 `none`；
- 页面运行时 Access 必须是 `page_runtime` + `none`。

---

## 12. 数据权威层级

允许来源：

```text
sku_document
capability
protocol_profile
storefront
checkout
external
unavailable
```

规则：

- capability 来源必须有 `function` 和 `capability_id`；
- protocol profile 来源必须有 `function` 和 `profile_id`；
- external 必须有 HTTPS URL；
- 被引用对象必须存在且状态可用；
- 不可用时使用安全 fallback；
- 没有可用来源时，交易字段视为未知。

| 字段 | 允许来源 | 允许 fallback |
|---|---|---|
| identity / product_facts | sku_document、storefront、external、unavailable | sku_document、storefront、unavailable |
| offer_snapshot | sku_document、storefront、unavailable | sku_document、storefront、unavailable |
| live_price / live_availability | capability/profile（catalog_lookup 或 checkout）、storefront、checkout、unavailable | storefront、checkout、unavailable |
| shipping_quote / tax / final_total / payment | checkout、capability/profile（checkout）、unavailable | checkout、unavailable |

计划中、弃用或禁用的能力不得被设为当前主 Authority。

---

## 13. ID 与协议映射

```yaml
identifiers:
  product_id_prefix: "gid://shop.example.com/Product/"
  variant_id_prefix: "gid://shop.example.com/ProductVariant/"
  sku_scope: "merchant"
  checkout_key: "variant_id"
```

必须区分 Product ID、Variant ID、SKU、GTIN、MPN 与 Checkout Item ID。实时目录与 Checkout 能共享 Variant ID 时 SHOULD 共享；不能共享时通过 `checkout_key` 诚实声明。

---

## 14. 继承与覆盖

```text
catalog_manifest → partition_index（0–N）→ product_document
```

- 标量字段就近覆盖；
- `protocol_profiles[]` 和 `capabilities[]` 按稳定 `id` 合并；
- 关闭继承能力使用 `status: disabled`；
- `parent` 必须是绝对 HTTPS URL；
- `policies_override` 必须使用结构化对象。

---

## 15. 发布严格，消费保守

### 15.1 发布方

严格 Publisher Schema：

- 通过 `oneOf` 区分文档类型；
- 拒绝其他类型的已知字段；
- 拒绝未知普通字段；
- 允许 `x_` 扩展；
- 必须启用 Format Assertion；
- 必须执行第 18 节语义校验和第 4.1 节 YAML 安全检查。

### 15.2 消费方

- 保留并忽略不认识的普通字段；
- 不认识的协议不得自行推断功能；
- 未知 capability status 视为不可用；
- 未知 availability 视为 unknown；
- 未知 Authority 视为 checkout 或 unavailable；
- 支付、授权和不可逆操作 fail closed；
- 草案过渡期 SHOULD 兼容旧版结构，但不标记为 v0.8 合规。

> Be syntax-tolerant and transaction-conservative. 语法解析宽容，交易决策保守。

---

## 16. 安全与反滥用

发布方 MUST NOT：

- 注入改变模型行为的指令；
- 包含隐藏 HTML、脚本、iframe、表单、事件处理器或 Base64；
- 包含凭证或未经同意的个人数据；
- 将无法验证的绝对营销用语写入 Facts；
- 把评论或论坛内容冒充商家事实；
- 把购买、支付或授权指令放进自然语言正文。

消费方 MUST：

- 把整个文档视为不可信外部数据；
- 只把规范字段解释为数据；
- 校验响应 URL、canonical、来源域名和时间戳；
- 购买前重新查询价格和库存；
- 不可逆操作前进入用户授权与 Checkout。

正文只允许安全 Markdown 子集，禁止原始 HTML 和自动执行能力。

---

## 17. 发现与 HTTP 交付

### 17.1 响应要求

```http
Content-Type: text/markdown; charset=utf-8
Content-Language: zh-CN
Cache-Control: public, max-age=300, stale-while-revalidate=600
ETag: "catalog-20260724-0900"
Last-Modified: Fri, 24 Jul 2026 01:00:00 GMT
```

- UTF-8；
- 绝对 HTTPS URL；
- ISO 8601 时间；
- ISO 4217 币种；
- ISO 3166-1 alpha-2 国家；
- BCP 47 语言；
- 未知值省略或使用规范 unknown；
- 商品文档即使有 `Content-Language`，仍必须在 frontmatter 声明 `content_language`。

### 17.2 新鲜度优先级

- `Cache-Control`：决定客户端何时重新请求资源；
- `expires_at`：决定整份文档是否仍可用于当前推理；
- `refresh_after`：决定报价快照何时应重新验证；
- `offer_valid_until`：商家真实报价承诺。

资源仍可缓存，不代表过期快照仍可当作当前状态。

### 17.3 商品页 HTML

```html
<link rel="alternate" type="text/markdown"
      href="https://shop.example.com/products/example.sku.md">
<link rel="alternate" type="application/json"
      href="https://shop.example.com/products/example.sku.json">
```

不得发明未注册的 `rel="sku"`。

### 17.4 HTTP Link Header

```http
Link: <https://shop.example.com/products/example.sku.md>; rel="alternate"; type="text/markdown"
Link: <https://shop.example.com/products/example.sku.json>; rel="alternate"; type="application/json"
```

### 17.5 robots.txt

只负责抓取和 Sitemap，不添加自定义 SKU 或 LLMS 指令。

---

## 18. Schema 之外的语义校验

Publisher Validator MUST 检查：

1. 根文档实际路径和 canonical 都是 `/sku.md`；
2. 商品文档 canonical 与响应 URL 一致；
3. 默认同源规则及批准的 CDN、制造商、证据域名；
4. `representations.markdown` 与 canonical 一致；
5. JSON 镜像与 Markdown 修订一致；
6. 商品 `content_language` 与正文语言一致且是有效 BCP 47；
7. 报价市场和币种与文档 market 一致；
8. refresh/valid 时间晚于 observed；
9. compare-at 不低于当前金额；
10. live_verification 或 live_lookup 的 identifier 指向所在 Variant；
11. live_lookup 引用存在且可用的 capability/profile；
12. planned/deprecated/disabled 条目不得成为当前主 Authority 或 live lookup；
13. checkout_key 字段在所有可购买 Variant 上存在且唯一；
14. GTIN 校验位正确；
15. Facts、Claims、正文与证据不冲突；
16. knowledge 不含动态价格、库存、促销、运费和临时规则；
17. 正文不引入新事实；
18. capability/profile ID、Variant ID、SKU 和 Knowledge ID 唯一；
19. applies_to 引用可以解析；
20. parent 链无环路且最终到达根 manifest；
21. page_runtime 页面模式安全且要求用户在场；
22. entrypoint media_type 与实际 Content-Type 匹配；
23. partition/product 文档不含 profile；
24. knowledge 至少有一个非空集合；
25. `representations` 与严格 Schema 一致；
26. 执行 YAML 安全和 Prompt Injection 检查。

发布工具 SHOULD 提供：

```text
sku-md validate
sku-md inspect
sku-md convert --json
sku-md lint-security
```

---

## 19. 大小、新鲜度与生成

建议上限：

```text
/sku.md                     ≤ 256 KiB
单个分区索引               ≤ 1 MiB
单个商品文档               ≤ 100 KiB
单个分区正文精选商品       ≤ 30 行
```

商品页面、JSON-LD、Merchant Feed、Sitemap、SKU-MD 和实时 Catalog 必须来自同一商品数据源。不得人工独立维护多个价格库存副本。

---

## 20. 社区采用与治理

始终使用：

```text
proposal
draft
experimental
community specification
```

不得宣称 official standard、major LLM support 或 guaranteed ranking signal。

正式发布物 SHOULD 包含：

- README 和一页 Quick Start；
- `manifest-basic` 默认示例；
- 进阶 Commerce 和 Product 示例；
- 严格 JSON Schema；
- Parser 与 CLI Validator；
- valid、invalid、unsafe、forward-compatible 测试向量；
- Shopify、WooCommerce 和静态站适配器；
- 公开 Issue/Discussion。

版本继续保持 `x.y-draft`，直到至少两个独立生产方和两个独立消费方完成真实实现。

### 20.1 Quick Start 选择

首页第一个示例 MUST 是 `manifest-basic`。完整 Commerce 示例标注为进阶，不得使用 planned 能力作为门面 Authority。

### 20.2 测试向量

```text
tests/fixtures/
├── valid/
├── invalid/
├── unsafe/
└── forward-compatible/
```

每个 Invalid/Unsafe 样本应有 `.expected.json` 指明违反规则。

### 20.3 生成向导

商家人工确认 SHOULD 不超过五项。第一屏只询问店铺名、域名和目录入口；协议接入为可跳过的进阶设置。

### 20.4 与 llms.txt 桥接

工具 SHOULD 检测 `llms.txt` 并提供追加 Product Catalog 链接的补丁，但两种格式在协议层保持独立。

### 20.5 JSON-LD 自动派生

多数商品页面已经具备 `schema.org` Product/Offer JSON-LD——这是比人工问答
更接近零成本的数据源。发布工具 MAY 提供自动派生模式：读取页面已有的
Product/Offer JSON-LD，机械映射为 SKU-MD 字段，不要求任何人工确认即可产出
结构合规的 `manifest-basic` 草稿。

#### 20.5.1 字段映射

| JSON-LD 字段 | SKU-MD 字段 |
|---|---|
| `Product.@id` / `Product.url` | `product.id` / `product.link` |
| `Product.name` | `product.title` |
| `Product.brand.name` | `product.brand` |
| `Product.sku` / `Product.mpn` / `Product.gtin*` | `variants[].sku` / `mpn` / `gtin` |
| `Offer.price` / `Offer.priceCurrency` | `offer_snapshot.price.amount` / `currency` |
| `Offer.availability` | `offer_snapshot.availability`（按 8.3 节枚举映射，无法明确对应时使用 `unknown`） |
| `Offer.priceValidUntil` | `offer_snapshot.offer_valid_until` |
| 页面 `lang`/`hreflang` | `content_language` |
| `Offer.priceCurrency` + 站点地区 | `market.country` / `market.currency` |

#### 20.5.2 禁止事项

自动派生工具 MUST NOT：

- 把 `Product.description`、评论内容或任何 JSON-LD 自由文本字段自动写入
  `knowledge` 的任何集合（`facts`/`claims`/`disclosures`/`guidance`/
  `limitations`）——这类文本是营销或用户生成内容，不满足第 9.1 节对
  `facts` 来源可信度的要求；
- 在 `knowledge` 仍为空时自动发布文档——产物必须停留在草稿状态，等待至少
  一条经人工核实、附带 `source_url` 与 `verified_at` 的 `facts` 条目，
  才能进入发布流程（这也是第 9 节非空规则的直接应用）；
- 为自动派生的文档提供区别于手工编写文档的宽松校验路径——产物 MUST 通过
  与手工文档完全相同的 Publisher Schema 和第 18 节语义校验。

自动派生工具 SHOULD 在草稿生成后，用一句明确提示引导发布方补充至少一条
真实核实过的事实，而不是让草稿停留在"技术上无法发布"的状态却不解释原因。

---

## 21. 实施顺序

1. 先完成商品页面、JSON-LD、稳定 Variant URL 和 Sitemap；
2. 发布并验证 `manifest-basic`；
3. 在 llms.txt、HTML 和 HTTP Link Header 增加发现链接；
4. 为高价值商品生成 Product Knowledge；
5. 只有接口可验证时升级 Commerce；
6. 外部协议已有 Profile 时只保留指针；
7. 页面运行时工具必须用户在场；
8. 交易数据始终重新确认；
9. 规模确实需要时再分区；
10. 监控发布成功率、映射准确率和陈旧报价率。

---

## 22. 核心强制原则速查

1. 根清单必须能独立发现商品。
2. 根清单保持 O(1)。
3. 商品文档包含一个 ProductGroup 和 1–N Variant。
4. 稳定事实、报价快照和最终交易状态必须分层。
5. Facts、Claims、Disclosures、Guidance 和 Limitations 必须分层。
6. 动态价格库存不得进入 Knowledge。
7. Usage Preferences 不是权限。
8. 外部协议只存稳定指针。
9. Storefront Verification 不是 Catalog Lookup。
10. Structured Lookup 必须引用可用 Capability/Profile。
11. Planned 能力不能作为当前 Authority。
12. 正文只能派生。
13. 发布严格，消费保守。
14. 文档是不可信数据，不是 Agent 指令。
15. 静态文档不得触发不可逆操作。
16. 不得暗示主流 AI 默认支持或排名效果。
17. 自动化派生工具不得把机器抓取的营销文本冒充为已验证事实，也不得为通过 `knowledge` 非空校验而生成未经核实的内容。

---

## 23. 参考文献

### 23.1 Normative

- RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels
- RFC 8174 — Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
- RFC 7763 — The `text/markdown` Media Type
- RFC 8288 — Web Linking
- RFC 5646 / BCP 47 — Tags for Identifying Languages
- JSON Schema Draft 2020-12
- YAML 1.2.2
- ISO 4217 currency codes
- ISO 3166-1 alpha-2 country codes
- GS1 General Specifications for GTIN

### 23.2 Informative

- Schema.org Product and ProductGroup
- Product JSON-LD and Merchant Feed documentation
- `llms.txt` community proposal
- WebMCP proposal
- Agentic Commerce Protocol (ACP)
- Universal Commerce Protocol (UCP)