文档写作规范
目标
文档应帮助读者完成任务，而不只是复述代码。每篇文档只服务一个主要目标，并明确适用读者、版本、前置条件和验证方法。
页面开头
操作类文档使用以下信息块：
markdown
> 适用读者：Halo 站长
> 适用版本：AI 智能套件 0.2.23、Halo 2.24+
> 预计耗时：10 分钟
> 前置条件：已经安装并启用插件操作文档结构
- 这个功能解决什么问题。
- 什么时候应该使用，什么时候不应该使用。
- 前置条件。
- 最短可运行示例。
- 完整配置步骤。
- 配置字段、默认值和影响。
- 如何验证成功。
- 失败与降级行为。
- 常见问题。
- 相关 API、架构和源码。
图示规则
- 系统边界、调用链、状态变化和分支逻辑使用版本化源文件生成的 SVG。
- 图表源文件统一放在
docs/diagrams/source/，导出文件放在docs/diagrams/exported/。 - 修改图表后运行
node docs/diagrams/source/render-diagrams.mjs重新生成 SVG。 - 图表配色、生成和检查方法见 文档图表维护。
- 产品操作页面优先使用真实截图，并注明截图版本。
- 稳定的产品总览继续使用仓库
assets/readme/中的精细 SVG。 - 不为单个事实增加装饰图；图必须帮助读者理解关系或完成操作。
- 图中的名称与代码、Console 页面保持一致。
- 任何依赖颜色表达的图，同时使用文字或形状表达语义。
事实来源
| 文档内容 | 首选事实来源 |
|---|---|
| API 路径、方法、认证 | endpoint/*Endpoint.java、RoleTemplate |
| 配置字段与默认值 | AIProperties.java、前端配置页面 |
| 数据模型 | extension/*.java |
| 插件兼容版本 | plugin.yaml、build.gradle |
| 构建与本地运行 | gradle.properties、dev-start.sh |
| 用户界面 | 当前 Console 页面和真实环境截图 |
不得从历史文档复制未经核对的包名、配置名、接口方法或默认值。
版本与安全
- 页面顶部标注适用版本。
- 示例中使用
YOUR_API_KEY，不得提交真实密钥、Cookie 或 Authorization。 - 管理 API 示例不得使用生产环境真实账号。
- 截图中出现域名、用户数据和 token 时先脱敏。
- 升级导致行为变化时，同时更新迁移文档和兼容矩阵。
链接与源码引用
- 仓库内使用相对链接。
- 用户手册不要依赖源码才能读懂，但可在文末提供“相关实现”。
- 移动文件时运行链接检查，避免孤立页面。
- 同一个事实尽量只在一处完整定义，其他页面用链接引用。
完成标准
一篇操作文档只有在满足以下条件时才算完成：
- 新读者能够只按文档完成操作。
- 每个关键步骤都有可观察的成功标志。
- 写明主要失败场景和恢复方法。
- 所有命令、路径、默认值均与当前版本核对。
- 复杂流程配有图示。