一个适配 Craft Agent / Claude Code 等 Agent 环境的手机预览技能，用于启动本地 Live Reload 服务器并生成二维码，扫码即可在手机上实时预览网页。
内置能力：
- 📱 扫码即览。生成终端二维码 + PNG 二维码，手机扫一扫直接打开本地页面。
- 🔄 实时热重载。修改
public/下的文件，桌面和手机浏览器自动刷新。 - 🌐 局域网投屏。自动获取本机 IP，电脑和手机在同一 WiFi 下即可访问。
- ⚙️ 零配置启动。不需要 nginx、不需要端口转发，开箱即用。
灵感来自日常开发中频繁需要在手机上调试移动端适配的场景——每次都要推到服务器太慢，本地又访问不了。这个 Skill 把整个流程压缩到一条指令。
npx skills add https://github.com/wildematt/phone-preview-skill --skill phone-preview-skill也可以直接把这段话发给有 shell 权限的 AI Agent：
帮我安装 phone-preview-skill。请把 https://github.com/wildematt/phone-preview-skill 克隆到 ~/.craft-agent/workspaces/<your-workspace>/skills/phone-preview，安装完成后检查 SKILL.md 和 assets/ 是否存在。
已经安装过的话，用这段话更新：
帮我更新 phone-preview-skill。请进入 ~/.craft-agent/workspaces/<your-workspace>/skills/phone-preview 执行 git pull，然后告诉我当前最新 commit。
安装后直接对 Agent 说：
帮我手机预览这个网页，我扫个码看看效果。
也可以试这些请求：
这个页面在手机上排版有问题，帮我预览一下。
我想在手机上看看这个 HTML 文件的效果。
帮我启动一个本地服务器，我要在手机上调试移动端样式。
把这份网页生成一个二维码，我要发给同事手机上看。
- 📱 扫码预览：生成终端二维码和 PNG 文件，手机扫一扫即可访问
- 🔄 Live Reload：文件修改后桌面和手机浏览器自动刷新，无需手动操作
- 🎨 CSS 热替换：修改 CSS 文件只更新样式，不刷新页面，表单状态和滚动位置不丢失
- 🌐 局域网访问：自动获取本机 IP，手机无需安装任何 App，浏览器直接打开
- 📦 轻量服务器：基于 Node.js 的 HTTP + WebSocket 服务器，资源占用极低
- 🖼 双二维码输出：终端 ASCII 二维码方便快速测试，PNG 文件方便保存和分享
- ⚙️ 智能端口探测：端口被占用时自动 +1 重试，无需手动干预
- 🔒 进程管理：PID 文件记录服务器状态，支持优雅停止
- 🔀 API 代理：支持代理
/api/*到后端服务，前端带后端的页面也能预览 - 🖥️ 跨平台：macOS / Linux / Windows WSL 均可使用
✅ 合适：移动端适配调试 / 响应式布局预览 / 分享本地页面给同事快速查看 / H5 活动页预览 / 手机端 UI 走查
❌ 不合适：需要公网访问的场景（仅限局域网）/ 需要 HTTPS 的 PWA 测试 / 多人同时连接的团队协作预览 / WebSocket 代理（当前仅代理 HTTP）
| 任务 | 推荐方式 |
|---|---|
| 移动端适配调试 | 启动服务后用手机实时查看，边改边刷新 |
| H5 页面预览 | 直接说"手机预览"，扫码在手机浏览器打开 |
| 分享本地页面 | 生成 PNG 二维码图片，发给同事扫码访问 |
| 响应式设计走查 | 手机和桌面同时打开，对比不同屏幕尺寸的显示效果 |
| 微信内置浏览器测试 | 手机扫码后在微信中打开链接（需在同一局域网） |
| 前端 + 后端联调 | 设置 PROXY_TARGET 代理 API 请求，前端页面可正常调用后端接口 |
- 比推服务器快：改代码秒级刷新，不用等部署，不用推到 staging 环境。
- 比 Charles 代理简单：不需要配置代理，不需要安装证书，扫个码就行。
- 比微信开发者工具轻：不需要引入完整框架，纯 HTML / CSS / JS 直接预览。
- 比截图调试准：真实设备渲染，能看到字体渲染、触摸交互、滚动行为等真实表现。
| 平台 | 状态 | 说明 |
|---|---|---|
| Craft Agent | ✅ 支持 | 原生 Skill 工作流，完整支持所有功能 |
| Claude Code | ✅ 支持 | 可安装为 workspace skill |
| Cursor / 其他本地 Agent | ✅ 可用 | 需要能读写文件并执行 shell 命令 |
| 普通 Chatbot | ❌ 不推荐 | 没有文件系统和 shell 时无法启动服务器 |
npx skills add https://github.com/wildematt/phone-preview-skill --skill phone-preview-skill帮我安装
phone-preview-skill这个 Skill。请按下面步骤做：
- 确保
~/.craft-agent/workspaces/<your-workspace>/skills/目录存在（不存在就创建）- 执行
git clone https://github.com/wildematt/phone-preview-skill.git ~/.craft-agent/workspaces/<your-workspace>/skills/phone-preview- 验证：
ls ~/.craft-agent/workspaces/<your-workspace>/skills/phone-preview/应该看到SKILL.md和assets/- 告诉我安装好了，之后我说"手机预览"之类的话就会触发这个 skill
把这段话复制粘贴给 Craft Agent / Claude Code / 任何有 shell 权限的 AI Agent，它会自动完成安装。
git clone https://github.com/wildematt/phone-preview-skill.git ~/.craft-agent/workspaces/<your-workspace>/skills/phone-preview装好后，Agent 会在对话里自动发现并调用这个 Skill。触发关键词：
- "手机预览"
- "扫码访问"
- "手机上看看"
- "二维码预览"
- "phone preview"
- "mobile preview"
- "帮我预览一下这个页面在手机上的效果"
Skill 本身是结构化工作流，Agent 会逐步引导：
- 识别目标文件 — 确认要预览的 HTML 文件或目录
- 准备服务目录 — 将文件复制到
.phone-preview/public/目录 - 启动服务器 — 在后台启动 Live Reload 服务器（默认端口 3000）
- 获取本机 IP — 自动获取局域网 IP 地址
- 生成二维码 — 输出终端二维码 + PNG 文件
- 呈现给用户 — 展示二维码图片，提供桌面预览链接
- 实时调试 — 修改
public/下的文件，浏览器自动刷新
详细说明见 SKILL.md。
phone-preview-skill/
├── SKILL.md ← Skill 主文件：工作流、前置条件、排障指南
├── README.md ← 本文件
└── assets/
├── preview-server.js ← Live Reload HTTP + WebSocket 服务器
├── generate-qr.js ← 二维码生成器（终端输出 + PNG 文件）
└── package.json ← npm 依赖声明（ws、qrcode）
- HTTP Server：基于 Node.js
http模块，提供静态文件服务 - WebSocket Server：复用 HTTP 端口（HTTP upgrade），无需额外端口
- 文件监听：使用
fs.watch监听public/目录，变更时通过 WebSocket 推送 - CSS 热替换：CSS 文件变更时发送
{type: 'css-update'}消息，客户端只替换<link>标签，不刷新页面 - 端口探测：从 3000 开始逐个尝试，找到可用端口后启动
- 进程管理：启动时写
server.pid（JSON 格式，含 PID、端口、IP）；支持 SIGTERM/SIGINT 优雅关闭 - API 代理：
/api/*请求自动转发到PROXY_TARGET，支持所有 HTTP 方法、请求体透传、CORS 头注入
- Node.js v18+
- npm 包：
ws、qrcode（通过assets/package.json管理） - 电脑和手机在同一 WiFi 网络下
安装依赖：
cd <skill_dir>/assets && npm install复制下面任意一条给 Agent：
帮我启动本地预览服务器，我要在手机上看看这个页面的移动端适配效果。
这个 HTML 文件在手机上排版有点问题，帮我预览一下，我扫个码看看。
我想把本地这个网页分享给同事在手机上看，帮我生成个二维码。
帮我开启 Live Reload，我要实时调试这个页面在手机上的显示效果。
电脑和手机不在同一个 WiFi 下能用吗？ 不能。这个 Skill 依赖局域网访问，电脑和手机必须连接同一个 WiFi 网络。
可以同时预览多个页面吗？ 当前版本一次只能预览一个页面。如需切换，需要先停止当前服务器再启动新的预览。
手机扫了码但打不开页面？
检查三点：① 确认电脑和手机在同一 WiFi；② 检查防火墙是否阻止了入站连接；③ 查看 server.pid 中记录的 IP 和端口是否正确（服务器会自动避开被占用的端口）。
二维码扫不了怎么办？ 终端输出的 ASCII 二维码在某些字体下可能不清晰，使用 Agent 提供的 PNG 版本更可靠。
可以修改端口号吗？
可以。启动时设置环境变量 PORT=8080 nohup node preview-server.js ...，或编辑 assets/preview-server.js 中的 START_PORT。
怎么停止服务器？
读取 server.pid 文件获取 PID，然后 kill <PID>。服务器会优雅关闭 WebSocket 连接并清理 PID 文件。
页面需要调后端 API 怎么办？
启动服务器时设置 PROXY_TARGET 环境变量，如 PROXY_TARGET=http://localhost:8080，所有 /api/* 请求会自动转发到后端。支持自定义前缀：PROXY_PREFIX=/v2。
支持 HTTPS 吗？ 当前版本仅支持 HTTP。对于需要 HTTPS 的 PWA 测试，建议使用 ngrok 或 Cloudflare Tunnel 等工具。
欢迎提 Issue 和 PR。以下是一些改进方向：
- 支持 HTTPS，用于 PWA 和 Service Worker 测试
- 支持同时预览多个页面
- 支持自定义端口配置（无需手动编辑代码）
- 支持远程访问（通过 ngrok 等集成）
- 添加页面性能分析工具（Lighthouse 等）
MIT © 2026 WildeMatt