pre-post

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pre-Post Screenshot Skill

Pre-Post 截图工具

Package:
pre-post
Visual diff tool for PRs — fastest path from code change to visual documentation.

包名：
pre-post
用于PR的视觉差异对比工具——从代码变更到视觉文档的最快路径。

Agent Behavior Rules

Agent 行为规则

DO NOT:

Switch git branches, stash changes, start dev servers, or assume what "before" is
Use
```
--full
```
unless user explicitly asks for full page / full scroll capture
Post screenshots to PR without user approval

DO:

Use
```
--markdown
```
when user wants PR integration or markdown output
Use
```
--responsive
```
to capture both desktop and mobile viewports
Use
```
--mobile
```
/
```
--tablet
```
if user mentions phone, mobile, tablet, responsive
Assume current state is After (localhost = after, production = before)
Show screenshots to user before posting to PR
If user provides only one URL, ASK: "What URL should I use for the 'before' state? (production URL, preview deployment, or another local port)"

禁止操作：

切换git分支、暂存变更、启动开发服务器，或自行假设“之前”的状态
除非用户明确要求全页面/全滚动截图，否则不要使用
```
--full
```
参数
未获得用户批准就将截图发布到PR

建议操作：

当用户需要PR集成或Markdown输出时，使用
```
--markdown
```
参数
使用
```
--responsive
```
参数同时捕获桌面和移动端视口
如果用户提及手机、移动端、平板或响应式，使用
```
--mobile
```
/
```
--tablet
```
参数
默认当前状态为之后（localhost=之后，生产环境=之前）
在发布到PR前先向用户展示截图
如果用户仅提供一个URL，询问："我应该使用哪个URL作为‘之前’的状态？（生产环境URL、预览部署地址或其他本地端口）"

Execution Order

执行步骤

1. Pre-flight Checks

1. 预检检查

bash

undefined

bash

undefined

Detect running dev server

检测运行中的开发服务器

lsof -i :3000 2>/dev/null || lsof -i :3001 2>/dev/null || lsof -i :5173 2>/dev/null || lsof -i :8080 2>/dev/null


If no dev server is running, tell the user to start one.

```bash

lsof -i :3000 2>/dev/null || lsof -i :3001 2>/dev/null || lsof -i :5173 2>/dev/null || lsof -i :8080 2>/dev/null


如果没有运行开发服务器，请告知用户启动一个。

```bash

Check production URL is accessible

检查生产环境URL是否可访问

curl -s -o /dev/null -w "%{http_code}" "<production-url>"


- **200** → proceed
- **401/403** → warn user: "Production URL requires authentication. Options: (1) provide a public URL, (2) skip 'before' and capture after-only, (3) provide auth cookies"
- **No production URL** → "after-only" mode: screenshot localhost only, label as current state

curl -s -o /dev/null -w "%{http_code}" "<production-url>"


- **200** → 继续执行
- **401/403** → 提醒用户："生产环境URL需要身份验证。可选方案：(1) 提供公共URL，(2) 跳过‘之前’状态，仅捕获‘之后’状态，(3) 提供身份验证Cookie"
- **无生产环境URL** → "仅之后"模式：仅截取localhost的截图，标记为当前状态

2. Route Detection + Refinement

2. 路由检测与优化

bash

undefined

bash

undefined

Detect affected routes from git diff

从git diff中检测受影响的路由

npx pre-post detect


This outputs JSON with detected routes, confidence levels, and source files.

**Claude's role:** Review the JSON output using conversation context:
- Add routes you know are affected from the work done in this session
- Remove false positives (e.g., API-only changes)
- For dynamic routes (e.g., `/blog/[slug]`), ask user for a sample value
- Present to user: "I'll screenshot these routes: `/dashboard`, `/settings`. Want to add or change any?"

npx pre-post detect


此命令会输出包含检测到的路由、置信度和源文件的JSON数据。

**Claude的职责：** 根据对话上下文审查JSON输出：
- 添加本次会话中已知受影响的路由
- 移除误报项（例如，仅API变更的路由）
- 对于动态路由（如`/blog/[slug]`），向用户询问示例值
- 向用户展示："我将为以下路由截图：`/dashboard`、`/settings`。是否需要添加或修改？"

3. Screenshot Capture

3. 截图捕获

Option A: CLI (preferred — deterministic)

bash

undefined

选项A：CLI（推荐——结果可预测）

bash

undefined

Single route, desktop only

单一路由，仅桌面端

npx pre-post compare
--before-base https://prod.com
--after-base http://localhost:3000
--routes /dashboard
--output /tmp/pre-post

Multiple routes, responsive (desktop + mobile)

多个路由，响应式（桌面+移动端）

npx pre-post compare
--before-base https://prod.com
--after-base http://localhost:3000
--routes /dashboard,/settings,/
--responsive
--output /tmp/pre-post


**Option B: Playwright MCP (for more control)**

Use when you need custom waits, interactions, or complex page states:

browser_resize(1280, 800) browser_navigate("https://prod.com/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-before.png")

browser_navigate("http://localhost:3000/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-after.png")

npx pre-post compare
--before-base https://prod.com
--after-base http://localhost:3000
--routes /dashboard,/settings,/
--responsive
--output /tmp/pre-post


**选项B：Playwright MCP（用于更多自定义控制）**

当你需要自定义等待、交互或处理复杂页面状态时使用：

browser_resize(1280, 800) browser_navigate("https://prod.com/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-before.png")

browser_navigate("http://localhost:3000/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-after.png")

Mobile

移动端

browser_resize(375, 812) browser_navigate("https://prod.com/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-before.png")

browser_navigate("http://localhost:3000/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-after.png")

undefined

browser_resize(375, 812) browser_navigate("https://prod.com/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-before.png")

browser_navigate("http://localhost:3000/dashboard") browser_wait_for(time: 3) browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-after.png")

undefined

4. User Approval

4. 用户确认

Show screenshots in conversation. Ask: "Here are the before/after screenshots. Should I post to PR, retake any, or add more pages?"

在对话中展示截图。询问："这是前后对比截图。是否需要发布到PR、重新截取或添加更多页面？"

5. Upload + PR Markdown

5. 上传与PR Markdown生成

bash

undefined

bash

undefined

Upload and generate markdown

上传并生成Markdown

mkdir -p /tmp/pre-post ./scripts/upload-and-copy.sh /tmp/pre-post/before.png /tmp/pre-post/after.png --markdown


Or use the CLI's built-in upload:

```bash
npx pre-post <before.png> <after.png> --markdown

For multi-route PRs, generate this format:

markdown

undefined

mkdir -p /tmp/pre-post ./scripts/upload-and-copy.sh /tmp/pre-post/before.png /tmp/pre-post/after.png --markdown


或者使用CLI内置的上传功能：

```bash
npx pre-post <before.png> <after.png> --markdown

对于多路由的PR，生成以下格式：

markdown

undefined

Visual Changes

视觉变更

/dashboard

/dashboard

<details open> <summary>Desktop (1280x800)</summary>

Pre	Post

</details> <details> <summary>Mobile (375x812)</summary>

Pre	Post

</details>

Captured by pre-post

undefined

<details open> <summary>Desktop (1280x800)</summary>

Pre	Post

</details> <details> <summary>Mobile (375x812)</summary>

Pre	Post

</details>

Captured by pre-post

undefined

6. PR Integration

6. PR集成

bash

undefined

bash

undefined

Get current PR

获取当前PR

gh pr view --json number,body

Append screenshots to PR body

将截图添加到PR描述末尾

gh pr edit <number> --body "<existing-body>

<generated-markdown>"


If no `gh` CLI: output markdown and tell user to paste manually.

gh pr edit <number> --body "<existing-body>

<generated-markdown>"


如果没有`gh` CLI：输出Markdown并告知用户手动粘贴。

Quick Reference

快速参考

bash

undefined

bash

undefined

Basic usage (two URLs)

基础用法（两个URL）

pre-post site.com localhost:3000

Detect routes from git diff

从git diff中检测路由

pre-post detect pre-post detect --framework nextjs-app

Compare with auto-detected routes

使用自动检测的路由进行对比

pre-post run --before-base https://prod.com --after-base http://localhost:3000

Compare specific routes

对比特定路由

pre-post compare --before-base URL --after-base URL --routes /dashboard,/settings

Responsive (desktop + mobile)

响应式（桌面+移动端）

pre-post compare --before-base URL --after-base URL --responsive

From existing images

从现有图片生成对比

pre-post before.png after.png --markdown

Via npx

通过npx使用

npx pre-post detect npx pre-post compare --before-base URL --after-base URL


| Flag | Description |
|------|-------------|
| `-m, --mobile` | Mobile viewport (375x812) |
| `-t, --tablet` | Tablet viewport (768x1024) |
| `--size <WxH>` | Custom viewport |
| `-f, --full` | Full scrollable page |
| `-s, --selector` | CSS selector to capture |
| `-r, --responsive` | Desktop + mobile capture |
| `--routes <paths>` | Explicit route list (comma-separated) |
| `--max-routes <n>` | Max detected routes (default: 5) |
| `--framework <name>` | Force framework detection |
| `--before-base <url>` | Production URL |
| `--after-base <url>` | Localhost URL |
| `-o, --output` | Output directory (default: ~/Downloads) |
| `--markdown` | Upload images & output markdown |
| `--upload-url <url>` | Upload endpoint (overrides git-native default) |

npx pre-post detect npx pre-post compare --before-base URL --after-base URL


| 参数 | 说明 |
|------|-------------|
| `-m, --mobile` | 移动端视口（375x812） |
| `-t, --tablet` | 平板视口（768x1024） |
| `--size <WxH>` | 自定义视口尺寸 |
| `-f, --full` | 全滚动页面截图 |
| `-s, --selector` | 要捕获的CSS选择器 |
| `-r, --responsive` | 同时捕获桌面和移动端截图 |
| `--routes <paths>` | 明确指定的路由列表（逗号分隔） |
| `--max-routes <n>` | 最大检测路由数（默认：5） |
| `--framework <name>` | 强制指定框架类型 |
| `--before-base <url>` | 生产环境URL |
| `--after-base <url>` | localhost URL |
| `-o, --output` | 输出目录（默认：~/Downloads） |
| `--markdown` | 上传图片并输出Markdown |
| `--upload-url <url>` | 自定义上传端点（覆盖默认的Git原生上传） |

Image Upload

图片上传

Screenshots are committed to

.pre-post/

on the current PR branch and served via GitHub blob URLs pinned to the commit SHA. This works for both public and private repos — blob URLs are same-origin on GitHub, so the markdown renderer resolves them with the viewer's authentication.

bash

undefined

截图将提交到当前PR分支的

.pre-post/

目录，并通过绑定到提交SHA的GitHub blob URL提供访问。此方式适用于公共和私有仓库——blob URL在GitHub上是同源的，因此Markdown渲染器会使用查看者的身份验证信息解析它们。

bash

undefined

Default (git-native — commits to PR branch, works on any repo)

默认方式（Git原生——提交到PR分支，适用于所有仓库）

./scripts/upload-and-copy.sh before.png after.png --markdown

Explicit override for external storage:

显式指定外部存储：

IMAGE_ADAPTER=0x0st ./scripts/upload-and-copy.sh before.png after.png --markdown

undefined

IMAGE_ADAPTER=0x0st ./scripts/upload-and-copy.sh before.png after.png --markdown

undefined

Error Reference

错误参考

Error	Fix
`command not found`	`npm install -g @juangadm/pre-post`
`browserType.launch: Executable doesn't exist`	`npx playwright install chromium`
401/403 on production URL	See pre-flight section above
Element not found	Verify selector exists on page
No changed files detected	Specify routes manually with `--routes`
Could not determine commit SHA	Ensure `git push` succeeded and HEAD is valid

错误信息	解决方法
`command not found`	`npm install -g @juangadm/pre-post`
`browserType.launch: Executable doesn't exist`	`npx playwright install chromium`
生产环境URL返回401/403	参考上面的预检检查部分
元素未找到	确认页面上存在该选择器
未检测到变更文件	使用 `--routes` 参数手动指定路由
无法确定提交SHA	确保 `git push` 已成功且HEAD有效