文档站点
翻译说明： 本页是与 英文源规格 一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。
状态
已接受。请参阅 ADR 0079。
决定
docs/ 目录是 pnpm 内的独立 VitePress 项目 工作区。 Markdown 仍然是事实的来源； VitePress 供应本地 开发服务器，静态构建，本地搜索索引，代码突出显示，以及 版本化的导航 shell。
该站点公开了两个区域设置入口点：
/— 英语优先的完整文档导航。/zh-CN/— 简体中文方向以及路径对路径伴侣docs/spec/下每个文档的页面。
对于根目录为 docs、docs/vercel.json 的 Vercel 部署 将 VitePress 构建输出声明为 .vitepress/dist 并启用 Vercel cleanUrls 路由。这会保留无扩展的链接，例如 /spec/README 和 /adr/README 在直接页面刷新后工作而不是变成静态 托管 404。
现有 spec/、adr/、project/ 和指南 Markdown 文件保持不变 因此存储库链接和评论历史记录保持稳定。中文规格页 生活在 docs/zh-CN/spec/ 下，相对路径与英语相同 来源。每个翻译的页面都链接到规范的英语页面并保留 代码、协议字段和标识符不变。
本地命令
pnpm docs:dev
pnpm docs:build
pnpm docs:preview
pnpm docs:check生产构建是静态的，不需要运行时服务。这 网站可能会在开发或部署期间加载 Google Fonts，但内容 和搜索索引由 VitePress 在本地生成。
pnpm docs:check 验证每个英文规范都有匹配的中文 Markdown 文件， 并且该配套文件同时满足以下全部条件：
- 有一级标题；
- 正文中含中文字符；
- 含
[英文源规格](/spec/<path>)规范来源链接； - 不残留未翻译占位符标记（该门禁以裸子串方式检索它，因此本页无法原样引用）；
- 表格形状与英文页面一致 —— 逐行比较
|单元格数量； - 围栏代码块数量与英文页面一致。
第 5 和第 6 条让该门禁是结构性的而非表面的：中文页面少了一个表格行或一个 代码块时，即使散文读起来完整也会被报告。该门禁由 .github/workflows/docs-check.yml 执行，覆盖应用 CI 工作流有意忽略的文档路径。 应把任何失败视为待补齐的镜像清单，并且不要在没有配套中文文件的情况下新增英文 规范。
pnpm docs:check 还会运行 scripts/check-docs.mjs，对 docs/ 下每个 Markdown 页面做第二道校验：
- 只有一个一级标题，
layout: home页面以 hero 代替； - 代码围栏成对，且同一张表格各行的列数一致；
- ADR 目录：文件名为
NNNN-slug.md（或纯 slug）、一个决策编号只有一个归属、H1 声明该编号，并含 Status、Context、Decision 段； adr/README.md：每条记录恰好一行索引，且行内链接只能指向拥有该编号的记录；docs/下所有ADR NNNN引用都能解析到记录，或解析到08-meta/decisions-log.md声明退役的编号；- 每个中文页面在同相对路径都有英文页面，其中
index.md与README.md视为同一页； NAV.md列出本树每个页面，且两棵spec/树的章节目录必须一致并保持01-product这样的编号。
随后同一工作流会运行 VitePress 生产构建，验证渲染路由与每条内部链接。
内容规则
- 英语仍然是规范、ADR、代码的规范源语言 标识符和协议术语。
- 每个英文规范同时有一个简体中文配套
/zh-CN/spec/下的相对路径；两个语言环境都暴露相同的部分并且 阅读顺序。 3.中文页面翻译完整的散文，链接回英文源， 并逐字保留代码、协议字段和标识符。措辞时 不同的是，英文合同仍然具有权威性。 4.侧边栏源自Markdown树，因此新的规范不能 被意外地从深度导航中遗漏。 - 用户可见或协议可见的文档行为属于 E2E 测试计划。
- 导航应暴露最短的有用路径；仍保留深层文件 可搜索并可直接链接。