iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
e790cf171a99a4dc82e32e02354dd7b9f608a985
zclaw_openfang/wiki/index.md
iven e790cf171a
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
docs(wiki): 创建 LLM Wiki 知识库 — 编译后项目画像 
受 Karpathy LLM Wiki 启发，将分散在 docs/ + memory/ + CLAUDE.md 的项目知识
编译为 8 个结构化 wiki 页面，解决新会话冷启动时上下文浪费问题。

- wiki/index.md: 主索引入口 (~200行)，CLAUDE.md @import 自动加载
- wiki/architecture.md: 系统架构编译 (crate依赖/客户端路由/聊天流/LLM驱动)
- wiki/module-status.md: 9个子系统状态 + Hands详情 + 测试覆盖
- wiki/data-flows.md: 6条核心数据流 (聊天/路由/记忆/认证/管家/Pipeline)
- wiki/development.md: 开发规范 (闭环工作法/验证命令/提交规范)
- wiki/known-issues.md: 缺陷状态 (P0/P1已修复，P2待处理)
- wiki/file-map.md: 代码库文件地图 (crates/desktop/admin-v2/docs)
- wiki/log.md: Append-only 变更日志
- CLAUDE.md: 添加 @wiki/index.md + §8.3 收尾流程增加 wiki 维护步骤
2026-04-11 00:20:17 +08:00

3.3 KiB
Raw Blame History

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

ZCLAW 项目知识库

面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。

一句话画像

Rust 10 crates (~66K行) + React 19 + Tauri 2.x + PostgreSQL + Axum。发布前稳定化阶段，功能冻结中。

关键数字

维度 数量
Rust Crates 10
Rust 代码 ~66,000 行
Rust 测试 822 (684 workspace + 138 SaaS)
Tauri 命令 182 (92 有前端调用, 20 @reserved, 70 孤儿)
SaaS API 140 端点
SaaS 数据表 34
Zustand Store 18
React 组件 ~135
中间件层 14
SKILL.md 75
Hands 9 启用 + 2 禁用
Pipeline 模板 17 YAML
LLM Provider 8

核心架构 → architecture

  • 客户端路由: Admin / SaaS Relay / Local Kernel / External Gateway
  • 聊天流: GatewayClient(WS) / KernelClient(Tauri Event) / SaaSRelay(HTTP SSE)
  • LLM 驱动: Anthropic / OpenAI / Gemini / Local + 国内 3 家(DeepSeek/Qwen/Moonshot)
  • 管家模式: ButlerRouter 4域分类 + 冷启动 4阶段 + 双模式UI

子系统状态 → module-status

子系统 状态 说明
管家模式 (Butler) 活跃 ButlerRouter + 冷启动 + 简洁UI + 痛点持久化
Hermes 管线 活跃 ExperienceStore + UserProfiler + NlScheduleParser + TrajectoryRecorder
聊天流 (ChatStream) 稳定 3 种实现，5min 超时守护
记忆管道 (Memory) 稳定 对话→提取→FTS5+TF-IDF→检索→注入
SaaS 认证 (Auth) 稳定 Token池 RPM/TPM 轮换 + JWT pwv 失效
Pipeline DSL 稳定 17 模板 + DAG 执行器
Hands 系统 稳定 9 启用
技能系统 稳定 75 SKILL.md + 语义路由
中间件链 稳定 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650)

核心数据流 → data-flows

用户操作 → React UI → Zustand Store → Tauri Commands → Kernel → LLM/Tools/Skills/Hands
  • 4 种 LLM Driver，国内兼容通过 base_url
  • SaaS unreachable 时自动降级到本地 Kernel
  • 记忆闭环: 对话 → extraction → FTS5+TF-IDF → 检索 → 注入 system prompt

开发须知 → development

  • 闭环工作法: 定位→修复→验证→提交→文档，每步不可跳过
  • 功能冻结: 禁止新增 SaaS API / SKILL.md / Tauri 命令 / 中间件 / admin 页面
  • 验证命令: cargo check --workspace / pnpm tsc --noEmit / pnpm vitest run

已知问题 → known-issues

  • 所有 P0/P1 已修复
  • 10 项 P2 代码质量问题待处理
  • 70 个 Tauri 命令孤儿（无前端调用且无 @reserved）

文件地图 → file-map

关键路径速查，按 crates/ / desktop/src/ / admin-v2/ 组织。

变更日志 → log

Append-only 操作记录。

给新会话的快速引导

  1. 先读本文件 (你正在读)
  2. 需要了解架构 → 读 architecture
  3. 需要了解某模块状态 → 读 module-status
  4. 需要了解数据流 → 读 data-flows
  5. 需要开发 → 读 development
  6. 需要知道有哪些 bug → 读 known-issues
  7. 需要找文件 → 读 file-map

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