文档写作工作流

新增页面

1. 在 docs/ 下按主题创建 Markdown 文件。
2. 在 docs/.vitepress/config.ts 中把页面加入 nav 或 sidebar。
3. 本地执行 pnpm docs:dev 检查导航、链接与层级是否清晰。

如果页面需要中英文双语，建议同步维护：

• 中文：docs/<section>/<page>.md
• 英文：docs/en/<section>/<page>.md

推荐的内容组织方式

为了让后续扩展成本更低，建议优先按“问题域”组织，而不是按“原始文件名”组织：

• guide/：入门、贡献方式、文档约定
• architecture/：稳定的系统模型与分层
• api/：对外契约、扩展接口、宿主能力
• en/：英文镜像内容，结构尽量与中文保持一致

如果某份主仓库文档只是阶段性说明，优先先抽出其中稳定的结论，再决定是否整篇迁移。

写作建议

• 一页只回答一个核心问题。
• 先写“为什么存在”，再写“如何使用”。
• 先固化稳定契约，再记录实现细节。
• 尽量把“当前实现”与“未来计划”分开，避免后续维护时混淆。

发布流程

推送到 main 后，GitHub Actions 会自动构建并发布到 GitHub Pages。
如果你后续调整了输出目录或包管理器，需要同步更新 .github/workflows/deploy.yml。