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/data-flows.md

@@ -0,0 +1,148 @@
+---
+title: 核心数据流
+updated: 2026-04-11
+status: active
+tags: [data-flow, architecture]
+---
+
+# 核心数据流
+
+> 从 [[index]] 导航到此处。架构细节见 [[architecture]]
+
+## 主数据流
+
+```
+用户操作 → React UI → Zustand Store → Tauri invoke() → zclaw-kernel → LLM/Tools/Skills/Hands
+```
+
+这是 ZCLAW 最核心的一条数据通路。所有用户交互都经过这条链路。
+
+## 聊天消息流
+
+```
+用户输入
+  → streamStore.sendMessage(content)
+    → effectiveSessionKey = conversationStore.sessionKey || uuid()
+    → effectiveAgentId = resolveGatewayAgentId(currentAgent)
+    → client.chatStream(content, callbacks, options)
+      → [KernelClient] Tauri invoke('kernel_chat', ...)
+        → Kernel → loop_runner → LLM Driver
+        → Tauri Event emit('chat-response-delta', ...)
+          → onDelta(text) → streamStore 追加 delta
+          → onTool(tool) → toolStore 更新
+          → onHand(hand) → handStore 更新
+          → onComplete() → conversationStore 持久化
+      → [SaaSRelay] HTTP POST /api/v1/relay/chat → SSE stream
+      → [GatewayClient] WebSocket send → onmessage 回调
+  → 5 分钟超时守护 (kernel-chat.ts:76)
+```
+
+## 客户端路由决策流
+
+```
+connectionStore.connect(url?, token?)
+  │
+  ├── Admin 模式? → localStorage('zclaw-saas-account').llm_routing
+  │     ├── "relay" → SaaS Relay
+  │     └── "local" → Kernel (adminForcedLocal=true)
+  │
+  ├── SaaS 模式? → localStorage('zclaw-connection-mode') === 'saas'
+  │     → health check SaaS
+  │       ├── 可达 → Tauri: KernelClient + SaaS baseUrl
+  │       │         Browser: SaaSRelayGatewayClient (SSE)
+  │       └── 不可达 → 降级到本地 Kernel
+  │
+  ├── Tauri 桌面? → isTauriRuntime() === true
+  │     → KernelClient + 自定义模型配置
+  │
+  └── Fallback → GatewayClient via WebSocket/REST
+```
+
+## 记忆管道流
+
+```
+对话发生
+  → extraction_adapter (LLM 提取: 偏好/知识/经验)
+    → MemoryEntry { agent_id, memory_type, content, keywords }
+    → SqliteStorage.store()
+      → FTS5 全文索引 + TF-IDF 权重计算
+      → (可选) EmbeddingClient.embed() → 向量存储 [未激活]
+
+查询时:
+  → MemoryRetriever.retrieve(query, agent_id)
+    → QueryAnalyzer: 意图分类 + 关键词提取 + 同义词扩展 (CJK)
+    → SemanticScorer: TF-IDF 匹配 + (可选) embedding 相似度
+    → 返回 top-k 相关记忆
+
+注入时:
+  → PromptInjector.inject(system_prompt, memories)
+    → token 预算控制
+    → 格式化为结构化上下文块
+    → 插入到 system prompt 中
+```
+
+## SaaS 认证流
+
+```
+用户登录
+  → POST /api/v1/auth/login { email, password }
+  → 验证 (Argon2id + OsRng 盐)
+  → 签发 JWT (Claims: user_id, role, pwv)
+  → set_auth_cookies():
+      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
+      zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly)
+  → 前端: saasStore 存储 → OS keyring 存 JWT
+
+Token 刷新:
+  → POST /api/v1/auth/refresh
+  → 验证 refresh_token (单次使用，旧 token 撤销到 DB)
+  → 签发新 access + refresh token
+
+密码修改:
+  → 更新 password_version (pwv)
+  → 所有旧 JWT 自动失效 (Claims.pwv != DB.pwv)
+```
+
+## 管家模式流
+
+```
+用户消息
+  → ButlerRouter 中间件
+    → 关键词 4 域分类: healthcare / data_report / policy / meeting
+    → 增强 system prompt (领域专用指令)
+  → LLM 响应
+  → PainAggregator 提取痛点
+    → PainStorage (内存 Vec 热缓存 + SQLite 持久)
+  → SolutionGenerator
+    → 基于痛点生成解决方案提案
+
+冷启动:
+  idle → (检测新用户) → greeting_sent → waiting_response → completed
+```
+
+## Pipeline 执行流
+
+```
+YAML Pipeline 定义
+  → PipelineExecutor.load(yaml)
+  → 构建 DAG (按依赖排序)
+  → 逐步执行:
+    → ActionRegistry.resolve(action_type)
+    → 执行 action → PipelineRun.step_results
+    → 全部完成 → PipelineRun.status = Completed
+  → 17 个行业模板在 pipelines/ 目录
+```
+
+## Hands 触发流
+
+```
+UI 触发 → handStore.trigger(handName, params)
+  → Tauri invoke('hand_trigger', { handName, params })
+    → Kernel → Hand 执行
+    → needs_approval? → 等待 approvalStore 确认
+    → 执行结果 → Tauri Event emit
+    → handStore 更新状态 + 记录日志
+```
+
+→ 架构组件见 [[architecture]]
+→ 模块状态见 [[module-status]]