# 模块 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 未接入）是此模块的核心架构缺陷。智能层"写了但没接通"的问题最集中。