docs: stabilization directive + TRUTH document + AI session prompts + dockerignore
- STABILIZATION_DIRECTIVE.md: feature freeze rules, banned actions, priorities - TRUTH.md: single source of truth for system state (crate counts, store counts) - AI_SESSION_PROMPTS.md: three-layer prompt system for AI sessions - Industry agent delivery design spec - Stabilization test suite for regression prevention - Delete stale ISSUE-TRACKER.md - Add .dockerignore for container builds - Add brainstorm session artifacts
This commit is contained in:
iven
166
docs/TRUTH.md
Normal file
166
docs/TRUTH.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# ZCLAW 系统真相文档
|
||||
|
||||
> **更新日期**: 2026-04-02
|
||||
> **数据来源**: V11 全面审计 + 二次审计 + 代码全量扫描
|
||||
> **规则**: 此文档是唯一真相源。所有其他文档如果与此冲突，以此为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 量化指标（已验证）
|
||||
|
||||
| 指标 | 实际值 | 验证方式 |
|
||||
|------|--------|----------|
|
||||
| Rust Crates | 10 个 (编译通过) | `cargo check --workspace` |
|
||||
| Rust 代码行数 | ~66,000 | wc -l |
|
||||
| Rust 单元测试 | 584 个 | `cargo test --workspace` |
|
||||
| Tauri 命令 | 171 个 | grep `#[tauri::command]` + 注释排除 |
|
||||
| **Tauri 命令有前端调用** | **147 个** | @connected 标注（经二次审计修正） |
|
||||
| **Tauri 命令无前端调用** | **24 个** | @reserved 标注 |
|
||||
| SKILL.md 文件 | 75 个 | `ls skills/*.md \| wc -l` |
|
||||
| Hands 启用 | 9 个 | Browser/Collector/Researcher/Clip/Twitter/Whiteboard/Slideshow/Speech/Quiz |
|
||||
| Hands 禁用 | 2 个 | Predictor, Lead |
|
||||
| SaaS API 端点 | 93 个（含 2 个 dev-only mock） | 路由注册全量统计 |
|
||||
| LLM Provider | 8 个 | Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local |
|
||||
| Zustand Store | 18 个 | ls desktop/src/store/ (含 chat/ 子目录) |
|
||||
| React 组件 | ~50 个 | ls desktop/src/components/ |
|
||||
| 前端 TypeScript 测试 | 21 个文件 | 8 单元 + 12 E2E spec + 1 源码内 |
|
||||
| Admin V2 页面 | 13 个 | admin-v2/src/pages/ 全量统计 |
|
||||
| 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 有已知缺陷
|
||||
|
||||
| 功能 | 问题 | 严重度 |
|
||||
|------|------|--------|
|
||||
| Skill 执行 | 前端传空 context → Rust 反序列化失败 | **P0** |
|
||||
| Hand 异步结果 | Rust emit 事件但前端无 listen() | P1 |
|
||||
| Agent 模板 | API 路径缺 /api/v1 前缀 → 404 | P1 |
|
||||
| Trigger 更新 | 参数格式不匹配 → 静默失败 | P1 |
|
||||
|
||||
### 2.3 已实现但未接通前端
|
||||
|
||||
| 功能 | Rust 状态 | 前端状态 |
|
||||
|------|-----------|----------|
|
||||
| Pipeline 执行 | DSL 引擎完整 | 无 invoke 调用 |
|
||||
| Viking 适配 | FTS5 + TF-IDF | 11 个命令无前端调用 |
|
||||
| Classroom | 27 个命令 | 7 个命令无前端调用 |
|
||||
| Browser Hand | 22 个命令 | 部分无前端调用 |
|
||||
| Multi-agent Director | 912 行 (feature-gated) | 未启用 |
|
||||
|
||||
### 2.4 前端孤立 invoke 调用（无 Rust 后端实现）
|
||||
|
||||
以下 5 个前端 `invoke()` 调用在 Rust 端无对应命令，运行时将返回 "command not found"：
|
||||
|
||||
| 命令 | 前端文件 | 说明 |
|
||||
|------|----------|------|
|
||||
| `viking_add_inline` | `viking-client.ts` | 无 Rust 实现，| `viking_server_start` | `viking-client.ts` | Viking 服务器生命周期管理未实现 |
|
||||
| `viking_server_status` | `viking-client.ts` | 同上 |
|
||||
| `viking_server_stop` | `viking-client.ts` | 同上 |
|
||||
| `viking_server_restart` | `viking-client.ts` | 同上 |
|
||||
|
||||
---
|
||||
|
||||
## 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 命令无连接状态标注 | **已修复** — 171/171 个命令已标注，经二次审计修正 19 个误标（147 @connected / 24 @reserved） |
|
||||
| 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** + 已注解 | 保留 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档漂移记录
|
||||
|
||||
以下文档中的数字已与实际不符，需要校准：
|
||||
|
||||
| 文档 | 过时内容 | 正确值 |
|
||||
|------|----------|--------|
|
||||
| CLAUDE.md (旧版) | "React 18" | React 19 |
|
||||
| CLAUDE.md (旧版) | "Tailwind CSS" | Tailwind 4 |
|
||||
| CLAUDE.md (旧版) | "Next.js (admin/)" | Vite + Ant Design Pro (admin-v2/) |
|
||||
| roadmap.md | Skills: 75 | 76 |
|
||||
| roadmap.md | Tauri 命令: 58+/130+ | 175 |
|
||||
|
||||
---
|
||||
|
||||
## 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 ✅ |
|
||||
Reference in New Issue
Block a user