From f2d6a3b6b7bab280b7810c122892ac5238618427 Mon Sep 17 00:00:00 2001 From: iven Date: Thu, 9 Apr 2026 14:09:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20architecture=20awareness=20system?= =?UTF-8?q?=20=E2=80=94=20CLAUDE.md=20=C2=A713/=C2=A714=20+=20ARCHITECTURE?= =?UTF-8?q?=5FBRIEF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .claude/hooks/arch-sync-check.js | 28 +++ .claude/settings.json | 15 ++ .claude/skills/sync-arch | 52 ++++++ CLAUDE.md | 84 +++++++-- docs/ARCHITECTURE_BRIEF.md | 299 +++++++++++++++++++++++++++++++ 5 files changed, 467 insertions(+), 11 deletions(-) create mode 100644 .claude/hooks/arch-sync-check.js create mode 100644 .claude/settings.json create mode 100644 .claude/skills/sync-arch create mode 100644 docs/ARCHITECTURE_BRIEF.md diff --git a/.claude/hooks/arch-sync-check.js b/.claude/hooks/arch-sync-check.js new file mode 100644 index 0000000..751deb5 --- /dev/null +++ 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 + } +}); diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..75eb15d --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "node .claude/hooks/arch-sync-check.js" + } + ] + } + ] + } +} diff --git a/.claude/skills/sync-arch b/.claude/skills/sync-arch new file mode 100644 index 0000000..64838e6 --- /dev/null +++ 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 `` 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 `` and ``): + - 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 `` + +4. **Update CLAUDE.md §14** (between `` and ``): + - 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 ` + +## 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 diff --git a/CLAUDE.md b/CLAUDE.md index 1e8ec06..6d457fa 100644 --- 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 架构快照** — 涉及子系统变更时，更新 `` 标记区域（可执行 `/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` + +*** + + + + +## 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同步/自动身份) + + + + + + +## 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 增强 + + diff --git a/docs/ARCHITECTURE_BRIEF.md b/docs/ARCHITECTURE_BRIEF.md new file mode 100644 index 0000000..daf50c1 --- /dev/null +++ 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//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个) |