From e790cf171a99a4dc82e32e02354dd7b9f608a985 Mon Sep 17 00:00:00 2001 From: iven Date: Sat, 11 Apr 2026 00:20:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E5=88=9B=E5=BB=BA=20LLM=20Wiki?= =?UTF-8?q?=20=E7=9F=A5=E8=AF=86=E5=BA=93=20=E2=80=94=20=E7=BC=96=E8=AF=91?= =?UTF-8?q?=E5=90=8E=E9=A1=B9=E7=9B=AE=E7=94=BB=E5=83=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 受 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 维护步骤 --- CLAUDE.md | 8 +++ wiki/architecture.md | 147 +++++++++++++++++++++++++++++++++++++++++ wiki/data-flows.md | 148 +++++++++++++++++++++++++++++++++++++++++ wiki/development.md | 115 ++++++++++++++++++++++++++++++++ wiki/file-map.md | 149 ++++++++++++++++++++++++++++++++++++++++++ wiki/index.md | 96 +++++++++++++++++++++++++++ wiki/known-issues.md | 57 ++++++++++++++++ wiki/log.md | 64 ++++++++++++++++++ wiki/module-status.md | 70 ++++++++++++++++++++ 9 files changed, 854 insertions(+) create mode 100644 wiki/architecture.md create mode 100644 wiki/data-flows.md create mode 100644 wiki/development.md create mode 100644 wiki/file-map.md create mode 100644 wiki/index.md create mode 100644 wiki/known-issues.md create mode 100644 wiki/log.md create mode 100644 wiki/module-status.md diff --git a/CLAUDE.md b/CLAUDE.md index 8707db3..0fb2355 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,5 @@ +@wiki/index.md + # ZCLAW 协作与实现规则 > **ZCLAW 是一个独立成熟的 AI Agent 桌面客户端**，专注于提供真实可用的 AI 能力，而不是演示 UI。 @@ -354,6 +356,12 @@ docs/ 3. **docs/ARCHITECTURE_BRIEF.md** — 架构决策或关键组件变更时 4. **docs/features/** — 功能状态变化时 5. **docs/knowledge-base/** — 新的排查经验或配置说明 +6. **wiki/** — 编译后知识库维护（按触发规则更新对应页面）： + - 修复 bug → 更新 `wiki/known-issues.md` + - 架构变更 → 更新 `wiki/architecture.md` + `wiki/data-flows.md` + - 文件结构变化 → 更新 `wiki/file-map.md` + - 模块状态变化 → 更新 `wiki/module-status.md` + - 每次更新 → 在 `wiki/log.md` 追加一条记录 6. **docs/TRUTH.md** — 数字（命令数、Store 数、crates 数等）变化时 #### 步骤 B：提交（按逻辑分组） diff --git a/wiki/architecture.md b/wiki/architecture.md new file mode 100644 index 0000000..e824fff --- /dev/null +++ b/wiki/architecture.md @@ -0,0 +1,147 @@ +--- +title: 系统架构 +updated: 2026-04-11 +status: active +tags: [architecture, core] +--- + +# 系统架构 + +> 从 [[index]] 导航到此处。详细架构参考: `docs/ARCHITECTURE_BRIEF.md` + +## Crate 依赖关系 + +``` +zclaw-types (L1: 基础类型, 无依赖) + ↑ +zclaw-memory (L2: SQLite, KV, 会话) + ↑ +zclaw-runtime (L3: 4 Driver, 7 工具, 14 中间件) + ↑ +zclaw-kernel (L4: 182 Tauri 命令, 核心协调) + ↑ +zclaw-saas (独立: Axum + PostgreSQL, 端口 8080) + ↑ +desktop/src-tauri (集成: kernel + skills + hands + protocols) +``` + +并行 crates (不依赖 runtime): +- `zclaw-skills` — 75 SKILL.md 解析 + 语义路由 +- `zclaw-hands` — 9 自主能力 +- `zclaw-protocols` — MCP 完整 + A2A feature-gated +- `zclaw-pipeline` — Pipeline DSL v1/v2 + DAG 执行器 +- `zclaw-growth` — 记忆增长 (FTS5 + TF-IDF + Embedding trait) + +## 客户端路由 (4 分支) + +``` +getClient() + ├── [1] Admin 路由: localStorage llm_routing → relay/local + ├── [2] SaaS Relay: SaaS不可达→降级到本地 Kernel + ├── [3] Local Kernel: Tauri 内置 (桌面端默认) + └── [4] External Gateway: WebSocket/REST fallback +``` + +关键文件: `desktop/src/store/connectionStore.ts:844` + +## 聊天流 (3 种实现) + +| 实现 | 传输 | 场景 | +|------|------|------| +| GatewayClient | WebSocket | 外部 Gateway 进程 | +| KernelClient | Tauri Event | 内置 Kernel (默认) | +| SaaSRelay | HTTP SSE | 浏览器端 SaaS 中继 | + +统一回调: `{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }` +5 分钟超时守护: `desktop/src/lib/kernel-chat.ts:76` + +## LLM 驱动 (4 + 3) + +### Rust Driver + +| Driver | 文件 | 协议 | +|--------|------|------| +| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages | +| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat | +| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini | +| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama | + +### 国内兼容 (通过 OpenAI 协议 + base_url) + +| Provider | base_url | +|----------|----------| +| DeepSeek | `https://api.deepseek.com` | +| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` | +| Moonshot | `https://api.moonshot.cn/v1` | + +API Key → OS keyring (`secure-storage.ts`) + +## 管家模式 (默认激活) + +``` +用户消息 → ButlerRouter (4域关键词分类) → 增强 system prompt → LLM + ↓ + PainAggregator → PainStorage (内存+SQLite) + ↓ + SolutionGenerator (痛点→方案) +``` + +- 冷启动: idle → greeting_sent → waiting_response → completed +- UI 双模式: simple (纯聊天, 默认) / professional (完整功能) +- ButlerRouter 文件: `crates/zclaw-runtime/src/middleware/butler_router.rs` + +## 记忆管道 (闭环) + +``` +对话 → extraction_adapter (LLM 提取) + → FTS5 全文索引 + TF-IDF 权重 + → 检索 (查询时召回) + → 注入 system prompt (token 预算控制) +``` + +- EmbeddingClient trait 已定义但未激活 +- zclaw-saas 有 pgvector HNSW 索引就绪，embedding 生成 deferred + +## SaaS 认证 + +| 数据 | 存储 | +|------|------| +| JWT Token | OS Keyring | +| 账户信息 | localStorage | +| Cookie | HttpOnly + Secure + SameSite=Strict | + +- JWT password_version: 改密码→所有旧 JWT 失效 +- Token 池: RPM/TPM 限流轮换 +- SaaS unreachable → 自动降级本地 Kernel + +## 中间件链 (14 层) + +关键中间件: +- DataMasking@90 — 请求前数据脱敏 +- ButlerRouter — 4域关键词分类 + system prompt 增强 +- TrajectoryRecorder@650 — 轨迹记录压缩 + +## 关键文件速查 + +### 前端 + +| 文件 | 职责 | +|------|------| +| `desktop/src/store/connectionStore.ts` | 客户端路由 | +| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 | +| `desktop/src/store/chat/conversationStore.ts` | 会话管理 | +| `desktop/src/store/saasStore.ts` | SaaS 认证 | +| `desktop/src/store/uiModeStore.ts` | 简洁/专业模式 | +| `desktop/src/hooks/use-cold-start.ts` | 管家冷启动 | + +### 后端 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动 | +| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 | +| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证 | +| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 | + +→ 数据流细节见 [[data-flows]] +→ 模块状态见 [[module-status]] diff --git a/wiki/data-flows.md b/wiki/data-flows.md new file mode 100644 index 0000000..738e969 --- /dev/null +++ b/wiki/data-flows.md @@ -0,0 +1,148 @@ +--- +title: 核心数据流 +updated: 2026-04-11 +status: active +tags: [data-flow, architecture] +--- + +# 核心数据流 + +> 从 [[index]] 导航到此处。架构细节见 [[architecture]] + +## 主数据流 + +``` +用户操作 → React UI → Zustand Store → Tauri invoke() → zclaw-kernel → LLM/Tools/Skills/Hands +``` + +这是 ZCLAW 最核心的一条数据通路。所有用户交互都经过这条链路。 + +## 聊天消息流 + +``` +用户输入 + → streamStore.sendMessage(content) + → effectiveSessionKey = conversationStore.sessionKey || uuid() + → effectiveAgentId = resolveGatewayAgentId(currentAgent) + → client.chatStream(content, callbacks, options) + → [KernelClient] Tauri invoke('kernel_chat', ...) + → Kernel → loop_runner → LLM Driver + → Tauri Event emit('chat-response-delta', ...) + → onDelta(text) → streamStore 追加 delta + → onTool(tool) → toolStore 更新 + → onHand(hand) → handStore 更新 + → onComplete() → conversationStore 持久化 + → [SaaSRelay] HTTP POST /api/v1/relay/chat → SSE stream + → [GatewayClient] WebSocket send → onmessage 回调 + → 5 分钟超时守护 (kernel-chat.ts:76) +``` + +## 客户端路由决策流 + +``` +connectionStore.connect(url?, token?) + │ + ├── Admin 模式? → localStorage('zclaw-saas-account').llm_routing + │ ├── "relay" → SaaS Relay + │ └── "local" → Kernel (adminForcedLocal=true) + │ + ├── SaaS 模式? → localStorage('zclaw-connection-mode') === 'saas' + │ → health check SaaS + │ ├── 可达 → Tauri: KernelClient + SaaS baseUrl + │ │ Browser: SaaSRelayGatewayClient (SSE) + │ └── 不可达 → 降级到本地 Kernel + │ + ├── Tauri 桌面? → isTauriRuntime() === true + │ → KernelClient + 自定义模型配置 + │ + └── Fallback → GatewayClient via WebSocket/REST +``` + +## 记忆管道流 + +``` +对话发生 + → extraction_adapter (LLM 提取: 偏好/知识/经验) + → MemoryEntry { agent_id, memory_type, content, keywords } + → SqliteStorage.store() + → FTS5 全文索引 + TF-IDF 权重计算 + → (可选) EmbeddingClient.embed() → 向量存储 [未激活] + +查询时: + → MemoryRetriever.retrieve(query, agent_id) + → QueryAnalyzer: 意图分类 + 关键词提取 + 同义词扩展 (CJK) + → SemanticScorer: TF-IDF 匹配 + (可选) embedding 相似度 + → 返回 top-k 相关记忆 + +注入时: + → PromptInjector.inject(system_prompt, memories) + → token 预算控制 + → 格式化为结构化上下文块 + → 插入到 system prompt 中 +``` + +## SaaS 认证流 + +``` +用户登录 + → POST /api/v1/auth/login { email, password } + → 验证 (Argon2id + OsRng 盐) + → 签发 JWT (Claims: user_id, role, pwv) + → set_auth_cookies(): + zclaw_access_token (path:/api, 2h TTL, HttpOnly) + zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly) + → 前端: saasStore 存储 → OS keyring 存 JWT + +Token 刷新: + → POST /api/v1/auth/refresh + → 验证 refresh_token (单次使用，旧 token 撤销到 DB) + → 签发新 access + refresh token + +密码修改: + → 更新 password_version (pwv) + → 所有旧 JWT 自动失效 (Claims.pwv != DB.pwv) +``` + +## 管家模式流 + +``` +用户消息 + → ButlerRouter 中间件 + → 关键词 4 域分类: healthcare / data_report / policy / meeting + → 增强 system prompt (领域专用指令) + → LLM 响应 + → PainAggregator 提取痛点 + → PainStorage (内存 Vec 热缓存 + SQLite 持久) + → SolutionGenerator + → 基于痛点生成解决方案提案 + +冷启动: + idle → (检测新用户) → greeting_sent → waiting_response → completed +``` + +## Pipeline 执行流 + +``` +YAML Pipeline 定义 + → PipelineExecutor.load(yaml) + → 构建 DAG (按依赖排序) + → 逐步执行: + → ActionRegistry.resolve(action_type) + → 执行 action → PipelineRun.step_results + → 全部完成 → PipelineRun.status = Completed + → 17 个行业模板在 pipelines/ 目录 +``` + +## Hands 触发流 + +``` +UI 触发 → handStore.trigger(handName, params) + → Tauri invoke('hand_trigger', { handName, params }) + → Kernel → Hand 执行 + → needs_approval? → 等待 approvalStore 确认 + → 执行结果 → Tauri Event emit + → handStore 更新状态 + 记录日志 +``` + +→ 架构组件见 [[architecture]] +→ 模块状态见 [[module-status]] diff --git a/wiki/development.md b/wiki/development.md new file mode 100644 index 0000000..f7c561a --- /dev/null +++ b/wiki/development.md @@ -0,0 +1,115 @@ +--- +title: 开发规范 +updated: 2026-04-11 +status: active +tags: [development, conventions] +--- + +# 开发规范 + +> 从 [[index]] 导航到此处。完整规范见 `CLAUDE.md` + +## 闭环工作法（强制） + +每次改动必须按顺序完成，不允许跳过： + +1. **定位问题** — 理解根因，不盲目堆补丁 +2. **最小修复** — 只改必要的代码 +3. **自动验证** — `tsc --noEmit` / `cargo check` / `vitest run` 必须通过 +4. **提交推送** — 按 §11 规范提交，**立即 `git push`** +5. **文档同步** — 检查 TRUTH.md / wiki / CLAUDE.md 是否需要更新 + +## 稳定化约束（功能冻结） + +| 禁止 | 原因 | +|------|------| +| 新增 SaaS API 端点 | 已有 140 个，前端未全部接通 | +| 新增 SKILL.md | 已有 75 个 | +| 新增 Tauri 命令 | 已有 182 个，70 个孤儿 | +| 新增中间件/Store | 已有 14 层中间件 + 18 个 Store | +| 新增 admin 页面 | 已有 15 页 | + +## 分层职责 + +``` +UI 组件 → 只负责展示和交互 +Store → 负责状态组织和流程编排 +Client → 负责网络通信和协议转换 +``` + +禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过: +- `desktop/src/lib/gateway-client.ts` — 主要通信客户端 +- `desktop/src/lib/tauri-gateway.ts` — Tauri 原生命令 + +## 验证命令 + +```bash +# TypeScript 类型检查 +pnpm tsc --noEmit + +# 前端单元测试 +cd desktop && pnpm vitest run + +# Rust 全量测试（排除 SaaS） +cargo test --workspace --exclude zclaw-saas + +# SaaS 集成测试（需要 PostgreSQL） +export TEST_DATABASE_URL="postgresql://postgres:123123@localhost:5432/zclaw" +cargo test -p zclaw-saas -- --test-threads=1 + +# 启动开发环境 +pnpm start:dev +``` + +## 提交规范 + +``` +(): +``` + +类型: feat / fix / refactor / docs / test / chore / perf / ci + +示例: +- `fix(chat): 修复流式响应中断问题` +- `refactor(store): 统一 Store 数据获取方式` + +## 代码规范 + +**TypeScript:** +- 避免 `any`，优先 `unknown + 类型守卫` +- 外部数据必须做容错解析 +- 不假设 API 响应永远只有一种格式 + +**React:** +- 函数组件 + hooks +- 复杂副作用收敛到 store +- 组件保持"展示层"职责 + +**Rust:** +- 错误处理: 禁止 `let _ =`，改为 `log::warn!` 或更高级别 +- 输入验证: 系统边界必须验证 + +## WebMCP 调试工具 + +优先使用 WebMCP 而非 DevTools MCP（节省 ~67% token）: + +| 工具 | 用途 | +|------|------| +| `get_zclaw_state` | 综合状态概览 | +| `check_connection` | 连接状态 | +| `send_message` | 发送聊天消息 | +| `get_console_errors` | 应用错误日志 | + +前提: Chrome 146+ + `chrome://flags/#enable-webmcp-testing` + +## Wiki 维护（收尾步骤） + +完成工作后，检查 wiki/ 是否需要更新： +- 修复 bug → 更新 [[known-issues]] +- 架构变更 → 更新 [[architecture]] + [[data-flows]] +- 文件结构变化 → 更新 [[file-map]] +- 模块状态变化 → 更新 [[module-status]] +- 每次更新 → 在 [[log]] 追加记录 + +→ 架构见 [[architecture]] +→ 文件位置见 [[file-map]] diff --git a/wiki/file-map.md b/wiki/file-map.md new file mode 100644 index 0000000..0567f9c --- /dev/null +++ b/wiki/file-map.md @@ -0,0 +1,149 @@ +--- +title: 文件地图 +updated: 2026-04-11 +status: active +tags: [files, reference] +--- + +# 文件地图 + +> 从 [[index]] 导航到此处。找什么去哪里。 + +## 项目顶层 + +``` +ZCLAW/ +├── CLAUDE.md → AI 协作规范（唯一入口） +├── wiki/ → 编译后知识库（新会话入口） +├── docs/ → 原始文档（raw 层） +├── skills/ → 75 个 SKILL.md +├── hands/ → HAND.toml 配置 +├── config/ → TOML 配置模板 +├── pipelines/ → 17 个 YAML Pipeline 模板 +├── saas-config.toml → SaaS 后端配置 +├── docker-compose.yml → PostgreSQL 容器 +``` + +## Rust Crates + +``` +crates/ +├── zclaw-types/ → L1 基础类型 (AgentId, Message, Error) +│ └── src/types.rs +│ +├── zclaw-memory/ → L2 存储层 +│ └── src/sqlite.rs, session_manager.rs +│ +├── zclaw-runtime/ → L3 运行时 +│ ├── src/driver/ → 4 LLM Driver (anthropic/openai/gemini/local.rs) +│ ├── src/middleware/ → 14 层中间件 +│ │ ├── butler_router.rs → 管家路由 +│ │ ├── data_masking.rs → 数据脱敏 +│ │ └── trajectory_recorder.rs → 轨迹记录 +│ ├── src/loop_runner.rs → 主聊天循环 +│ └── src/tools/ → 7 个工具 +│ +├── zclaw-kernel/ → L4 核心协调 +│ ├── src/kernel/mod.rs → Kernel 启动序列 +│ ├── src/config.rs → LLM 配置 + Driver 工厂 +│ └── src/intelligence/ → 管家/痛点/方案/人格 +│ ├── pain_storage.rs +│ ├── solution_generator.rs +│ └── personality_detector.rs +│ +├── zclaw-skills/ → 技能系统 +│ └── src/semantic_router.rs → TF-IDF 语义路由 +│ +├── zclaw-hands/ → 自主能力 +│ └── src/ (Browser/Collector/Researcher/...) +│ +├── zclaw-protocols/ → 协议 (MCP + A2A feature-gated) +│ +├── zclaw-pipeline/ → Pipeline DSL +│ └── src/executor.rs → DAG 执行器 +│ +├── zclaw-growth/ → 记忆增长 +│ ├── src/extractor.rs → LLM 记忆提取 +│ ├── src/retriever.rs → 语义检索 +│ ├── src/injector.rs → Prompt 注入 +│ ├── src/experience_store.rs → 经验 CRUD +│ └── src/storage/sqlite.rs → FTS5 + TF-IDF +│ └── src/retrieval/semantic.rs → EmbeddingClient trait +│ +└── zclaw-saas/ → SaaS 后端 (Axum + PostgreSQL) + ├── src/auth/ → 认证 (JWT + Cookie + TOTP) + ├── src/knowledge/ → 知识库 (23 API + pgvector) + ├── src/billing/ → 计费 (Alipay/WeChat) + ├── src/workers/ → 7 后台 Worker + └── migrations/ → SQL 迁移 (34 表) +``` + +## 前端 (desktop/src/) + +``` +desktop/src/ +├── store/ → 18 Zustand Store +│ ├── connectionStore.ts → 客户端路由 (844行, 核心中枢) +│ ├── saasStore.ts → SaaS 认证 +│ ├── uiModeStore.ts → 简洁/专业模式 +│ └── chat/ → 4 Store (stream/conversation/message/chat) +│ ├── streamStore.ts +│ └── conversationStore.ts +│ +├── components/ → ~135 React 组件 +│ ├── ChatArea.tsx → 聊天区域 +│ ├── SimpleSidebar.tsx → 简洁模式侧边栏 +│ └── ButlerPanel.tsx → 管家面板 +│ +├── hooks/ → React Hooks +│ └── use-cold-start.ts → 管家冷启动 +│ +├── lib/ → 通信和工具 +│ ├── gateway-client.ts → WebSocket 客户端 +│ ├── kernel-chat.ts → Tauri 内核聊天 +│ ├── saas-relay-client.ts → SaaS SSE 中继 +│ ├── tauri-gateway.ts → Tauri 原生命令 +│ ├── pipeline-client.ts → Pipeline 客户端 +│ ├── secure-storage.ts → OS keyring 存储 +│ └── webmcp-tools.ts → WebMCP 调试工具 +│ +└── store/index.ts → Store 协调器 + client 注入 +``` + +## Admin V2 (admin-v2/) + +``` +admin-v2/src/ +├── pages/ → 15 页面 (Dashboard/Agents/Knowledge/Billing/...) +├── services/ → SaaS API 调用封装 +└── tests/ → 17 测试文件 (61 tests) +``` + +## 文档 (docs/) + +``` +docs/ +├── TRUTH.md → 数字的唯一真相源 +├── ARCHITECTURE_BRIEF.md → 架构参考 +├── features/ → 功能文档 +│ ├── README.md → 功能索引 +│ ├── AUDIT_TRACKER.md → 审计进度 +│ └── audit-v12/ → V12 模块化审计报告 +├── knowledge-base/ → 技术知识库 +├── superpowers/ +│ ├── specs/ → 设计规格文档 +│ ├── plans/ → 实施计划 +│ └── reports/ → 测试报告 +└── archive/ → 归档文档 (~70+ 文件) +``` + +## Memory (.claude/projects/) + +``` +.claude/projects/g--ZClaw-openfang/memory/ +├── MEMORY.md → memory 索引 +└── 47 个 .md 文件 → 会话间工作记录 +``` + +→ 架构见 [[architecture]] +→ 开发规范见 [[development]] diff --git a/wiki/index.md b/wiki/index.md new file mode 100644 index 0000000..c4f81f1 --- /dev/null +++ b/wiki/index.md @@ -0,0 +1,96 @@ +--- +title: ZCLAW 项目知识库 +updated: 2026-04-11 +status: 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 为准 diff --git a/wiki/known-issues.md b/wiki/known-issues.md new file mode 100644 index 0000000..ec17dfa --- /dev/null +++ b/wiki/known-issues.md @@ -0,0 +1,57 @@ +--- +title: 已知问题 +updated: 2026-04-11 +status: active +tags: [issues, bugs] +--- + +# 已知问题 + +> 从 [[index]] 导航到此处。完整缺陷清单见 `docs/TRUTH.md §3` + +## P0 — 必然崩溃 + +| ID | 问题 | 状态 | +|----|------|------| +| SEC2-P0-01 | skill_execute 反序列化崩溃 | 已修复 | +| SEC2-P0-02 | TaskTool::default() panic | 已修复 | + +## P1 — 功能失效 + +| ID | 问题 | 状态 | +|----|------|------| +| SEC2-P1-01 | FactStore trait 零实现 | 已修复 | +| SEC2-P1-02 | agent-templates 路径错误 (缺 /api/v1) | 已修复 | +| SEC2-P1-03 | hand-execution-complete 无监听 | 已修复 | +| SEC2-P1-04 | InMemoryStorage RwLock unwrap 级联 | 已修复 | +| SEC2-P1-05~07 | HandRun 持久化静默忽略 (3处) | 已修复 | +| SEC2-P1-08 | FTS 索引更新静默失败 | 已修复 | +| SEC2-P1-09 | Worker dispatch 静默失败 | 已修复 | + +## P1.5 — 代码质量 + +| ID | 问题 | 状态 | +|----|------|------| +| SEC2-P1.5-01 | Capability _ => false 通配符 | 已修复 | +| SEC2-P1.5-02 | billing let _ = ... 冗余 | 已修复 | +| SEC2-P1.5-03 | relay SSE 错误路径 send 失败未记录 | 已修复 | +| SEC2-P1.5-04 | WASM runner 缺少状态注解 | 已修复 | +| SEC2-P1.5-05 | Tauri 命令无连接状态标注 | 已修复 | +| SEC2-P1.5-06 | extract_token_usage 静默丢弃解析错误 | 已修复 | +| SEC2-P1.5-07 | relay current_key_id 防御性 unwrap | 已修复 | + +## P2 — 代码质量（待处理） + +10 项代码质量问题 (SEC2-P2-01~10)，非阻塞性。详见 `docs/TRUTH.md §3.3` + +## 长期观察项 + +| 问题 | 说明 | 行动 | +|------|------|------| +| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | 逐步标注或清理 | +| Embedding 未激活 | EmbeddingClient trait 已写但未调用 | 发布后迭代 | +| SaaS embedding deferred | pgvector 索引就绪，生成未实现 | 发布后迭代 | +| webhook 死代码 | 5 路由定义但未挂载 | 待删除 | + +→ 模块状态见 [[module-status]] +→ 开发规范见 [[development]] diff --git a/wiki/log.md b/wiki/log.md new file mode 100644 index 0000000..0dc17d6 --- /dev/null +++ b/wiki/log.md @@ -0,0 +1,64 @@ +--- +title: 变更日志 +updated: 2026-04-11 +status: active +tags: [log, history] +--- + +# 变更日志 + +> Append-only 操作记录。格式: `## [日期] 类型 | 描述` + +## [2026-04-11] init | 创建 wiki 知识库 + +- 从 TRUTH.md / ARCHITECTURE_BRIEF.md / CLAUDE.md 编译 8 个 wiki 页面 +- 创建 index.md 入口 + 7 个主题页 +- CLAUDE.md 添加 @wiki/index.md 引用 + +## [2026-04-10] fix | 发布前修复批次 + +- ButlerRouter 语义路由 — SemanticSkillRouter TF-IDF 替代关键词 +- P1-04 AuthGuard 竞态 — 三态守卫 + cookie 先验证 +- P2-03 限流 — Cross 测试共享 token +- P1-02 浏览器聊天 — Playwright SaaS fixture +- BREAKS.md 全部 P0/P1/P2 已修复 + +## [2026-04-09] feat | Hermes Intelligence Pipeline 4 Chunk + +- Chunk1 ExperienceStore+Extractor (10 tests) +- Chunk2 UserProfileStore+Profiler (14 tests) +- Chunk3 NlScheduleParser (16 tests) +- Chunk4 TrajectoryRecorder+Compressor (18 tests) +- 中间件 13→14 层 (+TrajectoryRecorder@650) +- Schema v2→v4 (user_profiles + trajectory tables) + +## [2026-04-09] feat | 管家模式发布前实施完成 + +- ButlerRouter + 冷启动 + 简洁UI +- 痛点持久化 SQLite +- 桥测试 43 通过 + +## [2026-04-07] feat | 管家能力激活 + +- Tauri 命令 183→189 (+6 butler) +- multi-agent feature 默认启用 +- ButlerPanel UI 3 区 +- DataMaskingMiddleware@90 + +## [2026-04-03] fix | 前端改进 + 数字校准 + +- Pipeline 8 invoke 接通前端 +- Viking 5 孤立 invoke 清理 +- SaaS API 93→131 (新增 knowledge/billing/role) +- scheduled_task Admin V2 完整接入 + +## [2026-04-02] fix | P0/P1 全部修复 + +- 2 P0 崩溃修复 +- 9 P1 功能失效修复 +- 7 P1.5 代码质量修复 +- TRUTH.md 初始创建 + +--- + +> 更新规则: 每次重大变更后追加一条，最新在最上面 diff --git a/wiki/module-status.md b/wiki/module-status.md new file mode 100644 index 0000000..cbc09bb --- /dev/null +++ b/wiki/module-status.md @@ -0,0 +1,70 @@ +--- +title: 子系统状态 +updated: 2026-04-11 +status: active +tags: [status, modules] +--- + +# 子系统状态 + +> 从 [[index]] 导航到此处。数字真相源: `docs/TRUTH.md` + +## 活跃子系统 + +| 子系统 | 状态 | 最新变更 | 关键文件 | +|--------|------|----------|----------| +| 管家模式 (Butler) | 活跃 | 04-09 ButlerRouter + 双模式UI + 痛点持久化 + 冷启动 | `middleware/butler_router.rs`, `pain_storage.rs` | +| Hermes 管线 | 活跃 | 04-09 4 Chunk: 自我改进+用户建模+NL Cron+轨迹压缩 | `experience_store.rs`, `user_profiler.rs`, `nl_schedule_parser.rs` | +| 聊天流 (ChatStream) | 稳定 | 04-02 ChatStore 拆分为 4 Store | `streamStore.ts`, `conversationStore.ts` | +| 记忆管道 (Memory) | 稳定 | 04-02 闭环: 对话→提取→FTS5+TF-IDF→检索→注入 | `crates/zclaw-growth/` | +| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 | `saas/auth/handlers.rs` | +| Pipeline DSL | 稳定 | 04-01 17 YAML 模板 + DAG 执行器 | `crates/zclaw-pipeline/` | +| Hands 系统 | 稳定 | 9 启用 (详见下方) | `crates/zclaw-hands/` | +| 技能系统 (Skills) | 稳定 | 75 SKILL.md + 语义路由 | `crates/zclaw-skills/` | +| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) | `crates/zclaw-runtime/src/middleware/` | + +## Hands 详细状态 + +| Hand | 功能 | 状态 | 依赖 | +|------|------|------|------| +| Browser | 浏览器自动化 | 可用 | WebDriver | +| Collector | 数据收集聚合 | 可用 | — | +| Researcher | 深度研究 | 可用 | LLM | +| Clip | 视频处理 | 需 FFmpeg | FFmpeg | +| Twitter | Twitter 自动化 | 可用 | OAuth 1.0a (写操作) | +| Whiteboard | 白板演示 | 可用 | 导出开发中 | +| Slideshow | 幻灯片生成 | 可用 | — | +| Speech | 语音合成 | 可用 | Browser TTS | +| Quiz | 测验生成 | 可用 | — | +| Predictor | 预测分析 | 禁用 | 无 Rust 实现 | +| Lead | 销售线索发现 | 禁用 | 无 Rust 实现 | + +## Tauri 命令分布 + +| 类别 | 数量 | 说明 | +|------|------|------| +| 有前端调用 | 92 | 正常使用中 | +| @reserved | 20 | 已标注保留 | +| 孤儿 | 70 | 无前端调用且无标注 | + +## 测试覆盖 + +| 层级 | 数量 | 状态 | +|------|------|------| +| Rust workspace | 684 | 全通过 | +| SaaS 集成 | 138 | 全通过 (需 PostgreSQL) | +| 前端 vitest | 330 | 330 passed + 1 skipped | +| Admin V2 | 61 | 17 文件 | + +## SaaS API 分布 + +12 个路由模块: account / agent_template / auth / billing / knowledge / migration / model_config / prompt / relay / role / scheduled_task / telemetry + +总计 140 端点 (138 标准 + 2 dev-only) + +## 数据表 (34 个) + +核心表: users, agents, conversations, messages, knowledge_*, billing_*, agent_templates, model_configs, roles, permissions, scheduled_tasks, telemetry + +→ 架构细节见 [[architecture]] +→ 已知问题见 [[known-issues]]