文档维护规范

Project N.E.K.O. 的文档属于产品契约的一部分。文档应靠近所描述的代码，明确自身性质，并避免把容易过期的事实复制到多个页面。

文档分层

层级	用途	位置
用户与开发指南	受支持的安装方式和常用流程	guide/、config/、deployment/、frontend/、plugins/
架构与 API 参考	由当前代码支撑的契约	architecture/、modules/、api/
贡献规范	仓库级开发与验证规则	contributing/
项目记录	设计决策、性能快照和 SDK 变更说明	design/、benchmarks/、changelog/
组件自有文档	随单个组件维护的详细说明	例如 plugin/plugins/neko_live/docs/

项目记录用于保存证据和背景，不能替代当前代码、测试或已接受的 issue。

唯一事实来源

每类事实只保留一个权威页面：

• 行为和公开契约写入对应指南、架构页或 API 页；
• 仓库流程写入 contributing/；
• 实现理由和有日期的测量结果写入项目记录；
• 组件专用流程放在组件目录旁；
• 活跃的未来任务放在已接受的 issue 或维护中的项目看板。

命令清单、provider 表、版本结论和路线图承诺应链接到权威页面，不要重复复制。翻译页应同步权威含义，不应成为另一套独立规范。

状态用语

计划或记录必须在开头附近说明其权威性：

• 当前契约：由当前代码和测试约束的行为。
• 已实现设计记录：解释已发布行为的理由，细节可能被后续代码取代。
• 提案：文件存在不代表已批准或已实现。
• 历史快照：带日期的证据，不能当作当前状态。
• 已弃用：只为迁移或历史排查保留。

没有负责人和权威跟踪链接时，不要写“第二阶段即将完成”“下个版本支持”等模糊承诺。

多语言

文档站提供英语、简体中文和日语导航，但项目记录不要求全部翻译。对应语言页面不存在时，语言切换器会回到该语言首页。

修改已有镜像指南时：

1. 同一次改动中更新所有已有镜像；
2. 保持代码标识符、路径、占位符和警告含义一致；
3. 不要为了掩盖缺失覆盖而创建没有维护能力的空翻译；
4. 仅有单一语言的记录应在最近的索引中注明。

运行时 UI 的八语言同步规则是另一项独立要求，用户可见 locale key 仍必须全部同步。

docs/README_en.md、docs/README_ja.md 和 docs/README_ru.md 是由仓库根 README 链接的翻译版，刻意不参与 VitePress 构建，不应作为文档站导航页面使用。

docs/zh-CN/guide/openclaw_guide*.md 及相邻资源是由应用直接提供的多语言运行时教程。必须保持路径稳定，并继续排除在 VitePress 之外；公开的接入契约由 Agent 与插件文档维护。

链接与路径

• VitePress 页面使用 /plugins/quick-start 这类站点根路径。
• 目标是文档站外的仓库文件时，使用完整的 GitHub blob URL；不得使用向上相对路径（../）。
• 保持已有路由稳定；确需移动时应提供重定向或兼容页，并更新所有引用。
• 不得把生成文件、本地 worktree、临时报告、隐私日志或未合并 PR 分支作为长期文档链接。

提交前检查

1. 用当前代码和测试核对所描述的行为；
2. 删除密钥、原始用户内容、机器专用路径和临时证据；
3. 检查所有已存在的语言镜像；
4. 在 docs/ 下运行 npm ci 和 npm run build；
5. 文档若改变公开契约或示例，还应运行相关代码检查；
6. 保持 PR 范围单一，不使用堆叠式 PR 混入其他文档任务。