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