diff --git a/wiki/feature-map.md b/wiki/feature-map.md index 3ad5566..17ed2f1 100644 --- a/wiki/feature-map.md +++ b/wiki/feature-map.md @@ -1,423 +1,60 @@ --- -title: 功能链路映射 +title: 功能链路索引 updated: 2026-04-22 status: active -tags: [reference, feature-map, testing] --- -# 功能链路映射 - -> 从 [[index]] 导航。每条链路追踪一个功能从前端到后端的完整路径 + 测试覆盖。 -> 排序: 用户流程优先级 — 对话 > Agent > Hands > 记忆 > SaaS > 管家 > Pipeline > 配置 > 安全 - ---- - -## 对话 (5 条) - -### F-01: 发送消息 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天输入框 → streamStore.sendMessage(content) | -| 前端关键文件 | streamStore.ts, conversationStore.ts, kernel-chat.ts | -| 通信层 | getClient() → KernelClient (Tauri) / SaaSRelay (SSE) | -| Tauri 命令 | `agent_chat_stream` → desktop/src-tauri/src/kernel_commands/chat.rs | -| 中间件链 | ButlerRouter@80 → ... → Memory@150 → ... → Guardrail@400 → ... | -| Rust 核心 | kernel → runtime → loop_runner → LLM Driver | -| SaaS API | POST /api/v1/relay/chat/completions | -| 流式返回 | LLM → runtime → Tauri Event (stream:chunk) → streamStore.onDelta → UI | -| 测试文件 | tests/desktop/chatStore.test.ts (11), tests/seam/chat-seam.test.ts (8) | -| 测试状态 | ✅ 19/19 PASS | - -### F-02: 流式响应接收 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天面板实时显示文字流 | -| 前端关键文件 | streamStore.ts (onDelta/onThinkingDelta/onTool/onComplete) | -| 通信层 | Tauri Event emit → streamStore 回调 | -| 流式事件 | Delta / ThinkingDelta / ToolStart / ToolEnd / HandStart / HandEnd / Complete / Error | -| 超时守护 | kernel-chat.ts:76 — 5 分钟超时防挂起 | -| 测试文件 | tests/desktop/chatStore.test.ts (stream correlation via runId) | -| 测试状态 | ✅ PASS | - -### F-03: 模型切换 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天面板模型选择器 | -| 前端关键文件 | conversationStore.ts (currentModel), connectionStore.ts | -| 决策链 | UI 选择 → conversationStore.currentModel = newModel → 下次 sendMessage 生效 | -| SaaS 验证 | relay 白名单精确匹配 model_id (无别名解析) | -| 降级 | SaaS 不可达 → 降级到本地 Kernel + 用户自定义模型 | -| 测试文件 | tests/desktop/chatStore.test.ts | -| 测试状态 | ✅ PASS | - -### F-04: 上下文管理 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 跨会话恢复对话历史 | -| 前端关键文件 | conversationStore.ts (sessionKey), messageStore.ts (IndexedDB) | -| 持久化 | IndexedDB 消息存储 + SQLite sessions/messages | -| Tauri 命令 | kernel_init 时传入 session_id | -| 测试文件 | tests/desktop/chatStore.test.ts (session isolation) | -| 测试状态 | ✅ PASS | - -### F-05: 取消流式 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天面板停止按钮 | -| 前端关键文件 | streamStore.ts → cancelStream() | -| Tauri 命令 | `cancel_stream` → kernel_commands/chat.rs (原子标志位) | -| 机制 | AtomicBool cancel flag → 流式任务检测 → emit Error 事件 | -| 测试状态 | ✅ (chatStore test 覆盖) | - ---- - -## 分身 / Agent (4 条) - -### F-06: 创建 Agent - -| 维度 | 内容 | -|------|------| -| 用户入口 | 侧边栏 → 新建 Agent | -| 前端关键文件 | agentStore.ts | -| Tauri 命令 | `agent_create` → kernel_commands/agent.rs | -| Rust 核心 | kernel → zclaw-memory → SQLite agents 表 | -| 测试文件 | tests/desktop/chatStore.test.ts (agent isolation) | -| 测试状态 | ✅ PASS | - -### F-07: 切换 Agent - -| 维度 | 内容 | -|------|------| -| 用户入口 | 侧边栏 Agent 列表点击切换 | -| 前端关键文件 | agentStore.ts (currentAgent), conversationStore.ts | -| 机制 | 切换 agent_id → 新 session_key → 下次 sendMessage 使用新 Agent | -| 测试状态 | ✅ PASS | - -### F-08: 配置 Agent - -| 维度 | 内容 | -|------|------| -| 用户入口 | Agent 设置面板 (名称/模型/系统提示) | -| 前端关键文件 | agentStore.ts | -| Tauri 命令 | `agent_update` → kernel_commands/agent.rs | -| 存储 | config.toml (本地) / agent_templates 表 (SaaS) | -| 测试状态 | ✅ | - -### F-09: 删除 Agent - -| 维度 | 内容 | -|------|------| -| 用户入口 | Agent 列表 → 删除确认 | -| 前端关键文件 | agentStore.ts | -| Tauri 命令 | `agent_delete` → kernel_commands/agent.rs | -| 级联 | SQLite agents + sessions + messages 级联删除 | -| 测试状态 | ✅ | - ---- - -## 自主能力 / Hands (4 条) - -### F-09.5: Agent 搜索（网络搜索） - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天中输入搜索请求（如"搜索今天的新闻"） | -| 前端关键文件 | ChatArea.tsx (stripToolNarration), StreamingText.tsx (ReactMarkdown) | -| 触发机制 | LLM 判断需要搜索 → ToolUse{hand_researcher} → AgentLoop 执行 | -| Tauri 命令 | 无独立命令，通过 agent_chat_stream → loop_runner → hand_execute | -| Rust 核心 | zclaw-hands/researcher.rs: search_native() → Baidu + Bing CN 并行 | -| 网页获取 | fetch_via_jina() (Jina Reader API) → fetch_direct() (降级) | -| LLM 兼容 | 扁平 input_schema + empty-input 回退（_fallback_query 注入） | -| UI 处理 | hand 消息隐藏 + stripToolNarration 行级过滤 + ReactMarkdown 渲染 | -| 搜索引擎 | Baidu + Bing CN（国内优先）, DuckDuckGo fallback | -| 测试状态 | ✅ E2E 验证通过 (commit 5816f56 + 81005c3) | - -### F-10: 触发 Hand - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天中 LLM 决定调用 Hand / 自动化面板手动触发 | -| 前端关键文件 | handStore.ts, streamStore.ts (onHand 回调) | -| Tauri 命令 | `hand_execute` → kernel_commands/hand.rs → HandRegistry | -| Rust 核心 | zclaw-hands → 具体 Hand 实现 (Browser/Collector/Twitter/Quiz/...) | -| 流式事件 | HandStart / HandEnd (via agent_chat_stream) | -| 测试文件 | crates/zclaw-hands/src/hands/ (117 tests) | -| 测试状态 | ✅ 117/117 PASS | - -### F-11: Hand 审批 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 审批弹窗 (needs_approval 状态) | -| 前端关键文件 | handStore.ts (approval UI) | -| Tauri 命令 | `hand_approve` / `hand_cancel` → kernel_commands/hand.rs | -| 机制 | Hand TOML 配置 needs_approval=true → 执行前暂停等审批 | -| 测试状态 | ✅ | - -### F-12: Hand 结果查看 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天面板中 Hand 结果展示 | -| 前端关键文件 | handStore.ts | -| Tauri 命令 | `hand_run_status` / `hand_run_list` | -| 机制 | Hand 执行完成 → HandEnd 事件 → UI 展示结果 | -| 测试状态 | ✅ | - -### F-13: Browser 自动化 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天中触发浏览器操作 | -| 前端关键文件 | browserHandStore.ts | -| Tauri 命令 | 23 个 browser_* 命令 → desktop/src-tauri/src/browser/commands.rs | -| 依赖 | WebDriver (需要外部 WebDriver 进程) | -| 测试文件 | crates/zclaw-hands/src/hands/browser.rs (11 tests) | -| 测试状态 | ✅ 11/11 PASS | - ---- - -## 记忆 (3 条) - -### F-14: 记忆搜索 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 语义记忆 / 管家面板记忆搜索 | -| 前端关键文件 | memoryGraphStore.ts | -| Tauri 命令 | `memory_search` → memory_commands.rs → FTS5 + TF-IDF | -| Rust 核心 | zclaw-growth → retriever.rs → QueryAnalyzer → SemanticScorer | -| 查询类型 | Preference / Knowledge / Experience / Code / General | -| 测试文件 | crates/zclaw-growth/ (181 tests), zclaw-memory/ (54 tests) | -| 测试状态 | ✅ 235/235 PASS | - -### F-15: 记忆自动注入 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 无感 — 聊天时自动触发 | -| 触发链 | Memory 中间件@150 → 检测对话内容 → 提取记忆 | -| Tauri 命令 | `extract_and_store_memories` → memory/extractor.rs | -| 注入链 | PromptInjector.inject(system_prompt, memories) → token 预算控制 | -| 测试文件 | crates/zclaw-growth/src/injector.rs (9 tests) | -| 测试状态 | ✅ PASS | - -### F-16: 记忆手动管理 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 语义记忆 — 查看/删除/导出/导入 | -| 前端关键文件 | memoryGraphStore.ts | -| Tauri 命令 | `memory_stats` / `memory_export` / `memory_import` / `memory_delete_all` | -| 测试文件 | crates/zclaw-growth/src/storage/sqlite.rs (6 tests) | -| 测试状态 | ✅ PASS | - ---- - -## SaaS (6 条) - -### F-17: 用户注册 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 登录页 > 注册 | -| 前端关键文件 | saasStore (auth.ts) | -| SaaS API | POST /api/v1/auth/register (3次/小时 IP 限流) | -| Rust 核心 | auth/handlers.rs → Argon2id + OsRg 盐 + 邮箱 RFC 5322 校验 | -| 存储 | PostgreSQL accounts 表 | -| 测试文件 | crates/zclaw-saas/tests/auth_test.rs | -| 测试状态 | ✅ PASS | - -### F-18: 用户登录 - -| 维度 | 内容 | -|------|------| -| 用户入口 | SaaS 平台登录页 | -| 前端关键文件 | saasStore (auth.ts) | -| SaaS API | POST /api/v1/auth/login (5次/分钟 IP 限流 + 持久化) | -| 安全机制 | 账户锁定 (5 次失败 → 15 分钟) + JWT pwv 机制 | -| Token 存储 | Tauri: OS keyring / 浏览器: HttpOnly Cookie | -| 测试文件 | crates/zclaw-saas/tests/auth_test.rs, auth_security_test.rs | -| 测试状态 | ✅ PASS | - -### F-19: Token 刷新 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 无感 — access token 过期时自动触发 | -| 前端关键文件 | saasStore (auth.ts) | -| SaaS API | POST /api/v1/auth/refresh | -| 安全机制 | 单次使用 refresh token → 旧 token 撤销到 DB → 签发新对 | -| 测试状态 | ✅ PASS | - -### F-20: 订阅管理 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > SaaS 平台 / Admin 后台 | -| 前端关键文件 | saasStore (billing.ts) | -| SaaS API | GET /billing/subscription, GET /billing/plans | -| 数据表 | billing_plans, billing_subscriptions | -| 测试文件 | crates/zclaw-saas/tests/billing_test.rs | -| 测试状态 | ✅ PASS | - -### F-21: 支付/计费 - -| 维度 | 内容 | -|------|------| -| 用户入口 | SaaS 平台支付页 / Admin 管理计费 | -| 前端关键文件 | saasStore (billing.ts) | -| SaaS API | POST /billing/payments, GET /billing/invoices/:id/pdf | -| 支付渠道 | Alipay + WeChat (mock 路由用于开发) | -| 回调 | POST /billing/callback/:method | -| 实时配额 | billing_usage_quotas 递增 + aggregate_usage Worker | -| 测试文件 | crates/zclaw-saas/tests/billing_test.rs | -| 测试状态 | ✅ PASS | - -### F-22: Admin 后台管理 - -| 维度 | 内容 | -|------|------| -| 用户入口 | Admin V2 后台 (admin-v2/) | -| 前端关键文件 | admin-v2/src/pages/ (17 页面) | -| SaaS API | 118 个路由覆盖 13 个模块 | -| 认证 | Admin HttpOnly Cookie + admin_guard_middleware 权限验证 | -| 测试文件 | admin-v2/tests/pages/ (17 文件) + crates/zclaw-saas/tests/ (17 文件) | -| 测试状态 | ✅ PASS | - ---- - -## 管家 (3 条) - -### F-23: 简洁/专业模式切换 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 聊天面板右上角模式切换 | -| 前端关键文件 | uiModeStore.ts, SimpleSidebar.tsx | -| 机制 | simple 模式隐藏高级功能 / professional 模式展示完整功能 | -| 测试状态 | ✅ | - -### F-24: 行业配置 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 管家面板 > 行业选择 / Admin > 行业配置 | -| 前端关键文件 | industryStore.ts, ButlerPanel.tsx | -| SaaS API | GET /industries, GET /accounts/me/industries, PUT /accounts/:id/industries | -| 内置行业 | 4 个 (医疗/教育/金融/法律) | -| 中间件 | ButlerRouter@80 动态行业关键词匹配 | -| 测试状态 | ✅ 4 行业已验证 | - -### F-25: 痛点积累 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 无感 — 聊天中自动提取 | -| 触发链 | ButlerRouter → pain_aggregator → pain_storage (双写内存+SQLite) | -| Tauri 命令 | `butler_record_pain_point`, `butler_list_pain_points` | -| 方案生成 | 痛点积累到阈值 → `butler_generate_solution` | -| 测试文件 | intelligence/pain_aggregator.rs (9), pain_storage.rs (11), solution_generator.rs (5) | -| 测试状态 | ✅ 25/25 PASS | - ---- - -## Pipeline (3 条) - -### F-26: 选择模板 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 工作流面板 → 模板列表 | -| 前端关键文件 | workflowStore.ts, pipeline-client.ts | -| Tauri 命令 | pipeline discovery 命令 (8 个已接通前端) | -| 模板来源 | pipelines/ 目录 18 个 YAML (8 行业目录) | -| 测试文件 | crates/zclaw-pipeline/src/parser_v2.rs (11 tests) | -| 测试状态 | ✅ 11/11 PASS | - -### F-27: 配置参数 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 工作流面板 → 参数填写 | -| 前端关键文件 | workflowStore.ts | -| Tauri 命令 | pipeline discovery 配置命令 | -| YAML 结构 | 步骤 + 依赖 + 输入/输出定义 | -| 测试文件 | crates/zclaw-pipeline/src/parser.rs (5 tests) | -| 测试状态 | ✅ PASS | - -### F-28: 执行工作流 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 工作流面板 → 执行按钮 | -| Tauri 命令 | `orchestration_execute` (@reserved, 无前端 UI) | -| Rust 核心 | zclaw-pipeline → executor.rs → DAG 拓扑排序 + 并行执行 | -| 测试文件 | crates/zclaw-pipeline/src/executor.rs (2 tests) | -| 测试状态 | ✅ PASS | - ---- - -## 配置 (3 条) - -### F-29: 模型设置 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 模型与 API | -| 前端关键文件 | configStore.ts, settingsStore | -| 机制 | UI → config.toml 写入 → Kernel 热重载 | -| 8 Provider | Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local | -| 测试状态 | ✅ | - -### F-30: 工作区配置 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 工作区 | -| 前端关键文件 | configStore.ts | -| 持久化 | config.toml + environment variable 插值 ${VAR_NAME} | -| 测试状态 | ✅ | - -### F-31: 数据隐私 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 数据与隐私 | -| 前端关键文件 | configStore.ts | -| 功能 | 清除对话历史 / 导出数据 / 记忆管理 | -| Tauri 命令 | `memory_delete_all`, `memory_export` | -| 测试状态 | ✅ | - ---- - -## 安全 (2 条) - -### F-32: JWT 认证 - -| 维度 | 内容 | -|------|------| -| 用户入口 | 登录时自动触发 | -| 前端关键文件 | saasStore (auth.ts) → secure_storage.ts | -| SaaS API | POST /auth/login → JWT 签发 → Cookie 设置 | -| 验证链 | auth_middleware → JWT 解码 → Claims.pwv vs DB.pwv 比对 | -| 存储 | Tauri: OS keyring (DPAPI/Keychain/Secret Service) | -| 刷新 | POST /auth/refresh → 单次使用 rotation | -| 测试文件 | crates/zclaw-saas/tests/auth_test.rs, auth_security_test.rs | -| 测试状态 | ✅ PASS | - -### F-33: TOTP 2FA - -| 维度 | 内容 | -|------|------| -| 用户入口 | 设置 > 安全存储 > 2FA 设置 | -| 前端关键文件 | securityStore.ts | -| SaaS API | POST /auth/totp/setup → QR 码 / verify → 激活 / disable → 禁用 | -| 加密 | TOTP 密钥 AES-256-GCM 加密存储, 独立 ZCLAW_TOTP_ENCRYPTION_KEY | -| 测试文件 | crates/zclaw-saas/src/auth/totp.rs (inline tests) | -| 测试状态 | ✅ PASS | +# 功能链路索引 + +> 每个功能从前端到后端的完整路径。详细实现见各模块页面。 + +## 链路总览 + +| ID | 功能 | 模块 | 链路摘要 | +|----|------|------|----------| +| F-01 | 发送消息 | [[chat]] | ChatPanel → streamStore → getClient() → kernel_chat → loop_runner → LLM | +| F-02 | 流式响应 | [[chat]] | Tauri Event 'chat-response-delta' → streamStore.onDelta → UI | +| F-03 | 模型切换 | [[routing]] | conversationStore.currentModel → connectionStore → SaaS 白名单验证 | +| F-04 | 上下文管理 | [[chat]] | conversationStore → IndexedDB → 跨会话恢复 | +| F-05 | 取消流式 | [[chat]] | cancelStream() → atomic flag → kernel cancel | +| F-06 | 创建 Agent | [[chat]] | agentStore → kernel_agent_create → SQLite | +| F-07 | 切换 Agent | [[chat]] | agentStore.select → conversationStore.sessionKey 重置 | +| F-08 | 配置 Agent | [[chat]] | AgentSettings → kernel_agent_update → TOML/SQLite | +| F-09 | 删除 Agent | [[chat]] | agentStore → kernel_agent_delete → SQLite cleanup | +| F-09.5 | Agent 搜索 | [[hands-skills]] | ResearcherHand → Baidu+Bing CN 并行 → Jina Reader | +| F-10 | 触发 Hand | [[hands-skills]] | LLM tool_call → ToolRegistry → HandExecutor | +| F-11 | Hand 审批 | [[hands-skills]] | needs_approval=true → UI confirm → HandExecutor | +| F-12 | Hand 结果 | [[hands-skills]] | HandEnd event → handStore → UI | +| F-13 | Browser 自动化 | [[hands-skills]] | BrowserHand → chromiumoxide → headless Chrome | +| F-14 | 记忆搜索 | [[memory]] | MemoryPanel → viking_ls → FTS5 fulltext → UI | +| F-15 | 记忆注入 | [[memory]] | Middleware@150 → extraction_adapter → FTS5+TF-IDF → system prompt | +| F-16 | 记忆管理 | [[memory]] | MemoryPanel → viking_delete → FTS5 | +| F-17 | 用户注册 | [[saas]] | RegisterForm → POST /api/auth/register → Argon2id → JWT | +| F-18 | 用户登录 | [[saas]] | LoginForm → POST /api/auth/login → JWT→Cookie→Keyring | +| F-19 | Token 刷新 | [[security]] | HttpOnly cookie → POST /api/auth/refresh → rotate JWT | +| F-20 | 订阅管理 | [[saas]] | BillingPanel → GET /api/subscriptions → SaaS quota | +| F-21 | 支付计费 | [[saas]] | PayButton → POST /api/payments → Alipay/WeChat mock | +| F-22 | Admin 管理 | [[saas]] | Admin V2 → 137 routes → PostgreSQL | +| F-23 | 简洁/专业切换 | [[butler]] | uiModeStore.toggle → ButlerPanel layout switch | +| F-24 | 行业配置 | [[butler]] | industryStore → saas-industry API → ButlerRouter keywords | +| F-25 | 痛点积累 | [[butler]] | Middleware → ExperienceStore → FTS5 → pre_hook injection | +| F-26 | 选择模板 | [[pipeline]] | WorkflowPanel → pipelineStore → YAML parse | +| F-27 | 配置参数 | [[pipeline]] | WorkflowBuilder → DAG config → Tauri invoke | +| F-28 | 执行工作流 | [[pipeline]] | DAG executor → topological sort → parallel execution | +| F-29 | 模型设置 | [[routing]] | Settings → configStore → kernel_set_model | +| F-30 | 工作区配置 | [[routing]] | Settings → configStore → TOML write | +| F-31 | 数据隐私 | [[security]] | Settings → secure_storage → OS keyring | +| F-32 | JWT 认证 | [[security]] | login → JWT Claims(pwv) → Cookie→Keyring | +| F-33 | TOTP 2FA | [[security]] | Settings → TOTP secret → AES-256-GCM → verify | + +## 统计 + +| 模块 | 链路数 | 详见 | +|------|--------|------| +| 对话/Agent | 9 | [[chat]] | +| 自主能力 | 5 | [[hands-skills]] | +| 记忆 | 3 | [[memory]] | +| SaaS | 6 | [[saas]] | +| 管家 | 3 | [[butler]] | +| Pipeline | 3 | [[pipeline]] | +| 配置/安全 | 5 | [[routing]] [[security]] | diff --git a/wiki/index.md b/wiki/index.md index 4daa8cb..cb9d91a 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,6 +1,6 @@ --- title: ZCLAW 项目知识库 -updated: 2026-04-21 +updated: 2026-04-22 status: active --- @@ -8,49 +8,36 @@ status: active > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。 > **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。 -> **数据来源**: 2026-04-19 代码全量扫描验证，非文档推测。 +> **数据来源**: 2026-04-22 代码全量扫描验证，非文档推测。 ## 项目画像 | 维度 | 值 | |------|-----| | 定位 | AI Agent 桌面客户端 (Tauri 2.x) | -| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs文件) + React 19 + TypeScript + PostgreSQL | +| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs) + React 19 + TypeScript + PostgreSQL | | 阶段 | 发布前稳定化，功能冻结中 | -## 关键数字（2026-04-19 代码验证） +## 关键数字（2026-04-22 代码验证） -| 指标 | 值 | 验证方式 | -|------|-----|----------| -| Rust Crates | 10 + src-tauri | `ls crates/zclaw-*/Cargo.toml` | -| Rust 代码 | 101,967 行 (80,754 crates + 21,213 src-tauri, 357 .rs文件) | `wc -l` (2026-04-19 验证) | -| Rust 测试 | 987 (640 #[test] + 347 #[tokio::test]) | `grep '#\[test\]'` 含 src-tauri (2026-04-19 验证) | -| Rust 测试通过 | 797 workspace (sqlx 0.8 升级后) | `cargo test --workspace --exclude zclaw-saas` | -| Tauri 命令 | 190 定义 | `grep '#\[.*tauri::command'` (2026-04-16 验证) | -| 前端 invoke 调用 | 104 处 / 91 唯一命令 | `grep invoke( desktop/src/` (2026-04-19 验证) | -| @reserved 标注 | 97 个 (孤儿命令 ~0) | `grep @reserved src-tauri/` (2026-04-19 验证) | -| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` (2026-04-16 验证) | -| SaaS 模块 | 16 个目录 | `ls crates/zclaw-saas/src/*/` (2026-04-19 验证) | -| SKILL 目录 | 75 个 | `ls -d skills/*/` | -| HAND 配置 | 6 TOML + 1 系统内部 (_reminder) = 7 注册 | `ls hands/*.HAND.toml` + kernel registry | -| Pipeline YAML | 18 个 (8 目录) | `find pipelines/ -name "*.yaml"` (2026-04-19 验证) | -| Zustand Store | 25 个 (.ts, 含子目录 saas/5) | `find desktop/src/store/` (2026-04-19 验证) | -| React 组件 | 102 个 (.tsx/.ts, 11 子目录) | `find desktop/src/components/` (2026-04-19 验证) | -| Admin V2 页面 | 17 个 (.tsx) | `ls admin-v2/src/pages/` (2026-04-19 验证) | -| 中间件 | 14 层 runtime + 10 层 SaaS HTTP | `chain.register` 计数 (2026-04-22 验证) | -| 前端 lib/ | 75 个 .ts (71 顶层 + workflow-builder/3 + __tests__/1) | `find desktop/src/lib/` (2026-04-19 验证) | -| SQL 迁移 | 38 文件 (21 up + 17 down) / 42 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` (2026-04-19 验证) | -| Intelligence | 16 个 .rs 文件 | `ls src-tauri/src/intelligence/` (2026-04-19 验证) | -| Cargo Warnings | 0 (非 SaaS) | `cargo check --workspace --exclude zclaw-saas` | -| TODO/FIXME | 前端 1 + Rust 1 = 2 | `grep TODO/FIXME` (2026-04-19 验证) | -| dead_code | 0 个 | `grep '#\[dead_code\]'` (2026-04-19 验证) | +| 指标 | 值 | +|------|-----| +| Rust Crates | 10 + src-tauri | +| Rust 代码 | 101,967 行 (357 .rs文件) | +| Rust 测试 | 987 定义 / 797 通过 | +| Tauri 命令 | 190 定义 / 97 @reserved / 104 invoke | +| SaaS API | 137 .route() / 16 模块 / 38 SQL 迁移 / 42 表 | +| 中间件 | 14 层 runtime + 10 层 SaaS HTTP | +| SKILL / HAND | 75 技能目录 / 7 注册 Hand (6 TOML + _reminder) | +| Pipeline | 18 YAML 模板 (8 目录) | +| 前端 | 25 Store / 102 组件 / 75 lib / 17 Admin 页面 | +| Intelligence | 16 .rs 文件 | +| 质量指标 | 0 cargo warnings / 2 TODO/FIXME / 0 dead_code | ## 用户功能清单 -> ZCLAW 能做什么？按用户视角组织，快速定位功能所属模块。 - -| 类别 | 功能 | 用户入口 | Wiki 详情 | -|------|------|----------|-----------| +| 类别 | 功能 | 入口 | Wiki | +|------|------|------|------| | 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] | | 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] | | 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] | @@ -60,32 +47,18 @@ status: active | 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] | | Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] | | 安全 | JWT 认证、TOTP 2FA、操作审计 | 设置 > 安全存储 | [[security]] | -| 数据 | PostgreSQL (SaaS 42表) + SQLite/FTS5 (本地记忆) | — | [[data-model]] | +| 数据 | PostgreSQL (42表) + SQLite/FTS5 (本地记忆) | — | [[data-model]] | ## 跨模块数据流全景图 -> 一个请求的完整生命周期（SaaS relay 主路径）。详细流程见 [[routing]] 和 [[chat]]。 +> 请求的完整生命周期（SaaS relay 主路径）。详细流程见 [[routing]] 和 [[chat]]。 ``` -用户输入 - ↓ -React 组件 (ChatPanel.tsx) - ↓ -Zustand Store (chatStore.sendMessage) - ↓ -getClient() 路由决策 ──→ SaaS Relay (主路径) ──→ 本地 Kernel (降级) - ↓ ↓ ↓ -Tauri invoke SSE 连接 直接调用 - ↓ ↓ ↓ -Kernel Runtime SaaS → Token Pool Runtime - ↓ → LLM Provider ↓ -Middleware Chain (15层) ↓ Middleware Chain - ↓ 流式 SSE 返回 ↓ -LLM Driver ←─────────────────┘ LLM Driver - ↓ ↓ -Tauri Event emit Tauri Event emit - ↓ ↓ -streamStore.onDelta ←────────────────────────────┘ +用户输入 → React 组件 → Zustand Store → getClient() 路由决策 + ├── SaaS Relay (主路径): SSE → Token Pool → LLM Provider → 流式返回 + └── 本地 Kernel (降级): Tauri invoke → Runtime → Middleware Chain (14层) → LLM Driver + ↓ +streamStore.onDelta ← Tauri Event emit ←←←←←←←←←←←←←←←←←←←←←←←←←←←← ↓ UI 更新 (消息气泡渲染) ``` @@ -94,50 +67,35 @@ UI 更新 (消息气泡渲染) ``` ZCLAW -├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？看这里 +├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？ │ └── [[chat]] 聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？ -│ -├── [[saas]] SaaS平台 — 用户/计费/Admin API 都在这里 -│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换 -│ ├── 计费 配额实时递增 + Alipay/WeChat -│ └── Admin V2 17页管理后台 -│ -├── [[butler]] 管家模式 — 用户看到什么？行业怎么配？痛点怎么积？ -│ -├── [[middleware]] 中间件链 — 请求经过哪些处理？优先级怎么排？ -│ -├── [[memory]] 记忆管道 — 对话怎么变记忆？怎么检索？怎么注入？ -│ -├── [[hands-skills]] Hands(7注册) + Skills(75) — Agent能做什么动作？懂什么技能？ -│ -├── [[pipeline]] Pipeline DSL — 工作流怎么配？DAG怎么跑？有哪些模板？ -│ -├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流/加密 -│ -├── [[data-model]] 数据模型 — 42表PostgreSQL + FTS5本地存储 -│ -├── [[feature-map]] 功能链路映射 — 每个功能从前端到后端的完整路径+测试 -│ +├── [[saas]] SaaS平台 — 用户/计费/Admin API +├── [[butler]] 管家模式 — 行业配置、痛点积累、简洁/专业模式 +├── [[middleware]] 中间件链 — 请求处理、优先级排序 +├── [[memory]] 记忆管道 — 对话→记忆→检索→注入 +├── [[hands-skills]] Hands(7注册) + Skills(75) — 动作与技能 +├── [[pipeline]] Pipeline DSL — 工作流配置、DAG 执行 +├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流 +├── [[data-model]] 数据模型 — 42表 PostgreSQL + FTS5 本地 +├── [[feature-map]] 功能链路映射 — 前端到后端完整路径+测试 ├── [[development]] 开发规范 — 闭环工作法/验证命令/提交规范 ├── [[known-issues]] 已知问题 — P0/P1已修复，P2待处理 └── [[log]] 变更日志 — append-only ``` -## 核心架构决策（为什么这样设计） +## 症状导航 -**Q: 为什么 Tauri 不直连 LLM？** -→ 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。 +> 出问题了？按症状查表，先查"先查"列，再查"再查"列。 -**Q: 为什么有3种 ChatStream？** -→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。 - -**Q: 为什么管家模式是默认？** -→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。 - -**Q: 为什么中间件是14层runtime？** -→ 按优先级分6类: 78进化(Evolution) → 80-99路由(Butler) → 100-199上下文(Compaction/Memory/Title) → 200-399能力(SkillIndex/DanglingTool/ToolError/ToolOutputGuard) → 400-599安全(Guardrail/LoopGuard/SubagentLimit) → 600-799遥测(TrajectoryRecorder/TokenCalibration)。另有 10 层 SaaS HTTP 中间件 (限流/认证/配额/CORS/日志等)。 - -**Q: zclaw-growth 的进化引擎做什么？** -→ EvolutionEngine 负责从对话历史中检测行为模式变化，生成进化候选项（如新技能建议、工作流优化），通过 EvolutionMiddleware@78 注入 system prompt。配合 FeedbackCollector、PatternAggregator、QualityGate、SkillGenerator、WorkflowComposer 形成自我改进闭环。 +| 症状 | 先查 | 再查 | 常见根因 | +|------|------|------|----------| +| 流式响应卡住 | [[routing]] | [[chat]] → [[middleware]] | 连接断开 / SaaS relay 超时 | +| 记忆没有注入 | [[memory]] | [[middleware]] | FTS5 索引空 / 中间件跳过 | +| Hand 触发失败 | [[hands-skills]] | [[middleware]] | 工具调用被 Guardrail 拦截 | +| SaaS relay 502 | [[saas]] | [[routing]] | Token Pool 耗尽 / Key 过期 | +| 模型切换不生效 | [[routing]] | [[chat]] | SaaS 白名单 vs 本地配置不一致 | +| Agent 创建失败 | [[chat]] | [[saas]] | 权限或持久化问题 | +| Pipeline 执行卡住 | [[pipeline]] | [[middleware]] | DAG 循环 / 依赖缺失 | +| Admin 页面 403 | [[saas]] | [[security]] | JWT 过期 / admin_guard 拦截 | > 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准