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

138
wiki/index.md
View File

@@ -1,6 +1,6 @@
---
title: ZCLAW 项目知识库
updated: 2026-04-21
updated: 2026-04-22
status: active
---
@@ -8,49 +8,36 @@ status: active
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
> **数据来源**: 2026-04-19 代码全量扫描验证，非文档推测。
> **数据来源**: 2026-04-22 代码全量扫描验证，非文档推测。
## 项目画像
| 维度 | 值 |
|------|-----|
| 定位 | 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 代码 | 101,967 行 (80,754 crates + 21,213 src-tauri, 357 .rs文件) | `wc -l` (2026-04-19 验证) |
| Rust 测试 | 987 (640 #[test] + 347 #[tokio::test]) | `grep '#\[test\]'` 含 src-tauri (2026-04-19 验证) |
| Rust 测试通过 | 797 workspace (sqlx 0.8 升级后) | `cargo test --workspace --exclude zclaw-saas` |
| Tauri 命令 | 190 定义 | `grep '#\[.*tauri::command'` (2026-04-16 验证) |
| 前端 invoke 调用 | 104 处 / 91 唯一命令 | `grep invoke( desktop/src/` (2026-04-19 验证) |
| @reserved 标注 | 97 个 (孤儿命令 ~0) | `grep @reserved src-tauri/` (2026-04-19 验证) |
| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` (2026-04-16 验证) |
| SaaS 模块 | 16 个目录 | `ls crates/zclaw-saas/src/*/` (2026-04-19 验证) |
| SKILL 目录 | 75 个 | `ls -d skills/*/` |
| HAND 配置 | 6 TOML + 1 系统内部 (_reminder) = 7 注册 | `ls hands/*.HAND.toml` + kernel registry |
| 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 验证) |
| 指标 | 值 |
|------|-----|
| 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 |
## 用户功能清单
> ZCLAW 能做什么？按用户视角组织，快速定位功能所属模块。
| 类别 | 功能 | 用户入口 | Wiki 详情 |
|------|------|----------|-----------|
| 类别 | 功能 | 入口 | Wiki |
|------|------|------|------|
| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] |
| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] |
| 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] |
@@ -60,32 +47,18 @@ status: active
| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] |
| Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] |
| 安全 | 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 组件 (ChatPanel.tsx)
↓
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 ←────────────────────────────┘
用户输入 → 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 更新 (消息气泡渲染)
```
@@ -94,50 +67,35 @@ UI 更新 (消息气泡渲染)
```
ZCLAW
├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？看这里
├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？
│ └── [[chat]] 聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？
│
├── [[saas]] SaaS平台 — 用户/计费/Admin API 都在这里
│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换
│ ├── 计费 配额实时递增 + Alipay/WeChat
│ └── Admin V2 17页管理后台
│
├── [[butler]] 管家模式 — 用户看到什么？行业怎么配？痛点怎么积？
│
├── [[middleware]] 中间件链 — 请求经过哪些处理？优先级怎么排？
│
├── [[memory]] 记忆管道 — 对话怎么变记忆？怎么检索？怎么注入？
│
├── [[hands-skills]] Hands(7注册) + Skills(75) — Agent能做什么动作？懂什么技能？
│
├── [[pipeline]] Pipeline DSL — 工作流怎么配？DAG怎么跑？有哪些模板？
│
├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流/加密
│
├── [[data-model]] 数据模型 — 42表PostgreSQL + FTS5本地存储
│
├── [[feature-map]] 功能链路映射 — 每个功能从前端到后端的完整路径+测试
│
├── [[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
```
## 核心架构决策（为什么这样设计）
## 症状导航
**Q: 为什么 Tauri 不直连 LLM？**
→ 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。
> 出问题了？按症状查表，先查"先查"列，再查"再查"列。
**Q: 为什么有3种 ChatStream？**
→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。
**Q: 为什么管家模式是默认？**
→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。
**Q: 为什么中间件是14层runtime？**
→ 按优先级分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/日志等)。
**Q: zclaw-growth 的进化引擎做什么？**
→ EvolutionEngine 负责从对话历史中检测行为模式变化，生成进化候选项（如新技能建议、工作流优化），通过 EvolutionMiddleware@78 注入 system prompt。配合 FeedbackCollector、PatternAggregator、QualityGate、SkillGenerator、WorkflowComposer 形成自我改进闭环。
| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
| 流式响应卡住 | [[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` — 如有冲突以代码实际为准