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
parent 4a5389510e
commit e790cf171a
9 changed files with 854 additions and 0 deletions
--- 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：提交（按逻辑分组）
--- a/wiki/architecture.md
+++ 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]]
--- a/wiki/data-flows.md
+++ 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]]
--- a/wiki/development.md
+++ 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
+```
+
+## 提交规范
+
+```
+<type>(<scope>): <description>
+```
+
+类型: 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]]
--- a/wiki/file-map.md
+++ 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]]
--- a/wiki/index.md
+++ 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 为准
--- a/wiki/known-issues.md
+++ 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]]
--- a/wiki/log.md
+++ 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 初始创建
+
+---
+
+> 更新规则: 每次重大变更后追加一条，最新在最上面
--- a/wiki/module-status.md
+++ 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]]