{
  "$schema": "https://pingfanfan.github.io/OpenWebsite/schema/knowledge-page.schema.json",
  "format": "knowledge-page",
  "id": "retrieval-contract",
  "url": "https://pingfanfan.github.io/OpenWebsite/docs/retrieval-contract/",
  "rawUrl": "https://pingfanfan.github.io/OpenWebsite/raw/retrieval-contract.md",
  "apiUrl": "https://pingfanfan.github.io/OpenWebsite/api/pages/retrieval-contract.json",
  "schemaUrl": "https://pingfanfan.github.io/OpenWebsite/schema/knowledge-page.schema.json",
  "title": "检索与抓取契约",
  "summary": "定义发现入口、切块边界、引用方式和失败模式。",
  "lastUpdated": "2026-03-12",
  "version": "v1.0.0",
  "audience": ["ai-agent", "crawler", "developer", "human"],
  "sourceOfTruth": "抓取、切块和回引链路",
  "tags": ["retrieval", "crawl", "chunking", "citation"],
  "sections": [
    {
      "id": "discovery",
      "title": "发现入口",
      "summary": "站点至少需要为通用爬虫和模型工具提供可枚举入口。",
      "content": [
        "通用入口包括 robots.txt 和 sitemap.xml。",
        "模型入口包括 llms.txt 和 llms-full.txt。",
        "程序入口包括 api/site.json，以及页内的 alternate links。"
      ]
    },
    {
      "id": "chunking",
      "title": "切块规则",
      "summary": "切块边界应由页面结构主动提供，而不是完全交给索引系统猜测。",
      "content": [
        "一个 section 只讲一个主题，摘要句放在节首。",
        "列表项尽量写成完整句，避免脱离上文后失去语义。",
        "表格不要承载唯一事实，正文中要有文字解释。"
      ]
    },
    {
      "id": "citation",
      "title": "引用规则",
      "summary": "回引时应优先精确到带 anchor 的 section URL。",
      "content": [
        "优先引用带 anchor 的文档 URL，例如 /docs/url-conventions/#anchor-rules。",
        "需要原始文本时优先提供 Markdown URL。",
        "需要结构化字段时优先提供 JSON URL 和 schema 链接。"
      ]
    },
    {
      "id": "failure-modes",
      "title": "常见失败模式",
      "summary": "这些问题会显著降低 AI 消费质量，即便人类页面仍然看似可用。",
      "content": [
        "正文藏在点击展开或滚动加载之后会导致抓取不完整。",
        "路径频繁变化且无映射会让旧引用和缓存立即失效。",
        "内容更新但日期和版本不变会削弱新鲜度判断。"
      ]
    }
  ],
  "relatedPages": [
    {
      "id": "url-conventions",
      "title": "URL 规范",
      "url": "https://pingfanfan.github.io/OpenWebsite/docs/url-conventions/"
    },
    {
      "id": "json-schema",
      "title": "JSON Schema",
      "url": "https://pingfanfan.github.io/OpenWebsite/docs/json-schema/"
    }
  ]
}