feat: 添加公告书写标准文档，规范AI生成公告的Markdown格式

2026-04-20 16:08:10 +08:00
parent 8dd6daccd1
commit 2d3111228e
2 changed files with 573 additions and 0 deletions
@@ -0,0 +1,312 @@
+# 使用教程书写模板
+
+本文件用于约束 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 套话
+- 普通用户能直接照着做
@@ -0,0 +1,261 @@
+# 公告书写标准
+
+本文件用于约束 AI 生成“账号贡献站 / Codex 注册扩展”相关公告时的 Markdown 格式。
+
+使用方式：
+
+- 先把这份文件内容发给 AI
+- 再补充你这次要发的实际事项
+- 让 AI 严格按本文格式输出完整 Markdown
+- 最后把结果直接复制到管理端公告编辑框中
+
+---
+
+## 1. 公告用途
+
+公告用于发布以下信息：
+
+- 站点新增功能
+- 上传规则变更
+- 页面调整
+- 暂停维护通知
+- 已知问题说明
+- 临时提醒
+- 外部引导信息
+
+公告不是教程，不需要展开写成长文。
+
+---
+
+## 2. 公告总体要求
+
+AI 生成公告时必须满足：
+
+1. 使用标准 Markdown
+2. 不使用 HTML 标签
+3. 不写成口语化碎碎念
+4. 标题明确，首段直接说明本次公告主题
+5. 优先写结论，再写细节
+6. 语气清晰、正式、简洁
+7. 尽量让用户在 10 秒内看懂重点
+
+---
+
+## 3. 标准结构
+
+公告建议按以下结构输出：
+
+```md
+# 公告标题
+
+一句话概述本次公告核心内容。
+
+## 本次调整
+
+- 要点 1
+- 要点 2
+- 要点 3
+
+## 影响范围
+
+- 影响项 1
+- 影响项 2
+
+## 用户需要做什么
+
+- 用户动作 1
+- 用户动作 2
+
+## 补充说明
+
+补充说明内容。
+```
+
+不是每次都必须写满所有章节，但至少要保证：
+
+- 有一级标题
+- 有概述
+- 有要点列表
+
+---
+
+## 4. 标题规范
+
+标题必须满足：
+
+- 直接说明主题
+- 不使用夸张标题党
+- 不写“通知一下”“说一下”这种模糊表述
+
+推荐标题示例：
+
+- `# 账号贡献页新增公告与使用教程入口`
+- `# 上传规则调整说明`
+- `# sub2api 文件校验规则更新`
+- `# 站点临时维护公告`
+
+不推荐：
+
+- `# 说个事`
+- `# 看一下`
+- `# 更新了`
+
+---
+
+## 5. 正文写法规范
+
+### 5.1 第一段
+
+第一段必须直接说清：
+
+- 发生了什么
+- 对谁有影响
+- 是否需要操作
+
+示例：
+
+```md
+账号贡献页现已新增公告与使用教程区域，后续站点通知会优先通过公告发布，使用说明会统一整理到教程中。
+```
+
+### 5.2 列表
+
+重要事项优先使用短列表：
+
+```md
+## 本次调整
+
+- 首页右侧新增公告区域
+- 排行榜与使用教程支持切换查看
+- 教程内容仅在后台开启且有内容时显示
+```
+
+### 5.3 代码或路径
+
+涉及文件名、路径、接口、命令时必须用反引号包裹：
+
+- `codex-*.json`
+- `sub2api-account-*.json`
+- `POST /api/upload`
+- `账号贡献/contrib-portal`
+
+---
+
+## 6. 禁止项
+
+AI 生成公告时禁止：
+
+- 使用 HTML
+- 写超长大段无分段文字
+- 同一句里堆太多信息
+- 写模糊时间词但不写清上下文
+- 写成教程
+- 写成 PR 描述
+- 写内部开发者视角内容
+
+不要写：
+
+- “这个地方我改了一下”
+- “目前来说应该差不多”
+- “可能有点问题后面再看”
+
+---
+
+## 7. 推荐语气
+
+推荐风格：
+
+- 冷静
+- 直接
+- 不啰嗦
+- 对用户友好
+
+推荐表达：
+
+- “现已支持”
+- “已调整为”
+- “后续将通过此处发布”
+- “如你正在使用旧流程，请注意以下变化”
+
+---
+
+## 8. AI 生成公告时的固定指令
+
+把下面这段直接发给 AI：
+
+```md
+请帮我写一份“账号贡献站 / Codex 注册扩展”公告，严格遵守以下要求：
+
+1. 输出必须是 Markdown
+2. 不要使用 HTML
+3. 风格简洁、正式、清楚
+4. 先写结论，再写细节
+5. 重要信息尽量用短列表
+6. 涉及文件名、路径、接口、命令时用反引号包裹
+7. 不要写成长教程
+8. 不要写内部开发过程，只写用户看得懂的公告
+
+请按以下结构输出：
+
+# 标题
+
+一句话概述
+
+## 本次调整
+
+- ...
+
+## 影响范围
+
+- ...
+
+## 用户需要做什么
+
+- ...
+
+## 补充说明
+
+...
+```
+
+---
+
+## 9. 可直接替换变量模板
+
+你每次可以这样发给 AI：
+
+```md
+请按“账号贡献站公告标准”帮我写一份 Markdown 公告。
+
+本次公告主题：
+[这里写主题]
+
+这次变更点：
+- [变更点 1]
+- [变更点 2]
+- [变更点 3]
+
+希望重点强调：
+- [强调点 1]
+- [强调点 2]
+
+用户是否需要额外操作：
+[是 / 否]
+
+如果需要，操作内容：
+- [操作 1]
+- [操作 2]
+```
+
+---
+
+## 10. 结果验收标准
+
+生成后的 Markdown 必须满足：
+
+- 复制到管理端后能直接显示
+- 结构清楚
+- 第一眼能看懂重点
+- 没有 HTML
+- 没有明显 AI 套话
+- 没有多余开发术语