# FAQ / 教程贡献规范

> 目标：让任何人都可以提交可复用、可检索、可维护的经验内容，避免口口相传丢失。

## 适用范围

- FAQ（常见问题与报错处理）
- 使用教程（从 0 到 1、进阶技巧、集成示例）
- 运维经验（排障、监控、升级、回滚）

## FAQ 模板

复制以下结构提交：

```md
## 问题标题（简短、可搜索）

### 现象
- 具体报错信息：
- 出现场景：

### 根因
- 触发原因 1
- 触发原因 2

### 解决步骤
1. 步骤一
2. 步骤二
3. 验证结果

### 预防建议
- 建议一
- 建议二
```

## 教程模板

复制以下结构提交：

```md
# 教程标题

## 适用人群
- 新手 / 运维 / 集成开发者

## 前置条件
- 条件一
- 条件二

## 操作步骤
1. ...
2. ...
3. ...

## 验证方式
- 成功标准 1
- 成功标准 2

## 常见坑位
- 坑位 1 与规避方式
- 坑位 2 与规避方式
```

## 命名与归档建议

- FAQ 统一追加到 [`/docs/faq.md`](../faq.md)
- 教程建议新增 `docs/community/tutorial-<topic>.md`
- 文件名使用小写英文与 `-`，例如：`tutorial-openwebui.md`

## 提交要求

- 标题可检索：包含关键词（平台名、报错码、功能名）
- 步骤可复现：避免“试一下”“差不多”描述
- 版本要明确：注明适用版本、部署方式
- 结果可验证：给出成功判定标准

## 维护原则

- 过时内容要标记“已失效”并给替代方案
- 同类问题合并，避免 FAQ 膨胀重复
- 优先给“最短修复路径”，再补原理解释