| name | convention-audit |
| description | Use when: auditing project source code against the 14 modular standards in .wl-skills/standards/. Outputs deviation report and component-extraction suggestions to reports/. Triggers on: 规范审计, 规范检查, 代码审计, 对齐规范, 规范偏差, 接手新项目, 存量代码分析, 项目体检, audit code, check conventions, onboard project. |
Skill: 规范审计（convention-audit）v2
以 .wl-skills/standards/ 14 条规范为唯一基线，扫描项目源码，输出偏差报告和组件提取建议到 reports/ 目录。
核心理念：审查全覆盖、结果强量化、规则场景化、新增严格 + 存量渐进。
本 Skill 只负责发现偏差并给出整改建议，不自动修复（修复由 code-fix Skill 完成）。
触发词
规范审计 / 规范检查 / 代码审计 / 对齐规范 / 规范偏差 / audit code
Pre-flight 声明（执行前必须输出）
🚀 已触发技能 convention-audit/SKILL.md → 规范审计：扫描源码 + 偏差报告 + 提取建议
✅ 已读取 standards/index.md → 规范门控
✅ 已读取 standards/01 ~ 14 → 完整 14 条规范基线（审计场景需全量加载）
✅ 已读取 reports/规范审查报告.md → 现有报告（用于追加，不覆盖）
✅ 审计范围：{用户指定的目录或单文件}
✅ 工具链检测：ESLint {状态} / tsc {状态} / Husky {状态}
适用场景
| 场景 | 说明 |
|---|
| 新项目导入 wl-skills-kit 后 | 扫描旧代码，输出整改清单，逐步迁移 |
| 日常 Code Review 辅助 | 比对单文件或目录，快速发现偏差 |
| 项目迁移/升级 | 老项目引入新架构，批量评估改造量 |
| 团队培训 | 新成员提交代码前，用审计验证是否符合规范 |
| page-codegen 后置自检 | 页面生成完成后自动跑一次审计，确认合规 |
| 修复闭环复扫 | code-fix 修复后复扫，生成前后对比 |
| CI/CD（PLANNED） | PR 上自动跑审计，不合规 PR 阻断合并 |
复扫模式（--quick，v2.11+ 新增）
闭环专用：code-fix 修复后快速验证，不做全量 14 条扫描，仅复查上次报告中的 🔴🟡 项。
触发方式
复扫验证 / 复扫上次审计 / convention-audit --quick / 确认修复效果
执行逻辑
- 读取
reports/规范审查报告.md 最新章节中的 🔴🟡 偏差清单
- 仅对这些偏差涉及的文件重新检测（不扫描全项目）
- 对比上次报告数据，输出变化矩阵
- 追加复扫结果到报告
复扫报告格式
## 🔄 复扫 {YYYY-MM-DD HH:mm} | 触发：code-fix 后自动复扫
| 指标 | 修复前 | 修复后 | 变化 |
|---|---:|---:|---|
| 🔴 严重 | {N} | {N} | {-N} ✅ |
| 🟡 警告 | {N} | {N} | {-N} ✅ |
| 未解决 | - | {N} | 待处理 |
### 结论
- ✔ 闭环完成，可提交
- 或：✖ 仍有 {N} 个未解决项，建议继续处理
与全量审计的区别
| 全量审计 | --quick 复扫 |
|---|
| 规范覆盖 | 14 条全部 | 仅上次报告中的偏差项 |
| 扫描范围 | 指定目录或全项目 | 仅偏差涉及文件 |
| token 消耗 | 高 | 低（约全量的 10%） |
| 适用场景 | 首次体检/定期审计 | code-fix 后闭环验证 |
| 输出 | 完整报告 12 章 | 复扫对比矩阵 |
审计范围（14 条规范全覆盖）
审计方式分层
| 方式 | 说明 |
|---|
| 静态扫描 | 文件存在性检测、正则匹配（高可信度） |
| 工具链委托 | ESLint / tsc --noEmit / Git 命令（高可信度，不浪费 AI 算力） |
| AI 场景判断 | 页面类型识别、豁免判定（中可信度，需人工确认） |
14 条规范审计维度
| 编号 | 审计维度 | 审计方式 | 严重度判定 |
|---|
| 01 | 工具链就绪 | 静态扫描 | 缺少 .prettierrc.js / eslint.config.ts / .husky/ → 🔴 |
| 02 | 三文件分离 + 接口契约 | 静态 + AI 场景判断 | 应拆未拆 data.ts → 🔴（新增）/🟡（存量）；api.md 缺失见场景规则；index.vue 含业务逻辑 → 🔴/🟡；段落顺序乱 → 🟡 |
| 03 | 注释规范 | 静态扫描 | 死代码注释 → 🟡；TODO 不规范 → 🟡；显而易见注释 → 🟢；文件头缺失 → 🟢 |
| 04 | 基础编码（14 条） | ESLint + 静态扫描 | var / for...in / 字符串拼接 / .then() / ::v-deep → 🟡 |
| 05 | console 残留 | 静态扫描 | src/ 下无守卫的 console → 🟡 |
| 06 | 安全规范 | 静态扫描 | v-html 无注释 / import axios / eval / new Function → 🔴 |
| 07 | 配置管理 | 静态扫描 | 硬编码 http:// IP → 🔴；API 路径散落 → 🟡 |
| 08 | Git 规范 | Git 命令 + 文件检测 | 工具链缺失 → 🔴；分支名不规范 → 🟡；近期提交不规范 → 🟡；历史 → 🟢 |
| 09 | TypeScript 类型 + 类型错误 | K14（vue-tsc/tsc 委托）+ AI | 类型检查器缺失 → 🔴；vue-tsc --noEmit 非 0 → 🔴；any 滥用 → 🟡 |
| 10 | Pinia | 静态扫描 | data.ts 内 import Store → 🔴 |
| 11 | 表单校验 | AI 场景判断 | FORM_ROUTE 缺 validate / resetFields → 🔴 |
| 12 | BaseTable + cid | 静态 + 场景判断 | 主列表用 el-table → 🔴；cid 缺失/重复 → 🔴；弹窗小表格见豁免规则 |
| 13 | 平台组件合规 | 静态扫描 | 业务页面用 el-form/el-table/el-date-picker 替代封装 → 🔴；封装组件内部 → ⚠️ 待确认；3+ 复用 → 提取建议 |
| 14 | 布局容器 | 静态扫描 | 分栏未使用 jh-drag-row/jh-drag-col → 🔴 |
目录分层审查
不同目录类型适用不同规则强度，避免封装组件内部与业务页面混淆。
| 目录 | 规则强度 | 说明 |
|---|
src/views/** | 最严格 | 业务页面，全规范覆盖 |
src/components/local/** | 中等 | 业务封装组件，检查复用性、命名和组件锁状态 |
.wl-skills/src/components/**（模板/文档） | 宽松 | 禁止被运行时直接引用；不套页面三文件原则 |
新增 vs 存量代码区分
| 类型 | 处理策略 |
|---|
| 新增页面（AI 生成 / 手动新增） | 必须全规约，阻断项严格执行 |
| 本次修改页面 | 不新增违规，触碰范围内尽量修 |
| 存量未触碰页面 | 报告记录，后续治理，不阻断 |
执行流程
步骤 1：确定审计范围
| 用户输入 | 范围 |
|---|
| "审计整个项目" | src/views/ |
| "审计 produce/mmwr" | 该子目录 |
| "审计 mmwr-customer-archive 页面" | 单页面文件 |
步骤 2：加载规范基线 + 工具链检测
- 读取
standards/01 ~ 14 全部规范文件
- 检测工具链状态：
- ESLint：是否可执行
- TypeScript：
vue-tsc --noEmit（回退 tsc --noEmit）是否可执行、是否 0 error（K14）
- Git：当前分支 / 最近提交
- Husky：
.husky/pre-commit、.husky/pre-push、.husky/commit-msg 是否存在
- 读取
package.json 获取项目脚本名称
- 读取豁免配置（v2.11.4+）：如项目根存在
.wl-skills-validate.json，解析其中所有豁免条目（paths / rules / reason），在报告中单列"豁免项复核清单"，供人工逐条确认是否仍需豁免
步骤 3：扫描源码
逐个文件检查 14 个维度。同时记录：
- 扫描统计：目录数、文件数、页面数、类型分布
- 跨页面相同 el-* 模式（统计出现次数和位置）
- 每个偏差所在文件的菜单位置（从 koroFileHeader 文件头注释解析）
- 页面类型识别：判断是否需要
data.ts、api.md，是否属于豁免场景
- code-fix 能力评估：每个偏差标注是否可自动修复
步骤 4：追加写入两份报告
报告 A：reports/规范审查报告.md（追加，最新章节在顶）
## 🕐 {YYYY-MM-DD HH:mm} | 范围：{范围} | 触发：{user / page-codegen / CI}
### 1. 扫描范围与数据量
| 指标 | 值 |
|---|---|
| 扫描根目录 | {路径} |
| 扫描目录数 | {N} |
| 扫描文件数 | {N} |
| Vue 文件数 | {N} |
| TS/JS 文件数 | {N} |
| SCSS/CSS 文件数 | {N} |
| 业务页面目录数 | {N} |
| 豁免/不适用页面数 | {N} |
### 2. 工具链与 Git 状态
| 项目 | 状态 |
|---|---|
| ESLint | {已配置 / 未配置 / 执行失败} |
| Prettier | {.prettierrc.js 存在 / 缺失} |
| TypeScript | {tsc 可用 / 不可用} |
| Husky | {pre-commit ✓ commit-msg ✓ / 缺失} |
| @robot-admin/git-standards | {已初始化 / 未安装} |
| 当前分支 | {分支名} — {符合规范 / 不符合规范} |
| 最近提交规范性 | {N}/{总数} 条符合 type(scope): 格式 |
### 3. 14 条规范覆盖矩阵
| 规范 | 审查方式 | 结果 | 🔴 | 🟡 | 🟢 |
|---|---|---|---:|---:|---:|
| 01 工具链 | 文件检测 | {结果} | {N} | {N} | {N} |
| 02 结构 | 静态+AI | {结果} | {N} | {N} | {N} |
| 03 注释 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 04 基础编码 | ESLint/静态 | {结果} | {N} | {N} | {N} |
| 05 日志 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 06 安全 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 07 配置 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 08 Git | Git+文件 | {结果} | {N} | {N} | {N} |
| 09 TS | tsc/ESLint | {结果} | {N} | {N} | {N} |
| 10 Pinia | 静态扫描 | {结果} | {N} | {N} | {N} |
| 11 表单校验 | 场景扫描 | {结果} | {N} | {N} | {N} |
| 12 BaseTable | 静态+场景 | {结果} | {N} | {N} | {N} |
| 13 平台组件 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 14 布局容器 | 静态扫描 | {结果} | {N} | {N} | {N} |
### 4. 🔴 严重偏差（必须整改）
#### {编号}. 违反规范 {XX}（{规范名}）— {问题描述}
- **影响文件数**：{N}
- **出现次数**：{N}
- **菜单位置**（来自文件头）：{位置}
- **现状**：{描述}
- **应为**：{描述}
- **整改建议**：{建议}
- **自动修复**：{✅ 可自动修 / ⚠️ 需确认 / ❌ 人工处理}
- **涉及文件 Top N**：
1. `src/views/.../index.vue` — {N} 处
2. ...
（按规范条目分组列出全部偏差）
### 5. 🟡 警告偏差（建议整改）
（同格式，增加自动修复标记）
### 6. 🟢 提示与后续关注
（注释、TS 类型优化、存量历史问题等）
### 7. 豁免 / 不适用清单
| 文件/目录 | 规则 | 原因 | 结论 |
|---|---|---|---|
| {路径} | data.ts | 纯静态说明页 | 不适用 |
| {路径} | api.md | 无接口调用 | 豁免 |
| {路径} | AGGrid | 弹窗小型明细表 | 待人工确认 |
| {路径} | el-dialog | 封装组件内部实现 | 合理 |
| 问题 | 影响文件数 | 自动修复 | 建议 |
|---|---:|---|---|
| console 清理 | {N} | ✅ | 本轮修复 |
| var → const/let | {N} | ✅ | 本轮修复 |
| ::v-deep → :deep() | {N} | ✅ | 本轮修复 |
| BaseTable 缺 cid | {N} | ✅ | 本轮修复 |
| 简单 .then() → async/await | {N} | ⚠️ | 需确认 |
| 问题 | 原因 | 建议时间 |
|---|---|---|
| 存量页面迁移 data.ts | 大规模重构 | 按模块渐进 |
| el-table 全量迁移 | 需逐页面验证 | P1 分批 |
| 存量 api.md 补齐 | 非阻断项 | 后续补充 |
| 模块目录 | 🔴 | 🟡 | 🟢 | 合计 | 建议 |
|---|---:|---:|---:|---:|---|
| {模块路径}/ | {N} | {N} | {N} | {N} | {建议} |
| 优先级 | 整改项 | 建议方式 |
|---|---|---|
| P0 | {工具链缺失项} | 先备份配置，再初始化 |
| P1 | {严重偏差项} | code-fix / 立即修复 |
| P2 | {警告偏差项} | 分批修 |
| P3 | {存量治理项} | 渐进迁移 |
| 指标 | 本次值 | 上次值 | 变化 |
|---|---:|---:|---|
| 🔴 严重 | {N} | {N/-} | {±N} |
| 🟡 警告 | {N} | {N/-} | {±N} |
| el-table 文件数 | {N} | {N/-} | {±N} |
| console 文件数 | {N} | {N/-} | {±N} |
---
（历史章节自然下沉）
报告 B：reports/组件提取建议.md（追加）
## 🕐 {YYYY-MM-DD HH:mm} | 范围：{范围}
### 📦 组件提取建议（共 N 处）
| 建议组件名 | 出现次数 | 页面路径 | 菜单位置 | 模式描述 |
|---|---|---|---|---|
| c_statusBadge | 5 处 | src/views/sale/.../{a,b,c,d,e}/index.vue | 销售管理 > 多个子菜单 | 状态枚举彩色标签 |
> ⚠️ 以上为建议，不自动提取。
> 人工确认后，触发 `template-extract` Skill（页面级模板）或手动封装为 `c_*` 组件。
步骤 5：输出摘要
📦 审计完成
─────────────────────────────────────────────────────
📊 扫描：{N} 个目录 / {N} 个文件 / {N} 个业务页面
✅ reports/规范审查报告.md → 已追加（🔴{N} 🟡{N} 🟢{N}）
✅ reports/组件提取建议.md → 已追加 {M} 条
─────────────────────────────────────────────────────
📌 后续步骤：
1. 人工 review 报告，确认豁免清单和修复优先级
2. 触发 code-fix 修复"本次建议修复清单"中 ✅ 项
3. 需确认项（⚠️）人工评审后决定是否 code-fix
4. 提取建议人工评审 → template-extract 或手动封装
5. 修复后复扫，生成前后对比指标
6. 所有修复提交使用 git cz，确保 Git 规范合规
─────────────────────────────────────────────────────
偏差严重度定义
| 级别 | 标记 | 定义 | 自动修复 |
|---|
| 🔴 | 严重 | 架构性违反，影响可维护性 / 安全 / 团队协作 | 部分可自动修，部分需人工 |
| 🟡 | 警告 | 风格不统一 / 最佳实践偏离，不影响功能 | 大部分可自动修 |
| 🟢 | 提示 | 优化建议，可逐步改进 | 按需 |
code-fix 能力标记
| 标记 | 含义 | 处理方式 |
|---|
| ✅ 可自动修复 | 模式明确、风险低 | 直接交给 code-fix |
| ⚠️ 需确认后修复 | 有业务风险 | 人工确认后 code-fix |
| ❌ 人工处理 | 需要理解业务 | 不自动修 |
| 👀 后续关注 | 本轮不修 | 持续观察 |
阻断条件
以下问题视为阻断项，修复闭环前必须解决：
- 工具链缺失（husky / commitlint / prettierrc / eslint）
- 新增 AI 页面缺
api.md
- 新增业务页面应拆未拆
data.ts
- 新增页面主列表使用
el-table
- 明显安全问题：
eval、未声明的 v-html、硬编码 secret
- 修复后提交不符合 Git 规范
以下问题不阻断，作为后续治理：
- 注释规范问题
- 存量复杂页面缺
api.md
- 存量页面未拆
data.ts
- 部分 TS
any
- 历史提交信息不规范
- 弹窗小表格 AGGrid 待确认
- 弹窗内 AG Grid 缺少 v-if 延迟挂载（K19，自动检测）
报告可信度说明
审计报告应在概要处标注各检查方式的可信度，便于人工评审。
| 检查类型 | 可信度 |
|---|
| 文件是否存在 | 高 |
| 正则匹配（el-table / console / var 等） | 高 |
| 工具链输出（ESLint / tsc） | 高 |
| Git 提交历史 | 高 |
| 页面是否需要 data.ts | 中（需人工确认） |
| AGGrid 是否适配弹窗表格 | 中（需人工确认） |
| 弹窗内 AGGrid 是否有 v-if 延迟挂载 | 高（K19 自动检测） |
| 复杂业务逻辑是否应提取 | 中 |
与其他 Skill 的关系
| Skill | 关系 |
|---|
| page-codegen | 审计发现偏差后，可调用 page-codegen 重新生成合规代码 |
| template-extract | 审计输出的"组件提取建议"，确认后可触发 template-extract |
| code-fix | 审计报告中 ✅/⚠️ 标记项作为修复输入 |
| spec-doc-parse | 提供 spec 对齐模式的基准：用规范线解析出的 page-spec 与生成代码比对，输出 GAP 报告 |
| CI/CD | 审计可作为 PR 检查项，不合规 PR 阻断合并 |
注意事项
- 规范基线唯一：以
standards/index.md 加载的 14 条文件为准，不接受"旧代码一直这么写"的辩解
- 追加不覆盖：每次审计追加新章节到报告，不删除历史，便于追溯整改进度
- 菜单位置解析：依赖 koroFileHeader 文件头注释，缺失文件头时标记
菜单位置：未知
- AI 自我审计：page-codegen 生成代码后，建议立即跑一次单页审计验证合规
- 工具链优先：TS 类型 / ESLint 规则优先借助工具链扫描，AI 负责监督验证和归类，不浪费算力逐文件做语义分析
- 场景化判定：
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 .wl-skills/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）
# Spec 对齐 GAP 报告
- 生成时间：{YYYY-MM-DD HH:mm}
- spec 来源：.wl-skills/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 基准，跳过本模式。
