# Just-Product-Preview：AI代理原生的预览资源生成工具包

> Just-Product-Preview是一个面向AI代理的预览资源生成工具包，支持将本地应用、URL和HTML转换为README就绪的视觉证明。它提供CLI工具、可复用包、配方、清单和GitHub Action，帮助开发者自动化生成截图、视频、GIF等预览资源。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-18T18:43:50.000Z
- 最近活动: 2026-05-18T18:56:13.964Z
- 热度: 163.8
- 关键词: Just-Product-Preview, 预览生成, AI代理, 截图, 视频录制, GIF, CLI工具, GitHub Action, 自动化, Playwright
- 页面链接: https://www.zingnex.cn/forum/thread/just-product-preview-ai
- Canonical: https://www.zingnex.cn/forum/thread/just-product-preview-ai
- Markdown 来源: ingested_event

---

# Just-Product-Preview：AI代理原生的预览资源生成工具包

## 问题：预览资源制作的痛点

在软件开发过程中，预览资源（截图、视频、GIF等）扮演着重要角色。它们是README的视觉门面，是Pull Request的直观证明，是发布说明的生动展示。然而，制作这些预览资源往往是一个繁琐且容易出错的过程：

**手动操作繁琐**：开发者需要手动打开浏览器、调整到合适的视口、执行一系列操作、截图或录屏、编辑、导出。这个过程不仅耗时，而且难以保持一致性。

**本地开发难展示**：很多功能在本地开发阶段就已经完成，但尚未部署到生产环境。如何向团队成员或审查者展示这些本地工作的成果？

**重复劳动**：每个项目都需要类似的预览资源，但开发者往往需要重复相同的操作流程。

**AI代理的困境**：AI代理可以比团队更快地构建UI，但团队审查的速度跟不上。代理生成的代码如何快速转化为可审查的视觉证明？

Just-Product-Preview正是为解决这些问题而设计的。

## 解决方案：自动化的预览管道

Just-Product-Preview是一个面向AI代理的预览管道，能够将本地应用、URL和HTML转换为README就绪的视觉证明。它由`just-preview` CLI、可复用包、配方、清单和GitHub Action组成。

核心理念是：**在部署之前捕获本地应用，将视觉证明附加到Pull Request和发布中，为移动应用、文档、仪表板、落地页和PR预览维护可重复的配方**。

## 核心功能：从命令到资源

Just-Product-Preview提供了一系列简洁的CLI命令，覆盖各种预览需求：

### 1. 缩略图生成（Thumbnail）

```bash
just-preview thumbnail --url https://example.com --out outputs/cover.png
```

为README生成封面图片，支持PNG或JPEG格式。这是最基础的用例，几乎每个开源项目都需要。

### 2. 视频录制（Video）

```bash
just-preview video --url https://example.com --out outputs/preview.mp4 --duration 8
```

录制产品演示视频，支持WebM、MP4或MOV格式。适用于展示交互流程和动态效果。

### 3. GIF生成

```bash
just-preview gif --url http://localhost:3000 --out outputs/preview.gif --duration 6 --gif-width 960
```

生成轻量级动画预览，支持大小控制。GIF虽然画质不如视频，但兼容性更好，可以直接在GitHub README中播放。

### 4. 脚本化捕获（Recipe）

```bash
just-preview recipe --config recipes/landing-page.json
```

基于配方的录制，支持等待、滚动、点击、填充、悬停、按键和截图等步骤。这是最强大的功能，可以精确控制录制流程。

### 5. 代理交接（Manifest）

```bash
just-preview video --serve-command "pnpm dev" --serve-url http://localhost:5173 --manifest outputs/preview.manifest.json
```

生成JSON格式的工件清单，供CI和自动化使用。这让AI代理可以机器可读的方式处理预览资源，而不是依赖松散的文件路径。

### 6. 发布集成（Publish）

```bash
just-preview publish --manifest "outputs/*.manifest.json" --format readme --out outputs/readme-preview.md
```

将生成的清单转换为审查就绪的Markdown，支持README片段、GitHub PR预览评论、画廊或发布说明格式。

## 支持的配方步骤

配方（Recipe）是Just-Product-Preview最强大的功能。它允许你精确控制预览录制流程：

```json
{
  "serveCommand": "pnpm dev",
  "serveUrl": "http://localhost:5173",
  "serveSilent": true,
  "output": "outputs/preview.mp4",
  "viewport": "desktop",
  "steps": [
    { "type": "wait", "ms": 800 },
    { "type": "scroll", "to": 600, "duration": 1200 },
    { "type": "click", "selector": "[data-preview='demo-button']" }
  ]
}
```

支持的步骤类型包括：

| 步骤 | 用途 |
|------|------|
| wait | 暂停等待动画、数据或过渡效果完成 |
| scroll | 录制长页面，展示下方内容 |
| click | 触发UI状态变化 |
| fill | 输入表单内容 |
| hover | 展示悬停状态 |
| press | 演示键盘操作流程 |
| screenshot | 在录制过程中捕获静态帧 |

这些步骤可以组合成复杂的交互流程，确保预览资源准确展示产品的关键特性。

## 本地应用捕获

Just-Product-Preview的一个独特优势是支持本地应用捕获。你可以启动本地开发服务器，等待其就绪，然后自动捕获预览：

```bash
just-preview video \
  --serve-command "pnpm dev" \
  --serve-url http://localhost:5173 \
  --out outputs/preview.mp4 \
  --duration 8 \
  --manifest outputs/preview.manifest.json
```

对于monorepo项目，可以指定子目录：

```bash
just-preview thumbnail \
  --serve-command "pnpm dev" \
  --serve-cwd apps/web \
  --serve-url http://localhost:3000 \
  --serve-silent \
  --out outputs/cover.png
```

`--serve-silent`选项会抑制服务器输出，让录制过程更加干净。

## 项目架构：Monorepo设计

Just-Product-Preview采用monorepo架构，将所有组件版本统一管理：

```
Just-Product-Preview/
├── apps/
│   ├── cli/              # just-preview命令
│   └── docs/             # 文档构建器
├── packages/
│   ├── core/             # 共享的浏览器自动化、设备、本地服务器生命周期、配置、输出路径、清单、诊断和文件系统工具
│   ├── html2thumbnail/   # HTML转缩略图
│   ├── html2video/       # HTML转视频、MP4、WebM、MOV、GIF
│   ├── preview-recipe/   # 基于配方的录制
│   └── preview-publisher/ # README、PR、画廊和发布说明Markdown生成
├── docs/                 # 用户文档
├── examples/             # 基础URL、本地HTML、本地应用、发布工作流、Action示例
├── recipes/              # 可复用的捕获配方
├── schema/               # 配置的JSON Schema
├── scripts/              # 发布、验证和冒烟检查
└── action.yml            # 可复用的复合GitHub Action
```

这种架构的优势在于：
- 所有组件版本一致，避免版本冲突
- 便于跨包共享代码和工具
- 统一的构建和发布流程
- 便于贡献者理解和参与

## GitHub Actions集成

Just-Product-Preview提供GitHub Action，可以集成到CI/CD流程中：

```yaml
- uses: Just-Agent/Just-Product-Preview@v1
  with:
    command: 'video'
    url: 'https://example.com'
    output: 'outputs/preview.mp4'
```

这使得预览资源的生成可以自动化，每次代码提交都能生成最新的预览。

## AI代理友好设计

Just-Product-Preview的设计充分考虑了AI代理的使用场景：

**机器可读的清单**：代理可以生成和消费JSON格式的清单文件，而不是处理松散的文件路径。

**可重复的配方**：配方文件可以版本控制，确保不同环境、不同代理都能产生一致的输出。

**Markdown输出**：`publish`命令可以将预览资源转换为Markdown格式，便于人类审查和文档集成。

**清晰的CLI接口**：命令和参数设计简洁明了，便于代理理解和调用。

## 使用场景

Just-Product-Preview适用于多种场景：

**开源项目展示**：自动生成README封面和演示视频，提升项目的专业形象。

**PR预览**：在Pull Request中自动附加UI变更的视觉证明，帮助审查者快速理解改动。

**文档维护**：自动化生成文档中的截图，确保文档与代码保持同步。

**发布说明**：为每个版本自动生成预览资源，丰富发布说明的内容。

**设计审查**：在设计迭代过程中自动生成对比预览，便于团队讨论和决策。

**回归测试**：通过配方录制关键用户流程，作为视觉回归测试的基础。

## 快速开始

安装和构建monorepo：

```bash
pnpm install
pnpm build
```

安装Playwright使用的浏览器和视频运行时：

```bash
pnpm browsers:install
```

检查环境：

```bash
pnpm just-preview doctor
```

尝试示例：

```bash
pnpm just-preview video \
  --serve-command "node server.mjs" \
  --serve-cwd examples/local-app \
  --serve-url http://127.0.0.1:4177 \
  --serve-silent \
  --out outputs/local-app-preview.webm \
  --duration 5
```

## 总结

Just-Product-Preview填补了AI辅助开发流程中的一个重要空白：如何将AI快速生成的代码转化为可审查的视觉证明。通过自动化的预览管道、可重复的配方和AI友好的设计，它让预览资源的生成从繁琐的手动操作变成了自动化的CI/CD环节。

对于希望提升项目展示质量、加速代码审查流程的团队来说，Just-Product-Preview是一个值得尝试的工具。它不仅提高了效率，更重要的是确保了预览资源的一致性和可维护性。

项目地址：https://github.com/Just-Agent/Just-Product-Preview