@agile-team/wl-skills-kit 2.3.4 → 2.3.6

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

@@ -1,95 +1,95 @@
-# 使用指南：prototype-scan（原型扫描）
-
-> **谁读这个文档**：团队成员（产品/前端/后端）
-> **AI 触发文件**：同目录 `SKILL.md`（无需手动阅读）
-
----
-
-## 这个 Skill 解决什么问题
-
-把零散的需求来源（HTML/PDF 原型、详设文档、口述需求、PRD），**结构化为一份《页面清单》**，作为后续 `api-contract` 和 `page-codegen` 的输入。
-
----
-
-## 何时使用
-
-- 产品经理给你一组 HTML 原型，要做成页面
-- 拿到 Word/PDF 详设文档，需要拆解出多少个页面、各自有哪些字段
-- 业务方口述需求："给我加一个客户档案的页面，能查能改能审批……"
-- 想梳理一个模块到底有哪些页面、各自什么类型
-
----
-
-## 触发关键词
-
-`扫描原型` / `解析原型` / `页面清单` / `详设文档` / `口述需求` / `建个页面` / `写个页面`
-
----
-
-## 标准对话示例
-
-### 示例 1：HTML 原型扫描
-
-```
-你：扫描 docs/prototypes/客户管理/ 下的所有原型，生成页面清单。
-AI：[读取 SKILL.md → 输出 Pre-flight 声明]
-    Pre-flight：
-    ├─ 来源：docs/prototypes/客户管理/ 共 7 个 HTML
-    ├─ 输出：reports/PROTOTYPE_SCAN_客户管理_20260426.md
-    └─ 不会生成代码
-    [扫描中... 3 分钟]
-    完成，请确认页面清单：
-    1. mmwr-customer-archive (LIST 类型) - 客户档案查询
-    2. mmwr-customer-detail (DETAIL) - 客户详情
-    ... 共 7 项
-```
-
-### 示例 2：口述需求
-
-```
-你：给生产域加个炼钢批次管理，能查能改能批量审批。
-AI：[输出 Pre-flight]
-    Pre-flight：
-    ├─ 来源：口述需求
-    ├─ 输出：reports/PROTOTYPE_SCAN_炼钢批次_20260426.md
-    └─ 类型推断：LIST + 弹窗编辑 + 行内审批
-    需向你确认 4 项：
-    1. 批次主键是 heatNo 还是 batchId？
-    2. 状态字段有哪些值（已下达/进行中/已完成/作废）？
-    3. 审批是单人审还是多级流转？
-    4. 字典码用 ms_heat_status 还是 mmsm_heat_state？
-```
-
----
-
-## 输出物
-
-`.github/reports/PROTOTYPE_SCAN_<模块>_<YYYYMMDD>.md` —— 包含：
-
-- 页面清单表格（页面英文名 / 中文名 / 类型 / 路由 / 字段概要）
-- 各页面查询条件、表格列、表单字段的初步定义
-- 字典/弹窗/联动的猜测，标注 🟡 待确认
-
----
-
-## 常见踩坑
-
-| 现象                        | 原因                   | 解法                                      |
-| --------------------------- | ---------------------- | ----------------------------------------- |
-| AI 凭空臆造字段             | 原型缺失或描述模糊     | 让 AI 列"待确认"清单，逐项填空再继续      |
-| 页面命名不符合 kebab-case   | AI 直接用中文/驼峰命名 | 在指令里强调 "命名遵循 standards/page.md" |
-| 同一字段在多页面命名不一致  | AI 没有跨页面对齐      | 要求生成清单后做一遍"字段一致性自检"      |
-| LIST/MASTER_DETAIL 类型错判 | 原型隐含主从结构未识别 | 显式告知"这是主从表"或贴出原型图          |
-
----
-
-## FAQ
-
-**Q：扫描出来的页面清单可以直接用 `page-codegen` 生成代码吗？**
-A：建议先走 `api-contract` 生成 api.md，让后端确认接口字段，再 codegen。否则 data.ts 里的字段名可能和后端对不上。
-
-**Q：能不能跳过这个 Skill 直接让 AI 写代码？**
-A：可以但不推荐。Skill 的价值是**约束输出物落到统一文档**，便于团队对账。直接生成代码容易遗漏需求要点、字段命名不规范。
-
-**Q：扫描结果不对怎么办？**
-A：reports/ 下的 md 是 markdown，可以直接编辑。修改后再让 AI "基于 reports/PROTOTYPE_SCAN_xxx.md 进行 api-contract"。
+# 使用指南：prototype-scan（原型扫描）
+
+> **谁读这个文档**：团队成员（产品/前端/后端）
+> **AI 触发文件**：同目录 `SKILL.md`（无需手动阅读）
+
+---
+
+## 这个 Skill 解决什么问题
+
+把零散的需求来源（HTML/PDF 原型、详设文档、口述需求、PRD），**结构化为一份《页面清单》**，作为后续 `api-contract` 和 `page-codegen` 的输入。
+
+---
+
+## 何时使用
+
+- 产品经理给你一组 HTML 原型，要做成页面
+- 拿到 Word/PDF 详设文档，需要拆解出多少个页面、各自有哪些字段
+- 业务方口述需求："给我加一个客户档案的页面，能查能改能审批……"
+- 想梳理一个模块到底有哪些页面、各自什么类型
+
+---
+
+## 触发关键词
+
+`扫描原型` / `解析原型` / `页面清单` / `详设文档` / `口述需求` / `建个页面` / `写个页面`
+
+---
+
+## 标准对话示例
+
+### 示例 1：HTML 原型扫描
+
+```
+你：扫描 docs/prototypes/客户管理/ 下的所有原型，生成页面清单。
+AI：[读取 SKILL.md → 输出 Pre-flight 声明]
+    Pre-flight：
+    ├─ 来源：docs/prototypes/客户管理/ 共 7 个 HTML
+    ├─ 输出：reports/PROTOTYPE_SCAN_客户管理_20260426.md
+    └─ 不会生成代码
+    [扫描中... 3 分钟]
+    完成，请确认页面清单：
+    1. mmwr-customer-archive (LIST 类型) - 客户档案查询
+    2. mmwr-customer-detail (DETAIL) - 客户详情
+    ... 共 7 项
+```
+
+### 示例 2：口述需求
+
+```
+你：给生产域加个炼钢批次管理，能查能改能批量审批。
+AI：[输出 Pre-flight]
+    Pre-flight：
+    ├─ 来源：口述需求
+    ├─ 输出：reports/PROTOTYPE_SCAN_炼钢批次_20260426.md
+    └─ 类型推断：LIST + 弹窗编辑 + 行内审批
+    需向你确认 4 项：
+    1. 批次主键是 heatNo 还是 batchId？
+    2. 状态字段有哪些值（已下达/进行中/已完成/作废）？
+    3. 审批是单人审还是多级流转？
+    4. 字典码用 ms_heat_status 还是 mmsm_heat_state？
+```
+
+---
+
+## 输出物
+
+`.github/reports/PROTOTYPE_SCAN_<模块>_<YYYYMMDD>.md` —— 包含：
+
+- 页面清单表格（页面英文名 / 中文名 / 类型 / 路由 / 字段概要）
+- 各页面查询条件、表格列、表单字段的初步定义
+- 字典/弹窗/联动的猜测，标注 🟡 待确认
+
+---
+
+## 常见踩坑
+
+| 现象                        | 原因                   | 解法                                      |
+| --------------------------- | ---------------------- | ----------------------------------------- |
+| AI 凭空臆造字段             | 原型缺失或描述模糊     | 让 AI 列"待确认"清单，逐项填空再继续      |
+| 页面命名不符合 kebab-case   | AI 直接用中文/驼峰命名 | 在指令里强调 "命名遵循 standards/page.md" |
+| 同一字段在多页面命名不一致  | AI 没有跨页面对齐      | 要求生成清单后做一遍"字段一致性自检"      |
+| LIST/MASTER_DETAIL 类型错判 | 原型隐含主从结构未识别 | 显式告知"这是主从表"或贴出原型图          |
+
+---
+
+## FAQ
+
+**Q：扫描出来的页面清单可以直接用 `page-codegen` 生成代码吗？**
+A：建议先走 `api-contract` 生成 api.md，让后端确认接口字段，再 codegen。否则 data.ts 里的字段名可能和后端对不上。
+
+**Q：能不能跳过这个 Skill 直接让 AI 写代码？**
+A：可以但不推荐。Skill 的价值是**约束输出物落到统一文档**，便于团队对账。直接生成代码容易遗漏需求要点、字段命名不规范。
+
+**Q：扫描结果不对怎么办？**
+A：reports/ 下的 md 是 markdown，可以直接编辑。修改后再让 AI "基于 reports/PROTOTYPE_SCAN_xxx.md 进行 api-contract"。

package/files/.github/skills/core/template-extract/SKILL.md

@@ -1,139 +1,139 @@
----
-name: template-extract
-description: "Use when: extracting domain-specific page templates from existing project pages and contributing them to skills/core/page-codegen/templates/domains/. Triggers on: 提取模板, 抽取模板, 沉淀模板, 模板贡献, extract template, contribute template."
----
-
-# Skill: 模板提取（template-extract）
-
-从现有项目的成熟页面提取领域模板，沉淀到 `.github/skills/core/page-codegen/templates/domains/`，扩充团队 AI 模板库。
-
-> **核心理念**：模板贡献门槛极低 — 开发者只需说出一个页面目录路径，AI 完成 90% 的分析和写作。
-
----
-
-## 触发词
-
-`提取模板` / `抽取模板` / `沉淀模板` / `模板贡献` / `extract template`
-
----
-
-## Pre-flight 声明
-
-```
-🚀 已触发技能 template-extract/SKILL.md → 从现有页面提取领域模板
-✅ 已读取 template-extract/SKILL.md      → 提取流程主规则
-✅ 已读取 templates/_index.md            → 已有模板清单（避免重复）
-✅ 已读取 standards/02-code-structure.md → 模板必须遵循的代码结构
-✅ 已读取 standards/13-platform-components.md → 模板必须遵循的平台组件合规
-```
-
----
-
-## 执行流程
-
-### 步骤 1：开发者指定目标
-
-开发者提供一个目录路径：
-
-```
-"提取模板，目标页：src/views/produce/sjgl/mmwr-rolling-management/"
-```
-
-### 步骤 2：AI 读取目标页 4 文件
-
-```
-✅ 读取 {target}/index.vue
-✅ 读取 {target}/data.ts
-✅ 读取 {target}/index.scss
-✅ 读取 {target}/api.md（如存在）
-```
-
-### 步骤 3：AI 自动识别交互模式
-
-输出识别结论：
-
-```
-🔍 识别结果
-  - 页面包含：{2 个 BaseTable / 1 个内联 BaseForm / 4 个操作按钮}
-  - 交互模式：{双清单联动 + 内联表单 + 条件按钮}
-  - 与已有 TPL 对比：
-      ✅ 接近 TPL-OPERATION-STATION（domains/produce/）
-      ❌ 不符合 TPL-LIST / TPL-MASTER-DETAIL / TPL-RECORD-FORM
-  - 结论建议：本页面**已有相似模板**，可能是 TPL-OPERATION-STATION 的变体，
-              建议考虑增强现有模板而非新建。
-              （或：本页面是**独立新模式**，建议提取为 TPL-XXX）
-```
-
-### 步骤 4：AI 问答确认（最多 4 个问题）
-
-```
-❓ 问题 1：领域归属？
-   选项：A. produce（生产）  B. sale（销售）  C. 其他（请说明）
-
-❓ 问题 2：建议的模板命名？
-   AI 建议：TPL-{XXX-XXX}
-   如不满意请提出替代
-
-❓ 问题 3：是否有需要脱敏/抽象的业务特定内容？
-   - 业务字段名（建议保留作为占位符 [字段名]）
-   - 业务接口路径（建议改为 [服务缩写]/[资源名]/{action} 占位）
-   - 硬编码字典码（建议改为占位符或注释说明）
-
-❓ 问题 4：是否合并到已有模板？
-   仅当步骤 3 识别为「相似模板」时才问。
-   选项：A. 增强现有模板（追加章节）  B. 提取为独立新模板
-```
-
-### 步骤 5：生成 TPL 文件
-
-按 `templates/domains/_CONTRIBUTING.md` 格式生成，必须包含：
-
-- 适用场景说明
-- 识别规则（5 条以内）
-- 完整 index.vue / data.ts / index.scss 代码（脱敏后）
-- 注意事项
-
-### 步骤 6：写入并注册
-
-```
-✅ 写入 templates/domains/{domain}/TPL-{NAME}.md
-✅ 更新 templates/_index.md（追加注册条目）
-```
-
-### 步骤 7：输出后续步骤
-
-```
-📦 模板提取完成
-────────────────────────────────────────────────
-✅ 已生成 templates/domains/{domain}/TPL-{NAME}.md
-✅ 已更新 templates/_index.md 注册表
-────────────────────────────────────────────────
-📌 后续步骤：
-   1. 人工 review 模板内容（脱敏完整性 / 占位符正确性）
-   2. 提交：git cz → feat(template): 新增领域模板 TPL-{NAME}
-   3. PR 评审 → CHENY 合入
-────────────────────────────────────────────────
-```
-
----
-
-## 提取质量校验（AI 自检）
-
-生成 TPL 文件后，AI 必须自检：
-
-- [ ] 业务字段名已替换为 `[字段名]` / `[资源名]` 占位符
-- [ ] API 路径已替换为 `/[服务缩写]/[资源名]/{action}` 格式
-- [ ] 没有遗留具体的字典码 / 状态值（已注释说明用途）
-- [ ] 代码符合 standards/02、13（结构 + 组件合规）
-- [ ] 包含识别规则（让 AI 未来能匹配此模板）
-
----
-
-## 边界情况
-
-| 情况                             | 处理                                                         |
-| -------------------------------- | ------------------------------------------------------------ |
-| 目标页代码不符合 standards/ 规范 | 拒绝提取，输出审计建议（"目标页本身不合规，建议先整改"）     |
-| 目标页过于业务特化，无法抽象     | 反问开发者："此页面业务耦合较深，提取后通用性差，是否继续？" |
-| 已有 TPL 高度重合                | 优先建议增强现有模板，不建议新建                             |
-| 开发者指定的命名不符合规范       | 给出建议命名，请开发者确认                                   |
+---
+name: template-extract
+description: "Use when: extracting domain-specific page templates from existing project pages and contributing them to skills/core/page-codegen/templates/domains/. Triggers on: 提取模板, 抽取模板, 沉淀模板, 模板贡献, extract template, contribute template."
+---
+
+# Skill: 模板提取（template-extract）
+
+从现有项目的成熟页面提取领域模板，沉淀到 `.github/skills/core/page-codegen/templates/domains/`，扩充团队 AI 模板库。
+
+> **核心理念**：模板贡献门槛极低 — 开发者只需说出一个页面目录路径，AI 完成 90% 的分析和写作。
+
+---
+
+## 触发词
+
+`提取模板` / `抽取模板` / `沉淀模板` / `模板贡献` / `extract template`
+
+---
+
+## Pre-flight 声明
+
+```
+🚀 已触发技能 template-extract/SKILL.md → 从现有页面提取领域模板
+✅ 已读取 template-extract/SKILL.md      → 提取流程主规则
+✅ 已读取 templates/_index.md            → 已有模板清单（避免重复）
+✅ 已读取 standards/02-code-structure.md → 模板必须遵循的代码结构
+✅ 已读取 standards/13-platform-components.md → 模板必须遵循的平台组件合规
+```
+
+---
+
+## 执行流程
+
+### 步骤 1：开发者指定目标
+
+开发者提供一个目录路径：
+
+```
+"提取模板，目标页：src/views/produce/sjgl/mmwr-rolling-management/"
+```
+
+### 步骤 2：AI 读取目标页 4 文件
+
+```
+✅ 读取 {target}/index.vue
+✅ 读取 {target}/data.ts
+✅ 读取 {target}/index.scss
+✅ 读取 {target}/api.md（如存在）
+```
+
+### 步骤 3：AI 自动识别交互模式
+
+输出识别结论：
+
+```
+🔍 识别结果
+  - 页面包含：{2 个 BaseTable / 1 个内联 BaseForm / 4 个操作按钮}
+  - 交互模式：{双清单联动 + 内联表单 + 条件按钮}
+  - 与已有 TPL 对比：
+      ✅ 接近 TPL-OPERATION-STATION（domains/produce/）
+      ❌ 不符合 TPL-LIST / TPL-MASTER-DETAIL / TPL-RECORD-FORM
+  - 结论建议：本页面**已有相似模板**，可能是 TPL-OPERATION-STATION 的变体，
+              建议考虑增强现有模板而非新建。
+              （或：本页面是**独立新模式**，建议提取为 TPL-XXX）
+```
+
+### 步骤 4：AI 问答确认（最多 4 个问题）
+
+```
+❓ 问题 1：领域归属？
+   选项：A. produce（生产）  B. sale（销售）  C. 其他（请说明）
+
+❓ 问题 2：建议的模板命名？
+   AI 建议：TPL-{XXX-XXX}
+   如不满意请提出替代
+
+❓ 问题 3：是否有需要脱敏/抽象的业务特定内容？
+   - 业务字段名（建议保留作为占位符 [字段名]）
+   - 业务接口路径（建议改为 [服务缩写]/[资源名]/{action} 占位）
+   - 硬编码字典码（建议改为占位符或注释说明）
+
+❓ 问题 4：是否合并到已有模板？
+   仅当步骤 3 识别为「相似模板」时才问。
+   选项：A. 增强现有模板（追加章节）  B. 提取为独立新模板
+```
+
+### 步骤 5：生成 TPL 文件
+
+按 `templates/domains/_CONTRIBUTING.md` 格式生成，必须包含：
+
+- 适用场景说明
+- 识别规则（5 条以内）
+- 完整 index.vue / data.ts / index.scss 代码（脱敏后）
+- 注意事项
+
+### 步骤 6：写入并注册
+
+```
+✅ 写入 templates/domains/{domain}/TPL-{NAME}.md
+✅ 更新 templates/_index.md（追加注册条目）
+```
+
+### 步骤 7：输出后续步骤
+
+```
+📦 模板提取完成
+────────────────────────────────────────────────
+✅ 已生成 templates/domains/{domain}/TPL-{NAME}.md
+✅ 已更新 templates/_index.md 注册表
+────────────────────────────────────────────────
+📌 后续步骤：
+   1. 人工 review 模板内容（脱敏完整性 / 占位符正确性）
+   2. 提交：git cz → feat(template): 新增领域模板 TPL-{NAME}
+   3. PR 评审 → CHENY 合入
+────────────────────────────────────────────────
+```
+
+---
+
+## 提取质量校验（AI 自检）
+
+生成 TPL 文件后，AI 必须自检：
+
+- [ ] 业务字段名已替换为 `[字段名]` / `[资源名]` 占位符
+- [ ] API 路径已替换为 `/[服务缩写]/[资源名]/{action}` 格式
+- [ ] 没有遗留具体的字典码 / 状态值（已注释说明用途）
+- [ ] 代码符合 standards/02、13（结构 + 组件合规）
+- [ ] 包含识别规则（让 AI 未来能匹配此模板）
+
+---
+
+## 边界情况
+
+| 情况                             | 处理                                                         |
+| -------------------------------- | ------------------------------------------------------------ |
+| 目标页代码不符合 standards/ 规范 | 拒绝提取，输出审计建议（"目标页本身不合规，建议先整改"）     |
+| 目标页过于业务特化，无法抽象     | 反问开发者："此页面业务耦合较深，提取后通用性差，是否继续？" |
+| 已有 TPL 高度重合                | 优先建议增强现有模板，不建议新建                             |
+| 开发者指定的命名不符合规范       | 给出建议命名，请开发者确认                                   |

package/files/.github/skills/core/template-extract/USAGE.md

@@ -1,93 +1,93 @@
-# 使用指南：template-extract（模板提取）
-
-> **谁读这个文档**：团队成员（主要前端，模板贡献者）
-> **AI 触发文件**：同目录 `SKILL.md`
-
----
-
-## 这个 Skill 解决什么问题
-
-把项目里**已经写得很好的页面**抽取成可复用模板，沉淀到 `skills/core/page-codegen/templates/domains/` 下。下次 codegen 时同类页面优先复用。
-
----
-
-## 何时使用
-
-- 写完一个"代表性强、规范度高"的页面，想沉淀给团队复用
-- 同模块内重复结构出现 ≥ 3 次，应抽模板
-- 季度/版本末整理沉淀产出
-
----
-
-## 触发关键词
-
-`提取模板` / `抽取模板` / `沉淀模板` / `模板贡献`
-
----
-
-## 标准对话示例
-
-```
-你：把 src/views/produce/aiflow/mmwr-customer-archive/ 这个页面抽取成模板
-AI：[Pre-flight]
-    源：mmwr-customer-archive (LIST 类型，含审批工作流)
-    建议落位：templates/domains/produce/customer/list-with-approval/
-    将抽取：
-    - data.ts.tpl  （EColumn 字段保留 + 字段名占位化）
-    - index.vue.tpl
-    - index.scss.tpl
-    - meta.json    （记录适用场景、字段规则、字典）
-    占位约定：
-    - 资源名 → {{resourceName}}
-    - 服务缩写 → {{serviceShort}}
-    - 字典 logicValue → {{statusDict}}
-    通过 convention-audit 后才落盘。
-```
-
----
-
-## 输出物
-
-```
-templates/domains/<域>/<场景>/
-├── data.ts.tpl
-├── index.vue.tpl
-├── index.scss.tpl
-├── meta.json    适用条件 / 占位字段说明 / 字典依赖
-└── README.md   场景说明 + 何时复用 + 已知限制
-```
-
----
-
-## 模板分级
-
-| 层级         | 路径                             | 复用范围                            |
-| ------------ | -------------------------------- | ----------------------------------- |
-| `universal/` | `templates/universal/<类型>/`    | 跨业务通用（LIST/DETAIL/TREE_LIST） |
-| `domains/`   | `templates/domains/<域>/<场景>/` | 同域同场景                          |
-
-抽取的模板**默认进 domains/**。如果发现真的全员通用，可由维护者升级到 universal/。
-
----
-
-## 常见踩坑
-
-| 现象                               | 原因                 | 解法                                                            |
-| ---------------------------------- | -------------------- | --------------------------------------------------------------- |
-| 抽出来的模板里夹着业务字段         | 占位化不彻底         | meta.json 里**穷举所有占位**，AI 才会替换干净                   |
-| 模板下次 codegen 命中率低          | 命名/scope 太具体    | 起更通用的场景名（list-with-approval 比 mmwr-customer-list 好） |
-| 字典硬编码进模板                   | 没用 logicValue 占位 | 改用 `{{statusDict}}` 占位 + meta 里描述                        |
-| 不同业务字段长度不一时模板生成报错 | 列宽硬编码           | 模板里只给推荐值，meta 标"可调"                                 |
-
----
-
-## FAQ
-
-**Q：贡献的模板要走 review 吗？**
-A：建议至少同事 review 一下 meta.json + 是否真有复用价值。直接落盘容易污染模板库。
-
-**Q：模板出问题谁负责？**
-A：贡献者维护一段时间，稳定后由 kit 维护者接管。模板里要写 author + lastUpdate。
-
-**Q：能否私有领域只抽到本仓库不发布？**
-A：可以。`templates/domains/` 在 `.github/skills/` 下，跟着业务项目走。kit 包不强制收集。
+# 使用指南：template-extract（模板提取）
+
+> **谁读这个文档**：团队成员（主要前端，模板贡献者）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+把项目里**已经写得很好的页面**抽取成可复用模板，沉淀到 `skills/core/page-codegen/templates/domains/` 下。下次 codegen 时同类页面优先复用。
+
+---
+
+## 何时使用
+
+- 写完一个"代表性强、规范度高"的页面，想沉淀给团队复用
+- 同模块内重复结构出现 ≥ 3 次，应抽模板
+- 季度/版本末整理沉淀产出
+
+---
+
+## 触发关键词
+
+`提取模板` / `抽取模板` / `沉淀模板` / `模板贡献`
+
+---
+
+## 标准对话示例
+
+```
+你：把 src/views/produce/aiflow/mmwr-customer-archive/ 这个页面抽取成模板
+AI：[Pre-flight]
+    源：mmwr-customer-archive (LIST 类型，含审批工作流)
+    建议落位：templates/domains/produce/customer/list-with-approval/
+    将抽取：
+    - data.ts.tpl  （EColumn 字段保留 + 字段名占位化）
+    - index.vue.tpl
+    - index.scss.tpl
+    - meta.json    （记录适用场景、字段规则、字典）
+    占位约定：
+    - 资源名 → {{resourceName}}
+    - 服务缩写 → {{serviceShort}}
+    - 字典 logicValue → {{statusDict}}
+    通过 convention-audit 后才落盘。
+```
+
+---
+
+## 输出物
+
+```
+templates/domains/<域>/<场景>/
+├── data.ts.tpl
+├── index.vue.tpl
+├── index.scss.tpl
+├── meta.json    适用条件 / 占位字段说明 / 字典依赖
+└── README.md   场景说明 + 何时复用 + 已知限制
+```
+
+---
+
+## 模板分级
+
+| 层级         | 路径                             | 复用范围                            |
+| ------------ | -------------------------------- | ----------------------------------- |
+| `universal/` | `templates/universal/<类型>/`    | 跨业务通用（LIST/DETAIL/TREE_LIST） |
+| `domains/`   | `templates/domains/<域>/<场景>/` | 同域同场景                          |
+
+抽取的模板**默认进 domains/**。如果发现真的全员通用，可由维护者升级到 universal/。
+
+---
+
+## 常见踩坑
+
+| 现象                               | 原因                 | 解法                                                            |
+| ---------------------------------- | -------------------- | --------------------------------------------------------------- |
+| 抽出来的模板里夹着业务字段         | 占位化不彻底         | meta.json 里**穷举所有占位**，AI 才会替换干净                   |
+| 模板下次 codegen 命中率低          | 命名/scope 太具体    | 起更通用的场景名（list-with-approval 比 mmwr-customer-list 好） |
+| 字典硬编码进模板                   | 没用 logicValue 占位 | 改用 `{{statusDict}}` 占位 + meta 里描述                        |
+| 不同业务字段长度不一时模板生成报错 | 列宽硬编码           | 模板里只给推荐值，meta 标"可调"                                 |
+
+---
+
+## FAQ
+
+**Q：贡献的模板要走 review 吗？**
+A：建议至少同事 review 一下 meta.json + 是否真有复用价值。直接落盘容易污染模板库。
+
+**Q：模板出问题谁负责？**
+A：贡献者维护一段时间，稳定后由 kit 维护者接管。模板里要写 author + lastUpdate。
+
+**Q：能否私有领域只抽到本仓库不发布？**
+A：可以。`templates/domains/` 在 `.github/skills/` 下，跟着业务项目走。kit 包不强制收集。