QLHazycoder
7.6 KiB
7.6 KiB
使用教程书写与拆分模板
本文件用于约束 AI 后续维护 docs/使用教程/ 目录时的判断方式、拆分规则和输出格式。
这套教程已经从“单一大文件”改成了“总索引 + 分部分正文文件”的结构。
后续不要再把所有内容直接堆回 使用教程.md。
1. 目录结构
当前目录固定使用下面这套结构：
docs/使用教程/使用教程.md- 作用：总索引、部分清单、维护规则
docs/使用教程/使用教程书写模板.md- 作用：本模板，专门给 AI 使用
docs/使用教程/分部分/*.md- 作用：每一个独立教程部分的正文文件
维护原则：
使用教程.md只放总览和部分列表- 具体教程正文只放在
分部分/*.md - 新增教程主题时，优先判断是否属于现有部分
- 如果不属于现有部分，再新开一个部分文件
2. AI 维护流程
每次收到“更新教程”的任务时，必须先做下面 4 步：
- 先读取
docs/使用教程/使用教程.md - 再读取
docs/使用教程/分部分/下现有文件 - 判断本次内容属于哪个已有部分
- 如果没有匹配部分，再新建部分文件，并同步更新
使用教程.md
不要一上来直接写正文。
3. 先输出更新判断
AI 在真正改文档前，必须先给出一段“更新判断”。
固定格式如下：
## 更新判断
- 操作类型：`更新现有部分` / `新建部分` / `只更新总索引`
- 目标部分标题：`...`
- 目标文件：`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 |
5. 什么时候要新建部分
满足任意一条，就应该新建部分，而不是硬塞到旧文件里：
- 新内容的主题和现有 8 个部分都不匹配
- 新内容会让已有文件明显跑题
- 新内容已经形成独立功能块，后续大概率会继续单独维护
- 新内容虽然在总述里提到过，但当前还没有专门的部分文件
典型需要新开的例子：
HeroSMS手机接码扩展使用教程- 节点检测与纯净度检查网站使用教程
- 新的邮箱方案使用教程
- 新的代理配置方案
不应该新开的例子：
- 只是补充
PayPal一个报错说明 - 只是更新
Cloudflare Temp Email一个字段解释 - 只是修改
Clash Verge脚本中的几行配置说明
6. 新建部分时的文件命名规则
如果需要新开部分，使用下面规则：
- 放到
docs/使用教程/分部分/ - 文件名格式：
NN-部分标题.md
例如：
09-HeroSMS-手机接码扩展使用教程.md10-节点检测与纯净度检查网站使用教程.md
规则要求：
NN使用两位数字- 按当前排序往后递增
- 文件名直接使用中文标题，便于人工识别
- 新建后必须同步更新
使用教程.md的部分清单
7. 每个部分文件的固定结构
每个分部分正文文件都按下面结构写：
# 第X部分：部分标题
## 部分信息
- `section_slug`: `english-slug`
- `适用主题`: `主题 1`、`主题 2`
- `维护方式`: `直接更新本文件`
## 适用场景
- ...
## 准备内容
- ...
## 操作步骤
### 第一步：...
说明。
### 第二步：...
说明。
## 常见问题
### 问题 1
说明。
## 注意事项
- ...
要求：
- 继续使用标准 Markdown
- 不使用 HTML
- 命令、路径、按钮、文件名要用反引号
- 操作步骤按真实顺序来写
- 重要提示写在
常见问题或注意事项
8. 更新已有部分时的要求
如果本次属于已有部分：
- 直接修改对应的分部分文件
- 保持原有标题和主题边界
- 如果只是补充小知识点，不要新开大段无关章节
- 如果文件标题已经不够覆盖新内容，再考虑是否需要拆成新部分
更新已有部分时，优先做这几件事：
- 补充步骤
- 修正常见问题
- 更新注意事项
- 调整准备内容
9. 同步更新总索引时要改什么
以下情况必须同步修改 docs/使用教程/使用教程.md：
- 新增了部分文件
- 删除了部分文件
- 调整了部分顺序
- 修改了部分标题
- 新增了“待补充主题”
以下情况通常不需要改总索引：
- 只是补充某个部分里的正文
- 只是修正文案
- 只是补充 FAQ
10. 输出格式要求
AI 最终输出必须分成两段：
第一段：更新判断
固定使用本模板第 3 节的格式。
第二段：文档结果
根据情况二选一：
-
如果是更新已有部分
输出“修改后的完整分部分文件正文” -
如果是新建部分
输出：- 新文件路径
- 新文件完整正文
- 需要补到
使用教程.md清单中的新表格行
不要只输出零散段落。
要输出可直接覆盖文件的完整 Markdown。
11. 固定指令
把下面这段直接发给 AI：
请按 `docs/使用教程/使用教程书写模板.md` 执行。
你必须先读取：
1. `docs/使用教程/使用教程.md`
2. `docs/使用教程/分部分/` 下现有文件
然后先输出“更新判断”，判断本次内容属于：
- 更新现有部分
- 新建部分
- 只更新总索引
如果属于已有部分，就直接输出该部分文件的完整新版本。
如果不属于已有部分，就新开一个部分文件，并同时给出需要补到 `使用教程.md` 的部分清单项。
要求：
1. 输出必须是 Markdown
2. 不要使用 HTML
3. 不要把所有内容重新堆回 `使用教程.md`
4. 每个教程主题优先归到已有分部分文件
5. 只有在现有部分都不合适时，才允许新开部分
6. 文件名、路径、接口、按钮名称要用反引号包裹
7. 面向第一次使用的人来写
8. 步骤必须按真实顺序写