From b3f97d652507490bb0c7fb714c00ae76a4ebb67d Mon Sep 17 00:00:00 2001 From: iven Date: Sat, 11 Apr 2026 01:05:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E5=85=A8=E9=87=8F=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E9=AA=8C=E8=AF=81=E9=A9=B1=E5=8A=A8=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=20=E2=80=94=2010=E9=A1=B5=E5=9F=BA=E4=BA=8E=E5=AE=9E=E9=99=85?= =?UTF-8?q?=E6=89=AB=E6=8F=8F=E9=9D=9E=E6=96=87=E6=A1=A3=E6=8E=A8=E6=B5=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 关键数字修正: - Rust 74.5K行(原66K), Tauri命令 183(原182), SaaS路由 121 - 前端组件 104, lib/ 85文件, Store 17+4子store - TODO/FIXME 仅 8 个(前端4+Rust4) 内容增强: - 中间件完整14层注册清单含注册条件和优先级分类 - Store完整目录结构, Pipeline完整目录树 - Hands测试分布, Memory 16个Tauri命令列表 - 管家模式: 关键词路由→语义路由(TF-IDF)修正 - 代码健康度指标新增 --- wiki/butler.md | 59 +++++++++++++++++++++++++------- wiki/chat.md | 13 +++++-- wiki/development.md | 27 ++++++++------- wiki/hands-skills.md | 78 +++++++++++++++++++++++++++--------------- wiki/index.md | 38 ++++++++++++++++----- wiki/known-issues.md | 29 ++++++++++++++-- wiki/log.md | 13 +++++++ wiki/memory.md | 32 +++++++++++++++-- wiki/middleware.md | 81 ++++++++++++++++++++++++++++++++------------ wiki/pipeline.md | 61 +++++++++++++++++++++++++++------ wiki/routing.md | 43 ++++++++++++++++++++++- wiki/saas.md | 73 +++++++++++++++++++++++---------------- 12 files changed, 415 insertions(+), 132 deletions(-) diff --git a/wiki/butler.md b/wiki/butler.md index 2dfe699..3565f25 100644 --- a/wiki/butler.md +++ b/wiki/butler.md @@ -15,7 +15,7 @@ tags: [module, butler, interaction] 设计决策: 1. **默认激活** — 所有聊天都经过 ButlerRouter，不需要用户手动开启 -2. **4 域关键词分类** — healthcare / data_report / policy / meeting，自动增强 system prompt +2. **语义路由** — SemanticSkillRouter 用 TF-IDF 匹配 75 个技能，替代简单关键词 3. **痛点积累** — 从对话中提取用户痛点，积累后生成方案建议 4. **双模式 UI** — simple(纯聊天，默认) / professional(完整功能)，渐进式解锁 @@ -26,9 +26,11 @@ tags: [module, butler, interaction] ``` 用户消息 → ButlerRouter 中间件 (middleware/butler_router.rs) - → SemanticSkillRouter TF-IDF 匹配 75 个技能 - → 4 域关键词分类 - → 增强 system prompt (领域专用指令) + → ButlerRouterBackend trait → SemanticRouterAdapter + → SemanticSkillRouter (zclaw-skills/src/semantic_router.rs) + → TF-IDF 计算与 75 个技能的相似度 + → 返回 RoutingHint { category, confidence, skill_id } + → 增强 system prompt (匹配的技能上下文) → LLM 响应 → PainAggregator 提取痛点 → PainStorage (内存 Vec 热缓存 + SQLite 持久层) @@ -37,9 +39,21 @@ tags: [module, butler, interaction] → 基于痛点生成解决方案提案 ``` +### 语义路由桥接（kernel 层） + +```rust +// crates/zclaw-kernel/src/kernel/mod.rs:196-231 +struct SemanticRouterAdapter { router: Arc } +impl ButlerRouterBackend for SemanticRouterAdapter { + async fn classify(&self, query: &str) -> Option { ... } +} +``` + +这是 kernel 依赖 zclaw-runtime + zclaw-skills 的桥接点。 + ### 冷启动 (新用户引导) -入口: `desktop/src/hooks/use-cold-start.ts` +入口: `desktop/src/hooks/use-cold-start.ts`（lib/ 下有同名文件） ``` idle → (检测新用户) → greeting_sent → waiting_response → completed @@ -58,9 +72,33 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed 简洁侧边栏: `desktop/src/components/SimpleSidebar.tsx` 管家面板: `desktop/src/components/ButlerPanel.tsx` (3 区: 洞察/方案/记忆) +### Tauri 命令 + +5 个 butler 命令 (已标注 @reserved): + +```rust +// desktop/src-tauri/src/intelligence/pain_aggregator.rs +butler_list_pain_points +butler_record_pain_point +butler_generate_solution +butler_list_proposals +butler_update_proposal_status +``` + +### Intelligence 层文件结构 + +``` +desktop/src-tauri/src/intelligence/ +├── compactor.rs (5 commands: token estimation + compaction) +├── heartbeat.rs (10 commands: heartbeat engine CRUD) +├── identity.rs (16 commands: agent identity manager) +├── pain_aggregator.rs (5 commands: butler pain points) +└── reflection.rs (7 commands: reflection engine) +``` + ## 关联模块 -- [[middleware]] — ButlerRouter 是中间件链中的一层 +- [[middleware]] — ButlerRouter 是中间件链中的第一层 - [[chat]] — 消息流经过管家路由增强 - [[memory]] — 痛点存储在 memory 子系统 - [[hands-skills]] — 语义路由使用 75 个技能的 TF-IDF @@ -69,15 +107,12 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed | 文件 | 职责 | |------|------| -| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 (4域分类) | +| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 + ButlerRouterBackend trait | +| `crates/zclaw-skills/src/semantic_router.rs` | SemanticSkillRouter TF-IDF 实现 | +| `crates/zclaw-kernel/src/kernel/mod.rs:196-231` | SemanticRouterAdapter 桥接 | | `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点双写 (内存+SQLite) | | `crates/zclaw-kernel/src/intelligence/solution_generator.rs` | 方案生成 | | `desktop/src/hooks/use-cold-start.ts` | 冷启动 4 阶段 | | `desktop/src/store/uiModeStore.ts` | 双模式切换 | | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 | | `desktop/src/components/ButlerPanel.tsx` | 管家面板 (洞察/方案/记忆) | - -## Tauri 命令 - -6 个 butler 专属命令 (已标注 @reserved): -`butler_get_pain_points`, `butler_get_solutions`, `butler_delegate_task`, 等 diff --git a/wiki/chat.md b/wiki/chat.md index 6e46e68..d47a67c 100644 --- a/wiki/chat.md +++ b/wiki/chat.md @@ -30,7 +30,7 @@ tags: [module, chat, stream] ### 发送消息流 -入口: `streamStore.sendMessage(content)` → `streamStore.ts` +入口: `streamStore.sendMessage(content)` → `store/chat/streamStore.ts` ``` sendMessage(content) @@ -51,7 +51,7 @@ sendMessage(content) → 5 分钟超时守护 (kernel-chat.ts:76) 防止流挂起 ``` -### Store 拆分 (4 Store) +### Store 拆分 (5 Store) 原来 908 行的 ChatStore 已拆分为: @@ -61,6 +61,14 @@ sendMessage(content) | conversationStore | `store/chat/conversationStore.ts` | 会话管理、当前模型 | | messageStore | `store/chat/messageStore.ts` | 消息持久化 | | chatStore | `store/chat/chatStore.ts` | 聊天通用状态 | +| artifactStore | `store/chat/artifactStore.ts` | 聊天产物/附件 | + +### 前端 Tauri 命令映射 + +``` +kernel_chat / agent_chat / agent_chat_stream → 发送消息 +cancel_stream → 取消流式响应 +``` ### 模型切换 @@ -85,6 +93,7 @@ UI 选择模型 → conversationStore.currentModel = newModel |------|------| | `desktop/src/store/chat/streamStore.ts` | 流式消息编排 | | `desktop/src/store/chat/conversationStore.ts` | 会话管理 | +| `desktop/src/store/chat/artifactStore.ts` | 聊天产物管理 | | `desktop/src/lib/kernel-chat.ts` | Kernel ChatStream (Tauri) | | `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream | | `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) | diff --git a/wiki/development.md b/wiki/development.md index f7c561a..52a2fcd 100644 --- a/wiki/development.md +++ b/wiki/development.md @@ -23,23 +23,26 @@ tags: [development, conventions] | 禁止 | 原因 | |------|------| -| 新增 SaaS API 端点 | 已有 140 个，前端未全部接通 | +| 新增 SaaS API 端点 | 已有 121 个 .route()，前端未全部接通 | | 新增 SKILL.md | 已有 75 个 | -| 新增 Tauri 命令 | 已有 182 个，70 个孤儿 | -| 新增中间件/Store | 已有 14 层中间件 + 18 个 Store | +| 新增 Tauri 命令 | 已有 183 个，部分无前端调用 | +| 新增中间件 | 已有 14 层 | +| 新增 Store | 已有 17 文件 + chat/4 子store | | 新增 admin 页面 | 已有 15 页 | ## 分层职责 ``` -UI 组件 → 只负责展示和交互 -Store → 负责状态组织和流程编排 -Client → 负责网络通信和协议转换 +UI 组件 → 只负责展示和交互 (104 个 .tsx/.ts) +Store → 负责状态组织和流程编排 (17 文件 + 4 子store) +Client → 负责网络通信和协议转换 (85 个 lib/ 文件) ``` 禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过: - `desktop/src/lib/gateway-client.ts` — 主要通信客户端 - `desktop/src/lib/tauri-gateway.ts` — Tauri 原生命令 +- `desktop/src/lib/kernel-client.ts` — Kernel 客户端 +- `desktop/src/lib/saas-client.ts` — SaaS API 客户端 ## 验证命令 @@ -86,8 +89,9 @@ pnpm start:dev - 组件保持"展示层"职责 **Rust:** -- 错误处理: 禁止 `let _ =`，改为 `log::warn!` 或更高级别 +- 错误处理: 禁止 `let _ =`，改为 `tracing::warn!` 或更高级别 - 输入验证: 系统边界必须验证 +- 中间件: 实现 `AgentMiddleware` trait，4 个 hook 点 ## WebMCP 调试工具 @@ -106,10 +110,7 @@ pnpm start:dev 完成工作后，检查 wiki/ 是否需要更新： - 修复 bug → 更新 [[known-issues]] -- 架构变更 → 更新 [[architecture]] + [[data-flows]] -- 文件结构变化 → 更新 [[file-map]] -- 模块状态变化 → 更新 [[module-status]] +- 架构变更 → 更新对应模块页 + [[middleware]]/[[routing]] +- 文件结构变化 → 更新 [[routing]] Store 列表 +- 模块状态变化 → 更新 [[index]] 关键数字 - 每次更新 → 在 [[log]] 追加记录 - -→ 架构见 [[architecture]] -→ 文件位置见 [[file-map]] diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md index 238d70c..1464007 100644 --- a/wiki/hands-skills.md +++ b/wiki/hands-skills.md @@ -7,7 +7,7 @@ tags: [module, hands, skills] # Hands + Skills -> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] +> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[butler]] ## 设计思想 @@ -19,40 +19,60 @@ tags: [module, hands, skills] ## 代码逻辑 -### Hands (9 启用 + 2 禁用) +### Hands (9 启用) -| Hand | 功能 | 依赖 | 配置 | -|------|------|------|------| -| Browser | 浏览器自动化 | WebDriver | `hands/Browser/HAND.toml` | -| Collector | 数据收集聚合 | — | `hands/Collector/HAND.toml` | -| Researcher | 深度研究 | LLM | `hands/Researcher/HAND.toml` | -| Clip | 视频处理 | FFmpeg | `hands/Clip/HAND.toml` | -| Twitter | Twitter 自动化 | OAuth 1.0a | `hands/Twitter/HAND.toml` | -| Whiteboard | 白板演示 | — | `hands/Whiteboard/HAND.toml` | -| Slideshow | 幻灯片生成 | — | `hands/Slideshow/HAND.toml` | -| Speech | 语音合成 | Browser TTS | `hands/Speech/HAND.toml` | -| Quiz | 测验生成 | — | `hands/Quiz/HAND.toml` | -| Predictor | 预测分析 | **禁用** | 无 TOML/无 Rust 实现 | -| Lead | 销售线索 | **禁用** | 无 TOML/无 Rust 实现 | +每个 Hand 有独立的 `hands/.HAND.toml` 配置和 `crates/zclaw-hands/src/hands/` 下的 Rust 实现。 + +| Hand | 功能 | 依赖 | 测试数 | 配置 | +|------|------|------|--------|------| +| Browser | 浏览器自动化 (23 Tauri命令) | WebDriver | 8 | `hands/browser.HAND.toml` | +| Collector | 数据收集聚合 | — | 8 | `hands/collector.HAND.toml` | +| Researcher | 深度研究 | LLM | 22 | `hands/researcher.HAND.toml` | +| Clip | 视频处理 | FFmpeg | 30 | `hands/clip.HAND.toml` | +| Twitter | Twitter 自动化 (12 API v2) | OAuth 1.0a | 25 | `hands/twitter.HAND.toml` | +| Whiteboard | 白板演示 | — | — | `hands/whiteboard.HAND.toml` | +| Slideshow | 幻灯片生成 | — | 13 | `hands/slideshow.HAND.toml` | +| Speech | 语音合成 | Browser TTS | — | `hands/speech.HAND.toml` | +| Quiz | 测验生成 | — | — | `hands/quiz.HAND.toml` | + +Hands 测试分布（前 5）: Clip(30), Twitter(25), Researcher(22), Slideshow(13), Browser(8) + +### 禁用 Hands + +| Hand | 状态 | 说明 | +|------|------|------| +| Predictor | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 | +| Lead | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 | ### 触发流 ``` UI 触发 → handStore.trigger(handName, params) - → Tauri invoke('hand_trigger', { handName, params }) + → Tauri invoke('hand_execute', { handName, params }) → Kernel → Hand 执行 → needs_approval? → 等待 approvalStore 确认 → 执行结果 → Tauri Event emit → handStore 更新状态 + 记录日志 ``` -### Skills (75 个) +Hand 相关 Tauri 命令 (8 个): +`hand_list, hand_execute, hand_approve, hand_cancel, hand_get, hand_run_status, hand_run_list, hand_run_cancel` + +### Skills (75 个目录) ``` skills/ -├── SKILL_001_数据分析.md -├── SKILL_002_报告生成.md -├── ... (75 个 SKILL.md 文件) +├── accessibility-auditor/ api-tester/ +├── agentic-identity-trust/ app-store-optimizer/ +├── agents-orchestrator/ backend-architect/ +├── ai-engineer/ brand-guardian/ +├── analytics-reporter/ chart-visualization/ +├── chinese-writing/ classroom-generator/ +├── code-review/ consulting-analysis/ +├── content-creator/ data-analysis/ +├── data-consolidation-agent/ deep-research/ +├── devops-automator/ evidence-collector/ +├── ... (75 个目录，每个含 SKILL.md) ``` 每个 SKILL.md 定义: @@ -68,23 +88,27 @@ skills/ ``` 用户消息 → SemanticSkillRouter → TF-IDF 计算消息与 75 个技能的相似度 - → 返回最匹配的技能 - → ButlerRouter 使用此结果增强 system prompt + → 返回 { skill_id, confidence } + → ButlerRouter 使用 RoutingHint 增强 system prompt ``` +在 kernel 中通过 `SemanticRouterAdapter` 桥接到 `ButlerRouterBackend` trait。 + ## 关联模块 - [[chat]] — 消息流中可能触发 Hand/Skill - [[butler]] — ButlerRouter 使用语义路由匹配技能 -- [[middleware]] — 技能注入通过中间件实现 +- [[middleware]] — SkillIndex 中间件注入技能索引 ## 关键文件 | 文件 | 职责 | |------|------| -| `crates/zclaw-hands/src/` | 9 个 Hand 实现 | +| `crates/zclaw-hands/src/hands/` | 9 个 Hand 实现 | | `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 | -| `skills/*.md` | 75 个技能定义 | -| `hands/*/HAND.toml` | Hand 配置 | +| `crates/zclaw-skills/src/` | 技能解析和索引 | +| `skills/*/SKILL.md` | 75 个技能定义 | +| `hands/*.HAND.toml` | 9 个 Hand 配置 | | `desktop/src/store/handStore.ts` | 前端 Hand 状态 | -| `desktop/src/store/approvalStore.ts` | 审批状态 | +| `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 | +| `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) | diff --git a/wiki/index.md b/wiki/index.md index 5067777..925e4b6 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -8,34 +8,51 @@ status: active > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。 > **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。 +> **数据来源**: 2026-04-11 代码全量扫描验证，非文档推测。 ## 项目画像 | 维度 | 值 | |------|-----| | 定位 | AI Agent 桌面客户端 (Tauri 2.x) | -| 技术栈 | Rust 10 crates (~66K行) + React 19 + TypeScript + PostgreSQL | +| 技术栈 | Rust 10 crates (~74.5K行) + React 19 + TypeScript + PostgreSQL | | 阶段 | 发布前稳定化，功能冻结中 | -## 关键数字 +## 关键数字（2026-04-11 代码验证） -Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17 +| 指标 | 值 | 验证方式 | +|------|-----|----------| +| Rust Crates | 10 | `ls crates/zclaw-*/Cargo.toml` | +| Rust 代码 | 74,487 行 | `find crates/ -name "*.rs" \| xargs wc -l` | +| Rust #[test] | 431 个 | `grep '#\[test\]' crates/**/*.rs` | +| Tauri 命令 | 183 (含5 feature-gated) | `lib.rs generate_handler![]` 注册 | +| 前端 invoke 调用 | 105 处 | `grep invoke( desktop/src/` | +| SaaS .route() | 121 个 | `grep .route( crates/zclaw-saas/` | +| SKILL 目录 | 75 个 | `ls -d skills/*/` | +| HAND 配置 | 9 个 (TOML) | `ls hands/*.HAND.toml` | +| Pipeline YAML | 17 个 | `find pipelines/ -name "*.yaml"` | +| Zustand Store | 17 文件 + chat/4子store = 21 | `ls desktop/src/store/` | +| React 组件 | 104 个 (.tsx/.ts) | `find desktop/src/components/` | +| Admin V2 页面 | 15 个 (.tsx) | `ls admin-v2/src/pages/` | +| 中间件 | 14 层 (含1个条件注册) | `kernel/mod.rs create_middleware_chain` | +| 前端 lib/ | 85 个 .ts | `find desktop/src/lib/` | +| TODO/FIXME | 前端 4 + Rust 4 = 8 | `grep TODO/FIXME` | ## 模块导航树 ``` ZCLAW ├── [[routing]] 客户端路由 — 4分支决策，SaaS Relay是主路径 -│ └── [[chat]] 聊天系统 — 3种ChatStream，SaaS Token Pool是主路径 +│ └── [[chat]] 聊天系统 — 3种ChatStream，Store拆为4+1 │ ├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢 │ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换 │ ├── 计费 配额实时递增 + Alipay/WeChat │ └── Admin V2 15页管理后台 │ -├── [[butler]] 管家模式 — 默认交互范式，4域路由+冷启动+痛点 +├── [[butler]] 管家模式 — 默认交互范式，语义路由+冷启动+痛点 │ -├── [[middleware]] 中间件链 — 14层，DataMasking→ButlerRouter→TrajectoryRecorder +├── [[middleware]] 中间件链 — 14层，按优先级分类注册 │ ├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入 │ @@ -54,9 +71,12 @@ ZCLAW → 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。 **Q: 为什么有3种 ChatStream？** -→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。 +→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。 **Q: 为什么管家模式是默认？** -→ 面向医院行政等非技术用户，4域关键词分类+痛点积累+方案生成，降低使用门槛。 +→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。 -> 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准 +**Q: 为什么中间件是14层？** +→ 按优先级分4类: 100-199上下文(compaction/memory) → 200-399能力(skill/guardrail) → 400-599安全(loop_guard/data_masking) → 600-799遥测(token/title/trajectory)。Kernel `create_middleware_chain()` 条件注册，skill_index 仅在有技能时注册。 + +> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准 diff --git a/wiki/known-issues.md b/wiki/known-issues.md index 92012db..ab1ecae 100644 --- a/wiki/known-issues.md +++ b/wiki/known-issues.md @@ -18,13 +18,36 @@ tags: [issues, bugs] | P1.5 (代码质量) | 7 | 全部已修复 | | P2 (代码质量) | 10 | 待处理 | +## 代码健康度指标（2026-04-11 扫描） + +| 指标 | 值 | 说明 | +|------|-----|------| +| TODO/FIXME 前端 | 4 | 非常少 | +| TODO/FIXME Rust | 4 | 非常少 | +| @reserved 标注 | 33 | 无前端调用的命令已标注 | +| 前端孤立 invoke | 0 | 已清理 | + ## 长期观察项 | 问题 | 说明 | 位置 | |------|------|------| -| Tauri 命令孤儿 70 个 | 无前端调用且无 @reserved | `desktop/src-tauri/src/lib.rs` | +| Tauri 命令孤儿 | 注册 183 命令，前端调用 105 处，@reserved 33 个，剩余可能为内部调用 | `desktop/src-tauri/src/lib.rs` | | Embedding 未激活 | EmbeddingClient trait 已写但 NoOp | `zclaw-growth/src/retrieval/semantic.rs` | | SaaS embedding deferred | pgvector 索引就绪，生成未实现 | `zclaw-saas/src/workers/generate_embedding.rs` | -| webhook 死代码 | 5 路由定义但未挂载 | `zclaw-saas/src/webhook/` | +| SkillIndex 条件注册 | 无技能时 skill_index 中间件不注册 | `kernel/mod.rs:289` | +| Hermes Schema | v4 新增 user_profiles + trajectory 表 | `zclaw-saas/migrations/` | -→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]] +## 已修复的关键问题（历史记录） + +| ID | 问题 | 修复日期 | +|----|------|----------| +| SEC2-P0-01 | skill_execute 反序列化崩溃 | 04-02 | +| SEC2-P0-02 | TaskTool::default() panic | 04-02 | +| SEC2-P1-01~09 | 9 项功能失效 (FactStore/路径/监听/...) | 04-02 | +| SEC2-P1.5-01~07 | 7 项代码质量修复 | 04-02 | +| P0-2/P0-3 | usage 端点 + refresh token 类型 | 04-10 | +| P1-02 | 浏览器聊天 SaaS fixture | 04-10 | +| P1-04 | AuthGuard 竞态条件 | 04-10 | +| BREAKS 全部 | 全部 P0/P1/P2 已修复 | 04-10 | + +→ 模块详情见各模块页面: [[routing]] [[chat]] [[saas]] [[memory]] [[middleware]] diff --git a/wiki/log.md b/wiki/log.md index 0dc17d6..a604c33 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -9,6 +9,19 @@ tags: [log, history] > Append-only 操作记录。格式: `## [日期] 类型 | 描述` +## [2026-04-11] docs | Wiki 全面更新 — 代码验证驱动 + +- 全部 10 个 wiki 页面基于代码扫描验证更新（非文档推测） +- 关键数字修正: Rust 74.5K行(原66K)、Tauri命令 183(原182)、SaaS路由 121、前端组件 104、lib/ 85 文件 +- 新增中间件完整注册清单（14层含注册条件和优先级分类） +- 新增 Store 完整目录结构（17 文件 + chat/4 子store） +- 新增 Pipeline 模板完整目录树（17 YAML, 8 行业目录） +- 新增 Hands 测试数分布 +- 新增 memory Tauri 命令完整列表（16 个） +- 新增代码健康度指标（TODO/FIXME 仅 8 个） +- 修正管家模式描述: 关键词路由 → 语义路由(TF-IDF) +- 新增 artifactStore 到 chat Store 拆分列表 + ## [2026-04-11] init | 创建 wiki 知识库 - 从 TRUTH.md / ARCHITECTURE_BRIEF.md / CLAUDE.md 编译 8 个 wiki 页面 diff --git a/wiki/memory.md b/wiki/memory.md index d03366a..5953c08 100644 --- a/wiki/memory.md +++ b/wiki/memory.md @@ -60,6 +60,20 @@ ExperienceStore (crates/zclaw-growth/src/experience_store.rs) → URI scheme: agent://{agent_id}/experience/... ``` +### Hermes 管线 (4 Chunk) + +| Chunk | 模块 | 文件 | 测试 | +|-------|------|------|------| +| 1 | ExperienceStore + Extractor | experience_store.rs | 10 | +| 2 | UserProfileStore + Profiler | user_profile.rs | 14 | +| 3 | NlScheduleParser | nl_schedule.rs | 16 | +| 4 | TrajectoryRecorder + Compressor | middleware/trajectory_recorder.rs | 18 | + +Hermes 相关测试分布: +- `nl_schedule.rs`: 16 tests (中文时间→cron 解析) +- `types.rs`: 9 tests (记忆类型) +- `injector.rs`: 9 tests (prompt 注入) + ### 查询意图分类 `QueryAnalyzer` 支持 5 种意图: @@ -85,11 +99,21 @@ SaaS 侧: → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred) ``` +### 前端 Tauri 命令 + +Memory 相关命令 (13 个，来自 `memory_commands.rs` + `memory/`): +`memory_init, memory_store, memory_get, memory_search, memory_delete, memory_delete_all, memory_stats, memory_export, memory_import, memory_db_path, memory_configure_embedding, memory_is_embedding_configured, memory_build_context` + +加上 `memory/extractor.rs` 的 2 个: `extract_session_memories, extract_and_store_memories` +和 `memory/context_builder.rs` 的 1 个: `estimate_content_tokens` + +总计 16 个 memory 相关 Tauri 命令。 + ## 关联模块 - [[chat]] — 对话是记忆的输入源 - [[butler]] — 管家模式可能利用记忆提供个性化响应 -- [[middleware]] — 记忆注入通过中间件或 hook 实现 +- [[middleware]] — Memory 中间件自动提取 + SkillIndex 注入 ## 关键文件 @@ -102,5 +126,9 @@ SaaS 侧: | `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 | | `crates/zclaw-growth/src/retrieval/semantic.rs` | EmbeddingClient trait | | `crates/zclaw-growth/src/retrieval/query.rs` | 意图分类 + CJK 关键词 | -| `desktop/src/store/memoryStore.ts` | 前端记忆 UI | +| `crates/zclaw-growth/src/nl_schedule.rs` | 中文时间→cron 解析 (16 tests) | +| `crates/zclaw-runtime/src/middleware/memory.rs` | 记忆中间件 | +| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录中间件 | +| `desktop/src/store/memoryGraphStore.ts` | 前端记忆 UI | | `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 | +| `desktop/src-tauri/src/memory_commands.rs` | 13 个 memory CRUD 命令 | diff --git a/wiki/middleware.md b/wiki/middleware.md index 48b7bc4..149bb20 100644 --- a/wiki/middleware.md +++ b/wiki/middleware.md @@ -13,51 +13,88 @@ tags: [module, middleware, runtime] **中间件是请求处理的管道，按优先级顺序执行。** -- 优先级 0-100，数值越大越先执行 -- 每层中间件可以: 修改请求 / 拦截响应 / 记录日志 / 注入上下文 +- 优先级 0-999，数值越小越先执行（`middleware.rs` 按升序排列） +- 每层中间件实现 `AgentMiddleware` trait，4个 hook 点: `before_completion` / `before_tool_call` / `after_tool_call` / `after_completion` - 所有消息流（聊天、管家）都经过完整中间件链 +- 中间件可返回 `Stop`/`Block`/`AbortLoop` 决策来中断流程 ## 代码逻辑 -### 14 层中间件 +### 14 层中间件（注册顺序见 `kernel/mod.rs:190-345`） -关键中间件（按优先级排序）: +| # | 中间件 | 文件 | 职责 | 注册条件 | +|---|--------|------|------|----------| +| 1 | ButlerRouter | `middleware/butler_router.rs` | 语义技能路由 + system prompt 增强 | 始终 | +| 2 | DataMasking | `middleware/data_masking.rs` | 手机号/身份证等敏感数据脱敏 | 始终 | +| 3 | Compaction | `middleware/compaction.rs` | 超阈值时压缩对话历史 | `compaction_threshold > 0` | +| 4 | Memory | `middleware/memory.rs` | 对话后自动提取记忆 | 始终 | +| 5 | LoopGuard | `middleware/loop_guard.rs` | 防止工具调用无限循环 | 始终 | +| 6 | TokenCalibration | `middleware/token_calibration.rs` | Token 用量校准 | 始终 | +| 7 | SkillIndex | `middleware/skill_index.rs` | 注入技能索引到 system prompt | `!skill_index.is_empty()` | +| 8 | Title | `middleware/title.rs` | 自动生成会话标题 | 始终 | +| 9 | DanglingTool | `middleware/dangling_tool.rs` | 修复缺失的工具调用结果 | 始终 | +| 10 | ToolError | `middleware/tool_error.rs` | 格式化工具错误供 LLM 恢复 | 始终 | +| 11 | ToolOutputGuard | `middleware/tool_output_guard.rs` | 工具输出安全检查 | 始终 | +| 12 | Guardrail | `middleware/guardrail.rs` | shell_exec/file_write/web_fetch 安全规则 | 始终 | +| 13 | SubagentLimit | `middleware/subagent_limit.rs` | 限制并发子 agent | 始终 | +| 14 | TrajectoryRecorder | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 | 始终 | -| 优先级 | 中间件 | 文件 | 职责 | -|--------|--------|------|------| -| 90 | DataMasking | `middleware/data_masking.rs` | 请求发送前数据脱敏 (手机号/身份证) | -| ~500 | ButlerRouter | `middleware/butler_router.rs` | 4域关键词分类 + system prompt 增强 | -| 650 | TrajectoryRecorder | `middleware/trajectory_recorder.rs` | 轨迹记录 + 压缩 | +### 优先级分类（来自 `middleware.rs` 头注释） -其他 11 层: 认证、速率限制、日志、技能注入、记忆注入等。 +| 范围 | 类别 | 包含的中间件 | +|------|------|-------------| +| 100-199 | 上下文塑造 | Compaction, Memory | +| 200-399 | 能力 | SkillIndex, Guardrail | +| 400-599 | 安全 | LoopGuard, DataMasking | +| 600-799 | 遥测 | TokenCalibration, Title, TrajectoryRecorder | ### 中间件执行流 ``` -用户消息 - → [优先级 90] DataMasking — 脱敏敏感数据 - → [优先级 ~500] ButlerRouter — 关键词分类 + prompt 增强 - → [优先级 650] TrajectoryRecorder — 记录请求轨迹 - → [其他层] 认证/限流/日志/技能/记忆 +用户消息 → AgentLoop + → chain.run_before_completion(ctx) + → [按优先级升序] 每层 middleware.before_completion() + → Continue: 继续下一层 + → Stop(reason): 中断循环，返回 reason → LLM 调用 - → 响应原路返回 + → (工具调用时) chain.run_before_tool_call() + → Allow: 允许执行 + → Block(msg): 阻止，返回错误给 LLM + → ReplaceInput: 替换参数后允许 + → AbortLoop: 立即终止整个循环 + → chain.run_after_tool_call() + → chain.run_after_completion() +``` + +### 核心接口 + +```rust +// crates/zclaw-runtime/src/middleware.rs +trait AgentMiddleware: Send + Sync { + fn name(&self) -> &str; + fn priority(&self) -> i32 { 500 } + async fn before_completion(&self, ctx: &mut MiddlewareContext) -> Result; + async fn before_tool_call(&self, ctx: &MiddlewareContext, tool_name: &str, tool_input: &Value) -> Result; + async fn after_tool_call(&self, ctx: &mut MiddlewareContext, tool_name: &str, result: &Value) -> Result<()>; + async fn after_completion(&self, ctx: &MiddlewareContext) -> Result<()>; +} ``` ### 注册位置 -中间件在 `crates/zclaw-runtime/` 中注册，Kernel 启动时加载。 +`crates/zclaw-kernel/src/kernel/mod.rs:190-345` — `create_middleware_chain()` 方法，13 次 `chain.register()` + 1 个条件注册。 ## 关联模块 - [[butler]] — ButlerRouter 是管家模式的核心 - [[chat]] — 每条消息经过完整中间件链 -- [[memory]] — 记忆注入层从 FTS5 检索并注入 system prompt +- [[memory]] — Memory 中间件从对话提取记忆 +- [[hands-skills]] — SkillIndex 中间件注入技能索引 ## 关键文件 | 文件 | 职责 | |------|------| -| `crates/zclaw-runtime/src/middleware/` | 所有中间件实现 | -| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 | -| `crates/zclaw-runtime/src/middleware/data_masking.rs` | 数据脱敏 | -| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录 | +| `crates/zclaw-runtime/src/middleware.rs` | AgentMiddleware trait + MiddlewareChain | +| `crates/zclaw-runtime/src/middleware/` | 14 个中间件实现 (14个 .rs 文件) | +| `crates/zclaw-kernel/src/kernel/mod.rs:190-345` | 注册入口 | diff --git a/wiki/pipeline.md b/wiki/pipeline.md index 7b51977..f1aa8ab 100644 --- a/wiki/pipeline.md +++ b/wiki/pipeline.md @@ -15,7 +15,7 @@ tags: [module, pipeline, dsl] - YAML 定义 Pipeline 结构（步骤、依赖、输入/输出） - DAG 执行器按依赖拓扑排序执行 -- 17 个行业模板覆盖 10 大行业 +- 17 个 YAML 模板覆盖 8 大行业目录 - 前端已接通 8 个 Tauri invoke 调用 ## 代码逻辑 @@ -38,33 +38,72 @@ YAML Pipeline 定义 enum RunStatus { Pending, Running, Completed, Failed, Cancelled } ``` -### 模板 (17 个 YAML) +### 模板分布 (17 个 YAML) -位于 `pipelines/` 目录，覆盖: -- 汕头玩具行业、服装设计、医疗 -- 数据分析、报告生成 -- 教育、营销 -- 等 10 大行业 +``` +pipelines/ +├── _templates/ (2 模板) +│ ├── article-summary.yaml +│ └── competitor-analysis.yaml +├── design-shantou/ (4 模板) — 汕头玩具/服装行业 +│ ├── client-communication.yaml +│ ├── competitor-research.yaml +│ ├── supply-chain-collect.yaml +│ └── trend-to-design.yaml +├── education/ (4 模板) +│ ├── classroom.yaml +│ ├── lesson-plan.yaml +│ ├── research-to-quiz.yaml +│ └── student-analysis.yaml +├── healthcare/ (3 模板) +│ ├── data-report.yaml +│ ├── meeting-minutes.yaml +│ └── policy-compliance.yaml +├── legal/ (1 模板) +│ └── contract-review.yaml +├── marketing/ (1 模板) +│ └── campaign.yaml +├── productivity/ (1 模板) +│ └── meeting-summary.yaml +└── research/ (1 模板) + └── literature-review.yaml +``` ### 前端集成 | 组件 | 文件 | |------|------| | PipelineClient | `desktop/src/lib/pipeline-client.ts` | +| WorkflowBuilderStore | `desktop/src/store/workflowBuilderStore.ts` | +| Pipeline UI | `desktop/src/components/pipeline/` | | Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` | -8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用。 +Pipeline Tauri 命令 (12 个): + +| 文件 | 命令数 | 命令 | +|------|--------|------| +| discovery.rs | 8 | list/get/run/progress/cancel/result/runs/refresh | +| crud.rs | 3 | create/update/delete | +| intent_router.rs | 1 | route_intent | +| presentation.rs | 2 | analyze_presentation/pipeline_templates | + +前端 invoke 匹配: 8 个调用对应 8 个 discovery 命令，完整可用。 + +### 测试 + +`parser_v2.rs`: 11 tests — YAML 解析和 DAG 构建验证。 ## 关联模块 - [[hands-skills]] — Pipeline 步骤可能调用 Hand/Skill +- [[chat]] — Pipeline 可通过聊天触发 ## 关键文件 | 文件 | 职责 | |------|------| | `crates/zclaw-pipeline/src/executor.rs` | DAG 执行器 | -| `crates/zclaw-pipeline/src/` | Pipeline DSL 解析 | -| `pipelines/` | 17 个 YAML 模板 | +| `crates/zclaw-pipeline/src/parser_v2.rs` | YAML 解析 (11 tests) | +| `pipelines/` | 17 个 YAML 模板 (8 目录) | | `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 | -| `desktop/src-tauri/src/pipeline_commands/` | Tauri 命令桥接 | +| `desktop/src-tauri/src/pipeline_commands/` | 12 个 Tauri 命令 (4 文件) | diff --git a/wiki/routing.md b/wiki/routing.md index f7d8b65..175d8f8 100644 --- a/wiki/routing.md +++ b/wiki/routing.md @@ -86,6 +86,46 @@ listModels() 失败 `getClient()` 定义: `connectionStore.ts:844` 所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client。 +### Store 层 (17 文件 + chat/4) + +``` +desktop/src/store/ +├── index.ts Store 协调器 + client 注入 +├── agentStore.ts Agent 分身管理 +├── browserHandStore.ts 浏览器 Hand 状态 +├── chatStore.ts 聊天通用状态 +├── classroomStore.ts 课堂模式 +├── configStore.ts 配置读写 +├── connectionStore.ts 路由决策核心 +├── handStore.ts Hand 状态管理 +├── memoryGraphStore.ts 记忆图谱 +├── offlineStore.ts 离线队列 +├── saasStore.ts SaaS 认证 +├── securityStore.ts 安全状态 +├── sessionStore.ts 会话管理 +├── uiModeStore.ts 双模式 UI +├── workflowBuilderStore.ts 工作流构建器 +├── workflowStore.ts 工作流状态 +└── chat/ + ├── artifactStore.ts 聊天产物 + ├── conversationStore.ts 会话管理 + ├── messageStore.ts 消息持久化 + └── streamStore.ts 流式编排 +``` + +### lib/ 工具层 (85 个文件) + +关键分类: + +| 类别 | 文件 | 数量 | +|------|------|------| +| Kernel 通信 | kernel-chat/kernel-client/kernel-agent/... | 7 | +| SaaS 通信 | saas-client/saas-auth/saas-billing/... | 9 | +| Gateway | gateway-client/gateway-api/gateway-auth/... | 6 | +| Intelligence | intelligence-client/ + 5 fallback | 7 | +| 工具 | config-parser/crypto-utils/logger/utils | 10+ | +| Tauri 集成 | safe-tauri/tauri-gateway/secure-storage | 3 | + ## 关联模块 - [[chat]] — 路由决定使用哪种 ChatStream @@ -97,9 +137,10 @@ listModels() 失败 | 文件 | 职责 | |------|------| -| `desktop/src/store/connectionStore.ts` | 路由决策核心 (844行) | +| `desktop/src/store/connectionStore.ts` | 路由决策核心 | | `desktop/src/lib/gateway-client.ts` | WebSocket 客户端 | | `desktop/src/lib/kernel-chat.ts` | Tauri 内核聊天 | +| `desktop/src/lib/kernel-client.ts` | Kernel 客户端配置 | | `desktop/src/lib/saas-relay-client.ts` | SaaS SSE 中继 | | `desktop/src/lib/saas-client.ts` | SaaS API 客户端 | | `desktop/src/store/index.ts` | Store 协调器 + client 注入 | diff --git a/wiki/saas.md b/wiki/saas.md index 284ba23..70efc7e 100644 --- a/wiki/saas.md +++ b/wiki/saas.md @@ -25,7 +25,7 @@ tags: [module, saas, auth, billing] ``` 用户登录 (POST /api/v1/auth/login) - → Argon2id + OsRng 盐验证密码 + → Argon2id + OsRg 盐验证密码 → 签发 JWT (Claims: user_id, role, pwv) → set_auth_cookies(): zclaw_access_token (path:/api, 2h TTL, HttpOnly) @@ -62,7 +62,7 @@ JWT password_version (pwv): → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效 -密码存储: Argon2id + OsRng 随机盐 +密码存储: Argon2id + OsRg 随机盐 TOTP 加密: AES-256-GCM + 随机 Nonce ``` @@ -75,40 +75,52 @@ POST /api/v1/auth/refresh → 签发新 access + refresh token ``` +### SaaS 模块结构（代码验证） + +15 个模块目录 (`crates/zclaw-saas/src/`): + +``` +account/ agent_template/ auth/ billing/ knowledge/ +migration/ model_config/ models/ prompt/ relay/ +role/ scheduled_task/ tasks/ telemetry/ workers/ +``` + ### SaaS API 分布 -12 个路由模块，140 端点: +121 个 `.route()` 调用，12 个路由模块 (main.rs `.merge()` 注册): -| 模块 | 端点数 | 说明 | -|------|--------|------| -| auth | ~10 | 登录/注册/刷新/2FA | -| relay | ~5 | 聊天中转/模型列表/任务 | -| billing | 10 | 配额/订阅/支付 | -| knowledge | 23 | 知识库 CRUD + pgvector | -| model_config | ~8 | Provider + 模型管理 | -| account | ~8 | 用户管理 | -| agent_template | ~8 | Agent 模板 | -| role | 11 | 角色 + 权限 | -| telemetry | ~5 | 用量统计 | -| prompt | ~5 | Prompt 模板 | -| scheduled_task | 5 | 定时任务 CRUD | -| migration | ~2 | Schema 迁移 | +| 模块 | 路由注册 | 说明 | +|------|----------|------| +| auth | handlers.rs | 登录/注册/刷新/2FA | +| relay | relay/ | 聊天中转/模型列表/任务 | +| billing | billing/ + callback_routes | 配额/订阅/支付 | +| knowledge | knowledge/ | 知识库 CRUD + pgvector (最大模块) | +| model_config | model_config/ | Provider + 模型管理 | +| account | account/ | 用户管理 | +| agent_template | agent_template/ | Agent 模板 | +| role | role/ | 角色 + 权限 | +| telemetry | telemetry/ | 用量统计 | +| prompt | prompt/ | Prompt 模板 | +| scheduled_task | scheduled_task/ | 定时任务 CRUD | +| migration | migration/ | Schema 迁移 | -### 数据表 (34 个) +### 数据表 (38 CREATE TABLE) -核心: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version +32 个 SQL 迁移文件，38 个 `CREATE TABLE` 语句。 + +核心表: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version, user_profiles, trajectory_records ### Workers (7 个) -| Worker | 职责 | -|--------|------| -| log_operation | 操作日志 | -| cleanup_rate_limit | 限流记录清理 | -| cleanup_refresh_tokens | 刷新 token 清理 | -| record_usage | 用量记录 | -| update_last_used | 模型最后使用更新 | -| aggregate_usage | 用量聚合 | -| generate_embedding | 内容分块 (Phase 2 embedding deferred) | +| Worker | 文件 | 职责 | +|--------|------|------| +| log_operation | workers/ | 操作日志 | +| cleanup_rate_limit | workers/ | 限流记录清理 | +| cleanup_refresh_tokens | workers/ | 刷新 token 清理 | +| record_usage | workers/ | 用量记录 | +| update_last_used | workers/ | 模型最后使用更新 | +| aggregate_usage | workers/ | 用量聚合 | +| generate_embedding | workers/ | 内容分块 (embedding deferred) | ## 关联模块 @@ -120,12 +132,13 @@ POST /api/v1/auth/refresh | 文件 | 职责 | |------|------| +| `crates/zclaw-saas/src/main.rs` | 路由注册入口 (12个 .merge()) | | `crates/zclaw-saas/src/auth/handlers.rs` | 认证端点 | | `crates/zclaw-saas/src/relay/` | 聊天中转 | | `crates/zclaw-saas/src/billing/` | 计费 | -| `crates/zclaw-saas/src/knowledge/` | 知识库 (23 API) | +| `crates/zclaw-saas/src/knowledge/` | 知识库 | | `crates/zclaw-saas/src/workers/` | 7 个后台 Worker | -| `crates/zclaw-saas/migrations/` | SQL 迁移 (34 表) | +| `crates/zclaw-saas/migrations/` | SQL 迁移 (32 文件) | | `admin-v2/src/pages/` | 15 页管理后台 | | `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 | | `desktop/src/store/saasStore.ts` | SaaS 认证状态 |