docs: add architecture awareness system — CLAUDE.md §13/§14 + ARCHITECTURE_BRIEF

- Activate CLAUDE.md with §13 architecture snapshot (auto-sync markers) and §14 anti-pattern warnings + scenario instructions - Fix dead link to non-existent STABILIZATION_DIRECTIVE.md - Update stale numbers (93→130 SaaS APIs, 171→182 Tauri commands, 13→15 admin pages) - Create docs/ARCHITECTURE_BRIEF.md as permanent architecture reference covering 10 subsystems (butler, chatstream, LLM drivers, client routing, SaaS auth, memory pipeline, Pipeline DSL, Hands, middleware, key paths) - Add /sync-arch skill for manual or workflow-triggered architecture sync - Add PostToolUse hook to remind doc sync after git commit/push - Update §8.3 completion flow to include architecture snapshot updates - Mark memory files (system_architecture, butler_mode) as migrated to BRIEF - Add ARCHITECTURE_BRIEF.md as top entry in MEMORY.md index
2026-04-09 14:09:26 +08:00
parent 26f50cd746
commit f2d6a3b6b7
5 changed files with 467 additions and 11 deletions
--- a/docs/ARCHITECTURE_BRIEF.md
+++ b/docs/ARCHITECTURE_BRIEF.md
@@ -0,0 +1,299 @@
+# ZCLAW 架构概览
+
+> **永久最新参考文档** — 每次重大变更后由 auto-sync 更新。
+> 最后更新: 2026-04-09
+> 详细功能文档见 [docs/features/](features/README.md)
+
+---
+
+## 1. 管家模式 (Butler Mode)
+
+管家模式是 ZCLAW 的核心交互范式，默认激活。
+
+### 架构组件
+
+| 组件 | 文件 | 职责 |
+|------|------|------|
+| ButlerRouter | `crates/zclaw-runtime/src/middleware/butler_router.rs` | 关键词4域分类 (healthcare/data_report/policy/meeting)，增强 system prompt |
+| PainStorage | `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点双写 (内存 Vec 热缓存 + SQLite 持久层)，全局 `PAIN_STORAGE` 单例 |
+| SolutionGenerator | `crates/zclaw-kernel/src/intelligence/solution_generator.rs` | 基于痛点生成解决方案提案 |
+| Cold Start Hook | `desktop/src/hooks/use-cold-start.ts` | 4阶段: idle→greeting_sent→waiting_response→completed |
+| UI Mode Store | `desktop/src/store/uiModeStore.ts` | 双模式切换: 'simple'(默认, 纯聊天) / 'professional'(完整功能) |
+| SimpleSidebar | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 |
+
+### 数据流
+
+```
+用户消息 → ButlerRouter (关键词分类) → 增强 system prompt → LLM → 响应
+                                                              ↓
+                                              PainAggregator → PainStorage (内存+SQLite双写)
+                                                              ↓
+                                              SolutionGenerator (基于痛点生成提案)
+```
+
+---
+
+## 2. 聊天流 (ChatStream)
+
+3 种 ChatStream 实现，由 `getClient()` 路由决定使用哪种。
+
+### 实现对比
+
+| 实现 | 类 | 传输协议 | 使用场景 |
+|------|------|----------|----------|
+| GatewayClient.chatStream | `desktop/src/lib/gateway-client.ts` | WebSocket | 外部 ZCLAW Gateway 进程 |
+| KernelClient.chatStream | `desktop/src/lib/kernel-chat.ts` | Tauri Event | 内置 Kernel (桌面端默认) |
+| SaaSRelay.chatStream | `desktop/src/lib/saas-relay-client.ts` | HTTP SSE | 浏览器端 SaaS 中继 |
+
+### 统一回调接口
+
+所有实现共享相同的 callback 结构:
+
+```ts
+{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }
+```
+
+### StreamStore 发送流程
+
+```
+streamStore.sendMessage(content)
+  → effectiveSessionKey = conversationStore.sessionKey || crypto.randomUUID()
+  → effectiveAgentId = resolveGatewayAgentId(currentAgent)
+  → client.chatStream(content, callbacks, { sessionKey, agentId, chatMode... })
+  → 5-minute timeout guard (kernel-chat.ts:76) 防止流挂起
+```
+
+---
+
+## 3. LLM 驱动 (Provider Drivers)
+
+### 4 个 Rust Driver
+
+| Driver | 文件 | 协议 |
+|--------|------|------|
+| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages API |
+| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat Completions API |
+| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini API |
+| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama (localhost:11434) |
+
+### Driver Factory
+
+```
+LlmConfig::create_driver()
+  match api_protocol:
+    Anthropic → AnthropicDriver (base_url 为空时用原生 SDK)
+    OpenAI    → OpenAiDriver (base_url 可指向兼容端点)
+```
+
+### 国内 Provider (通过 OpenAI 兼容协议)
+
+| Provider | base_url |
+|----------|----------|
+| DeepSeek | `https://api.deepseek.com` |
+| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Moonshot | `https://api.moonshot.cn/v1` |
+
+### 前端模型配置
+
+```
+CustomModel { id, name, provider, apiKey, apiProtocol, baseUrl }
+```
+
+API Key 存储在 OS keyring (非 localStorage)，通过 `secure-storage.ts` 管理。
+
+---
+
+## 4. 客户端路由 (Client Routing)
+
+### 路由决策树
+
+```
+connectionStore.connect(url?, token?)
+  │
+  ├── [1] Admin 路由: localStorage('zclaw-saas-account').llm_routing
+  │     relay → SaaS Relay 模式
+  │     local  → Kernel 模式 (adminForcedLocal=true)
+  │
+  ├── [2] SaaS Relay: localStorage('zclaw-connection-mode') === 'saas'
+  │     health check → 不可达时降级到本地 Kernel
+  │     Tauri: KernelClient + SaaS baseUrl
+  │     Browser: SaaSRelayGatewayClient (SSE)
+  │
+  ├── [3] Local Kernel: isTauriRuntime() === true
+  │     KernelClient + 自定义模型配置
+  │
+  └── [4] External Gateway (fallback)
+        GatewayClient via WebSocket/REST
+```
+
+### 客户端类型
+
+| 客户端 | 传输 | 用途 |
+|--------|------|------|
+| GatewayClient | WebSocket + REST | 外部 Gateway 进程 |
+| KernelClient | Tauri invoke() | 内置 Kernel |
+| SaaSRelayGatewayClient | HTTP SSE | 浏览器端 SaaS 中继 |
+
+`getClient()` 定义在 `connectionStore.ts:844`，所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client 实例。
+
+---
+
+## 5. SaaS 认证 (Token Pool)
+
+### 会话存储
+
+| 数据 | 存储位置 | Key |
+|------|----------|-----|
+| JWT Token | OS Keyring | `zclaw-saas-token` |
+| SaaS URL | localStorage | `zclaw-saas-url` |
+| 账户信息 | localStorage | `zclaw-saas-account` |
+| 连接模式 | localStorage | `zclaw-connection-mode` |
+
+### Cookie 认证
+
+后端通过 `set_auth_cookies()` (saas/auth/handlers.rs) 设置:
+- `zclaw_access_token` (path: /api, 2h TTL)
+- `zclaw_refresh_token` (path: /api/v1/auth, 7d TTL)
+- Secure: dev=false, prod=true | SameSite=Strict | HttpOnly=true
+
+### Token 池与限流
+
+SaaS Relay 端点实施 RPM/TPM 限流轮换:
+- JWT password_version: 密码修改后所有已签发 JWT 自动失效
+- SaaS unreachable 时 `connectionStore.ts:456-466` 自动降级到本地 Kernel
+
+---
+
+## 6. 记忆管道 (Memory Pipeline)
+
+### 闭环架构
+
+```
+用户对话 → extraction_adapter (LLM提取关键信息)
+         → FTS5 全文索引 + TF-IDF 权重计算
+         → 检索 (查询时召回相关记忆)
+         → 注入系统提示 (提供给 LLM 上下文)
+```
+
+### 关键组件
+
+| 组件 | 位置 | 职责 |
+|------|------|------|
+| GrowthCrate | `crates/zclaw-growth/` | FTS5 + TF-IDF 核心 |
+| ExtractionAdapter | `crates/zclaw-kernel/` | 从对话提取结构化信息 |
+| TauriExtractionDriver | `desktop/src-tauri/` | 桥接前端与后端提取 |
+| MemoryStore | `desktop/src/store/` | 前端记忆状态管理 |
+
+### 存储
+
+- 对话记忆: SQLite (zclaw-memory crate)
+- 向量嵌入: PostgreSQL + pgvector 0.8.2 (zclaw-saas)
+- API Key: OS keyring (secure-storage.ts)
+
+---
+
+## 7. Pipeline DSL
+
+### 架构
+
+```
+YAML Pipeline 定义
+  → PipelineExecutor (crates/zclaw-pipeline/src/executor.rs)
+  → DAG 运行器 (按依赖顺序执行步骤)
+  → ActionRegistry (步骤动作注册)
+  → PipelineRun { status, current_step, step_results, outputs }
+```
+
+### 运行状态
+
+```rust
+enum RunStatus { Pending, Running, Completed, Failed, Cancelled }
+```
+
+### 前端集成
+
+| 组件 | 文件 |
+|------|------|
+| PipelineClient | `desktop/src/lib/pipeline-client.ts` |
+| usePipelineRun hook | React 状态管理 |
+| Pipeline Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` |
+
+### 模板
+
+17 个 YAML 模板覆盖 10 大行业 (汕头玩具/服装设计/医疗等)，位于 `pipelines/` 目录。
+
+---
+
+## 8. Hands 自主能力系统
+
+### 9 个启用的 Hands
+
+| Hand | 能力 | 关键依赖 |
+|------|------|----------|
+| Browser | 浏览器自动化 | WebDriver |
+| Collector | 数据收集聚合 | — |
+| Researcher | 深度研究 | LLM |
+| Clip | 视频处理 | FFmpeg |
+| Twitter | Twitter 自动化 | OAuth 1.0a (写操作) |
+| Whiteboard | 白板演示 | — (导出开发中) |
+| Slideshow | 幻灯片生成 | — |
+| Speech | 语音合成 | Browser TTS |
+| Quiz | 测验生成 | — |
+
+### 触发流程
+
+```
+UI 触发 → handStore → Tauri invoke('hand_trigger')
+  → Kernel → Hand 执行
+  → needs_approval? → 等待用户审批 → approvalStore
+  → 执行日志记录
+```
+
+### 配置
+
+每个 Hand 通过 `hands/<Name>/HAND.toml` 配置，包含:
+- enabled 状态
+- 参数定义
+- needs_approval 标记
+- 依赖声明
+
+---
+
+## 9. 中间件链 (12 层)
+
+运行时注册顺序 (优先级 0-100):
+
+```
+DataMasking@90 → ButlerRouter → (其他10层) → LLM 调用
+```
+
+DataMasking (优先级 90) 在请求发送前执行数据脱敏。ButlerRouter 在消息流中注入领域分类的 system prompt 增强。
+
+---
+
+## 10. 关键文件路径速查
+
+### 前端核心
+
+| 文件 | 职责 |
+|------|------|
+| `desktop/src/store/connectionStore.ts` | 客户端路由、连接模式、模型配置 |
+| `desktop/src/store/index.ts` | Store 协调器、共享 client 注入 |
+| `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` | 管家冷启动 hook |
+
+### 后端核心
+
+| 文件 | 职责 |
+|------|------|
+| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动序列 |
+| `crates/zclaw-kernel/src/config.rs` | LLM 配置 + Driver 工厂 |
+| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 (迭代工具使用) |
+| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 |
+| `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点持久化 |
+| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证端点 |
+| `crates/zclaw-pipeline/src/executor.rs` | Pipeline 执行器 |
+| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 (182个) |