SmartEye测试平台（smarteye-case）

App 视觉还原测试用例管理平台：从 Figma 生成用例，测试人员上传 iOS / Android 截图，自动与设计稿做视觉对比，一键生成给 AI 的修改建议。

要在其他项目中使用，直接让 AI 阅读本 README 并按「在其他项目中接入」执行。

• 用例管理：按模块管理，一个 Figma 手机屏对应一条用例；步骤、检查点、前置条件、Mock、接口、PRD 引用可编辑；支持 JSON / CSV 导入导出，提供「AI 补全用例」提示词
• Figma 增量同步：按节点内容指纹比对，新增页面自动建用例并按功能归类模块，变化的页面覆盖设计稿并重新对比，未变化的跳过；单条用例也可以按节点链接更新设计稿
• AI 生成用例内容：附带 Claude Code skill smarteye-cases，根据 Figma 范围 + PRD + 客户端代码生成每个页面的标题、步骤、检查点等，Figma 同步时一起导入
• 截图与验证：iOS / Android 分别上传、替换、删除截图；状态（未验证 / 通过 / 不通过 / 阻塞 / 未实现 / 不适用）手动判定，支持批量操作和快捷键
• 视觉对比：自动裁剪状态栏、遮罩调试浮窗，pixelmatch 像素对比；识别整页主题错误、整块偏移、元素偏移、缺少 / 多余元素、颜色差异；并排 / 滑块 / 叠加三种查看方式
• AI 修改建议：单条或按模块 / 全部批量复制，包含 Figma 节点（链接、Dev Mode、MCP 调用参数）、图片相对路径、差异区域坐标、人工备注、检查点、逻辑说明文档，以及根据项目配置生成的批量修复前置提示词
• 本地运行：Node 内置 SQLite，数据存放在项目目录中，可随项目提交共享

在其他项目中接入（AI 可直接按本节执行）

给 AI 的说明：用户让你「在这个项目里接入 SmartEye测试平台 / smarteye-case」时，按下面步骤在目标项目根目录执行。每一步都有完成标准；遇到「需要用户操作」的步骤要停下来告诉用户，不要代替用户输入密码、Token 或完成登录。所有写进配置、数据库和提示词的路径都用相对项目根目录的路径，不要出现本机绝对路径。

步骤 0：检查环境

node -v                          # 需要 ≥ 22.13，推荐 24
npm config get registry          # 查看当前 npm 源
git rev-parse --show-toplevel    # 确认在项目根目录（建议是 git 仓库）

• Node 版本不够：提示用户升级（如 nvm install 24 && nvm use 24 或 fnm use 24），升级前不要继续。
• 项目根目录没有 package.json：先执行 npm init -y（仅作为安装开发依赖的载体，不影响原项目）。
• npm 源是国内镜像（如 registry.npmmirror.com）且安装不到最新版本时，安装命令加 --registry=https://registry.npmjs.org/。

完成标准：Node ≥ 22.13，当前目录是要接入的项目根目录。

步骤 1：安装

npm install -D smarteye-case

如果使用了镜像源，安装后可把 package-lock.json 中 registry.npmmirror.com 的下载地址替换为 registry.npmjs.org，方便海外同事安装（包内容相同，integrity 不变）。

完成标准：npx smarteye --version 输出版本号。

步骤 2：初始化

npx smarteye init --name "<项目名>"

会自动完成：

| 动作 | 结果 | |---|---| | 生成配置 | 项目根目录 smarteye.config.json（模板，需在步骤 3 补全） | | 补充 .gitignore | .env（存 Figma Token）、smarteye/.smarteye.pid | | 补充 npm scripts | npm run start-smarteye、npm run stop-smarteye（已存在同名脚本时不覆盖） | | 安装 AI skill | .claude/skills/smarteye-cases/（Claude Code 自动识别） |

已存在配置时加 --force 才会覆盖；只更新 skill 用 npx smarteye skill --force。

完成标准：以上 4 项都已生成；.gitignore 中包含 .env。

步骤 3：补全 smarteye.config.json（AI 需要阅读项目后填写）

模板里的值都是示例，必须根据项目实际情况修改。字段完整说明见 docs/config.md，JSON Schema 见 docs/config-schema.json。

| 字段 | 怎么确定 | |---|---| | name | 项目 / App 名称，显示在平台标题和 AI 提示词中 | | port | 默认 5178；与项目其他本地服务冲突时改掉 | | dataDir | 默认 smarteye，一般不改 | | envFile | 默认 .env；项目已有 .env 且被其他工具使用也没关系（只读写 FIGMA_TOKEN= 这一行），但必须在 .gitignore 中 | | platforms.ios.codeDir | iOS 工程所在目录：查找 *.xcodeproj / *.xcworkspace / Package.swift 所在的目录，如 ios/、MyApp-iOS/ | | platforms.ios.stack | 看源码与依赖判断：Swift / Objective-C，SwiftUI / UIKit，CocoaPods / SPM；写出打开的 workspace 和 scheme（xcodebuild -list 可查） | | platforms.ios.designSystem | 搜索颜色、字体、间距的集中定义：Theme、Colors、DesignSystem、Assets.xcassets、Fonts/ | | platforms.ios.build | 可在项目根目录执行的构建验证命令，如 xcodebuild -workspace ios/App.xcworkspace -scheme App -configuration Debug -destination 'generic/platform=iOS Simulator' build | | platforms.ios.guide | 工程约定文档：AGENTS.md / CLAUDE.md / CONTRIBUTING.md，没有就删掉该字段 | | platforms.android.* | 同上：codeDir 为含 settings.gradle(.kts) 的目录；stack 如 Kotlin + Jetpack Compose / XML View；designSystem 搜索 Theme.kt、colors.xml、designsystem；build 如 cd android && ./gradlew :app:assembleDebug | | 只有一个平台 | 另一个平台的 platforms.* 可以删除或留空；平台界面仍显示 iOS / Android 两栏，不用的一栏标记「不适用」即可 | | docs | PRD、接口文档所在位置（相对路径），如 docs/prd/、api/openapi.yaml；没有就写 [] | | modules | 模块规则，顺序即平台侧边栏顺序。优先参照 Figma 的 section / page 划分和 PRD 功能模块。每条：module 模块名、prefix 用例ID前缀（大写字母或数字，如 AUTH）、keywords 关键词。归类规则：取 Figma 画板名第一个「-」之前的功能名，按最长关键词匹配；因此关键词应写画板命名里常用的功能名（如画板叫「登录-输入邮箱」「登录设备管理-加载中」，就分别给「登录」「登录设备管理」配规则） | | compare.cropTop / cropBottom | 忽略顶部状态栏和底部 Home Indicator 的高度（设计稿按 750 宽计算，px），默认 88 / 60 通常可用 | | compare.masks | 截图中与设计稿无关、需要忽略的区域（如 Debug 包的悬浮调试按钮）。坐标按 750 宽设计稿计算：{ "x": 610, "y": 580, "w": 140, "h": 180, "label": "调试浮窗" }。不确定时先留空，上传截图后在差异图上看位置再补 | | ai.context | 补充给 AI 的项目上下文，每项一行，如「app-prototype/：交互原型，只读」 | | ai.rules | AI 修改代码时必须遵守的额外规则，如「不要修改 vendor/ 下的文件」 |

示例（iOS 与 Android 双端项目）：

{
  "$schema": "./node_modules/smarteye-case/docs/config-schema.json",
  "name": "Demo App",
  "port": 5178,
  "dataDir": "smarteye",
  "envFile": ".env",
  "platforms": {
    "ios": {
      "label": "iOS",
      "codeDir": "ios/",
      "stack": "Swift + SwiftUI，SPM，打开 `ios/Demo.xcodeproj`，scheme `Demo`",
      "designSystem": "`ios/Demo/DesignSystem/Colors.swift`、`Typography.swift`",
      "build": "xcodebuild -project ios/Demo.xcodeproj -scheme Demo -configuration Debug -destination 'generic/platform=iOS Simulator' build",
      "guide": "ios/AGENTS.md"
    },
    "android": {
      "label": "Android",
      "codeDir": "android/",
      "stack": "Kotlin + Jetpack Compose，Gradle",
      "designSystem": "`android/app/src/main/java/com/demo/ui/theme/Theme.kt`",
      "build": "cd android && ./gradlew :app:assembleDebug",
      "guide": "android/AGENTS.md"
    }
  },
  "docs": ["docs/prd/"],
  "modules": [
    { "module": "登录注册", "prefix": "AUTH", "keywords": ["登录", "注册", "忘记密码", "验证码"] },
    { "module": "首页", "prefix": "HOME", "keywords": ["首页"] },
    { "module": "个人中心", "prefix": "PROF", "keywords": ["个人中心", "个人信息", "设置"] }
  ],
  "compare": { "cropTop": 88, "cropBottom": 60, "threshold": 0.1, "masks": { "ios": [], "android": [] } },
  "ai": { "context": [], "rules": [] }
}

完成标准：配置是合法 JSON；platforms.*.codeDir、docs、guide 中的路径在项目中真实存在；modules 覆盖了本次要测试的功能模块。

步骤 4：启动并检查

npm run start-smarteye          # 或 npx smarteye start；--port 指定端口，--no-open 不打开浏览器
npx smarteye status             # 查看运行状态

启动日志会显示项目名、配置文件和数据目录。首次启动会自动创建 smarteye/（smarteye.db、assets/、.gitignore）。

完成标准：浏览器打开 http://localhost:<port>，左上角显示「SmartEye测试平台」和项目名。

步骤 5：配置 Figma Token（需要用户操作）

告诉用户：

1. 在 Figma → 头像 → Settings → Security → Personal access tokens 生成 Token，权限勾选 File content（Read）。
2. 在平台「设置 → Figma Token」粘贴并点「校验并保存」（会写入 .env 的 FIGMA_TOKEN=）。

也可以由用户手动在 .env 中写 FIGMA_TOKEN=... 后重启平台。不要让用户把 Token 发给你，也不要把 Token 写进配置文件或提交到仓库。

完成标准：平台「设置 → Figma Token」显示「已配置」。

步骤 6：生成第一批用例

需要用户提供：Figma 范围链接（带 node-id，选中 section / page 后复制链接）、相关 PRD 路径（可选）。

1. 生成用例内容（在 Claude Code 中，项目根目录）： 用 smarteye-cases，根据 <Figma 链接> 和 <PRD 路径> 生成用例 产出 smarteye/drafts/<名称>.cases.json 与 <名称>.review.md，详见下文「用 AI 生成用例内容」。
2. 检查模块规则：review.md 或同步结果里出现未配置的模块时，先在 smarteye.config.json 的 modules（或平台「设置 → 模块规则」）补上，否则用例ID前缀为 CASE。
3. 导入平台：「从 Figma 生成 / 更新」→ 粘贴同一个 Figma 链接 →「用例内容文件」选择 .cases.json → 开始同步。

不使用 skill 时直接执行第 3 步（不选内容文件），生成的是模板用例，之后可以在「导入 / 导出 → 复制 AI 补全用例提示词」补全。

完成标准：平台左侧出现对应模块，用例数量与 Figma 手机屏数量一致，用例详情中有步骤和检查点。

步骤 7：提交到仓库

| 提交 | 不提交 | |---|---| | smarteye.config.json | .env（Figma Token） | | smarteye/smarteye.db、smarteye/assets/、smarteye/docs/ | smarteye/.smarteye.pid | | smarteye/drafts/*.cases.json、*.review.md | smarteye/drafts/*/（skill 导出的临时设计稿） | | .claude/skills/smarteye-cases/、package.json、package-lock.json | node_modules/ |

以上忽略规则由 smarteye init 和平台自动写入 .gitignore / smarteye/.gitignore。截图较多时仓库体积会增长，如不希望提交截图，可在 .gitignore 中加 smarteye/assets/screenshots/、smarteye/assets/diff/。

其他成员拉取代码后：npm install → npm run start-smarteye → 在平台配置自己的 Figma Token（只有从 Figma 同步用例时需要）。

日常使用

| 场景 | 操作 | |---|---| | 新增功能 / 新的 Figma 页面 | 重复步骤 6（新模块先加 modules 规则） | | Figma 设计稿修改 | 「从 Figma 生成 / 更新」粘贴同一范围链接；新页面建用例，变化的页面更新设计稿并重新对比已上传截图，原「通过」重置为「未验证」 | | 只更新某一页设计稿 | 用例详情 → 设计稿下方「更新设计稿」 | | 验收 | 用例详情按平台上传截图（拖拽 / ⌘V / 上传）→ 查看对比 → 标记状态 | | 让 AI 修复视觉问题 | 单条「复制 AI 修改建议」，或模块页顶部「复制本模块 AI 修改建议」，粘贴给 AI | | 升级平台 | npm install -D smarteye-case@latest（镜像未同步时加 --registry=https://registry.npmjs.org/），然后 npx smarteye skill --force 更新 skill，重启平台 | | 停止平台 | npm run stop-smarteye |

常见问题

| 问题 | 处理 | |---|---| | 需要 Node.js ≥ 22.13 | 升级 Node（推荐 24） | | 未找到配置文件 | 在项目根目录执行，或 --config <路径> 指定；没有配置先 npx smarteye init | | 端口 xxx 已被占用 | npx smarteye stop；仍被其他程序占用时改配置 port 或 --port | | 安装时报 notarget / 找不到版本 | 镜像源未同步，加 --registry=https://registry.npmjs.org/ | | Figma 同步报 Token 无效 / 403 | 重新生成 Token 并在「设置 → Figma Token」保存；确认 Token 所属账号有该文件的访问权限 | | 用例ID前缀是 CASE | 该模块没有匹配的 modules 规则；补规则后可在「设置 → 模块规则 → 保存并重新归类全部用例」（只改模块，不改已生成的用例ID） | | Figma 某些画板没有生成用例 | 只识别竖屏手机尺寸画板（宽 320~430 / 640~860 / 1080~1290，高 ≥ 宽 × 1.6），名称以「说明 / 注释 / 备注」开头的会被忽略 | | 截图对比差异很大 | 检查截图机型比例是否与设计稿一致（如 375×812pt）；确认 App 主题（深浅色）；在「设置 → 对比设置」调整裁剪高度和遮罩 | | 修改了配置中的 modules / compare 没生效 | 平台「设置」里保存过的规则优先于配置文件；在平台设置中修改，或删除数据库中对应设置后重启 |

安装

需要 Node.js ≥ 22.13（推荐 24）。

npm install -D smarteye-case
npx smarteye init        # 生成 smarteye.config.json，补充 .gitignore 与 npm scripts，安装 AI skill

编辑 smarteye.config.json，填写项目名、iOS / Android 代码目录与构建命令、设计系统位置、模块规则等，字段说明见 docs/config.md。

使用

npx smarteye start       # 启动并打开 http://localhost:5178（或 npm run start-smarteye）
npx smarteye stop        # 停止（或 npm run stop-smarteye）
npx smarteye status      # 查看运行状态

| 参数 | 说明 | |---|---| | --port, -p | 指定端口（默认读取配置文件 port，再默认 5178） | | --config, -c | 指定配置文件路径（默认从当前目录向上查找） | | --no-open | 启动时不自动打开浏览器（也可设置 SMARTEYE_NO_OPEN=1） |

首次使用：

1. 「设置 → Figma Token」配置 Token（保存到项目 .env，不会提交）。
2. （推荐）用 skill 生成用例内容，见下文「用 AI 生成用例内容」。
3. 「从 Figma 生成 / 更新」粘贴带 node-id 的 Figma 链接（选中 section 或页面后复制链接），在「用例内容文件」选择上一步生成的 .cases.json，可同时填写本地 PRD 等 Markdown 作为逻辑说明文档。
4. 打开用例，按平台上传截图 → 查看对比 → 判定状态 → 「复制 AI 修改建议」交给 AI 修复。

不使用 skill 时，Figma 生成的用例是模板骨架，可在「导入 / 导出 → 复制 AI 补全用例提示词」交给 AI 补全，或手动编辑。

用 AI 生成用例内容（Claude Code skill）

smarteye init 会把 skill 安装到项目的 .claude/skills/smarteye-cases/（单独安装或更新：npx smarteye skill [--force]）。在项目根目录打开 Claude Code：

用 smarteye-cases，根据 https://www.figma.com/design/<key>/...?node-id=5-5 和 docs/prd/登录注册.md 生成用例

skill 会：

1. 读取 smarteye.config.json（平台代码目录、模块规则、文档位置）。
2. 用 scripts/figma-frames.mjs 列出范围内的手机屏并导出设计稿（识别规则与平台一致，保证 node_id 对得上；需要 Figma Token）。
3. 逐张看设计稿，结合 PRD、接口文档和客户端代码，为每个手机屏写一条用例：标题、优先级、前置条件、Mock、测试数据、编号操作步骤、检查点（① 视觉 ② 功能 ③ 接口）、接口、PRD 引用、iOS / Android 客户端页面与差异。画板多时按 section 交给子 agent 并行。
4. 校验数量与 node_id，输出 smarteye/drafts/<name>.cases.json 和待确认问题 smarteye/drafts/<name>.review.md。

然后在平台「从 Figma 生成 / 更新」中粘贴同一个 Figma 链接并选择 .cases.json：

| 选项 | 行为 | |---|---| | 只填充新建用例和仍是模板的用例（默认） | 新页面直接生成完整用例；已编写过的用例不被覆盖（结果中列出） | | 覆盖已编写的用例内容 | 内容文件中的字段覆盖已有用例（用例ID、模块、Figma 信息不变） |

内容文件中找不到对应页面的 node_id 会在同步结果中列出。已同步过 Figma 的项目，也可以在「导入 / 导出」中直接导入 .cases.json（按 node_id 更新）。

数据与提交

<项目根目录>/
├─ smarteye.config.json    配置（提交）
├─ .env                    FIGMA_TOKEN（不提交）
└─ smarteye/               数据目录（建议提交，团队共享用例和验证结果）
   ├─ smarteye.db          SQLite 数据库
   ├─ assets/figma/        设计稿
   ├─ assets/screenshots/  上传的截图
   ├─ assets/diff/         差异图
   ├─ docs/                从项目外导入的逻辑说明文档
   └─ drafts/              skill 生成的用例内容文件（*.cases.json、*.review.md；导出的临时设计稿不提交）

数据库和 AI 提示词中只保存相对项目根目录的路径，不包含本机绝对路径。截图会让仓库体积逐渐增大，如不希望提交截图，可把 smarteye/assets/screenshots/、smarteye/assets/diff/ 加入 .gitignore。

用例数据格式

导入接口 POST /api/cases/import 与界面导入使用同一格式，见 docs/case-schema.json。

开发

git clone https://github.com/zivyangll/SmartEyeCase.git && cd SmartEyeCase
npm install
npm run dev              # API（示例配置 example/smarteye.config.json）+ Vite 前端热更新 http://localhost:5179
npm run build            # 构建前端到 dist/（npm pack / publish 时自动执行）

目录：bin/ CLI、server/ API 与业务逻辑（Express、node:sqlite、sharp + pixelmatch、Figma API、提示词）、web/ React 前端、skills/ Claude Code skill、templates/ init 模板、docs/ 配置与数据格式说明。

发布流程见 PUBLISHING.md。

参考

数据模型与验证状态参考 Kiwi TCMS，视觉对比与审核交互参考 Argos、reg-suit、BackstopJS。

License

MIT