iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(wiki): Phase E+F完成 — index重构+feature-map转索引
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details

Browse Source 
- index.md: 移除架构Q&A(移入模块页)+新增症状导航表 (144→101行)
- feature-map.md: 33链路详细描述→紧凑索引表 (424→60行)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
iven
2026-04-22 21:57:47 +08:00
parent c10e50d58e
commit 7ba7389093
2 changed files with 103 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files

473
wiki/feature-map.md
View File

@@ -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]] |