iven/zclaw_openfang

Fork 0

Files

iven ed77095a37

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

docs(wiki): 系统性更新 — L0速览+L1模块标准化+L2功能链路映射(33条)

三层架构增强:
- L0 index.md: 用户功能清单+跨模块数据流全景图+导航树增强 (92→143行)
- L1 8个模块页标准化: 功能清单/API接口/测试链路/已知问题
  routing(252→326) chat(101→157) saas(153→230) memory(182→333)
  butler(137→179) middleware(121→159) hands-skills(218→257) pipeline(111→156)
- L1 新增2页: security.md(157行) data-model.md(180行)
- L2 feature-map.md: 33条端到端功能链路映射(408行)

维护机制: CLAUDE.md §8.3 wiki触发规则 5→9条
设计文档: docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md

2026-04-21 23:48:19 +08:00

14 KiB

Raw Blame History

title, updated, status, tags

title

updated

status

功能链路映射

从 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

14 KiB Raw Blame History

功能链路映射

对话 (5 条)

F-01: 发送消息

F-02: 流式响应接收

F-03: 模型切换

F-04: 上下文管理

F-05: 取消流式

分身 / Agent (4 条)

F-06: 创建 Agent

F-07: 切换 Agent

F-08: 配置 Agent

F-09: 删除 Agent

自主能力 / Hands (4 条)

F-10: 触发 Hand

F-11: Hand 审批

F-12: Hand 结果查看

F-13: Browser 自动化

记忆 (3 条)

F-14: 记忆搜索

F-15: 记忆自动注入

F-16: 记忆手动管理

SaaS (6 条)

F-17: 用户注册

F-18: 用户登录

F-19: Token 刷新

F-20: 订阅管理

F-21: 支付/计费

F-22: Admin 后台管理

管家 (3 条)

F-23: 简洁/专业模式切换

F-24: 行业配置

F-25: 痛点积累

Pipeline (3 条)

F-26: 选择模板

F-27: 配置参数

F-28: 执行工作流

配置 (3 条)

F-29: 模型设置

F-30: 工作区配置

F-31: 数据隐私

安全 (2 条)

F-32: JWT 认证

F-33: TOTP 2FA

14 KiB

Raw Blame History