zclaw_openfang/docs/features/COMPREHENSIVE_AUDIT_V11.md

ZCLAW 全面功能审计报告 V11

审计日期: 2026-04-02 审计范围: 10 Rust crate + desktop 前端 + admin-v2 管理后台 基线: V10 审计追踪（20 项发现）

---

1. 执行摘要

关键指标

指标	数值	文档值	状态
Tauri 命令（注册）	175	58+ / 130+	文档不一致
Tauri 命令（有前端调用）	~90	-	51% 利用率
SKILL.md	76	66/75/77	文档不一致
Hands	9 目录	11	CLAUDE.md 与实际不一致
Zustand Stores	15	14	文档偏差
SaaS API 路由	58	72+	文档偏高
Admin-v2 页面	12	11	文档偏低
源文件	233 (.rs) + 122 (.tsx) + 15 (.ts store)	-	-

V10→V11 状态变更

V10 ID	V11 状态	说明
BREAK-02	关闭	记忆提取通过 MemoryMiddleware.after_completion 正常触发
BREAK-03	关闭	approval_respond 自动 spawn tokio task 执行 Hand
BREAK-04	关闭	pipeline-complete 在 discovery.rs:165 emit，前端有监听器
BREAK-01	已修复	保持 CLOSED

---

2. 发现项索引

P1: 严重级（3 项）

ID	问题	文件	验证方法
V11-P1-01	trigger_update 参数不匹配，更新静默失败	desktop/src/lib/kernel-triggers.ts:99 → desktop/src-tauri/src/kernel_commands/trigger.rs:183-189	前端发 {id, updates:{...}} 但 Rust 期望扁平参数
V11-P1-02	SaaS 配置同步不传播到 Rust Kernel	desktop/src/store/saasStore.ts:484-541	localStorage 写入但 Kernel 无读取路径
V11-P1-03	3 个 SQL 表零读取：prompt_sync_status, telemetry_reports, key_usage_window	crates/zclaw-saas/src/db.rs 迁移定义	grep -rn "SELECT.*FROM.*<table>" crates/zclaw-saas/src/ 零结果

P2: 高优先级（6 项）

ID	问题	文件
V11-P2-01	saas-admin.ts 30 方法零消费者（admin-v2 独立 Axios 实现）	desktop/src/lib/saas-admin.ts
V11-P2-02	7 个 Role/Permission 路由无前端消费者	crates/zclaw-saas/src/role/mod.rs
V11-P2-03	deprecated gateway-storage sync 方法仍被生产代码调用	desktop/src/lib/gateway-storage.ts:129,196
V11-P2-04	ToolDefinition 在 types 和 runtime 重复定义	crates/zclaw-types/src/tool.rs:8 vs crates/zclaw-runtime/src/driver/mod.rs:94
V11-P2-05	62 个 Tauri 命令无前端调用（含 8 classroom 命令中 7 个未调用）	desktop/src-tauri/src/lib.rs:124-323
V11-P2-06	migration/service.rs config_items 查询缺少 LIMIT	crates/zclaw-saas/src/migration/service.rs

P3: 中优先级（8 项）

ID	问题	文件
V11-P3-01	audit-logger.ts 导出但零 import	desktop/src/lib/audit-logger.ts
V11-P3-02	OFP 能力定义无消费者	crates/zclaw-types/src/capability.rs:28-32
V11-P3-03	deprecated extract_structured_facts() 零调用但未移除	crates/zclaw-runtime/src/growth.rs:224
V11-P3-04	SaaS knowledge 模块 3 个 handler 返回空数据	crates/zclaw-saas/src/knowledge/handlers.rs:91,293,321
V11-P3-05	Director (multi-agent) 912 行 feature-gated 未启用	crates/zclaw-kernel/src/director.rs
V11-P3-06	定时任务执行结果未持久化	crates/zclaw-saas/src/scheduler.rs:147-225
V11-P3-07	secure-storage.ts 3 个 deprecated sync 方法零调用	desktop/src/lib/secure-storage.ts:309,317,325
V11-P3-08	SaaS config 2 个预留参数未消费	crates/zclaw-saas/src/config.rs:122,125

P4: 低优先级（5 项）

ID	问题	文件
V11-P4-01	ContentBlock 4 处定义（不同域，非 bug 但名称混淆）	types/message.rs, runtime/driver/mod.rs, hands/slideshow.rs, protocols/mcp_types.rs
V11-P4-02	Desktop ↔ Admin 13+ 类型名称不一致	desktop/src/lib/saas-types.ts vs admin-v2/src/types/index.ts
V11-P4-03	文档数字不一致（Skills 76 vs 66/75/77）	多个文档
V11-P4-04	A2A/WASM feature-gated 代码未启用	crates/zclaw-protocols/src/a2a.rs, crates/zclaw-skills/src/wasm_runner.rs
V11-P4-05	embedding 生成已禁用（注释掉）	crates/zclaw-saas/src/workers/generate_embedding.rs:92

Info: 保留不变（V10 继承）

V10 ID	状态	说明
DEAD-01	FALSE_POSITIVE	PromptInjector 已通过 PromptBuilder 接入
DEAD-02	FALSE_POSITIVE	MemoryRetriever 已通过 MemoryMiddleware 接入
DEAD-03	FALSE_POSITIVE	GrowthTracker 已通过 GrowthIntegration 接入
SEC-V9-01	FALSE_POSITIVE	SQL 仅构建 $N 占位符

---

3. Rust Crate 能力矩阵

Crate	源文件	行数	公开项	Feature-Gate	Dead Code	Deprecated	测试
zclaw-types	10	1,741	86	0	0	0	57
zclaw-memory	5	1,333	36	0	0	0	25
zclaw-runtime	35	9,145	188	0	5	1	42
zclaw-kernel	25	8,185	225	22 (multi-agent)	3	0	52
zclaw-skills	15	4,057	116	4 (wasm)	0	0	22
zclaw-hands	14	7,501	140	0	0	0	155
zclaw-protocols	5	1,697	104	2 (a2a)	1	0	5
zclaw-pipeline	23	7,502	200	0	1	0	59
zclaw-growth	14	4,732	137	0	2	0	66
zclaw-saas	87	14,949	489	0	2	0	17
合计	233	64,842	1,621	28	14	1	500

Trait 实现完整性

Trait	定义位置	实现数	状态
LlmDriver	zclaw-runtime/driver/mod.rs	4	完整
Tool	zclaw-runtime/tool.rs	7	完整
Hand	zclaw-hands/hand.rs	9	完整
Exporter	zclaw-kernel/export/mod.rs	4	完整
McpClient	zclaw-protocols/mcp.rs	2	完整
A2aClient	zclaw-protocols/a2a.rs	1 (gated)	Feature-gated
FactStore	zclaw-memory/fact.rs	0	未实现
Worker	zclaw-saas/workers/mod.rs	7	完整

---

4. 数据流验证结果

Flow A: 聊天 → 记忆提取 ✅ WORKING

chat.rs:246 (LoopEvent::Complete)
  → loop_runner.rs:798 (run_after_completion)
    → MemoryMiddleware.after_completion (middleware/memory.rs:101)
      → GrowthIntegration.extract_combined (growth.rs:279)
        → MemoryExtractor.extract + store_memories

Tauri post_conversation_hook 不重复提取，仅处理心跳+反思。

Flow B: 审批 → Hand 自动执行 ✅ WORKING

approval.rs:52 → kernel.respond_to_approval (approvals.rs:55)
  → tokio::spawn (approvals.rs:71)
    → hands.execute (approvals.rs:99)
    → emit "hand-execution-complete" (approval.rs:84-137)

Flow C: Pipeline 完成事件 ✅ WORKING

Rust emit: discovery.rs:165 → app.emit("pipeline-complete", ...)
Frontend listen: pipeline-client.ts:257 → PipelinesPanel.tsx:383

Flow D: SaaS 配置同步 ❌ BROKEN

saasStore.ts:484 → saasClient.pullConfig → localStorage write
⚠️ 无传播路径到 Rust Kernel

配置变更停留在 localStorage，Kernel 独立读取 TOML 文件，不受 SaaS 配置同步影响。

---

5. Admin-v2 审计

页面与 API 对齐

页面	Service 文件	API 调用数	状态
Login	auth.ts	2	完整
Dashboard	stats.ts	1	完整
Accounts	accounts.ts	4	完整
ModelServices	providers.ts + models.ts	11	完整
Config	config.ts	2	完整
Relay	relay.ts	2	完整
Logs	logs.ts	1	完整
Prompts	prompts.ts	7	完整
Usage	usage.ts	2	完整
Billing	billing.ts	6	完整
AgentTemplates	agent-templates.ts	5	完整
Knowledge	knowledge.ts	15	完整（后端有 3 个 stub handler）

类型一致性

Desktop ↔ Admin-v2 之间存在 13+ 类型名称不一致（详见 V11_GAP_ANALYSIS.md）。

3 个有意义的字段差异：

1. AccountPublic.llm_routing: desktop 可选 vs admin 必填
2. TokenInfo nullability: string | null vs string | undefined
3. PromptVariable.type: string vs 'string'|'number'|'select'|'boolean'

---

6. 孤立路由清单

路由	模块	原因
POST /api/v1/auth/logout	auth	无消费者
GET /api/v1/config/analysis	migration	无消费者
POST /api/v1/config/seed	migration	无消费者
GET /api/v1/config/sync-logs	migration	无消费者
GET /api/v1/usage (model_config)	model_config	无消费者
GET/POST /api/v1/roles	role	无 admin-v2 service
GET/PUT/DELETE /api/v1/roles/:id	role	无 admin-v2 service
GET/POST /api/v1/permission-templates	role	无 admin-v2 service
GET/DELETE /api/v1/permission-templates/:id	role	无 admin-v2 service
POST /api/v1/permission-templates/:id/apply	role	无 admin-v2 service
GET /api/v1/roles/:id/permissions	role	无 admin-v2 service

---

7. 验证命令

# Skills 计数
ls skills/ | wc -l  # 预期: 76

# Hands 计数
ls hands/ | wc -l   # 预期: 9

# Tauri 命令计数
grep -c "#\[tauri::command\]" desktop/src-tauri/src/ -r --include="*.rs"  # 预期: 175

# 死代码验证
grep -rn "from.*audit-logger" desktop/src/ --include="*.ts"  # 预期: 0 结果

# 孤立表验证
grep -rn "SELECT.*FROM.*prompt_sync_status" crates/zclaw-saas/src/  # 预期: 0 结果
grep -rn "SELECT.*FROM.*telemetry_reports" crates/zclaw-saas/src/    # 预期: 0 结果
grep -rn "SELECT.*FROM.*key_usage_window" crates/zclaw-saas/src/     # 预期: 0 结果

# deprecated 函数调用者
grep -rn "extract_structured_facts" crates/ --include="*.rs"  # 仅定义和注释引用

# trigger_update 参数不匹配
grep -A5 "trigger_update" desktop/src/lib/kernel-triggers.ts
grep -A5 "trigger_update" desktop/src-tauri/src/kernel_commands/ -r --include="*.rs"