文档写作与一致性规范

文档状态：Stable

目标：让文档在多人协作下保持可读、可维护、可快速检索。

1. 基本结构模板

每篇文档建议至少包含：

1. 这篇文档解决什么问题（适用场景）
2. 前置条件（环境/输入）
3. 操作步骤（命令或流程）
4. 预期输出（成功后看到什么）
5. 常见失败与排查

2. 标题与层级

• 一级标题（#）只出现一次
• 二级标题用于主要章节
• 不要跳级（## 后直接 ####）

3. 命令与路径

• 所有命令放入 fenced code block（bash）
• 路径使用仓库相对路径
• 示例路径优先复用已存在的真实路径（避免伪路径）

4. 术语统一

优先使用以下术语：

• runtime（运行时）
• workbench（工作台）
• artifact（产物）
• contract（契约）
• validation（验证）

避免同义词在同一文档混用，减少歧义。

5. 状态标识

文档开头统一使用：

• > 文档状态：**Stable**
• > 文档状态：**Beta**
• > 文档状态：**Legacy**

含义见 docs/README.md。

6. 链接与维护

• 新增文档必须接入至少一个入口页（docs/README.md 或专题 README）
• 修改文档后检查本地链接有效性
• 过时文档不要直接删，先标记 Legacy 并给替代链接