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 关键偏差分析
- Tauri 命令 184→191 (+7): V12 后新增命令 (行业加载/Hermes 组件/管家主动性)
- @reserved 33→24 (-9): Butler/MCP 等命令已接通前端，不再需要 @reserved 标记
- SaaS .route() 122→136 (+14): Knowledge Phase A-D + Industry + Billing + Role 等新增路由
- 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 |
c048cb215f