docs(wiki): Phase E+F完成 — index重构+feature-map转索引
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
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
- 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
@@ -1,423 +1,60 @@
|
|||||||
---
|
---
|
||||||
title: 功能链路映射
|
title: 功能链路索引
|
||||||
updated: 2026-04-22
|
updated: 2026-04-22
|
||||||
status: active
|
status: active
|
||||||
tags: [reference, feature-map, testing]
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# 功能链路映射
|
# 功能链路索引
|
||||||
|
|
||||||
> 从 [[index]] 导航。每条链路追踪一个功能从前端到后端的完整路径 + 测试覆盖。
|
> 每个功能从前端到后端的完整路径。详细实现见各模块页面。
|
||||||
> 排序: 用户流程优先级 — 对话 > Agent > Hands > 记忆 > SaaS > 管家 > Pipeline > 配置 > 安全
|
|
||||||
|
## 链路总览
|
||||||
---
|
|
||||||
|
| ID | 功能 | 模块 | 链路摘要 |
|
||||||
## 对话 (5 条)
|
|----|------|------|----------|
|
||||||
|
| F-01 | 发送消息 | [[chat]] | ChatPanel → streamStore → getClient() → kernel_chat → loop_runner → LLM |
|
||||||
### F-01: 发送消息
|
| 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 |
|
||||||
| 用户入口 | 聊天输入框 → streamStore.sendMessage(content) |
|
| F-06 | 创建 Agent | [[chat]] | agentStore → kernel_agent_create → SQLite |
|
||||||
| 前端关键文件 | streamStore.ts, conversationStore.ts, kernel-chat.ts |
|
| F-07 | 切换 Agent | [[chat]] | agentStore.select → conversationStore.sessionKey 重置 |
|
||||||
| 通信层 | getClient() → KernelClient (Tauri) / SaaSRelay (SSE) |
|
| F-08 | 配置 Agent | [[chat]] | AgentSettings → kernel_agent_update → TOML/SQLite |
|
||||||
| Tauri 命令 | `agent_chat_stream` → desktop/src-tauri/src/kernel_commands/chat.rs |
|
| F-09 | 删除 Agent | [[chat]] | agentStore → kernel_agent_delete → SQLite cleanup |
|
||||||
| 中间件链 | ButlerRouter@80 → ... → Memory@150 → ... → Guardrail@400 → ... |
|
| F-09.5 | Agent 搜索 | [[hands-skills]] | ResearcherHand → Baidu+Bing CN 并行 → Jina Reader |
|
||||||
| Rust 核心 | kernel → runtime → loop_runner → LLM Driver |
|
| F-10 | 触发 Hand | [[hands-skills]] | LLM tool_call → ToolRegistry → HandExecutor |
|
||||||
| SaaS API | POST /api/v1/relay/chat/completions |
|
| F-11 | Hand 审批 | [[hands-skills]] | needs_approval=true → UI confirm → HandExecutor |
|
||||||
| 流式返回 | LLM → runtime → Tauri Event (stream:chunk) → streamStore.onDelta → UI |
|
| F-12 | Hand 结果 | [[hands-skills]] | HandEnd event → handStore → UI |
|
||||||
| 测试文件 | tests/desktop/chatStore.test.ts (11), tests/seam/chat-seam.test.ts (8) |
|
| F-13 | Browser 自动化 | [[hands-skills]] | BrowserHand → chromiumoxide → headless Chrome |
|
||||||
| 测试状态 | ✅ 19/19 PASS |
|
| F-14 | 记忆搜索 | [[memory]] | MemoryPanel → viking_ls → FTS5 fulltext → UI |
|
||||||
|
| F-15 | 记忆注入 | [[memory]] | Middleware@150 → extraction_adapter → FTS5+TF-IDF → system prompt |
|
||||||
### F-02: 流式响应接收
|
| 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 |
|
||||||
| 前端关键文件 | streamStore.ts (onDelta/onThinkingDelta/onTool/onComplete) |
|
| F-21 | 支付计费 | [[saas]] | PayButton → POST /api/payments → Alipay/WeChat mock |
|
||||||
| 通信层 | Tauri Event emit → streamStore 回调 |
|
| F-22 | Admin 管理 | [[saas]] | Admin V2 → 137 routes → PostgreSQL |
|
||||||
| 流式事件 | Delta / ThinkingDelta / ToolStart / ToolEnd / HandStart / HandEnd / Complete / Error |
|
| F-23 | 简洁/专业切换 | [[butler]] | uiModeStore.toggle → ButlerPanel layout switch |
|
||||||
| 超时守护 | kernel-chat.ts:76 — 5 分钟超时防挂起 |
|
| F-24 | 行业配置 | [[butler]] | industryStore → saas-industry API → ButlerRouter keywords |
|
||||||
| 测试文件 | tests/desktop/chatStore.test.ts (stream correlation via runId) |
|
| F-25 | 痛点积累 | [[butler]] | Middleware → ExperienceStore → FTS5 → pre_hook injection |
|
||||||
| 测试状态 | ✅ PASS |
|
| F-26 | 选择模板 | [[pipeline]] | WorkflowPanel → pipelineStore → YAML parse |
|
||||||
|
| F-27 | 配置参数 | [[pipeline]] | WorkflowBuilder → DAG config → Tauri invoke |
|
||||||
### F-03: 模型切换
|
| 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 |
|
||||||
| 前端关键文件 | conversationStore.ts (currentModel), connectionStore.ts |
|
| F-33 | TOTP 2FA | [[security]] | Settings → TOTP secret → AES-256-GCM → verify |
|
||||||
| 决策链 | UI 选择 → conversationStore.currentModel = newModel → 下次 sendMessage 生效 |
|
|
||||||
| SaaS 验证 | relay 白名单精确匹配 model_id (无别名解析) |
|
## 统计
|
||||||
| 降级 | SaaS 不可达 → 降级到本地 Kernel + 用户自定义模型 |
|
|
||||||
| 测试文件 | tests/desktop/chatStore.test.ts |
|
| 模块 | 链路数 | 详见 |
|
||||||
| 测试状态 | ✅ PASS |
|
|------|--------|------|
|
||||||
|
| 对话/Agent | 9 | [[chat]] |
|
||||||
### F-04: 上下文管理
|
| 自主能力 | 5 | [[hands-skills]] |
|
||||||
|
| 记忆 | 3 | [[memory]] |
|
||||||
| 维度 | 内容 |
|
| SaaS | 6 | [[saas]] |
|
||||||
|------|------|
|
| 管家 | 3 | [[butler]] |
|
||||||
| 用户入口 | 跨会话恢复对话历史 |
|
| Pipeline | 3 | [[pipeline]] |
|
||||||
| 前端关键文件 | conversationStore.ts (sessionKey), messageStore.ts (IndexedDB) |
|
| 配置/安全 | 5 | [[routing]] [[security]] |
|
||||||
| 持久化 | 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 |
|
|
||||||
|
|||||||
136
wiki/index.md
136
wiki/index.md
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: ZCLAW 项目知识库
|
title: ZCLAW 项目知识库
|
||||||
updated: 2026-04-21
|
updated: 2026-04-22
|
||||||
status: active
|
status: active
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -8,49 +8,36 @@ status: active
|
|||||||
|
|
||||||
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。
|
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。
|
||||||
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
|
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
|
||||||
> **数据来源**: 2026-04-19 代码全量扫描验证，非文档推测。
|
> **数据来源**: 2026-04-22 代码全量扫描验证，非文档推测。
|
||||||
|
|
||||||
## 项目画像
|
## 项目画像
|
||||||
|
|
||||||
| 维度 | 值 |
|
| 维度 | 值 |
|
||||||
|------|-----|
|
|------|-----|
|
||||||
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
|
| 定位 | 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 Crates | 10 + src-tauri |
|
||||||
| Rust 代码 | 101,967 行 (80,754 crates + 21,213 src-tauri, 357 .rs文件) | `wc -l` (2026-04-19 验证) |
|
| Rust 代码 | 101,967 行 (357 .rs文件) |
|
||||||
| Rust 测试 | 987 (640 #[test] + 347 #[tokio::test]) | `grep '#\[test\]'` 含 src-tauri (2026-04-19 验证) |
|
| Rust 测试 | 987 定义 / 797 通过 |
|
||||||
| Rust 测试通过 | 797 workspace (sqlx 0.8 升级后) | `cargo test --workspace --exclude zclaw-saas` |
|
| Tauri 命令 | 190 定义 / 97 @reserved / 104 invoke |
|
||||||
| Tauri 命令 | 190 定义 | `grep '#\[.*tauri::command'` (2026-04-16 验证) |
|
| SaaS API | 137 .route() / 16 模块 / 38 SQL 迁移 / 42 表 |
|
||||||
| 前端 invoke 调用 | 104 处 / 91 唯一命令 | `grep invoke( desktop/src/` (2026-04-19 验证) |
|
| 中间件 | 14 层 runtime + 10 层 SaaS HTTP |
|
||||||
| @reserved 标注 | 97 个 (孤儿命令 ~0) | `grep @reserved src-tauri/` (2026-04-19 验证) |
|
| SKILL / HAND | 75 技能目录 / 7 注册 Hand (6 TOML + _reminder) |
|
||||||
| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` (2026-04-16 验证) |
|
| Pipeline | 18 YAML 模板 (8 目录) |
|
||||||
| SaaS 模块 | 16 个目录 | `ls crates/zclaw-saas/src/*/` (2026-04-19 验证) |
|
| 前端 | 25 Store / 102 组件 / 75 lib / 17 Admin 页面 |
|
||||||
| SKILL 目录 | 75 个 | `ls -d skills/*/` |
|
| Intelligence | 16 .rs 文件 |
|
||||||
| HAND 配置 | 6 TOML + 1 系统内部 (_reminder) = 7 注册 | `ls hands/*.HAND.toml` + kernel registry |
|
| 质量指标 | 0 cargo warnings / 2 TODO/FIXME / 0 dead_code |
|
||||||
| 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 验证) |
|
|
||||||
|
|
||||||
## 用户功能清单
|
## 用户功能清单
|
||||||
|
|
||||||
> ZCLAW 能做什么？按用户视角组织，快速定位功能所属模块。
|
| 类别 | 功能 | 入口 | Wiki |
|
||||||
|
|------|------|------|------|
|
||||||
| 类别 | 功能 | 用户入口 | Wiki 详情 |
|
|
||||||
|------|------|----------|-----------|
|
|
||||||
| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] |
|
| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] |
|
||||||
| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] |
|
| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] |
|
||||||
| 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] |
|
| 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] |
|
||||||
@@ -60,32 +47,18 @@ status: active
|
|||||||
| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] |
|
| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] |
|
||||||
| Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] |
|
| Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] |
|
||||||
| 安全 | JWT 认证、TOTP 2FA、操作审计 | 设置 > 安全存储 | [[security]] |
|
| 安全 | 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 组件 → Zustand Store → getClient() 路由决策
|
||||||
|
├── SaaS Relay (主路径): SSE → Token Pool → LLM Provider → 流式返回
|
||||||
|
└── 本地 Kernel (降级): Tauri invoke → Runtime → Middleware Chain (14层) → LLM Driver
|
||||||
↓
|
↓
|
||||||
React 组件 (ChatPanel.tsx)
|
streamStore.onDelta ← Tauri Event emit ←←←←←←←←←←←←←←←←←←←←←←←←←←←←
|
||||||
↓
|
|
||||||
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 ←────────────────────────────┘
|
|
||||||
↓
|
↓
|
||||||
UI 更新 (消息气泡渲染)
|
UI 更新 (消息气泡渲染)
|
||||||
```
|
```
|
||||||
@@ -94,50 +67,35 @@ UI 更新 (消息气泡渲染)
|
|||||||
|
|
||||||
```
|
```
|
||||||
ZCLAW
|
ZCLAW
|
||||||
├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？看这里
|
├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？
|
||||||
│ └── [[chat]] 聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？
|
│ └── [[chat]] 聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？
|
||||||
│
|
├── [[saas]] SaaS平台 — 用户/计费/Admin API
|
||||||
├── [[saas]] SaaS平台 — 用户/计费/Admin API 都在这里
|
├── [[butler]] 管家模式 — 行业配置、痛点积累、简洁/专业模式
|
||||||
│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换
|
├── [[middleware]] 中间件链 — 请求处理、优先级排序
|
||||||
│ ├── 计费 配额实时递增 + Alipay/WeChat
|
├── [[memory]] 记忆管道 — 对话→记忆→检索→注入
|
||||||
│ └── Admin V2 17页管理后台
|
├── [[hands-skills]] Hands(7注册) + Skills(75) — 动作与技能
|
||||||
│
|
├── [[pipeline]] Pipeline DSL — 工作流配置、DAG 执行
|
||||||
├── [[butler]] 管家模式 — 用户看到什么？行业怎么配？痛点怎么积？
|
├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流
|
||||||
│
|
├── [[data-model]] 数据模型 — 42表 PostgreSQL + FTS5 本地
|
||||||
├── [[middleware]] 中间件链 — 请求经过哪些处理？优先级怎么排？
|
├── [[feature-map]] 功能链路映射 — 前端到后端完整路径+测试
|
||||||
│
|
|
||||||
├── [[memory]] 记忆管道 — 对话怎么变记忆？怎么检索？怎么注入？
|
|
||||||
│
|
|
||||||
├── [[hands-skills]] Hands(7注册) + Skills(75) — Agent能做什么动作？懂什么技能？
|
|
||||||
│
|
|
||||||
├── [[pipeline]] Pipeline DSL — 工作流怎么配？DAG怎么跑？有哪些模板？
|
|
||||||
│
|
|
||||||
├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流/加密
|
|
||||||
│
|
|
||||||
├── [[data-model]] 数据模型 — 42表PostgreSQL + FTS5本地存储
|
|
||||||
│
|
|
||||||
├── [[feature-map]] 功能链路映射 — 每个功能从前端到后端的完整路径+测试
|
|
||||||
│
|
|
||||||
├── [[development]] 开发规范 — 闭环工作法/验证命令/提交规范
|
├── [[development]] 开发规范 — 闭环工作法/验证命令/提交规范
|
||||||
├── [[known-issues]] 已知问题 — P0/P1已修复，P2待处理
|
├── [[known-issues]] 已知问题 — P0/P1已修复，P2待处理
|
||||||
└── [[log]] 变更日志 — append-only
|
└── [[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 实现间接中转。
|
|------|------|------|----------|
|
||||||
|
| 流式响应卡住 | [[routing]] | [[chat]] → [[middleware]] | 连接断开 / SaaS relay 超时 |
|
||||||
**Q: 为什么管家模式是默认？**
|
| 记忆没有注入 | [[memory]] | [[middleware]] | FTS5 索引空 / 中间件跳过 |
|
||||||
→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。
|
| Hand 触发失败 | [[hands-skills]] | [[middleware]] | 工具调用被 Guardrail 拦截 |
|
||||||
|
| SaaS relay 502 | [[saas]] | [[routing]] | Token Pool 耗尽 / Key 过期 |
|
||||||
**Q: 为什么中间件是14层runtime？**
|
| 模型切换不生效 | [[routing]] | [[chat]] | SaaS 白名单 vs 本地配置不一致 |
|
||||||
→ 按优先级分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/日志等)。
|
| Agent 创建失败 | [[chat]] | [[saas]] | 权限或持久化问题 |
|
||||||
|
| Pipeline 执行卡住 | [[pipeline]] | [[middleware]] | DAG 循环 / 依赖缺失 |
|
||||||
**Q: zclaw-growth 的进化引擎做什么？**
|
| Admin 页面 403 | [[saas]] | [[security]] | JWT 过期 / admin_guard 拦截 |
|
||||||
→ EvolutionEngine 负责从对话历史中检测行为模式变化，生成进化候选项（如新技能建议、工作流优化），通过 EvolutionMiddleware@78 注入 system prompt。配合 FeedbackCollector、PatternAggregator、QualityGate、SkillGenerator、WorkflowComposer 形成自我改进闭环。
|
|
||||||
|
|
||||||
> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准
|
> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准
|
||||||
|
|||||||
Reference in New Issue
Block a user