内容与双语策略

内容层级

层级	目标	内容边界
README	首次理解与最短成功路径	定位、宿主、安装、常用操作、安全摘要与导航
文档站点	使用、设计和维护知识	指南、架构、边界、CLI、迁移与参考资料
代码与 schema	可执行契约	实际行为、字段、默认值与拒绝条件
测试与 CI	可验证证据	回归、内容契约、链接和构建门禁

发生冲突时，先核对用户当前意图，再以当前代码、配置、测试、schema 和 manifest 为事实依据。文档需要描述计划时， 必须与已实现事实分开。

历史页面可以保留被替代方案和演进过程，但必须明确它们是在解释“为什么走到这里”，不能让读者把历史输入或后来采用的 研究框架误认为当前实现契约。历史内容默认不应全部进入 Agent 上下文，应通过 metadata、状态、路由和检索按需发现。

README 精简门禁

README 的职责是帮助第一次接触项目的人完成理解、安装和最短成功路径；精简不等于丢弃信息。每次从 README 删除内容时， PR 必须附带迁移清单，并把仍然有效、会影响使用或维护判断的内容放入文档站点。只有能够说明该内容属于重复、过时或纯实现细节 时，才可以不迁移；不能因为内容技术性强、篇幅长或暂时缺少合适页面而直接删除。

迁移后应同时更新导航、站内链接和内容契约测试。若一项信息只适合由代码、schema 或 --help 承载，站点也应给出入口和 适用边界，让读者知道去哪里核对，而不是让信息静默消失。

双语范围

中文是深度技术文档的 canonical 版本；中文和英文 README 保持相同信息架构，英文站点维护完整的定位与快速开始。 新增或修改公开能力时，必须同步两份 README 的核心声明、宿主列表、命令和安全边界。深度页面若尚未翻译，应链接到 canonical 页面，不能复制一份无人维护的过期全文。

Owner 与更新触发器

站点页面 frontmatter 的 owner 标识维护责任。以下变化必须同步相关文档：CLI 命令或默认值、Adapter 支持、路径与 环境变量、schema 迁移、安全边界、发布门禁和能力证据。

手写与生成边界

所有 Markdown 页面和导航均为人工维护事实；VitePress 只生成静态 HTML、资源和本地搜索索引。 docs/.vitepress/dist 与缓存不提交。搜索索引来自同一构建输入，不是新的事实源。

本地搜索边界

站点使用 VitePress 内置搜索，在构建阶段生成随站点发布的本地搜索索引，不依赖服务端或外部搜索服务。这种方式部署简单、 响应快，也能让搜索结果与当前文档版本保持一致。

索引会随文档规模增长并下载到浏览器，当前方案也不提供向量语义召回。未来如果文档规模或召回质量要求明显超过本地搜索能力， 再在对应的搜索设计文档中比较分词、模糊匹配、相关度排序、预构建索引与语义检索方案。