# chrome-manual-vite-press

**Repository Path**: jpw_code/chrome-manual-vite-press

## Basic Information

- **Project Name**: chrome-manual-vite-press
- **Description**: 通过浏览器插件，浏览器扩展原型，只做录制 + Markdown 导出。在正式网站上正常操作，扩展在后台自动录屏/截图 + 记录点击位置和描述，最后导出为 Markdown。
核心功能设计
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手册录制器

Chrome 浏览器扩展，**录制网页操作步骤并自动生成 VitePress 用户手册**。

在目标系统页面上操作时，扩展自动捕获点击、输入、选择、提交等交互事件，附带截图标注，最终导出为 Markdown 文档。

## 功能概览

- **操作录制** — 自动捕获点击、输入、下拉选择、表单提交、SPA 页面导航
- **截图标注** — 每次操作自动截取可见标签页，在点击位置绘制红色靶心标记
- **文档大纲树** — 模块 → 分类 → 步骤 三级树形结构，可折叠、可拖拽排序
- **多模块管理** — 支持同时录制多个功能模块，自由添加预定义或自定义模块
- **内联编辑** — 双击树中任意节点即可重命名（模块名、分类名、步骤描述）
- **智能导航** — 检测 SPA 页面跳转，自动创建新分类并弹出确认提示
- **多格式导出** — 导出为 ZIP（含截图）、复制 Markdown 到剪贴板，或直接写入本地文件夹

## 安装

### 开发模式加载

1. 克隆仓库或下载源码
2. 打开 Chrome，访问 `chrome://extensions`
3. 打开右上角「开发者模式」
4. 点击「加载已解压的扩展程序」
5. 选择 `extension/dist` 目录
6. 扩展图标出现在工具栏

### 构建

```bash
cd extension
npm install
npm run build      # 生产构建 → dist/
npm run dev        # 开发模式（文件变更自动构建）
```

## 使用指南

### 1. 开始录制

点击扩展图标打开 Popup 面板：

1. 在「目标模块」下拉框中选择要录制的模块（如「用户管理」「考试管理」等）
2. 点击 **开始录制** 按钮
3. 扩展自动打开侧边栏面板，显示文档大纲树

> 录制过程中 Popup 面板状态会同步更新，Start 按钮变为禁用状态。

### 2. 侧边栏：文档大纲树

侧边栏是核心工作区，展示 **模块 → 分类 → 步骤** 三级树形结构：

```
📘 用户管理                     ← 模块节点（双击重命名）
  📄 1. 列表页操作  🎯 [2]      ← 分类节点
    1. 点击「查询」按钮           ← 步骤节点（可拖拽排序）
    2. 在「姓名」输入框输入"张三"
  📄 2. 新增/编辑用户    [0]
    操作页面，步骤将出现在此处...
```

#### 节点操作方式

| 节点类型 | 展开/折叠 | 设为录制目标 | 重命名 | 删除 |
|---------|----------|------------|--------|------|
| **模块** | 点击模块标题行 | — | 双击模块名称 | 不支持直接删除 |
| **分类** | 点击分类标题行 | 点击 🎯 按钮 | 双击分类名称 | 点击 ✕ 按钮 |
| **步骤** | 始终展开 | — | 单击步骤描述文字 | 鼠标悬停后点击 ✕ |

#### 录制目标（🎯 按钮）

每个分类节点前有 🎯 按钮。点击后该分类变为**绿色高亮**，此后所有操作都录制到这个分类下。

- 绿色左边框 + 绿色背景 = 当前录制目标
- 切换到另一个分类后，新步骤归入新目标

### 3. 管理模块

点击侧边栏底部「**+ 添加模块**」按钮：

- **自定义模块** — 在输入框中输入模块名称，按 Enter 或点击「添加」
- **预定义模块** — 从下方列表中选择（共 17 个预置模块）
- 已添加的模块显示 ✓ 标记，不可重复添加

### 4. 管理分类

在当前模块折叠区域下方点击「**+ Add Section**」创建自定义分类。

页面导航时，扩展会自动检测 URL 变化，弹出确认提示：

> "新页面 'XXX' — 创建新分类？ [保留] [移除]"

5 秒内不操作则自动保留。

### 5. 编辑步骤

- **修改描述** — 单击步骤文字进入编辑模式，修改后按 Enter 保存，Esc 取消
- **拖拽排序** — 拖拽步骤到另一个步骤上方释放，即可跨分类调整顺序
- **查看截图** — 点击步骤缩略图可放大查看带标注的截图

### 6. 停止录制

在 Popup 或侧边栏点击 **停止** 按钮。停止后已录制的数据保留在树中，可继续编辑和导出。

### 7. 导出文档

侧边栏工具栏选择 **📄 导出文档**，自动停止录制并打包：

| 选项 | 说明 |
|------|------|
| **导出全部模块 (ZIP)** | 打包所有有步骤的模块 |
| **导出当前模块 (ZIP)** | 仅导出当前选中的模块 |

导出的 ZIP 解压后可直接运行，包含在线预览编辑器：

```
manual-recorder-{timestamp}.zip
├── modules/                 # 录制的 Markdown 文档
│   └── xxx.md
├── images/                  # 带靶心标注的截图
│   └── 模块名/
│       └── {stepId}.png
├── server.py                # 后端服务（Python）
├── index.html               # 在线预览 & 编辑页面
├── export_word.py           # Word 导出模块
├── preview.sh               # macOS / Linux 启动脚本
├── preview.bat              # Windows CMD 启动脚本
├── preview.ps1              # Windows PowerShell 启动脚本
└── README.md                # 使用说明
```

**导出 ZIP 后的使用步骤**：

```bash
# 1. 解压 ZIP
unzip manual-recorder-xxx.zip -d my-docs && cd my-docs

# 2. 安装依赖（Word 导出需要）
pip3 install python-docx

# 3. 启动（二选一）
python3 server.py            # 直接运行
# 或
chmod +x preview.sh && ./preview.sh start   # macOS/Linux

# 4. 浏览器打开 http://localhost:8765
```

> 📦 最新运行文件可从仓库获取：https://gitee.com/jpw_code/md-web-editor  
> 🧩 扩展源码：https://gitee.com/jpw_code/chrome-manual-vite-press

## 生成的 Markdown 示例

```markdown
# 用户管理

## 功能概述
用户管理模块提供用户管理相关的创建、编辑、查询和管理功能。

## 前置条件
- 用户已登录系统
- 具有「用户管理」模块的访问权限

## 操作指南

### 1. 列表页操作
1. 点击「查询」按钮
   ![](images/employee/abc123.png)

2. 在「姓名」输入框中输入"张三"
   ![](images/employee/def456.png)
```

## 技术架构

```
extension/
├── src/
│   ├── popup/            # 扩展图标弹窗（启动/停止/打开侧边栏）
│   ├── sidepanel/        # 侧边栏主界面（文档大纲树）
│   ├── background/       # Service Worker（状态管理/导出）
│   ├── content/          # Content Script（事件捕获/截图标注）
│   ├── export/           # Markdown 生成/ZIP 打包/文件系统导出
│   └── shared/           # 类型定义/存储/消息协议/模块注册表
└── dist/                 # 构建产物（加载此目录）
```

- **Chrome Manifest V3** + Service Worker
- **Vite** 构建（`vite-plugin-web-extension`）
- **TypeScript** 全栈类型安全
- **JSZip** ZIP 打包
- **chrome.storage.session** 录制数据持久化

## 权限说明

| 权限 | 用途 |
|------|------|
| `activeTab` | 获取当前标签页以注入脚本和截图 |
| `scripting` | 动态注入 Content Script |
| `storage` | 保存录制会话数据和截图 |
| `sidePanel` | 打开侧边栏面板 |
| `downloads` | 下载导出的 ZIP 文件 |
| `tabs` | 获取和监听标签页状态 |
| `<all_urls>` | 在目标页面上捕获操作事件 |

## 预定义模块

共内置 17 个模块，每个模块预设 3-5 个操作分类：

用户管理、考试管理、考核管理、异常工单、班级管理、素材管理、招聘管理、权限管理、系统设置、通知管理、群组管理、设备管理、字典管理、分类管理、文件预览、个人中心、首页

可通过「添加模块 → 输入自定义名称」创建自定义模块。

## License

MIT License — 详见 [LICENSE](LICENSE) 文件。