---
title: 功能链路映射
updated: 2026-04-21
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-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 |