zclaw_openfang/docs/features/audit-v12/M4-intelligence-layer.md

模块 M4 智能层 审计报告

审计版本: V12 审计日期: 2026-04-04 审计范围: 记忆/身份演化/反思引擎/心跳巡检/自主授权/上下文压缩 6 个子模块

---

1. 模块概况

功能描述

ZCLAW 智能层提供 Agent 的"认知能力"：跨会话记忆、人格演化、行为反思、主动巡检、自主决策授权、上下文压缩。

涉及文件清单

前端

• 记忆: store/memoryGraphStore.ts, lib/intelligence-client/memory.ts, components/MemoryPanel.tsx
• 身份: lib/intelligence-client/identity.ts, components/AgentOnboardingWizard.tsx
• 反思: lib/intelligence-client/reflection.ts, components/ReflectionLog.tsx
• 心跳: lib/intelligence-client/heartbeat.ts
• 自主: lib/autonomy-manager.ts, components/AutonomyConfig.tsx
• 压缩: lib/intelligence-client/fallback-compactor.ts

后端 (Rust)

• Intelligence 引擎: desktop/src-tauri/src/intelligence/ (memory.rs, identity.rs, reflection.rs, heartbeat.rs, compactor.rs)
• Runtime 中间件: crates/zclaw-runtime/src/middleware/ (memory.rs, compaction.rs)
• 存储: crates/zclaw-growth/src/storage/sqlite.rs
• Kernel 集成: crates/zclaw-kernel/src/kernel/messaging.rs

---

2. 子模块逐个分析

2.1 Agent 记忆

检查维度	状态	详情
链路完整性	⚠️	双数据库问题 — 前端 UI 用 PersistentMemoryStore(LIKE 搜索)，Runtime 中间件用 SqliteStorage(FTS5 搜索)，两套独立 SQLite
参数一致性	⚠️	前端 types?: MemoryType[](数组) vs 后端 memory_type?: string(单值)
边界处理	✅	错误传播完整，embedding 失败优雅降级
状态管理	⚠️	前端手动刷新，无自动同步
安全	⚠️	无 content 长度限制，无 importance 范围验证

关键问题 [P0]: 双数据库导致：

• 用户手动保存的记忆不出现在对话记忆注入中
• Agent 自动提取的记忆不出现在前端记忆面板
• 前端记忆搜索用的是 LIKE 模糊匹配，文档声称的 FTS5 仅在 Runtime 层生效

2.2 身份演化

检查维度	状态	详情
链路完整性	✅	identity_get/propose_change/approve_proposal 全部注册，UI 组件完整
参数一致性	✅	Soul/Instructions 枚举匹配正确
边界处理	✅	快照上限 50，并发 Mutex 保护
状态管理	✅	文件系统持久化(store.json)，重启恢复
安全	⚠️	store.json 无加密，proposal_id 可预测

关键问题: user_profile 注入被注释掉（防止对话泄漏），心跳人格改进不会自动创建 identity proposal。整体功能可用但需手动触发。

2.3 反思引擎

检查维度	状态	详情
链路完整性	⚠️	命令全部注册，但 LLM 驱动未接入
参数一致性	✅	类型转换正确
边界处理	✅	LLM 失败回退到规则分析，空记忆列表处理正确
状态管理	✅	对话计数器 + 双重触发条件
安全	✅	持久化 fire-and-forget 不影响主流程

关键问题 [P0]: reflection_reflect Tauri 命令传入 driver=None，即使配置 use_llm=true 也只用规则分析。LLM 分析路径从未在 Tauri 桌面端生效。

2.4 心跳巡检

检查维度	状态	详情
链路完整性	✅	后端引擎完整（5 项内置检查）
参数一致性	✅	安静时间解析正确
边界处理	⚠️	interval_minutes 无下限验证
状态管理	⚠️	不自动启动，需前端调用 heartbeat_init + heartbeat_start
安全	⚠️	全局静态状态，所有 agent 共享

关键问题 [P1]: 心跳引擎完全依赖前端主动初始化和数据同步。MEMORY_STATS_CACHE、LAST_INTERACTION、CORRECTION_COUNTERS 三个全局缓存需前端定期调用命令填充，否则心跳检查返回空结果。

2.5 自主授权

检查维度	状态	详情
链路完整性	❌	纯前端实现，无后端 Rust 集成
参数一致性	⚠️	workflow_trigger 映射到 autoCompaction，语义不匹配
边界处理	✅	高风险操作强制审批，自主模式禁止自我修改
状态管理	✅	localStorage 持久化，审计日志 100 条上限
安全	❌	后端无强制检查，恶意用户可绕过前端直接调用 Tauri 命令

关键问题 [P1]: 自主授权仅是前端"咨询层"，后端 MemoryMiddleware 等不检查自主授权级别。TOML 的 requires_approval 仅在 hand_execute 路径生效，其他操作完全绕过。

2.6 上下文压缩

检查维度	状态	详情
链路完整性	✅	Runtime 中间件自动触发，Tauri 命令手动触发
参数一致性	⚠️	两套 CompactionConfig 默认值不同
边界处理	✅	空消息处理正确，LLM 失败回退
状态管理	✅	无状态设计，校准因子全局共享
安全	✅	校准使用 EMA + clamp，合理

关键问题: Tauri 层和 Runtime 层各有独立的压缩实现，代码重复但配置不同。Runtime 层是实际生效路径。

---

3. 问题清单

ID	描述	文件:行号	级别
M4-01	[P0] 双数据库: PersistentMemoryStore vs SqliteStorage 数据不共享	memory/persistent.rs vs zclaw-growth/src/storage/sqlite.rs	P0
M4-02	[P0] 反思引擎 LLM 未接入: reflection_reflect 传 driver=None	reflection.rs:759-766	P0
M4-03	[P1] 心跳不自动启动: 需前端手动初始化	heartbeat.rs	P1
M4-04	[P1] 自主授权后端无强制: 仅前端咨询层	autonomy-manager.ts	P1
M4-05	前端记忆搜索用 LIKE 非 FTS5	persistent.rs search()	P1
M4-06	前端 types 数组 vs 后端单值	MemorySearchOptions 类型定义	P2
M4-07	记忆 content 无长度限制	memory_commands	P2
M4-08	tags 参数标注 dead_code 未使用	persistent.rs	P2
M4-09	heartbeat interval_minutes 无下限验证	heartbeat.rs	P2
M4-10	identity proposal_id 可预测	identity.rs rand_id()	P2
M4-11	store.json 无加密	identity.rs	P2
M4-12	自主授权 workflow_trigger 映射错误	autonomy-manager.ts:271	P2
M4-13	两套压缩实现代码重复	compactor.rs vs compaction.rs	P3
M4-14	heartbeat broadcast subscribe 未被使用	heartbeat.rs	P3
M4-15	heartbeat 历史截断 split_off 语义	heartbeat.rs	P3

---

4. 改进建议

短期修复（按优先级）

1. [P0] 统一存储层：合并 PersistentMemoryStore 和 SqliteStorage，或让前端搜索也查询 SqliteStorage
2. [P0] 在 reflection_reflect Tauri 命令中传入实际 LLM 驱动
3. [P1] 自动启动心跳引擎（在 agent_chat_stream 或 Kernel 初始化中）
4. [P1] 将自主授权关键检查移到 Rust 后端

长期架构建议

• 前端记忆搜索升级为 FTS5
• 移除 Tauri 层的重复压缩实现，统一使用 Runtime 中间件
• identity 持久化改为 SQLite

---

5. 健康度评分

维度	评分	说明
链路完整性	50/100	双数据库是架构级问题，LLM/心跳未接入
参数一致性	65/100	基本匹配但有多处类型/映射不一致
边界处理	70/100	整体较好，缺少输入验证
状态管理	65/100	多数子模块缺少自动触发/同步
安全资源	55/100	自主授权不强制、store.json 不加密

综合健康度: 61/100

两个 P0 级问题（双数据库 + 反思 LLM 未接入）是此模块的核心架构缺陷。智能层"写了但没接通"的问题最集中。