Neo 主题换肤支持情况分析 Skill 安装与使用

Beta 状态

本「Neo 主题换肤支持情况分析 Skill」目前处于 Beta 阶段，功能和使用方式仍在持续打磨中。试用过程中发现任何问题，或有改进建议，欢迎随时反馈到 neo-cmp-docs Issues。

什么是 Neo 主题换肤支持情况分析 Skill

一套 AI 辅助的只读分析工具，帮助你在动手改造之前，先摸清 Neo 平台历史项目的主题换肤「家底」。AI 会扫描项目源码，盘点哪些页面 / 组件已经支持换肤（已使用 Neo 主题 CSS 变量），以及哪些还残留硬编码品牌色，并结合每个组件的功能、类型与项目内使用位置，产出一份《当前项目主题换肤支持情况.md》分析报告。

它回答两个核心问题：

1. 哪些页面 / 组件已经支持换肤，分别用到了哪些 Neo 主题 CSS 变量。
2. 哪些页面 / 组件尚存硬编码色值，分别残留了哪些硬编码品牌色。

只读分析，不改源码

本 Skill 全程只读，绝不修改任何源码，唯一产物是一份 md 分析报告。规则完全内置（CSS 变量清单 + 色值匹配规则 + 忽略规则），不依赖任何其他技能。如果你要真正改造项目（把硬编码色值替换为 CSS 变量），请使用「Neo 主题换肤 Skill」。

核心能力：

• 🔍 已支持换肤盘点：扫描项目中所有 Neo 主题 CSS 变量（var(--xxx) / rgba(var(--xxx-rgb), a) / getCssVarHex('--xxx')）引用，按组件汇总用到的变量分类（品牌色 / 按钮色 / 边框色 / 背景色 / 图标色 / 文本色 / 导航色）与去重后的具体变量列表
• 🎯 蓝色硬编码盘点：按内置识别规则找出仍在使用硬编码品牌蓝的组件——完全匹配 48 组（主品牌色 33 组 + 次品牌色 15 组）+ 仅以 #0564f5 为基准的 1-2 色阶近似匹配，标注残留色值、匹配类型与建议目标变量
• 🎨 浅蓝背景色盘点：识别 background / background-color（JSX 为 backgroundColor）上的 11 组浅蓝硬编码色值，建议目标变量 var(--brand-color-tint)；非背景属性上的浅蓝不计入残留
• 🔘 Primary 按钮语义识别：button-primary / ant-btn-primary / btn-primary / a-Button--primary / btn-conform / add_button / confirm_button / cancel_button 均按 Primary 按钮语义分析，优先给出 --color-button-filled-primary* 系列建议变量
• 🧩 组件元数据分析：为每个命中的组件读取实现入口，总结 50 字内功能说明，判定组件类型（NeoRegister 注册 → amis 组件；XRegister.CmpDefine 注册 → Neo 2.0 组件；否则未知），并按 type / cmpType 在项目内精确检索使用位置
• 📊 生成分析报告：在项目根目录输出《当前项目主题换肤支持情况.md》，报告头标注项目名称、仓库地址、所在分支，正文以组件为最小粒度逐行输出已支持 / 尚存硬编码两张明细表

与「主题换肤升级 Skill」的区别

对比项	主题换肤支持情况分析 Skill（本文）	主题换肤（升级）Skill
目的	只读盘点现状，摸清家底	实际改造，替换为 CSS 变量
是否改源码	❌ 全程只读	✅ 会修改源码
产物	《当前项目主题换肤支持情况.md》分析报告	改造后的源码 + 《Neo主题换肤功能升级报告.md》
典型使用时机	改造前评估、验收后复盘	需要让项目支持换肤时

建议流程：先用本分析 Skill 摸清现状 → 再用升级 Skill 做改造 → 最后再跑一次本分析 Skill 验收复盘。

环境准备

依赖	说明
AI 编辑器	CodeBuddy、Kiro、Cursor 等支持 Skills 的 AI 编辑器
项目	待分析的 Neo 平台项目（本地已 clone，且能访问 git）
Node.js	用于运行内置扫描脚本 neoThemeAnalyzer.js 做一次性数据采集（无 Node 环境时可退化为手动 grep 扫描）

本 Skill 直接在 AI 编辑器中运行，通过对源码的扫描与阅读完成分析。内置的扫描脚本仅做只读扫描，不会改动仓库。

安装

手动安装步骤

1. 下载技能包：neo-theme-analyze-skill.zip

2. 解压并导入：将 neo-theme-analyze-skill.zip 解压，得到 neo-theme-analyze-skill 目录。

3. 根据你使用的 AI 编辑器，将 skill 添加到对应编辑器中。

CodeBuddy 安装步骤

1. 在「技能」页面，点击右上角的「+ 添加技能」按钮，选择「上传技能」
2. 选择解压得到的 neo-theme-analyze-skill 目录，点击「确定」
3. 安装完成后，在技能列表中可看到「Neo 平台主题换肤支持情况分析」技能

Kiro 安装步骤

1. 将 neo-theme-analyze-skill 目录放入 Kiro 的 skills 目录中
2. 重启 Kiro 或重新加载技能列表

Cursor 安装步骤

1. 将 neo-theme-analyze-skill 目录放入项目的 .cursor/skills/ 目录下
2. 重启 Cursor 或重新加载窗口

覆盖说明

若目标目录中已有同名 skill，覆盖式写入即可。

使用方式

触发方式

在 AI 编辑器中打开待分析的 Neo 项目，然后对 AI 说：

"分析当前项目的主题换肤支持情况"

或使用以下触发短语：

• "分析项目主题换肤支持情况"
• "梳理主题换肤支持情况"
• "盘点主题换肤 / 项目换肤情况分析"
• "主题换肤支持情况分析 / 主题换肤现状分析"
• "分析已支持换肤的组件"
• "分析还有哪些硬编码色"
• "换肤兼容性分析"

若你的真实意图是改造 / 替换（让项目支持换肤、升级换肤功能），本 Skill 不负责改造，请改用「主题换肤 Skill」。

AI 会做什么

AI 会按照以下五个步骤严格顺序执行，最终产出一份分析报告：

步骤	任务	产出
0	采集项目关键信息	项目名称、仓库地址、所在分支
1	扫描「已支持换肤」	已用 CSS 变量的组件清单 + 变量分类与明细
2	扫描「尚存硬编码色值」	残留硬编码色值的组件清单 + 具体色值
3	分析组件元数据与使用位置	50 字内功能说明、组件类型、type/cmpType、项目内引用位置
4	生成报告	项目根目录 当前项目主题换肤支持情况.md

全程由 AI 自主完成，没有「交由人工复核」的环节

脚本产出的功能说明、组件类型、使用位置等都只是初筛线索。AI 必须自己读取源码把它们核实并定稿后写入报告，不得把不确定项以「待人工复核」「待确认」等占位内容遗留在报告里。

步骤 0：采集项目关键信息

通过只读命令读取 package.json 的 name、git 远程地址、当前分支（及可选的短 commit），写入报告头；任一取不到时如实填「未知」。

步骤 1：扫描已支持换肤的页面与组件

在源码（*.scss/css/less/tsx/ts/jsx/js，排除 node_modules、测试文件、构建产物）中查找所有 Neo 主题 CSS 变量引用，按 7 大类归组：

分类	变量前缀 / 代表变量
品牌色	--brand-color、--brand-color-hover、--brand-color-shade、--brand-color-tint …
背景色	--color-bg-brand*
边框色	--color-border-brand*
图标色	--color-icon-brand*、--color-icon-fill-brand-link
文本色	--color-text-brand*、--color-text-brand-link
按钮色	--color-button-filled-primary*（含 -color / -secondary 系列）
导航色	--brand-nav-header-*

对每个组件汇总用到的变量分类与去重后的具体变量列表，并归属到组件与所在页面。项目自定义的非主题变量（如 --gap、--radius）不计入。

步骤 2：扫描尚存硬编码色值

找出「应替换但尚未替换」的残留项，分蓝色与浅蓝两条线：

蓝色（品牌色）

• 完全匹配：色值命中内置 48 组对照表（主品牌色 33 组 + 次品牌色 15 组，含 6 位 hex、8 位 hex、rgb()、rgba() 各格式）
• 近似匹配：色值仅与唯一基准色 #0564f5 差异在 1-2 色阶内（单通道差 ≤ 32 且欧氏距离 ≤ 50），报告标注 近似匹配·N色阶
• 8 位 hex：按前 6 位判断归属，后 2 位换算 alpha，建议替换为 rgba(var(--xxx-rgb), alpha)
• 建议目标变量：主品牌色 → var(--brand-color)；次品牌色 → var(--brand-color-hover)

浅蓝（背景色专用）

以下 11 组浅蓝出现在 background / background-color / backgroundColor 上时计入残留，建议目标变量 var(--brand-color-tint)：

#e6f0fe、#e6f7ff、#e8f0fe、#e8f1ff、#e7f7ff、#eff6ff、#eef2ff、#dcf4ff、#d9f3fb、#eceff8、#edeff2（常见 8 位写法 #edeff280）

含透明度写法：#edeff280 → 建议 rgba(var(--brand-color-tint-rgb), 0.5)；rgba(230, 247, 255, 0.2) → 建议 rgba(var(--brand-color-tint-rgb), 0.2)。

⚠️ 浅蓝只做完全匹配、不参与近似匹配（近似匹配的唯一基准 #0564f5 只服务蓝色）；出现在 color / border-color / box-shadow 等非背景属性上的浅蓝、以及清单外的浅色（#f0f8ff、#fafcff 等）都不计入残留，可记入「合法跳过」区。

Primary 按钮语义识别（强制）

button-primary、ant-btn-primary、btn-primary、a-Button--primary，以及 class 中含 btn-conform、add_button、confirm_button、cancel_button 的按钮，都必须按 Primary 按钮语义分析（这几个不含 primary 字样，最容易漏判），命中的硬编码色优先建议按钮色变量而非普通品牌色：

场景	建议变量
非白底按钮的 background / background-color	--color-button-filled-primary / -hover / -active
非白底按钮的 color（字体色）	--color-button-filled-primary-color / -color-hover
非白底按钮的 border-color / border 中色值	与 background 同一套背景色变量（非字体色变量）
白底按钮 / 空心（轮廓）按钮（含 cancel_button）的 color / border-color	--color-button-filled-primary 状态系列，背景保持原样

add_button（新增）、confirm_button（确认）按实心 Primary 按钮给建议；cancel_button（取消）按空心轮廓按钮给建议。

扫描时会严格按忽略规则逐项判定并跳过（详见下文「智能忽略规则」），跳过项不计入「尚存硬编码色值」，但可在报告「合法跳过」区单独记录。

步骤 3：分析组件功能、类型与使用位置

对步骤 1、2 命中的每个组件：

1. 功能说明：读取组件渲染结构、核心 props、事件处理与数据逻辑，用一句中文概括，长度 ≤ 50 字（不臆测、不写实现细节）
2. 组件类型与注册标识：
   • NeoRegister(...) 注册 → amis 组件，取 name 作为 type
   • XRegister.CmpDefine(...) 注册 → Neo 2.0 组件，取 cmpType
   • 两者均无 → 未知
   • 若同一组件同时命中两类注册 → 同时列出两种标识并注明「注册冲突」
3. 使用位置：按 type / cmpType 在项目内精确检索引用，记录相对路径 + 行号，排除注册声明自身、测试文件与示例；未找到写「未发现」，类型未知或无标识时写「无法按注册标识检索」

步骤 4：生成分析报告

在项目根目录输出 当前项目主题换肤支持情况.md，包含项目关键信息、总体汇总、已支持换肤明细（含逐组件变量明细区）、尚存硬编码色值明细，以及可选的合法跳过项。

数据采集：优先跑内置扫描器

Skill 要求优先运行内置扫描器一次性完成步骤 1~3 的数据采集，再由 AI 逐个读取组件入口核实后撰写报告：

# 在项目根目录执行
node /path/to/neo-theme-analyze-skill/scripts/neoThemeAnalyzer.js

# 指定项目根目录并输出 JSON
node neoThemeAnalyzer.js --root ./my-app --json

配套脚本：

脚本	作用
neoThemeAnalyzer.js	主扫描器，一次性采集变量引用、硬编码残留、组件元数据
neoThemeColorMatcher.js	色值判定引擎，matchBrandColor()（蓝色）/ matchLightBlueTint()（浅蓝）
componentMetadataAnalyzer.js	组件注册类型、功能说明候选、使用位置初筛

无 Node 环境时可退化为手动 grep 扫描，但近似色（与 #0564f5 差 1-2 色阶但不在完全匹配表内）无法用固定 grep 命中，需要借助 matchBrandColor() 判定，或对可疑蓝色逐一计算 Δ_ch / d。

脚本产出的是初筛数据（功能说明候选、注册类型、使用位置等），AI 会逐个读取组件入口核实并定稿后写入报告，不会直接照抄脚本候选值。

智能忽略规则

扫描尚存硬编码色值时，AI 会按固定顺序逐项判定，命中任一规则即判为「合法跳过」，不计入尚存硬编码色值（可在报告「合法跳过」区单独记录）：

忽略场景	说明
① 类名 / 变量名中含色值	如 text-[#0564f5]、bg-[#4e80f5]
② 测试文件	*.test.*、*.spec.*、__tests__/ 目录
③ 已注释代码（5 类形态）	单行 //；行内 // 之后；单行块注释 /* ... */；多行块注释中间行（含以 * 起首的续行，须用状态机跟踪 /* / */ 开合）；JSX 注释 {/* ... */}
④ blue 类选择器（含回溯）	class 名含 blue；所属 CSS 选择器向上回溯（含多行、SCSS/Less 嵌套、& 拼接）后含 blue 也跳过
⑤ var() 中备用（回退）色值	如 var(--brand-color, #0564f5)、var(--card-bg, #e6f0fe)、rgba(var(--brand-color-rgb, 5, 100, 245), 0.2)。仅在变量缺失时兜底，不是运行时生效的主题色 → 不计入残留，蓝色与浅蓝同等适用
⑥ ECharts 属性	图表配置中的色值（ECharts 不支持 var()，需用 getCssVarHex() 方案）。须读取完整文件上下文向上回溯到最外层 option 对象确认，不能只看 color: / itemStyle: 等单行属性名
⑦ 颜色数组字面量	色值位于数组内，如 ['#0564f5', '#4e80f5']
⑧ 取色器对象	色值作为对象属性值，且该对象所有属性值都是色值 → 认定为调色板对象整体跳过
⑨ SASS/Less 变量名含 blue	变量名含 blue（如 $blue-base、@blue-6），对应色值也跳过
⑩ 超阈值非品牌色	与基准色 #0564f5 差异超阈值（单通道差 > 32 或欧氏距离 > 50）
⑪ 浅蓝在非背景属性上	color / border-color / box-shadow / fill / stroke 等属性上的浅蓝不计入残留
⑫ 清单外浅色	不在浅蓝 11 色清单内的浅色（如 #f0f8ff、#fafcff）不计入残留

ECharts 判定的三类命中条件

① 任意层级命中 series: [{ type: 'bar' }]、xAxis、yAxis、legend、grid、dataZoom、visualMap 等专有属性；② 祖先 key 链含 ECharts 专有 key（如 legend.pageIconColor）；③ 经 define() / export default / module.exports / return 导出且顶层含 ≥2 个 ECharts 顶层 option 键的独立配置模块——即使不 import echarts、不用 <ReactECharts>、变量不叫 option 也算。三者任一命中即成立。

报告结构

生成的《当前项目主题换肤支持情况.md》包含以下部分：

1. 项目关键信息：项目名称、仓库地址、所在分支（+ 可选 commit、分析日期）
2. 总体汇总：扫描文件数、已支持换肤组件数、尚存硬编码色值组件数、命中主题变量总数、残留硬编码色值总数、近似匹配数、合法跳过数
3. 一、已支持换肤的页面与组件：以组件为最小粒度逐行输出，含组件名称、功能说明（≤50 字）、组件类型、注册标识、所在页面、文件位置、用到的地方、CSS 变量分类，并附逐组件的具体变量明细区（1.x）
4. 二、尚存硬编码色值：逐组件输出，含组件名称、功能说明、组件类型、注册标识、所在页面、文件位置、用到的地方、残留硬编码色值（标注色系：蓝色 / 浅蓝）、匹配类型、建议目标变量
5. 三、合法跳过项（可选）：因忽略规则跳过的硬编码色值及原因

硬性输出规范

Skill 对报告有一组强制约束，任一不满足即视为未完成分析：

• 必须以「组件」为最小粒度逐行输出，严禁用「components/ 目录 120 个文件」这类目录 / 文件计数聚合替代组件明细
• 每行每个字段都必须填满真实值，不得留空、不得用 -、TODO、「待补充」「待人工复核」「待确认」等占位内容
• 确实无法判定的字段只能按约定值填写：所在页面「未知」、功能说明「未知（未找到组件实现入口）」、组件类型 / 注册标识「未知」、使用位置「未发现」或「无法按注册标识检索」
• 已支持换肤部分必须含逐组件 CSS 变量明细区，只给大类聚合统计视为不合规
• 功能说明必须来自对组件实现的实际阅读，长度 ≤ 50 字；组件类型与注册标识必须来自注册代码证据
• 报告内容必须与实际扫描 / 阅读结果一致，不得编造组件、色值或引用位置

报告样例（节选）

## 一、已支持换肤的页面与组件

| 组件名称 | 功能说明（≤50字） | 组件类型 | 注册标识 | 所在页面 | 文件位置 | 用到的地方 | CSS 变量分类 |
|:--|:--|:--|:--|:--|:--|:--|:--|
| UserCard | 展示用户摘要并支持进入详情 | amis 组件 | `type=user-card` | Dashboard 页 | src/pages/Dashboard/UserCard.tsx | src/pages/Home/schema.ts:32 | 品牌色、文本色 |
| NavBar | 提供全局导航、选中与返回交互 | Neo 2.0 组件 | `cmpType=navBar` | 多页面复用 | src/components/NavBar/index.scss | src/pages/Layout/config.ts:18 | 导航色、按钮色 |

### 1.1 UserCard 变量明细
- 品牌色：`--brand-color`、`--brand-color-hover`
- 文本色：`--color-text-brand-link`

## 二、尚存硬编码色值

| 组件名称 | 功能说明（≤50字） | 组件类型 | 注册标识 | 所在页面 | 文件位置 | 残留硬编码色值 | 匹配类型 | 建议目标变量 |
|:--|:--|:--|:--|:--|:--|:--|:--|:--|
| LoginForm | 提供账号输入、校验与登录提交 | amis 组件 | `type=login-form` | 登录页 | src/pages/Login/LoginForm.scss:22 | `#0564f5`（蓝色） | 完全匹配 | `var(--brand-color)` |
| Badge | 展示带状态语义的徽标信息 | 未知 | 未知 | 未知 | src/components/Badge/index.tsx:31 | `#0968f5`（蓝色） | 近似匹配·1色阶 | `var(--brand-color)` |
| InfoPanel | 展示提示信息与操作入口 | Neo 2.0 组件 | `cmpType=infoPanel` | 详情页 | src/pages/Detail/panel.scss:14 | `#e6f0fe`（浅蓝，background） | 完全匹配 | `var(--brand-color-tint)` |
| SubmitBtn | 提交表单并反馈提交状态 | amis 组件 | `type=submit-btn` | 表单页 | src/components/SubmitBtn/index.scss:9 | `#0564f5`（btn-conform 背景） | 完全匹配 | `var(--color-button-filled-primary)` |

典型使用场景

场景：改造前先摸清项目换肤家底

你接手一个体量较大的历史项目，不确定前人有没有做过换肤改造，也不清楚还有多少硬编码颜色散落在各处，直接动手改造心里没底。

使用 Skill 后：

1. 对 AI 说："分析当前项目的主题换肤支持情况"
2. AI 按顺序执行五个步骤：采集项目信息 → 扫描已支持换肤组件 → 扫描尚存硬编码色值（蓝色 + 浅蓝背景色 + Primary 按钮语义）→ 分析每个组件的功能 / 类型 / 使用位置 → 生成《当前项目主题换肤支持情况.md》
3. 你拿到一份逐组件的现状清单，清楚看到「已支持 X 个组件、还有 Y 个组件残留硬编码色」，据此评估改造工作量与优先级

价值：无需逐文件人工排查，一次对话即可产出结构化现状报告，让改造决策有据可依；改造完成后再跑一次，还能作为验收复盘的依据。

常见问题

Q: 这个 Skill 会修改我的代码吗？

不会。本 Skill 全程只读，只扫描和阅读源码，唯一产物是项目根目录下的《当前项目主题换肤支持情况.md》报告，不会改动任何源码文件。

Q: 它和「主题换肤 Skill」有什么区别？

本 Skill 只做只读盘点分析，输出现状报告；「主题换肤 Skill」才会真正改造替换源码。建议先用本 Skill 摸清现状，再用升级 Skill 改造，最后再用本 Skill 验收复盘。

Q: 什么是近似匹配？

当源码中的色值与唯一基准色 #0564f5 差异在 1-2 色阶内（单通道差 ≤ 32 且欧氏距离 ≤ 50）时，Skill 会推断它是主品牌色变体并计入「尚存硬编码色值」，在报告中标注 近似匹配·N色阶 及差异数值，方便你复核确认。近似匹配只与 #0564f5 比较，不与对照表其他色值（含次品牌色）比较。

Q: 浅蓝色值为什么只在背景属性上算残留？

浅蓝的对应变量是 var(--brand-color-tint)，语义上就是浅色底色。出现在 color、border-color、box-shadow 等非背景属性上的浅蓝不属于换肤改造范围，因此不计入残留。清单外的浅色也不做近似推断，避免把中性浅灰底色误判成品牌色。

Q: 为什么 var() 里的色值不算残留？

var(--brand-color, #0564f5) 中逗号后的色值是备用（回退）值，只在 CSS 变量未定义时兜底，不是运行时生效的主题色，替换它也没有换肤收益。所以这类色值一律判为合法跳过，蓝色与浅蓝同等适用。

Q: add_button、cancel_button 这类名字也会被识别吗？

会。btn-conform、add_button、confirm_button、cancel_button 都不含 primary 字样，但属于 Primary 按钮语义，Skill 会强制识别并按按钮语义给出 --color-button-filled-primary* 建议变量。其中 add_button / confirm_button 按实心按钮处理，cancel_button 按空心轮廓按钮处理（只对 color / border-color 给建议）。

Q: 组件类型是怎么判定的？

按注册代码判定：通过 NeoRegister(...) 注册的判为 amis 组件，取 name 作为 type；通过 XRegister.CmpDefine(...) 注册的判为 Neo 2.0 组件，取 cmpType；两者都没有则为「未知」。若同时命中两类注册，报告会同时列出两种标识并注明「注册冲突」。

Q: 报告里的「使用位置」是怎么来的？

AI 会用组件的 type / cmpType 值在项目内精确检索引用（如 type: 'user-card'、cmpType="navBar"），记录相对路径与行号，并排除注册声明自身、测试文件和示例。找不到引用时写「未发现」，类型未知或无标识时写「无法按注册标识检索」。

Q: 报告里会出现「待人工复核」吗？

不会。Skill 明确要求 AI 自主完成全部核实工作，报告中的每个字段都必须填满真实值；无法判定时只能填写约定值（「未知」/「未发现」/「无法按注册标识检索」），不允许出现空白、-、TODO 或「待复核」类占位内容。

Q: 为什么 ECharts 图表里的颜色没被算作硬编码残留？

ECharts 不支持 var(--css-variable) 写法，Skill 会将图表配置中的色值判为「合法跳过」，不计入尚存硬编码色值。判定时会读取完整文件上下文向上回溯到最外层 option 对象确认。如需图表也响应换肤，请使用 getCssVarHex() 方案。

Q: 不装 Node.js 能用吗？

可以，但准确度会下降。内置扫描脚本是 Skill 推荐的数据采集方式；无 Node 环境时 AI 会退化为手动 grep 扫描，而近似色无法被固定 grep 命中，需要 AI 对可疑蓝色逐一计算色差判定，耗时更长也更易漏项。建议尽量装上 Node.js。

反馈与改进

使用过程中遇到问题或有优化建议，欢迎提交到 neo-cmp-docs Issues。