docs(wiki): 创建 LLM Wiki 知识库 — 编译后项目画像

受 Karpathy LLM Wiki 启发，将分散在 docs/ + memory/ + CLAUDE.md 的项目知识
编译为 8 个结构化 wiki 页面，解决新会话冷启动时上下文浪费问题。

- wiki/index.md: 主索引入口 (~200行)，CLAUDE.md @import 自动加载
- wiki/architecture.md: 系统架构编译 (crate依赖/客户端路由/聊天流/LLM驱动)
- wiki/module-status.md: 9个子系统状态 + Hands详情 + 测试覆盖
- wiki/data-flows.md: 6条核心数据流 (聊天/路由/记忆/认证/管家/Pipeline)
- wiki/development.md: 开发规范 (闭环工作法/验证命令/提交规范)
- wiki/known-issues.md: 缺陷状态 (P0/P1已修复，P2待处理)
- wiki/file-map.md: 代码库文件地图 (crates/desktop/admin-v2/docs)
- wiki/log.md: Append-only 变更日志
- CLAUDE.md: 添加 @wiki/index.md + §8.3 收尾流程增加 wiki 维护步骤

wiki/architecture.md

@@ -0,0 +1,147 @@
+---
+title: 系统架构
+updated: 2026-04-11
+status: active
+tags: [architecture, core]
+---
+
+# 系统架构
+
+> 从 [[index]] 导航到此处。详细架构参考: `docs/ARCHITECTURE_BRIEF.md`
+
+## Crate 依赖关系
+
+```
+zclaw-types          (L1: 基础类型, 无依赖)
+    ↑
+zclaw-memory         (L2: SQLite, KV, 会话)
+    ↑
+zclaw-runtime        (L3: 4 Driver, 7 工具, 14 中间件)
+    ↑
+zclaw-kernel         (L4: 182 Tauri 命令, 核心协调)
+    ↑
+zclaw-saas           (独立: Axum + PostgreSQL, 端口 8080)
+    ↑
+desktop/src-tauri    (集成: kernel + skills + hands + protocols)
+```
+
+并行 crates (不依赖 runtime):
+- `zclaw-skills` — 75 SKILL.md 解析 + 语义路由
+- `zclaw-hands` — 9 自主能力
+- `zclaw-protocols` — MCP 完整 + A2A feature-gated
+- `zclaw-pipeline` — Pipeline DSL v1/v2 + DAG 执行器
+- `zclaw-growth` — 记忆增长 (FTS5 + TF-IDF + Embedding trait)
+
+## 客户端路由 (4 分支)
+
+```
+getClient()
+  ├── [1] Admin 路由: localStorage llm_routing → relay/local
+  ├── [2] SaaS Relay: SaaS不可达→降级到本地 Kernel
+  ├── [3] Local Kernel: Tauri 内置 (桌面端默认)
+  └── [4] External Gateway: WebSocket/REST fallback
+```
+
+关键文件: `desktop/src/store/connectionStore.ts:844`
+
+## 聊天流 (3 种实现)
+
+| 实现 | 传输 | 场景 |
+|------|------|------|
+| GatewayClient | WebSocket | 外部 Gateway 进程 |
+| KernelClient | Tauri Event | 内置 Kernel (默认) |
+| SaaSRelay | HTTP SSE | 浏览器端 SaaS 中继 |
+
+统一回调: `{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }`
+5 分钟超时守护: `desktop/src/lib/kernel-chat.ts:76`
+
+## LLM 驱动 (4 + 3)
+
+### Rust Driver
+
+| Driver | 文件 | 协议 |
+|--------|------|------|
+| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages |
+| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat |
+| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini |
+| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama |
+
+### 国内兼容 (通过 OpenAI 协议 + base_url)
+
+| Provider | base_url |
+|----------|----------|
+| DeepSeek | `https://api.deepseek.com` |
+| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Moonshot | `https://api.moonshot.cn/v1` |
+
+API Key → OS keyring (`secure-storage.ts`)
+
+## 管家模式 (默认激活)
+
+```
+用户消息 → ButlerRouter (4域关键词分类) → 增强 system prompt → LLM
+                                                              ↓
+                                              PainAggregator → PainStorage (内存+SQLite)
+                                                              ↓
+                                              SolutionGenerator (痛点→方案)
+```
+
+- 冷启动: idle → greeting_sent → waiting_response → completed
+- UI 双模式: simple (纯聊天, 默认) / professional (完整功能)
+- ButlerRouter 文件: `crates/zclaw-runtime/src/middleware/butler_router.rs`
+
+## 记忆管道 (闭环)
+
+```
+对话 → extraction_adapter (LLM 提取)
+     → FTS5 全文索引 + TF-IDF 权重
+     → 检索 (查询时召回)
+     → 注入 system prompt (token 预算控制)
+```
+
+- EmbeddingClient trait 已定义但未激活
+- zclaw-saas 有 pgvector HNSW 索引就绪，embedding 生成 deferred
+
+## SaaS 认证
+
+| 数据 | 存储 |
+|------|------|
+| JWT Token | OS Keyring |
+| 账户信息 | localStorage |
+| Cookie | HttpOnly + Secure + SameSite=Strict |
+
+- JWT password_version: 改密码→所有旧 JWT 失效
+- Token 池: RPM/TPM 限流轮换
+- SaaS unreachable → 自动降级本地 Kernel
+
+## 中间件链 (14 层)
+
+关键中间件:
+- DataMasking@90 — 请求前数据脱敏
+- ButlerRouter — 4域关键词分类 + system prompt 增强
+- TrajectoryRecorder@650 — 轨迹记录压缩
+
+## 关键文件速查
+
+### 前端
+
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/store/connectionStore.ts` | 客户端路由 |
+| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
+| `desktop/src/store/chat/conversationStore.ts` | 会话管理 |
+| `desktop/src/store/saasStore.ts` | SaaS 认证 |
+| `desktop/src/store/uiModeStore.ts` | 简洁/专业模式 |
+| `desktop/src/hooks/use-cold-start.ts` | 管家冷启动 |
+
+### 后端
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动 |
+| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 |
+| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证 |
+| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 |
+
+→ 数据流细节见 [[data-flows]]
+→ 模块状态见 [[module-status]]