@agile-team/wl-skills-kit 2.9.4 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.10.0] - 2026-05-31
+
+### Added
+
+- **新增 `spec-doc-parse` Skill（规范线）**：专门解构 wl-skills-design 产出的标准《需求设计说明书》（IPO 表 / 功能编码 / 流程五要素），输出与 `prototype-scan` 完全相同格式的 page-spec JSON，自带 Pre-flight 校验 + Parse Validation 五项检查 + 自动修复纠偏 + 解析报告（`SPEC_PARSE_*.md`）
+- **`convention-audit` 新增 `--mode spec-align`（GAP 报告）**：比对 spec 定义字段 vs 代码实际字段，输出 `SPEC_GAP_*.md`，完成「说明书 → 代码」零损耗闭环验证
+
+### Changed
+
+- **双线隔离（原型线 / 规范线）**：`_registry.md` 调度规则新增「优先级 0」——输入命中 `docs/spec/` / 功能编码 `/[A-Z]{2,6}[0-9]{3}/` / IPO 表特征时强制路由 `spec-doc-parse`，禁止 `prototype-scan` 接管；两线最终汇聚同一份 page-spec JSON，下游无感知
+- **`prototype-scan` 模式 B 收敛**：由「详设文档」收敛为「非规范零散详设」，加入排除声明，避免与标准说明书混淆
+- 同步更新 `_pipeline.md`（规范线分支 + I/O 契约）、`copilot-instructions.md`（Intent Router）、`kit-internal/architecture.md`（ADR-009）、`lint-skills.js`（spec-doc-parse 纳入写操作 Skill 校验）
+- 启用 Skill 数 10 → 11
+
 ## [2.9.4] - 2026-05-18
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.9.4** — 一键将 14 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.10.0** — 一键将 14 条规范、11 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -184,6 +184,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   │   ├── _compat/                      多 AI 编辑器适配（配置 + headers）
 │   │   ├── core/                         核心通用 Skill
 │   │   │   ├── prototype-scan/   { SKILL.md, USAGE.md }
+│   │   │   ├── spec-doc-parse/   { SKILL.md, USAGE.md }
 │   │   │   ├── api-contract/     { SKILL.md, USAGE.md }
 │   │   │   ├── page-codegen/     { SKILL.md, USAGE.md, templates/ }
 │   │   │   ├── convention-audit/ { SKILL.md, USAGE.md }
@@ -329,7 +330,8 @@ npx @agile-team/wl-skills-kit update
 
 | Skill              | 状态    | 路径                            | 核心用途                                    |
 | ------------------ | ------- | ------------------------------- | ------------------------------------------- |
-| `prototype-scan`   | ✅ 启用 | `skills/core/prototype-scan/`   | 原型/详设/口述 → 页面清单                   |
+| `prototype-scan`   | ✅ 启用 | `skills/core/prototype-scan/`   | 原型线：Axure/截图/口述/非规范详设 → 页面清单 |
+| `spec-doc-parse`   | ✅ 启用 | `skills/core/spec-doc-parse/`   | 规范线：wl-skills-design 标准说明书 → 页面清单 |
 | `api-contract`     | ✅ 启用 | `skills/core/api-contract/`     | 生成 api.md 前后端契约                      |
 | `page-codegen`     | ✅ 启用 | `skills/core/page-codegen/`     | 页面骨架生成 + 模板调度                     |
 | `convention-audit` | ✅ 启用 | `skills/core/convention-audit/` | 13 条规范扫描 + 双报告                      |

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.9.4
+ * wl-skills-kit CLI v2.10.0
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）

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

@@ -266,6 +266,7 @@ onMounted(() => select());
 | 用户自然表达 | 自动触发 |
 | ------------ | -------- |
 | 生成页面 / 做个页面 / 列表页 / 管理页 / 台账 / 根据原型 / 根据截图 / 补页面 | `page-codegen`，必要时先 `prototype-scan` + `api-contract` |
+| 解析说明书 / 规范文档转页面 / 根据说明书生成 / IPO 转页面 / docs/spec 路径 / 功能编码（PMMB001） | `spec-doc-parse`（**规范线**，wl-skills-design 标准说明书专属，禁止 prototype-scan 接管） |
 | mock / 假数据 / 后端没好 / 先能跑 / 联调前 | `page-codegen` 的 mock-first 规则 |
 | 菜单 / 注册页面 / 点击进不来 / 同步菜单 / 补菜单 | `menu-sync` + `route-check` |
 | 风格 / 样式不生效 / skills-ui / 操作列 / 状态标签 / AGGrid | `page-codegen` + `wk-skills-ui runtime` + `doctor-ui` |

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

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

package/files/.github/skills/_compat/headers/cursor-mdc.txt

@@ -1,5 +1,5 @@
 ---
-description: "项目编码规范（13 条标准 + 10 个 Skill 自动调度，由 wl-skills-kit 自动生成）"
+description: "项目编码规范（13 条标准 + 11 个 Skill 自动调度，由 wl-skills-kit 自动生成）"
 globs:
   - "**/*.vue"
   - "**/*.ts"

package/files/.github/skills/_compat/headers/kiro.txt

@@ -1,6 +1,6 @@
 ---
 inclusion: always
-description: 项目编码规范（13 条标准 + 10 个 Skill 自动调度）
+description: 项目编码规范（13 条标准 + 11 个 Skill 自动调度）
 ---
 
 <!-- Kiro Steering 规则。由 @agile-team/wl-skills-kit 自动生成。-->

package/files/.github/skills/_compat/headers/trae.txt

@@ -1,5 +1,5 @@
 ---
-description: "项目编码规范（13 条标准 + 10 个 Skill 自动调度，由 wl-skills-kit 自动生成）"
+description: "项目编码规范（13  条标准 + 11 个 Skill 自动调度，由 wl-skills-kit 自动生成）"
 globs: ["**/*.vue", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.scss"]
 alwaysApply: true
 ---

package/files/.github/skills/_pipeline.md

@@ -18,20 +18,24 @@
 ## 2. Pipeline 总览
 
 ```text
-prototype-scan
+prototype-scan                       // 原型线：Axure / 截图 / 口述 / 非规范详设
+spec-doc-parse                       // 规范线：wl-skills-design 标准说明书（二者二选一，汇聚同一 page-spec）
   → business-doc-extract（可选，资料达模块级时推荐）
   → api-contract
   → page-codegen
-  → convention-audit
+  → convention-audit（规范线可追加 --mode spec-align 生成 GAP 报告）
   → code-fix（可选）
   → menu-sync / dict-sync / permission-sync（按页面需要选择）
   → template-extract（成熟页面沉淀，可选）
 ```
 
+> **双线隔离**：`prototype-scan`（原型线）与 `spec-doc-parse`（规范线）是互斥的两个入口，按输入类型二选一（详见 `_registry.md` 调度规则优先级 0），输出格式完全相同，下游无感知。
+
 常见变体：
 
 ```text
 口述需求 → page-codegen → convention-audit                  // 碎片化，不走业务文档
+标准说明书 → spec-doc-parse → api-contract → page-codegen → convention-audit --mode spec-align   // 规范线闭环
 存量项目反向梳理 → business-doc-extract → convention-audit
 原型/详设 → business-doc-extract → api-contract → page-codegen
 存量项目体检 → convention-audit → code-fix
@@ -48,11 +52,12 @@ prototype-scan
 
 | Skill | input_from | output_file | next_suggest |
 |---|---|---|---|
-| `prototype-scan` | 原型/详设/口述需求 | `.github/reports/PROTOTYPE_SCAN_*.md` | `business-doc-extract`（资料达模块级）或 `api-contract` |
+| `prototype-scan` | 原型/非规范详设/口述需求 | `.github/reports/PROTOTYPE_SCAN_*.md` | `business-doc-extract`（资料达模块级）或 `api-contract` |
+| `spec-doc-parse` | wl-skills-design 标准说明书（`docs/spec/{项目代号}/ch1-3.md` + `4.x-*.md` + `4.N-data-report.md`） | `.github/reports/SPEC_PARSE_*.md`（含 page-spec JSON + 解析报告） | `api-contract`（处理完阻断/待确认项后） |
 | `business-doc-extract` | 已发布原型目录 / 详设 / 字段实体 / 字典资料 / 现有页面 + `api.md` / `prototype-scan` 输出 | `docs/business/index.md` + `docs/business/open-questions.md` + `docs/business/0X-xx/{index,requirement,dictionary,field}.md` | `api-contract` 或 `page-codegen`（项目需求依据） |
-| `api-contract` | `prototype-scan` 输出、`docs/business/0X-xx/requirement.md` + `field.md` 或用户口述接口信息 | `src/views/**/api.md` | `page-codegen` |
+| `api-contract` | `prototype-scan` 输出、`spec-doc-parse` 输出、`docs/business/0X-xx/requirement.md` + `field.md` 或用户口述接口信息 | `src/views/**/api.md` | `page-codegen` |
 | `page-codegen` | `api.md` / page-spec / 用户口述需求 | `src/views/**/{index.vue,data.ts,index.scss,api.md}` + `.github/reports/SYS_MENU_INFO.md` | `convention-audit`；如有菜单则 `menu-sync` |
-| `convention-audit` | 任意源码目录或文件 | `.github/reports/AUDIT_*.md` | 有可自动修复项时 `code-fix`；有菜单/字典/权限差异时对应 sync Skill |
+| `convention-audit` | 任意源码目录或文件；`--mode spec-align` 时额外入 `spec-doc-parse` 的 page-spec / 说明书 | `.github/reports/AUDIT_*.md`；`--mode spec-align` 输出 `SPEC_GAP_*.md` | 有可自动修复项时 `code-fix`；有菜单/字典/权限差异时对应 sync Skill |
 | `code-fix` | `convention-audit` 报告 | 源码 diff / 修复摘要 | `convention-audit` 复扫 |
 | `menu-sync` | `.github/reports/SYS_MENU_INFO.md` | 后端菜单数据 + 同步摘要 | `permission-sync`（如需角色授权/动作） |
 | `dict-sync` | `.github/reports/SYS_DICT_INFO.md` | 后端字典数据 + 同步摘要 | `convention-audit` 复扫（如页面依赖字典） |

package/files/.github/skills/_registry.md

@@ -13,6 +13,7 @@ skills/
 │
 ├── core/                核心通用 Skill（任何前端业务项目通用）
 │   ├── prototype-scan/
+│   ├── spec-doc-parse/
 │   ├── api-contract/
 │   ├── page-codegen/
 │   ├── convention-audit/
@@ -41,7 +42,8 @@ skills/
 
 | Skill 名         | 状态    | 路径                                    | MCP 工具依赖                                                                                                              | 触发关键词                                                                                                                              |
 | ---------------- | ------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| prototype-scan   | ✅ 启用 | `skills/core/prototype-scan/SKILL.md`   | —                                                                                                                          | 扫描原型 / 解析原型 / 页面清单 / 详设文档 / 口述需求 / 建个页面 / 写个页面 / 根据截图 / 根据原型                                        |
+| prototype-scan   | ✅ 启用 | `skills/core/prototype-scan/SKILL.md`   | —                                                                                                                          | 扫描原型 / 解析原型 / 页面清单 / 口述需求 / 建个页面 / 写个页面 / 根据截图 / 根据原型（**非规范零散详设**）                              |
+| spec-doc-parse   | ✅ 启用 | `skills/core/spec-doc-parse/SKILL.md`   | —                                                                                                                          | 解析说明书 / 解析需求文档 / 规范文档转页面 / 根据说明书生成 / IPO 转页面 / 功能编码 / docs/spec（**wl-skills-design 标准说明书**）       |
 | api-contract     | ✅ 启用 | `skills/core/api-contract/SKILL.md`     | —                                                                                                                          | 接口约定 / api.md / 字段定义 / 前后端对齐 / 接口设计                                                                                    |
 | page-codegen     | ✅ 启用 | `skills/core/page-codegen/SKILL.md`     | `wls_validate_page` / `wls_doctor_ui`                                                                                      | 生成页面 / 创建页面 / 代码生成 / vue页面 / 按原型生成 / 帮我生成 / 列表页 / 管理页 / 台账 / mock / 假数据 / 先能跑 / AGGrid / skills-ui |
 | convention-audit | ✅ 启用 | `skills/core/convention-audit/SKILL.md` | `wls_code_scan` / `wls_audit_report_push`                                                                                  | 规范审计 / 代码审计 / 规范检查 / 对齐规范 / 规范偏差 / 接手新项目 / 存量代码分析 / 项目体检                                             |
@@ -58,6 +60,7 @@ skills/
 
 ## 调度规则
 
+0. **优先级 0（最高）— 双线隔离**：若用户输入路径含 `docs/spec/`，或文档含功能编码 `/[A-Z]{2,6}[0-9]{3}/` / IPO 表「处理逻辑」/ 流程五要素，**强制路由 `spec-doc-parse`（规范线）**，跳过 `prototype-scan` 的所有模式匹配。反之，Axure HTML / 截图 / 口述 / 非规范零散详设走 `prototype-scan`（原型线）。两线最终汇聚到同一份 page-spec JSON。
 1. **首先加载** `_best-practices.md`（场景索引，语义级路由依据），结合用户意图判断属于哪个场景
 2. 按场景指向的 Skill，`read_file` 加载对应 SKILL.md
 3. SKILL.md 中标注的 `必读 standards` 按 `standards/index.md` 任务类型映射加载
@@ -74,7 +77,7 @@ skills/
 
 当用户消息同时匹配多个 Skill 时（如"扫描原型并生成页面"）：
 
-1. 优先识别**完整流水线意图**：读取 `_pipeline.md`，按 `prototype-scan` → `api-contract` → `page-codegen` → `convention-audit` → sync/ops 的顺序建议下一步
+1. 优先识别**完整流水线意图**：读取 `_pipeline.md`，按 `prototype-scan`（原型线）或 `spec-doc-parse`（规范线）→ `api-contract` → `page-codegen` → `convention-audit` → sync/ops 的顺序建议下一步
 2. 否则按**最具体的触发词**匹配单个 Skill
 3. 用户明确指定时（如"只扫描，不生成"），按用户指示
 

package/files/.github/skills/core/convention-audit/SKILL.md

@@ -366,6 +366,7 @@ description: "Use when: auditing project source code against the 14 modular stan
 | **page-codegen** | 审计发现偏差后，可调用 page-codegen 重新生成合规代码 |
 | **template-extract** | 审计输出的"组件提取建议"，确认后可触发 template-extract |
 | **code-fix** | 审计报告中 ✅/⚠️ 标记项作为修复输入 |
+| **spec-doc-parse** | 提供 spec 对齐模式的基准：用规范线解析出的 page-spec 与生成代码比对，输出 GAP 报告 |
 | **CI/CD** | 审计可作为 PR 检查项，不合规 PR 阻断合并 |
 
 ---
@@ -378,3 +379,54 @@ description: "Use when: auditing project source code against the 14 modular stan
 4. **AI 自我审计**：page-codegen 生成代码后，建议立即跑一次单页审计验证合规
 5. **工具链优先**：TS 类型 / ESLint 规则优先借助工具链扫描，AI 负责监督验证和归类，不浪费算力逐文件做语义分析
 6. **场景化判定**：`data.ts` / `api.md` / AGGrid 均按场景规则判定，不机械检查文件数量
+
+---
+
+## spec 对齐扫描（GAP 报告）
+
+> 闭环能力：与 `core/spec-doc-parse` 联动。当页面代码来自「规范线」（wl-skills-design 说明书 → spec-doc-parse → page-codegen）时，本模式把 **原始 spec 定义的字段** 与 **代码中实际存在的字段** 逐项比对，生成 GAP 报告，验证「说明书 → 代码」是否零损耗。
+
+### 触发
+
+```
+审计 {页面目录} --mode spec-align --spec docs/spec/{项目代号}/4.x-{子模块}.md
+```
+或自然语言：「检查 {页面} 是否跟说明书对齐」。
+
+### 比对维度
+
+| 维度 | 检查点 | 偏差判定 |
+|------|--------|---------|
+| 查询字段 | spec `query[]` vs 代码 `queryDef()` | spec 有代码缺 → 🔴 漏字段；代码多出 → 🟡 超出 spec |
+| 表格列 | spec `columns[]` vs 代码 `columnsDef()` | 同上，且顺序不一致 → 🟡 |
+| 工具栏 | spec `toolbar[]` vs 代码 `toolbarDef()` | 按钮缺失/多出 → 🔴/🟡 |
+| 表单字段 | spec `formSections[].fields[]` vs 弹窗组件 | 必填字段缺失 → 🔴 |
+| 接口 URL | spec 推算 URL vs 代码 `API_CONFIG` | 路径不一致 → 🟡 待确认 |
+| 权限码 | spec notes 权限码候选 vs 代码 v-permission | 未挂载 → 🟡，建议 permission-sync |
+
+### GAP 报告（reports/SPEC_GAP_{模块}_{日期}.md）
+
+```markdown
+# Spec 对齐 GAP 报告
+- 生成时间：{YYYY-MM-DD HH:mm}
+- spec 来源：docs/spec/{项目代号}/4.x-{子模块}.md
+- 代码范围：src/views/.../{页面}/
+
+## GAP 摘要
+- spec 字段总数：N  代码实现：N  漏：N  多：N  顺序不一致：N
+
+## 漏字段（spec 有、代码无 → 🔴）
+| # | 类型 | spec 字段 | 所在功能 | 建议 |
+|---|------|----------|---------|------|
+| 1 | query | customerType | PMMB001 | 补入查询项 |
+
+## 多余字段（代码有、spec 未定义 → 🟡）
+| # | 类型 | 代码字段 | 建议 |
+|---|------|----------|------|
+| 1 | column | remark | 确认是否需要，否则反馈 design 补 spec |
+
+## 下一步
+→ 漏字段交 code-fix / page-codegen 补齐；多余字段反馈上游 design 补 spec。
+```
+
+> spec 对齐模式**只对规范线生成的页面生效**；原型线（prototype-scan）生成的页面无 spec 基准，跳过本模式。

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

@@ -1,6 +1,6 @@
 ---
 name: prototype-scan
-description: "Use when: analyzing Axure exported HTML prototype files to extract page inventory, classify interaction patterns, identify reusable components, and produce a structured page checklist for Vue development. Also supports detailed design documents (MD/Word) or natural language descriptions as input. Triggers on: prototype analysis, axure scan, page inventory, 原型解析, 页面清单, axure转vue, 详设文档, design doc, 详细设计, 口述需求, 自然语言建页面, natural language page request, 建个页面, 写个页面, 口头描述页面."
+description: "Use when: analyzing Axure exported HTML prototype files to extract page inventory, classify interaction patterns, identify reusable components, and produce a structured page checklist for Vue development. Also supports NON-standard detailed design documents (free-form MD/Word) or natural language descriptions as input. DO NOT use for standard requirement-spec documents produced by wl-skills-design (path contains docs/spec/, has function codes like PMMB001, IPO tables, flow five-elements) — route those to spec-doc-parse instead. Triggers on: prototype analysis, axure scan, page inventory, 原型解析, 页面清单, axure转vue, 口述需求, 自然语言建页面, natural language page request, 建个页面, 写个页面, 口头描述页面."
 ---
 
 # Skill: 原型解析（prototype-scan）
@@ -15,7 +15,9 @@ description: "Use when: analyzing Axure exported HTML prototype files to extract
 |------|------|----------|
 | **模式 0（自然语言）** | 用户口述需求，无文件 | 日常对话："帮我建一个客户管理页面，有XX字段" |
 | **模式 A（Axure）** | Axure HTML 文件包目录 | 已有原型设计，AI 全量扫描 HTML |
-| **模式 B（详设文档）** | MD/Word/表格格式的详细设计文档 | 已有详细设计文档，AI 解析结构化字段 |
+| **模式 B（非规范详设）** | MD/Word/表格格式的零散详细设计 | 已有非规范详设文档，AI 解析结构化字段 |
+
+> ⚠️ **双线隔离（必读）**：本 Skill 走「原型线」。若输入是 wl-skills-design 产出的**标准需求设计说明书**（路径含 `docs/spec/`、含功能编码 `/[A-Z]{2,6}[0-9]{3}/`、含 IPO 表「处理逻辑」、含流程五要素），属于「规范线」，**禁止本 Skill 接管**，必须路由到 `core/spec-doc-parse/SKILL.md`。两线各自解析，最终都汇聚到同一份 page-spec JSON，下游 `api-contract` / `page-codegen` 无感知来源。
 
 ---
 
@@ -403,9 +405,13 @@ const [模块名]Module = gProd("[base-path]", {
 
 ---
 
-## 输入模式 B：详细设计文档
+## 输入模式 B：非规范详细设计文档
+
+> ⚠️ **模式 B 排除范围**：若文档路径含 `docs/spec/`，或文档内含 `§四 功能设计详细规范` / IPO 表格（含「处理逻辑」二级标题）/ 功能编码（正则 `/[A-Z]{2,6}[0-9]{3}/`）/ 流程说明五要素，
+> **表明这是 wl-skills-design 的标准产出，不触发本模式**，应转发 `core/spec-doc-parse/SKILL.md`。
+> 本模式只处理**非规范、零散的**详设（本来就不规范的输入，AI 自由发挥是帮助）；面对高精度规范文档时，专属解析才能保证零损耗。
 
-> 详设文档输入比 Axure HTML **精度更高（95-100%）**，因为字段名和类型是明确写出的，不需要从视觉推断。
+> 非规范详设输入比 Axure HTML **精度更高（95-100%）**，因为字段名和类型是明确写出的，不需要从视觉推断。
 > 输出格式与模式 A 完全一致（page-spec JSON），page-codegen 无感知。
 
 ### 为什么详设比 Axure 更精确

package/files/.github/skills/core/spec-doc-parse/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: spec-doc-parse
+description: "Use when: parsing STANDARD requirement-design specification documents produced by wl-skills-design (path contains docs/spec/, files like ch1-3.md / 4.x-{module}.md / 4.N-data-report.md, with function codes like PMMB001, IPO tables containing 处理逻辑, and flow descriptions with five-elements) into the SAME page-spec JSON consumed by page-codegen. This is the 规范线 (spec line) counterpart to prototype-scan (原型线). Self-validating, self-correcting, report-producing. Triggers on: 解析说明书, 解析需求文档, 解析详设, 规范文档转页面, 根据说明书生成, spec doc parse, IPO 转页面, docs/spec, 功能编码, 需求设计说明书."
+---
+
+# Skill: 规范文档解构（spec-doc-parse）
+
+将 **wl-skills-design 产出的标准《需求设计说明书》**（`docs/spec/{项目代号}/` 下的 `ch1-3.md` + `4.x-{子模块}.md` + `4.N-data-report.md`）解构为与 `prototype-scan` **完全相同格式的 page-spec JSON**，作为 `api-contract` / `page-codegen` 的输入。
+
+> **双线汇聚原则**：原型线（prototype-scan）和规范线（本 Skill）是两条独立的输入线，但**汇聚点只有一个 —— page-spec JSON + api.md**。下游 `page-codegen` 不感知来源，两线代码完全共享。
+> **职责边界**：design 负责「生成标准」，kit 负责「解构标准、完整读取」。本 Skill 是 kit 侧解构能力的承载者。
+
+---
+
+## 与 prototype-scan 的硬隔离（必读）
+
+| 维度 | prototype-scan（原型线） | spec-doc-parse（规范线） |
+|------|--------------------------|--------------------------|
+| 输入 | Axure HTML / 截图 / 口述 / **非规范**详设 | **wl-skills-design 标准说明书** |
+| 识别特征 | 视觉原型、自由格式文档 | `docs/spec/` 路径 / 功能编码 `/[A-Z]{2,6}[0-9]{3}/` / IPO 表「处理逻辑」/ 流程五要素 |
+| 解析方式 | 视觉/语义推断（精度 70-95%） | 规范结构精确映射（精度 95-100%） |
+| 禁区 | **不得处理** `docs/spec/` 标准文档 | **不接受** Axure HTML / 截图 |
+
+> 当用户输入命中规范线特征时，**强制走本 Skill**，禁止 prototype-scan 接管（见 `_registry.md` 调度规则「优先级 0」）。
+
+---
+
+## Pre-flight 声明（执行前必须输出）
+
+```
+🚀 已触发技能 spec-doc-parse/SKILL.md       → 规范文档解构：标准说明书 → page-spec JSON
+✅ 已读取 standards/index.md                 → 规范门控（任务类型：解析规范文档转页面）
+✅ 已读取 core/prototype-scan/SKILL.md       → page-spec JSON 结构定义（统一汇聚格式）
+✅ 已读取 standards/12-base-table.md         → AGGrid 列定义约束（供下游 page-codegen）
+✅ 已识别文档结构：{doc-skeleton 5 文件 / 单卷 / 单子模块}
+✅ 来源文件：{docs/spec/{项目代号}/...}
+✅ 输出：reports/SPEC_PARSE_{模块}_{日期}.md（page-spec JSON + 解析报告）
+✅ 不会生成代码（解析 + 报告，代码生成由 page-codegen 承接）
+```
+
+**结构不合规时（红叉 + 暂停）**：
+
+```
+❌ 文档结构校验失败：未找到 ch1-3.md 或任何 4.x-*.md，或文档不含功能编码/IPO 表
+   → 这可能不是 wl-skills-design 标准说明书
+   → 若为非规范详设，请改用 prototype-scan（原型线）
+   → ⛔ 解析已暂停
+```
+
+---
+
+## 前置检查
+
+```
+□ 文档来源路径：docs/spec/{项目代号}/
+□ 文件清单：ch1-3.md（概述）+ 4.x-{子模块}.md（详细设计）[+ 4.N-data-report.md]
+□ 目标项目路径：src/views/[域]/[模块]/[子模块]/
+□ 服务缩写：从功能编码前缀推断（pm / mmwr / mmsm / sale / hrms / base）
+□ 解析范围：整卷 / 指定子模块 / 指定功能编码
+```
+
+---
+
+## 解析流水线（9 步）
+
+```
+Step 1  结构识别    识别 doc-skeleton 5 文件结构，确认卷归属与子模块清单
+Step 2  章节拆解    按 4.x.y.z 编号解析  子模块 → 流程 → 功能
+Step 3  IPO 解析    每个 4.x.4.z 功能 → 提取「画面逻辑（原型）」+「处理逻辑（IPO）」
+Step 4  字段提取    从画面逻辑字段说明表提取 字段名/控件类型/必填/数据来源/校验规则
+Step 5  模式推断    根据「页面类型」映射到 prototype-scan 同款 pattern 枚举
+Step 6  接口推算    功能编码 → 服务缩写 → /{服务}/{资源CamelCase}/{操作}
+Step 7  权限提取    流程活动编码 [流程编码]-[E/C/M]-[NN] → v-permission code 候选
+Step 8  生成产物    输出与 prototype-scan 完全相同格式的 page-spec JSON
+Step 9  自验证+报告  Parse Validation 五项检查 + 自动修复 + 解析报告
+```
+
+---
+
+## Step 1 — 结构识别
+
+依据 `wl-skills-design` 的 `doc-skeleton.md` 5 文件结构识别：
+
+```
+docs/spec/{项目代号}/
+├── ch1-3.md              ← 第 1~3 章（总体概述、术语、范围）
+├── 4.1-{子模块名}.md     ← 子模块详细设计（流程 + IPO）
+├── 4.2-{子模块名}.md
+├── ...
+└── 4.N-data-report.md    ← 数据需求表 + 报表设计
+```
+
+- 从 `ch1-3.md` 提取：项目名称、项目代号、模块清单、术语表（供字段命名参考）
+- 从每个 `4.x-*.md` 提取：子模块编码、流程清单、功能清单
+- 从 `4.N-data-report.md` 提取：数据实体字段（**优先作为字段英文名权威来源**，减少推断）
+
+---
+
+## Step 2 — 章节拆解
+
+按 wl-skills-design 编号体系逐层拆解：
+
+| 层级 | 编号格式 | 含义 | 映射 |
+|------|---------|------|------|
+| 子模块 | `4.x` | 业务子模块 | 目录层 `[子模块]/` |
+| 流程 | `4.x.{流程编码}` | 业务流程 | 不直接出页面，提供活动 → 权限码 |
+| 功能 | `4.x.4.z`（功能编码 `[子模块代码][NNN]`） | 单个功能页面集 | **一个功能 → 1~N 个 page-spec** |
+
+---
+
+## Step 3 — IPO 表解析（核心）
+
+每个 `4.x.4.z` 功能包含两部分（对应 wl-skills-design `sub/03-function-ipo.md`）：
+
+### 3.1 画面逻辑（原型）→ 页面结构
+
+从「画面逻辑」小节的**字段说明表**提取：
+
+```
+| 字段名 | 控件类型 | 必填 | 数据来源 | 字段规则 |
+```
+
+映射到 page-spec：
+
+| 画面逻辑来源 | → page-spec 字段 | 说明 |
+|-------------|------------------|------|
+| 页面类型（列表页/新增页/修改页/详情页） | `pattern` | 见 Step 5 映射表 |
+| 列表页 - 搜索区字段 | `query[]` | 搜索条件一律「选填」 |
+| 列表页 - 操作按钮 | `toolbar[]` | 顺序严格保持 |
+| 列表页 - 显示列 | `columns[]` | 顺序严格保持 |
+| 列表页 - 操作列 | `operations[]` | 编辑/删除/查看/审批等 |
+| 新增/修改页 - 字段 | `formSections[].fields[]` | 含 required |
+| 字段控件类型 | `query/columns/fields.type` | 见 3.3 控件映射 |
+| 字段字典 | `dictCode` | 从字段规则/数据来源提取 |
+| 子表（明细表） | `subTables[]` | 含 editable/inlineEdit |
+
+### 3.2 处理逻辑（IPO）→ notes + 接口推算
+
+「处理逻辑」描述确认按钮三段式（数据校验 + 数据处理 + 触发事件），用于：
+
+- **触发事件** → `notes[]`（写入哪张表、推送哪个模块），并辅助 Step 6 接口路径命名
+- **数据校验** → 字段 `required` / 校验规则补充
+- 凡处理逻辑中标注 `【待确认：...】` → 原样保留进 `notes[]`，不得擅自填充
+
+### 3.3 控件类型 → page-spec type 映射
+
+| IPO 控件类型 | page-spec type | 补充 |
+|-------------|----------------|------|
+| 文本框 / 输入框 | `input` | — |
+| 下拉选择 | `dict` | 需 `dictCode` |
+| 单日期 | `date` | — |
+| 日期范围 | `dateRange` | 需 `startName`/`endName` |
+| 月份选择 | `month` | — |
+| 用户选择 | `userPicker` | — |
+| 部门选择 | `deptPicker` | — |
+| 文件上传 | `fileUpload` | — |
+
+---
+
+## Step 4 — 字段英文名提取（优先权威源）
+
+英文名来源优先级（高 → 低）：
+
+1. **`4.N-data-report.md` 数据实体字段**（权威，wl-skills-design 已定义）→ 直接采用
+2. IPO 表字段说明中显式英文名 → 直接采用
+3. 均无 → 从中文名推断 camelCase，`notes[]` 标注 `[推断英文名，请确认]`
+
+---
+
+## Step 5 — 交互模式推断
+
+复用 `prototype-scan` 同款 pattern 枚举（保证下游一致）：
+
+| 文档「页面类型」描述 | pattern |
+|---------------------|---------|
+| 列表页 / 查询页 / 管理页（默认） | `LIST` |
+| 主从 / 上下表 / 主表+明细 | `MASTER_DETAIL` |
+| 左树右表 / 树形分类 | `TREE_LIST` |
+| 多 Tab 详情 / 详情页 | `DETAIL_TABS` |
+| 独立路由表单 / 复杂表单 | `FORM_ROUTE` |
+| 变更历史 / 变更记录 | `CHANGE_HISTORY` |
+| 记录表单 / 无分页录入 | `RECORD_FORM` |
+| 工位 / 操作站 | `OPERATION_STATION` |
+
+无法判断 → 降级 `LIST`，`notes[]` 标注 `[降级 LIST，请核查]`。
+
+---
+
+## Step 6 — 接口路径推算
+
+功能编码前缀 → 服务缩写 → URL：
+
+```
+功能编码 PMMB001  →  前缀 PM  →  服务 pm  →  /pm/{资源CamelCase}/{操作}
+```
+
+| 服务缩写 | 含义 | 示例 |
+|---------|------|------|
+| pm | 生产管理 | `/pm/omptMillPlanOrder/list` |
+| mmwr | 精整作业 | `/mmwr/mmwrTechFinish/list` |
+| mmsm | 炼钢管理 | `/mmsm/mmsmRsltLadleUse/list` |
+| sale | 销售管理 | `/sale/saleOrder/list` |
+| hrms | 人力资源 | `/hrms/hrmsEmployee/list` |
+| base | 基础数据 | `/base/cmUserGroup/list` |
+
+> 仅生成 page-spec 与 api.md 草案的 URL 建议；真实接口契约由后续 `api-contract` Skill 落地。
+
+---
+
+## Step 7 — 权限码提取
+
+从子模块流程的活动编码提取 v-permission code 候选：
+
+```
+流程活动编码：[流程编码]-[操作类型]-[NN]    操作类型 E(在线展示)/C(创建)/M(修改)
+PMMB-A-01-E-01（查询目标列表）→ permission:pmmb:target:list
+PMMB-A-01-C-02（新增目标）     → permission:pmmb:target:add
+PMMB-A-01-M-03（修改目标）     → permission:pmmb:target:edit
+```
+
+权限码写入 page-spec `notes[]`，供后续 `permission-sync` Skill 注册。
+
+---
+
+## Step 8 — 生成 page-spec JSON
+
+输出格式**与 `core/prototype-scan/SKILL.md` 的 page-spec 结构完全一致**（字段名、层级、枚举均不变）。
+执行前必须先 `read_file` 加载 prototype-scan SKILL.md 的「输出格式：page-spec JSON」章节，按同一模板逐字段填充，**禁止用「等」「...」省略字段**。
+
+`notes[]` 中规范线特有的补充：
+
+```jsonc
+"notes": [
+  "[规范线] 来源：docs/spec/huaxin/4.1-target.md §4.1.4.1 PMMB001",
+  "[规范线] 权限码候选：permission:pmmb:target:list / :add / :edit",
+  "[规范线] 触发事件：提交后写入 bom_ratio 表并触发重算（见处理逻辑）",
+  "[待确认] status 字段 dictCode 推断为 target_status，需后端确认"
+]
+```
+
+---
+
+## Step 9 — 自验证 + 自修复 + 报告
+
+### 9.1 Parse Validation（五项检查）
+
+```
+□ 每个功能至少有一个页面类型声明（缺 → 降级 LIST + 标注）
+□ 输入字段都有控件类型（缺 → 从字段名推断 + 标注【推断，待确认】）
+□ 确认按钮有触发事件描述（缺 → notes 写【待确认：提交后触发哪些下游操作】）
+□ 活动编码符合 [流程编码]-[E/C/M]-[NN]（格式偏差 → 自动修复 + 报告差异）
+□ 服务缩写在已知列表（pm/mmwr/mmsm/sale/hrms/base）（不在 → BLOCK + 报告）
+```
+
+### 9.2 自动修复纠偏（Auto-Correction）
+
+| 发现问题 | 自动修复 | 报告标记 |
+|---------|---------|---------|
+| 活动编码用旧格式（仅 `E-NN` 无操作类型分位） | 对齐为 `[流程编码]-E-[NN]`（系统在线默认 E） | `[AUTO-FIX]` |
+| 字段英文名空白 | 优先取 data-report 实体字段，否则推断 camelCase | `notes` 追加 `[推断，请确认]` |
+| 页面类型无法映射 | 降级 `LIST` | `notes` 追加 `[降级，请核查]` |
+| dictCode 缺失 | 从字段名语义推断候选 | `notes` 追加 `[推断 dictCode，需后端确认]` |
+| 功能编码格式错误（不匹配 `/[A-Z]{2,6}[0-9]{3}/`） | **不自动修复**（编码是架构决策） | `[BLOCK]`，暂停该功能解析 |
+| 服务缩写未知 | **不自动修复** | `[BLOCK]`，列入报告待人工补充 |
+
+> 自动修复只处理**无损/可逆**问题；涉及架构决策（编码、服务划分、触发事件）一律 BLOCK 或 待确认，绝不捏造。
+
+### 9.3 解析报告（reports/SPEC_PARSE_{模块}_{日期}.md）
+
+```markdown
+# Spec-Doc Parse 报告
+- 生成时间：{YYYY-MM-DD HH:mm}
+- 来源文件：docs/spec/{项目代号}/4.x-{子模块}.md
+- 解析范围：{整卷 / 子模块 / 功能编码}
+
+## 解析摘要
+- 功能总数：N    成功：N    待确认：N    自动修复：N    阻断：N
+
+## 功能清单
+| 功能编码 | 功能名称 | 页面数 | page-spec | 状态 |
+|---------|---------|-------|-----------|------|
+| PMMB001 | BOM 钢种配比 | 2 | ✅ 生成 | ready |
+| PMMB002 | 目标管理 | 3 | ⚠️ 待确认 | 7 项待确认 |
+| PMMB003 | 计划管理 | 1 | ❌ 阻断 | 功能编码格式错误 |
+
+## 待确认清单
+| # | 功能 | 字段/项目 | 问题 | 建议 |
+|---|-----|----------|------|------|
+| 1 | PMMB001 | submitBtn.触发事件 | 未描述下游操作 | 请补充 |
+| 2 | PMMB002 | status.dictCode | 推断 target_status | 需后端确认 |
+
+## 自动修复记录
+| # | 位置 | 修复内容 |
+|---|------|---------|
+| 1 | PMMB001-A-01-E-01 | 活动编码格式已对齐新规范 |
+
+## 阻断清单（需人工处理）
+| # | 功能 | 原因 |
+|---|-----|------|
+| 1 | PMMB003 | 功能编码格式错误，不符合 [子模块代码][NNN] |
+```
+
+---
+
+## 完成摘要（执行结束后输出）
+
+```
+## 完成摘要
+- 产物：reports/SPEC_PARSE_{模块}_{日期}.md（含 page-spec JSON 数组）
+- 关键数据：功能 N 个 / 页面 N 个 / 待确认 N 项 / 自动修复 N 项 / 阻断 N 项
+- 风险：{阻断项与待确认项需人工确认后再进 page-codegen}
+
+## 建议下一步
+- next_suggest：先处理阻断项与待确认项 → api-contract（生成 api.md）→ page-codegen
+- 原因：page-spec 已就绪，可进入接口约定与代码生成
+- 是否需要用户确认：是
+```
+
+---
+
+## 闭环验证（与 convention-audit 联动）
+
+解析产出可被 `convention-audit` 的「spec 对齐扫描」模式回扫：
+
+```
+spec-doc-parse 输出 page-spec JSON
+  → page-codegen 生成代码
+  → convention-audit --mode spec-align（比对 spec 字段 vs 代码字段）
+  → 输出 GAP 报告（spec 中有但代码缺失的字段 / 代码多出 spec 未定义的字段）
+```
+
+详见 `core/convention-audit/SKILL.md` §「spec 对齐扫描（GAP 报告）」。

package/files/.github/skills/core/spec-doc-parse/USAGE.md

@@ -0,0 +1,97 @@
+# 使用指南：spec-doc-parse（规范文档解构）
+
+> **谁读这个文档**：团队成员（产品/前端/后端）
+> **AI 触发文件**：同目录 `SKILL.md`（无需手动阅读）
+
+---
+
+## 这个 Skill 解决什么问题
+
+把 **wl-skills-design 产出的标准《需求设计说明书》**（`docs/spec/` 下的 IPO 表、功能编码、流程五要素）**完整解构**为一份《页面清单》（page-spec JSON），作为后续 `api-contract` 和 `page-codegen` 的输入。
+
+一句话：**design 负责「写标准文档」，spec-doc-parse 负责「读懂标准文档、转成可生成代码的结构」。**
+
+---
+
+## 双线分工（重要）
+
+团队里有两条独立的输入线，**互不污染**：
+
+| 线 | Skill | 输入 | 何时用 |
+|----|-------|------|--------|
+| **原型线** | `prototype-scan` | Axure 原型 / 截图 / 口述 / 零散详设 | 只有原型、没有规范文档时 |
+| **规范线** | `spec-doc-parse`（本 Skill） | wl-skills-design 标准说明书 | 已有 `docs/spec/` 标准文档时 |
+
+> 两条线最终都汇聚到**同一份 page-spec JSON**，下游代码生成完全一样。
+> 所以：**有标准说明书就走规范线，精度最高（95-100%）；只有原型走原型线。**
+
+---
+
+## 何时使用
+
+- 拿到 wl-skills-design 生成的 `docs/spec/{项目代号}/4.x-xxx.md`，要把它变成页面
+- 说明书里有功能编码（如 PMMB001）、IPO 表、流程图说明
+- 想把整卷说明书一次性解构成页面清单，再批量生成代码
+
+---
+
+## 触发关键词
+
+`解析说明书` / `解析需求文档` / `规范文档转页面` / `根据说明书生成` / `IPO 转页面` / `功能编码`
+
+---
+
+## 标准对话示例
+
+### 示例 1：解析单个子模块
+
+```
+你：解析 docs/spec/huaxin/4.1-target.md，生成页面清单。
+AI：[读取 SKILL.md → 输出 Pre-flight]
+    Pre-flight：
+    ├─ 识别结构：doc-skeleton 单子模块（4.1 目标管理）
+    ├─ 来源：docs/spec/huaxin/4.1-target.md
+    ├─ 输出：reports/SPEC_PARSE_target_20260531.md
+    └─ 不会生成代码
+    [解析中...]
+    完成，解析报告：
+    - 功能 3 个 / 页面 5 个 / 待确认 2 项 / 自动修复 1 项 / 阻断 0 项
+    请确认 2 项待确认后进入 api-contract。
+```
+
+### 示例 2：误用原型线的自动纠偏
+
+```
+你：扫描 docs/spec/huaxin/4.1-target.md 生成页面。
+AI：检测到输入是 wl-skills-design 标准说明书（含功能编码 + IPO 表）。
+    → 这属于「规范线」，已自动切换到 spec-doc-parse（精度更高）。
+    [继续按规范线解析]
+```
+
+---
+
+## 它会产出什么
+
+1. **page-spec JSON**（与 prototype-scan 同格式）—— 喂给 page-codegen 直接生成 Vue 页面
+2. **解析报告**（`reports/SPEC_PARSE_*.md`）—— 功能清单 + 待确认清单 + 自动修复记录 + 阻断清单
+3. **权限码候选**（写在 notes）—— 供 permission-sync 注册
+
+---
+
+## 自闭环能力（这个 Skill 的特点）
+
+| 能力 | 说明 |
+|------|------|
+| **自验证** | Pre-flight 校验文档结构 + Parse Validation 五项检查 |
+| **自修复** | 活动编码旧格式、英文名空白、dictCode 缺失等无损问题自动修正 |
+| **纠偏** | 架构性问题（功能编码错误、未知服务缩写）不捏造，标记 BLOCK |
+| **报告** | 每次解析输出完整报告，待确认/阻断项可追溯 |
+| **闭环** | 产物可被 convention-audit 的 spec 对齐模式回扫，生成 GAP 报告 |
+
+---
+
+## 边界提醒
+
+- 本 Skill **不处理** Axure 原型、截图 —— 那是 `prototype-scan` 的职责
+- 本 Skill **不生成代码** —— 代码由 `page-codegen` 承接
+- 本 Skill **不捏造**架构决策 —— 触发事件、接口、编码缺失一律标注待确认

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.9.4",
-  "description": "AI Skill 模板包 v2.9.4  — 14 条编码规范 + 10 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
+  "version": "2.10.0",
+  "description": "AI Skill 模板包 v2.10.0  — 14 条编码规范 + 11 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
     "wl-skills": "bin/wl-skills.js"