# FAQ / 教程贡献规范

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

## 适用范围

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

## 维护元数据（必填）

所有 FAQ / 教程内容都应在标题下方补一段维护元数据：

```md
> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false
```

- `owner`：后续负责校对、修订、答疑的人或团队。
- `audience`：目标读者，避免把新手教程写成排障手册，或把运维经验写成泛泛介绍。
- `last verified`：最近一次按文档步骤、截图或行为重新核对的日期。
- `obsolete`：默认写 `false`；如果内容已失效，改为 `true`，并在正文开头补替代方案、迁移路径或删除计划。

## FAQ 模板

复制以下结构提交：

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

> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false

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

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

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

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

## 教程模板

复制以下结构提交：

```md
# 教程标题

> owner: @github-id / team
> audience: 新手 / 运维 / 集成开发者
> last verified: YYYY-MM-DD
> obsolete: false

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

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

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

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

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

## 命名与归档建议

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

## 提交要求

- 标题可检索：包含关键词（平台名、报错码、功能名）
- 步骤可复现：避免 `试一下`、`差不多` 这类描述
- 版本要明确：注明适用版本、部署方式
- 结果可验证：给出成功判定标准
- 元数据完整：`owner / audience / last verified / obsolete` 四项缺一不可

## 维护原则

- 过时内容要标记 `已失效` 并给替代方案
- 同类问题合并，避免 FAQ 膨胀重复
- 优先给最短修复路径，再补原理解释
- 正文有实质更新时，同步刷新 `last verified`
- 负责人变更时，及时更新 `owner`，不要留下无人维护的教程