c048cb215f
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
V13 审计聚焦 V12 后新增功能 (行业配置/Knowledge/Hermes/管家主动性): - 总体健康度 82/100 (V12: 76) - P1 新发现 3 项: TrajectoryRecorder 未注册/industryStore 孤立/桌面端无 Knowledge Search - P2 新发现 3 项: Webhook 孤儿表/Structured Data 无 Admin/PersistentMemoryStore 遗留 - 修正 V12 错误认知 5 项: Butler/MCP/Gateway/Presentation 已接通 - TRUTH.md 数字校准: Tauri 184→191, SaaS 122→136, @reserved 33→24
305 lines
15 KiB
Markdown
305 lines
15 KiB
Markdown
# V13 系统性功能审计报告
|
||
|
||
> **审计日期**: 2026-04-12
|
||
> **审计范围**: 全系统功能一致性 + 系统可用性
|
||
> **审计方法**: 量化基线对比 + 五种断链模式扫描 + 功能逐项链路追踪
|
||
> **基准对比**: V12 模块化审计 (2026-04-04)
|
||
|
||
---
|
||
|
||
## 1. 执行摘要
|
||
|
||
### 1.1 总体健康度: **82/100** (V12: 加权平均 76/100)
|
||
|
||
V12 后新增的 4 大功能系统 (行业配置/Knowledge/Hermes/管家主动性) 大部分已正确接通。发现 **3 个确认断链** 和 **3 个确认差距**，无 P0 级问题。
|
||
|
||
### 1.2 Top 5 发现
|
||
|
||
| # | 发现 | 严重度 | 类型 |
|
||
|---|------|--------|------|
|
||
| 1 | TrajectoryRecorderMiddleware 未注册到中间件链 | **P1** | 写了没接 |
|
||
| 2 | industryStore 未被任何组件导入 | **P1** | 写了没接 |
|
||
| 3 | 桌面端未接入 Knowledge Search API | **P1** | 写了没接 |
|
||
| 4 | Webhook 孤儿表 (迁移存在但代码已删) | **P2** | 存了没用 |
|
||
| 5 | Structured Data Source 路由无 Admin-v2 消费者 | **P2** | 写了没接 |
|
||
|
||
### 1.3 修正 V12 错误认知
|
||
|
||
| V12 认知 | V13 实际 | 说明 |
|
||
|----------|---------|------|
|
||
| Butler/Pain Aggregator 5 命令 @reserved 无前端调用 | **已接通** | `viking-client.ts` 有全部 5 个 invoke 调用，ButlerPanel 3 个组件消费 |
|
||
| MCP 4 命令无前端调用 | **已接通** | `mcp-client.ts` 有全部 4 个 invoke 调用，MCPServices.tsx 消费 |
|
||
| Reflection Engine driver=None | **已修复** | `reflection.rs:787-792` 从 kernel_state 获取真实 driver |
|
||
| Pipeline Presentation 无前端调用 | **部分接通** | `analyze_presentation` 被 PresentationContainer.tsx 调用 |
|
||
| Gateway 控制命令无前端调用 | **已接通** | `tauri-gateway.ts` 有 zclaw_start/stop/restart/version 调用 |
|
||
| Embedding 全部 NoOp | **设计如此** | NoOp 仅是默认值，用户配置后替换为真实 provider |
|
||
| Memory 双存储未统一 | **事实已统一** | PersistentMemoryStore 仅保留用于遗留嵌入配置，所有数据走 VikingStorage |
|
||
|
||
---
|
||
|
||
## 2. 量化基线 (TRUTH.md 漂移校准)
|
||
|
||
### 2.1 指标对比
|
||
|
||
| 指标 | TRUTH.md 值 | V13 当前值 | 偏差 | 说明 |
|
||
|------|------------|-----------|------|------|
|
||
| Tauri 命令 | 184 | **191** | **+7** | 行业/Hermes 等新增命令 |
|
||
| 前端 invoke | 105 | **106** | +1 | industryStore 新增 1 处 |
|
||
| @reserved | 33 | **24** | **-9** | 部分命令已接通前端 |
|
||
| 孤儿命令 | ~46 | **~61** | **+15** | 191-106-24=61, 含新增命令 |
|
||
| Rust 测试 #[test] | 431 | **433** | +2 | |
|
||
| Rust 测试 #[tokio::test] | 367 | **368** | +1 | |
|
||
| Rust 测试合计 | 798 | **801** | +3 | |
|
||
| dead_code (crates) | - | **16** | - | 14 文件 |
|
||
| dead_code (src-tauri) | - | **27** | - | 15 文件 |
|
||
| dead_code 合计 | 76 | **43** | **-33** | 显著减少 |
|
||
| TODO/FIXME (Rust) | 4 | **3** | -1 | |
|
||
| TODO/FIXME (前端) | 4 | **1** | -3 | |
|
||
| Zustand Store | 20 | **21** | +1 | 含 industryStore |
|
||
| React 组件 | 104 | **104** | 0 | |
|
||
| SaaS .route() | 122 | **136** | **+14** | Knowledge/Industry/Billing 等新增路由 |
|
||
| SKILL.md | 75 | **75** | 0 | |
|
||
| 前端 lib | 83 | **83** | 0 | |
|
||
| Rust LOC (crates) | ~74,600 | **77,025** | +2,425 | |
|
||
| Rust LOC (src-tauri) | - | **61,414** | - | |
|
||
| Rust LOC 总计 | - | **138,439** | - | crates + src-tauri |
|
||
|
||
### 2.2 关键偏差分析
|
||
|
||
1. **Tauri 命令 184→191 (+7)**: V12 后新增命令 (行业加载/Hermes 组件/管家主动性)
|
||
2. **@reserved 33→24 (-9)**: Butler/MCP 等命令已接通前端，不再需要 @reserved 标记
|
||
3. **SaaS .route() 122→136 (+14)**: Knowledge Phase A-D + Industry + Billing + Role 等新增路由
|
||
4. **dead_code 76→43 (-33)**: 大量清理工作已完成
|
||
|
||
---
|
||
|
||
## 3. 五种断链模式分析
|
||
|
||
### 3.1 "写了没接" — 确认 3 项
|
||
|
||
#### GAP-01: TrajectoryRecorderMiddleware 未注册 (P1)
|
||
|
||
- **位置**: `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` (完整实现, 有测试)
|
||
- **断链点**: `crates/zclaw-kernel/src/kernel/mod.rs` 的 `create_middleware_chain()` 中 **零匹配** `trajectory`
|
||
- **影响**: Hermes Schema v4 创建了 `trajectory_events` 表，TrajectoryRecorder 代码存在但永不执行 → 轨迹数据零流入 → 经验分析基础缺失
|
||
- **修复**: 在 `create_middleware_chain()` 末尾注册 TrajectoryRecorder (优先级 @650)
|
||
|
||
#### GAP-02: industryStore 未被组件导入 (P1)
|
||
|
||
- **位置**: `desktop/src/store/industryStore.ts` (完整 Store, 有 persist)
|
||
- **断链点**: `Grep 'from.*industryStore\|useIndustryStore' desktop/src/` 仅返回自身文件
|
||
- **影响**: 行业配置数据可从 SaaS 获取，可推送到 Rust 后端 (`viking_load_industry_keywords`)，但**桌面端 UI 无法展示行业配置状态**
|
||
- **注意**: `industryStore` 中的 `fetchIndustries()` 调用 `viking_load_industry_keywords` 成功后端数据流通，但 Store 本身未被任何 React 组件消费
|
||
- **修复**: 在 Settings 或 ButlerPanel 中添加行业配置展示组件
|
||
|
||
#### GAP-03: 桌面端未接入 Knowledge Search API (P1)
|
||
|
||
- **位置**: SaaS 有 `POST /api/v1/knowledge/search` 端点
|
||
- **断链点**: `desktop/src/` 中搜索 `knowledge/search` **零匹配**
|
||
- **影响**: 桌面端用户无法搜索 SaaS 知识库中的内容。Knowledge 仅通过 Admin-v2 管理
|
||
- **修复**: 在 saasStore 或新建 knowledgeStore 中添加搜索方法，接入 VikingPanel 或独立面板
|
||
|
||
### 3.2 "接了没传" — 无确认项
|
||
|
||
| 检查项 | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| 行业关键词传播 | ✅ 正常 | `industryStore.ts:87` → `viking_commands.rs:708` → `kernel/mod.rs:244` 完整连通 |
|
||
| 计费用量增量 | ✅ 正常 | 双路径: 桌面 handStore 手动报告 + SaaS relay 自动递增 |
|
||
| Reflection Engine driver | ✅ 正常 | `reflection.rs:787-792` 从 kernel_state 获取真实 LLM driver |
|
||
|
||
### 3.3 "传了没存" — 无确认项
|
||
|
||
| 检查项 | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| User profiles 持久化 | ✅ 正常 | `user_profiler.rs:107` 写入, `agent.rs:188` 读取 |
|
||
| Trajectory events | ⚠️ 关联 GAP-01 | 表存在+代码存在，但因中间件未注册导致零数据流入 |
|
||
|
||
### 3.4 "存了没用" — 确认 1 项
|
||
|
||
#### GAP-04: Webhook 孤儿表 (P2)
|
||
|
||
- **位置**: `crates/zclaw-saas/migrations/20260403000002_webhooks.sql`
|
||
- **现状**: 创建了 `webhook_subscriptions` 和 `webhook_deliveries` 表，但所有业务代码已删除
|
||
- **影响**: 新数据库部署时会创建无用表，占用 schema 空间
|
||
- **修复**: 添加 down migration 或在 schema 中标注 deprecated
|
||
|
||
### 3.5 "双系统不同步" — 确认 1 项
|
||
|
||
#### GAP-05: PersistentMemoryStore 遗留 (P2)
|
||
|
||
- **位置**: `desktop/src-tauri/src/memory/persistent.rs` (有 `#[allow(dead_code)]`)
|
||
- **现状**: 数据流已统一到 VikingStorage，PersistentMemoryStore 仅保留用于遗留嵌入配置路径
|
||
- **影响**: 代码复杂度增加，两个独立的 SQLite 连接
|
||
- **修复**: 将嵌入配置路径迁移到 VikingStorage，然后删除 PersistentMemoryStore
|
||
|
||
### 3.6 "写了没接" — Admin-v2 侧
|
||
|
||
#### GAP-06: Structured Data Source 路由无消费者 (P2)
|
||
|
||
- **位置**: SaaS Knowledge 模块有 5 个 structured source 路由
|
||
- **断链点**: `admin-v2/src/services/knowledge.ts` 中搜索 `structured` **零匹配**
|
||
- **影响**: 结构化数据源 API 存在但无管理界面
|
||
- **修复**: 在 Admin Knowledge 页面添加结构化数据源管理
|
||
|
||
---
|
||
|
||
## 4. 功能逐项审计结果
|
||
|
||
### 4.1 V12 后新增功能
|
||
|
||
#### 行业配置系统 — 完成度: **75/100**
|
||
|
||
| 链路环节 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| SaaS 行业 CRUD (10 路由) | ✅ | handlers.rs + service.rs 完整 |
|
||
| Admin-v2 行业管理页面 | ✅ | Industries.tsx 完整 |
|
||
| Desktop industryStore | ⚠️ GAP-02 | Store 存在但无组件导入 |
|
||
| Tauri viking_load_industry_keywords | ✅ | 命令定义+注册+调用 |
|
||
| ButlerRouter 行业关键词注入 | ✅ | kernel/mod.rs:244 共享 Arc |
|
||
| 4 内置行业配置 | ✅ | 医院行政/酒店/教育/零售 |
|
||
|
||
#### Knowledge Phase A-D — 完成度: **85/100**
|
||
|
||
| 链路环节 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| Knowledge SaaS (29 路由) | ✅ | Category/Item/Version/Search/Seed/Analytics |
|
||
| Admin-v2 Knowledge 页面 | ✅ | 消费 categories/items/search/analytics |
|
||
| Knowledge Analytics (5 端点) | ✅ | Knowledge.tsx:534-558 全部消费 |
|
||
| Structured Data Source (5 路由) | ⚠️ GAP-06 | 无 admin-v2 消费者 |
|
||
| Desktop Knowledge Search | ⚠️ GAP-03 | 无桌面端调用 |
|
||
| 种子知识冷启动 | ✅ | seed 端点 + 种子模板 |
|
||
|
||
#### Hermes Intelligence Pipeline — 完成度: **65/100**
|
||
|
||
| 链路环节 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| ExperienceStore | ✅ | 实例化在 experience.rs，有 Tauri 命令 |
|
||
| UserProfileStore | ✅ | 写入 user_profiler.rs，读取 agent.rs |
|
||
| TrajectoryRecorder | ⚠️ GAP-01 | 代码完整但未注册中间件链 |
|
||
| NlScheduleParser | ✅ | 中文时间→cron 转换 |
|
||
| Schema v4 (user_profiles + trajectory) | ✅ | 表已创建 |
|
||
| Trajectory 数据实际流入 | ❌ | 因 GAP-01 导致零数据 |
|
||
|
||
#### 管家主动性 (Phase 2-5) — 完成度: **80/100**
|
||
|
||
| 链路环节 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| ButlerRouter 语义路由 | ✅ | SemanticSkillRouter TF-IDF |
|
||
| 触发信号持久化 | ✅ | VikingStorage |
|
||
| 跨会话连续性 | ✅ | 痛点回访 + 经验检索 |
|
||
| ButlerPanel UI | ✅ | Insights/Proposals/Memory 3 区 |
|
||
| Pain Aggregator 5 命令 | ✅ | viking-client.ts 全部 5 个 invoke |
|
||
| 行业配置注入 ButlerRouter | ✅ | kernel/mod.rs 共享 Arc |
|
||
|
||
### 4.2 V12 高风险模块复验
|
||
|
||
#### M3 Hands System — V12: 58/100 → V13: **72/100**
|
||
|
||
提升原因: Butler/MCP 命令接通确认, 数据流验证通过。仍有孤儿命令 (gateway control 细粒度命令)。
|
||
|
||
#### M4 Intelligence Layer — V12: 61/100 → V13: **78/100**
|
||
|
||
提升原因: Reflection Engine driver 已连接, User Profile 持久化已验证, PersistentMemoryStore 事实已统一。仍有 GAP-01 (TrajectoryRecorder)。
|
||
|
||
#### M2 Agent Clones — V12: 67/100 → V13: **75/100**
|
||
|
||
维持提升: CRUD 完整, 身份演化链路正常, onboarding wizard 存在。
|
||
|
||
### 4.3 V12 模块评分更新
|
||
|
||
| 模块 | V12 评分 | V13 评分 | 变化 | 关键变化 |
|
||
|------|---------|---------|------|----------|
|
||
| M1 智能对话 | 91 | **91** | 0 | 无回归 |
|
||
| M2 Agent 分身 | 67 | **75** | +8 | CRUD 验证通过 |
|
||
| M3 Hands 系统 | 58 | **72** | +14 | Butler/MCP 接通确认 |
|
||
| M4 智能层 | 61 | **78** | +17 | Reflection driver 已连, User Profile 已通 |
|
||
| M5 技能生态 | 85 | **85** | 0 | 无回归 |
|
||
| M6 Pipeline 工作流 | 72 | **75** | +3 | Pipeline Presentation 部分接通 |
|
||
| M7 SaaS 桌面端 | 85 | **83** | -2 | Knowledge Search 未接桌面 (GAP-03) |
|
||
| M8 Admin V2 | 82 | **83** | +1 | Knowledge Analytics 全部接通 |
|
||
| M9 通信安全 | 86 | **86** | 0 | 无回归 |
|
||
| M11 Classroom | 70 | **72** | +2 | 小幅改善 |
|
||
|
||
**加权平均**: V12 ~76/100 → V13 **82/100**
|
||
|
||
---
|
||
|
||
## 5. 技术债目录
|
||
|
||
### 5.1 dead_code 标记分类 (43 处)
|
||
|
||
| 类别 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| 真正预留 (保留) | ~12 | A2A/WASM feature-gated, driver 反序列化结构体 |
|
||
| 应该删除 | ~8 | Webhook 相关, PersistentMemoryStore 遗留 |
|
||
| 应该接通 | ~5 | TrajectoryRecorder, HTML/Markdown export |
|
||
| 可接受 (类型转换/兼容) | ~18 | driver 响应字段, 中间件辅助 |
|
||
|
||
### 5.2 孤儿命令分析 (约 61 个)
|
||
|
||
- **已接通 (之前误标)**: ~9 个 (Butler 5 + MCP 4) — 应移除 @reserved 标记
|
||
- **合理的 @reserved**: 24 个 — 为未来功能预留
|
||
- **真正孤儿**: ~28 个 — 含 gateway 细粒度控制、viking CLI、classroom 部分、memory 基础命令
|
||
|
||
### 5.3 孤儿 SaaS 表
|
||
|
||
| 表名 | 状态 | 建议 |
|
||
|------|------|------|
|
||
| webhook_subscriptions | 代码已删，迁移仍在 | 添加 down migration |
|
||
| webhook_deliveries | 代码已删，迁移仍在 | 添加 down migration |
|
||
|
||
---
|
||
|
||
## 6. 修复计划
|
||
|
||
### P1 — 必须修复 (影响功能完整性)
|
||
|
||
| ID | 问题 | 修复方案 | 影响文件 | 工作量 |
|
||
|----|------|----------|----------|--------|
|
||
| FIX-01 | TrajectoryRecorder 未注册中间件 | 在 `create_middleware_chain()` 末尾添加注册 (优先级 @650) | `crates/zclaw-kernel/src/kernel/mod.rs` | 0.5h |
|
||
| FIX-02 | industryStore 无组件消费 | 在 Settings 或 ButlerPanel 添加行业配置展示 | `desktop/src/components/` + store import | 2h |
|
||
| FIX-03 | 桌面端无 Knowledge Search | 新建 knowledgeStore 或扩展 saasStore，添加搜索 UI | `desktop/src/store/` + `desktop/src/components/` | 4h |
|
||
|
||
### P2 — 应该修复 (代码清洁度)
|
||
|
||
| ID | 问题 | 修复方案 | 影响文件 | 工作量 |
|
||
|----|------|----------|----------|--------|
|
||
| FIX-04 | Webhook 孤儿迁移 | 添加 down migration 或标注 deprecated | `crates/zclaw-saas/migrations/` | 0.5h |
|
||
| FIX-05 | Structured Data Source 无 Admin UI | 在 Admin Knowledge 页面添加管理 | `admin-v2/src/` | 4h |
|
||
| FIX-06 | PersistentMemoryStore 遗留 | 迁移嵌入配置到 VikingStorage 后删除 | `desktop/src-tauri/src/memory/` | 3h |
|
||
|
||
### P3 — 可选改善
|
||
|
||
| ID | 问题 | 修复方案 | 工作量 |
|
||
|----|------|----------|--------|
|
||
| FIX-07 | ~28 孤儿 Tauri 命令未标注 | 审计并标注 @reserved 或删除 | 2h |
|
||
| FIX-08 | @reserved 标记过时 (Butler/MCP 已接通) | 移除 9 个过时 @reserved | 0.5h |
|
||
| FIX-09 | dead_code 清理 (应删除的 ~8 处) | 移除确认无用的 dead code | 1h |
|
||
|
||
---
|
||
|
||
## 7. 附录
|
||
|
||
### 7.1 确认已接通的功能 (修正 V12 错误认知)
|
||
|
||
| 功能 | 前端调用位置 | 消费组件 |
|
||
|------|-------------|----------|
|
||
| Butler Pain Aggregator 5 命令 | `desktop/src/lib/viking-client.ts:261-308` | ButlerPanel 3 个组件 + useButlerInsights hook |
|
||
| MCP 生命周期 4 命令 | `desktop/src/lib/mcp-client.ts:49-76` | MCPServices.tsx |
|
||
| Gateway 控制命令 | `desktop/src/lib/tauri-gateway.ts:77-217` | App.tsx + connectionStore |
|
||
| Pipeline analyze_presentation | `desktop/src/components/presentation/PresentationContainer.tsx:55` | PresentationContainer |
|
||
| Knowledge Analytics 5 端点 | `admin-v2/src/pages/Knowledge.tsx:534-558` | AnalyticsPanel |
|
||
| Reflection Engine driver | `desktop/src-tauri/src/intelligence/reflection.rs:787-792` | 从 kernel_state 获取 |
|
||
|
||
### 7.2 搜索模式参考 (未来复审计)
|
||
|
||
| 检查项 | Grep 模式 | 路径 |
|
||
|--------|----------|------|
|
||
| Tauri 命令定义 | `#\[.*tauri::command` | `desktop/src-tauri/src/` |
|
||
| 前端 invoke 调用 | `invoke\(` | `desktop/src/` |
|
||
| @reserved 标注 | `@reserved` | `desktop/src-tauri/src/` |
|
||
| dead_code 标记 | `allow\(dead_code\)` | `crates/` + `desktop/src-tauri/src/` |
|
||
| 孤儿 Store | Store 文件名 vs `from.*StoreName` 引用 | `desktop/src/store/` |
|
||
| SaaS 路由 | `\.route\(` | `crates/zclaw-saas/src/` |
|
||
| 中间件注册 | 中间件 struct 名称 | `crates/zclaw-kernel/src/kernel/mod.rs` |
|