From 36a1c87d87bd8af514edeef8a9b1f0fbaafa4928 Mon Sep 17 00:00:00 2001 From: iven Date: Sat, 11 Apr 2026 00:36:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E9=87=8D=E6=9E=84=E4=B8=BA?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E5=8C=96=E7=9F=A5=E8=AF=86=E5=BA=93=20?= =?UTF-8?q?=E2=80=94=20=E6=8C=89=E6=A8=A1=E5=9D=97=E7=BB=84=E7=BB=87?= =?UTF-8?q?=E8=80=8C=E9=9D=9E=E6=8C=89=E6=96=87=E6=A1=A3=E7=B1=BB=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 问题: 旧 wiki 按文档类型组织（architecture/data-flows/file-map）， 修复 Butler Router 需要读 4 个文件才能拼凑全貌。 且 SaaS Relay 主路径 vs 本地降级的优先级描述不准确。 重构为模块化结构，每个模块页自包含： - 设计思想: 为什么这样设计 - 代码逻辑: 数据流 + 关键代码 - 关联模块: 依赖关系 新增模块页: - routing.md: 客户端路由 (明确 SaaS Relay 是主路径，不是本地模式) - chat.md: 聊天系统 (3种实现 + Token Pool 中转机制) - butler.md: 管家模式 (路由/冷启动/痛点/双模式UI) - memory.md: 记忆管道 (提取→FTS5→检索→注入) - saas.md: SaaS平台 (认证/Token池/计费/Admin) - middleware.md: 中间件链 (14层 + 优先级) - hands-skills.md: Hands(9) + Skills(75) - pipeline.md: Pipeline DSL 删除旧文件: architecture.md, data-flows.md, module-status.md, file-map.md (内容已分布到对应模块页中) 添加 .gitignore 排除 Obsidian 工作区状态文件 --- wiki/.gitignore | 4 + wiki/.obsidian/app.json | 1 + wiki/.obsidian/appearance.json | 1 + wiki/.obsidian/core-plugins.json | 33 +++++++ wiki/architecture.md | 147 ------------------------------ wiki/butler.md | 83 +++++++++++++++++ wiki/chat.md | 92 +++++++++++++++++++ wiki/data-flows.md | 148 ------------------------------ wiki/file-map.md | 149 ------------------------------- wiki/hands-skills.md | 90 +++++++++++++++++++ wiki/index.md | 110 ++++++++--------------- wiki/known-issues.md | 55 +++--------- wiki/memory.md | 106 ++++++++++++++++++++++ wiki/middleware.md | 63 +++++++++++++ wiki/module-status.md | 70 --------------- wiki/pipeline.md | 70 +++++++++++++++ wiki/routing.md | 105 ++++++++++++++++++++++ wiki/saas.md | 139 ++++++++++++++++++++++++++++ 18 files changed, 839 insertions(+), 627 deletions(-) create mode 100644 wiki/.gitignore create mode 100644 wiki/.obsidian/app.json create mode 100644 wiki/.obsidian/appearance.json create mode 100644 wiki/.obsidian/core-plugins.json delete mode 100644 wiki/architecture.md create mode 100644 wiki/butler.md create mode 100644 wiki/chat.md delete mode 100644 wiki/data-flows.md delete mode 100644 wiki/file-map.md create mode 100644 wiki/hands-skills.md create mode 100644 wiki/memory.md create mode 100644 wiki/middleware.md delete mode 100644 wiki/module-status.md create mode 100644 wiki/pipeline.md create mode 100644 wiki/routing.md create mode 100644 wiki/saas.md diff --git a/wiki/.gitignore b/wiki/.gitignore new file mode 100644 index 0000000..2ac4cac --- /dev/null +++ b/wiki/.gitignore @@ -0,0 +1,4 @@ +.obsidian/workspace.json +.obsidian/workspace-mobile.json +.obsidian/plugins/ +.trash/ diff --git a/wiki/.obsidian/app.json b/wiki/.obsidian/app.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/wiki/.obsidian/app.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/wiki/.obsidian/appearance.json b/wiki/.obsidian/appearance.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/wiki/.obsidian/appearance.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/wiki/.obsidian/core-plugins.json b/wiki/.obsidian/core-plugins.json new file mode 100644 index 0000000..639b90d --- /dev/null +++ b/wiki/.obsidian/core-plugins.json @@ -0,0 +1,33 @@ +{ + "file-explorer": true, + "global-search": true, + "switcher": true, + "graph": true, + "backlink": true, + "canvas": true, + "outgoing-link": true, + "tag-pane": true, + "footnotes": false, + "properties": true, + "page-preview": true, + "daily-notes": true, + "templates": true, + "note-composer": true, + "command-palette": true, + "slash-command": false, + "editor-status": true, + "bookmarks": true, + "markdown-importer": false, + "zk-prefixer": false, + "random-note": false, + "outline": true, + "word-count": true, + "slides": false, + "audio-recorder": false, + "workspaces": false, + "file-recovery": true, + "publish": false, + "sync": true, + "bases": true, + "webviewer": false +} \ No newline at end of file diff --git a/wiki/architecture.md b/wiki/architecture.md deleted file mode 100644 index e824fff..0000000 --- a/wiki/architecture.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -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]] diff --git a/wiki/butler.md b/wiki/butler.md new file mode 100644 index 0000000..2dfe699 --- /dev/null +++ b/wiki/butler.md @@ -0,0 +1,83 @@ +--- +title: 管家模式 +updated: 2026-04-11 +status: active +tags: [module, butler, interaction] +--- + +# 管家模式 (Butler Mode) + +> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[memory]] + +## 设计思想 + +**核心问题: 非技术用户（如医院行政）不会写 prompt，需要 AI 主动引导。** + +设计决策: +1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启 +2. **4 域关键词分类** — healthcare / data_report / policy / meeting，自动增强 system prompt +3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议 +4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁 + +## 代码逻辑 + +### 数据流 + +``` +用户消息 + → ButlerRouter 中间件 (middleware/butler_router.rs) + → SemanticSkillRouter TF-IDF 匹配 75 个技能 + → 4 域关键词分类 + → 增强 system prompt (领域专用指令) + → LLM 响应 + → PainAggregator 提取痛点 + → PainStorage (内存 Vec 热缓存 + SQLite 持久层) + → 全局 PAIN_STORAGE 单例 + → SolutionGenerator + → 基于痛点生成解决方案提案 +``` + +### 冷启动 (新用户引导) + +入口: `desktop/src/hooks/use-cold-start.ts` + +``` +idle → (检测新用户) → greeting_sent → waiting_response → completed +``` + +4 个阶段，自动检测用户是否需要引导，发送欢迎消息，等待响应后完成。 + +### UI 双模式 + +| 模式 | Store | 特点 | +|------|-------|------| +| simple (默认) | `uiModeStore.ts` | 纯聊天界面，隐藏高级功能 | +| professional | `uiModeStore.ts` | 完整功能面板 | + +切换文件: `desktop/src/store/uiModeStore.ts` +简洁侧边栏: `desktop/src/components/SimpleSidebar.tsx` +管家面板: `desktop/src/components/ButlerPanel.tsx` (3 区: 洞察/方案/记忆) + +## 关联模块 + +- [[middleware]] — ButlerRouter 是中间件链中的一层 +- [[chat]] — 消息流经过管家路由增强 +- [[memory]] — 痛点存储在 memory 子系统 +- [[hands-skills]] — 语义路由使用 75 个技能的 TF-IDF + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 (4域分类) | +| `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点双写 (内存+SQLite) | +| `crates/zclaw-kernel/src/intelligence/solution_generator.rs` | 方案生成 | +| `desktop/src/hooks/use-cold-start.ts` | 冷启动 4 阶段 | +| `desktop/src/store/uiModeStore.ts` | 双模式切换 | +| `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 | +| `desktop/src/components/ButlerPanel.tsx` | 管家面板 (洞察/方案/记忆) | + +## Tauri 命令 + +6 个 butler 专属命令 (已标注 @reserved): +`butler_get_pain_points`, `butler_get_solutions`, `butler_delegate_task`, 等 diff --git a/wiki/chat.md b/wiki/chat.md new file mode 100644 index 0000000..6e46e68 --- /dev/null +++ b/wiki/chat.md @@ -0,0 +1,92 @@ +--- +title: 聊天系统 +updated: 2026-04-11 +status: active +tags: [module, chat, stream] +--- + +# 聊天系统 + +> 从 [[index]] 导航。关联模块: [[routing]] [[saas]] [[butler]] + +## 设计思想 + +**核心问题: 3 种运行环境需要 3 种 ChatStream 实现。** + +| 环境 | 实现 | 传输 | 为什么 | +|------|------|------|--------| +| 桌面端 (Tauri) | KernelClient | Tauri Event | 内置 Kernel，但 baseUrl 可指向 SaaS relay | +| 桌面端 (Tauri + SaaS) | KernelClient + relay | Tauri Event → SaaS | 主路径: Token Pool 中转 | +| 浏览器端 | SaaSRelayGatewayClient | HTTP SSE | 无 Tauri 运行时 | +| 外部 Gateway | GatewayClient | WebSocket | 独立进程部署 | + +**统一接口**: 3 种实现共享同一套回调: + +```ts +{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError } +``` + +## 代码逻辑 + +### 发送消息流 + +入口: `streamStore.sendMessage(content)` → `streamStore.ts` + +``` +sendMessage(content) + → effectiveSessionKey = conversationStore.sessionKey || uuid() + → effectiveAgentId = resolveGatewayAgentId(currentAgent) + → client.chatStream(content, callbacks, { sessionKey, agentId, chatMode }) + → KernelClient: Tauri invoke('kernel_chat', ...) + → Kernel → loop_runner → LLM Driver + → 如果 baseUrl 指向 SaaS relay → 请求发往 Token Pool → LLM + → 如果 baseUrl 指向 LLM 直连 → 请求直接发往 LLM + → 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/completions → SSE + → GatewayClient: WebSocket send → onmessage + → 5 分钟超时守护 (kernel-chat.ts:76) 防止流挂起 +``` + +### Store 拆分 (4 Store) + +原来 908 行的 ChatStore 已拆分为: + +| Store | 文件 | 职责 | +|-------|------|------| +| streamStore | `store/chat/streamStore.ts` | 流式消息编排、发送、取消 | +| conversationStore | `store/chat/conversationStore.ts` | 会话管理、当前模型 | +| messageStore | `store/chat/messageStore.ts` | 消息持久化 | +| chatStore | `store/chat/chatStore.ts` | 聊天通用状态 | + +### 模型切换 + +``` +UI 选择模型 → conversationStore.currentModel = newModel + → 下次 sendMessage 时，connectionStore 读取 currentModel + → SaaS 模式: relay 白名单验证 → 可用则切换 + → 本地模式: 直接使用用户配置的模型 +``` + +## 关联模块 + +- [[routing]] — 路由决定使用哪种 client +- [[saas]] — Token Pool 提供模型和 API Key +- [[butler]] — ButlerRouter 中间件增强 system prompt +- [[middleware]] — 消息经过 14 层中间件处理 +- [[memory]] — 对话内容可能触发记忆提取 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 | +| `desktop/src/store/chat/conversationStore.ts` | 会话管理 | +| `desktop/src/lib/kernel-chat.ts` | Kernel ChatStream (Tauri) | +| `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream | +| `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) | +| `desktop/src/components/ChatArea.tsx` | 聊天区域 UI | +| `crates/zclaw-runtime/src/loop_runner.rs` | Rust 主聊天循环 | diff --git a/wiki/data-flows.md b/wiki/data-flows.md deleted file mode 100644 index 738e969..0000000 --- a/wiki/data-flows.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -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]] diff --git a/wiki/file-map.md b/wiki/file-map.md deleted file mode 100644 index 0567f9c..0000000 --- a/wiki/file-map.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: 文件地图 -updated: 2026-04-11 -status: active -tags: [files, reference] ---- - -# 文件地图 - -> 从 [[index]] 导航到此处。找什么去哪里。 - -## 项目顶层 - -``` -ZCLAW/ -├── CLAUDE.md → AI 协作规范（唯一入口） -├── wiki/ → 编译后知识库（新会话入口） -├── docs/ → 原始文档（raw 层） -├── skills/ → 75 个 SKILL.md -├── hands/ → HAND.toml 配置 -├── config/ → TOML 配置模板 -├── pipelines/ → 17 个 YAML Pipeline 模板 -├── saas-config.toml → SaaS 后端配置 -├── docker-compose.yml → PostgreSQL 容器 -``` - -## Rust Crates - -``` -crates/ -├── zclaw-types/ → L1 基础类型 (AgentId, Message, Error) -│ └── src/types.rs -│ -├── zclaw-memory/ → L2 存储层 -│ └── src/sqlite.rs, session_manager.rs -│ -├── zclaw-runtime/ → L3 运行时 -│ ├── src/driver/ → 4 LLM Driver (anthropic/openai/gemini/local.rs) -│ ├── src/middleware/ → 14 层中间件 -│ │ ├── butler_router.rs → 管家路由 -│ │ ├── data_masking.rs → 数据脱敏 -│ │ └── trajectory_recorder.rs → 轨迹记录 -│ ├── src/loop_runner.rs → 主聊天循环 -│ └── src/tools/ → 7 个工具 -│ -├── zclaw-kernel/ → L4 核心协调 -│ ├── src/kernel/mod.rs → Kernel 启动序列 -│ ├── src/config.rs → LLM 配置 + Driver 工厂 -│ └── src/intelligence/ → 管家/痛点/方案/人格 -│ ├── pain_storage.rs -│ ├── solution_generator.rs -│ └── personality_detector.rs -│ -├── zclaw-skills/ → 技能系统 -│ └── src/semantic_router.rs → TF-IDF 语义路由 -│ -├── zclaw-hands/ → 自主能力 -│ └── src/ (Browser/Collector/Researcher/...) -│ -├── zclaw-protocols/ → 协议 (MCP + A2A feature-gated) -│ -├── zclaw-pipeline/ → Pipeline DSL -│ └── src/executor.rs → DAG 执行器 -│ -├── zclaw-growth/ → 记忆增长 -│ ├── src/extractor.rs → LLM 记忆提取 -│ ├── src/retriever.rs → 语义检索 -│ ├── src/injector.rs → Prompt 注入 -│ ├── src/experience_store.rs → 经验 CRUD -│ └── src/storage/sqlite.rs → FTS5 + TF-IDF -│ └── src/retrieval/semantic.rs → EmbeddingClient trait -│ -└── zclaw-saas/ → SaaS 后端 (Axum + PostgreSQL) - ├── src/auth/ → 认证 (JWT + Cookie + TOTP) - ├── src/knowledge/ → 知识库 (23 API + pgvector) - ├── src/billing/ → 计费 (Alipay/WeChat) - ├── src/workers/ → 7 后台 Worker - └── migrations/ → SQL 迁移 (34 表) -``` - -## 前端 (desktop/src/) - -``` -desktop/src/ -├── store/ → 18 Zustand Store -│ ├── connectionStore.ts → 客户端路由 (844行, 核心中枢) -│ ├── saasStore.ts → SaaS 认证 -│ ├── uiModeStore.ts → 简洁/专业模式 -│ └── chat/ → 4 Store (stream/conversation/message/chat) -│ ├── streamStore.ts -│ └── conversationStore.ts -│ -├── components/ → ~135 React 组件 -│ ├── ChatArea.tsx → 聊天区域 -│ ├── SimpleSidebar.tsx → 简洁模式侧边栏 -│ └── ButlerPanel.tsx → 管家面板 -│ -├── hooks/ → React Hooks -│ └── use-cold-start.ts → 管家冷启动 -│ -├── lib/ → 通信和工具 -│ ├── gateway-client.ts → WebSocket 客户端 -│ ├── kernel-chat.ts → Tauri 内核聊天 -│ ├── saas-relay-client.ts → SaaS SSE 中继 -│ ├── tauri-gateway.ts → Tauri 原生命令 -│ ├── pipeline-client.ts → Pipeline 客户端 -│ ├── secure-storage.ts → OS keyring 存储 -│ └── webmcp-tools.ts → WebMCP 调试工具 -│ -└── store/index.ts → Store 协调器 + client 注入 -``` - -## Admin V2 (admin-v2/) - -``` -admin-v2/src/ -├── pages/ → 15 页面 (Dashboard/Agents/Knowledge/Billing/...) -├── services/ → SaaS API 调用封装 -└── tests/ → 17 测试文件 (61 tests) -``` - -## 文档 (docs/) - -``` -docs/ -├── TRUTH.md → 数字的唯一真相源 -├── ARCHITECTURE_BRIEF.md → 架构参考 -├── features/ → 功能文档 -│ ├── README.md → 功能索引 -│ ├── AUDIT_TRACKER.md → 审计进度 -│ └── audit-v12/ → V12 模块化审计报告 -├── knowledge-base/ → 技术知识库 -├── superpowers/ -│ ├── specs/ → 设计规格文档 -│ ├── plans/ → 实施计划 -│ └── reports/ → 测试报告 -└── archive/ → 归档文档 (~70+ 文件) -``` - -## Memory (.claude/projects/) - -``` -.claude/projects/g--ZClaw-openfang/memory/ -├── MEMORY.md → memory 索引 -└── 47 个 .md 文件 → 会话间工作记录 -``` - -→ 架构见 [[architecture]] -→ 开发规范见 [[development]] diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md new file mode 100644 index 0000000..238d70c --- /dev/null +++ b/wiki/hands-skills.md @@ -0,0 +1,90 @@ +--- +title: Hands + Skills +updated: 2026-04-11 +status: active +tags: [module, hands, skills] +--- + +# Hands + Skills + +> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] + +## 设计思想 + +**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层)** + +- Hands: 浏览器自动化、数据收集、Twitter 操作等 — **执行动作** +- Skills: 75 个 SKILL.md 文件 — **语义路由匹配**，增强 LLM 的领域知识 +- 触发: 用户请求 → LLM 判断需要执行 → 选择 Hand/Skill → 执行 + +## 代码逻辑 + +### Hands (9 启用 + 2 禁用) + +| Hand | 功能 | 依赖 | 配置 | +|------|------|------|------| +| Browser | 浏览器自动化 | WebDriver | `hands/Browser/HAND.toml` | +| Collector | 数据收集聚合 | — | `hands/Collector/HAND.toml` | +| Researcher | 深度研究 | LLM | `hands/Researcher/HAND.toml` | +| Clip | 视频处理 | FFmpeg | `hands/Clip/HAND.toml` | +| Twitter | Twitter 自动化 | OAuth 1.0a | `hands/Twitter/HAND.toml` | +| Whiteboard | 白板演示 | — | `hands/Whiteboard/HAND.toml` | +| Slideshow | 幻灯片生成 | — | `hands/Slideshow/HAND.toml` | +| Speech | 语音合成 | Browser TTS | `hands/Speech/HAND.toml` | +| Quiz | 测验生成 | — | `hands/Quiz/HAND.toml` | +| Predictor | 预测分析 | **禁用** | 无 TOML/无 Rust 实现 | +| Lead | 销售线索 | **禁用** | 无 TOML/无 Rust 实现 | + +### 触发流 + +``` +UI 触发 → handStore.trigger(handName, params) + → Tauri invoke('hand_trigger', { handName, params }) + → Kernel → Hand 执行 + → needs_approval? → 等待 approvalStore 确认 + → 执行结果 → Tauri Event emit + → handStore 更新状态 + 记录日志 +``` + +### Skills (75 个) + +``` +skills/ +├── SKILL_001_数据分析.md +├── SKILL_002_报告生成.md +├── ... (75 个 SKILL.md 文件) +``` + +每个 SKILL.md 定义: +- 技能名称和描述 +- 触发条件 +- 执行步骤 +- 输入/输出格式 + +### 语义路由 + +`crates/zclaw-skills/src/semantic_router.rs` + +``` +用户消息 → SemanticSkillRouter + → TF-IDF 计算消息与 75 个技能的相似度 + → 返回最匹配的技能 + → ButlerRouter 使用此结果增强 system prompt +``` + +## 关联模块 + +- [[chat]] — 消息流中可能触发 Hand/Skill +- [[butler]] — ButlerRouter 使用语义路由匹配技能 +- [[middleware]] — 技能注入通过中间件实现 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-hands/src/` | 9 个 Hand 实现 | +| `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 | +| `skills/*.md` | 75 个技能定义 | +| `hands/*/HAND.toml` | Hand 配置 | +| `desktop/src/store/handStore.ts` | 前端 Hand 状态 | +| `desktop/src/store/approvalStore.ts` | 审批状态 | diff --git a/wiki/index.md b/wiki/index.md index c4f81f1..5067777 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -7,90 +7,56 @@ status: active # ZCLAW 项目知识库 > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。 +> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。 -## 一句话画像 +## 项目画像 -Rust 10 crates (~66K行) + React 19 + Tauri 2.x + PostgreSQL + Axum。发布前稳定化阶段，功能冻结中。 +| 维度 | 值 | +|------|-----| +| 定位 | AI Agent 桌面客户端 (Tauri 2.x) | +| 技术栈 | Rust 10 crates (~66K行) + React 19 + TypeScript + PostgreSQL | +| 阶段 | 发布前稳定化，功能冻结中 | ## 关键数字 -| 维度 | 数量 | -|------|------| -| Rust Crates | 10 | -| Rust 代码 | ~66,000 行 | -| Rust 测试 | 822 (684 workspace + 138 SaaS) | -| Tauri 命令 | 182 (92 有前端调用, 20 @reserved, 70 孤儿) | -| SaaS API | 140 端点 | -| SaaS 数据表 | 34 | -| Zustand Store | 18 | -| React 组件 | ~135 | -| 中间件层 | 14 | -| SKILL.md | 75 | -| Hands | 9 启用 + 2 禁用 | -| Pipeline 模板 | 17 YAML | -| LLM Provider | 8 | +Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17 -## 核心架构 → [[architecture]] - -- **客户端路由**: Admin / SaaS Relay / Local Kernel / External Gateway -- **聊天流**: GatewayClient(WS) / KernelClient(Tauri Event) / SaaSRelay(HTTP SSE) -- **LLM 驱动**: Anthropic / OpenAI / Gemini / Local + 国内 3 家(DeepSeek/Qwen/Moonshot) -- **管家模式**: ButlerRouter 4域分类 + 冷启动 4阶段 + 双模式UI - -## 子系统状态 → [[module-status]] - -| 子系统 | 状态 | 说明 | -|--------|------|------| -| 管家模式 (Butler) | 活跃 | ButlerRouter + 冷启动 + 简洁UI + 痛点持久化 | -| Hermes 管线 | 活跃 | ExperienceStore + UserProfiler + NlScheduleParser + TrajectoryRecorder | -| 聊天流 (ChatStream) | 稳定 | 3 种实现，5min 超时守护 | -| 记忆管道 (Memory) | 稳定 | 对话→提取→FTS5+TF-IDF→检索→注入 | -| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 | -| Pipeline DSL | 稳定 | 17 模板 + DAG 执行器 | -| Hands 系统 | 稳定 | 9 启用 | -| 技能系统 | 稳定 | 75 SKILL.md + 语义路由 | -| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) | - -## 核心数据流 → [[data-flows]] +## 模块导航树 ``` -用户操作 → React UI → Zustand Store → Tauri Commands → Kernel → LLM/Tools/Skills/Hands +ZCLAW +├── [[routing]] 客户端路由 — 4分支决策，SaaS Relay是主路径 +│ └── [[chat]] 聊天系统 — 3种ChatStream，SaaS Token Pool是主路径 +│ +├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢 +│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换 +│ ├── 计费 配额实时递增 + Alipay/WeChat +│ └── Admin V2 15页管理后台 +│ +├── [[butler]] 管家模式 — 默认交互范式，4域路由+冷启动+痛点 +│ +├── [[middleware]] 中间件链 — 14层，DataMasking→ButlerRouter→TrajectoryRecorder +│ +├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入 +│ +├── [[hands-skills]] Hands(9) + Skills(75) — 自主能力+语义技能路由 +│ +├── [[pipeline]] Pipeline DSL — YAML+DAG执行器+17行业模板 +│ +├── [[development]] 开发规范 — 闭环工作法/验证命令/提交规范 +├── [[known-issues]] 已知问题 — P0/P1已修复，P2待处理 +└── [[log]] 变更日志 — append-only ``` -- 4 种 LLM Driver，国内兼容通过 base_url -- SaaS unreachable 时自动降级到本地 Kernel -- 记忆闭环: 对话 → extraction → FTS5+TF-IDF → 检索 → 注入 system prompt +## 核心架构决策（为什么这样设计） -## 开发须知 → [[development]] +**Q: 为什么 Tauri 不直连 LLM？** +→ 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。 -- **闭环工作法**: 定位→修复→验证→提交→文档，每步不可跳过 -- **功能冻结**: 禁止新增 SaaS API / SKILL.md / Tauri 命令 / 中间件 / admin 页面 -- **验证命令**: `cargo check --workspace` / `pnpm tsc --noEmit` / `pnpm vitest run` +**Q: 为什么有3种 ChatStream？** +→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。 -## 已知问题 → [[known-issues]] - -- 所有 P0/P1 已修复 -- 10 项 P2 代码质量问题待处理 -- 70 个 Tauri 命令孤儿（无前端调用且无 @reserved） - -## 文件地图 → [[file-map]] - -关键路径速查，按 `crates/` / `desktop/src/` / `admin-v2/` 组织。 - -## 变更日志 → [[log]] - -Append-only 操作记录。 - ---- - -## 给新会话的快速引导 - -1. 先读本文件 (你正在读) -2. 需要了解架构 → 读 [[architecture]] -3. 需要了解某模块状态 → 读 [[module-status]] -4. 需要了解数据流 → 读 [[data-flows]] -5. 需要开发 → 读 [[development]] -6. 需要知道有哪些 bug → 读 [[known-issues]] -7. 需要找文件 → 读 [[file-map]] +**Q: 为什么管家模式是默认？** +→ 面向医院行政等非技术用户，4域关键词分类+痛点积累+方案生成，降低使用门槛。 > 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准 diff --git a/wiki/known-issues.md b/wiki/known-issues.md index ec17dfa..92012db 100644 --- a/wiki/known-issues.md +++ b/wiki/known-issues.md @@ -7,51 +7,24 @@ tags: [issues, bugs] # 已知问题 -> 从 [[index]] 导航到此处。完整缺陷清单见 `docs/TRUTH.md §3` +> 从 [[index]] 导航。完整清单见 `docs/TRUTH.md §3` -## P0 — 必然崩溃 +## 当前状态 -| ID | 问题 | 状态 | -|----|------|------| -| SEC2-P0-01 | skill_execute 反序列化崩溃 | 已修复 | -| SEC2-P0-02 | TaskTool::default() panic | 已修复 | - -## P1 — 功能失效 - -| ID | 问题 | 状态 | -|----|------|------| -| SEC2-P1-01 | FactStore trait 零实现 | 已修复 | -| SEC2-P1-02 | agent-templates 路径错误 (缺 /api/v1) | 已修复 | -| SEC2-P1-03 | hand-execution-complete 无监听 | 已修复 | -| SEC2-P1-04 | InMemoryStorage RwLock unwrap 级联 | 已修复 | -| SEC2-P1-05~07 | HandRun 持久化静默忽略 (3处) | 已修复 | -| SEC2-P1-08 | FTS 索引更新静默失败 | 已修复 | -| SEC2-P1-09 | Worker dispatch 静默失败 | 已修复 | - -## P1.5 — 代码质量 - -| ID | 问题 | 状态 | -|----|------|------| -| SEC2-P1.5-01 | Capability _ => false 通配符 | 已修复 | -| SEC2-P1.5-02 | billing let _ = ... 冗余 | 已修复 | -| SEC2-P1.5-03 | relay SSE 错误路径 send 失败未记录 | 已修复 | -| SEC2-P1.5-04 | WASM runner 缺少状态注解 | 已修复 | -| SEC2-P1.5-05 | Tauri 命令无连接状态标注 | 已修复 | -| SEC2-P1.5-06 | extract_token_usage 静默丢弃解析错误 | 已修复 | -| SEC2-P1.5-07 | relay current_key_id 防御性 unwrap | 已修复 | - -## P2 — 代码质量（待处理） - -10 项代码质量问题 (SEC2-P2-01~10)，非阻塞性。详见 `docs/TRUTH.md §3.3` +| 级别 | 数量 | 状态 | +|------|------|------| +| P0 (崩溃) | 2 | 全部已修复 | +| P1 (功能失效) | 9 | 全部已修复 | +| P1.5 (代码质量) | 7 | 全部已修复 | +| P2 (代码质量) | 10 | 待处理 | ## 长期观察项 -| 问题 | 说明 | 行动 | +| 问题 | 说明 | 位置 | |------|------|------| -| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | 逐步标注或清理 | -| Embedding 未激活 | EmbeddingClient trait 已写但未调用 | 发布后迭代 | -| SaaS embedding deferred | pgvector 索引就绪，生成未实现 | 发布后迭代 | -| webhook 死代码 | 5 路由定义但未挂载 | 待删除 | +| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | `desktop/src-tauri/src/lib.rs` | +| Embedding 未激活 | EmbeddingClient trait 已写但 NoOp | `zclaw-growth/src/retrieval/semantic.rs` | +| SaaS embedding deferred | pgvector 索引就绪，生成未实现 | `zclaw-saas/src/workers/generate_embedding.rs` | +| webhook 死代码 | 5 路由定义但未挂载 | `zclaw-saas/src/webhook/` | -→ 模块状态见 [[module-status]] -→ 开发规范见 [[development]] +→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]] diff --git a/wiki/memory.md b/wiki/memory.md new file mode 100644 index 0000000..d03366a --- /dev/null +++ b/wiki/memory.md @@ -0,0 +1,106 @@ +--- +title: 记忆管道 +updated: 2026-04-11 +status: active +tags: [module, memory, growth] +--- + +# 记忆管道 (Memory Pipeline) + +> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] + +## 设计思想 + +**核心问题: LLM 无状态，每次对话都从零开始。需要从历史对话中积累知识。** + +设计决策: +1. **闭环架构** — 对话 → 提取 → 索引 → 检索 → 注入，形成正向循环 +2. **FTS5 + TF-IDF** — 轻量级语义搜索，不依赖外部 embedding 服务 +3. **Token 预算控制** — 注入 system prompt 时有 token 上限，防止溢出 +4. **EmbeddingClient trait 已预留** — 接口已写，激活即可升级到向量搜索 + +## 代码逻辑 + +### 闭环数据流 + +``` +[提取] 对话发生 + → MemoryExtractor (crates/zclaw-growth/src/extractor.rs) + → LLM 提取: 偏好 (Preference) / 知识 (Knowledge) / 经验 (Experience) + → MemoryEntry { agent_id, memory_type, content, keywords, importance } + +[索引] 存储 + → SqliteStorage.store() (crates/zclaw-growth/src/storage/sqlite.rs) + → SQLite + FTS5 全文索引 + → TF-IDF 权重计算 + → (可选) EmbeddingClient.embed() → 向量存储 [未激活] + +[检索] 查询时 + → MemoryRetriever.retrieve(query, agent_id) (crates/zclaw-growth/src/retriever.rs) + → QueryAnalyzer: 意图分类 (Preference/Knowledge/Experience/Code/General) + → 中文+英文关键词提取 + CJK 支持 + 同义词扩展 + → SemanticScorer: TF-IDF 匹配 (70% embedding / 30% TF-IDF, embedding 未激活) + → 返回 top-k 相关记忆 + +[注入] 给 LLM + → PromptInjector.inject(system_prompt, memories) (crates/zclaw-growth/src/injector.rs) + → token 预算控制 + → 格式化为结构化上下文块 + → 插入到 system prompt 中 +``` + +### 经验存储 (ExperienceStore) + +Hermes 管线 Chunk1 新增: + +``` +ExperienceStore (crates/zclaw-growth/src/experience_store.rs) + → CRUD 封装: pain → solution → outcome 结构化经验 + → 底层使用 VikingAdapter + → URI scheme: agent://{agent_id}/experience/... +``` + +### 查询意图分类 + +`QueryAnalyzer` 支持 5 种意图: + +| 意图 | 说明 | 检索策略 | +|------|------|----------| +| Preference | 用户偏好 | 精确匹配 preference 类型记忆 | +| Knowledge | 知识查询 | 语义搜索 knowledge 类型 | +| Experience | 经验检索 | 时间+相关性排序 | +| Code | 代码相关 | 关键词优先 | +| General | 通用 | 混合策略 | + +### Embedding 基础设施 (已写未激活) + +``` +EmbeddingClient trait (crates/zclaw-growth/src/retrieval/semantic.rs) + → async embed(&str) -> Vec + → is_available() -> bool + → 当前实现: NoOpEmbeddingClient (始终返回空) + +SaaS 侧: + → pgvector HNSW 索引就绪 (knowledge_chunks 表, vector(1536)) + → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred) +``` + +## 关联模块 + +- [[chat]] — 对话是记忆的输入源 +- [[butler]] — 管家模式可能利用记忆提供个性化响应 +- [[middleware]] — 记忆注入通过中间件或 hook 实现 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-growth/src/extractor.rs` | LLM 记忆提取 | +| `crates/zclaw-growth/src/retriever.rs` | 语义检索 | +| `crates/zclaw-growth/src/injector.rs` | Prompt 注入 (token 预算) | +| `crates/zclaw-growth/src/experience_store.rs` | 经验 CRUD | +| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 | +| `crates/zclaw-growth/src/retrieval/semantic.rs` | EmbeddingClient trait | +| `crates/zclaw-growth/src/retrieval/query.rs` | 意图分类 + CJK 关键词 | +| `desktop/src/store/memoryStore.ts` | 前端记忆 UI | +| `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 | diff --git a/wiki/middleware.md b/wiki/middleware.md new file mode 100644 index 0000000..48b7bc4 --- /dev/null +++ b/wiki/middleware.md @@ -0,0 +1,63 @@ +--- +title: 中间件链 +updated: 2026-04-11 +status: active +tags: [module, middleware, runtime] +--- + +# 中间件链 + +> 从 [[index]] 导航。关联模块: [[chat]] [[butler]] [[memory]] + +## 设计思想 + +**中间件是请求处理的管道，按优先级顺序执行。** + +- 优先级 0-100，数值越大越先执行 +- 每层中间件可以: 修改请求 / 拦截响应 / 记录日志 / 注入上下文 +- 所有消息流（聊天、管家）都经过完整中间件链 + +## 代码逻辑 + +### 14 层中间件 + +关键中间件（按优先级排序）: + +| 优先级 | 中间件 | 文件 | 职责 | +|--------|--------|------|------| +| 90 | DataMasking | `middleware/data_masking.rs` | 请求发送前数据脱敏 (手机号/身份证) | +| ~500 | ButlerRouter | `middleware/butler_router.rs` | 4域关键词分类 + system prompt 增强 | +| 650 | TrajectoryRecorder | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 | + +其他 11 层: 认证、速率限制、日志、技能注入、记忆注入等。 + +### 中间件执行流 + +``` +用户消息 + → [优先级 90] DataMasking — 脱敏敏感数据 + → [优先级 ~500] ButlerRouter — 关键词分类 + prompt 增强 + → [优先级 650] TrajectoryRecorder — 记录请求轨迹 + → [其他层] 认证/限流/日志/技能/记忆 + → LLM 调用 + → 响应原路返回 +``` + +### 注册位置 + +中间件在 `crates/zclaw-runtime/` 中注册，Kernel 启动时加载。 + +## 关联模块 + +- [[butler]] — ButlerRouter 是管家模式的核心 +- [[chat]] — 每条消息经过完整中间件链 +- [[memory]] — 记忆注入层从 FTS5 检索并注入 system prompt + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-runtime/src/middleware/` | 所有中间件实现 | +| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 | +| `crates/zclaw-runtime/src/middleware/data_masking.rs` | 数据脱敏 | +| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录 | diff --git a/wiki/module-status.md b/wiki/module-status.md deleted file mode 100644 index cbc09bb..0000000 --- a/wiki/module-status.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 子系统状态 -updated: 2026-04-11 -status: active -tags: [status, modules] ---- - -# 子系统状态 - -> 从 [[index]] 导航到此处。数字真相源: `docs/TRUTH.md` - -## 活跃子系统 - -| 子系统 | 状态 | 最新变更 | 关键文件 | -|--------|------|----------|----------| -| 管家模式 (Butler) | 活跃 | 04-09 ButlerRouter + 双模式UI + 痛点持久化 + 冷启动 | `middleware/butler_router.rs`, `pain_storage.rs` | -| Hermes 管线 | 活跃 | 04-09 4 Chunk: 自我改进+用户建模+NL Cron+轨迹压缩 | `experience_store.rs`, `user_profiler.rs`, `nl_schedule_parser.rs` | -| 聊天流 (ChatStream) | 稳定 | 04-02 ChatStore 拆分为 4 Store | `streamStore.ts`, `conversationStore.ts` | -| 记忆管道 (Memory) | 稳定 | 04-02 闭环: 对话→提取→FTS5+TF-IDF→检索→注入 | `crates/zclaw-growth/` | -| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 | `saas/auth/handlers.rs` | -| Pipeline DSL | 稳定 | 04-01 17 YAML 模板 + DAG 执行器 | `crates/zclaw-pipeline/` | -| Hands 系统 | 稳定 | 9 启用 (详见下方) | `crates/zclaw-hands/` | -| 技能系统 (Skills) | 稳定 | 75 SKILL.md + 语义路由 | `crates/zclaw-skills/` | -| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) | `crates/zclaw-runtime/src/middleware/` | - -## Hands 详细状态 - -| Hand | 功能 | 状态 | 依赖 | -|------|------|------|------| -| Browser | 浏览器自动化 | 可用 | WebDriver | -| Collector | 数据收集聚合 | 可用 | — | -| Researcher | 深度研究 | 可用 | LLM | -| Clip | 视频处理 | 需 FFmpeg | FFmpeg | -| Twitter | Twitter 自动化 | 可用 | OAuth 1.0a (写操作) | -| Whiteboard | 白板演示 | 可用 | 导出开发中 | -| Slideshow | 幻灯片生成 | 可用 | — | -| Speech | 语音合成 | 可用 | Browser TTS | -| Quiz | 测验生成 | 可用 | — | -| Predictor | 预测分析 | 禁用 | 无 Rust 实现 | -| Lead | 销售线索发现 | 禁用 | 无 Rust 实现 | - -## Tauri 命令分布 - -| 类别 | 数量 | 说明 | -|------|------|------| -| 有前端调用 | 92 | 正常使用中 | -| @reserved | 20 | 已标注保留 | -| 孤儿 | 70 | 无前端调用且无标注 | - -## 测试覆盖 - -| 层级 | 数量 | 状态 | -|------|------|------| -| Rust workspace | 684 | 全通过 | -| SaaS 集成 | 138 | 全通过 (需 PostgreSQL) | -| 前端 vitest | 330 | 330 passed + 1 skipped | -| Admin V2 | 61 | 17 文件 | - -## SaaS API 分布 - -12 个路由模块: account / agent_template / auth / billing / knowledge / migration / model_config / prompt / relay / role / scheduled_task / telemetry - -总计 140 端点 (138 标准 + 2 dev-only) - -## 数据表 (34 个) - -核心表: users, agents, conversations, messages, knowledge_*, billing_*, agent_templates, model_configs, roles, permissions, scheduled_tasks, telemetry - -→ 架构细节见 [[architecture]] -→ 已知问题见 [[known-issues]] diff --git a/wiki/pipeline.md b/wiki/pipeline.md new file mode 100644 index 0000000..7b51977 --- /dev/null +++ b/wiki/pipeline.md @@ -0,0 +1,70 @@ +--- +title: Pipeline DSL +updated: 2026-04-11 +status: active +tags: [module, pipeline, dsl] +--- + +# Pipeline DSL + +> 从 [[index]] 导航。关联模块: [[hands-skills]] + +## 设计思想 + +**Pipeline = 可编排的工作流，按 DAG 依赖顺序执行步骤。** + +- YAML 定义 Pipeline 结构（步骤、依赖、输入/输出） +- DAG 执行器按依赖拓扑排序执行 +- 17 个行业模板覆盖 10 大行业 +- 前端已接通 8 个 Tauri invoke 调用 + +## 代码逻辑 + +### 架构 + +``` +YAML Pipeline 定义 + → PipelineExecutor (crates/zclaw-pipeline/src/executor.rs) + → 构建 DAG (按依赖排序) + → 逐步执行: + → ActionRegistry.resolve(action_type) + → 执行 action → PipelineRun.step_results + → 全部完成 → PipelineRun.status = Completed +``` + +### 运行状态 + +```rust +enum RunStatus { Pending, Running, Completed, Failed, Cancelled } +``` + +### 模板 (17 个 YAML) + +位于 `pipelines/` 目录，覆盖: +- 汕头玩具行业、服装设计、医疗 +- 数据分析、报告生成 +- 教育、营销 +- 等 10 大行业 + +### 前端集成 + +| 组件 | 文件 | +|------|------| +| PipelineClient | `desktop/src/lib/pipeline-client.ts` | +| Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` | + +8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用。 + +## 关联模块 + +- [[hands-skills]] — Pipeline 步骤可能调用 Hand/Skill + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-pipeline/src/executor.rs` | DAG 执行器 | +| `crates/zclaw-pipeline/src/` | Pipeline DSL 解析 | +| `pipelines/` | 17 个 YAML 模板 | +| `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 | +| `desktop/src-tauri/src/pipeline_commands/` | Tauri 命令桥接 | diff --git a/wiki/routing.md b/wiki/routing.md new file mode 100644 index 0000000..f7d8b65 --- /dev/null +++ b/wiki/routing.md @@ -0,0 +1,105 @@ +--- +title: 客户端路由 +updated: 2026-04-11 +status: active +tags: [module, routing, connection] +--- + +# 客户端路由 + +> 从 [[index]] 导航。关联模块: [[chat]] [[saas]] + +## 设计思想 + +**核心决策: Tauri 桌面端通过 SaaS Token Pool 中转访问 LLM，不直连。** + +为什么？ +1. **集中密钥管理** — 用户不需要自己的 API Key，SaaS 维护共享 Key 池 +2. **用量追踪 + 计费** — 每次调用经过 SaaS，`record_usage` worker 记录 token 消耗 +3. **模型白名单** — Admin 配置哪些模型可用，`listModels()` 返回白名单 +4. **降级保障** — SaaS 挂了自动切本地 Kernel，桌面端不变砖 + +## 代码逻辑 + +### 4 分支决策树 + +入口: `connectionStore.ts:349` → `connect(url?, token?)` + +``` +connect() + │ + ├── [1] Admin 强制路由: localStorage llm_routing + │ ├── "relay" → 强制 SaaS Relay 模式 + │ └── "local" → 强制本地 Kernel (adminForceLocal=true) + │ + ├── [2] SaaS Relay 模式: localStorage('zclaw-connection-mode') === 'saas' + │ ├── Tauri: KernelClient + baseUrl = saasUrl/api/v1/relay + │ │ apiKey = SaaS JWT (不是 LLM Key!) + │ ├── Browser: SaaSRelayGatewayClient (SSE) + │ └── SaaS 不可达 → 降级到本地 Kernel + │ + ├── [3] 本地 Kernel: isTauriRuntime() === true + │ KernelClient + 用户自定义模型配置 + │ 用户需要自己的 API Key + │ + └── [4] External Gateway (fallback) + GatewayClient via WebSocket/REST +``` + +### SaaS Relay 主路径 (Tauri 桌面端) + +关键代码: `connectionStore.ts:482-535` + +```ts +kernelClient.setConfig({ + provider: 'custom', + model: modelToUse, // 从 SaaS listModels() 获取 + apiKey: session.token, // SaaS JWT，不是 LLM Key + baseUrl: `${session.saasUrl}/api/v1/relay`, // 指向 SaaS relay + apiProtocol: 'openai', +}); +``` + +**注意**: Kernel 仍然执行 LLM 调用逻辑，但请求发往 SaaS relay 而非直连 LLM。 +SaaS relay 接到请求后，从 Token Pool 中取一个可用 Key，转发给真实 LLM。 + +### SaaS 降级流程 + +关键代码: `connectionStore.ts:446-468` + +``` +listModels() 失败 + → 401 → session 过期 → logout → 要求重新登录 + → 其他错误 → saasDegraded = true + → saasStore.saasReachable = false + → 降级到本地 Kernel 模式 +``` + +### 客户端类型 + +| 客户端 | 传输 | 文件 | 用途 | +|--------|------|------|------| +| GatewayClient | WebSocket + REST | `lib/gateway-client.ts` | 外部 Gateway 进程 | +| KernelClient | Tauri invoke() | `lib/kernel-chat.ts` | 内置 Kernel (桌面端) | +| SaaSRelayGatewayClient | HTTP SSE | `lib/saas-relay-client.ts` | 浏览器端 SaaS 中继 | + +`getClient()` 定义: `connectionStore.ts:844` +所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。 + +## 关联模块 + +- [[chat]] — 路由决定使用哪种 ChatStream +- [[saas]] — Token Pool、认证、模型管理 +- [[middleware]] — 请求经过中间件链处理 +- [[butler]] — 管家模式通过 ButlerRouter 中间件介入 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `desktop/src/store/connectionStore.ts` | 路由决策核心 (844行) | +| `desktop/src/lib/gateway-client.ts` | WebSocket 客户端 | +| `desktop/src/lib/kernel-chat.ts` | Tauri 内核聊天 | +| `desktop/src/lib/saas-relay-client.ts` | SaaS SSE 中继 | +| `desktop/src/lib/saas-client.ts` | SaaS API 客户端 | +| `desktop/src/store/index.ts` | Store 协调器 + client 注入 | diff --git a/wiki/saas.md b/wiki/saas.md new file mode 100644 index 0000000..284ba23 --- /dev/null +++ b/wiki/saas.md @@ -0,0 +1,139 @@ +--- +title: SaaS 平台 +updated: 2026-04-11 +status: active +tags: [module, saas, auth, billing] +--- + +# SaaS 平台 + +> 从 [[index]] 导航。关联模块: [[routing]] [[chat]] + +## 设计思想 + +**核心定位: SaaS 是 Tauri 桌面端的中枢，不是独立 Web 应用。** + +关键决策: +1. **Token Pool** — 桌面端不持有 LLM API Key，SaaS 维护共享 Key 池，RPM/TPM 轮换 +2. **JWT + Cookie 双通道** — Tauri 用 OS keyring 存 JWT，浏览器用 HttpOnly cookie +3. **计费闭环** — 配额实时递增 → 聚合器调度 → mock 支付路由 +4. **Admin V2** — 15 页管理后台，管理模型/用户/计费/知识库 + +## 代码逻辑 + +### 认证流 + +``` +用户登录 (POST /api/v1/auth/login) + → 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) + Secure: dev=false, prod=true | SameSite=Strict + +前端存储: + → Tauri: OS keyring → saasStore.token + → 浏览器: HttpOnly Cookie (JS 不可读) + → localStorage: saasUrl + account 信息 (非敏感) +``` + +### Token 池 + 限流 + +``` +SaaS Relay 收到 LLM 请求 (POST /api/v1/relay/chat/completions) + → 验证 JWT → 提取 user_id + → 从 Token Pool 选择可用 Key (RPM/TPM 轮换) + → 转发请求到真实 LLM API + → 记录 usage (record_usage worker) + → 返回响应 + +限流规则: + → /api/auth/login: 5次/分钟/IP (防暴力) + 持久化到 PostgreSQL + → /api/auth/register: 3次/小时/IP (防刷注册) + → 公共端点: 20次/分钟/IP +``` + +### 密码安全 + +``` +JWT password_version (pwv): + → JWT Claims 含 pwv 字段 + → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv + → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效 + +密码存储: Argon2id + OsRng 随机盐 +TOTP 加密: AES-256-GCM + 随机 Nonce +``` + +### Token 刷新 + +``` +POST /api/v1/auth/refresh + → 验证 refresh_token (单次使用) + → 旧 refresh_token 撤销到 DB (rotation 校验) + → 签发新 access + refresh token +``` + +### SaaS API 分布 + +12 个路由模块，140 端点: + +| 模块 | 端点数 | 说明 | +|------|--------|------| +| auth | ~10 | 登录/注册/刷新/2FA | +| relay | ~5 | 聊天中转/模型列表/任务 | +| billing | 10 | 配额/订阅/支付 | +| knowledge | 23 | 知识库 CRUD + pgvector | +| model_config | ~8 | Provider + 模型管理 | +| account | ~8 | 用户管理 | +| agent_template | ~8 | Agent 模板 | +| role | 11 | 角色 + 权限 | +| telemetry | ~5 | 用量统计 | +| prompt | ~5 | Prompt 模板 | +| scheduled_task | 5 | 定时任务 CRUD | +| migration | ~2 | Schema 迁移 | + +### 数据表 (34 个) + +核心: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version + +### Workers (7 个) + +| Worker | 职责 | +|--------|------| +| log_operation | 操作日志 | +| cleanup_rate_limit | 限流记录清理 | +| cleanup_refresh_tokens | 刷新 token 清理 | +| record_usage | 用量记录 | +| update_last_used | 模型最后使用更新 | +| aggregate_usage | 用量聚合 | +| generate_embedding | 内容分块 (Phase 2 embedding deferred) | + +## 关联模块 + +- [[routing]] — SaaS Relay 是 Tauri 的主路径 +- [[chat]] — 聊天请求经过 SaaS relay 中转 +- [[memory]] — knowledge_chunks 表有 pgvector 索引 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-saas/src/auth/handlers.rs` | 认证端点 | +| `crates/zclaw-saas/src/relay/` | 聊天中转 | +| `crates/zclaw-saas/src/billing/` | 计费 | +| `crates/zclaw-saas/src/knowledge/` | 知识库 (23 API) | +| `crates/zclaw-saas/src/workers/` | 7 个后台 Worker | +| `crates/zclaw-saas/migrations/` | SQL 迁移 (34 表) | +| `admin-v2/src/pages/` | 15 页管理后台 | +| `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 | +| `desktop/src/store/saasStore.ts` | SaaS 认证状态 | + +## 安全 + +完整审计: `docs/features/SECURITY_PENETRATION_TEST_V1.md` +- CORS 白名单 (生产缺失拒绝启动) +- Cookie Secure (dev=false, prod=true) +- JWT 签名密钥 >= 32 字符 (release fallback 拒绝启动) +- 独立 TOTP 加密密钥