# AI 友好型网站文档总览

Summary: 这套文档定义一个面向 AI agent、爬虫和检索系统的静态知识站合同，包括站点结构、URL 规则、页面模板、JSON Schema 和检索契约。

Last updated: 2026-03-12  
Version: v1.0.0  
Docs URL: https://pingfanfan.github.io/OpenWebsite/docs/  
API URL: https://pingfanfan.github.io/OpenWebsite/api/pages/docs-home.json

## 站点契约

- 正文可在首次 HTTP 响应中直接获取。
- 每个主题同时提供 HTML、Markdown、JSON 三种表示。
- 每个 section 使用稳定 anchor。
- 每个页面显式声明更新时间、版本、来源和相关页面。
- JSON 输出遵守统一 schema。

## 文档地图

- `/docs/information-architecture/`: 定义站点层级、目录布局和页面职责。
- `/docs/url-conventions/`: 定义 slug、锚点、路径生命周期和版本语义。
- `/docs/page-template/`: 定义 HTML 骨架、元数据块和 section contract。
- `/docs/json-schema/`: 定义机器可验证的数据合同。
- `/docs/retrieval-contract/`: 定义抓取入口、切块规则和引用方式。

## 扩展模型

新增主题时需要同步新增：

1. `/docs/<slug>/`
2. `/raw/<slug>.md`
3. `/api/pages/<slug>.json`
4. `/api/site.json` 中的索引项
5. `llms.txt` 与 `sitemap.xml` 中的入口

## 发布检查单

- 确认页面无需脚本执行即可读取正文。
- 确认标题层级和锚点命名稳定。
- 确认页面带有更新时间和版本。
- 确认 JSON 能通过 schema 校验。