# 功能审计修复 — 会话交接文档

> **创建时间**: 2026-03-26
> **审计报告**: `plans/piped-wondering-thompson.md`
> **旧审计对比**: `docs/analysis/FEATURE-INTEGRITY-AUDIT.md`（含 6 处事实错误，勿参考）

---

## 背景

对 ZCLAW 全系统 12 个子系统执行了五步审计（文档对齐→追踪数据流→识别dead_code→检查trait实现→端到端验证），发现 19 处差距、22 处 dead_code、8 项文档不一致。核心问题模式：**"写了没接"** — 大量代码已实现但从未接入实际运行流程。

---

## 修复任务清单（严格按优先级执行）

### P0 — 影响核心功能可用性

#### P0-1: Context Compaction 内核集成

**问题**: 上下文压缩仅在前端 `chatStore.ts` 执行，`kernel.rs` 的 `send_message_stream()` 不感知压缩，LLM 实际收到完整历史，前端压缩只是视觉隐藏。

**差距模式**: 双系统不同步

**修复路径**:
- `crates/zclaw-kernel/src/kernel.rs` — 在 `send_message_stream()` 中添加 token 估算 + 阈值检查 + 压缩逻辑
- 参考前端实现: `desktop/src/store/chatStore.ts:333-359`（`checkThreshold` + `compact`）
- 参考后端压缩器: `desktop/src-tauri/src/intelligence/compactor.rs`（462 行，已有完整实现）
- 修复后删除前端 `chatStore.ts` 中的重复压缩调用，改为依赖内核

**验证**: 发送 20+ 条消息后，检查发给 LLM 的实际 context 长度是否被压缩

---

#### P0-2: 文档虚假声称清理

**问题**: README、CLAUDE.md 中多处状态描述与代码不符

**修复清单**:
| 文件 | 行/位置 | 当前声称 | 应改为 |
|------|---------|---------|-------|
| `CLAUDE.md` | 项目结构 crates 列表 | `zclaw-channels (Telegram, Discord, Slack)` | `zclaw-channels (仅 ConsoleChannel 测试适配器)` |
| `CLAUDE.md` | Hands 表格 Lead 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
| `CLAUDE.md` | Hands 表格 Predictor 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
| `docs/features/README.md` | Hands 统计 | `9 implemented = 82%` | `7 fully working, 2 config-only (Lead/Predictor)` |
| `docs/features/README.md` | Lead/Predictor 注册状态 | 标记为已注册 | 标记为未实现 |
| `docs/features/06-context-compaction.md` | 成熟度标签 | L4 Production | L2 (前端仅视觉压缩，内核未集成) |
| `docs/features/README.md` | 删除引用 6 个不存在的文档链接 | 01-vector-memory.md 等 | 删除这些引用 |

**验证**: `rg "Lead|Predictor|Telegram|Discord|Slack" CLAUDE.md` 确认已修正

---

#### P0-3: Quiz Hand 占位符生成器替换

**问题**: `DefaultQuizGenerator` 生成 "Question N about X" / "Option A/B/C/D"，正确答案永远是 Option A

**修复路径**:
- `crates/zclaw-hands/src/hands/quiz.rs:35-68` — 替换 `DefaultQuizGenerator::generate()` 实现
- 利用已有的 `QuizGenerator` trait（同文件），实现 LLM 驱动的生成器
- 参考同类模式: `crates/zclaw-runtime/src/tools/web_fetch.rs` 中的 LLM 调用方式
- 生成器需要接收 LLM driver 引用（通过 `QuizHand::new()` 或 `with_generator()` 传入）

**验证**: 触发 Quiz Hand，检查生成的题目是否有真实内容和随机正确答案

---

### P1 — 减少技术债务

#### P1-1: Intelligence 死代码清理

**问题**: 4 个模块有完整代码但从未被前端调用

**清理清单**:
| 文件 | 大小 | Tauri 命令数 | 前端调用 | 建议 |
|------|------|------------|---------|------|
| `desktop/src-tauri/src/intelligence/mesh.rs` | ~300+ 行 | 8 个 | 0 | 删除或移到 `#[cfg(feature = "experimental")]` |
| `desktop/src-tauri/src/intelligence/persona_evolver.rs` | ~300+ 行 | 7 个 | 0 | 同上 |
| `desktop/src-tauri/src/intelligence/pattern_detector.rs` | ~200+ 行 | 0 | 0 | 删除 |
| `desktop/src-tauri/src/intelligence/trigger_evaluator.rs` | ~500+ 行 | 0 | 0 | 删除 |

**注意**: `recommender.rs` **不是**死代码（被 `mesh.rs` 使用），但若 mesh.rs 被移除则 recommender 也变为死代码。

**修复步骤**:
1. 删除上述 4 个文件
2. 从 `desktop/src-tauri/src/intelligence/mod.rs` 移除对应 `pub mod` 声明
3. 从 `desktop/src-tauri/src/lib.rs` invoke_handler 移除对应 15 个命令注册（mesh 8 个 + persona_evolver 7 个）
4. 运行 `cargo check` 确认编译通过

**验证**: `cargo check` + `rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/`

---

#### P1-2: Heartbeat Engine 整理

**问题**: Heartbeat 实际完成度 ~75%（App.tsx 启动时调用 init/start，有 tokio 定时循环），但 `trigger_evaluator` 子模块为死代码

**修复路径**:
- 若 P1-1 已删除 trigger_evaluator，则 Heartbeat 中对它的引用也需要处理
- 检查 `heartbeat.rs` 中是否有对 `trigger_evaluator` 的 import，若有则移除
- 移除 `heartbeat.rs` 的 `#![allow(dead_code)]`（既然模块是活的，不需要此标记）
- 确认 `heartbeat_tick` 中 trigger 评估逻辑降级为简单实现

**验证**: `cargo check` + 启动应用确认 heartbeat 仍正常运行

---

#### P1-3: Identity 持久化

**问题**: `AgentIdentityManager` 使用 InMemory 存储，重启后身份数据丢失

**修复路径**:
- `desktop/src-tauri/src/intelligence/identity.rs` — 将 InMemory 存储替换为 SQLite
- 参考已有的持久化模式: `crates/zclaw-growth/src/storage/sqlite.rs`
- SOUL.md 内容、人格预设、变更提案历史需要持久化到 SQLite 表
- 启动时从 SQLite 恢复状态

**验证**: 设置人格后重启应用，检查人格是否保留

---

#### P1-4: Channels 文档修正

**问题**: CLAUDE.md 声称 zclaw-channels 支持 Telegram/Discord/Slack，实际只有 ConsoleChannel

**修复路径**:
- 已在 P0-2 中覆盖（同一处 CLAUDE.md 修改）

---

### P2 — 改善开发体验

#### P2-1: KernelConfig::load() 实现

**问题**: `crates/zclaw-kernel/src/config.rs:256-259` 的 `load()` 始终返回 `Self::default()`

**修复路径**:
- 实现 TOML 文件读取（项目已依赖 `toml` crate）
- 默认路径: `~/.zclaw/config.toml` 或项目根 `config/config.toml`
- 支持 `${VAR_NAME}` 环境变量插值（参考 `desktop/src/lib/toml-utils.ts`）
- 保留 `from_provider()` 作为运行时覆盖

**验证**: 修改 config.toml 中的某个值，重启后端确认生效

---

#### P2-2: PPTX/PDF 导出修复或明确禁用

**问题**: Pipeline 的 ActionRegistry 对 PPTX/PDF 返回 "feature in development" 错误

**修复路径**（二选一）:
- **方案 A**: 修复导出 — `crates/zclaw-kernel/src/export/pptx.rs` 已有实现，检查为什么 Pipeline 层面报错
- **方案 B**: 明确禁用 — 从 Pipeline 前端 UI 中隐藏 PPTX/PDF 选项，避免用户触发报错

**验证**: 在 Pipeline 编辑器中尝试 PPTX 导出

---

#### P2-3: Embedding 搜索统一

**问题**: 向量嵌入仅连接到 Viking 侧车存储，内核原生 MemoryStore 不使用

**修复路径**:
- `desktop/src-tauri/src/embedding_adapter.rs` 已实现 EmbeddingClient trait
- 将相同 adapter 注入到 `zclaw-growth` 的 `SemanticScorer`（已有 `with_embedding()` 方法）
- 在 `intelligence_hooks.rs` 的 `build_memory_context()` 中启用嵌入搜索

**验证**: 配置 embedding provider 后，搜索记忆时确认使用了向量搜索

---

## 不在本次修复范围的事项

| 项目 | 原因 |
|------|------|
| 新增 Telegram/Discord/Slack 适配器 | 需求未确认，工作量大于修复 |
| Pipeline 智能路由（01-intelligent-routing.md） | 纯新功能，非修复 |
| WASM/Native 技能执行模式 | 纯新功能 |
| Agent 导入/导出、模板库 | 纯新功能 |
| 生物识别支持 | 纯新功能 |
| 旧报告提到的 6 个 404 API 端点 | ZCLAW 是 Tauri 桌面应用，不走 HTTP API，这些端点不适用 |

---

## 验证命令速查

```bash
# 编译检查（每次修改后必跑）
cargo check 2>&1 | grep -i "warning\|error"

# TypeScript 类型检查
cd desktop && pnpm tsc --noEmit

# 单元测试
cargo test -p zclaw-growth 2>&1 | tail -5
cd desktop && pnpm vitest run

# 验证文档修正
rg "Lead.*可用|Predictor.*可用|Telegram|Discord|Slack" CLAUDE.md

# 验证死代码清理
rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/

# 验证 heartbeat 清理
rg "allow\(dead_code\)" desktop/src-tauri/src/intelligence/heartbeat.rs
```

---

## 关键文件索引

| 文件 | 用途 |
|------|------|
| `plans/piped-wondering-thompson.md` | 完整审计报告（本文档的详细版本） |
| `crates/zclaw-kernel/src/kernel.rs` | 内核，P0-1 修改目标 |
| `crates/zclaw-hands/src/hands/quiz.rs` | Quiz Hand，P0-3 修改目标 |
| `desktop/src-tauri/src/intelligence/` | 智能层，P1-1/P1-2 修改目标 |
| `desktop/src-tauri/src/intelligence/identity.rs` | 身份管理，P1-3 修改目标 |
| `desktop/src-tauri/src/lib.rs:1376-1566` | Tauri 命令注册表 |
| `desktop/src-tauri/src/intelligence_hooks.rs` | 智能 hooks 集成点 |
| `crates/zclaw-kernel/src/config.rs:256-259` | 配置加载，P2-1 修改目标 |
| `CLAUDE.md` | 项目文档，P0-2 修改目标 |
| `docs/features/README.md` | 功能索引，P0-2 修改目标 |