zclaw_openfang/docs/handoff-audit-fix-2026-03-26.md

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

创建时间: 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，这些端点不适用

---

验证命令速查

# 编译检查（每次修改后必跑）
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 修改目标