文档维护指南

本站集中维护 Biulight 产品的公开用户手册。产品代码仓库负责提供事实，本站负责把事实整理成便于用户查找和完成任务的文档。

内容放在哪里

内容	位置
产品安装、操作、配置与故障排查	docs/products/<product>/
多个项目都适用的通用知识	docs/knowledge/
开发与文档维护规范	docs/developing/
个人学习记录	docs/learning/
有明确时间线的文章	blog/

产品内部架构、ADR、发布流程和代码约束应留在各自代码仓库。只有当这些信息会改变用户操作或排障方式时，才把结论写进用户手册。

页面类型

• 快速开始：提供从零到首次成功的最短路径。
• 操作指南：帮助用户完成一个明确任务。
• 参考手册：准确列出命令、字段、默认值和兼容性。
• 故障排查：从用户可观察的症状出发给出检查与修复步骤。

不要把四种页面揉成一篇超长说明。背景知识只保留到足以帮助用户做出决定的程度。

更新流程

1. 在 .agents/projects.yml 中找到产品的来源仓库和上次审阅提交。
2. 检查此后发生的用户可见变化，包括安装方式、命令、配置、平台支持和错误处理。
3. 根据用户任务更新相应页面，不机械复制 README 或源码注释。
4. 对照命令定义与配置解析器核实示例；涉及危险操作时优先给出预览方式。
5. 执行 pnpm build 和必要的 pnpm typecheck。
6. 更新来源登记中的 last_reviewed_ref 与版本。

完整的 AI 维护约束见仓库根目录的 AGENTS.md，新页面模板位于 .agents/templates/。