AI 友好型网站文档总览
这套文档把站点当成“机器可消费的知识系统”来设计。核心目标不是视觉呈现，而是稳定发现、直接抓取、可靠切块和可验证引用。
站点契约
任何被公开给 AI 使用的页面，都必须满足一组固定合同，否则后续索引、检索和引用会持续退化。
- 正文可在首次 HTTP 响应中获取，不依赖客户端脚本拼接。
- 每个主题提供 HTML、Markdown、JSON 三种同步表示。
- 每个 section 使用稳定、语义化、可预测的锚点。
- 每个页面显式声明更新时间、版本、来源和相关页面。
- JSON 输出遵守统一 schema，便于程序化验证。
文档地图
下面这些页面构成了这类站点的最小闭环：结构、命名、模板、Schema 和检索契约。
| 页面 | 说明 | 入口 |
|---|---|---|
| 信息架构 | 定义站点层级、内容类型、目录布局和页面职责。 | /docs/information-architecture/ |
| URL 规范 | 定义 slug、锚点、资源路径、废弃策略与版本语义。 | /docs/url-conventions/ |
| 页面模板 | 定义 HTML 骨架、元数据块、section contract 和链接关系。 | /docs/page-template/ |
| JSON Schema | 定义机器消费的字段、对象结构与最小验证要求。 | /docs/json-schema/ |
| 检索契约 | 定义抓取入口、切块边界、引用规则和常见失败模式。 | /docs/retrieval-contract/ |
扩展模型
新增主题时，不是只加一个 HTML 页面，而是要同时新增三种同步输出，并补到总索引里。
- 新增 docs 页面，路径形如 `/docs/<slug>/`。
- 新增同名 Markdown，路径形如 `/raw/<slug>.md`。
- 新增同名 JSON，路径形如 `/api/pages/<slug>.json`。
- 将新页面加入 `/api/site.json`、`llms.txt` 与 `sitemap.xml`。
- 为所有一级 section 设计稳定 anchor，例如 `#constraints`、`#examples`。
发布检查单
这份清单关注的是可抓取性和可维护性，而不是像素级视觉问题。
确认文档无需登录、无需脚本执行、无需滚动触发加载。
确认标题层级清晰，section id 稳定，摘要能单独成立。
确认页面显式提供日期、版本、原始来源和相关页面。
确认 JSON 文件能通过 schema 校验，索引入口能发现新页面。