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/.claude/hooks/arch-sync-check.js
+++ b/.claude/hooks/arch-sync-check.js
@@ -0,0 +1,28 @@
+// arch-sync-check.js
+// PostToolUse hook: detects git commit/push and reminds to sync architecture docs
+// Reads tool input from stdin, outputs reminder if git operation detected
+
+const CHUNKS = [];
+process.stdin.on('data', (c) => CHUNKS.push(c));
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(Buffer.concat(CHUNKS).toString());
+    const toolName = input.tool_name || '';
+    const toolInput = input.tool_input || {};
+
+    // Only check Bash tool calls
+    if (toolName !== 'Bash') return;
+
+    const cmd = (toolInput.command || '').trim();
+
+    // Detect git commit or git push
+    const isGitCommit = cmd.startsWith('git commit') || cmd.includes('&& git commit');
+    const isGitPush = cmd.startsWith('git push') || cmd.includes('&& git push');
+
+    if (isGitCommit || isGitPush) {
+      console.log('[arch-sync] Architecture docs may need updating. Run /sync-arch or update CLAUDE.md §13 + ARCHITECTURE_BRIEF.md as part of §8.3 completion flow.');
+    }
+  } catch {
+    // Silently ignore parse errors
+  }
+});
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/arch-sync-check.js"
+          }
+        ]
+      }
+    ]
+  }
+}
--- a/.claude/skills/sync-arch
+++ b/.claude/skills/sync-arch
@@ -0,0 +1,52 @@
+# Architecture Sync Skill
+
+Analyze recent git changes and update the architecture documentation to keep it current.
+
+## When to use
+
+- After completing a significant feature or bugfix
+- As part of the §8.3 completion flow
+- When you notice the architecture snapshot is stale
+- User runs `/sync-arch`
+
+## Steps
+
+1. **Gather context**: Run `git log --oneline -10` and identify commits since the last ARCH-SNAPSHOT update date (check the comment in CLAUDE.md `<!-- ARCH-SNAPSHOT-START -->` section).
+
+2. **Analyze changes**: For each relevant commit, determine which subsystems were affected:
+   - Butler/管家模式 (butler_router, pain_storage, cold_start, ui_mode)
+   - ChatStream/聊天流 (kernel-chat, gateway-client, saas-relay, streamStore)
+   - LLM Drivers/驱动 (driver/*, config.rs)
+   - Client Routing/客户端路由 (connectionStore)
+   - SaaS Auth/认证 (saas-session, auth handlers, token pool)
+   - Memory Pipeline/记忆管道 (growth, extraction, FTS5)
+   - Pipeline DSL (pipeline/*, executor)
+   - Hands (hands/*, handStore)
+   - Middleware (middleware/*)
+   - Skills (skills/*, skillStore)
+
+3. **Update CLAUDE.md §13** (between `<!-- ARCH-SNAPSHOT-START -->` and `<!-- ARCH-SNAPSHOT-END -->`):
+   - Update the "活跃子系统" table: change status and latest change for affected subsystems
+   - Update "关键架构模式": modify descriptions if architecture changed
+   - Update "最近变更": add new entries, keep only the most recent 4-5
+   - Update the date in the comment `<!-- 此区域由 auto-sync 自动更新，更新时间: YYYY-MM-DD -->`
+
+4. **Update CLAUDE.md §14** (between `<!-- ANTI-PATTERN-START -->` and `<!-- ANTI-PATTERN-END -->`):
+   - Add new anti-patterns if new pitfalls were discovered
+   - Add new scenario instructions if new common patterns emerged
+   - Remove items that are no longer relevant
+
+5. **Update docs/ARCHITECTURE_BRIEF.md**:
+   - Update the affected subsystem sections with new details
+   - Add new components, files, or data flows that were introduced
+   - Update the "最后更新" date at the top
+
+6. **Commit**: Create a commit with message `docs(sync-arch): update architecture snapshot for <date>`
+
+## Rules
+
+- Only update content BETWEEN the HTML comment markers — never touch other parts of CLAUDE.md
+- Keep the snapshot concise — the §13 section should be under 50 lines
+- Use accurate dates from git log, not approximations
+- If no significant changes since last update, do nothing (don't create empty commits)
+- Architecture decisions > code details — focus on WHAT and WHY, not line numbers
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,8 +2,7 @@

 > **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**，专注于提供真实可用的 AI 能力，而不是演示 UI。

-> **当前阶段: 稳定化。** 参见 [docs/STABILIZATION_DIRECTIVE.md](docs/STABILIZATION_DIRECTIVE.md)
-> 在 P0 缺陷修复完成前，不接受任何新功能。所有 AI 会话必须先确认稳定化状态。
+> **当前阶段: 发布前管家模式实施。** 稳定化基线已达成，管家模式6交付物已完成。

 ## 1. 项目定位

@@ -30,15 +29,15 @@ ZCLAW 是面向中文用户的 AI Agent 桌面端，核心能力包括：

 ### 1.3 稳定化铁律

-**在 [STABILIZATION_DIRECTIVE.md](docs/STABILIZATION_DIRECTIVE.md) 完成标准达标前，以下行为被禁止：**
+**稳定化基线达成后仍需遵守以下约束：**

 | 禁止行为 | 原因 |
 |----------|------|
-| 新增 SaaS API 端点 | 已有 93 个（含 2 个 dev-only），前端未全部接通 |
+| 新增 SaaS API 端点 | 已有 130 个（含 2 个 dev-only），前端未全部接通 |
 | 新增 SKILL.md 文件 | 已有 75 个，大部分未执行验证 |
-| 新增 Tauri 命令 | 已有 171 个，24 个无前端调用 |
+| 新增 Tauri 命令 | 已有 182 个，70 个无前端调用且无 @reserved |
 | 新增中间件/Store | 已有 12 层中间件 + 18 个 Store |
-| 新增 admin 页面 | 已有 13 页 |
+| 新增 admin 页面 | 已有 15 页 |

 ### 1.4 系统真实状态

@@ -53,13 +52,13 @@ ZCLAW/
 │   ├── zclaw-types/          # L1: 基础类型 (AgentId, Message, Error)
 │   ├── zclaw-memory/         # L2: 存储层 (SQLite, KV, 会话管理)
 │   ├── zclaw-runtime/        # L3: 运行时 (4 Driver, 7 工具, 12 层中间件)
-│   ├── zclaw-kernel/         # L4: 核心协调 (171 Tauri 命令)
+│   ├── zclaw-kernel/         # L4: 核心协调 (182 Tauri 命令)
 │   ├── zclaw-skills/         # 技能系统 (75 SKILL.md 解析, 语义路由)
 │   ├── zclaw-hands/          # 自主能力 (9 启用, 106 Rust 测试)
 │   ├── zclaw-protocols/      # 协议支持 (MCP 完整, A2A feature-gated)
 │   ├── zclaw-pipeline/       # Pipeline DSL (v1/v2, 10 行业模板)
 │   ├── zclaw-growth/         # 记忆增长 (FTS5 + TF-IDF)
-│   └── zclaw-saas/           # SaaS 后端 (93 API, Axum + PostgreSQL)
+│   └── zclaw-saas/           # SaaS 后端 (130 API, Axum + PostgreSQL)
 ├── admin-v2/                 # 管理后台 (Vite + Ant Design Pro, 13 页)
 ├── desktop/                  # Tauri 桌面应用
 │   ├── src/
@@ -351,9 +350,11 @@ docs/
 检查以下文档是否需要更新，有变更则立即修改：

 1. **CLAUDE.md** — 项目结构、技术栈、工作流程、命令变化时
-2. **docs/features/** — 功能状态变化时
-3. **docs/knowledge-base/** — 新的排查经验或配置说明
-4. **docs/TRUTH.md** — 数字（命令数、Store 数、crates 数等）变化时
+2. **CLAUDE.md §13 架构快照** — 涉及子系统变更时，更新 `<!-- ARCH-SNAPSHOT-START/END -->` 标记区域（可执行 `/sync-arch` 技能自动分析）
+3. **docs/ARCHITECTURE_BRIEF.md** — 架构决策或关键组件变更时
+4. **docs/features/** — 功能状态变化时
+5. **docs/knowledge-base/** — 新的排查经验或配置说明
+6. **docs/TRUTH.md** — 数字（命令数、Store 数、crates 数等）变化时

 #### 步骤 B：提交（按逻辑分组）

@@ -516,3 +517,64 @@ refactor(store): 统一 Store 数据获取方式
 ### 完整审计报告

 参见 `docs/features/SECURITY_PENETRATION_TEST_V1.md`
+
+***
+
+<!-- ARCH-SNAPSHOT-START -->
+<!-- 此区域由 auto-sync 自动更新，请勿手动编辑。更新时间: 2026-04-09 -->
+
+## 13. 当前架构快照
+
+### 活跃子系统
+
+| 子系统 | 状态 | 最新变更 |
+|--------|------|----------|
+| 管家模式 (Butler) | ✅ 活跃 | 04-09 ButlerRouter + 双模式UI + 痛点持久化 + 冷启动 |
+| 聊天流 (ChatStream) | ✅ 稳定 | 04-02 ChatStore 拆分为 4 Store (stream/conversation/message/chat) |
+| 记忆管道 (Memory) | ✅ 稳定 | 04-02 闭环修复: 对话→提取→FTS5+TF-IDF→检索→注入 |
+| SaaS 认证 (Auth) | ✅ 稳定 | Token池 RPM/TPM 轮换 + JWT password_version 失效机制 |
+| Pipeline DSL | ✅ 稳定 | 04-01 17 个 YAML 模板 + DAG 执行器 |
+| Hands 系统 | ✅ 稳定 | 9 启用 (Browser/Collector/Researcher/Twitter/Whiteboard/Slideshow/Speech/Quiz/Clip) |
+| 技能系统 (Skills) | ✅ 稳定 | 75 个 SKILL.md + 语义路由 |
+| 中间件链 | ✅ 稳定 | 12 层 (含 DataMasking@90, ButlerRouter) |
+
+### 关键架构模式
+
+- **管家模式**: 双模式UI (默认简洁/解锁专业) + ButlerRouter 4域关键词分类 (healthcare/data_report/policy/meeting) + 冷启动4阶段hook (idle→greeting→waiting→completed) + 痛点双写 (内存Vec+SQLite)
+- **聊天流**: 3种实现 → GatewayClient(WebSocket) / KernelClient(Tauri Event) / SaaSRelay(SSE) + 5min超时守护。详见 [ARCHITECTURE_BRIEF.md](docs/ARCHITECTURE_BRIEF.md)
+- **客户端路由**: `getClient()` 4分支决策树 → Admin路由 / SaaS Relay(可降级到本地) / Local Kernel / External Gateway
+- **SaaS 认证**: JWT→OS keyring 存储 + HttpOnly cookie + Token池 RPM/TPM 限流轮换 + SaaS unreachable 自动降级
+- **记忆闭环**: 对话→extraction_adapter→FTS5全文+TF-IDF权重→检索→注入系统提示
+- **LLM 驱动**: 4 Rust Driver (Anthropic/OpenAI/Gemini/Local) + 国内兼容 (DeepSeek/Qwen/Moonshot 通过 base_url)
+
+### 最近变更
+
+1. [04-09] 管家模式6交付物完成: ButlerRouter + 冷启动 + 简洁模式UI + 桥测试 + 发布文档
+2. [04-08] 侧边栏 AnimatePresence bug + TopBar 重复 Z 修复 + 发布评估报告
+3. [04-07] @reserved 标注 5 个 butler Tauri 命令 + 痛点持久化 SQLite
+4. [04-06] 4 个发布前 bug 修复 (身份覆盖/模型配置/agent同步/自动身份)
+
+<!-- ARCH-SNAPSHOT-END -->
+
+<!-- ANTI-PATTERN-START -->
+<!-- 此区域由 auto-sync 自动更新，请勿手动编辑。更新时间: 2026-04-09 -->
+
+## 14. AI 协作注意事项
+
+### 反模式警告
+
+- ❌ **不要**建议新增 SaaS API 端点 — 已有 130 个，稳定化约束禁止新增
+- ❌ **不要**忽略管家模式 — 已上线且为默认模式，所有聊天经过 ButlerRouter
+- ❌ **不要**假设 Tauri 直连 LLM — 实际通过 SaaS Token 池中转，SaaS unreachable 时降级到本地 Kernel
+- ❌ **不要**建议从零实现已有能力 — 先查 Hand(9个)/Skill(75个)/Pipeline(17模板) 现有库
+- ❌ **不要**在 CLAUDE.md 以外创建项目级配置或规则文件 — 单一入口原则
+
+### 场景化指令
+
+- 当遇到**聊天相关** → 记住有 3 种 ChatStream 实现，先用 `getClient()` 判断当前路由模式
+- 当遇到**认证相关** → 记住 Tauri 模式用 OS keyring 存 JWT，SaaS 模式用 HttpOnly cookie
+- 当遇到**新功能建议** → 先查 [TRUTH.md](docs/TRUTH.md) 确认可用能力清单，避免重复建设
+- 当遇到**记忆/上下文相关** → 记住闭环已接通: FTS5+TF-IDF+embedding，不是空壳
+- 当遇到**管家/Butler** → 管家模式是默认模式，ButlerRouter 在中间件链中做关键词分类+system prompt 增强
+
+<!-- ANTI-PATTERN-END -->
--- 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个) |