外观
文档规范与更新要求
用于保持文档与代码同步，减少端口、配置、契约和版本信息在多处复制后产生漂移。
文档站与 Bun 约定
apps/docs-site/只负责 VitePress 导航、路由、搜索和 Mermaid 渲染；根 README、docs/、 模块 README 与模块docs/是内容源，不为站点复制正文。文档下载资产统一放在apps/docs-site/public/downloads/，由 VitePress 原样复制到站点根路径。- 文档站依赖安装和命令运行统一使用 Bun。
- 缓存与静态产物位于
apps/docs-site/.vitepress/，不提交到 Git。 - 新增可收录 Markdown 时，同步检查站点的 rewrite、导航、侧边栏与排除规则。
目录职责
README.md：项目定位、系统边界、最短启动和文档入口。docs/：跨项目的服务目录、开发测试、部署、演示、排障、发布升级和文档规范。apps/<module>/README.md：模块定位、快速启动、最小验证和专题导航。apps/<module>/docs/：模块配置、API、协议、运行机制、业务开发与示例。onnx-platform/<service>/README.md与docs/：C++ 服务快速入口与专题。onnx-platform/models/*/README.md：模型来源、文件、许可和最小使用信息。
模块事实不要复制到根 docs/；跨项目文档需要提及时只保留场景上下文并链接到主文档。
唯一事实来源
| 事实 | 唯一来源 |
|---|---|
| 版本、显著变更与破坏性变更 | RELEASE_NOTES.md |
| 服务、默认端口、健康检查和根默认启动进程 | 服务目录 |
| 配置字段、默认值与路径解析 | 模块配置专题及实际 config.json 样例 |
| HTTP / WebSocket 契约 | 模块 API 或协议专题 |
| 部署资产边界 | deploy/README.md |
| Apps / ONNX 发布包装配 | 发布包装配 |
修改事实时先更新其唯一来源。其他页面只保留帮助理解当前场景所必需的摘要与链接。
模块 README 最小内容
- 模块用途与边界。
- 快速运行和构建方式。
- 最小配置提示与配置专题链接。
- 最小验证方式。
- API / 协议、运行和排障专题导航。
- 升级注意事项（仅在确有模块级破坏性变化时）。
长字段表、完整响应、后台任务机制和大段示例应放入专题，不持续堆叠在 README。
变更同步规则
- 修改服务启动、端口或健康检查：更新代码 / 配置和服务目录。
- 修改配置结构：更新类型、实际配置样例和模块配置专题。
- 修改请求参数、事件、响应或状态码：更新模块 API / 协议专题。
- 修改运维可见行为：更新模块运行专题与跨项目故障排查入口。
- 修改部署资产：更新
deploy/README.md；修改发布包：更新发布包装配专题。 - 修改版本行为或破坏性约定：更新
RELEASE_NOTES.md，必要时补充升级步骤。
保留旧页面路由；从过长 README 迁移正文时，可保留原主要标题作为简短跳转段落，降低外部 深链接立即失效的影响。
生成内容排除
日志、录音、缓存、构建产物、运行输出和 onnx-platform/stability-results/** 中的 Markdown 不得进入 VitePress。正式稳定性测试说明 onnx-platform/docs/stability-test.md 必须保留。
提交检查
文档改动至少执行：
bash
bun run docs:check常规提交执行：
bash
bun run checkdocs:check 构建 VitePress，并以 ignoreDeadLinks: false 校验死链；check 依次执行现有 TypeScript workspace 类型检查与 docs:check。另外建议执行 git diff --check。
本仓库暂不新增 GitCode CI 或本地 Git hook；统一命令可直接供后续流水线调用。