文档规范与更新要求

用于保持文档与代码同步，减少端口、配置、契约和版本信息在多处复制后产生漂移。

文档站与 Bun 约定

• docs-site/ 只负责 VitePress 导航、路由、搜索和 Mermaid 渲染；根 README、docs/、 模块 README 与模块 docs/ 是内容源，不为站点复制正文。文档下载资产统一放在 docs-site/public/downloads/，由 VitePress 原样复制到站点根路径。
• 文档站依赖安装和命令运行统一使用 Bun。
• 缓存与静态产物位于 docs-site/.vitepress/，不提交到 Git。
• 新增可收录 Markdown 时，同步检查站点的 rewrite、导航、侧边栏与排除规则。

目录职责

• README.md：项目定位、系统边界、最短启动和文档入口。
• docs/：跨项目的服务目录、开发测试、部署、演示、排障、发布升级和文档规范。
• deploy/freeswitch/README.md 与 deploy/freeswitch/docs/：FreeSWITCH 容器化部署、完整配置树详解与五大运维专题。
• apps/<module>/README.md：模块定位、快速启动、最小验证和专题导航。
• apps/<module>/docs/：模块配置、API、协议、运行机制、业务开发与示例。
• onnx-platform/<service>/README.md 与 docs/：Rust 服务快速入口与专题。
• onnx-platform/models/*/README.md：模型来源、文件、许可和最小使用信息。
• AGENTS.md 与 CLAUDE.md：AI Agent 全局上下文、核心端口与工程架构指引。

模块事实不要复制到根 docs/；跨项目文档需要提及时只保留场景上下文并链接到主文档。

现状镜像优先原则（杜绝 Changelog 化）

• 文档始终以当前最新状态为准：所有技术文档、配置参考与运维手册直接描述系统当前最新是什么样、当前怎么跑，必须使用笃定的现在时态。
• 严禁在日常文档中追加“考古式”注释：严禁在日常文档或模块 README 中追加“以前是 A，自某版本起改成 B”的历史说明。
• 废弃即剔除，不留墓碑：当配置项、脚本或文件被删除/废止时，直接从文档中删除对应说明或表格行，不留墓碑残留。
• 版本历史唯有 RELEASE_NOTES.md：版本演进轨迹、里程碑上线与破坏性升级说明仅在 RELEASE_NOTES.md 中记录。

唯一事实来源

事实	唯一来源
版本、显著变更与破坏性变更	RELEASE_NOTES.md
服务、默认端口、健康检查和根默认启动进程	服务目录
配置字段、默认值与路径解析	模块配置专题及实际 config.toml 样例
HTTP / WebSocket 契约	模块 API 或协议专题
FreeSWITCH 容器化资产与完整 XML 配置树	deploy/freeswitch/README.md 与专题
部署资产边界与拓扑	deploy/README.md
Agent 上下文与工程架构入口	AGENTS.md 与 CLAUDE.md
源码仓库访问、源码共享、权限撤销与许可边界	源码仓库访问与授权

修改事实时先更新其唯一来源。其他页面只保留帮助理解当前场景所必需的摘要与链接。

模块 README 最小内容

• 模块用途与边界。
• 快速运行和构建方式。
• 最小配置提示与配置专题链接。
• 最小验证方式。
• API / 协议、运行和排障专题导航。
• 升级注意事项（仅在确有模块级破坏性变化时）。

长字段表、完整响应、后台任务机制和大段示例应放入专题，不持续堆叠在 README。

变更同步规则

• 修改服务启动、端口或健康检查：更新代码 / 配置和服务目录。
• 修改配置结构：更新类型、实际配置样例和模块配置专题。
• 修改请求参数、事件、响应或状态码：更新模块 API / 协议专题。
• 修改运维可见行为：更新模块运行专题与跨项目故障排查入口。
• 修改部署资产：更新 deploy/README.md。
• 修改 FreeSWITCH 容器基线或配置树：更新 deploy/freeswitch/README.md 与对应专题。
• 修改核心服务归属、端口或全局命令：同步更新 AGENTS.md 与 CLAUDE.md。
• 修改源码访问、源码共享、权限撤销或许可边界：更新 docs/source-repository-access.md；其他文档仅保留摘要和链接。
• 修改版本行为或破坏性约定：更新 RELEASE_NOTES.md，必要时补充升级步骤。

RELEASE_NOTES.md 中已发布版本用于保存当时的版本事实和变更轨迹，不作为当前源码交付、仓库访问、 权限操作或部署操作指南。现行规则必须回到对应 SSOT，历史条目需要提示机制后续废弃时只保留短注 和现行文档链接，不复制当前操作细节。

保留旧页面路由；从过长 README 迁移正文时，可保留原主要标题作为简短跳转段落，降低外部 深链接立即失效的影响。

生成内容排除

日志、录音、缓存、构建产物和运行输出中的 Markdown 不得进入 VitePress。 以 -results 结尾的运行结果目录通过通用排除规则过滤。

提交检查

文档改动至少执行：

bun run docs:build

常规提交执行：

bun run lint
bun run typecheck

docs:build 构建 VitePress，并以 ignoreDeadLinks: false 校验死链；lint 与 typecheck 分别执行所有工作区子项目的格式化/代码检查与 TypeScript 类型检查。另外建议执行 git diff --check。

本仓库暂不新增 GitCode CI 或本地 Git hook；统一命令可直接供后续流水线调用。