QLHazyCoder
280 lines
7.8 KiB
Markdown
280 lines
7.8 KiB
Markdown
# 使用教程书写与拆分模板
|
||
|
||
本文件用于约束 AI 后续维护 `docs/使用教程/` 目录时的判断方式、拆分规则和输出格式。
|
||
|
||
这套教程已经从“单一大文件”改成了“总索引 + 分部分正文文件”的结构。
|
||
后续不要再把所有内容直接堆回 `使用教程.md`。
|
||
|
||
---
|
||
|
||
## 1. 目录结构
|
||
|
||
当前目录固定使用下面这套结构：
|
||
|
||
- `docs/使用教程/使用教程.md`
|
||
- 作用：总索引、部分清单、维护规则
|
||
- `docs/使用教程/使用教程书写模板.md`
|
||
- 作用：本模板，专门给 AI 使用
|
||
- `docs/使用教程/分部分/*.md`
|
||
- 作用：每一个独立教程部分的正文文件
|
||
|
||
维护原则：
|
||
|
||
1. `使用教程.md` 只放总览和部分列表
|
||
2. 具体教程正文只放在 `分部分/*.md`
|
||
3. 新增教程主题时，优先判断是否属于现有部分
|
||
4. 如果不属于现有部分，再新开一个部分文件
|
||
|
||
---
|
||
|
||
## 2. AI 维护流程
|
||
|
||
每次收到“更新教程”的任务时，必须先做下面 4 步：
|
||
|
||
1. 先读取 `docs/使用教程/使用教程.md`
|
||
2. 再读取 `docs/使用教程/分部分/` 下现有文件
|
||
3. 判断本次内容属于哪个已有部分
|
||
4. 如果没有匹配部分，再新建部分文件，并同步更新 `使用教程.md`
|
||
|
||
不要一上来直接写正文。
|
||
|
||
---
|
||
|
||
## 3. 先输出更新判断
|
||
|
||
AI 在真正改文档前，必须先给出一段“更新判断”。
|
||
|
||
固定格式如下：
|
||
|
||
```md
|
||
## 更新判断
|
||
|
||
- 操作类型：`更新现有部分` / `新建部分` / `只更新总索引`
|
||
- 目标部分标题：`...`
|
||
- 目标文件：`docs/使用教程/分部分/xx-xxx.md`
|
||
- 判断理由：`...`
|
||
- 是否需要同步更新使用教程.md：`是` / `否`
|
||
```
|
||
|
||
要求：
|
||
|
||
- 如果能明确归到已有部分，就选 `更新现有部分`
|
||
- 如果现有部分都不合适，就选 `新建部分`
|
||
- 只有在修改部分列表、排序、说明文字时，才选 `只更新总索引`
|
||
|
||
---
|
||
|
||
## 4. 当前部分清单
|
||
|
||
AI 维护时默认按下面的范围归类：
|
||
|
||
| 序号 | 部分标题 | 主要覆盖主题 | 文件 |
|
||
|---|---|---|---|
|
||
| 01 | 相关项目地址与部署说明 | `cpa`、`sub2api`、项目地址、部署前提、部署环境 | `docs/使用教程/分部分/01-相关项目地址与部署说明.md` |
|
||
| 02 | 更新扩展 | `git pull`、`GitHub Desktop`、手动覆盖更新、扩展重新加载 | `docs/使用教程/分部分/02-更新扩展.md` |
|
||
| 03 | Cloudflare Temp Email 使用说明 | `Cloudflare Temp Email`、`Admin Auth`、`Custom Auth`、随机子域、固定子域、邮件接收 | `docs/使用教程/分部分/03-Cloudflare-Temp-Email-使用说明.md` |
|
||
| 04 | iCloud 隐私邮箱使用方法 | `iCloud+`、`隐藏邮件地址`、Apple ID、转发邮箱、刷新隐私邮箱 | `docs/使用教程/分部分/04-iCloud-隐私邮箱使用方法.md` |
|
||
| 05 | QQ 邮箱切换邮箱使用教程 | `QQ 邮箱`、英文邮箱、`Foxmail`、删除后重建 | `docs/使用教程/分部分/05-QQ-邮箱切换邮箱使用教程.md` |
|
||
| 06 | PayPal 注册与绑卡使用教程 | `PayPal`、注册、绑卡、钱包、身份认证、右上角通知 | `docs/使用教程/分部分/06-PayPal-注册与绑卡使用教程.md` |
|
||
| 07 | ChatGPT Plus 订阅说明（待人工审核） | `ChatGPT Plus`、订阅说明、支付流程说明、人工审核 | `docs/使用教程/分部分/07-0元试用-ChatGPT-Plus-教程.md` |
|
||
| 08 | Clash Verge 非港轮询配置 | `Clash Verge`、`非港轮询`、扩展脚本、规则模式、系统代理 | `docs/使用教程/分部分/08-Clash-Verge-非港轮询配置.md` |
|
||
| 09 | GPC 卡密页面充值说明 | `GPC`、充值卡密、卡密余额、网页充值、`ChatGPT Plus` | `docs/使用教程/分部分/09-GPC-卡密页面充值说明.md` |
|
||
|
||
---
|
||
|
||
## 5. 什么时候要新建部分
|
||
|
||
满足任意一条，就应该新建部分，而不是硬塞到旧文件里：
|
||
|
||
1. 新内容的主题和现有 9 个部分都不匹配
|
||
2. 新内容会让已有文件明显跑题
|
||
3. 新内容已经形成独立功能块，后续大概率会继续单独维护
|
||
4. 新内容虽然在总述里提到过，但当前还没有专门的部分文件
|
||
|
||
典型需要新开的例子：
|
||
|
||
- `HeroSMS` 手机接码扩展使用教程
|
||
- 节点检测与纯净度检查网站使用教程
|
||
- 新的邮箱方案使用教程
|
||
- 新的代理配置方案
|
||
|
||
不应该新开的例子：
|
||
|
||
- 只是补充 `PayPal` 一个报错说明
|
||
- 只是更新 `Cloudflare Temp Email` 一个字段解释
|
||
- 只是修改 `Clash Verge` 脚本中的几行配置说明
|
||
|
||
---
|
||
|
||
## 6. 新建部分时的文件命名规则
|
||
|
||
如果需要新开部分，使用下面规则：
|
||
|
||
1. 放到 `docs/使用教程/分部分/`
|
||
2. 文件名格式：
|
||
|
||
```text
|
||
NN-部分标题.md
|
||
```
|
||
|
||
例如：
|
||
|
||
- `09-HeroSMS-手机接码扩展使用教程.md`
|
||
- `10-节点检测与纯净度检查网站使用教程.md`
|
||
|
||
规则要求：
|
||
|
||
- `NN` 使用两位数字
|
||
- 按当前排序往后递增
|
||
- 文件名直接使用中文标题，便于人工识别
|
||
- 新建后必须同步更新 `使用教程.md` 的部分清单
|
||
|
||
---
|
||
|
||
## 7. 每个部分文件的固定结构
|
||
|
||
每个分部分正文文件都按下面结构写：
|
||
|
||
```md
|
||
# 第X部分：部分标题
|
||
|
||
## 部分信息
|
||
|
||
- `section_slug`: `english-slug`
|
||
- `适用主题`: `主题 1`、`主题 2`
|
||
- `维护方式`: `直接更新本文件`
|
||
|
||
## 适用场景
|
||
|
||
- ...
|
||
|
||
## 准备内容
|
||
|
||
- ...
|
||
|
||
## 操作步骤
|
||
|
||
### 第一步：...
|
||
|
||
说明。
|
||
|
||
### 第二步：...
|
||
|
||
说明。
|
||
|
||
## 常见问题
|
||
|
||
### 问题 1
|
||
|
||
说明。
|
||
|
||
## 注意事项
|
||
|
||
- ...
|
||
```
|
||
|
||
要求：
|
||
|
||
- 继续使用标准 Markdown
|
||
- 不使用 HTML
|
||
- 命令、路径、按钮、文件名要用反引号
|
||
- 操作步骤按真实顺序来写
|
||
- 重要提示写在 `常见问题` 或 `注意事项`
|
||
|
||
---
|
||
|
||
## 8. 更新已有部分时的要求
|
||
|
||
如果本次属于已有部分：
|
||
|
||
1. 直接修改对应的分部分文件
|
||
2. 保持原有标题和主题边界
|
||
3. 如果只是补充小知识点，不要新开大段无关章节
|
||
4. 如果文件标题已经不够覆盖新内容，再考虑是否需要拆成新部分
|
||
|
||
更新已有部分时，优先做这几件事：
|
||
|
||
- 补充步骤
|
||
- 修正常见问题
|
||
- 更新注意事项
|
||
- 调整准备内容
|
||
|
||
---
|
||
|
||
## 9. 同步更新总索引时要改什么
|
||
|
||
以下情况必须同步修改 `docs/使用教程/使用教程.md`：
|
||
|
||
- 新增了部分文件
|
||
- 删除了部分文件
|
||
- 调整了部分顺序
|
||
- 修改了部分标题
|
||
- 新增了“待补充主题”
|
||
|
||
以下情况通常不需要改总索引：
|
||
|
||
- 只是补充某个部分里的正文
|
||
- 只是修正文案
|
||
- 只是补充 FAQ
|
||
|
||
---
|
||
|
||
## 10. 输出格式要求
|
||
|
||
AI 最终输出必须分成两段：
|
||
|
||
### 第一段：更新判断
|
||
|
||
固定使用本模板第 3 节的格式。
|
||
|
||
### 第二段：文档结果
|
||
|
||
根据情况二选一：
|
||
|
||
1. 如果是更新已有部分
|
||
输出“修改后的完整分部分文件正文”
|
||
|
||
2. 如果是新建部分
|
||
输出：
|
||
- 新文件路径
|
||
- 新文件完整正文
|
||
- 需要补到 `使用教程.md` 清单中的新表格行
|
||
|
||
不要只输出零散段落。
|
||
要输出可直接覆盖文件的完整 Markdown。
|
||
|
||
---
|
||
|
||
## 11. 固定指令
|
||
|
||
把下面这段直接发给 AI：
|
||
|
||
```md
|
||
请按 `docs/使用教程/使用教程书写模板.md` 执行。
|
||
|
||
你必须先读取：
|
||
|
||
1. `docs/使用教程/使用教程.md`
|
||
2. `docs/使用教程/分部分/` 下现有文件
|
||
|
||
然后先输出“更新判断”，判断本次内容属于：
|
||
|
||
- 更新现有部分
|
||
- 新建部分
|
||
- 只更新总索引
|
||
|
||
如果属于已有部分，就直接输出该部分文件的完整新版本。
|
||
如果不属于已有部分，就新开一个部分文件，并同时给出需要补到 `使用教程.md` 的部分清单项。
|
||
|
||
要求：
|
||
|
||
1. 输出必须是 Markdown
|
||
2. 不要使用 HTML
|
||
3. 不要把所有内容重新堆回 `使用教程.md`
|
||
4. 每个教程主题优先归到已有分部分文件
|
||
5. 只有在现有部分都不合适时，才允许新开部分
|
||
6. 文件名、路径、接口、按钮名称要用反引号包裹
|
||
7. 面向第一次使用的人来写
|
||
8. 步骤必须按真实顺序写
|
||
```
|