@qilitt-mickey/vue3-temp-skill 1.2.6 → 1.2.7

package/README.md

@@ -1,146 +1,82 @@
 # vue3-temp-skill
 
-Vue 3 企业级中后台项目开发技能包。两条链路：
+面向 **vue3-web-temp 及其派生 Vue 3 项目**的工程技能。支持常规功能开发，也支持与通用设计技能 `project-ui-design` 同轮协作：按原稿调整真实项目的页面、布局和组件表现，保留项目业务与工程约束。
 
-- **常规开发** —— 能力组路由（列表页 / 表单 / API / 权限 / 可视化 …）
-- **视觉契约落地** —— 读设计侧契约，照抄生成三份 CSS
+## 双技能使用
 
-与设计侧 `project-ui-design` 构成双端体系。
-
-## 这是什么
-
-### 链路一 · 常规开发
-
-```text
-/vue3-temp-skill <自然语言需求>
-  → 项目探查（package.json / 路由 / Re* / Hooks / API）
-  → 能力路由（match.py "需求" --json，按 load_files 读）
-  → 业务闭环实现（页面 + 路由 + API + 类型 + mock）
-  → code-quality 清单 + lint / type-check
-```
-
-### 链路二 · 视觉契约落地
+在目标项目中附上设计图、设计文件路径或已确定的 Demo：
 
 ```text
-输入：<项目根>/.design/visual-contract-<场景>-<页型>.json
-  → ① 落地自检（六项：契约存在/完整/CSS生成/CSS引入/角色挂载/布局挂载）
-  → ② 读契约（唯一输入，只读一次）
-  → ③ 选 adapter（按 package.json 判定所用组件库）
-  → ④ 生成 ui-tokens.css（:root 变量）
-  → ⑤ 生成 ui-roles.css（.role-* 规则）
-  → ⑥ 生成 ui-layout.css（.ui-page 网格）
-  → ⑦ 挂载（.ui-page / .ui-region-* / .role-*）
-  → ⑧ 重跑自检确认六项全过 → 目视对照
+/project-ui-design 按照设计效果进行还原落地到项目中
+/vue3-temp-skill 代码规范按照此要求
 ```
 
-**AI 在链路二的工作是翻译，不是判断。** 契约写什么就生成什么——落点层级已由 `host[]` / `inner[]` 两个数组物理二分，落地端不推断属性该落哪一层。
+两行先后顺序不影响职责顺序；不需要人工搬运 JSON 或另开会话。不支持 Slash 的编辑器可直接读取两个 `SKILL.md` 及其相对资源。缺少原稿时明确补充来源，不把内置示例当成用户选定设计。
 
-**落地自检是交付前置条件**（`npm run check:landing`）：
+## 执行链路
 
-| 检查项 | 断点含义 |
-|---|---|
-| `contract-found` | `.design/` 下没有契约 → 设计侧没落盘 |
-| `contract-valid` | 契约字段缺失 |
-| `css-generated` | 三份 CSS 未生成 |
-| `css-imported` | **生成了但没被 import** → 浏览器不加载 |
-| `roles-mounted` | **CSS 有规则但模板没挂类** → 死样式，只有个别角色生效 |
-| `layout-mounted` | 没挂 `.ui-page` → 骨架仍是项目原样 |
-
-**任何一项断掉都会表现为「CSS 写了但页面没变化」。先跑自检定位断点，不要目视猜。**
-
-## 视觉契约的核心机制
+**设计还原**：项目探查 → 固定原稿与视觉交接 → 保存业务基线 → 调整真实视图 → 工程检查、业务回归与原稿对照 → 修正差异。
 
-| 机制 | 说明 |
-|---|---|
-| **照抄不判断** | 不判断落点层级、不合并声明、不补角色库没有的角色、不改契约值 |
-| **布局由 CSS 网格决定** | 项目布局组件退化为占位容器（只提供插槽）；设计布局与项目布局不一致时，差异只体现在 `ui-layout.css` 的取值上 |
-| **角色类独立命名空间** | `role-` 前缀独立类 + 独立文件，天然不与组件库同类规则竞争；确需提权走 adapter 唯一通道 |
-| **令牌全站联动** | 契约令牌编译为 CSS 变量；改一个令牌值，全站引用它的地方同步变化 |
-| **契约不含技术栈信息** | 只有 CSS 属性、令牌引用、区域与角色；组件库差异（深度选择器语法、穿透前缀、落点文件）全在 adapter |
+**常规开发**：项目探查 → `scripts/match.py` 按需路由 → 复用项目组件、Hooks、HTTP 和类型 → 完成行为闭环 → 工程与功能检查。
 
-## 文档分工
+原稿决定视觉，项目源码和用户明确需求决定业务，模板规范决定工程实现。
 
-| 文件 | 读者 | 内容 |
-|------|------|------|
-| `SKILL.md` | AI | 触发方式、目标、能力组路由、工作流、视觉契约落地要点、红线 |
-| `README.md`（本文件） | 维护者 / 开发者 | 安装、命令、扩展、新增 adapter、与模板的关系 |
-| `references/*.md` | AI | 40+ 专项能力 reference（业务开发用） |
-| `references/design-apply.md` | AI | **视觉契约落地协议**：六步流程 + 三列映射表 + 翻译规则 |
-| `references/adapters/*.md` | AI | Vue 组件库适配：深度选择器语法 / 穿透前缀 / 落点文件 |
-| `mapping/<场景>.json` | AI + 维护者 | 区域名 ↔ 项目现状对照（scope / var / fallback 三列） |
+- 可调整页面模板、壳层布局、视觉容器、CSS 及项目自有 `Re*` 组件的表现层；不限于加 class 或生成三份 CSS。
+- 保留项目的字段、菜单、列、筛选、按钮、枚举、API、权限、校验、状态和业务顺序；不复制 Demo 业务凑截图。
+- 保留组件公开接口、`useTableSearch` 定高与滚动链、`ReTableBar`、`RePagination`、`ReTableOperate` 和详情返回链；共享改动检查所有受影响调用处。
 
-## 安装
+## 原稿与证据
 
-Node.js >= 22.12.0
+新交接格式为 `ui.design-handoff/1.0`。同一任务保存于 `<项目根>/.design/<任务名>/`：
 
-```bash
-npx @qilitt-mickey/vue3-temp-skill@latest install all
-```
-
-一键安装到本机检测到的全部 AI 编程工具；也可显式指定：
-
-```bash
-npx @qilitt-mickey/vue3-temp-skill@latest install cursor
-npx @qilitt-mickey/vue3-temp-skill@latest install all --project ./my-app
-npx @qilitt-mickey/vue3-temp-skill@latest update
-```
-
-| 目标 | 级别 |
-|------|------|
-| cursor / qoder / claude / universal / windsurf / trae | 全局（个人目录） |
-| copilot / gemini | 项目级（需 `--project <dir>`） |
-
-安装器复制运行时文件：`references/`（含 `adapters/`）、`scripts/`（`match.py` + `modules.json`）、`mapping/`、`SKILL.md`、`README.md`。`release.js` 留在技能包仓库供维护使用。
-
-开发期调试可直接从源码目录安装：`node bin/cli.js install claude`。
+| 产物 | 责任 |
+|---|---|
+| `handoff.json`、原稿、参考图、素材 | 设计侧提供通用视觉规格与来源证据 |
+| `business-baseline.json` | 项目侧记录实施前业务与当前工作区基线 |
+| `implementation.json` | 项目侧记录原稿区域到目标文件、路由、实例的映射 |
+| `verification.json`、结果图 | 项目侧记录逐项对照、差异、业务及工程结果 |
 
-## 命令
+原稿始终可重新打开。逐区域、逐实例、逐状态、逐视口检查；必需元素缺失不能记为跳过。只在已验证的可比范围内报告结果，不把业务内容差异改成 Demo 数据，不用“CSS 存在”或脚本退出成功替代视觉证据。
 
-| 命令 | 职责 |
-|------|------|
-| `node bin/cli.js install <target>` | 安装器统一入口：`install` / `update` / `uninstall` / `list` |
-| `npm run check:landing` | **契约落地自检**（六项）：判断「契约 → 样式 → 挂载」断在哪一环 |
-| `python scripts/match.py "需求" --json` | 能力路由：按需求返回应加载的 reference 清单 |
-| `npm run release`（`:minor` / `:major`） | 结构检查 → 升版本 → 提交 → 发布 npm |
+## 旧格式兼容
 
-## 扩展
+已有 `ui.visual-contract/1.0` 仍可读取：保留原文件，找回其设计来源，复用可信规格并补新交接。旧 adapter、mapping 和角色规则仅作为排查线索，不覆盖原稿值。
 
-| 要加什么 | 怎么做 | 哪些文件不动 |
-|---|---|---|
-| 新业务能力 | 在 `references/` 加一份专项 md + 在 `scripts/modules.json` 登记 | 其余全部 |
-| 新组件库适配 | 照 `references/adapters/_new-adapter.md` 写一份 Vue 组件库 adapter | 契约、`design-apply.md`、其他 adapter |
-| 新场景的变量映射 | 加 `mapping/<场景>.json` | adapter 与契约 |
-| 项目自身能力 | 写进 `references/project-inventory.md` | 全部 |
+旧 `generate-css.mjs` 与 `verify-render.mjs` 已停止执行，调用会给出迁移提示。旧 `check-landing.mjs` 只有显式 `--legacy-diagnostics` 才运行文本诊断，始终标记视觉未验证并非零退出；它不是当前验收入口。
 
-**新增 adapter 的判据**：写完后同一份契约应能不改一行内容地落到用该组件库的项目。若需要改契约，说明 adapter 越界了。
+## 主要规范
 
-**关于跨前端框架**：契约格式本身不含技术栈信息，因此可以交给不同框架的项目技能消费。但**本技能只服务 Vue 3**，adapter 只覆盖 Vue 组件库——支持 React / Angular 等框架时，由对应框架的项目技能自带 adapter，契约无需改动。
+| 文件 | 用途 |
+|---|---|
+| `SKILL.md` | 分支、职责、实施和完成条件 |
+| `references/core-kernel.md` | 模板工程硬约束 |
+| `references/design-apply.md` | 原稿接入、业务保护、视图实施 |
+| `references/visual-verification.md` | 视觉、状态、视口与业务验收 |
+| `references/code-quality.md` | 工程质量及交付检查 |
+| `references/adapters/vue-element-plus.md` | 实际组件 DOM 与样式落点检查 |
+| `scripts/modules.json`、`scripts/match.py` | 常规需求的按需规范路由 |
 
-## 与设计侧的关系
+## 安装与测试
 
-| 契约 | 说明 |
-|------|------|
-| 视觉契约 | 设计侧唯一交付物，协议 `ui.visual-contract/1.0`；只有 CSS 属性、令牌引用、区域与角色 |
-| 落点路径 | 设计侧写 `<项目根>/.design/`，本技能从同一路径读——目录通用，与 AI 工具无关 |
-| 三列映射表 | 本技能侧的 `mapping/<场景>.json`，把契约的区域名对到项目现状的承载类名 |
-| adapter | 承接组件库差异，本技能侧维护；设计侧不感知 |
+要求 Node.js >= 22.12.0；能力路由需要 Python 3，无 Python 时按技能入口表加载规范。本轮改动尚未发布到 npm，先从本源码目录安装到选定编辑器：
 
-## 与模板的关系
+```bash
+node bin/cli.js --help
+node bin/cli.js install qoder
+node bin/cli.js install copilot --project /path/to/project
+node bin/cli.js list
+npm test
+python scripts/match.py --batch
+```
 
-本 Skill 约定对齐 **vue3-web-temp** 精简脚手架：
+安装器携带运行时资源；项目级说明使用独立托管区块，避免覆盖用户说明及另一套技能。安装目标和参数以 `--help` 为准。旧版本冲突按提示处理，勿直接覆盖未知文件。
 
-| 文档 | 读者 | 内容 |
-|------|------|------|
-| 模板 `README.md` | 人类开发者 | 安装、配置、命令、与 AI 协同入口 |
-| 模板 `AGENTS.md` | AI 助手 | 仓库事实、硬性约定摘要、Skill 路由 |
-| 本包 `references/` | AI + 开发者 | **标准样板**、专项细则、addon 安装表 |
-| 本包 `addon-enable.md` | AI + 开发者 | **出厂已删依赖的逐文件恢复代码** |
+`npx @qilitt-mickey/vue3-temp-skill@latest` 仍指向已发布版本；新版发布前不会包含本轮修改。源码检查通过不代表所有编辑器已经实机验证。
 
-## 工具中立
+## 与模板及设计侧的边界
 
-本包与任何 AI 工具无关。`references/` / `scripts/` / `mapping/` / `SKILL.md` 内不出现任何特定 AI 工具的名称或专有路径；`bin/cli.js` 的多工具安装清单是**分发特性**，不是内容绑定。
+模板 `AGENTS.md` 提供当前项目事实与入口；本包维护 Vue 模板的工程流程和适配；设计侧保持通用，不维护模板路径、组件名、CSS 选择器或业务映射。
 
-## 发布
+新增业务能力时增加按需 reference 并登记路由；新增 Vue 组件库时增加适配规范并验证实际 DOM。其他框架使用各自项目技能，通用设计交接无需修改。
 
-- 维护侧：`npm run release` 自动完成结构检查、升版本与发布（支持 `--dry-run` / `--no-push`）
-- 用户侧：发布后经 `npx @qilitt-mickey/vue3-temp-skill@latest update` 更新已安装目标
+发布入口保留在 `package.json`；提交、发布和安装到用户环境均需明确授权。本次源码更新不等于已经发布或更新了机器上的已安装技能。

package/SKILL.md

@@ -1,174 +1,56 @@
 ---
-name: "vue3-temp-skill"
-description: "Vue 3 企业级项目开发技能。面向 vue3-web-temp 及其派生项目，帮助产品经理和前端快速把点子做成可演示、可验证、可继续演进的 Demo；同时约束真实模板复用、代码质量，并支持把设计侧的视觉契约照抄落地。"
-scope: project
-agent_created: true
-tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-quality, visual-contract]
+name: vue3-temp-skill
+description: 在 vue3-web-temp 及其派生 Vue 3 项目开发功能、修复代码或落地设计。与 project-ui-design 同轮使用时，保留项目业务，按模板规范调整视图、布局、组件样式并逐区域验证视觉效果。
 ---
 
-# Vue 3 项目开发技能
+# 执行
 
-## 目标
+先判断用户是否要求修改项目。仅要求设计或预览时，由 `project-ui-design` 完成设计与交接；本技能只提供已要求的工程约束，不修改项目代码，不进入以下实施步骤。明确要求落地、功能开发或修复时再执行以下流程。
 
-把产品点子快速落到真实 Vue 3 项目中，先形成客户可看的完整 Demo，再保留后续正式开发所需的代码边界。页面可以使用 mock 和最小数据，但不得使用模板演示噪音、虚构项目能力或堆叠无法维护的代码。
+## 1. 确认项目与任务
 
-## 触发方式
+- 使用用户指定的项目根或当前已打开的目标项目；读取项目协同说明、`package.json`、锁文件及 Git 状态，保留已有未提交改动。
+- 读取 `references/core-kernel.md`；以当前源码核对组件、依赖、路由、接口、主题和布局，不把模板清单当成当前项目事实。
+- 用户要求设计还原、UI 改版、按图落地，或同轮调用 `project-ui-design` 时，直接进入 `references/design-apply.md`；有原稿但无 JSON 时在同轮调用或读取设计技能，完成提取后继续实施。
+- 只有业务功能需求时运行 `python <本技能>/scripts/match.py "<需求>" --json`，按 `load_files` 加载专项规范；无 Python 时按下表选取。
+- 同时有业务增量和视觉需求时，分别列出用户授权的业务变更与视觉变更；Demo 不提供新增业务需求。
+- 完成条件：项目根、目标范围、任务类型和实际可用规范已确定；不在技能仓库中写目标业务代码。
 
-```text
-/vue3-temp-skill <自然语言需求>
-```
+## 2. 分配职责
 
-典型需求：
+- `project-ui-design` 提供原稿、视觉规格、素材与对照依据；本技能决定目标文件、组件组合、实际样式落点和业务回归。
+- 按「项目探查 → 设计提取 → 业务映射 → 视图实施 → 视觉与功能验证」执行；两行 Slash 的先后顺序不改变流程。
+- 原稿控制视觉；目标项目及明确的业务需求控制数据和行为；模板规范控制工程实现。发生视觉与默认样板差异时调整样板视图，保留硬性代码规范。
+- 宿主没有 Slash 或技能调用工具时直接读取两个技能入口及相对资源；不依赖特定编辑器、浏览器插件或多代理机制。
+- 完成条件：每项修改都有视觉依据或明确业务授权，不把设计技能绑定到本模板。
 
-- 开发客户管理列表，支持搜索、分页、编辑和详情
-- 做一个订单仪表盘，含统计卡片和趋势图
-- 给现有 Demo 增加附件上传、导出或审批流
-- 把一个页面从 mock 改成真实 API
-- 「按这份设计契约改造全系统」（用户可能是小白，只会给文件路径或拖入文件；见 §3b）
+## 3. 实施
 
-## 运行时只保留三件事
+- 视觉任务按 `references/design-apply.md` 完成全部步骤，允许修改页面模板、布局和项目自有组件的表现层；不限定只生成 CSS 或只加 class。
+- 常规功能任务复用现有 `Re*`、Hooks、HTTP、类型、权限与路由；按命中模块完成页面和行为闭环。
+- 列表保留 `useTableSearch`、`ReTableBar`、`RePagination`、`ReTableOperate` 及其数据和事件契约；HTTP 经 `@/utils/http`，类型按实际 `Result<T>`。
+- 新增依赖、改变权限规则、发送外部消息、发布或破坏性操作按用户授权执行；不得以视觉需求替代这些授权。
+- 完成条件：目标视图已接入真实项目路径与原有业务，样式已在运行页面生效，功能未被静态演示内容替换。
 
-1. **项目探查**：读取目标项目的 `package.json`、路由、页面、`Re*` 组件、Hooks、API 和样式；以源码事实为准。
-2. **能力路由**：运行 `scripts/match.py "需求" --json`，**仅**按输出中的 `load_files` 阅读 reference；禁止自行展开全部 `references/`。无 Python 时按下方能力组表手动匹配。
-3. **视觉契约落地**：输入是设计侧的视觉契约 JSON 时，走 `design-apply` 协议——**先跑落地自检，再照抄生成三份样式文件与页面骨架 SFC**，见 §3 输入分流。
+## 4. 验证交付
 
-```bash
-node <技能>/scripts/check-landing.mjs --project <项目根>
-```
+- 重读 `references/code-quality.md`，检查实际改动；执行项目已有 lint、类型检查及相关构建/测试命令。
+- 视觉任务读取 `references/visual-verification.md`，对原稿与真实目标页面逐区域、逐状态、逐视口核验，修复后重测。
+- 独立检查业务保持与视觉还原；不以脚本 exit 0、class 出现、CSS 已生成、类型通过或截图已保存替代视觉及功能验收。
+- 返回修改范围、原稿与目标页面、实际检查结果、差异和产物路径。浏览器或业务环境不可用时明确列出未验证项，不宣称完成还原。
+- 完成条件：请求范围无未解释差异，工程与业务回归通过，参考图、结果图和逐项结果可读取；否则保持未完成并说明具体阻塞。
 
-**八项全过（exit 0）是交付前置条件**：契约存在 → 契约完整 → 契约结构合规 → 三份 CSS 生成 → 被 import → 角色类挂载 100% → 布局类挂载 → CSS 规则覆盖契约全部声明。
-**任何一项断掉，都会出现「CSS 写了但页面没变化」——先修断点，不要目视猜。**
+## 按需规范
 
-## 能力组路由
-
-| 能力组 | 覆盖内容 | 主要参考文件 |
-|---|---|---|
-| `page-crud` | 常规列表、筛选、分页、表格操作 | `crud-pages.md` |
-| `page-detail` | 独立详情/编辑页、顶部标签、路由 meta | `detail-page.md` |
-| `data-service` | HTTP、API、类型、mock、联调 | `http-api.md`、`api-check.md` |
-| `forms` | 表单、弹窗、远程选择、回显、字典、反馈 | `form-advanced.md`、`data-writeback.md`、`base-code-dict.md`、`feedback-loading.md` |
-| `access` | 权限、认证页面 | `permission-auth.md`、`auth-pages.md` |
-| `theme-layout` | 布局、主题色、暗黑模式、侧栏配色、令牌 | `layout-theme.md` |
-| `shared-ui` | Re*、图标、通用展示和指令 | `ui-components.md`、`icons.md`、`feedback-ui.md`、`directives-advanced.md` |
-| `table-advanced` | 树表、VXE 表格 | `tree-table.md`、`table-vxe.md` |
-| `visualization` | 图表、大屏、关系图谱 | `chart-echarts.md`、`data-screen.md`、`graph-relation.md` |
-| `workflow` | BPMN、G6 流程图、字段映射 | `workflow-bpmn.md`、`flowchart-g6.md`、`data-mapping.md` |
-| `files-and-editors` | 附件、预览、下载、富文本、二维码 | `file-management.md`、`download-export.md`、`rich-text.md`、`qrcode-barcode.md` |
-| `realtime-and-mobile` | WebSocket、移动端、微信、验证码、动效 | 对应专项 reference |
-| `data-compare` | 编辑页变更对比和汇总 | `data-compare.md` |
-| `design-apply` | **视觉契约落地**：落地自检 → 读契约 → 选 adapter → **`scripts/generate-css.mjs` 确定性生成三份 CSS** → **`scripts/generate-page.mjs` 确定性生成页面骨架 SFC（不手写骨架）** → 挂载 → **`scripts/verify-render.mjs` computed style 逐点比对** → 差异清零。**主入口 `design-apply.md`，adapter 见 `adapters/`（做到哪一步读哪一份）** | `design-apply.md`、`adapters/`、`mapping/`、`scripts/check-landing.mjs`、`scripts/generate-css.mjs`、`scripts/generate-page.mjs`、`scripts/verify-render.mjs` |
-
-## 工作流
-
-### 1. 识别目标和范围
-
-- 确认目标项目根目录；没有明确目标时先询问，不在技能仓库里写业务代码。
-- 判断是 Demo 验证、功能增量还是正式业务开发。
-- 保留目标项目当前初始化视觉，不让开发技能自行设计。
-
-### 2. 读取事实
-
-- 先读 `references/core-kernel.md`。
-- 运行 `scripts/match.py "需求" --json`，按 `load_files` 阅读。
-- 读取目标项目当前 `package.json` 和锁文件；不要根据"core/addon"标签猜依赖是否存在。
-- 扫描已有 `Re*`、Hooks、`src/api`、路由和相关页面；已有封装优先于技能示例。
-
-### 3. 实现闭环
-
-- 页面、路由、API、类型、mock 和共享组件按一个业务闭环实现。
-- 列表使用 `useTableSearch`、`ReTableBar`、`RePagination`；有独立详情时同步完成 `useDetail` 与路由 meta。
-- HTTP 只经过 `@/utils/http`，响应按项目实际 `Result<T>` 约定处理。
-- Demo 可以最小化数据和接口，但目录、类型、命名和组件边界要能承接后续开发。
-- 新依赖先检查目标项目；缺失时说明精确版本、原因和构建接线，确认后再安装。
-- 只有目标项目确实存在排除项、占位插件或缺失接线时，才读取 `addon-enable.md` 恢复配置。
-
-**输入分流**：
-
-| 输入 | 走哪条链路 |
-|---|---|
-| 自然语言需求（业务功能） | 常规闭环（见上） |
-| **设计侧的视觉契约 JSON**（`ui.visual-contract/1.0`，落盘在 `.design/`） | **`design-apply.md` 协议** —— 照抄生成 `ui-tokens.css` / `ui-roles.css` / `ui-layout.css` |
-
-### 3b. 小白用户执行纪律（design-apply 场景）
-
-使用者默认**不懂设计也不懂代码**，交互遵守四条：
-
-1. **全自动默认**：识别为视觉契约后**直接开始执行全流程**（落地自检 → 读契约 → 选 adapter → 生成三份 CSS → 生成页面骨架 → 挂载 → 验证 → 视觉验收），不等用户逐步确认。
-2. **契约缺失 = 硬阻断，不允许"边猜边改"**：`check-landing.mjs` 报 `contract-found FAIL` 时**必须停下**，用大白话报告「还没拿到设计文件」并给出下一步。**严禁在契约缺失的情况下凭理解直接改项目样式**——那是旧体系的失败模式：改了一堆 CSS 却没有任何东西对应，最后只有个别地方碰巧变了。
-3. **契约存在但 `roles-mounted` 未 100% = 不算完成**：角色类没挂满，页面上就只会有个别角色生效（常见症状：只有菜单颜色变了）。必须按 adapter 的「角色类挂载方式」补齐后重跑自检。
-4. **术语不对用户出现**：对用户不说"契约 / 角色 / 令牌 / adapter / 区域 / 自检"——说"设计文件 / 样式规则 / 全局变量 / 组件适配 / 页面区域 / 检查"。这些词只出现在内部文档与交付说明里。
-5. **无文件时的引导**：用户说"全系统改成 XX 风格"但没给设计文件 → 提示一句话："请先在设计助手（project-ui-design 技能）里说『我要 XX 风格的全系统设计』拿到设计文件，再回来发给我"。如果本机同时装有设计技能，可直接引导用户回到设计会话完成设计，再回本项目落地。
-6. **交付话术**：完成后用大白话总结（改了哪些页面 / 哪些地方变了 / 怎么验收），不输出施工坐标等技术细节；验收引导统一为"运行 `pnpm dev` 打开页面对照看效果，哪里不满意直接说"。
-
-### 4. 验证与交付
-
-- 对照 `references/code-quality.md` 检查类型、组件复用、API、路由、权限、安全、异常反馈、响应式和可演进性。
-- 在目标项目执行 `pnpm lint:fix`、`pnpm type-check`；改动构建配置时再执行 `pnpm build`。
-- **设计契约落地时追加视觉验收**：用无头浏览器对契约每条声明做 `getComputedStyle` 逐点比对（期望源就是契约 JSON 本身）；差异定位顺序「挂载遗漏 → 穿透/选择器通道错 → 提权被盖 → 契约值本身错」，前三者修落地侧，最后一种 **改契约 → 重新生成 CSS**（改契约远比改代码便宜）。全部命中后截图与 `meta.source.mockup` 并排留档；不建期望值文件、不跑采集脚本、不做长期 diff 报告。
-- 最终说明：命中能力组、修改文件、功能验证、命令结果、未解决问题和下一步。
-
-## 视觉契约落地（design-apply 架构要点）
-
-契约是设计侧产出的**项目完整视觉事实源**，协议 `ui.visual-contract/1.0`。
-
-| 原则 | 含义 |
+| 需求 | 读取 |
 |---|---|
-| **照抄不判断** | 契约写什么就生成什么。落点层级已由 `host[]` / `inner[]` 两个数组物理二分，落地端不推断「这属性落哪层」 |
-| **契约是唯一事实源** | 不读项目现有样式来决定怎么落地；冲突时以契约为准 |
-| **布局由 CSS 网格决定** | 项目布局组件退化为**占位容器**（只提供插槽，不参与布局决策）；设计布局与项目布局不一致时，差异只体现在 `ui-layout.css` 的取值上，不需要适配、不需要切形态、不需要结构手术 |
-| **角色类独立命名空间** | 角色类是 `role-` 前缀的独立类 + 独立文件，天然不与组件库同类规则竞争；确需提权时走 adapter 的唯一通道，**不在角色类里整条加 `!important`** |
-| **契约不含技术栈** | 契约里只有 CSS 属性、令牌引用、区域与角色——本技能据此生成样式，无需理解组件内部实现 |
-| **组件库差异只在 adapter** | 深度选择器语法、穿透前缀、落点文件——adapter 的全部职责；本技能只服务 Vue 3，adapter 只覆盖 Vue 组件库 |
-
-**三条产物的命名空间互不干扰**：
-
-| 命名空间 | 归属 | 产物 |
-|---|---|---|
-| 页面私有样式 | 常规开发 | 页面 scoped 样式 |
-| `role-` | 视觉契约落地 | `src/styles/ui-roles.css` |
-| `ui-` | 视觉契约落地 | `src/styles/ui-tokens.css` + `src/styles/ui-layout.css` |
-
-## 项目事实优先级
-
-`目标项目当前源码` > `目标项目 package.json / 锁文件` > `本 Skill reference` > `通用 Vue 习惯`。
-
-## 工具中立（不可越）
-
-本技能包**与任何 AI 工具无关**，可被任意工具识别与调用。
-
-| 约束 | 说明 |
-|---|---|
-| **技能内容零工具痕迹** | `references/` / `scripts/` / `mapping/` / `SKILL.md` 内不出现任何特定 AI 工具的名称、专有目录、专有文件格式 |
-| **路径约定用通用目录** | 读契约：`<项目根>/.design/`；写样式：`src/styles/`。都是通用项目目录 |
-| **分发靠 CLI 多目标** | `bin/cli.js` 的多工具安装能力是**分发特性，不是内容绑定**；工具清单可增删，不影响技能内容 |
-| **触发用 Slash Command** | `/vue3-temp-skill`，各工具通用约定 |
-
-**判据**：把本包放进任何一个支持 Markdown + JSON + Python 的 AI 环境，不改任何一行内容就能用。
-
-## 默认禁止
-
-- 不在页面内直接使用 `axios` / `fetch`，不虚构 API 前缀。
-- 不二次挂载 `Layout`，不把模板演示页原样当业务页面。
-- 不使用裸 `v-if` 代替权限指令，不使用不可信 `v-html`。
-- 不为了视觉效果引入未经确认的新 UI 框架或图表库。
-- 不把 lint 通过当成业务闭环完成。
-- **不改组件库源码**；样式调整只经 `ui-*.css` 三份文件与项目自身样式层。
-- **不直接改生成出来的 `ui-*.css`**——要改改契约或改 adapter，然后重新生成。直接改会被下次生成覆盖，且不留痕迹。
-- **不在角色类里整条加 `!important`**——层叠问题走 adapter 的唯一提权通道。
-- **不为契约新增技术栈字段**——组件库差异进 adapter，契约保持中立。
-
-## 最终回复格式
-
-```markdown
-## 命中能力组
-- page-crud / data-service / ...
-
-## 变更说明
-- `src/...`：...
-
-## 验证结果
-- 功能：...
-- `pnpm lint:fix`：通过 | 失败（原因）
-- `pnpm type-check`：通过 | 失败（原因）
-- 视觉契约落地（本轮有契约输入时必填，无则 N/A）：八项自检全过 → 视觉验收 computed style 比对差异 N 处（已改契约重新生成 / 待确认）→ 截图已留档
-```
+| 设计还原 / 外观改版 | `references/design-apply.md` → `references/visual-verification.md` |
+| 列表与详情 | `references/crud-pages.md`、`references/detail-page.md` |
+| 数据接口 | `references/http-api.md`、`references/api-check.md` |
+| 表单与回显 | `references/form-advanced.md`、`references/data-writeback.md`、`references/base-code-dict.md` |
+| 权限与登录 | `references/permission-auth.md`、`references/auth-pages.md` |
+| 主题与壳层 | `references/layout-theme.md` |
+| 通用组件与图标 | `references/ui-components.md`、`references/icons.md` |
+| 高级表格、图表、流程、文件、移动端 | 按 `scripts/modules.json` 中的能力组加载对应 reference |
+| 缺失依赖与 addon | `references/project-inventory.md`、`references/addon-enable.md` |
+| 交付检查 | `references/code-quality.md` |