如何运行 UI UX Pro Max 的离线数据验证门禁 verify:data？-平芜编程栈

如何运行 UI UX Pro Max 的离线数据验证门禁 verify:data？

【免费下载链接】ui-ux-pro-max-skillAn AI skill that provides design intelligence for building professional UI/UX across multiple platforms.项目地址: https://gitcode.com/gh_mirrors/ui/ui-ux-pro-max-skill

UI UX Pro Max（ui-ux-pro-max-skill）的数据集中在src/ui-ux-pro-max/data/下，由verify:data这条 npm 脚本统一校验。当你修改了 CSV 数据、搜索脚本、平台模板或cli/assets/中的镜像副本之后，需要跑一遍这条门禁，确认数据结构、文档声明与镜像同步都没有被改坏。整个门禁不访问网络：README 明确说明普通开发和 CI 是 network-independent，verify:data是其中完整的离线门禁。本文给出它的运行方式、每个子门禁检查什么，以及输出如何判读。

准备条件

在仓库根目录（README.md、cli/、src/、scripts/所在的目录）下操作，并确认：

Python 3.x：README 的 Prerequisites 一节写明 Python 3.x 是搜索脚本的运行要求，且脚本只使用标准库——不安装任何依赖、不发起网络请求。可用python3 --version检查。
Node 与 npm：门禁本身是一串 npm script 串联。各validate:*/test:python/evaluate:relevance步骤通过 run-python.mjs 启动 Python：它按平台选择解释器（Windows 用python，其他平台用python3）并透传退出码。
bash：两个 smoke 脚本是 bash 脚本，通过bash scripts/smoke-*.sh执行。

不需要npm install即可完成门禁（check:assets子门禁明确标注 no npm install required）。

verify:data 串联了哪些子门禁

cli/package.json 中的定义：

"verify:data": "npm run validate:csv && npm run validate:semantic && npm run validate:agent-guide && npm run validate:catalog-summary && npm run test:python && npm run evaluate:relevance && npm run smoke:domains && npm run smoke:stacks && npm run check:assets"

9 个子步骤按顺序执行，任一失败（退出码非 0）即中止后续步骤。各步骤实际执行的命令与职责：

子门禁	实际执行	检查内容
`validate:csv`	`python3 scripts/validate-csv.py`	遍历`src/ui-ux-pro-max/data/`下全部 CSV：空文件、缺失/空白/重复表头、字段数不匹配的行、数据集中的空行
`validate:semantic`	`python3 src/ui-ux-pro-max/scripts/validate_data.py`	数据语义校验
`validate:agent-guide`	`python3 scripts/validate-agent-guide.py`	校验 agent 指南文档声明与实际数据一致，并跑 3 组锁定的语义搜索示例
`validate:catalog-summary`	`python3 scripts/generate-catalog-summary.py --check`	检查 catalog-summary.json（生成数量统计 + 文件快照哈希）是否与当前数据一致，并核对 README 中的数据计数
`test:python`	`python3 -m unittest discover -s src/ui-ux-pro-max/scripts/tests -p 'test_*.py'`	运行`src/ui-ux-pro-max/scripts/tests/`下全部`test_*.py`单元测试
`evaluate:relevance`	`python3 scripts/evaluate-relevance.py`	对已发货的搜索数据做确定性相关度评估，对照提交在仓库中的阈值判定
`smoke:domains`	`bash scripts/smoke-domains.sh`	对注册表中的每个非 stack 搜索域执行一次聚焦查询，要求每个域至少返回 1 条结果
`smoke:stacks`	`bash scripts/smoke-stacks.sh`	对`STACK_CONFIG`注册的每个 stack 执行聚焦查询，要求每个 stack 至少返回 1 条结果
`check:assets`	`node cli/scripts/sync-assets.mjs --check`	校验`cli/assets/`与`.claude/skills/ui-ux-pro-max/{data,scripts}`是否与`src/ui-ux-pro-max/`同步（只校验，不写文件）

两个需要知道的细节：

validate-agent-guide.py 除了比对行数声明外，还会实际调用search.py --json跑 3 组固定示例（design-system、--domain ux、--stack react-native）并断言返回了预期路由的结果，因此它对数据文件是有读取依赖的。
所有validate:*步骤在 package.json 中都是cd .. && node cli/scripts/run-python.mjs ...，即先回到仓库根目录再执行——所以必须在仓库根目录运行npm --prefix cli run verify:data，否则脚本定位不到scripts/与src/。

运行完整门禁

在仓库根目录执行 README「Catalog provenance and refresh」一节给出的命令：

npm --prefix cli run verify:data

--prefix cli让 npm 把 cli/package.json 当作项目根，从而运行其中的 script。等价写法是先进入cli/再执行：

npm run verify:data

（见 README.md「For Contributors」第 4 步的本地验证序列：npm run sync:assets→npm run check:assets→npm run verify:data→npm run typecheck。）

只跑单个子门禁

verify:data是串联入口，9 个子步骤都可以单独运行，方便定位失败发生在哪一段：

npm --prefix cli run validate:csv # CSV 结构校验 npm --prefix cli run validate:semantic # 语义校验 npm --prefix cli run validate:agent-guide # agent 指南声明与锁定示例 npm --prefix cli run validate:catalog-summary # 仅检查生成的 catalog summary npm --prefix cli run test:python # Python 单元测试 npm --prefix cli run evaluate:relevance # 相关度评估 npm --prefix cli run smoke:domains # 搜索域 smoke npm --prefix cli run smoke:stacks # stack smoke npm --prefix cli run check:assets # 资产镜像同步校验

README 还单独提示：只想核对 catalog summary 时用npm --prefix cli run validate:catalog-summary。

如何判读结果

各子门禁通过时打印的信息来自脚本源码，可按以下特征判断：

validate-csv.py：通过打印CSV validation passed: {n} runtime CSV files checked.；失败时向 stderr 逐条列出问题（如expected {x} fields, got {y}），退出码 1；数据目录缺失时退出码 2。
generate-catalog-summary.py 的--check模式：通过打印Catalog summary is current.；summary 文件缺失、过期（重新生成的内容与已提交文件不一致）或 README 计数过期时以退出码 2 报错，提示regenerate it。
validate-agent-guide.py：通过打印Agent guide validation passed: 20 platforms and 3 locked examples checked.；失败时逐条打印差异，退出码 1。
smoke-domains.sh：逐域打印PASS/FAIL与返回条数，全部通过时最后一行是OK: {total}/{total} domains returned ≥1 result。
smoke-stacks.sh 头部注释明确了退出码约定：0全部 stack 返回 ≥1 结果；1至少一个 stack 返回 0 条；2环境问题（search.py缺失、注册表数量不符）。

smoke 脚本还内置了数量锁，供注册表有意变更后使用：smoke-domains.sh 默认期望 12 个域（可用环境变量EXPECTED_DOMAIN_COUNT调整），smoke-stacks.sh 默认期望 22 个 stack（可用EXPECTED_STACK_COUNT调整）。只有当你有意增删了注册表条目时才需要显式设置这些变量，脚本注释也要求此时 deliberate 地 bump 数值，以便意外漂移仍然响亮地失败。日常运行不需要设置。

门禁失败时的定位顺序

由于 9 个步骤用&&串联，失败一定最先发生在链条前段：

若卡在validate:csv/validate:semantic，先修复数据文件本身（脚本输出会给出具体文件与行号）。
若数据没问题但validate:agent-guide或validate:catalog-summary报「声明不一致」「stale」，说明你改了数据但没有同步更新文档声明或重新生成 summary——按各自报错提示处理（catalog summary 的提示是 regenerate）。
若smoke:domains/smoke:stacks报某域或某 stack 返回 0 条，对应现象是注册表条目与其 CSV 不匹配（例如 CSV 被误清空），smoke-stacks 的注释把这类回归列为它的目标场景。
若只有check:assets失败，说明src/ui-ux-pro-max/的改动没有同步到镜像副本——按 CLAUDE.md 的 Sync Rules，先编辑src/再运行npm run sync:assets（在cli/下）即可重新生成镜像。

什么时候会运行它

package.json 中的发布钩子会把verify:data作为发布前置步骤之一：

"prepublishOnly": "npm run sync:assets && npm run verify:data && npm run typecheck && npm run build"

即发布ui-ux-pro-max-cli到 npm 之前会自动跑一遍同步 + 完整数据门禁 + 类型检查 + 构建。对贡献者而言，它是每次改动src/ui-ux-pro-max/data/、src/ui-ux-pro-max/scripts/或模板后提交 PR 前的本地验证手段，且全程离线可重复。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考