0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
224 lines
9.0 KiB
Markdown
224 lines
9.0 KiB
Markdown
# 功能审计修复 — 会话交接文档
|
||
|
||
> **创建时间**: 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 修改目标 |
|