常见问题
一般
文档站和各个业务系统是什么关系？
文档站只描述各系统，不运行它们。实际服务地址见页脚「相关链接」或各系统 index.md。
我应该先读哪篇文档？
为什么推荐 build + serve 而不是 npm start？
完整构建更接近生产环境，能提前发现 broken link、MDX 错误等问题。开发模式热更新适合改主题或组件，不一定能暴露全部构建问题。
写作与结构
新文档应该放在哪个目录？
按 Diátaxis 类型选择，见 文档结构。业务系统文档放在 docs/systems/<系统名>/。
加了 md 文件但侧边栏没有？
必须在 sidebars.ts 中注册 doc ID。见 侧边栏与导航。
如何画架构图？
在 Markdown 中使用 mermaid 代码块。节点内换行用 <br/>。规范见 doc-writing Skill。
技术
Node 版本要求？
= 20.0，见
package.json的engines字段。
如何部署到生产？
npm run deploy
需 Cloudflare 账号与 Wrangler 登录。详见 生产部署。
如何切换文档版本？
使用导航栏右侧版本下拉，在 Current 与 V1.0 之间切换。
如何添加英文翻译？
默认 locale 为 zh-Hans。英文翻译文件放在 i18n/en/ 对应路径。可运行 npm run write-translations 提取待翻译项。
权限
谁可以合并 PR / 部署？
由技术部仓库维护者与 Cloudflare 账号管理员决定，具体以部门内约定为准。