UI-zoucha-feishu (v1.0)

中文 UI 走查 Skill：对比 Figma 与前端页面，生成结构化走查报告，并自动发布到飞书文档（支持用户身份创建、表格对照、截图嵌入）。

功能概览

• 中文结构化走查输出
• 设计稿信息与前端信息并排对照表（属性级）
• 一键创建飞书文档并回填链接
• 支持自动截图并嵌入飞书文档
• 支持用户 token 自动刷新（长期使用）

目录说明

• SKILL.md：Skill 主说明（给模型执行用）
• agents/openai.yaml：Agent 展示信息
• scripts/：脚本工具
• references/：报告 schema / 模板 / 发布说明
• adapters/：多编辑器适配文件（Cursor / Claude / VS Code / Codex）
• reports/：本地生成的报告与截图（默认不进 Git）

多编辑器适配

本项目不是“仅限 Codex”，而是“脚本统一、指令分发到各编辑器”的方案。

| 编辑器 | 适配方式 | 对应文件 | |---|---|---| | Codex | 原生 Skill | SKILL.md | | Cursor | Rules 文件 | adapters/cursor/ui-zoucha-feishu.mdc | | Claude | 项目指令文件 | adapters/claude/CLAUDE.md | | VS Code | Copilot 项目指令 | adapters/vscode/copilot-instructions.md | | Windsurf | Rules 文件 | adapters/windsurf/ui-zoucha-feishu.md |

通用调用模板：adapters/common/invoke-prompt-template.md

一键安装（主流编辑器）

在目标项目执行（或带 --project 指定路径）：

npx -y design-fidelity-checker-skills --project "/path/to/your-project" --editors all

默认会安装：

• Cursor
• Claude
• VS Code (Copilot)
• Windsurf
• Codex（安装到 CODEX_HOME/skills/ui-zoucha-feishu）

可选仅安装部分：

npx -y design-fidelity-checker-skills install --project "/path/to/your-project" --editors cursor,claude,vscode

卸载：

npx -y design-fidelity-checker-skills uninstall --project "/path/to/your-project" --editors all

如果你在本仓库本地调试（不经过 npx），可继续使用：

node scripts/install_skill.mjs --project "/path/to/your-project" --editors all
node scripts/uninstall_skill.mjs --project "/path/to/your-project" --editors all

开源发布安全边界（必须遵守）

可上传：

• SKILL.md
• agents/openai.yaml
• scripts/*.mjs
• references/*
• adapters/*
• .env.example
• .gitignore
• README.md
• SECURITY.md
• RELEASE_CHECKLIST.md

不要上传：

• .env（任何密钥、token）
• reports/（可能包含内网地址、账号信息、业务截图）
• .claude/（本地工具状态）
• 带真实 app_id/app_secret/token 的日志、截图、文档链接

环境要求

• Node.js >= 18（需内置 fetch）
• 飞书自建应用（个人版/企业版均可，但权限范围不同）

1. 配置环境变量

复制示例文件：

cp .env.example .env

按需填写：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_USER_ACCESS_TOKEN=u-xxx
FEISHU_USER_REFRESH_TOKEN=ur-xxx
FEISHU_AUTO_REFRESH_USER_TOKEN=1
FEISHU_FOLDER_TOKEN=fldcnxxx

说明：

• 推荐 FEISHU_USER_ACCESS_TOKEN：文档所有者是当前用户，可直接编辑
• 推荐 FEISHU_USER_REFRESH_TOKEN：发布前自动刷新 token，减少手工授权
• FEISHU_FOLDER_TOKEN 可选：指定文档落盘目录

2. 飞书权限（建议一次配齐）

用户身份权限建议至少包含：

• docx:document
• docx:document:create
• docx:document.block:convert
• docs:document.media:upload（截图嵌入需要）
• offline_access（长期刷新 token 需要）

每次新增权限后：

1. 发布应用新版本
2. 重新授权拿新 code
3. 用 code 兑换 token

3. 获取用户 token

3.1 生成授权链接

node scripts/get_feishu_user_token.mjs --redirect-uri "http://127.0.0.1:8787/callback"

3.2 浏览器授权后拿 code

回调 URL 示例：

http://127.0.0.1:8787/callback?code=xxxx&state=ui-zoucha

3.3 用 code 换 token

node scripts/get_feishu_user_token.mjs --code "xxxx"

把返回的 user_access_token、refresh_token 写入 .env。

4. 刷新 token（长期使用）

手动刷新并回写 .env：

node scripts/refresh_feishu_user_token.mjs

仅查看刷新结果，不回写：

node scripts/refresh_feishu_user_token.mjs --no-write-env

5. 生成报告

仅生成模板：

node scripts/create_report_template.mjs --page "页面名"

一步生成并发布：

node scripts/create_and_publish_report.mjs \
  --page "页面名" \
  --figma "https://www.figma.com/..." \
  --url "http://localhost:3000/demo"

6. 发布到飞书

node scripts/publish_feishu_walkthrough.mjs \
  --input references/report-example.json \
  --title "UI走查 - 示例" \
  --writeback

常用参数：

• --title：覆盖文档标题
• --folder-token：覆盖环境变量目录
• --no-images：不上传截图
• --no-writeback：不回写 JSON

成功输出示例（关键字段）：

• url
• auth_mode（应为 user_access_token）
• screenshots_embedded
• screenshots_failed

7. 发布前自检（建议）

1. 确认 .env 没被提交
2. 确认 reports/ 没被提交
3. 全仓搜索是否含 u- / ur- / app_secret / 内网地址
4. 用最小报告跑一遍发布流程
5. 确认 auth_mode=user_access_token

许可证建议

建议开源时添加 LICENSE（如 MIT），并在 SECURITY.md 说明漏洞上报方式。