@agile-team/wl-skills-kit 2.8.0 → 2.9.2

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [2.9.2] - 2026-05-17
+
+### Added
+
+- **`doctor-ui` 新增 C_Splitter 残留扫描（standards/14 一致性）**：
+  - 业务代码（`.vue / .ts / .scss / .js`）命中 → `✖ error`，列出文件:行号:片段
+  - 文档/规则（`.md / .mdc`）命中 → `⚠ warn`
+  - 自动豁免：上下文 ±1 行含 `已废弃 / DEPRECATED / 严禁 / 不再需要 / 已迁移 / deprecated`；`C_Splitter/` 组件目录自身豁免
+  - 明细分组打印，单次最多列 60 条，超出汇总"另有 X 处未列出"
+- **`standards/14-layout-containers.md` 扩充**：
+  - §6 lint/codegen 强制项追加 `validate` / `doctor-ui` 命令矩阵
+  - 新增 §7 FAQ（旧页面是否要改、阈值配置、嵌套性能、过渡期保留）
+- **`tests/doctor-ui.test.js`**：4 项新单测覆盖无残留、业务代码命中、豁免词、自身组件豁免
+
+### Notes
+
+- 测试矩阵：cli + lint-skills + doctor-ui + registry + version-tools 合计 **53 测试通过**
+- 升级路径：`npx @agile-team/wl-skills-kit@latest update` 同步 standards/14；CI 增挂 `wl-skills doctor-ui` 即可
+
+## [2.9.1] - 2026-05-17
+
+### Added
+
+- **`validate` 三项新检查**（接 v2.9.0 的 standards/14 落地阻断）：
+  - 🔴 `error`：页面 `index.vue` 出现 `<C_Splitter>` 标签
+  - 🔴 `error`：`index.vue` / `data.ts` 出现 `import C_Splitter`
+  - ℹ `info`：提及 `C_Splitter` 的过时注释（如 `已改为 C_Splitter`、`migrate to C_Splitter`、`TODO ... C_Splitter`）
+- **`scripts/lint-skills.js` 新增规则 8**：扫描 `files/**/*.{vue,ts}`，禁止任何 `<C_Splitter>` 标签或 `import C_Splitter`（仅允许 `files/src/components/global/C_Splitter/index.vue` 自身保留废弃声明）。
+- **`.husky/pre-commit` 接入 `lint-skills`**：维护者侧提交时自动守门，从源头阻止 C_Splitter 回潮。
+
+### Notes
+
+- 实战验证：wl-mdata 现网 28 个页面 0 命中（之前已全量迁移）；故意污染测试用例可精准触发 3 项检查。
+- 兼容性：所有新检查均为加法，未改动既有 validate 规则；下游项目无需调整。
+
+## [2.9.0] - 2026-05-17
+
+### Added
+
+- **`files/.github/standards/14-layout-containers.md`**（新规范，🔴 必遵 + 阻断）：布局容器规范。根因解析 `C_Splitter` 在 `onMounted` 中调用 `slots.default()` 冻结 vnode 快照、导致子树响应式完全失效；明确左右分割只用 `jh-drag-col`（`#left`/`#right`），上下分栈只用 `jh-drag-row`（`#top`/`#bottom`）；附迁移对照表、lint 规则、废弃路线图。
+- **`files/src/components/global/C_Splitter/index.vue`** 加入 `@deprecated` 注释 + 运行时 `console.warn`（同会话仅警告一次），引导改用 `jh-drag-col` / `jh-drag-row`。
+
+### Changed
+
+- **`standards/index.md`**：13 条 → 14 条；任务 A（生成新页面）/ B（修改重构）必读集合纳入 `14`。
+- **`standards/13-platform-components.md`** 与 `copilot-instructions.md`：「左右分割」推荐组件由 `C_Splitter` 改为 `jh-drag-col`；明确 `C_Splitter` 已废弃及根因。
+- **TPL-TREE-LIST.md**：模板示例改为 `<jh-drag-col :leftWidth="220">` + `#left`/`#right` 显式插槽；SCSS 去除 `.my-splitter-container :deep` 残留；顶部加「布局硬约束」段。
+- **TPL-DETAIL-TABS.md**：示例由 `<C_Splitter direction="vertical">` 改为 `<jh-drag-row :topHeight="380">` + `#top`/`#bottom`；移除 `import C_Splitter`。
+- **`page-codegen/SKILL.md`** 与 `templates/_index.md`：TREE_LIST 描述同步至 jh-drag-col；上下分栈描述同步至 jh-drag-row。
+- **`prototype-scan/SKILL.md`**：原型扫描产出物示例与说明同步至 jh-drag-col。
+- **`demo/sale/demo/add-demo/`** 与 **`demo/sale/demo/metallurgical-spec/`**：示例 `<C_Splitter>` 全部迁移到 `<jh-drag-row>`；SCSS 注释、README 文案对齐。
+
+### Notes
+
+- 兼容性：`C_Splitter` 源文件保留但加废弃警告，**不删除**，避免外部业务项目升级时立即报错；下一个 major 版本前再做物理移除评估。
+- 参考案例：`wl-ui-sale` 项目所有左树右表/上下分栈页面（material、materialCategory、transactionType、unit、price-maintain、ContractEditTab 等）均使用 `jh-drag-col` / `jh-drag-row`，未踩 `C_Splitter` 冻 vnode 坑——本次规范固化的正是该实战路径。
+
 ## [2.8.0] - 2026-05-16
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.8.0** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.9.2 ** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.8.0
+ * wl-skills-kit CLI v2.9.2 
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -831,6 +831,17 @@ function scanPageDirs(scanRel) {
       hasEmptyOnClick: /onClick\s*:\s*\(\s*[^)]*\s*\)\s*=>\s*\{\s*\}/.test(
         dataContent,
       ),
+      hasCSplitterTag: /<C_Splitter\b/.test(indexContent),
+      hasCSplitterImport:
+        /from\s+["'][^"']*C_Splitter[^"']*["']/.test(indexContent) ||
+        /from\s+["'][^"']*C_Splitter[^"']*["']/.test(dataContent),
+      staleSplitterComments: (
+        (indexContent.match(/(?:已改为|migrate to|TODO).{0,40}C_Splitter/g) || [])
+          .concat(
+            dataContent.match(/(?:已改为|migrate to|TODO).{0,40}C_Splitter/g) ||
+              [],
+          )
+      ).length,
       apiUrls: Array.from(
         dataContent.matchAll(/:\s*["']([^"']+\/[^"']+)["']/g),
       ).map((m) => m[1]),
@@ -972,6 +983,27 @@ function runValidate() {
         dir: page.dir,
         text: "存在空 onClick: () => {}",
       });
+    if (page.hasCSplitterTag)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "禁用 <C_Splitter>：请改用 jh-drag-col（左右）/ jh-drag-row（上下），详 standards/14-layout-containers.md",
+      });
+    if (page.hasCSplitterImport)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "禁止 import C_Splitter：该组件已废弃（onMounted 冻 vnode 致响应式失效），详 standards/14",
+      });
+    if (page.staleSplitterComments > 0)
+      issues.push({
+        level: "info",
+        dir: page.dir,
+        text:
+          "发现 " +
+          page.staleSplitterComments +
+          " 处提及 C_Splitter 的过时注释，建议清理",
+      });
     if (page.apiConfigCount > 0 && mockFiles.length === 0)
       issues.push({
         level: "warn",
@@ -1074,11 +1106,75 @@ function runDoctorUi() {
   );
   add("renderOps", /renderOps\s*\(/.test(allSource), "操作列需使用 renderOps");
 
+  // —— C_Splitter 残留扫描（standards/14 一致性）——
+  // 业务代码（.vue / .scss / .ts）禁止任何 C_Splitter；文档/规则（.md / .mdc）只允许"废弃说明"句式
+  const EXEMPT_KEYWORDS =
+    /已废弃|DEPRECATED|严禁|不再需要|已迁移|deprecated/i;
+  const splitterFiles = files.filter(
+    (rel) =>
+      /\.(ts|vue|scss|js|tsx|md|mdc)$/.test(rel) &&
+      !rel.startsWith("node_modules/") &&
+      !rel.startsWith("dist/") &&
+      !rel.startsWith(".git/"),
+  );
+  const codeHits = [];
+  const docHits = [];
+  for (const rel of splitterFiles) {
+    if (
+      rel.includes("/C_Splitter/") ||
+      rel.endsWith("/C_Splitter/index.vue") ||
+      rel.endsWith("/C_Splitter/index.scss")
+    )
+      continue; // 组件自身保留（带 deprecation warning）
+    const full = path.join(TARGET_DIR, rel);
+    let content;
+    try {
+      content = fs.readFileSync(full, "utf8");
+    } catch {
+      continue;
+    }
+    if (!/C_Splitter/.test(content)) continue;
+    const lines = content.split(/\r?\n/);
+    lines.forEach((line, idx) => {
+      if (!/C_Splitter/.test(line)) return;
+      // 取上下文 ±1 行做豁免判断
+      const ctx = [lines[idx - 1] || "", line, lines[idx + 1] || ""].join("\n");
+      if (EXEMPT_KEYWORDS.test(ctx)) return;
+      const item = { rel, line: idx + 1, text: line.trim().slice(0, 100) };
+      if (/\.(vue|ts|scss|js|tsx)$/.test(rel)) codeHits.push(item);
+      else docHits.push(item);
+    });
+  }
+  add(
+    "C_Splitter 业务代码残留",
+    codeHits.length === 0,
+    codeHits.length === 0
+      ? "无"
+      : codeHits.length + " 处（详见下方明细，需改 jh-drag-col/-row）",
+  );
+  add(
+    "C_Splitter 文档/规则残留",
+    docHits.length === 0,
+    docHits.length === 0
+      ? "无"
+      : docHits.length + " 处（详见下方明细，建议同步说明）",
+  );
+
   for (const item of checks) {
     console.log(
       "  " + statusIcon(item.ok) + " " + item.name + " — " + item.detail,
     );
   }
+  if (codeHits.length || docHits.length) {
+    console.log("");
+    console.log("  ── C_Splitter 残留明细 ──");
+    for (const h of codeHits.slice(0, 30))
+      console.log("  ✖ " + h.rel + ":" + h.line + "  " + h.text);
+    for (const h of docHits.slice(0, 30))
+      console.log("  ⚠ " + h.rel + ":" + h.line + "  " + h.text);
+    const overflow = codeHits.length + docHits.length - 60;
+    if (overflow > 0) console.log("  … 另有 " + overflow + " 处未列出");
+  }
   const failed = checks.filter((item) => !item.ok).length;
   console.log("");
   console.log(

package/files/.github/copilot-instructions.md

@@ -203,7 +203,7 @@ onMounted(() => select());
 | 部门选择 | jh-dept-picker | @jhlc/jh-ui                      |
 | 文件上传 | jh-file-upload | @jhlc/jh-ui                      |
 | 文本翻译 | jh-text        | @jhlc/jh-ui                      |
-| 左右分割 | C_Splitter     | src/components/global            |
+| 左右分割 | jh-drag-col    | @jhlc/jh-ui (#left/#right slot)  |
 | 树形面板 | C_Tree         | src/components/global            |
 
 ## 组件提取策略

package/files/.github/guides/architecture.md

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.8.0（2026-05-16）
+> **当前版本**：v2.9.2（2026-05-17）
 
 ---
 

package/files/.github/skills/core/page-codegen/SKILL.md

@@ -1065,7 +1065,7 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 | LIST | templates/universal/TPL-LIST.md | 标准查询+工具栏+表格+分页 | mmwr-customer-archive |
 | MASTER_DETAIL | templates/universal/TPL-MASTER-DETAIL.md | jh-drag-row 主从表，双击联动 | ompt-ht-plan-order |
 | TREE_LIST | templates/universal/TPL-TREE-LIST.md | 左侧 C_Tree + 右侧列表 | — |
-| DETAIL_TABS | templates/universal/TPL-DETAIL-TABS.md | C_Splitter 上Tab表单+下子表 | add-demo / domestic-trade-order |
+| DETAIL_TABS | templates/universal/TPL-DETAIL-TABS.md | jh-drag-row 上Tab表单+下子表 | add-demo / domestic-trade-order |
 | FORM_ROUTE | templates/universal/TPL-FORM-ROUTE.md | 复杂表单独立路由（非弹窗） | mmwr-customer-apply-add-form |
 | CHANGE_HISTORY | templates/universal/TPL-CHANGE-HISTORY.md | 左历史时间线+右变更详情 | mmwr-customer-apply-change-history |
 | RECORD_FORM | templates/universal/TPL-RECORD-FORM.md | BaseQuery选主记录+Form+Table无分页 | mmsm-convert-progress |

package/files/.github/skills/core/page-codegen/templates/_index.md

@@ -11,7 +11,7 @@
 | LIST            | `templates/universal/TPL-LIST.md`           | 标准列表页（查询+工具栏+表格+分页）     |
 | FORM_ROUTE      | `templates/universal/TPL-FORM-ROUTE.md`     | 复杂表单独立路由页（多 Tab / 多子表）   |
 | MASTER_DETAIL   | `templates/universal/TPL-MASTER-DETAIL.md`  | 主从表页（jh-drag-row 上下分栏）        |
-| TREE_LIST       | `templates/universal/TPL-TREE-LIST.md`      | 左树右列表页（C_Splitter 布局）         |
+| TREE_LIST       | `templates/universal/TPL-TREE-LIST.md`      | 左树右列表页（jh-drag-col 布局）         |
 | DETAIL_TABS     | `templates/universal/TPL-DETAIL-TABS.md`    | 详情 Tab 页（上方表单 + 下方 Tab 子表） |
 | CHANGE_HISTORY  | `templates/universal/TPL-CHANGE-HISTORY.md` | 变更历史比对页（时间线 + 字段差异）     |
 | RECORD_FORM     | `templates/universal/TPL-RECORD-FORM.md`    | 录入型实绩页（无分页，查询 + 内联表单） |

package/files/.github/skills/core/page-codegen/templates/universal/TPL-DETAIL-TABS.md

@@ -3,15 +3,16 @@
 > 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
 
 > 适用场景：编辑/维护页面，上半区为多 Tab 表单（基本信息/客户信息/其他信息），下半区为子项表格。
-> 布局核心：`C_Splitter direction="vertical"` 垂直分割上下区域。
+> **布局核心**：`jh-drag-row :topHeight="..."` 垂直分割上下区域（严禁 `C_Splitter`，详 standards/14-layout-containers.md）。
 > **参考标杆**：`src/views/sale/demo/add-demo/`、`src/views/sale/demo/domestic-trade-order-mainten/`
 
 #### index.vue
 
 ```vue
 <template>
-  <div class="app-container app-page-container">
-    <C_Splitter direction="vertical">
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-row :topHeight="380">
+      <template #top>
       <!-- 上：表单区 -->
       <el-card shadow="never" class="form-card">
         <!-- 页头工具栏 -->
@@ -66,7 +67,9 @@
           </el-tab-pane>
         </el-tabs>
       </el-card>
+      </template>
 
+      <template #bottom>
       <!-- 下：子项表格区 -->
       <el-card shadow="never" class="items-card">
         <div class="items-section">
@@ -97,13 +100,14 @@
           />
         </div>
       </el-card>
-    </C_Splitter>
+      </template>
+    </jh-drag-row>
   </div>
 </template>
 
 <script setup lang="ts">
 import { onMounted } from "vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// ⚠️ 不再需要 import C_Splitter——jh-drag-row 是 @jhlc/jh-ui 全局注册组件
 import {
   form,
   rules,

package/files/.github/skills/core/page-codegen/templates/universal/TPL-TREE-LIST.md

@@ -1,13 +1,14 @@
 # TREE_LIST：树形+列表
 
 > 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
+> **布局硬约束**：严禁使用 `C_Splitter`（冻vnode导致响应式完全失效），必须用 `jh-drag-col`（详 standards/14-layout-containers.md）。
 
 #### index.vue
 
 ```vue
 <template>
-  <div class="app-container app-page-container">
-    <C_Splitter :left-width="220">
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-col :leftWidth="220">
       <template #left>
         <C_Tree
           :tree-data="treeData"
@@ -40,7 +41,7 @@
           @size-change="select"
         />
       </template>
-    </C_Splitter>
+    </jh-drag-col>
   </div>
 </template>
 
@@ -197,10 +198,8 @@ export function createPage(editModalRef?: any) {
 
 ```scss
 .app-page-container {
-  // C_Splitter 需要父容器撑满高度
-  :deep(.my-splitter-container) {
-    height: 100%;
-  }
+  // jh-drag-col 需要父容器擑满高度
+  height: 100%;
 }
 ```
 

package/files/.github/skills/core/prototype-scan/SKILL.md

@@ -144,7 +144,7 @@ AI 根据提取的信息，内部构建 page-spec JSON（**不输出给用户**
 | --------------- | --------------------- | ------------------------------------------------ |
 | `LIST`          | 查询区 + 表格 + 分页  | BaseQuery + BaseTable + jh-pagination            |
 | `MASTER_DETAIL` | 上方主表 + 下方明细表 | jh-drag-row（需 `.drager_row { height: 100% }`） |
-| `TREE_LIST`     | 左侧树 + 右侧表格     | C_Splitter + C_Tree                              |
+| `TREE_LIST`     | 左侧树 + 右侧表格     | jh-drag-col + C_Tree                              |
 | `FORM_MODAL`    | 弹窗中的表单          | el-dialog + el-form                              |
 | `COMPOSITE`     | 多种组合              | 组合使用                                         |
 
@@ -195,7 +195,7 @@ AI 根据提取的信息，内部构建 page-spec JSON（**不输出给用户**
 | 表格     | BaseTable               | 通过 `columnsDef()` 声明式配置       |
 | 分页     | jh-pagination           | 固定用法，见 copilot-instructions.md |
 | 上下分栏 | jh-drag-row             | 主从表必备，需设 `:top-height`       |
-| 左右分割 | C_Splitter              | 树形+列表必备，设 `:left-width`      |
+| 左右分割 | jh-drag-col             | 树形+列表必备，设 `:leftWidth` + #left/#right slot |
 | 树形面板 | C_Tree                  | 含搜索+Tab 切换                      |
 | 下拉选择 | jh-select               | dict 属性自动加载字典数据            |
 | 日期选择 | jh-date / jh-date-range | 参见 `docs/jh-date.md`               |

package/files/.github/standards/13-platform-components.md

@@ -31,8 +31,8 @@
 | 下拉 / 选择器       | `jh-select` / `jh-picker`                     | ❌ el-select 手写 options    |
 | 只读文本展示        | `jh-text`                                     | ❌ span/div 直接渲染         |
 | 分页                | `jh-pagination`                               | ❌ el-pagination             |
-| 上下分栏            | `jh-drag-row`                                 | ❌ 手动 flex/grid            |
-| 左右分割            | `C_Splitter`                                  | ❌ 手动 flex/grid            |
+| 上下分栏            | `jh-drag-row` (#top/#bottom)                  | ❌ 手动 flex/grid          |
+| 左右分割            | `jh-drag-col` (#left/#right)                  | ❌️ `C_Splitter`（已废弃，onMounted 冻vnode，导致子树响应式完全失效） |
 | 树形面板            | `C_Tree`                                      | ❌ el-tree 手写              |
 | 状态标签            | `C_TagStatus`                                 | ❌ el-tag + 颜色映射         |
 | HTTP 请求           | `getAction/postAction/putAction/deleteAction` | ❌ axios / fetch 直接调用    |

package/files/.github/standards/14-layout-containers.md

@@ -0,0 +1,159 @@
+# 14 — 布局容器规范（C_Splitter 禁用 + jh-drag-col/row 唯一推荐）
+
+> **强制度**：🔴 必遵 + 阻断式（lint 命中即报错）。
+> **背景**：2024 年 12 月一次真实事故，左树右表页面右侧面板永不刷新，最终定位为 `C_Splitter` 在 `onMounted` 中调用 `slots.default()` 冻结 vnode 快照，导致子树所有响应式绑定与父组件 ref 脱钩。
+> **结论**：项目中**禁止再使用 `C_Splitter`**，所有左右/上下分栏一律用 `jh-drag-col` / `jh-drag-row`。
+
+---
+
+## 1. 强制对照
+
+| 场景       | ✅ 必用                                | ❌ 禁用             |
+| ---------- | -------------------------------------- | ------------------- |
+| 左右分栏   | `<jh-drag-col :leftWidth="240">` + `#left` / `#right` slot | `C_Splitter`、`el-aside`+`el-main` 手写 flex |
+| 上下分栏   | `<jh-drag-row :topHeight="240">` + `#top` / `#bottom` slot  | `C_Splitter direction="vertical"`、手写 flex |
+| 嵌套分栏   | 多层 `jh-drag-col` / `jh-drag-row` 直接嵌套 | C_Splitter 嵌套（双倍 vnode 冻结） |
+
+> `@jhlc/jh-ui` 的 `jh-drag-col` / `jh-drag-row` 使用 Vue 原生 `<slot />` 直接渲染，**不缓存 vnode**，子组件响应式与父组件 ref 完全连通。
+
+---
+
+## 2. C_Splitter 为什么必须废弃（根因）
+
+`src/components/global/C_Splitter/index.vue` 内部实现：
+
+```js
+onMounted(() => {
+  const defaultSlots = slots.default ? slots.default() : [];
+  // ...
+  vnodes.value = children;  // 冻结 vnode 列表
+});
+// 模板里
+// <component :is="item" />
+```
+
+**反应链**：
+
+1. `slots.default()` 只在 `onMounted` 执行一次 → 拿到的是**当时**的 vnode 快照
+2. 模板用 `<component :is="item" />` 渲染快照 → 子组件的所有 props/slot props/ref 绑定**永远定格在 mount 那一刻**
+3. 父组件后续修改 ref（`activeModelId.value = "xxx"`）→ 子组件 v-if/v-show/插值**全部失效**
+4. 表现：点击树节点，右侧表格**永远显示初始数据**或空白；vue-devtools 看 ref 已变但 UI 不动
+
+> 这是 Vue 3 slot 渲染模型的本质：`slots.default()` 是一次性的 render function 调用，**不能用 ref 缓存其结果当模板用**。任何"缓存 vnode 数组再 component is 渲染"的写法都有同样的 bug。
+
+---
+
+## 3. 标准用法
+
+### 3.1 左树右表（最常见）
+
+```vue
+<template>
+  <div class="app-container app-page-container" style="height: 100%">
+    <jh-drag-col :leftWidth="240">
+      <template #left>
+        <C_Tree :data="treeData" @node-click="onNodeClick" />
+      </template>
+      <template #right>
+        <BaseQuery ... />
+        <BaseToolbar ... />
+        <BaseTable v-if="activeModelId" ... />
+      </template>
+    </jh-drag-col>
+  </div>
+</template>
+```
+
+✅ `v-if`、`ref` 赋值、所有响应式都能正常驱动右侧重渲染。
+
+### 3.2 上表下详情（master-detail）
+
+```vue
+<jh-drag-row :topHeight="320">
+  <template #top>
+    <BaseTable ... @row-click="onRowClick" />
+  </template>
+  <template #bottom>
+    <DetailPanel v-if="currentRow" :data="currentRow" />
+  </template>
+</jh-drag-row>
+```
+
+### 3.3 上 Tab 表单 + 下子表
+
+```vue
+<jh-drag-row :topHeight="280">
+  <template #top>
+    <el-tabs v-model="activeTab"> ... </el-tabs>
+  </template>
+  <template #bottom>
+    <BaseTable ... />
+  </template>
+</jh-drag-row>
+```
+
+---
+
+## 4. 兼容期处理
+
+若现存项目仍引用 `C_Splitter`：
+
+1. **当前版本**：保留组件文件，在 `onMounted` 顶部加 `console.warn("[C_Splitter 已废弃] ...")` 提示
+2. **下一版本**：删除 `src/components/global/C_Splitter/`，全量替换为 `jh-drag-col/row`
+3. **lint 规则**：`wl-skills validate` / `wl-skills doctor-ui` 命中 `import C_Splitter` 或 `<C_Splitter` 时报 ERROR
+
+---
+
+## 5. 自动迁移建议
+
+```bash
+# 项目根目录执行
+grep -rln "C_Splitter" src/views | while read f; do
+  echo "需要人工改造：$f"
+done
+```
+
+迁移要点：
+
+| 旧写法 | 新写法 |
+| ------ | ------ |
+| `<C_Splitter :left-width="220">` | `<jh-drag-col :leftWidth="220">` |
+| `<C_Splitter direction="vertical">` | `<jh-drag-row :topHeight="...">` |
+| 默认 slot 顺序：第一项 / 第二项 | 显式 `#left` `#right` / `#top` `#bottom` |
+| 拖动配置：`min-left-width="200"` | `jh-drag-col` 内置阈值 |
+
+---
+
+## 6. lint / codegen 强制项
+
+- `prototype-scan` / `page-codegen` 生成的模板**禁止**包含 `C_Splitter`
+- TPL-TREE-LIST、TPL-DETAIL-TABS 等模板必须使用 `jh-drag-col` / `jh-drag-row`
+- `wl-skills validate-page` 扫到 `C_Splitter` 直接 fail
+- `wl-skills validate src/views`：业务页面扫描 `<C_Splitter` / `import C_Splitter` / 过时注释（error / info 三级）
+- `wl-skills doctor-ui`：全仓扫描 `.vue/.ts/.scss/.md/.mdc`，区分**业务代码残留（error）**与**文档/规则残留（warn）**；含 `已废弃|DEPRECATED|严禁|不再需要|已迁移` 关键词的上下文自动豁免；`C_Splitter/` 组件目录自身豁免
+
+> 推荐在 CI 非阻断阶段挂 `wl-skills doctor-ui`，残留明细一目了然；提交前 pre-commit 由 `lint-skills` 兜底，禁止任何新增引用流入仓库。
+
+---
+
+## 7. FAQ
+
+**Q1：旧页面跑得好好的，为什么也要改？**
+现状只是"还没踩到 ref 变更的场景"。一旦页面后续接入树节点切换 / 全屏刷新 / 编辑回填，就会出现 ref 改了 UI 不动的灵异 bug，排查成本远大于一次性迁移。
+
+**Q2：`jh-drag-col` 没有 `min-left-width` 怎么办？**
+内部默认 200~600 阈值已可用；如需自定义，传 `:minLeftWidth` / `:maxLeftWidth`（数值，单位 px）。
+
+**Q3：嵌套两层分栏会有性能问题吗？**
+不会。`jh-drag-col` / `jh-drag-row` 都是直接 `<slot />`，没有 vnode 缓存或额外 watcher，嵌套层数与原生 div 等价。
+
+**Q4：必须保留 `C_Splitter` 组件文件吗？**
+保留一段过渡期（带 deprecation warning）即可。等仓库扫描 0 命中后，下一个大版本直接删除 `src/components/global/C_Splitter/`。
+
+---
+
+## 关联
+
+- `12-base-table.md` — BaseTable 内部高度撑满依赖父容器有明确高度，jh-drag-col/row 已正确给子区设 `height: 100%`
+- `13-platform-components.md` — 平台组件对照表已同步移除 C_Splitter
+- 真实场景案例：`demo/produce/aiflow/mmwr-customer-detail/`（master-detail 使用 jh-drag-row）

package/files/.github/standards/index.md

@@ -5,7 +5,7 @@
 
 ---
 
-## 13 条规范清单
+## 14 条规范清单
 
 | 编号 | 文件                        | 主题                   | 强制度         |
 | ---- | --------------------------- | ---------------------- | -------------- |
@@ -22,6 +22,7 @@
 | 11   | `11-form-validation.md`     | 表单与校验             | 🔴 必遵        |
 | 12   | `12-base-table.md`          | BaseTable + AGGrid cid | 🔴 必遵        |
 | 13   | `13-platform-components.md` | 平台组件合规（核心）   | 🔴 必遵 + 阻断 |
+| 14   | `14-layout-containers.md`   | 布局容器（禁用 C_Splitter） | 🔴 必遵 + 阻断 |
 
 ---
 
@@ -32,14 +33,14 @@
 ### 任务类型 A：生成新页面（page-codegen）
 
 ```
-必读：01 / 02 / 04 / 12 / 13
+必读：01 / 02 / 04 / 12 / 13 / 14
 按需：09（TS 类型复杂时） / 10（涉及 Store） / 11（FORM_ROUTE 模板）
 ```
 
 ### 任务类型 B：修改/重构既有页面
 
 ```
-必读：02 / 04 / 13
+必读：02 / 04 / 13 / 14
 按需：09 / 10 / 11
 ```
 

package/files/demo/sale/demo/add-demo/index.scss

@@ -10,7 +10,7 @@
   display: flex;
   flex-direction: column;
 
-  // C_Splitter 区域
+  // jh-drag-row 区域
   .main-splitter {
     flex: 1;
     overflow: hidden;

package/files/demo/sale/demo/add-demo/index.vue

@@ -9,8 +9,9 @@
  -->
 <template>
   <div class="main-maintenance-container">
-    <!-- C_Splitter 包裹表单区和项次信息 -->
-    <C_Splitter direction="vertical" class="main-splitter">
+    <!-- jh-drag-row 包裹表单区和项次信息（上下拖拽） -->
+    <jh-drag-row :topHeight="480" class="main-splitter">
+      <template #top>
       <!-- 🆕 使用增强版组件（集成所有功能） -->
       <c_formSections
         :sections="sectionsConfig"
@@ -43,7 +44,9 @@
           </el-row>
         </template>
       </c_formSections>
+      </template>
 
+      <template #bottom>
       <el-card
         shadow="never"
         class="items-card"
@@ -88,7 +91,8 @@
           </div>
         </div>
       </el-card>
-    </C_Splitter>
+      </template>
+    </jh-drag-row>
 
     <!-- 全屏模式 - 使用 Teleport 传送到 body -->
     <Teleport to="body">
@@ -136,7 +140,7 @@
 <script setup lang="ts">
 import { onMounted } from "vue";
 import { ArrowDown, Close } from "@element-plus/icons-vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// jh-drag-row 是 @jhlc/jh-ui 全局注册组件，无需 import
 import c_formSections from "@/components/local/c_formSections/index.vue";
 import {
   form,

package/files/demo/sale/demo/metallurgical-spec/index.scss

@@ -220,7 +220,7 @@
 
     // 明细信息的表格容器（固定高度，给实验表格留空间）
     &[data-tab="detail"] {
-      // 移除 table-container 固定高度，让 C_Splitter 控制
+      // 移除 table-container 固定高度，让 jh-drag-row 控制
       .detail-tables-splitter {
         flex: 1;
       }

package/files/demo/sale/demo/metallurgical-spec/index.vue

@@ -151,7 +151,8 @@
 
                 <!-- 选择节点后显示表格数据 -->
                 <div v-else class="tables-content">
-                  <C_Splitter direction="vertical">
+                  <jh-drag-row :topHeight="320">
+                    <template #top>
                     <div class="main-table-section">
                       <BaseTable
                         :key="updateKey"
@@ -163,6 +164,8 @@
                         @row-click="handleRowClick"
                       />
                     </div>
+                    </template>
+                    <template #bottom>
                     <div>
                       <div class="experiment-section">
                         <div class="experiment-header">
@@ -193,7 +196,8 @@
                         </div>
                       </div>
                     </div>
-                  </C_Splitter>
+                    </template>
+                  </jh-drag-row>
                 </div>
               </div>
             </div>
@@ -220,7 +224,7 @@
 import { onMounted, onUnmounted, watch, nextTick } from "vue";
 import { ArrowDown, ArrowLeft } from "@element-plus/icons-vue";
 import c_formModal from "@/components/local/c_formModal/index.vue";
-import C_Splitter from "@/components/global/C_Splitter/index.vue";
+// jh-drag-row 是 @jhlc/jh-ui 全局注册组件，无需 import
 import {
   // 状态
   activeTab,

package/files/src/components/global/C_Splitter/index.vue

@@ -23,6 +23,22 @@
 <script setup>
 import { ref, reactive, onMounted, useSlots, onUnmounted } from "vue";
 
+// ⚠️ [DEPRECATED] C_Splitter 已废弃，请改用：
+//   左右分割 → <jh-drag-col :leftWidth="260"> #left / #right </jh-drag-col>
+//   上下分栈 → <jh-drag-row :topHeight="200"> #top / #bottom </jh-drag-row>
+// 原因：C_Splitter 在 onMounted 中调用 slots.default() 冻结 vnode 快照，
+//      导致子树响应式绑定（v-if / v-show / 插值）与父组件 ref 完全解耦，
+//      ref 赋值不触发重渲染。详见 .github/standards/14-layout-containers.md
+if (typeof window !== "undefined" && !window.__C_SPLITTER_WARNED__) {
+  window.__C_SPLITTER_WARNED__ = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    "[C_Splitter 已废弃] 已检测到 C_Splitter 使用。请改用 jh-drag-col / jh-drag-row。\n" +
+    "原因：slots.default() 被冻结为 vnode 快照，导致子树响应式失效。\n" +
+    "详见：.github/standards/14-layout-containers.md"
+  );
+}
+
 const props = defineProps({
   direction: {
     type: String,

package/files/src/components/local/c_formSections/README.md

@@ -472,7 +472,7 @@ const defaultForm = generateDefaultFormData(sectionsConfig);
 - ✅ 真实的保存/草稿/取消逻辑（使用 request + Mock）
 - ✅ 项次信息管理（带分页，使用 jh-pagination）
 - ✅ 全屏模式支持
-- ✅ C_Splitter 拖动调整布局
+- ✅ jh-drag-row 拖拽调整布局
 
 **使用方式**:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.8.0",
-  "description": "AI Skill 模板包 v2.8.0 — 13 条编码规范 + 10 个 AI Skill + 17 个 MCP Tool + Mock 架构体系，一条命令导入 Vue 3 项目",
+  "version": "2.9.2",
+  "description": "AI Skill 模板包 v2.9.2 — 13 条编码规范 + 10 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
     "wl-skills": "bin/wl-skills.js"
@@ -75,4 +75,4 @@
       "eslint --fix --no-cache"
     ]
   }
-}
+}