aitu/docs/user-manual

用户手册生成系统

快速开始

一键更新用户手册（推荐）

pnpm manual:update

这个命令会自动完成：

1. 运行 E2E 测试生成带标注的截图
2. 自动复制截图到正确位置
3. 编译 MDX 文档生成 HTML

分步执行

如果需要单独执行某个步骤：

# 1. 只生成截图（需要开发服务器运行）
pnpm manual:screenshots

# 2. 只编译 HTML（会自动复制 E2E 截图）
pnpm manual:build

目录结构

docs/user-manual/
├── config.yaml          # 配置文件
├── content/             # MDX 源文件
│   ├── index.mdx
│   ├── basics/
│   ├── drawing/
│   ├── ai-generation/
│   └── advanced/
└── README.md            # 本文档

apps/web-e2e/
├── src/manual-gen/      # 截图生成测试
│   ├── basics.manual.spec.ts
│   ├── drawing.manual.spec.ts
│   ├── ai-generation.manual.spec.ts
│   └── advanced.manual.spec.ts
├── src/utils/
│   └── screenshot-annotations.ts  # 标注工具库
└── test-results/
    └── manual-screenshots/  # 生成的截图（自动复制）

apps/web/public/user-manual/  # 最终输出
├── index.html
├── *.html               # 各页面
└── screenshots/         # 截图文件

添加新截图

1. 编辑 apps/web-e2e/src/manual-gen/ 目录下的测试文件
2. 使用标注工具库添加带标注的截图：

import {
  screenshotWithAnnotations,
  circleOnElement,
  highlightElement,
  arrowToElement,
  circle,
  arrow,
  highlight,
} from '../utils/screenshot-annotations';

// 基于元素位置的标注（推荐）
const btn = page.getByRole('button', { name: /示例/ });
const annotations = [];

// 高亮框 + 标签（标签位置：top/bottom/left/right）
const highlight = await highlightElement(btn, '按钮说明', 4, undefined, 'right');
if (highlight) annotations.push(highlight);

// 箭头标注（direction: left/right/up/down）
const arrow = await arrowToElement(btn, '说明文字', 'left', { x: 20 });
if (arrow) annotations.push(arrow);

// 数字圆圈
const circle = await circleOnElement(btn, 1, { x: -30 });
if (circle) annotations.push(circle);

// 截图
await screenshotWithAnnotations(
  page,
  'test-results/manual-screenshots/example.png',
  annotations
);

3. 在 MDX 文档中引用截图：

<Screenshot id="example" />
<p class="screenshot-caption">截图说明</p>

4. 运行 pnpm manual:update 更新

标注位置策略

• 左侧工具栏元素：使用 labelPosition='right' 或 direction='left'
• 右侧面板元素：使用 labelPosition='left' 或 direction='right'
• 对话框/弹窗：基于对话框 boundingBox 计算相对位置
• 避免遮挡：标注放在元素的 tooltip 通常出现的位置

常见问题

截图位置不对？

检查标注工具的参数：

• highlightElement(element, label, padding, color, labelPosition)
• arrowToElement(element, label, direction, offset, color)
• circleOnElement(element, number, offset, color)

测试失败？

1. 确保开发服务器运行：pnpm start
2. 检查元素选择器是否正确
3. 添加适当的等待时间：await page.waitForTimeout(500)

需要调试？

# 显示浏览器运行测试
cd apps/web-e2e && npx playwright test --project=manual --headed

# 查看测试报告
npx playwright show-report apps/web-e2e/playwright-report

录制测试代码

使用 Playwright Codegen 录制用户操作，自动生成测试代码：

pnpm manual:record

1. 浏览器窗口打开后，进行你想录制的操作
2. Playwright Inspector 窗口会显示生成的代码
3. 复制代码到测试文件中

生成 GIF 动图

步骤 1：录制视频

# 运行带视频录制的测试
pnpm manual:video

# 或单独运行某个测试
cd apps/web-e2e && CI= npx playwright test --project=manual-video -g "测试名称"

视频保存在 apps/web-e2e/test-results/ 目录下（WebM 格式）。

步骤 2：转换为 GIF

需要安装 ffmpeg：

# macOS
brew install ffmpeg

# 转换视频为 GIF（带裁剪）
node scripts/video-to-gif.js --test "测试名称" --trim 2.9

裁剪参数说明

# 从第 2 秒开始
node scripts/video-to-gif.js --trim 2

# 从第 2 秒开始，取 15 秒
node scripts/video-to-gif.js --trim 2:15

一键生成思维导图 GIF

pnpm manual:gif:mindmap

这个命令会自动：

1. 录制思维导图创建演示视频
2. 裁剪并转换为 GIF
3. 重建用户手册