7ba7389093
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>
102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
---
|
||
title: ZCLAW 项目知识库
|
||
updated: 2026-04-22
|
||
status: active
|
||
---
|
||
|
||
# ZCLAW 项目知识库
|
||
|
||
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。
|
||
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
|
||
> **数据来源**: 2026-04-22 代码全量扫描验证，非文档推测。
|
||
|
||
## 项目画像
|
||
|
||
| 维度 | 值 |
|
||
|------|-----|
|
||
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
|
||
| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs) + React 19 + TypeScript + PostgreSQL |
|
||
| 阶段 | 发布前稳定化，功能冻结中 |
|
||
|
||
## 关键数字（2026-04-22 代码验证）
|
||
|
||
| 指标 | 值 |
|
||
|------|-----|
|
||
| Rust Crates | 10 + src-tauri |
|
||
| Rust 代码 | 101,967 行 (357 .rs文件) |
|
||
| Rust 测试 | 987 定义 / 797 通过 |
|
||
| Tauri 命令 | 190 定义 / 97 @reserved / 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 / 102 组件 / 75 lib / 17 Admin 页面 |
|
||
| Intelligence | 16 .rs 文件 |
|
||
| 质量指标 | 0 cargo warnings / 2 TODO/FIXME / 0 dead_code |
|
||
|
||
## 用户功能清单
|
||
|
||
| 类别 | 功能 | 入口 | Wiki |
|
||
|------|------|------|------|
|
||
| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] |
|
||
| 分身 | 创建/切换/配置 Agent | 侧边栏 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 拦截 |
|
||
|
||
> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准
|