8898bb399e
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
Update audit tracker, roadmap, architecture docs, add admin-v2 Roles page + Billing tests, sync CLAUDE.md, Cargo.toml, docker-compose.yml, add deep-research / frontend-design / chart-visualization skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
237 lines
9.8 KiB
Markdown
237 lines
9.8 KiB
Markdown
# 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. 验证命令
|
||
|
||
```bash
|
||
# 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"
|
||
```
|