zclaw_openfang/docs/TRUTH.md

ZCLAW 系统真相文档

更新日期: 2026-04-05 数据来源: V11 全面审计 + 二次审计 + V12 模块化端到端审计 + 代码全量扫描验证 规则: 此文档是唯一真相源。所有其他文档如果与此冲突，以此为准。

---

1. 量化指标（已验证）

指标	实际值	验证方式
Rust Crates	10 个 (编译通过)	cargo check --workspace
Rust 代码行数	~66,000	wc -l
Rust 单元测试	383 个	grep '#\[test\]' crates/
Tauri 命令	183 个 (180 注册含 4 A2A feature-gated + 1 未注册 identity_init + 2 待确认)	grep #[tauri::command] 完整审计
Tauri 命令有前端调用	160 个	@connected 标注（含 4 个 A2A feature-gated）
Tauri 命令无前端调用	16 个	@reserved 标注
SKILL.md 文件	75 个	ls skills/*.md | wc -l
Hands 启用	9 个	Browser/Collector/Researcher/Clip/Twitter/Whiteboard/Slideshow/Speech/Quiz（均有 HAND.toml）
Hands 禁用	2 个	Predictor, Lead（概念定义存在，无 TOML 配置文件或 Rust 实现）
Pipeline 模板	17 个 YAML	pipelines/ 目录全量统计（含 _templates/ 和 design-shantou/ 子目录）
SaaS API 端点	130 个（128 标准 + 2 dev-only mock；webhook 5 路由已定义但未挂载）	路由注册 handler 引用全量统计
SaaS 路由模块	12 个	account/agent_template/auth/billing/knowledge/migration/model_config/prompt/relay/role/scheduled_task/telemetry（scheduled_task: 后端 5 CRUD + Admin V2 前端 service/page/route/nav）
SaaS 数据表	34 个（含 saas_schema_version）	CREATE TABLE 全量统计
SaaS Workers	7 个	log_operation/cleanup_rate_limit/cleanup_refresh_tokens/record_usage/update_last_used/aggregate_usage/generate_embedding
LLM Provider	8 个	Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local
Zustand Store	18 个	ls desktop/src/store/ (含 chat/ 子目录)
React 组件	~135 个	find desktop/src/components/ (.tsx/.ts)
前端 TypeScript 测试	23 个文件	1 单元 + 22 E2E spec
Admin V2 页面	15 个	admin-v2/src/pages/ 全量统计（含 ScheduledTasks、ConfigSync）
桌面端设置页面	19 个	SettingsLayout.tsx tabs: 通用/用量统计/积分详情/模型与API/MCP服务/技能/IM频道/工作区/数据与隐私/安全存储/SaaS平台/订阅与计费/语义记忆/安全状态/审计日志/定时任务/心跳配置/提交反馈/关于
Admin V2 测试	322 个	vitest 统计
中间件层	11 层	运行时注册

---

2. 端到端可用功能

以下功能经过代码验证，从前端到后端完整连通：

2.1 确认可用

功能	路径	验证状态
智能对话	UI → chatStore → Tauri → Kernel → LLM Driver → 流式返回	✅ 代码完整
Agent 分身管理	UI → agentStore → Tauri → Kernel	✅ 代码完整
模型切换	UI → Settings → config.toml → Kernel	✅ 代码完整
Hand 触发	UI → handStore → Tauri → Kernel → Hand 执行	✅ 代码完整
Hand 审批	UI → approvalStore → Tauri → Kernel	✅ 代码完整
记忆搜索	UI → memoryStore → Tauri → Growth → FTS5	✅ 代码完整
配置读写	UI → Settings → config.toml	✅ 代码完整
SaaS 登录/注册	UI → saasStore → SaaS API → PostgreSQL	✅ 代码完整
SaaS 配置同步	UI → saasStore → SaaS API → Store 更新	✅ 代码完整
Admin V2 管理	admin-v2 → SaaS API → PostgreSQL	✅ 代码完整
支付集成	Admin → SaaS → Alipay/WeChat API	✅ 代码完整

2.2 有已知缺陷

2026-04-03 更新: 以下 P0/P1 缺陷已全部修复（详见 §3.1/3.2），本节保留仅作历史记录。

功能	原问题	修复状态
Skill 执行	前端传空 context → Rust 反序列化失败	✅ 已修复 (SEC2-P0-01)
Hand 异步结果	Rust emit 事件但前端无 listen()	✅ 已修复 (SEC2-P1-03)
Agent 模板	API 路径缺 /api/v1 前缀 → 404	✅ 已修复 (SEC2-P1-02)
Trigger 更新	参数格式不匹配 → 静默失败	✅ 已修复 (V11-P1-01)

2.3 已实现但未接通前端

功能	Rust 状态	前端状态
Pipeline 执行	DSL 引擎完整	已接通前端 (8 个 invoke 调用匹配 8 个 Rust 命令，已确认可用)
Viking 适配	FTS5 + TF-IDF	5 个孤立 invoke 已清理，新增 addWithMetadata/storeWithSummaries 方法 + UI
Classroom	27 个命令	7 个命令无前端调用（classroom_list/generation_progress 等已标注 @reserved）
Browser Hand	22 个命令	部分无前端调用
Multi-agent Director	912 行 (feature-gated)	未启用

2.4 前端孤立 invoke 调用（已清理）

Viking 5 个孤立 invoke 调用已于 2026-04-03 清理移除：

• viking_add_inline, viking_server_start, viking_server_status, viking_server_stop, viking_server_restart

当前无已知前端孤立 invoke 调用。

---

3. 已知缺陷清单

3.1 P0 — 必然崩溃

ID	问题	状态
SEC2-P0-01	skill_execute 反序列化崩溃	已修复 — kernel-skills.ts 注入真实 agentId/sessionId，workingDir 改为 null
SEC2-P0-02	TaskTool::default() panic	已修复 — 移除 impl Default

3.2 P1 — 功能失效

ID	问题	状态
SEC2-P1-01	FactStore trait 零实现	已修复 — 移除死 trait，保留值类型
SEC2-P1-02	agent-templates 路径错误	已修复 — saas-client.ts 已添加 /api/v1
SEC2-P1-03	hand-execution-complete 无监听	已修复 — ChatArea 添加 Tauri 事件监听 + streamStore.cancelStream 补全
SEC2-P1-04	InMemoryStorage RwLock unwrap 级联	已修复 — 7 处改为 .expect()
SEC2-P1-05~07	HandRun 持久化静默忽略 (3处)	已修复 — tracing::warn!
SEC2-P1-08	FTS 索引更新静默失败	已修复 — tracing::warn!
SEC2-P1-09	Worker dispatch 静默失败	已修复 — tracing::warn!

3.3 P1.5 — 代码质量补充修复

ID	问题	状态
SEC2-P1.5-01	Capability _ => false 通配符	已修复 — 3 个方法改为穷举匹配，grants() 保留通配符+注释说明
SEC2-P1.5-02	billing let _ = ... ? 冗余模式	已修复 — 移除冗余 let _ =
SEC2-P1.5-03	relay SSE 错误路径 send 失败未记录	已修复 — 改为 if let Err + tracing::debug!
SEC2-P1.5-04	WASM runner 缺少状态注解	已修复 — 添加 active module 说明
SEC2-P1.5-05	Tauri 命令无连接状态标注	已修复 — 177 个命令完整审计（160 @connected / 16 @reserved / 1 未注册 identity_init）
SEC2-P1.5-06	extract_token_usage 静默丢弃解析错误	已修复 — 添加 tracing::debug!
SEC2-P1.5-07	relay current_key_id 防御性 unwrap	已修复 — 改为 ok_or_else 返回内部错误

3.3 P2 — 代码质量

ID	问题
SEC2-P2-01~10	10 项代码质量问题（详见二次审计）

---

4. 死代码清单

文件/目录	行数	状态	建议
desktop/src/lib/audit-logger.ts	170	已删除	-
desktop/src/lib/saas-admin.ts	234	已在之前清理中删除	-
desktop/src/lib/gateway-reconnect.ts	~100	已删除 (零生产引用)	-
admin/	整目录	已删除 (空目录壳)	-
admin-temp-dir/	整目录	已删除	-
crates/zclaw-channels/	Cargo.toml only	已在之前清理中删除	-
docs/analysis/ISSUE-TRACKER.md	-	已删除	-
Director multi-agent	912	feature-gated off + 已注解	保留
A2A 协议	~400	feature-gated off + 已注解	保留
WASM runner	~200	Active module + 已注解	保留
crates/zclaw-saas/src/webhook/	~400	死代码: 未在 lib.rs pub mod 注册，未在 main.rs merge()，无前端调用	删除
crates/zclaw-saas/src/workers/webhook_delivery.rs	~160	死代码: 未在 workers/mod.rs pub mod 注册	删除
admin-v2/src/components/StatusTag.tsx	~20	孤立组件: 从未被导入	删除

---

4.5 近期前端改进 (2026-04-03)

改进	说明
Pipeline 前端接通	8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用
Viking 孤立调用清理	5 个无后端实现的 invoke 已移除
Viking 新方法	addWithMetadata, storeWithSummaries 新增，含 UI
api-fallbacks 标记	_isFallback markers + console.warn logging
MessageSearch 恢复	ChatArea 头部搜索按钮，功能完整
scheduled_task Admin V2	后端 5 CRUD 端点完成，Admin V2 前端 service + page + route + nav 已添加

---

5. 文档漂移记录

以下文档中的数字已与实际不符，需要校准（2026-04-03 已全部修正）：

文档	过时内容	正确值	状态
CLAUDE.md (旧版)	"React 18"	React 19	✅ 已修正
CLAUDE.md (旧版)	"Tailwind CSS"	Tailwind 4	✅ 已修正
CLAUDE.md (旧版)	"Next.js (admin/)"	Vite + Ant Design Pro (admin-v2/)	✅ 已修正
features/README.md	SaaS API: 58	131	✅ 已修正
features/README.md	Tauri 命令: 175	171	✅ 已修正
features/README.md	SaaS Workers: 5	7	✅ 已修正
features/README.md	SKILL: 76	75	✅ 已修正
docs/README.md	Crates: 8	10	✅ 已修正

---

6. 更新日志

日期	更新内容
2026-04-02	初始创建，基于 V11 全面审计 + 二次审计数据
2026-04-02	P0 全部修复 (SEC2-P0-01/02)；P1 全部修复 (SEC2-P1-01~09)
2026-04-02	P1.5 代码质量修复：capability 穷举匹配、SaaS 静默错误、WASM 注解、Tauri 命令标注
2026-04-02	深度审计后修正：8 个 Tauri 标注误标、4 处 SaaS let _ = 清理、TRUTH.md 路由数 58→93
2026-04-02	二次深度审计：(1) 再修正 11 个 Tauri 标注 (147 connected / 24 reserved = 171) (2) 修正文档数字 SKILL 75/Stores 18/Admin 13 (3) relay extract_token_usage + current_key_id 防御性修复 (4) 记录 5 个前端孤立 invoke 调用
2026-04-02	构建验证通过：cargo check ✅ + tsc --noEmit ✅
2026-04-03	数字全面验证校准：SaaS API 93→131 (新增 knowledge 23 + billing 10 + role 11 等模块增长)、Rust 测试 584→383、React 组件 ~50→~135、前端测试 21→23、SaaS Workers 5→7 (新增 aggregate_usage/generate_embedding)、SaaS 路由模块 10→12、数据表 25→34
2026-04-03	前端改进记录：(1) Pipeline 8 invoke 接通前端 (2) Viking 5 孤立 invoke 清理 + 2 新方法+UI (3) api-fallbacks _isFallback 标记 + console.warn 日志 (4) MessageSearch 恢复到 ChatArea (5) scheduled_task Admin V2 完整接入 (service+page+route+nav)
2026-04-04	V12 模块化审计后更新：(1) Pipeline 模板 10→17 YAML (2) Hands 禁用说明细化（无 TOML/Rust 实现） (3) SEC2-P1-01 FactStore 标记 FALSE_POSITIVE (4) V11-P1-03 SQL 表标记 FALSE_POSITIVE (5) M11-02 map_err 已修复 (6) M4-04 深层 WONTFIX
2026-04-05	Admin V2 页面数 14→15（新增 ConfigSync 页面）；桌面端设置页面确认为 19 个
2026-04-06	全面一致性审查：(1) Tauri 命令 177→183 (grep 重新验证) (2) SaaS API 131→130 (webhook 5 路由已定义但未挂载) (3) 删除 webhook 死代码模块 + webhook_delivery worker (4) admin-v2 权限模型修复 (6+ permission key 补全) (5) Logs.tsx 代码重复消除 (6) 清理未使用 service 方法 (agent-templates/billing/roles)