ui-ux-pro-max-skill 仓库中的三处 data / scripts / templates：src、cli/assets 与 .claude/skills 的区别与同步维护指南-创锋一号

ui-ux-pro-max-skill 仓库中的三处 data / scripts / templates：src、cli/assets 与 .claude/skills 的区别与同步维护指南

【免费下载链接】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-skill 仓库中，data（设计数据 CSV/JSON）、scripts（Python 工具脚本）和templates（Skill 模板）分别存在于三个不同的物理位置：src/ui-ux-pro-max/、cli/assets/和.claude/skills/ui-ux-pro-max/。三者用途截然不同，却常常让维护者困惑"到底该改哪一份、哪一份能删、为什么会漂移"。本文以 docs/三个>const sourceRoot = join(repoRoot, 'src', 'ui-ux-pro-max'); const assetRoot = join(repoRoot, 'cli', 'assets'); const dirsToSync = ['data', 'scripts', 'templates']; const checkOnly = process.argv.includes('--check');

src/ui-ux-pro-max/{data,scripts,templates}→cli/assets/（npm 打包用）；
.claude/skills/下的6 个子 Skill（banner-design、brand、design、design-system、slides、ui-styling）→cli/assets/skills/，这样uipro init安装的是全部7 个 Skill（1 个编排器 + 6 个子 Skill），而不是只有模板渲染出来的编排器；
src/ui-ux-pro-max/{data,scripts}→.claude/skills/ui-ux-pro-max/{data,scripts}（Claude Code 插件方式加载时实际读取的副本）。

第三块尤为重要：注释里写明"Nothing previously checked it against src/, so it silently drifted"——即.claude/skills/ui-ux-pro-max/这份副本此前从未被检查，曾静默漂移（缺少 stack CSV、多个数据文件内容过期）。这正是三处结构容易出问题的历史根源。

为什么不镜像 templates 到 .claude/skills

同样在注释里说明了原因（第 30～38 行）：.claude/skills/ui-ux-pro-max/SKILL.md是手工编写的，与 CLI 那份由模板渲染的 SKILL.md 不同，因此只有data/和scripts/被镜像，永远不镜像templates/或 SKILL.md 本身。这也解释了为什么.claude/skills/ui-ux-pro-max/目录下只有data、scripts、references而没有templates。

排除规则与行尾归一化

脚本对同步内容有两条精细规则：

排除重二进制资产（第 44～46 行）：canvas-fonts、__pycache__目录，以及ttf/otf/woff2/png/jpg/gif/ico/coverage/pyc等扩展名全部跳过——canvas 字体约 5.8MB，Skill 注册依赖 SKILL.md 而非字体文件，打包时排除可以避免 npm 包膨胀；
CRLF → LF 归一化（第 50 行）：所有同步的文本资产在写入与哈希前统一转为 LF，避免 Gitautocrlf跨平台检出造成字节哈希漂移。

哈希比对与孤儿文件清理

diffDir用 SHA-256（fileHash，先toLF再哈希）逐文件比对源与目标，把差异归为三类可读消息：extra asset file（目标多出来的文件）、missing asset file（缺失）、stale asset file（内容过期）。而syncDir在复制前会先删除整个目标目录再重建，这样源里删掉的文件不会在目标里留下孤儿残留。

安全边界

assertInsideRepo（第 61～67 行）会在写入前校验解析后的路径必须以repoRoot开头，防止脚本意外修改仓库之外的任何路径——这是对发布流水线的一项防御性保障。

check:assets 与 CI：漂移的守门员

check:assets不只是本地命令，它还由"Check asset sync"CI 工作流执行，见 .github/workflows/check-asset-sync.yml。该工作流：

在pull_request（涉及src/ui-ux-pro-max/**、cli/assets/**、.claude/skills/**、sync-assets.mjs、cli/package.json等路径）与push到 main 时触发；
在 Node 20 环境运行npm --prefix cli run check:assets，由于脚本只用 Node 内置模块，无需npm install，检查快速且稳定；
额外执行一项路径契约检查（对应 issue #474）：grep各 SKILL.md 中是否出现硬编码的~/.claude/skills/...用户级路径——这类路径只在一种安装上下文（用户级安装）下有效，在 marketplace/plugin 安装（Skill 位于插件缓存）或项目级 CLI 安装下会失效，因此 Skill 指令必须使用 Skill 相对路径。

在cli/package.json中还能看到发布前的完整校验链prepublishOnly：

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

而verify:data又串起了 CSV 校验、语义校验、Agent 指南校验、catalog-summary 校验、Python 单元测试、相关性评估、领域/技术栈冒烟测试以及check:assets。也就是说，同步校验被嵌入了完整的发布质量门禁，任何未同步的 src 修改都会被拦截在发布之前。

三处目录在安装链路上的落点

理解cli/assets/的"打包"含义，可以从 CLI 安装实现 cli/src/commands/init.ts 看出：

运行时通过ASSETS_CANDIDATES依次探测dist/assets与cli/assets，定位随包携带的资源目录（第 23～29 行）；
默认走模板生成路径：uipro init --ai <assistant>用 cli/src/utils/template.ts 按目标 AI 平台（claude/cursor/windsurf/copilot/kiro/codex/roocode/qoder/gemini/trae/opencode/universal 等，见 cli/README.md）渲染出对应的 Skill 文件，模板即来自src/ui-ux-pro-max/templates/同步到cli/assets/templates/的副本；
若指定--legacy，则先尝试从 GitHub Release 下载 ZIP（tryGitHubInstall），失败或--offline时回退到copyFolders(ASSETS_DIR, ...)，此时安装的正是cli/assets/里打包的 data/scripts/templates 与子 Skill（复制逻辑见 cli/src/utils/extract.ts 的copyFolders）。

这解释了原文档表格中"用户执行npm i -g ui-ux-pro-max-cli再uipro init时，安装的是这里打包的 data/scripts/templates 和子 Skill"这句话的完整链路：src → sync 脚本 → cli/assets → npm 包 → uipro init 分发。同样地，当本仓库以 Claude Code 插件方式安装时，.claude/skills/ui-ux-pro-max/中的data/scripts副本就是 Claude Code 实际读取的内容，SKILL.md 里也明确要求通过${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py这样的 Skill 相对路径调用搜索脚本（见 .claude/skills/ui-ux-pro-max/SKILL.md 的 "Running the search tool" 一节）。

常见误区与规避要点

误区一：只改 cli/assets 以为能影响 npm 包。cli/assets/是同步产物，直接修改会在下一次sync:assets或 CI 的check:assets中被判定为漂移（stale asset file/extra asset file）并失败。
误区二：把 .claude/skills/ui-ux-pro-max/{data,scripts} 当独立维护区。它是 Claude Code 实际加载的副本，但必须由 src 同步而来，否则会重蹈"静默漂移"覆辙。
误区三：给副本做符号链接。Windows Git 检出下符号链接失效，脚本的"删除重建"策略也天然不兼容链接。
误区四：改了 SKILL.md 却期待它被同步。.claude/skills/ui-ux-pro-max/SKILL.md手工维护，不参与同步；CLI 侧由模板渲染生成的 SKILL.md 则来自 templates，两者不可混为一谈。

总结

三处 data/scripts/templates 的本质是"一份真相源 + 两个按用途生成的镜像"：src/ui-ux-pro-max/是唯一手工维护的源码，cli/assets/服务于 npm 分发，.claude/skills/ui-ux-pro-max/服务于 Claude Code 插件加载。维护者只需遵守"只在 src 改、提交前跑sync:assets+check:assets"这一条纪律，再借助 CI 中的资产同步检查与路径契约检查做兜底，即可长期保持三处目录一致、可追溯、可发布。

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

企业官网建设流程全解析