128 lines
6.1 KiB
Markdown
128 lines
6.1 KiB
Markdown
|
# 使用手册生成规范（卡若AI 结构）
|
|||
|
|
|
|||
|
|
> **强制**：任何项目生成使用手册时，一律按本规范执行。
|
|||
|
|
> **参照**：卡若AI 使用手册（`卡若AI/运营中枢/使用手册/`）
|
|||
|
|
> **版本**：1.0 | **更新**：2026-03-12
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、为什么按这个结构
|
|||
|
|
|
|||
|
|
- **统一体验**：在任意项目上生成的使用手册，结构一致、导航清晰，用户和卡若AI 都能快速查找。
|
|||
|
|
- **书籍式**：每篇一个文件夹、每章一个 .md，像一本书，便于维护和增量更新。
|
|||
|
|
- **图文并茂**：必须包含配图（架构图、流程图、截图），配图与手册一起存放、一起同步。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、标准目录结构（必须遵守）
|
|||
|
|
|
|||
|
|
生成使用手册时，在项目的 **`开发文档/9、手册/`** 下按以下结构创建（可根据项目规模精简篇数，但**结构形式一致**）：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
9、手册/
|
|||
|
|
├── README.md ← 序 + 总目录（入口）
|
|||
|
|
├── 使用手册（带图）.md ← 可选：导航页/单页摘要
|
|||
|
|
├── images/ ← 配图目录（与手册同步）
|
|||
|
|
│ ├── README.md ← 配图索引（文件名、说明、引用章节）
|
|||
|
|
│ └── [架构图/流程图/截图].png
|
|||
|
|
├── 第一篇_XXX/ ← 按主题分篇
|
|||
|
|
│ ├── 01_章节名.md
|
|||
|
|
│ └── 02_章节名.md
|
|||
|
|
├── 第二篇_XXX/
|
|||
|
|
│ └── ...
|
|||
|
|
├── 附录/
|
|||
|
|
│ ├── A_速查表.md
|
|||
|
|
│ ├── B_常用命令.md
|
|||
|
|
│ ├── C_FAQ.md
|
|||
|
|
│ └── D_更新记录.md
|
|||
|
|
├── 使用手册提示词.md ← 本目录原有
|
|||
|
|
├── 使用手册生成规范_卡若AI结构.md ← 本文件（可复制到各项目）
|
|||
|
|
└── _智能展开.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **README.md**：序言 + 总目录表格（篇→章→文件→内容），与卡若AI 使用手册 README 形式一致。
|
|||
|
|
- **每章独立 .md**：章内可含图片引用，如 `` 或 ``（视层级而定）。
|
|||
|
|
- **images/**：所有配图放此目录，并在 `images/README.md` 登记「文件名、说明、引用章节」。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、书写形式（聊天的形式 / 卡若式）
|
|||
|
|
|
|||
|
|
- **语气**：大白话、用户能听懂；避免堆砌术语。
|
|||
|
|
- **结构**：每章有「小结/概述」、分节清晰、必要时用表格与列表。
|
|||
|
|
- **导航**：每章文首「返回 [总目录](../README.md) | 上一章」；文末「下一章：[第X章](链接)」。
|
|||
|
|
- **复盘友好**：若手册由卡若AI 生成，结尾可带简要复盘或更新记录。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、图文要求（强制）
|
|||
|
|
|
|||
|
|
### 4.1 必须包含图片
|
|||
|
|
|
|||
|
|
使用手册**必须图文并茂**，不得仅有文字。至少包含：
|
|||
|
|
|
|||
|
|
| 类型 | 说明 | 示例 |
|
|||
|
|
|:---|:---|:---|
|
|||
|
|
| 架构/系统图 | 产品架构、模块关系、数据流 | 系统架构图、功能模块图 |
|
|||
|
|
| 流程图 | 操作流程、业务流程、状态流转 | 用户操作流程图、上线流程图 |
|
|||
|
|
| 界面截图 | 关键页面、操作步骤截图 | 登录页、核心功能页、设置页 |
|
|||
|
|
|
|||
|
|
### 4.2 图片流程（生成手册时的执行顺序）
|
|||
|
|
|
|||
|
|
1. **确定配图清单**：根据目录与章节，列出需要的图（架构图、流程图、截图），写入 `images/README.md` 的「计划」或直接写表。
|
|||
|
|
2. **创建 images 目录**：在 `9、手册/images/` 下存放所有图片；单张建议 <5MB，格式以 PNG 为主。
|
|||
|
|
3. **生成或采集图片**：
|
|||
|
|
- 架构/流程图：可用 Mermaid 生成后导出 PNG，或由 AI 生成示意图，保存到 `images/`。
|
|||
|
|
- 界面截图：从实际项目/原型截取，命名规范如 `页面名_功能说明.png`。
|
|||
|
|
4. **在章节中引用**：在对应章节用 Markdown 插入，例如 ``，并配图题（**图 X-X 标题**）。
|
|||
|
|
5. **登记配图索引**：在 `images/README.md` 中维护「文件名 | 说明 | 引用章节」表格，与卡若AI 使用手册的 `images/README.md` 形式一致。
|
|||
|
|
6. **同步**：手册与 images 一并提交、一并同步（如 Git/Gitea），不分离。
|
|||
|
|
|
|||
|
|
### 4.3 图片命名与索引示例
|
|||
|
|
|
|||
|
|
**images/README.md 示例**：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 使用手册配图
|
|||
|
|
|
|||
|
|
| 文件名 | 说明 | 引用章节 |
|
|||
|
|
|:---|:---|:---|
|
|||
|
|
| 系统架构图.png | 整体架构与模块关系 | 第1章 总览 |
|
|||
|
|
| 登录流程.png | 用户登录步骤 | 第2章 快速开始 |
|
|||
|
|
| 控制台首页.png | 控制台首页截图 | 第3章 功能说明 |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、与卡若AI 使用手册的对应关系
|
|||
|
|
|
|||
|
|
| 卡若AI 使用手册 | 项目使用手册可对应 |
|
|||
|
|
|:---|:---|
|
|||
|
|
| 第一篇 认识… / 第二篇 快速入门 | 第一篇 产品介绍 / 第二篇 快速开始 |
|
|||
|
|
| 第三篇 功能详解（按模块） | 第三篇 功能说明（按功能/页面） |
|
|||
|
|
| 第四篇 运营/规范 | 第四篇 配置与运维（若有） |
|
|||
|
|
| 第五篇 网站/控制台 | 按项目实际（如 第五篇 API 与集成） |
|
|||
|
|
| 第六篇 进阶 | 按项目实际（如 进阶与扩展） |
|
|||
|
|
| 附录 A/B/C/D | 附录 速查/命令/FAQ/更新记录 |
|
|||
|
|
|
|||
|
|
项目可只保留 2～4 篇 + 附录，但**目录清晰、每章独立 .md、配图在 images/ 并写索引**三项不变。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、生成时的 AI 协作指令
|
|||
|
|
|
|||
|
|
当用户说「生成使用手册」「写使用手册」「按卡若AI 手册结构写手册」时：
|
|||
|
|
|
|||
|
|
1. **先读**：本规范 + 卡若AI `运营中枢/使用手册/README.md`（了解总目录与篇章形式）。
|
|||
|
|
2. **再规划**：根据当前项目功能，列出「篇→章」目录草案，并列出配图清单（架构图、流程图、截图）。
|
|||
|
|
3. **执行**：按本规范创建 `9、手册/` 下 README、各篇文件夹、各章 .md；创建 `images/` 与 images/README.md；生成或采集图片并引用、登记。
|
|||
|
|
4. **校验**：是否每章有导航、是否所有图在 images/ 且已登记、README 总目录是否完整。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、参考路径（卡若AI 主仓库）
|
|||
|
|
|
|||
|
|
- **使用手册总目录**：`/Users/karuo/Documents/个人/卡若AI/运营中枢/使用手册/README.md`
|
|||
|
|
- **配图索引示例**：`运营中枢/使用手册/images/README.md`
|
|||
|
|
- **单章示例**：`运营中枢/使用手册/第一篇_认识卡若AI/02_架构总览.md`（含图片引用与图题）
|