# 使用教程书写模板

本文件用于约束 AI 生成“账号贡献站 / Codex 注册扩展”使用教程时的 Markdown 格式。

使用方式：

- 先把这份文件发给 AI
- 再告诉 AI 本次要写哪一部分教程
- 让 AI 严格按本文格式输出
- 输出结果直接复制到管理端“使用教程”编辑区

---

## 1. 教程用途

使用教程用于说明：

- 页面怎么用
- 上传文件怎么准备
- 上传步骤是什么
- 常见错误怎么理解
- 注意事项有哪些

教程不是公告，所以要：

- 结构完整
- 步骤清楚
- 能让第一次接触的人看懂

---

## 2. 教程总体要求

AI 生成教程时必须满足：

1. 使用标准 Markdown
2. 不使用 HTML
3. 章节分明
4. 按用户实际操作顺序来写
5. 重点步骤必须编号
6. 文件名、路径、接口、按钮名要用反引号包裹
7. 语言要清楚，不要写废话

---

## 3. 标准结构

教程建议按这个结构输出：

```md
# 教程标题

一句话说明这份教程是教什么的。

## 适用场景

- 场景 1
- 场景 2

## 准备内容

- 需要准备的内容 1
- 需要准备的内容 2

## 操作步骤

### 第一步：...

说明。

### 第二步：...

说明。

### 第三步：...

说明。

## 常见问题

### 问题 1

说明。

### 问题 2

说明。

## 注意事项

- 注意项 1
- 注意项 2
```

---

## 4. 标题规范

标题必须直接说清主题。

推荐示例：

- `# 账号贡献页使用教程`
- `# 如何准备可上传的 JSON 文件`
- `# 账号贡献上传操作说明`

不推荐：

- `# 使用方法`
- `# 教你怎么弄`
- `# 说明一下`

---

## 5. 正文写法规范

### 5.1 先讲适用场景

教程开头要先告诉用户：

- 这份教程适合谁
- 能解决什么问题

示例：

```md
本教程适用于首次使用账号贡献页的用户，帮助你完成文件准备、上传和结果查看。
```

### 5.2 步骤必须按顺序写

不要跳步，不要先写报错再写操作。

推荐：

```md
## 操作步骤

### 第一步：准备 JSON 文件

...

### 第二步：打开贡献页面

...

### 第三步：填写昵称并上传

...
```

### 5.3 命令、按钮、文件名要加反引号

例如：

- `验证并上传`
- `codex-*.json`
- `sub2api-account-*.json`
- `POST /api/upload`

---

## 6. 常见问题写法

常见问题建议用二级或三级标题展开：

```md
## 常见问题

### 为什么按钮没有出现？

如果后台没有开启教程显示，前台不会显示“使用教程”按钮。

### 为什么文件上传失败？

请先检查文件命名、文件大小和内容格式是否符合要求。
```

---

## 7. 禁止项

AI 生成教程时禁止：

- 使用 HTML
- 写内部开发实现细节
- 写成公告语气
- 写成 PR 说明
- 大段堆文字不分章节
- 用“应该”“可能”“大概”这种模糊表达描述核心步骤

不要写：

- “这里我做了一个功能”
- “你应该差不多知道怎么操作”
- “这个问题暂时先这样”

---

## 8. 推荐语气

推荐风格：

- 清楚
- 分步骤
- 面向第一次使用的人
- 说明明确，不省略关键动作

推荐表达：

- “先准备”
- “然后打开”
- “接着点击”
- “如果出现以下情况”
- “请确认”

---

## 9. AI 生成教程时的固定指令

把下面这段直接发给 AI：

```md
请帮我写一份“账号贡献站 / Codex 注册扩展”的使用教程，严格遵守以下要求：

1. 输出必须是 Markdown
2. 不要使用 HTML
3. 面向第一次使用的人来写
4. 结构必须清楚，章节明确
5. 操作步骤必须按顺序写
6. 文件名、接口、按钮名称、路径要用反引号包裹
7. 不要写内部开发过程
8. 重要部分要短句、短段落，不要写成大段废话

请按以下结构输出：

# 标题

一句话说明

## 适用场景

- ...

## 准备内容

- ...

## 操作步骤

### 第一步：...

...

### 第二步：...

...

## 常见问题

### ...

...

## 注意事项

- ...
```

---

## 10. 可直接替换变量模板

你每次可以这样发给 AI：

```md
请按“账号贡献站使用教程模板”帮我写一份 Markdown 教程。

本次教程主题：
[这里写主题]

目标读者：
[例如：第一次使用贡献页的用户]

希望教程覆盖的内容：
- [内容 1]
- [内容 2]
- [内容 3]

必须出现的步骤：
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

希望补充的常见问题：
- [问题 1]
- [问题 2]
```

---

## 11. 结果验收标准

生成后的教程 Markdown 必须满足：

- 复制到管理端后能直接显示
- 标题和章节清楚
- 教程导航能识别出标题结构
- 步骤顺序合理
- 没有 HTML
- 没有明显 AI 套话
- 普通用户能直接照着做