@qilitt-mickey/vue3-temp-skill 1.1.30 → 1.1.33

package/README.md

@@ -1,16 +1,25 @@
 # vue3-temp-skill
 
-Vue 3 企业级中后台项目开发规范技能包 — 按团队规范生成代码并自动审查。
+Vue 3 企业级项目开发技能包。面向 vue3-web-temp 及其派生项目，把产品点子快速做成可演示、可验证、可继续演进的 Demo，同时约束代码质量和设计落地。
+
+## 文档分工
+
+| 文档 | 读者 | 内容 |
+|------|------|------|
+| `SKILL.md` | AI | 何时做什么、禁止什么、工作流约束 |
+| `README.md`（本文件） | 维护者 / 人类开发者 | 安装、脚本命令、本地调试、发布 |
+| `references/*.md` | AI（写代码时） | 标准样板、专项细则、硬失败表 |
+| `scripts/modules.json` | 匹配器 + 维护者 | 能力组关键词、同批加载、闸门项 |
 
 ## 这是什么
 
-`/vue3-temp-skill <需求>` → 命中模块 → 按约定生成 → `code-quality` 闸门。
+`/vue3-temp-skill <需求>` → 项目探查 → 能力路由 → 按约定实现 → `code-quality` 闸门。
 
 - **始终加载** `core-kernel`
-- **按需** `project-inventory`（addon / 查 Re* / 装依赖）
-- **精简模板启用 addon** `addon-enable`（装包后逐文件恢复配置，非自动）
+- **按需** `project-inventory`（查依赖 / 装包 / 查 Re* 名录）
+- **按需** `addon-enable` — 只有目标项目确实存在排除项、占位插件或缺失接线时才读
 - **生成后闸门** `code-quality`：清单 + `pnpm lint:fix` + `pnpm type-check` + 结果块
-- 复用仓库已有封装；选型表指定库勿擅自替换；addon 精确版本见 inventory 第九节
+- **设计交接** 有 `design-handoff/v1` 时读 `design-handoff`，落地后用 `handoff.mjs` 做轻量校验
 
 ## 使用方式
 
@@ -28,13 +37,64 @@ Vue 3 企业级中后台项目开发规范技能包 — 按团队规范生成代
 
 ## 模块一览
 
-| 类型 | 模块 |
+| 类型 | 能力组 |
 |------|------|
 | 始终 | core-kernel |
 | 闸门 | code-quality |
-| 按需资产 | project-inventory、**addon-enable** |
-| 标准业务 | http-api、crud-pages、detail-page、data-writeback、permission-auth、layout-theme、design-system、design-handoff、design-verify、icons、feedback-loading、base-code-dict、api-check、ui-components |
-| 专项 | form-advanced、table-vxe、tree-table、chart-echarts、file-management、download-export、rich-text、graph-relation、workflow-bpmn、flowchart-g6、data-mapping、websocket-realtime、mobile-h5、wechat-js、verify-captcha、qrcode-barcode、feedback-ui、seamless-scroll、particles、data-compare、data-screen、directives-advanced |
+| 高频 | page-crud、page-detail、data-service、forms、access、design-implementation、shared-ui |
+| 专项 | table-advanced、visualization、workflow、files-and-editors、realtime-and-mobile、data-compare、i18n |
+| 工程 | project-setup（project-inventory + addon-enable） |
+
+能力组定义、关键词和参考文件由 `scripts/modules.json` 维护。
+
+## 维护者：扩展能力组
+
+新增能力时先判断能否并入已有组；确需扩展时编辑 `scripts/modules.json`（关键词、`load` 映射），再运行 `npm run validate` 校验。
+
+## 脚本与 npm 命令
+
+### 运行时（AI / 本地调试）
+
+| 脚本 | 职责 |
+|------|------|
+| `scripts/match.py` | 能力路由器：输入需求，输出 JSON（`load_files`、同批加载、闸门项） |
+| `scripts/handoff.mjs` | 设计交接：`init` 校验 JSON 并建 session，`check` 校验关键接线 |
+
+**匹配器调用（本地环境）：**
+
+```bash
+# Windows 优先
+py -3 scripts/match.py "客户列表查询跳转详情" --json
+
+# 通用
+python scripts/match.py "客户列表查询跳转详情" --json
+python scripts/match.py --batch   # 15 个典型场景回归
+```
+
+**npm 封装：**
+
+```bash
+npm run match          # python scripts/match.py
+npm run match:batch    # 批量回归
+npm run handoff:init   # node scripts/handoff.mjs init（需追加 --project 等参数）
+npm run handoff:check  # node scripts/handoff.mjs check
+```
+
+### 维护者（不随技能安装分发）
+
+| 脚本 / 命令 | 职责 |
+|-------------|------|
+| `scripts/validate.mjs` / `npm run validate` | 结构校验：frontmatter、路由引用、交叉引用 |
+| `scripts/check.mjs` / `npm run check` | 发布前检查：validate + match 批量回归 |
+| `scripts/cli.mjs` | 统一入口：`--validate` / `--route` / `--list` |
+| `npm run release` | 先 check，再升版本、提交、发布 npm |
+
+```bash
+node scripts/cli.mjs --list
+node scripts/cli.mjs --route "客户列表跳转详情"
+node scripts/cli.mjs --validate
+npm run check
+```
 
 ## 安装
 
@@ -44,6 +104,8 @@ Node.js >= 22.12.0
 npx @qilitt-mickey/vue3-temp-skill@latest install all
 ```
 
+安装器只复制 AI 运行时文件：`match.py`、`modules.json`、`handoff.mjs`。validate / check / cli 留在技能包仓库供维护使用。
+
 | 目标 | 说明 |
 |------|------|
 | 个人 Skill 目录 | 安装器写入当前 AI 环境支持的 Skill 目录 |
@@ -51,13 +113,31 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 
 具体路径因 AI 环境而异，安装完成后以安装器输出为准。
 
-## 生成工作流（AI）
+### 设计落地（可选）
+
+handoff JSON 可以来自对话、临时文件或管道。状态默认保存在用户级状态目录，**不在业务项目创建 `.handoff/`**：
+
+- 默认路径：`~/.workbuddy/state/vue3-temp-skill/<项目哈希>/handoff.json`
+- Windows 示例：`%USERPROFILE%\.workbuddy\state\vue3-temp-skill\<项目哈希>\handoff.json`
+
+```bash
+# 动手前：校验 JSON 规格并建立 session
+node scripts/handoff.mjs init  --project ./my-vue-app --file C:/temp/handoff.json
+
+# 落地后：确认关键接线存在
+node scripts/handoff.mjs check --project ./my-vue-app --require-session
+```
+
+也支持显式指定状态目录（适合 CI 或多工作区）：追加 `--state-dir <项目外状态目录>`。
+
+通过 npm 包 CLI：
+
+```bash
+npx @qilitt-mickey/vue3-temp-skill handoff init  --project ./my-vue-app --file C:/temp/handoff.json
+npx @qilitt-mickey/vue3-temp-skill handoff check --project ./my-vue-app --require-session
+```
 
-1. 解析需求 → 命中功能模块  
-2. 读 `core-kernel` + 命中模块；addon 时加读 inventory + **`addon-enable`**；设计交接块时加读 `design-handoff`  
-3. 缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 逐文件恢复配置**  
-4. 复用仓库 Re*/Hook/utils；按模块示例生成落盘  
-5. 执行 `code-quality` → 输出审查结果块 + 变更说明  
+`handoff.mjs` 只做两件事：确认 JSON 规格完整，确认目标项目存在落地所需关键接线。它不统计改动文件数量，也不要求全项目遍历。
 
 ## 与模版的关系
 
@@ -70,8 +150,8 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 | 本包 `references/` | AI + 开发者 | **标准样板**、专项细则、addon 安装表 |
 | 本包 `addon-enable.md` | AI + 开发者 | **出厂已删依赖的逐文件恢复代码** |
 
-- 模板仓库：布局壳 + core 依赖 + `Re*` 源码（addon 组件默认不参与类型检查直至安装依赖）
-- **标准样板**：在本包 `references/`，不在模板 `views/`
-- 壳层以当前项目源码为准；规范与安装表以本包为准
-- HTTP：`axios@1.19.0` 固定版本，仅经 `@/utils/http`
+- 模板仓库：布局壳 + `Re*` 源码 + 多种已接线能力；具体依赖和构建状态以目标项目当前源码为准
+- **标准样板**：在本包 `references/`；模板 `views/` 主要用于确认真实接线，不直接复制演示文案
+- 壳层、组件和 API 以当前项目源码为准；规范文档只补充实现方法
+- HTTP：仅经 `@/utils/http`；版本以目标项目 `package.json` 和锁文件为准
 - **设计协同**：定制 UI 由**设计技能**出稿（含 `design-handoff/v1` JSON）→ 本 Skill 工程落地；不引入其他设计 Skill

package/SKILL.md

@@ -1,263 +1,117 @@
 ---
 name: "vue3-temp-skill"
-description: "Vue 3 企业级中后台项目开发规范技能包。用户通过 /vue3-temp-skill 命令描述需求，AI 自动匹配对应规范模块生成代码，并在生成后自动执行代码质量审查。"
+description: "Vue 3 企业级项目开发技能。面向 vue3-web-temp 及其派生项目，帮助产品经理和前端快速把点子做成可演示、可验证、可继续演进的 Demo；同时约束真实模板复用、代码质量和设计交接落地。"
 scope: project
-tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, component, api, permission, mobile, code-review, compare]
+agent_created: true
+tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-quality]
 ---
 
-# Vue 3 项目开发规范技能包
+# Vue 3 项目开发技能
 
-执行顺序：运行 `python scripts/match.py "<需求>"` 获取精确匹配 → 按 `load_files` 读参考文件 → 生成 → 按 `quality_gates` 检查 → 执行 `code-quality` → 回复含审查结果块。
+## 目标
 
-> **模块路由优先用脚本**：`python scripts/match.py "需求描述"` 输出 JSON，含命中模块、同批加载、闸门项、加载文件清单。AI 按此结果加载文件，不自行推理匹配。无 Python 环境时回退至下方路由表手动匹配。
+把产品点子快速落到真实 Vue 3 项目中，先形成客户可看的完整 Demo，再保留后续正式开发所需的代码边界。页面可以使用 mock 和最小数据，但不得使用模板演示噪音、虚构项目能力或堆叠无法维护的代码。
 
-### 脚本工具
+## 触发方式
 
-| 命令 | 用途 |
-|------|------|
-| `python scripts/match.py "<需求>"` | **运行时匹配器**（AI 调用）：输出命中模块、同批加载、闸门项、文件清单 |
-| `python scripts/match.py --batch` | 批量测试 15 个典型场景 |
-| `npm run check` | **发布前全量检查**（5 项任一失败即中断） |
-| `npm run validate` | 结构校验：frontmatter、路由表一致性、孤立模块、交叉引用 |
-| `npm run audit` | 命中精度审计：关键词重叠、盲区、模块评分、边界冲突 |
-| `npm run content` | 内容可用性审计：样板完整性、Must-do 清单 |
-| `npm run deps` | 依赖图分析：断链、循环依赖、引用热度 |
-| `npm run match:batch` | 批量测试（npm 封装） |
-| `node scripts/cli.mjs --list` | 列出所有可用命令 |
-
-> `npm run release` 会自动先执行全量检查，通过后才升版本、提交、发布。
-
-## 术语约定
-
-全文统一使用下表术语；不得使用「黄金样板 / 强制完整样板 / 抗略读 / 默记 / 真相源」等表述。
-
-| 统一术语 | 含义 | 禁止使用 |
-|----------|------|----------|
-| 标准样板 | 模块内完整代码样板，命中即整段落盘 | 黄金样板、强制完整样板 |
-| 完整性守则 | 全模块通用的防浅读规则 | 抗略读 |
-| 速查约定 | 高频写法的快速指引 | 默记 |
-| 权威性优先级 | 实现方式选取顺序：仓库封装 > 本 Skill 示例 > 通用 Vue 习惯 | 真相源 |
-| 回退至 | 缺档取值动作（如「缺档 → 回退至 default」） | 缺档场景的「落到」 |
-| 未命中模块 | 需求无对应专项模块时的路由结果 | 「兜底」指代路由结果 |
-
-## 模版约定
-
-- 面向由 **vue3-web-temp** 脚手架搭出的业务项目（目录名/安装路径因人而异，以当前工作区为准）
-- **文档分工**：人类读模板 `README.md`；AI 读模板 `AGENTS.md` + 本 Skill；样板与细则在本包 `references/`
-- **设计协同**：定制 UI 由**设计技能**出稿（含 `design-handoff/v1` JSON）→ 本 Skill 工程落地；不引入其他设计 Skill
-- **精简出厂**：模板 `views/` 仅保留登录/首页等壳页面；**业务标准样板**在本包 `references/`（如 `crud-pages`、`detail-page`）
-- **依赖分层**：`package.json` 仅 **core**；**addon** 默认不装；缺包时装依赖后须按 `addon-enable.md` **逐文件恢复配置**（非自动）
-- 壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
-- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` 逐文件修改清单（含 1:1 还原要求 F1-F14 / P1-P7）+ `design-verify.md` 还原度验证
-- **设计优先级**：当设计技能产出（`design-handoff/v1` JSON）存在时，视觉层面（布局/间距/圆角/阴影/色彩/组件结构）以设计技能产出为准，本技能出厂默认值按设计产出替换。详见下方「设计优先级与 handoff 强制执行」段
-
-## 使用方式
-
-```
+```text
 /vue3-temp-skill <自然语言需求>
 ```
 
-## 项目优先
-
-1. 先读 `references/core-kernel.md`
-2. 复用仓库已有 `Re*` / Hook / utils；选型表指定库勿擅自替换
-3. 按命中模块内**标准样板**整段编写（禁止只抄 API 签名、丢掉 meta/配套段落）
-4. 无对应能力 → 标注「待确认」，未经同意不引入新依赖
-5. 权威性优先级：`仓库已有封装` > `本 Skill 示例` > 通用 Vue 习惯
-6. 命中 addon / 缺依赖：读 `project-inventory` 第九/十节 + **`addon-enable.md`**（逐文件恢复代码）；精确版本安装，禁止 `@latest`
-
-## 完整性守则（全模块强制）
-
-按需模块 ≠ 可浅读。命中即须落到该文件的**标准样板 / Must-do**，生成后靠 `code-quality` 硬失败表兜底。
-
-1. **样板字段默认写出**：示例里写明的 `activePath` / `keepAlive` / `roles` / `responseType: "blob"` 等不得改成 `//` 注释再当可选项；仅业务明确不需要时才删除
-2. **关联能力同批落盘**：列表→详情 = `crud-pages` + `detail-page` 三件套；有 API = 同步 `http-api`；有删除 = 确认框；有编辑回显 = `Object.assign`
-3. **Hook ≠ 壳层自动**：`toDetail` 写 tag；侧栏高亮 / keepAlive 靠路由 meta；`http` 加解密靠环境开关，不靠单请求配置
-4. **大范围交付仍须逐模块核对硬失败表**，禁止以 lint 通过代替硬失败表逐项核对
-
-## 设计落地（handoff）
-
-设计技能每次产出时**始终自动附加 `design-handoff/v1` JSON**。本技能检测到 JSON 后**强制加载** `references/design-handoff.md`，按 C/T/F/Co/S/P 六步全流程执行（配置→令牌→框架→共享组件→样式→页面），**任一步跳过 = 硬失败**。执行完毕后**强制加载** `references/design-verify.md` 逐项验证还原度（区域级 + 逐属性 CSS 校验）。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。用户无需提及「JSON」或「handoff」——这是两技能间的自动协议。完整规则与逐项清单见 `design-handoff.md`，验证流程见 `design-verify.md`。
+典型需求：
+
+- 开发客户管理列表，支持搜索、分页、编辑和详情
+- 做一个有设计感的订单仪表盘，沿用设计 handoff
+- 给现有 Demo 增加附件上传、导出或审批流
+- 把一个页面从 mock 改成真实 API
+
+## 运行时只保留三件事
+
+1. **项目探查**：读取目标项目的 `package.json`、路由、页面、`Re*` 组件、Hooks、API 和样式；以源码事实为准。
+2. **能力路由**：运行 `scripts/match.py "需求" --json`，**仅**按输出中的 `load_files` 阅读 reference；禁止自行展开全部 `references/`。无 Python 时按下方能力组表手动匹配。
+3. **质量闸门**：代码完成后读取 `references/code-quality.md`，执行清单和项目命令；有设计 handoff 时完成交接检查（init → 改代码 → check exit 0）。
+
+## 能力组路由
+
+| 能力组 | 覆盖内容 | 主要参考文件 |
+|---|---|---|
+| `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` |
+| `design-implementation` | 设计 handoff、主题、布局、组件样式 | `design-handoff.md`、`design-system.md`、`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` |
 
-### 项目级模式 vs 单页模式
-
-通过 JSON 的 `meta.transformScope` 字段自动识别改造范围：
-
-| 模式 | 触发条件 | 执行范围 | 关键规则 |
-|------|---------|---------|---------|
-| **单页模式**（默认） | `transformScope: "single-page"` 或未设置 | C/T/F/Co/S + 单个页面 P 步骤 | 只改造当前对话涉及的页面，框架/共享组件若已改造则跳过 |
-| **项目级模式** | `transformScope: "project"` | C/T/F/Co/S（全局一次） + **全页面遍历改造** | 先扫描全部路由，构建页面清单，逐页面执行 P 步骤，全部完成后做全量校验 |
-
-**项目级模式核心规则**：
-1. 先扫描 `src/router/modules/` 所有路由文件，构建页面清单
-2. C/T/F/Co/S 是全局的，只执行一次（框架 + 共享组件）
-3. 逐页面执行 P1-P7，每页标记 `status: completed`
-4. 单次对话改不完时，输出进度 + 待改造页面清单，用户说「继续」时从断点恢复
-5. **禁止在未完成全部页面前声称任务完成**——必须明确告知进度和剩余页面
-
-### 设计概念 → 项目组件映射
-
-设计 skill 定义了"表格工具栏""操作列""导航栏"等设计概念，本技能通过映射表自动找到项目中对应的组件进行修改。映射表见 `design-handoff.md` 第八章（共享组件级落地）。共享组件在 Co 步骤（F 步骤之后、S 步骤之前）统一修改，**一处修改，全局生效**，不需要在每个页面重复处理。
-
-### 设计产出落盘范围
-
-设计落地时，所有修改只落在 `src/`、`public/`、`platform-config.json` 等业务代码中：
-- ✅ 设计规范读取**设计技能**的 `references/` 文件，不另存到项目
-- ✅ 设计产出 HTML 仅在对话中作为参考对照，**不写入项目文件**
-- ❌ 不得把设计 HTML / 规范文档写入项目内非业务目录
-
-违反此规则即硬失败。
-
-## 模块路由表
+## 工作流
 
-### 始终加载
+### 1. 识别目标和范围
 
-| 模块 | 文件 |
-|------|------|
-| **core-kernel** | `references/core-kernel.md` |
+- 确认目标项目根目录；没有明确目标时先询问，不在技能仓库里写业务代码。
+- 判断是 Demo 验证、功能增量还是正式业务开发。
+- 判断是否有设计稿或 `design-handoff/v1` JSON。没有时保留目标项目当前初始化视觉；有时按设计要求落地，不让开发技能自行设计。
 
-### 按需加载
+### 2. 读取事实
 
-| 时机 | 文件 |
-|------|------|
-| addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
-| **启用精简模板已删的 addon（装包 + 改配置）** | `references/addon-enable.md`（与功能模块同读） |
-| 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（逐文件修改清单）+ `design-verify.md`（还原度验证）+ `design-system.md`（项目设计系统说明） |
-| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-handoff.md` 1:1 还原要求（F1-F14 / P1-P7） |
+- 先读 `references/core-kernel.md`。
+- 运行 `scripts/match.py "需求" --json`，按 `load_files` 阅读。
+- 读取目标项目当前 `package.json` 和锁文件；不要根据“core/addon”标签猜依赖是否存在。
+- 扫描已有 `Re*`、Hooks、`src/api`、路由和相关页面；已有封装优先于技能示例。
 
-### 标准业务面
+### 3. 实现闭环
 
-| 模块 | 关键词 |
-|------|--------|
-| **http-api** | 接口、http、加密、API、请求、响应、axios |
-| **crud-pages** | 列表、表格、查询、管理、CRUD、新增、行编辑、操作列、行操作、分页、筛选、批量、排序 |
-| **detail-page** | 详情、编辑页、查看页、新开路由、toDetail、activePath、showLink、顶部 tag、跳转 |
-| **data-writeback** | 回显、回填、回写、useFormCheck、编辑数据 |
-| **permission-auth** | 权限、v-auth、roles、ReAuth、按钮权限、页面权限、角色可见 |
-| **layout-theme** | 布局、主题、暗黑、`--vts-*`、UnoCSS、夜间模式、换肤、侧栏、标签页、面包屑 |
-| **design-system** | 设计规范、UI 规范、按 XX 规范适配、design-tokens、主题色系、令牌体系、暗色模式 |
-| **icons** | 图标、svg-icon、Iconify、ReIconPicker、菜单图标、icon |
-| **feedback-loading** | message、loading、确认框、提示、加载、操作反馈、骨架屏 |
-| **base-code-dict** | 字典、baseCode、码表、下拉字典、数据字典 |
-| **api-check** | 联调、mock、契约、对接后端、接口核对 |
-| **i18n-localization** | 国际化、多语言、i18n、vue-i18n、locale、语言切换、语言包、useI18n、ReLanguageSwitch |
-| **auth-pages** | 登录、注册、忘记密码、重置密码、认证、auth、login、register、signup、forgot-password、找回密码（**设计自由，仅规范流程**） |
-| **ui-components** | 新建 Re*、type.ts、组件目录；**用法见各功能模块**（本文件仅索引） |
+- 页面、路由、API、类型、mock 和共享组件按一个业务闭环实现。
+- 列表使用 `useTableSearch`、`ReTableBar`、`RePagination`；有独立详情时同步完成 `useDetail` 与路由 meta。
+- HTTP 只经过 `@/utils/http`，响应按项目实际 `Result<T>` 约定处理。
+- Demo 可以最小化数据和接口，但目录、类型、命名和组件边界要能承接后续开发。
+- 新依赖先检查目标项目；缺失时说明精确版本、原因和构建接线，确认后再安装。
+- 只有目标项目确实存在排除项、占位插件或缺失接线时，才读取 `addon-enable.md` 恢复配置。
 
-### 专项能力包
+### 4. 设计交接
 
-| 模块 | 关键词 |
-|------|--------|
-| **tree-table** | 树表、ReTreeLine、handleTree、树形、树状、层级表格、组织架构、部门树 |
-| **table-vxe** | vxe、高性能表格、虚拟滚动、虚拟表格、大数据表格、单元格编辑 |
-| **form-advanced** | 弹窗、对话框、抽屉、ReDialog、ReDialogResize、锚点、卡片选择、地址解析、ReSelectQuery、级联、远程搜索、下拉选择、高级表单、步骤条、折叠面板、穿梭框、分步表单、联动、动态表单、日历、时间选择、日期选择、拖动、拖拽排序 |
-| **data-compare** | v-compare、变更汇总、变更对比、数据对比、字段对比、高亮变更 |
-| **file-management** | 附件、ReAttachment、ReFileViewer、预览、上传、文件上传、图片上传、断点续传、分片上传、打印、截图、视频播放、音频 |
-| **download-export** | 导出、excel、blob、下载文件、下载、导出Excel |
-| **rich-text** | 富文本、wangeditor、ReRichText、编辑器、Markdown |
-| **chart-echarts** | echarts、图表、ReEchart、折线图、柱状图、饼图、统计图、雷达图、散点图、热力图、趋势图、地图、甘特图 |
-| **data-screen** | 大屏、dataScreen、数据大屏、看板、数据看板、仪表盘、全屏可视化 |
-| **graph-relation** | 图谱、relation-graph、关系图、知识图谱、关系网络 |
-| **workflow-bpmn** | bpmn、流程审批、审批流、工作流、审批流程 |
-| **flowchart-g6** | g6、流程图、拓扑图、antv、自定义流程图、流程设计 |
-| **data-mapping** | jsplumb、字段映射、连线映射、数据映射 |
-| **websocket-realtime** | websocket、ws、实时、消息推送、实时推送、在线状态 |
-| **mobile-h5** | 移动端、H5、vant、vconsole、手机 |
-| **wechat-js** | 微信、weixin、wechat、js-sdk |
-| **verify-captcha** | 验证码、滑块、短信验证、拖拽验证、图片验证码 |
-| **qrcode-barcode** | 二维码、条形码、扫码 |
-| **feedback-ui** | 通知栏、水印、时间轴、打字机、展示组件、空状态 |
-| **seamless-scroll** | 无缝滚动、跑马灯、marquee、滚动公告 |
-| **particles** | 粒子、tsparticles、登录背景粒子、粒子动画 |
-| **directives-advanced** | 一键复制、复制、标题字号自适应、字号自适应 → `v-copy` / `v-auto-font` |
+- 发现 `$schema: design-handoff/v1` 后，读取 `references/design-handoff.md`。
+- 动手前初始化 handoff session；设计决定视觉、结构和交互意图，本技能只负责映射到真实模板并保留业务逻辑。
+- 只修改 handoff 明确覆盖的文件和页面；不为通过检查虚构修改、不强制全项目遍历。
+- 项目级视觉改造只有在用户明确要求时才执行；单页 Demo 默认只处理当前页面及必要共享组件。
 
-### 匹配规则
+### 5. 验证与交付
 
-1. 单模块 → 该模块 + `core-kernel`；结束后执行 `code-quality`
-2. 多模块 → 同时加载（例：客户列表 = `crud-pages` + `permission-auth` + `http-api`）
-3. 未命中模块 → 仅 `core-kernel`，向用户确认是否专项
-4. 默认不改 `vite.config.ts` / `build/**`；**例外**：按 `addon-enable.md` 恢复 FileViewer / VantResolver / Vconsole 等占位插件时允许改 `build/plugins/*`
-5. 效果匹配：
-   - 启用 echarts / vant / file-viewer / 富文本等已删 addon → 功能模块 + **`addon-enable`**
-   - 弹窗、对话框、抽屉 → `form-advanced`
-   - 远程搜索下拉、级联选择 → `form-advanced`
-   - 步骤条、分步表单、穿梭框、折叠面板、动态表单 → `form-advanced`
-   - 日历、时间选择、日期选择、联动 → `form-advanced`
-   - 点一下复制 → `directives-advanced`（`v-copy`）
-   - 标题字跟着宽度变小 → `directives-advanced`（`v-auto-font`）
-   - 角色可见、按钮权限 → `permission-auth`
-   - 变更对比、数据对比 → `data-compare`
-   - 导出、下载文件 → `download-export`
-   - 菜单/本地图标 → `icons`
-   - 粒子背景 → `particles`
-   - 树形列表、层级表格、组织架构、部门树 → `tree-table`
-   - 虚拟滚动、大数据表格 → `table-vxe`
-   - 骨架屏 → `feedback-loading`
-   - 空状态 → `feedback-ui`
-   - 标签页、面包屑 → `layout-theme`
-   - 批量操作、表格排序 → `crud-pages`
-   - 趋势图、地图、甘特图 → `chart-echarts`
-   - 附件上传、断点续传 → `file-management`
-   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system`（项目设计系统说明）+ `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`（逐文件修改清单，含 C/T/F/Co/S/P 全流程 + 共享组件映射 + 项目级模式）+ `design-verify.md`（还原度验证）
-   - 列表→独立详情/编辑页 → `crud-pages` + `detail-page`
-   - 图表（折线/柱状/饼图） → `chart-echarts`
-   - 数据大屏、看板 → `data-screen`
-   - 实时推送、在线状态 → `websocket-realtime`
-   - BPMN 流程、审批、工作流 → `workflow-bpmn`
-   - 自定义流程图、流程设计、拓扑 → `flowchart-g6`
-   - 国际化、多语言、i18n、语言切换 → `i18n-localization`
-   - 注册、忘记密码、重置密码、认证 → `auth-pages`（设计自由，仅规范流程；含验证码 → `verify-captcha`）
-   - 打印、截图 → `file-management`（ReFileViewer）
-   - 视频播放、音频 → `file-management`（ReFileViewer 文件预览）
-6. 独立详情路由：跳转与 meta 见 `detail-page`（`toDetail` / `showLink` / `activePath` / `initToDetail`）
+- 对照 `references/code-quality.md` 检查类型、组件复用、API、路由、权限、安全、异常反馈、响应式和可演进性。
+- 在目标项目执行 `pnpm lint:fix`、`pnpm type-check`；改动构建配置时再执行 `pnpm build`。
+- 有 handoff 时：落地前 init session，完成后 handoff check（`--require-session`）须 **exit 0** 才能声称设计落地完成。
+- 最终说明：命中能力组、修改文件、功能验证、设计落地范围、命令结果、未解决问题和下一步。
 
-## 速查约定（细则见对应模块）
+## 项目事实优先级
 
-- HTTP：`import { http } from '@/utils/http'`；方法跟后端（允许 GET/POST）；`Result<T>`；`VITE_API_BASE_URL` → `http-api`
-- 列表：`onSearch` / `reset` + 标准样板 → `crud-pages`
-- 独立详情：`toDetail` **不能替代** `activePath` / `keepAlive` / `moreTags`；三件套 → `detail-page`
-- 权限：`meta.roles` + `v-auth`/`ReAuth` → `permission-auth`
-- 不二次挂 Layout；`script setup` + `defineOptions({ name })`；`$t('中文')`；样式契约 → `core-kernel`
+`目标项目当前源码` > `目标项目 package.json / 锁文件` > `本 Skill reference` > `通用 Vue 习惯`。
 
-## 工作流
+## 默认禁止
 
-1. **需求分析**：列出功能模块 ID（不含 `code-quality`）
-2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；**检测 design-handoff/v1 JSON 是否存在** — 若存在，强制加载 `design-handoff`（逐文件修改清单，含 C/T/F/Co/S/P 全流程 + 共享组件映射 + 项目级模式）+ `design-verify`（还原度验证）+ `design-system.md`，并按设计产出优先级执行
-3. **模式判断**：有 handoff JSON 时，读取 `meta.transformScope`：
-   - `project` → 进入**项目级模式**：先扫描 `src/router/modules/` 构建页面清单，输出「待改造页面清单」供用户确认
-   - `single-page` 或未设置 → 单页模式，仅处理当前页面
-4. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
-5. **探查**：复用仓库 `Re*` / Hook / utils；**项目级模式下**，探查所有共享组件（ReTableBar / ReTableOperate / RePagination 等）的当前实现
-6. **生成**：
-   - 单页模式：C/T/F/Co/S + 当前页面 P 步骤
-   - 项目级模式：C/T/F/Co/S（全局一次） + 逐页面执行 P 步骤，标记完成状态
-   - **有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
-7. **设计还原度验证**：有 handoff JSON 时必须执行，加载 `design-verify.md` 按其流程逐区域逐元素对照设计规范验证（10.1-10.7 区域级 + 10.8 逐属性 CSS 校验），输出「设计还原度验证报告」+「逐属性 CSS 校验报告」，未通过项必须修正
-8. **功能完整性核查**：有 handoff JSON 时必须执行，按 `design-handoff.md` 第十一章逐项核查功能是否正常（框架/共享组件/页面），样式改造不得破坏原有功能，发现问题立即修正
-9. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（项目级模式需校验全页面完成度 + 共享组件修改 + 设计还原度 + 功能完整性）
-10. **输出**：变更说明（含已改配置文件列表）+ 设计还原度验证报告 + 逐属性 CSS 校验报告 + 功能完整性核查报告 + 待确认项；**项目级模式未全部完成时，输出进度 + 待改造页面清单 + 「继续」指令提示**
+- 不在页面内直接使用 `axios` / `fetch`，不虚构 API 前缀。
+- 不二次挂载 `Layout`，不把模板演示页原样当业务页面。
+- 不使用裸 `v-if` 代替权限指令，不使用不可信 `v-html`。
+- 不为了视觉效果引入未经确认的新 UI 框架或图表库。
+- 不把 lint 通过当成业务闭环完成，也不把 handoff 文件修改数量当成设计质量证明。
 
-### 最终回复结构
+## 最终回复格式
 
 ```markdown
-## 命中模块
-- <功能模块…>（缺包时含 addon-enable）
-
-## 代码质量审查
-- 闸门：已执行 code-quality（生成后）
-- 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表→详情(如适用) / 列表布局(如适用) / 风格 / addon启用(如适用) → 通过 | 已修正：…
-- 硬失败：无 | 已拦截并修正：…
-- handoff 落地（如有 JSON）：C/T/F/Co/S/P 全流程已执行 → 通过 | 未完成项：…（硬失败）
-- 还原度验证（如有 JSON）：design-verify.md 区域级 + 逐属性校验已执行 → 通过 | 偏差项：…（已修正 / 待确认）
-- 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
-- 待确认：…
+## 命中能力组
+- page-crud / data-service / ...
 
 ## 变更说明
-- …
-- 移除/新增元素（如有 handoff）：按设计输出移除了…/新增了…（供用户确认）
+- `src/...`：...
+
+## 验证结果
+- 功能：...
+- 设计交接：未涉及 | 已按 handoff 落地 ...
+- `pnpm lint:fix`：通过 | 失败（原因）
+- `pnpm type-check`：通过 | 失败（原因）
+- 待确认：...
 ```
-
-## 文件索引
-
-`references/<模块名>.md` 与路由表 ID 一一对应。依赖安装见 `project-inventory.md` 第九节；**精简模板配置恢复见 `addon-enable.md`**。

package/bin/cli.js

@@ -21,13 +21,15 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const { execFileSync, execSync } = require("child_process");
 
 const HOME = os.homedir();
 // bin/cli.js → 上一级即包根目录
 const SKILL_DIR = path.resolve(__dirname, "..");
 const SKILL_NAME = "vue3-temp-skill";
 const TRACK_FILE = path.join(HOME, ".vue3-temp-skill.json");
+// 只复制 AI 运行时真正需要的文件；validate/check/cli 属于作者侧工具，不随技能分发
+const RUNTIME_SCRIPT_FILES = ["match.py", "modules.json", "handoff.mjs"];
 
 // ============================================================
 // 版本
@@ -251,6 +253,15 @@ function installSkills(targetKey, projectDir) {
     copyDir(refsSrc, path.join(dest, "references"));
   }
 
+  const scriptsSrc = path.join(SKILL_DIR, "scripts");
+  if (fs.existsSync(scriptsSrc)) {
+    const scriptsDest = path.join(dest, "scripts");
+    ensureDir(scriptsDest);
+    for (const file of RUNTIME_SCRIPT_FILES) {
+      copyFile(path.join(scriptsSrc, file), path.join(scriptsDest, file));
+    }
+  }
+
   // Cursor：清理旧版 rules/*.mdc，避免与 skills 重复
   if (cfg.legacyRulesFile) {
     const legacy = cfg.legacyRulesFile(projectDir);
@@ -337,6 +348,8 @@ ${bold("命令:")}
   update [target]     更新已安装的技能（默认更新全部已安装目标）
   uninstall [target]  卸载技能（默认卸载全部已安装目标）
   list                查看已安装的目标和版本
+  handoff init        校验 handoff JSON 规格，在用户级目录建立会话（不污染业务项目）
+  handoff check       确认目标项目存在设计落地所需的关键接线
 
 ${bold("目标 (target):")}
   cursor       → Cursor          ~/.cursor/skills/
@@ -370,8 +383,9 @@ ${bold("示例:")}
   ${dim("# 查看已安装情况")}
   npx @qilitt-mickey/vue3-temp-skill list
 
-  ${dim("# 卸载")}
-  npx @qilitt-mickey/vue3-temp-skill uninstall cursor
+  ${dim("# 设计交接（在业务项目根目录执行）")}
+  npx @qilitt-mickey/vue3-temp-skill handoff init --project ./my-app --file C:/temp/handoff.json
+  npx @qilitt-mickey/vue3-temp-skill handoff check --project ./my-app --require-session
 `);
 }
 
@@ -591,6 +605,36 @@ function cmdList() {
   }
 }
 
+function cmdHandoff(sub, args, projectDir) {
+  const proj = projectDir || process.cwd();
+  const fileIdx = args.indexOf("--file");
+  const handoffFile = fileIdx !== -1 ? path.resolve(args[fileIdx + 1]) : null;
+  const stateDirIdx = args.indexOf("--state-dir");
+  const stateDir = stateDirIdx !== -1 ? path.resolve(args[stateDirIdx + 1]) : null;
+  const requireSession = args.includes("--require-session");
+  const scriptDir = path.join(SKILL_DIR, "scripts");
+
+  if (sub !== "init" && sub !== "check") {
+    console.error(red("✗ handoff 子命令: init | check"));
+    console.error(dim("  handoff init  --project <dir> --file <handoff.json> [--state-dir <dir>]"));
+    console.error(dim("  handoff check --project <dir> [--state-dir <dir>] [--require-session]"));
+    console.error(dim("  默认状态目录见 README.md「设计落地」"));
+    process.exit(1);
+  }
+
+  const script = path.join(scriptDir, "handoff.mjs");
+  const childArgs = [script, sub, "--project", proj];
+  if (sub === "init" && handoffFile) childArgs.push("--file", handoffFile);
+  if (stateDir) childArgs.push("--state-dir", stateDir);
+  if (sub === "check" && requireSession) childArgs.push("--require-session");
+
+  try {
+    execFileSync(process.execPath, childArgs, { stdio: "inherit" });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+}
+
 // ============================================================
 // 入口
 // ============================================================
@@ -626,6 +670,9 @@ function main() {
     case "list":
       cmdList();
       break;
+    case "handoff":
+      cmdHandoff(target, args.slice(2), projectDir);
+      break;
     default:
       // 兼容旧用法：直接传 target 名当作 install
       if (TARGETS[command] || command === "all") {