# Pm Operation Manual

> 用于生成、撰写或创建操作手册或用户指南的技能。 触发场景：(1) "生成操作手册" "写操作手册" "创建操作手册" "用户手册", (2) "使用说明" "功能说明文档" "快速入门" "用户指南", (3) "导出操作手册" "操作手册导出Word" "用户手册转Word", (4) 生成系统管理员操作手册， (5) 生成终端用户手册或快速入门指南。 基于需求文档和现有前端页面生成操作手册。

- Skill: `idwong/pm-operation-manual` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add idwong/pm-operation-manual`
- Raw SKILL.md: https://api.skillmd.com/api/skills/idwong/pm-operation-manual/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: iDWong (https://skillmd.com/u/idwong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/idwong/pm-operation-manual

---


> **流程位置**：`pm-master` 阶段10 操作手册 ／ `dev-master` **阶段12 文档与发版**；也可单点直接调用。
> （两条流程的阶段号不同，按当前在跑的那条读。）
> 流程内落盘路径 `prd/release/{日期}-{项目}-用户操作手册-V{版本}.md`（流程门禁按 glob 匹配，命名带产品名/日期是正常的）。
> 上游读 `SPEC_SOURCE` + `dev/code/` 的代码（若有；由 `dev-master` 产出，`pm-master` 链路不出代码）。

# 操作手册生成器

## 角色定义

以资深技术文档工程师视角工作：
- ✅ 操作步骤完整清晰，不省略任何关键步骤
- ✅ 使用第二人称（"您"），界面元素用【】标注
- ✅ 每个功能覆盖：概述、新增、查询、编辑、删除及特殊操作
- ✅ 重要提示用"注意："或"⚠️"标注
- ❌ 不用技术术语（"调用接口"、"API请求"）
- ❌ 不说"系统会自动"，说"系统将显示/提示/跳转到"

## 支持的手册类型

| 类型 | 受众 | 特点 |
|------|------|------|
| 用户操作手册 | 终端用户 | 图文步骤，通俗语言，场景导向 |
| 管理员手册 | 系统管理员 | 完整功能，配置说明，权限管理 |
| 快速入门指南 | 新用户 | 只覆盖核心功能，10分钟上手 |

## 执行流程

### Step 0: 扫描项目上下文

先主动扫描项目，找到已有文档再开始工作：

| 优先级 | 文件类型 | 查找方式 |
|--------|---------|---------|
| 最高 | 需求说明书 | `Glob("**/*需求*说明书*.md")` |
| 高 | 功能清单 | `Glob("**/*功能*清单*.md")` |
| 低 | 路由/代码 | `src/router/`, `src/views/`, `src/api/` |

扫描完成后直接基于内容工作，只询问一件事：**是否需要自动截图**（需要先启动开发服务器）。

### Step 1: 读取模板

读取 `references/templates/operation-manual.md`，按模板结构生成文档。

### Step 2: 生成任务清单

**必须先展示任务清单，再逐个生成，禁止一次性写入整个文档。**

任务拆分原则：**拆到最小粒度，每个功能模块的每个子操作（新增、查询、编辑、删除、特殊操作）都是独立任务。**

任务清单示例：
```
| 序号 | 任务名称 | 状态 |
|------|---------|------|
| 1  | 创建文档骨架 | ⏳ 等待中 |
| 2  | 一、文档信息 + 二、系统简介 | ⏳ 等待中 |
| 3  | 三、快速开始 | ⏳ 等待中 |
| 4  | 4.1 工作台 - 功能概述 | ⏳ 等待中 |
| 5  | 4.1 工作台 - 待办事项操作 | ⏳ 等待中 |
| 6  | 4.2.1 设备档案 - 功能概述 | ⏳ 等待中 |
| 7  | 4.2.1 设备档案 - 新增设备 | ⏳ 等待中 |
| 8  | 4.2.1 设备档案 - 查询筛选 | ⏳ 等待中 |
| 9  | 4.2.1 设备档案 - 编辑设备 | ⏳ 等待中 |
| 10 | 4.2.1 设备档案 - 删除设备 | ⏳ 等待中 |
| 11 | 4.2.1 设备档案 - 导出数据 | ⏳ 等待中 |
| 12 | 4.2.2 设备分类 - 功能概述 | ⏳ 等待中 |
...
| N  | 五、常见问题 + 六、联系支持 | ⏳ 等待中 |
```

执行规则：
1. 每次只生成一个任务，生成前更新为 🔄，完成后更新为 ✅，重新展示清单
2. 第一个任务用 Write 创建文件，后续用 Edit 追加
3. 截图位置用 `> **[截图:功能名-操作]**` 占位

### Step 3: 截图处理（可选）

用户确认需要截图时，参考 `references/screenshot-guide.md` 执行截图方案。

截图完成后将占位标记替换为实际图片引用：
```markdown
<!-- 替换前 -->
> **[截图:device-list]**：设备档案列表

<!-- 替换后 -->
![设备档案列表](images/screenshots/device-list.png)
```

### Step 4: 导出文档（可选）

> **⚠️ 导出前后各一件事**：① 图片必须放在**文档同级的 `images/` 子目录**且**文件名纯 ASCII**——这是唯一可用形式，`img/`、`images/sub/`、`../images/`、与文档同目录、中文名**全都静默丢图**（脚本仍打印 `Export succeeded`，但 `word/media/` 是空的）；② 导出后立刻验 `unzip -l <docx> | grep -c "word/media/"`，数字必须等于图片张数。实测边界表见 `../common/README.md`。

**Windows（PowerShell）：** `../common/export-word.ps1 <markdown文件路径> operation-manual`

**跨平台：** `python ../common/export-word.py <markdown文件路径> operation-manual`

**Git Bash：** `bash ../common/export-word.sh <markdown文件路径> operation-manual`

## 文档命名规范

`prd/release/{日期}-{项目名称}-{手册类型}-V{版本号}.md`

示例：`prd/release/20260330-智慧厂区巡检系统-用户操作手册-V1.0.md`（研发链跑同一技能时落 `dev/release/`）

**修订：就地改也要改文件名。** **不论体量大小一律就地 `Edit` 改**（大文档尤其别整份重写，小文档也不要另存新文件）——**目录里永远只留最高版本那一份**；改完必须三样一起动——文首「文档版本」、版本记录表、**`mv` 把文件名的版本号也改掉**（局部修订 `+0.1`，结构性重写进大版本；日期取改动当天）。**绝不允许内容已是 V1.1、文件名还写 V1.0。**改名后 `grep` 一遍旧名，把 README 清单、下游「来源」行、`tools/` 脚本里的引用一并改掉。完整规则见 `../common/README.md`。

## 参考资源

- 操作手册模板：`references/templates/operation-manual.md`
- 截图操作指南：`references/screenshot-guide.md`

## 输入来源：代码页面之外，设计稿也算

项目还没出代码、但 `design-system/` 已有设计稿时，**可以拿设计稿当截图与步骤来源**
（三张预览墙 + 全屏页都是真实可交互页面，`FLOWS.md` 里就是一条条可照抄的操作路径）。
两条注意：① 必须是**过了闭环检查**的设计稿，未签字的不算数；② 手册里注明「界面以设计稿为准，上线后以实际页面复核」。

## 外部依赖与降级：Word/xlsx 导出

导出链走**技能库根的 `config.json`** 里的 `apiBaseUrl`（**端点不随仓库分发**，取值见该文件）。

| 情况 | 表现 | 怎么办 |
|---|---|---|
| 没配 `config.json` | 脚本报「无法从 config.json 读取 apiBaseUrl」 | 从同级 `config.example.json` 复制后填地址 |
| 服务没起 | `curl` 连不上 / 超时 | 先自检（在技能自己的目录下跑）：`curl -s -o /dev/null -w '%{http_code}' "$(python3 -c 'import json;print(json.load(open("../config.json"))["apiBaseUrl"])')/"`，**连得上就行**（`/` 不是路由，返回 404 也算通；连不上才是服务没起），起服务后重试 |
| 两者都缺 | —— | **降级交 md**，并在交付清单里写明「Word 未导出（端点未配）」 |

**三条不许**：不许把「导出失败」写成完成；不许跳过导出直接说交付完成；
不许在导出后不验图——`unzip -l x.docx | grep -c 'word/media/'` 要等于文档里的图片张数（文件名含中文会静默丢图）。