巡检系统全景诊断与改进方案

2026-06-26 · 基于代码全链路审计

一、现状全景：4 套并行巡检体系

BossAgents 当前存在 4 套独立的巡检/检查体系，彼此重叠、数据源不同、调度方式各异：

1.1 AI Inspector（ai-inspector.js）— 主力巡检引擎

1.2 HealthPatrol + HealthScanner（health-patrol.js）— 新一代评分引擎

1.3 合规性巡检（compliance-inspector.js）— 早期原型

1.4 一致性巡检（consistency-check.js）— 轻量工具

1.5 各种 check-*.js 脚本 — 零散工具

• check-bom-structure.js、check-template.js、check-test-parts-deps.js
• check-encoding.js、check-syntax.js、inspect-db.js、inspect-def.js、inspect-err.js、inspect-sections.js、inspect.js
• scripts/check-quality-itemtypes.js
• tools/check-multi-level-bom.js、tools/_check-v2-imports.js

数了数 至少 14 个独立检查脚本/工具，分散在 4 个目录下，无统一调用入口。

二、核心问题诊断

🔴 P0：4 套巡检体系相互孤立，数据源不一致

| 巡检体系 | SCSAI 实时数据 | sciot_import.db | 其他数据库 |

|---|---|---|---|

| AI Inspector | ✅ 实时拉取 | ✅ 读规则 | — |

| HealthPatrol | ❌ 不调 | ✅ 主数据源 | core_runtime.db / enterprise_store.db |

| ComplianceInspector | ❌ | ❌ | aml_store.db（独立） |

| ConsistencyCheck | ❌ | ✅ | — |

后果：对同一个 ItemType（如 Part），AI Inspector 报告"必须有中文标签"（实时 SCSAI），HealthScanner 评分完整性维度（本地缓存），结果可能矛盾。

🔴 P1：四条巡检路线分裂，职责边界不清晰

AI Inspector（ai-inspector.js）
├─ 规则来自 sciot_rules_v2（与 aml.js CRUD 共用）
├─ 数据来自 SCSAI API（实时）
├─ 目标：单个 ItemType / 全量对象的规则命中检查

HealthPatrol（health-patrol.js）
├─ 规则来自 EnterpriseRules（独立 enterprise_store.db）
├─ 数据来自本地 3 DB（离线）
├─ 目标：6维健康度评分 + 定性定级

ComplianceInspector（compliance-inspector.js）
├─ 规则硬编码
├─ 数据来自 aml_store.db（被遗忘的数据库）
├─ 目标：基础物料合规

ConsistencyCheck（consistency-check.js）
├─ 规则硬编码
├─ 数据来自 sciot_import.db（同集不同库）
├─ 目标：数据层完整性

🔴 P1：数据库访问方式三套并存，混乱

| 模式 | 使用方 | 是否统一 |

|---|---|---|

| db-adapter → .preare/.get/.all/.run/.save | consistency-check.js, enterprise-rules.js, health-scanner.js | ✅ |

| sqlite-compat → .preare/.get/.all/.run/.save | ai-inspector.js 的 getDb() + getSciotDb() | ⚠️ 同名但不同模块 |

| 直接 sql.js → new SQL.Database() + .exec() | ai-inspector.js 的 getSciotDb()（异步 sql.js 路径） | ❌ |

🟡 P2：前端完全没有巡检 UI

• frontend/app.js 中搜索 ai-inspector、health-patrol、巡检结果 均为空
• 数字员工页面（DigitalStaff.vue/管理页面）无巡检按钮或巡检结果面板
• AI Inspector 的 SSE 流式能力无人消费
• 数据集市 (app.js:2624-2655) 有一个"检验记录"Tab，但那是质量管理的 inspection（进货检验），非对象模型巡检

🟡 P2：AI Inspector 的数据模型与前端不分离

• 巡检规则直接硬编码在 ai-inspector.js 中（DEFAULT_MODEL_RULES + DEFAULT_INSTANCE_RULES），与 sciot_rules_v2 表的数据库规则两套系统
• DEFAULT_MODEL_RULES 写入 sciot_rules_v2（initBuiltinRules()），但写时用 INSERT OR IGNORE，更新代码规则时必须手动清理旧数据
• 修复脚本中 generateFixAML() 写死了 7 种 add_property:xxx 映射，扩展需改代码

🟡 P2：HealthPatrol 已准备好但无集成点

• enterprise-rules.js 提供了完整的 validateType() 接口，可与 AI Inspector 结合
• health-scanner.js 6 维评分体系比 AI Inspector 更结构化
• correction-learner.js 存在但未被任何代码引用

🟢 P3：ComplianceInspector 应废弃或重写

• 依赖 aml_store.db 的 parts/ecr 表，这些表大概率不存在
• 功能完全被 AI Inspector 的 instance 巡检覆盖

🟢 P3：零散 check-*.js 脚本管理缺失

• 14 个脚本无统一入口，多数不知道谁调用、何时调用
• 部分脚本（check-encoding.js、check-syntax.js）可能已被 workflow pipeline 取代

三、改进方案（分三阶段）

Phase 0：统一数据访问（1天）

目标：消除 DB 访问混乱

Before:
  ai-inspector.js ─── sqlite-compat (同步) + sql.js (异步)
  consistency-check ── db-adapter
  health-scanner ──── db-adapter
  enterprise-rules ── db-adapter

After:
  全系统统一使用 /server/db-adapter
  同步：createDatabase(path) 返回 compatible handle
  异步：createAsyncDatabase(path) 按需

具体改动：

1. ai-inspector.js 的 getDb() 和 getSciotDb() 改为统一调用 db-adapter
2. 移除 initSqlJsOnce() 和 _sqlJsReady 惰性初始化
3. 统一 consistency-check.js 的 getSciotDb() 指向同一个数据库实例

Phase 1：巡检引擎合并（2天）

目标：AI Inspector 吸收 HealthPatrol，统一巡检体系

改造路线：

AI Inspector v5.0 ─────┬─ SCSAI API 实时检查（现有规则引擎）
                      ├─ HealthScanner 离线评分（新增集成）
                      ├─ EnterpriseRules 企业合规（新增集成）
                      └─ CorrectionLearner 学习闭环（新增集成）

关键改动：

1. 规则统一

• DEFAULT_MODEL_RULES 从代码中移出，改为数据库初始化 seed
• initBuiltinRules() 升级为可更新（删除旧版重写），支持版本号
• EnterpriseRules 的 validateType() 作为独立维度集成（不覆盖已有规则）

1. 巡检结果合并

• AI Inspector 返回 issues[]（规则命中），新增 scores{}（6维健康度）
• 巡检日志表 inspection_logs 增加 avg_score 字段
• 前端既可看规则命中，也可看健康度趋势

1. 合规废弃

• 删除 compliance-inspector.js（被 AI Inspector instance 巡检完全覆盖）
• 收集零散 check-*.js 脚本，有必要的并入 AI Inspector 规则库

Phase 2：前端巡检面板（3天）

目标：数字员工页面可获得完整的巡检体验

新增前端组件：

数字员工页面
├─ 员工列表（已有）
├─ 任务看板（已有）
└─ 🆕 巡检结果面板
    ├─ 报告概览：健康度总分 + 等级分布 + 趋势图
    ├─ 问题列表：按严重程度/类型/对象类分组
    │   └─ 每项：规则名、描述、自动修复按钮 / 手动处理提示
    ├─ 历史记录：过去 N 次巡检对比
    └─ 立即巡检按钮 → 调用 /api/ai-inspector/inspect-stream
  
数据集市（可选）
├─ 对象类健康度排名
├─ 规则命中统计 TOP 10
└─ 修复成功率趋势

API 新增/增强：

• GET /api/digital-staff/inspection/latest — 获取最近一次巡检摘要
• GET /api/digital-staff/inspection/trend?days=30 — 健康度趋势
• POST /api/digital-staff/run-inspection — 触发巡检（DS-BOSS-002 调度）

四、统一巡检架构（目标状态）

┌─────────────────────────────────────────────────────┐
│                  数字员工调度器                       │
│            (Cron / 手动 / 事件触发)                  │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│              UnifiedInspectionEngine                 │
│  (ai-inspector.js 升级，吸收三套引擎)                 │
├──────────────────────────────────────────────────────┤
│  ┌────────────────────┐  ┌────────────────────────┐ │
│  │ 规则引擎 (Rules)    │  │ 评分引擎 (Scorer)      │ │
│  │ • sciot_rules_v2   │  │ • HealthScanner 6维    │ │
│  │ • 硬编码内置规则    │  │ • EnterpriseRules 校验  │ │
│  │ • 用户自定义规则    │  │ • 行业模板基准          │ │
│  └────────┬───────────┘  └────────┬───────────────┘ │
│           │                       │                  │
│  ┌────────▼───────────────────────▼───────────────┐  │
│  │          修复引擎 (Fixer)                       │  │
│  │  • AML 自动修复     • LLM 诊断修复              │  │
│  │  • Correction Learner 学习                      │  │
│  └────────────────────┬───────────────────────────┘  │
│                       │                              │
│  ┌────────────────────▼───────────────────────────┐  │
│  │          审计日志 + 趋势存储                     │  │
│  │  inspection_logs + inspection_issues            │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘
           │                    │
           ▼                    ▼
     SCSAI API(实时)     本地 DB(离线评分)

数据流

触发巡检
  │
  ├─ scope=model（对象模型）
  │   ├─ 从 SCSAI 获取全部 ItemType
  │   ├─ 逐 ItemType 检查规则命中（规则引擎）
  │   ├─ 逐 ItemType 计算 6 维评分（评分引擎）
  │   └─ 结果合并：issues[] + scores{}
  │
  ├─ scope=instance（业务实例）
  │   ├─ 从 SCSAI 获取指定 ItemType 的实例
  │   ├─ 逐实例检查规则命中（规则引擎）
  │   └─ 统计每个 ItemType 的问题分布
  │
  └─ scope=all（全量巡检，< 30分钟）
      ├─ 模型巡检 + 核心业务类型实例巡检
      └─ 生成综合报告

结果存储 → 前端数字员工面板展示

五、配置一站式调度改造

数字员工 DS-BOSS-002（系统运维师）的 runOnce() 方法当前固定调用 consistencyCheck()，需要改为调用 Unified Inspection Engine：

// Before (staff-manager.js 中 DS-BOSS-002)
async runStaffOnce(ctx) {
  const { db } = ctx;
  const result = consistencyCheck(db);
  return { ...result, descriptions: ['数据库完整性检查'] };
}

// After
async runStaffOnce(ctx) {
  const result = await unifiedInspection.run({
    scope: 'all',
    mode: 'quick',       // 定时巡检用 quick 模式
    priority: 'P1',
    checkConsistency: true,  // 保留原一致性检查
  });
  return result;
}

六、待确认事项

| 问题 | 建议 |

|---|---|

| HealthPatrol 是否要继续推进 | 建议合并入 AI Inspector，保留其 6 维评分 + EnterpriseRules |

| compliance-inspector.js 是否可删除 | 是，功能完全重叠 |

| **18 个 check-*.js 如何清理 | 逐个审计：可删除/可合并/保留独立 |

| 前端巡检面板优先级 | Phase 2，建议在数字员工页面稳定后做 |

| SCSAI 认证混乱** | ai-inspector.js 有自己的 auth 逻辑（getAuthUser/getAuthPass），与 SCSAI-auth.js 不互通，需统一 |

七、总结

| 评级 | 发现 |

|---|---|

| 🔴 P0 | 4 套并行的巡检系统，数据源不一致、结果可能矛盾 |

| 🔴 P1 | 3 种数据库访问模式共存，属于架构债务 |

| 🟡 P2 | 所有巡检引擎（含 HealthPatrol）均无前端 UI，等于未被使用 |

| 🟡 P2 | EnterpriseRules + HealthScanner + CorrectionLearner 三件套写好但处于"僵尸代码"状态 |

| 🟢 P3 | compliance-inspector.js 应废弃，14 个 check-*.js 应清理 |

建议优先级：Phase 0（统一 DB 访问，1天）→ Phase 1（合并引擎，2天）→ Phase 2（前端面板，3天）