8b3e43710b
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
- hands-skills.md: Researcher 搜索能力详细说明 + 数据流 + 修复清单 - feature-map.md: 新增 F-09.5 Agent 搜索链路 (搜索引擎/网页获取/UI处理) - known-issues.md: 搜索 04-22 P1×3 修复记录 (SEARCH-1/2/3) - log.md: 追加 04-22 变更日志
424 lines
15 KiB
Markdown
424 lines
15 KiB
Markdown
---
|
||
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 |
|