#文档贡献

本文档使用 Rspress 编写。语法见 Rspress 官方文档；本页约定本站的措辞与写作要求。

#本地开发

bun install
bun run dev       # 开发服务器（热重载）
bun run build     # 生产构建
bun run preview   # 预览构建结果

目录大致如下：

docs-site/
├── rspress.config.ts
├── docs/
│   ├── _nav.json
│   ├── guide/           # 快速开始
│   ├── manual/          # 用户手册
│   ├── administrator/   # 运维手册
│   ├── dev/             # 开发指南
│   ├── faq/
│   └── glossary/
└── ...

新增页面后更新所在目录的 _meta.json；若要出现在顶栏，再改 docs/_nav.json。

目录页可用 frontmatter overview: true，由侧边栏自动生成分组卡片，见 Overview 页。

#限制性用词参考 RFC 2119

RFC 2119 描述了一些常见用词的意思，简而言之：

#必须、应该

必须要满足的，是强制要求的，通常意味着不如此执行会造成不可预料的后果。

#禁止、不应该

必须被禁止的，是绝不允许的，通常意味着如果如此执行会造成不可预料的后果。

#建议、推荐、尽量、尽可能

有可能有合理的原因，在特定的场景下可接受，且是被建议的，即能用即用。

#不建议、不推荐

有可能有合理的原因，在特定的场景下可接受，但是不被建议的，即非必要不使用。

#可以、允许、可选

完完全全是可选的，无所谓有无。

#以最新版本为参考

如果在最新版本中，一些行为存在更改，考虑到本应用程序的迭代方式，应该以最新版本为参考。对于不具有向前兼容功能的破坏性修改，应该仅保留最新版本的行为描述（如安装部署方式），但同时，如果已有计划在未来存在破坏性修改，除非是不可预料的，否则应提前在文档中以 danger note 形式警告。反之，如果一些需要向前兼容的功能在最新版本存在破坏性修改，则应该以 warn note 的形式给出警告。

#以客观事实为依据

尚未上线的功能不建议存在于文档中。具体而言：对于尚未承诺的功能，不应该写入文档；对于尚未进行的开发计划不建议写入文档；对于已经开发完毕但尚未上线的功能可以写入文档，但必须做出标注；对于已经上线的功能应该写入文档。

#尽可能全面

对于可能出现的问题和常见错误操作建议写入文档，即文档既应该描述正确做法，也应该描述错误做法。这有助于用户自行排查错误原因。

#尽量避免翻译腔

所谓翻译腔，可以参考中文维基百科中「翻译腔」的条目，简而言之就是「说人话」。但本文档不严格要求翻译腔问题，最重要的是句子通顺，避免病句。在技术文档中，信达永远比雅更重要。

#构建与搜索

• 构建产物默认在 doc_build/（Rspress 配置为准），可静态托管
• 站内搜索使用 Rspress 内置 FlexSearch，一般无需额外配置

#AI 编写/内容缺失标记

AstraSchedule 不反对 AI Coding，但文档站应当提供准确无误的事实，故当某一篇文档是由 AI 生成时，应该按 AI 生成的程度在文档的 一级标题前 放置以下标记：

#完全由人工编写

不做任何标记

#AI 参与编写，且经过人工完整审阅校对

不做任何标记

#AI 辅助编写一部分/AI部分修正，人工未校对

> [!WARNING]
> 
> 本页由 AI 工具参考代码编写，部分内容未经过人工审核，内容仅供参考。如果无法解决问题或需要协助部署，可邮箱联系：kuohu@getastra.cn

#完全由AI编写，人工未校对

> [!DANGER]
>
> 本页由 AI 工具参考代码编写，尚未经过人工审核，内容仅供参考。如果无法解决问题或需要协助部署，可邮箱联系：kuohu@getastra.cn

#文档中图片太少

> [!TIP]
>
> 本页配图较少，待维护者补充。如果无法解决问题或需要协助部署，可邮箱联系：kuohu@getastra.cn

#内容风格不适合阅读对象，但没有事实性错误

> [!TIP]
>
> 本页所有内容均已校对，但对于目标读者可能过于晦涩/浅显，需要维护者对文档进行润色。如果无法解决问题或需要协助部署，可邮箱联系：kuohu@getastra.cn