文档维护
开始改一篇文档前，先明确读者、进入目的和最需要获得的结果。教程负责让读者完成任务，参考负责精确查询，内核说明负责解释机制；避免把同一段契约复制到多个页面。
按阅读场景组织
| 页面 | 优先内容 | 组织方式 |
|---|---|---|
| 首页 | 项目范围、最小代码与两个开发入口 | 简短定位、代码、导航 |
| 指南 | 一个任务及失败边界 | 示例先于扩展细节，交叉链接到参考 |
| 概念与内核 | 机制、所有权、不变量 | 时序或依赖图，关联源码与测试 |
| 配置 | 选项、单位、默认值 | 按配置职责分表，单独解释策略 |
| API | 导入、签名、返回值、状态与错误 | 符号标题和紧凑表格 |
| 历史设计 | 当时的问题与取舍 | 状态提示，链接当前实现 |
文件与导航
页面使用一个 H1，frontmatter 写 description；历史、迁移页增加 status。栏目侧栏与顶栏集中在 .vitepress/navigation.mjs。每个正式页面都需有可达入口；旧 URL 移动时保留过渡页和原有重要锚点。
站内链接使用相对路径或站点路径，链接源码时指向仓库真实文件。页面不能出现待实现的导航链接。跨文档契约变更先更新参考，再调整指南和迁移说明。
文案与术语
正文使用简体中文，保留 API 标识符。统一使用“请求体”“响应头”“中间件”“处理器”“背压”“消息定界”“子应用”和“取消信号”。有参数单位时在表头或说明中明确，避免把毫秒与秒混用。
一句话能表达的关系写成一句话。列表用于步骤或并列选项，表格用于查询和比较。避免重复总结、夸张性能描述及无依据的兼容承诺。工作区能力和已发布能力分开标注。
组件与视觉
.vitepress/theme/style.css 集中维护浅色与深色令牌：正文 16px、代码 14px、正文最大宽度 760px、侧栏 260px。中性色承载正文，蓝色只强调链接与主要入口，边框定义分区。移动端将多列切为单列，代码和表格允许局部横向滚动。
| 模式 | 实现 | 使用条件 |
|---|---|---|
| 阅读路线 | DocLinks | 首页、栏目入口或明确的下一步选择 |
| 模块依赖 | LayerDiagram | 解释固定分层，不表达运行时序 |
| 复制命令 | HomeCommand | 仅包装复制交互，文案由页面传入 |
| 提示 | 原生 info / warning 容器 | 必须提前知道的版本或行为边界 |
| 多种命令 | 原生 code-group | TS/JS 或等效入口的可替代选择 |
| 参数查询 | Markdown 表格 | 静态字段、类型与默认值 |
不要把每段正文包装为卡片。组件只维护语言无关的结构与交互，标题、说明、无障碍标签和反馈文案都由 Markdown 或语言配置传入。组件应使用语义 HTML，保留键盘焦点和减少动态效果的设置。参数表不引入客户端状态；只有真实查询需求再考虑交互筛选。
示例与检查
完整示例放在 docs/examples，Markdown 使用代码导入，避免显示与执行两份代码。NOVA_DOCS_CHECK 仅供仓库检查导入示例；正常运行时自动监听。指南内局部片段应标明依赖的 app 或上下文。
pnpm -F nova-http build
pnpm docs:check
pnpm docs:builddocs:check 执行可运行示例与关键行为断言；docs:build 渲染后检查站内链接、锚点、导航与单页 H1。格式检查使用根目录 oxfmt。首次发布或视觉变更还需检查首页、指南、配置、API、长设计页在窄屏和深色模式下的阅读表现。
参考方向
信息组织参考 Vue 指南的渐进阅读与指南/API 分离，以及 Fastify 文档的技术主题查询入口。Nova 保留自身的 TCP、消息契约和生命周期内容，不复制其他框架的能力或文案。