zclaw_openfang/wiki/index.md

title, updated, status

title	updated	status
ZCLAW 项目知识库	2026-04-24	active

ZCLAW 项目知识库

面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。 使用方式: 找到你要处理的模块，读对应页面，直接开始工作。 数据来源: 2026-04-23 代码全量扫描验证，非文档推测。

项目画像

维度	值
定位	AI Agent 桌面客户端 (Tauri 2.x)
技术栈	Rust 10 crates + src-tauri (~148K行, 384 .rs) + React 19 + TypeScript + PostgreSQL
阶段	发布前稳定化，功能冻结中

关键数字（2026-04-23 代码验证）

指标	值
Rust Crates	10 + src-tauri
Rust 代码	148,185 行 (384 .rs文件)
Rust 测试	997 定义 (619 #[test] + 378 #[tokio::test])
Tauri 命令	193 定义 / 104 invoke
SaaS API	137 .route() / 16 模块 / 38 SQL 迁移 / 42 表
中间件	14 层 runtime + 10 层 SaaS HTTP
SKILL / HAND	75 技能目录 / 7 注册 Hand (6 TOML + _reminder)
Pipeline	18 YAML 模板 (8 目录)
前端	25 Store / 103 组件 / 78 lib / 17 Admin 页面
Intelligence	16 .rs 文件
质量指标	0 cargo warnings / 2 TODO/FIXME / 0 dead_code

用户功能清单

类别	功能	入口	Wiki
对话	发消息、流式响应、多模型切换、LLM 动态建议	聊天面板	chat
分身	创建/切换/配置 Agent、跨会话身份记忆 (soul.md)	侧边栏 Agent 列表	chat
自主	触发 Browser/Collector/Twitter 等	自动化面板	hands-skills
记忆	搜索历史、自动注入上下文、身份信号提取	设置 > 语义记忆	memory
配置	模型/API/工作区/安全存储	设置面板 (19 页)	development
SaaS	登录注册、订阅计费、Admin 管理	SaaS 平台 / Admin 后台	saas
管家	痛点积累、行业配置、简洁/专业模式、跨会话身份、动态建议	聊天面板 (默认模式)	butler
Pipeline	YAML 模板选择、配置、DAG 执行	工作流面板	pipeline
安全	JWT 认证、TOTP 2FA、操作审计	设置 > 安全存储	security
数据	PostgreSQL (42表) + SQLite/FTS5 (本地记忆)	—	data-model

跨模块数据流全景图

请求的完整生命周期（SaaS relay 主路径）。详细流程见 routing 和 chat。

用户输入 → React 组件 → Zustand Store → getClient() 路由决策
  ├── SaaS Relay (主路径): SSE → Token Pool → LLM Provider → 流式返回
  └── 本地 Kernel (降级): Tauri invoke → Runtime → Middleware Chain (14层) → LLM Driver
                                                                      ↓
streamStore.onDelta ← Tauri Event emit ←←←←←←←←←←←←←←←←←←←←←←←←←←←←
  ↓
UI 更新 (消息气泡渲染)

模块导航树

ZCLAW
├── [[routing]]        客户端路由 — 连接断了吗？数据走哪条路？
│   └── [[chat]]       聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？
├── [[saas]]           SaaS平台 — 用户/计费/Admin API
├── [[butler]]         管家模式 — 行业配置、痛点积累、简洁/专业模式
├── [[middleware]]     中间件链 — 请求处理、优先级排序
├── [[memory]]         记忆管道 — 对话→记忆→检索→注入
├── [[hands-skills]]   Hands(7注册) + Skills(75) — 动作与技能
├── [[pipeline]]       Pipeline DSL — 工作流配置、DAG 执行
├── [[security]]       安全体系 — JWT/Cookie/TOTP/CSP/限流
├── [[data-model]]     数据模型 — 42表 PostgreSQL + FTS5 本地
├── [[feature-map]]    功能链路映射 — 前端到后端完整路径+测试
├── [[development]]    开发规范 — 闭环工作法/验证命令/提交规范
├── [[known-issues]]   已知问题 — P0/P1已修复，P2待处理
└── [[log]]            变更日志 — append-only

症状导航

出问题了？按症状查表，先查"先查"列，再查"再查"列。

症状	先查	再查	常见根因
流式响应卡住	routing	chat → middleware	连接断开 / SaaS relay 超时
记忆没有注入	memory	middleware	FTS5 索引空 / 中间件跳过
Hand 触发失败	hands-skills	middleware	工具调用被 Guardrail 拦截
SaaS relay 502	saas	routing	Token Pool 耗尽 / Key 过期
模型切换不生效	routing	chat	SaaS 白名单 vs 本地配置不一致
Agent 创建失败	chat	saas	权限或持久化问题
Pipeline 执行卡住	pipeline	middleware	DAG 循环 / 依赖缺失
Admin 页面 403	saas	security	JWT 过期 / admin_guard 拦截
Agent 名字不记住	butler	memory	soul.md 写入失败 / identity signal 未提取
建议不个性化	chat	butler	4路上下文超时 / ExperienceExtractor 未初始化

数字真相源: docs/TRUTH.md — 如有冲突以代码实际为准