@qilitt-mickey/vue3-temp-skill 1.1.32 → 1.1.34

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"];
 
 // ============================================================
 // 版本
@@ -253,7 +255,11 @@ function installSkills(targetKey, projectDir) {
 
   const scriptsSrc = path.join(SKILL_DIR, "scripts");
   if (fs.existsSync(scriptsSrc)) {
-    copyDir(scriptsSrc, path.join(dest, "scripts"));
+    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 重复
@@ -342,8 +348,8 @@ ${bold("命令:")}
   update [target]     更新已安装的技能（默认更新全部已安装目标）
   uninstall [target]  卸载技能（默认卸载全部已安装目标）
   list                查看已安装的目标和版本
-  handoff init        初始化业务项目 .handoff/session.json
-  handoff check       设计落地管控闸门（步骤 + JSON 规格）
+  handoff init        校验 handoff JSON 规格，在用户级目录建立会话（不污染业务项目）
+  handoff check       确认目标项目存在设计落地所需的关键接线
 
 ${bold("目标 (target):")}
   cursor       → Cursor          ~/.cursor/skills/
@@ -377,8 +383,8 @@ ${bold("示例:")}
   ${dim("# 查看已安装情况")}
   npx @qilitt-mickey/vue3-temp-skill list
 
-  ${dim("# 设计落地管控（在业务项目根目录执行）")}
-  npx @qilitt-mickey/vue3-temp-skill handoff init --project ./my-app --file .handoff/handoff.json
+  ${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
 `);
 }
@@ -602,40 +608,31 @@ function cmdList() {
 function cmdHandoff(sub, args, projectDir) {
   const proj = projectDir || process.cwd();
   const fileIdx = args.indexOf("--file");
-  const handoffFile =
-    fileIdx !== -1 ? path.resolve(proj, args[fileIdx + 1]) : path.join(proj, ".handoff", "handoff.json");
+  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") {
-    const script = path.join(scriptDir, "handoff-session-init.mjs");
-    try {
-      execSync(`"${process.execPath}" "${script}" --project "${proj}" --file "${handoffFile}"`, {
-        stdio: "inherit",
-      });
-    } catch (e) {
-      process.exit(e.status ?? 1);
-    }
-    return;
+  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);
   }
 
-  if (sub === "check") {
-    const script = path.join(scriptDir, "handoff-governance.mjs");
-    const extra = requireSession ? " --require-session" : "";
-    try {
-      execSync(`"${process.execPath}" "${script}" --project "${proj}"${extra}`, {
-        stdio: "inherit",
-      });
-    } catch (e) {
-      process.exit(e.status ?? 1);
-    }
-    return;
-  }
+  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");
 
-  console.error(red("✗ handoff 子命令: init | check"));
-  console.error(dim("  handoff init  --project <dir> [--file .handoff/handoff.json]"));
-  console.error(dim("  handoff check --project <dir> [--require-session]"));
-  process.exit(1);
+  try {
+    execFileSync(process.execPath, childArgs, { stdio: "inherit" });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
 }
 
 // ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.32",
+  "version": "1.1.34",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"
@@ -23,21 +23,13 @@
     "release": "node release.js",
     "release:minor": "node release.js minor",
     "release:major": "node release.js major",
-    "check": "scripts\\check.cmd",
-    "prepack": "scripts\\check.cmd",
+    "check": "node scripts/check.mjs",
+    "prepack": "node scripts/check.mjs",
     "validate": "node scripts/validate.mjs",
-    "audit": "node scripts/ai-match-audit.mjs",
-    "content": "node scripts/ai-content-audit.mjs",
-    "deps": "node scripts/analyze-deps.mjs",
-    "deps:hot": "node scripts/analyze-deps.mjs --hot",
-    "deps:mermaid": "node scripts/analyze-deps.mjs --mermaid",
     "match": "python scripts/match.py",
     "match:batch": "python scripts/match.py --batch",
-    "gen:index": "node scripts/generate-index.mjs",
-    "gen:index:write": "node scripts/generate-index.mjs --write",
-    "scaffold": "node scripts/scaffold-module.mjs",
-    "handoff:init": "node scripts/handoff-session-init.mjs",
-    "handoff:check": "node scripts/handoff-governance.mjs",
+    "handoff:init": "node scripts/handoff.mjs init",
+    "handoff:check": "node scripts/handoff.mjs check",
     "postpublish": "echo 'Published @qilitt-mickey/vue3-temp-skill to npmjs.org'"
   },
   "keywords": [

package/references/code-quality.md

@@ -13,7 +13,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 
 1. 重读本文件
 2. 列出本轮改动路径，对照下方清单；**硬失败表命中则先改代码再继续**
-3. **有 handoff session 时**（`.handoff/session.json` 存在）：必跑 `vue3-temp-skill handoff check --project <业务项目> --require-session` → **exit 0 才能声称设计落地完成**（见 `handoff-governance.md`）
+3. **有 handoff 时**：动手前 init session；落地完成后 handoff check（`--require-session`）须 **exit 0** 才能声称设计落地完成
 4. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`
 5. 失败则修代码并重跑，直至通过或写明阻塞
 6. 最终回复追加：
@@ -24,7 +24,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - 改动文件：`path/a`、`path/b`、…
 - 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表→详情 ✅或N/A / 列表布局 ✅或N/A / 风格 ✅
 - 硬失败：无 | 已拦截并修正：…
-- handoff 管控（如有 session）：`vue3-temp-skill handoff check` → 通过 | 失败项：…
+- handoff 检查（如有）：通过 | 失败项：…
 - 已修正：…（无则写「无」）
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
@@ -48,122 +48,22 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 | 新菜单路由 | 父级无 `icon` 或业务页二次挂 `Layout` | `icons` + `core-kernel` |
 | 列表查询区 `el-form` / 查询按钮 | 写了 `size="small"`（紧凑主题用户未要求） | 不写 size，用 default=`--control-height` |
 | 本轮新增 addon 并引用对应 `Re*` / Vant / 微信 | 已装包但 `tsconfig exclude` 仍含该路径，或 `addon-enable` 要求的 build/src 未改 | 按 **`addon-enable.md`** 对应章节恢复后重跑 type-check |
+| `element-plus.scss` / `sidebar.scss` 等样式消费层 | `var(--font-size-*)` 用于 `line-height` / `height` 等非字号属性 | 查 TSB：`classifyToken` + `PROPERTY_FORBIDDEN`；`line-height` → `--line-height` 或 `--el-menu-item-height` |
 | `element-plus.scss` 内视觉规则（shadow/hover/transition） | 出现非令牌引用的裸 hex / px / rgba 值 | 全部改为 `var()` 引用令牌 |
 | 视觉规则新增 | `dark.scss` 缺少对应暗色覆盖 | 每条新规则在 `html.dark` 内有对应覆盖 |
 
-### 设计模式专项检查（设计 Skill 产出或指定设计规范时强制执行）
-
-> 任一项未通过 = 硬失败，必须修正后重新生成。
-> 对照 `design-handoff.md` 硬失败表 + 元素自查隐藏清单逐项核查。
-
-#### 配置层（4 项）
-
-- [ ] `platform-config.json` 的 `EpThemeColor` 与设计主色一致
-- [ ] `Theme` 与侧栏风格对应（`dark-gradient` → `default`）
-- [ ] `ShowModel` 与页签风格一致
-- [ ] `Version` 已自增
-
-#### 令牌层（5 项）
-
-- [ ] `--primary-0` ~ `--primary-9` 完整 10 级色阶
-- [ ] 几何尺寸令牌与设计一致（header/tabs/sidebar/margin）
-- [ ] 控件高度令牌与设计一致（`--control-height*`）
-- [ ] 视觉令牌完整（shadow/transition/transform）
-- [ ] 无硬编码 hex 值出现在令牌以外的位置
-
-#### 框架层（7 项）
-
-- [ ] 顶栏元素组成与设计一致（不多不少：设置/通知/全屏/搜索/面包屑）
-- [ ] 语言切换为内联文字（非下拉框）
-- [ ] 侧栏底部折叠按钮设计无则已隐藏（折叠按钮移至顶部）
-- [ ] 菜单 hover 折叠功能设计无则已禁用
-- [ ] 菜单激活态：品牌色极浅底 + 右侧强调条（非纯蓝底白字）
-- [ ] 页签横线居中，关闭按钮行为正确
-- [ ] Logo 区：品牌色方块 + 白字首字（非默认彩色图标）
-
-#### 样式层（6 项）
-
-- [ ] 卡片 hover 有浮起效果（transform + shadow）
-- [ ] 按钮 hover 有上浮效果（位移 + 阴影）
-- [ ] 输入框聚焦有光环（品牌色边框 + 外阴影）
-- [ ] 表格行 hover 有品牌色底
-- [ ] 展开收起按钮 hover 文字不变淡（加深为品牌色）
-- [ ] 所有视觉规则在暗色模式下有对应覆盖
-
-#### 共享组件层（10 项）
-
-- [ ] ReTableBar 工具栏按钮样式符合设计规范（刷新/密度/列设置：icon 16px、按钮 32px、分隔线 1px）
-- [ ] ReTableBar 工具栏左右布局正确（左批量操作、右工具按钮）
-- [ ] ReTableBar 标题区：设计模式下无多余「展示列表」标题文字
-- [ ] ReTableOperate 操作列：纯文字链接，无图标，按钮间有 1px×14px 竖分隔线
-- [ ] ReTableOperate「更多」按钮：带 10px 下拉箭头，下拉菜单样式正确
-- [ ] ReTableOperate 折叠阈值：limit 默认 3，列宽动态计算（`resolveOperateColumnWidth`）
-- [ ] RePagination 分页样式符合设计规范（两段式布局、可选 10/20/50 条）
-- [ ] 侧栏菜单激活态：实色品牌底 + 左侧 3px 指示条 + 白色文字（非 8% 透明底）
-- [ ] 顶栏折叠按钮：垂直居中，40×40px；设置按钮：已隐藏/删除
-- [ ] 内容区模块分割线：各区域间距与设计规范一致（标题 20px / 筛选 20px / 工具栏 20px 8px / 表格 0 20px / 分页 8px 20px 20px）
-
-#### 页面层（11 项）
-
-- [ ] 页面有标题区（`.vts-page-header`：标题 + 描述 + 操作按钮）
-- [ ] 筛选区有容器感（`.vts-filter-area`：背景 + 底部分割线）
-- [ ] 操作栏存在（`.vts-action-bar`：批量操作 + 工具按钮）
-- [ ] 表格区有包裹感（`.vts-table-area`）
-- [ ] 状态标签样式符合规范（filled/outlined/solid 按列分配）
-- [ ] 操作列统一为文字链接 + "更多"下拉（ReTableOperate）
-- [ ] 设计中未体现的元素已隐藏/移除（对照元素自查隐藏清单 4.1-4.4）
-- [ ] 所有样式值引用 CSS 变量，无裸 hex/px 值
-- [ ] 页面无「展示列表」等多余标题文字
-- [ ] 页面无「左侧按钮可以增加多个」「增加一行可编辑数据」等示例按钮
-- [ ] 操作列按钮无多余图标，仅保留文字 + 竖分隔线
-
-#### 项目级完成性（transformScope=project 时额外执行）
-
-- [ ] 已扫描全部路由模块（`src/router/modules/`），页面清单完整
-- [ ] 所有列表页均已按设计规范改造（base/tree/vxe-table 等）
-- [ ] 所有表单页均已按设计规范改造
-- [ ] 所有详情页均已按设计规范改造
-- [ ] 工作台/仪表盘/数据大屏等其他页面均已按设计规范改造
-- [ ] 共享组件（ReTableBar/ReTableOperate/RePagination）已全局修改
-- [ ] 框架组件（navbar/sidebar/tabs/app-main）已全局修改
-- [ ] 元素隐藏清单已逐项检查并处理（顶栏/侧栏/列表/共享组件 四类）
-- [ ] 无遗漏页面（对照路由清单逐一核对）
-- [ ] 所有页面的多余元素（「展示列表」「左侧按钮...」等）均已清除
-
-#### 设计落地管控（有 `.handoff/session.json` 时必须执行）
-
-> 详见 `references/handoff-governance.md`。lint/type-check **不能**代替本段。
-
-- [ ] 动手前已 `handoff-session-init`，`.handoff/session.json` 含完整 handoff + baseline
-- [ ] handoff JSON 含 `structureRequirements` + `interactionSpecs`
-- [ ] C/T/F/Co/S/P 全流程已执行（`handoff-step-check` 通过）
-- [ ] 代码与当次 JSON 一致（`handoff-spec-check` 通过）
-- [ ] 已落盘 `.handoff/verify-report.json`（`overallPass: true`）
-- [ ] **`vue3-temp-skill handoff check --project <业务项目> --require-session` → exit 0**
-
-#### 设计还原度验证（有 handoff JSON 时必须执行）
-
-> 验证依据：设计 skill 的规范文件（design-tokens.md / unified-framework.md / list-page.md / component-spec.md）
-> 验证方法：代码级对照——读取设计规范预期值 → 检查项目代码实际值 → 比对是否一致
-> 验证顺序：框架层 → 页面层 → 共享组件层 → 细节项 → 元素清理
-
-- [ ] **框架层还原度**：顶栏高度/元素/折叠位置、侧栏宽度/背景/激活态、页签高度/激活态、内容区背景/padding，共 10 项已逐项对照
-- [ ] **页面层还原度**：卡片阴影圆角、标题区字号/padding、筛选区背景/分隔线、工具栏布局/按钮、表格表头/行高/hover、操作列样式、分页布局、模块分割线/间距，共 12 项已逐项对照
-- [ ] **共享组件还原度**：ReTableBar（按钮样式/布局/分页集成）、ReTableOperate（文字链接/分隔线/更多箭头/折叠逻辑）、RePagination（样式/布局），共 10 项已逐项对照
-- [ ] **核心组件还原度**：按钮（高度/圆角/主色三态）、输入框（高度/圆角/focus 光环）、Tag（5 种状态色）、下拉菜单、空状态，已逐项对照
-- [ ] **细节项还原度**：图标大小 16px、分隔线 #F0F0F0、hover 文字加深不变浅、行高正确、字重正确、圆角统一、阴影自然、更多按钮有箭头、操作列有竖分隔线、页签下划线居中、操作列 sticky、选择列 48px、状态标签颜色对应、卡片有阴影，共 15 项已逐项检查
-- [ ] **令牌溯源检查**：颜色/尺寸/间距均通过 CSS 变量传递，变量值与 design-tokens.md 一致，无裸 hex/px 值
-- [ ] **元素清理检查**：设置按钮、展示列表标题、示例按钮、操作列多余图标等已全部移除
-- [ ] **已输出「设计还原度验证报告」**（格式见 `design-verify.md` 10.7），包含整体还原度、各层通过率、偏差项及修正方案
-- [ ] **CSS 冲突检测已执行**（`design-verify.md` 10.7.5）：选择器重复扫描完成，无意冲突已消除，导入顺序已验证，新增 CSS 文件已注册
-- [ ] **已输出「CSS 冲突检测报告」**（格式见 `design-verify.md` 10.7.5.5），包含扫描范围、重复选择器明细、导入顺序验证结果
-- [ ] **逐属性 CSS 校验已执行**（`design-verify.md` 10.8）：从设计源文件提取 CSS 属性清单，逐条比对项目代码，不一致项已修正并回读校验通过
-- [ ] **已输出「逐属性 CSS 校验报告」**（格式见 `design-verify.md` 10.8.5），包含校验范围、偏差明细、待确认项
-- [ ] **设计落盘范围**：设计产出 HTML 未写入项目文件，设计规范未另存到非业务目录，所有修改只在 src/ 等业务代码中
-- [ ] **功能完整性核查**：样式改造后原有功能全部正常（框架层/共享组件层/页面层均已逐项核查，无按钮失效、事件丢失、数据绑定断裂等功能回归问题）
-- [ ] **已输出「功能完整性核查报告」**（格式见 design-handoff.md 第十一章 11.7），包含整体通过率、各层核查结果、发现的问题及修正方案
-
-> ⚠️ 硬约束：设计还原度验证未通过的项，必须修正后重新验证，直至全部通过。禁止带着未修正的偏差项进入后续环节。
+### 设计 handoff（有 `design-handoff/v1` JSON 时）
+
+> 对照 `design-handoff.md` **第八章**硬失败表；**第九章**落地清单；**design-verify.md** 还原度验证；**design-handoff.md 第十一章**功能完整性核查。lint/type-check 不能代替上述检查。
+
+- [ ] 动手前已 init handoff session
+- [ ] handoff JSON 含 `meta` / `shell` / `geometry` / `tokens`；有 `structureRequirements` 时同时有 `interactionSpecs`
+- [ ] 只改了 handoff 明确覆盖的文件和页面，没有为凑数虚构修改
+- [ ] 业务逻辑在视觉改造后未被破坏（按钮、事件、数据绑定仍可用）
+- [ ] 第九章各层清单已逐项核对
+- [ ] design-verify 还原度验证已通过（有偏差须修正）
+- [ ] 第十一章功能完整性核查已通过
+- [ ] 落地完成后 handoff check（`--require-session`）→ **exit 0**
 
 ## 选型与硬约束
 
@@ -219,8 +119,8 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 
 ### design-system（命中时）
 
-- [ ] 有设计 Skill 产出时已读 `design-handoff.md` 逐文件修改清单并执行
-- [ ] 设计还原检查对照设计 Skill 的 `project-implementation-protocol.md` 检查清单
+- [ ] 有设计 handoff 时已读 `design-handoff.md` 并按 C/T/F/Co/S/P 执行
+- [ ] 设计还原对照 `design-verify.md` 与当次 JSON
 - [ ] 令牌 / `platform-config.json` / 侧栏主题三处一致
 - [ ] **无**设计落地时未改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
 - [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档回退至 default；查询区不写 size

package/references/core-kernel.md

@@ -171,5 +171,8 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 | 详情跳转 | `detail-page` |
 | 主题布局 | `layout-theme` |
 | 设计规范适配 | `design-system` + 有产出时 `design-handoff` + `design-verify` |
-| 版本/安装 | `project-inventory` |
+| 依赖盘点 / 装包 / addon 接线 | `project-inventory` + `addon-enable` |
+| 多语言 | `i18n-localization` |
 | 生成后审查 | `code-quality` |
+
+能力组与关键词的完整定义见 `scripts/modules.json`，运行时由 `scripts/match.py` 路由。

package/references/design-handoff.md

@@ -22,41 +22,21 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 - ✅ 所有修改只动 `src/`、`public/`、`platform-config.json` 等业务代码
 - ❌ 不得把设计 HTML / 规范文档写入项目内非业务目录
 
-## 双轨
+## 双轨与模式
 
 | 场景 | 行为 |
 |------|------|
-| **未调用设计 / 无 handoff** | 保持模板出厂（主色 `#409EFF`、`Theme: light`=白侧栏、`ShowModel: chrome`、margin 8） |
-| **有 design-handoff/v1 JSON** | 按本清单 5 步 51 项逐项执行；只改主色不改 Theme/Version = **落地失败** |
+| 无 handoff | 保持模板出厂视觉 |
+| 有 `design-handoff/v1` | 按本清单 C/T/F/Co/S/P 执行；只改主色不改 Theme/Version = 落地失败 |
 
-## 两种调用场景
+**改造范围**（`meta.transformScope`）：
 
-> 以下「设计技能」泛指任何能输出 `design-handoff/v1` JSON 的设计类技能，不限定具体技能名称。
-
-| 场景 | 触发时机 | 执行范围 | 关键规则 |
-|------|---------|---------|---------|
-| **先开发 → 后调设计** | 业务页面已用 vue3-temp-skill 开发完成，用户不满意效果，调设计技能输出 handoff JSON | C/T/F/S/P **全 5 步** | 页面组件保留业务逻辑（API/路由/状态/事件），**重写 `<template>` 和样式**，使页面结构与设计输出一致 |
-| **先设计 → 后开发** | 新项目先调设计技能输出 handoff JSON，再调 vue3-temp-skill | 先执行 C/T/F/S（配置/令牌/框架/样式），后续业务开发时 P 步骤随页面生成同步落地 | 后续每个新页面开发都须遵循已落地设计规范，不以出厂样板覆盖设计输出 |
-
-**两种场景均须执行完整 C/T/F/Co/S/P 流程，不可跳步。**
-
-### 项目级模式 vs 单页模式
-
-通过 `meta.transformScope` 字段识别改造范围：
-
-| 模式 | transformScope 值 | 执行逻辑 |
-|------|-------------------|---------|
-| **单页模式**（默认） | `"single-page"` 或未设置 | 仅处理当前页面，C/T/F/Co/S 若已落地则跳过 |
-| **项目级模式** | `"project"` | 全局执行 C/T/F/Co/S（一次），然后遍历所有路由页面逐一改造 |
-
-**项目级模式执行要点**：
-1. **Step 0 — 页面清单初始化**：扫描 `src/router/modules/` 所有路由文件，按页面类型（list/form/detail/dashboard 等）分组，构建待改造页面清单
-2. **Step 1-5 — 全局层落地**：C/T/F/Co/S 五步是项目全局的，只执行一次（配置/令牌/框架/共享组件/样式）
-3. **Step 6 — 全页面遍历**：按页面清单逐页执行 P1-P7，每页标记完成状态
-4. **断点续改**：单次对话未完成全部页面时，记录已完成页面，用户说「继续」时从下一个 pending 页面开始
-5. **完成性校验**：全部页面完成后，执行项目级完成性校验（见第九章末）
+| 模式 | 条件 | 范围 |
+|------|------|------|
+| 单页（默认） | 未设置或 `single-page` | 当前页面 + 必要共享组件；C/T/F/Co/S 已落地则跳过 |
+| 项目级 | `project` | 全局 C/T/F/Co/S 一次，再遍历全部路由页；未完成前不得声称完成 |
 
-> ⚠️ 项目级模式下，**禁止在未完成全部页面前声称任务完成**。必须明确告知：已完成 X/Y 页面，剩余 Z 页面待改造，说「继续」即可继续。
+**先开发后设计 / 先设计后开发**：均须完整 C/T/F/Co/S/P；页面保留业务逻辑，重写 template 与样式以对齐设计结构。
 
 ## 设计为准原则
 
@@ -68,21 +48,13 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 4. **设计输出未覆盖的区域 → 保持项目已有实现**，仅同步令牌（色彩/字体/圆角等）
 5. **隐藏/移除功能性元素时**：在回复中明确列出被移除的元素，供用户确认是否需要补回
 
-## 触发（自动，无需用户提及 JSON）
-
-> 设计技能每次产出时**始终自动附加 `design-handoff/v1` JSON**。
-> 本技能检测到 JSON 存在 → 自动触发完整 C/T/F/S/P 流程，用户无需提及「JSON」「handoff」「桥接」等技术词。
+## 触发
 
-**触发条件**（满足任一）：
-
-1. 会话中存在 `design-handoff/v1` JSON（设计技能自动产出）
-2. 会话中存在设计技能的 HTML 产出 + 用户要求按设计结果适配工程代码
-
-⚠️ 触发后 **必须执行完整 C/T/F/S/P 五步**，禁止只改主色或只改令牌。
+会话中存在 `design-handoff/v1` JSON，或存在设计 HTML 且用户要求按设计适配工程代码 → 自动执行完整 C/T/F/Co/S/P，禁止只改主色或只改令牌。
 
 ## 规范识别回执（动手前必出）
 
-> 动手前须 `handoff-session-init` 写入 `.handoff/session.json`（见 `handoff-governance.md`）。
+> 动手前先 init handoff session（保存当次 JSON 规格）；不在业务项目创建 `.handoff/`。
 
 ```markdown
 ## 规范识别回执
@@ -151,7 +123,7 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| F1 | `structureRequirements.frameworkShell.header` | `src/layout/components/navbar/index.vue` | 顶栏组成：折叠按钮（左）+ 语言切换 + 功能图标组 + 分割线 + 欢迎区 + 头像（右）。**设计中未体现的元素必须移除**（设置/通知/全屏/搜索/面包屑等） | 元素与设计完全一致，不多不少 |
+| F1 | `structureRequirements.frameworkShell.header` | `src/layout/components/lay-navbar/index.vue` | 顶栏组成：折叠按钮（左）+ 语言切换 + 功能图标组 + 分割线 + 欢迎区 + 头像（右）。**设计中未体现的元素必须移除**（设置/通知/全屏/搜索/面包屑等） | 元素与设计完全一致，不多不少 |
 | F2 | `interactionSpecs.languageSwitch` | navbar/ 语言切换组件 | **改为内联文字**（中 / EN），竖线分隔。激活态品牌色文字，非激活次要色。**禁止下拉框** | 语言切换为内联文字 |
 | F3 | `structureRequirements.frameworkShell.headerLayout` | navbar/index.vue | flex 两端对齐：左侧折叠按钮，右侧功能组 | 布局与设计一致 |
 | F4 | `interactionSpecs.menuActive` → 头像区 | navbar/ 欢迎区 | 悬停态：头像微浮起 + 欢迎文字变品牌色 | hover 效果与设计一致 |
@@ -408,8 +380,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 1. 读取 JSON 的 `visual` + `interactionSpecs` 字段
 2. 按「区域映射表」逐项将 JSON 值写入 `element-plus.scss` 对应 CSS 选择器
 3. **所有值引用 `design-tokens.scss` 令牌变量**，不硬编码
-4. JSON 无值时回退 `design-tokens.md` 默认值（设计技能令牌库）
-5. `dark.scss` 对以上规则逐条提供暗色覆盖
+4. **令牌语义绑定（TSB）**：引用前按 `design-system.md`「TSB」— `classifyToken(--name)` + `PROPERTY_FORBIDDEN[property]`；禁止为凑变量跨域（如 `line-height: var(--font-size-base)`）
+5. JSON 无值时回退 `design-tokens.md` 默认值（设计技能令牌库）
+6. `dark.scss` 对以上规则逐条提供暗色覆盖
 
 ### 5.2 原则（硬约束，不随设计变化而失效）
 
@@ -500,28 +473,28 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ## 八、硬失败（任一项命中 = 落地失败，必须修正）
 
-> **硬失败分两类**（详见 `handoff-governance.md`）：
-> - **流程类**：步骤跳过、无 session、无 verify 报告、lint 代替管控 — **与设计无关，永远检查**
+> **硬失败分两类**：
+> - **流程类**：无 session、跳过关键步骤、lint 代替交接检查 — **与设计无关，永远检查**
 > - **规格类**：代码与**当次** handoff JSON 的 `structureRequirements` / `interactionSpecs` 不一致 — **随设计变，不写死在本表**
+>
+> 单页 Demo 默认只处理当前页面及必要共享组件；只有用户明确要求项目级改造时才遍历全部路由。
 
-### 8.1 流程硬失败（机器可拦）
+### 8.1 流程硬失败
 
 | 类别 | 条件 | 处理 |
 |------|------|------|
-| 管控 | 有 handoff 但未 `handoff-session-init` | 硬失败：先写 `.handoff/session.json` |
-| 管控 | `handoff-step-check` 任一步（C/T/F/Co/S）文件无 diff | 硬失败：补全该步骤，禁止跳过 Co |
-| 管控 | 只改 C/T 未改 Co 共享组件即声称完成 | 硬失败：执行 Co1-Co12 |
-| 管控 | 未执行 `vue3-temp-skill handoff check --require-session` | 硬失败：机器闸门 exit 0 后才能完成 |
-| 管控 | 以 `lint:fix` / `type-check` 通过代替 handoff 管控 | 硬失败：二者是必要非充分条件 |
-| 管控 | 有 handoff 但未落盘 `.handoff/verify-report.json` | 硬失败：design-verify 报告必须落盘 |
-| 项目级 | 项目级模式下未扫描全部路由即开始改造 | 硬失败：先完成 Step 0 页面清单初始化 |
+| 流程 | 有 handoff 但未 init session | 硬失败：先建立 session |
+| 流程 | 只改令牌未改共享组件即声称完成 | 硬失败：补齐共享组件改造 |
+| 流程 | 未执行 handoff check（`--require-session`）或未 exit 0 | 硬失败：检查通过后才能完成 |
+| 流程 | 以 `lint:fix` / `type-check` 通过代替 handoff 检查 | 硬失败：二者是必要非充分条件 |
+| 流程 | 为通过检查而修改 handoff 未覆盖的文件 | 硬失败：撤销无关修改 |
+| 项目级 | 项目级模式下未扫描全部路由即开始改造 | 硬失败：先完成页面清单 |
 | 项目级 | 项目级模式下未完成全部页面即声称完成 | 硬失败：必须告知进度和剩余页面 |
 | 设计落地 | 设计 HTML / 规范文档被写入项目非业务目录 | 硬失败：撤销，设计修改只落在 src/ 等业务代码 |
 | 功能回归 | 样式改造后原有功能被破坏 | 硬失败：修复后重新验证 |
-| 逐属性校验 | 10.8 发现不一致且未修复 | 硬失败：零差异后才能声明完成 |
-| CSS 冲突 | 10.7.5 未执行就进 10.8 | 硬失败：先冲突检测 |
+| 逐属性校验 | 发现不一致且未修复 | 硬失败：零差异后才能声明完成 |
 
-### 8.2 规格硬失败（读当次 JSON + spec-check）
+### 8.2 规格硬失败（读当次 JSON 逐项对照）
 
 | 类别 | 条件 | 处理 |
 |------|------|------|
@@ -555,10 +528,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ---
 
-## 九、落地完整性校验（code-quality 额外执行）
+## 九、落地完整性校验
 
-> 当 `design-handoff/v1` JSON 存在时，`code-quality` 必须额外执行以下校验。
-> 任一项未通过 = 硬失败，必须修正后重新生成。
+> `code-quality` 闸门引用本节。任一项未通过 = 硬失败。
 
 ### 配置层
 
@@ -588,6 +560,7 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 - [ ] `element-plus.scss` 视觉规则按 S1 区域映射表逐项写入，值来自 JSON `visual` / `interactionSpecs`
 - [ ] `dark.scss` 对以上视觉规则有暗色覆盖
+- [ ] 样式消费层无跨域 `var()` 引用（见 `design-system.md` TSB 规则）
 
 ### 共享组件层
 
@@ -632,11 +605,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ---
 
-## 十、设计还原度验证（加载 design-verify.md）
+## 十、设计还原度验证
 
-> C/T/F/Co/S/P 执行完毕后，加载 `references/design-verify.md` 按其流程逐项验证。
-> 验证流程包含：区域级验证(10.1-10.7) → 逐属性CSS校验(10.8) → 设计变更同步(10.9)。
-> **未通过项必须修正后才能进入第十一章功能完整性核查。**
+> C/T/F/Co/S/P 完成后读 `references/design-verify.md` 逐项验证；通过后进入第十一章功能核查。
 
 ---
 

package/references/design-system.md

@@ -63,6 +63,31 @@ tags: [design-system, design-tokens, element-plus, theme, css-variables, dark-mo
 | `--el-menu-item-height` | 侧栏/垂直菜单项、子菜单 title | 顶栏、页签栏 |
 | `--vts-tabs-height` / `--tabs-height` | 多标签页签栏 | 菜单、表单控件 |
 
+## 令牌语义绑定（TSB · Token Semantic Binding）
+
+> **统一识别规则**：`--token` 后缀/前缀 → 令牌域；CSS 属性 → 禁止域列表（`PROPERTY_FORBIDDEN`）。只拦截**已知跨域错误**，不靠穷举合法组合。
+
+### 识别算法（AI 与机器共用）
+
+1. **令牌域** = `classifyToken(--name)`：先看后缀（`-height` / `-width` / `font-size` / `-padding` …），再看前缀表
+2. **属性禁止域** = `PROPERTY_FORBIDDEN[property]`：命中则硬失败
+3. 未列入禁止域的引用默认放行（含 theme-bridge、box-shadow 用色值变量等）
+
+### 高频禁止（摘要）
+
+| CSS 属性 | 禁止令牌域 | 典型错误 |
+|---|---|---|
+| `line-height` | typography-size | `var(--font-size-base)` |
+| `height` / `min-height` | typography-size、typography-flow | 用字号变量填高度 |
+| `font-size` | geometry-height、spacing、color | 用 `--control-height` 填字号 |
+| `padding` / `margin` | typography-size | 用 `--font-size-*` 填间距 |
+
+### 纪律
+
+1. **先语义、后数值** — 看变量定义的是什么，不是数字是否一样
+2. **能 inherit 不重复** — 父级已设行高/高度时，子元素用 `inherit`
+3. **新增 `--*` 先归类** — 按下方后缀/前缀规则归入正确令牌域，禁止在业务样式里混用语义
+
 壳层令牌接线关系（值来源：上游设计产出 > 用户/预设 > 模版默认）：
 
 | 模版令牌 | 执行层消费位置 |

package/references/design-verify.md

@@ -7,9 +7,7 @@ tags: [handoff, verify, css-audit, design-sync, hard-fail]
 
 # 设计还原度验证
 
-> 本文件由 `design-handoff.md` 执行流程第 8 步加载。
-> C/T/F/Co/S/P 改造执行完毕后，按本文件逐项验证还原度。
-> **未通过项必须修正后才能进入功能完整性核查和 code-quality 闸门。**
+> C/T/F/Co/S/P 完成后按本文件逐项验证；未通过项修正后再做 `design-handoff.md` 第十一章功能核查。
 
 ## 验证流程总览
 
@@ -37,18 +35,20 @@ tags: [handoff, verify, css-audit, design-sync, hard-fail]
 
 > **验证真相源顺序**：当次 handoff JSON（`structureRequirements` + `interactionSpecs`）> 设计 HTML > 设计 skill references > 模板出厂默认值。
 
-1. 读取 `.handoff/session.json` 或会话中的 handoff JSON
+1. 读取 session 或会话中的 handoff JSON（业务项目不创建 `.handoff/`）
 2. 从 JSON 展开**本次验证清单**（非 skill 静态表）：
    - `frameworkShell.header` → 顶栏元素逐项
    - `interactionSpecs.tabsActive.underline` → 决定是否检查下划线
    - `interactionSpecs.tableOperate.showIcon` → 决定是否禁止 icon
    - `interactionSpecs.menuActive.*` → 侧栏激活 inset/通栏/圆角
-3. 执行 `vue3-temp-skill handoff check --project <业务项目> --require-session`（内含 step-check + spec-check）作为机器预检
+3. 执行 handoff check（`--require-session`）作为机器预检，须 **exit 0**
 4. 人工/AI 区域验证（10.2–10.5）对照 JSON 展开项，**禁止**用上一版设计的静态预期
 
 ### 10.0.1 verify-report 落盘
 
-design-verify 完成后必须写入项目 `.handoff/verify-report.json`：
+> 报告是 AI 执行期的内部状态，不作为业务项目交付物；最终回复只汇总结论和待确认偏差。
+
+design-verify 完成后可在 session 状态目录写入 `verify-report.json`（可选）：
 
 ```json
 {