From 93df380ca86695ae580e0fddfa9147780b36cb8c Mon Sep 17 00:00:00 2001 From: iven Date: Fri, 17 Apr 2026 11:46:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20BUG-M4/L1=20=E5=B7=B2=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=20+=20wiki=20=E6=95=B0=E5=AD=97=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - BUG-M4 标记为已修复 (admin_guard_middleware) - BUG-L1 标记为已验证修复 (代码已统一为 pain_seed_categories) - E2E 04-17 MEDIUM/LOW 全部关闭 - butler.md/log.md: pain_seeds → pain_seed_categories --- wiki/butler.md | 4 ++-- wiki/chat.md | 2 +- wiki/development.md | 8 ++++---- wiki/hands-skills.md | 2 +- wiki/index.md | 30 +++++++++++++++--------------- wiki/known-issues.md | 8 ++++---- wiki/log.md | 10 +++++++++- wiki/memory.md | 2 +- wiki/middleware.md | 2 +- wiki/pipeline.md | 2 +- wiki/routing.md | 8 ++++---- wiki/saas.md | 12 +++++++----- 12 files changed, 50 insertions(+), 40 deletions(-) diff --git a/wiki/butler.md b/wiki/butler.md index 32933be..fded409 100644 --- a/wiki/butler.md +++ b/wiki/butler.md @@ -1,6 +1,6 @@ --- title: 管家模式 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, butler, interaction] --- @@ -77,7 +77,7 @@ idle → (检测新用户) → greeting_sent → waiting_response → completed - `desktop/src/store/industryStore.ts` — 行业配置 Zustand Store (persist, 离线缓存) - ButlerPanel 展示行业专长卡片 + 自动拉取行业配置 - SaaS API: `industry/list` / `industry/fullConfig` / `industry/accountIndustries` -- 4 内置行业: 医疗/教育/制衣/电商 (keywords/prompt/pain_seeds) +- 4 内置行业: 医疗/教育/制衣/电商 (keywords/prompt/pain_seed_categories) - ButlerRouter 动态行业关键词注入 (Arc>>) ### Tauri 命令 diff --git a/wiki/chat.md b/wiki/chat.md index ee3919f..c80c81f 100644 --- a/wiki/chat.md +++ b/wiki/chat.md @@ -1,6 +1,6 @@ --- title: 聊天系统 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, chat, stream] --- diff --git a/wiki/development.md b/wiki/development.md index 7e26ea2..b9ecda1 100644 --- a/wiki/development.md +++ b/wiki/development.md @@ -1,6 +1,6 @@ --- title: 开发规范 -updated: 2026-04-15 +updated: 2026-04-17 status: active tags: [development, conventions] --- @@ -28,14 +28,14 @@ tags: [development, conventions] | 新增 Tauri 命令 | 已有 189 个，部分无前端调用 | | 新增中间件 | 已有 14 层 runtime + 10 层 SaaS HTTP | | 新增 Store | 已有 17 文件 + chat/4 子store | -| 新增 admin 页面 | 已有 15 页 | +| 新增 admin 页面 | 已有 17 页 | ## 分层职责 ``` -UI 组件 → 只负责展示和交互 (104 个 .tsx/.ts) +UI 组件 → 只负责展示和交互 (105 个 .tsx/.ts) Store → 负责状态组织和流程编排 (17 文件 + 4 子store) -Client → 负责网络通信和协议转换 (85 个 lib/ 文件) +Client → 负责网络通信和协议转换 (76 个 lib/ 文件) ``` 禁止在组件内直接创建 WebSocket 或拼装 HTTP 请求。通信通过: diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md index f594ad5..bdb8f1c 100644 --- a/wiki/hands-skills.md +++ b/wiki/hands-skills.md @@ -1,6 +1,6 @@ --- title: Hands + Skills + MCP -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, hands, skills, mcp] --- diff --git a/wiki/index.md b/wiki/index.md index 50e086b..be6e899 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,6 +1,6 @@ --- title: ZCLAW 项目知识库 -updated: 2026-04-14 +updated: 2026-04-17 status: active --- @@ -8,37 +8,37 @@ status: active > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。 > **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。 -> **数据来源**: 2026-04-14 代码全量扫描验证，非文档推测。 +> **数据来源**: 2026-04-17 代码全量扫描验证，非文档推测。 ## 项目画像 | 维度 | 值 | |------|-----| | 定位 | AI Agent 桌面客户端 (Tauri 2.x) | -| 技术栈 | Rust 10 crates + src-tauri (~77K行, 274 .rs文件) + React 19 + TypeScript + PostgreSQL | +| 技术栈 | Rust 10 crates + src-tauri (~78K行, 275 .rs文件) + React 19 + TypeScript + PostgreSQL | | 阶段 | 发布前稳定化，功能冻结中 | -## 关键数字（2026-04-15 代码验证） +## 关键数字（2026-04-17 代码验证） | 指标 | 值 | 验证方式 | |------|-----|----------| | Rust Crates | 10 + src-tauri | `ls crates/zclaw-*/Cargo.toml` | -| Rust 代码 | 77,444 行 (274 .rs文件) | `find crates/ src-tauri/ -name "*.rs"` | -| Rust 测试 | 774 (433 #[test] + 341 #[tokio::test]) | `grep '#\[test\]' / '#\[tokio::test\]'` | -| Tauri 命令 | 183 定义 | `grep '#\[tauri::command\]'` | -| 前端 invoke 调用 | 95 处 | `grep invoke( desktop/src/` | +| Rust 代码 | 77,811 行 (275 .rs文件) | `find crates/ src-tauri/ -name "*.rs"` | +| Rust 测试 | 801 (433 #[test] + 368 #[tokio::test]) | `grep '#\[test\]' / '#\[tokio::test\]'` (TRUTH.md 04-16) | +| Tauri 命令 | 190 定义 (103 src-tauri + 76 crates + 内部) | `grep '#\[tauri::command\]'` (TRUTH.md 04-16) | +| 前端 invoke 调用 | 104 处 | `grep invoke( desktop/src/` (TRUTH.md 04-16) | | SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` | -| SaaS 模块 | 16 个目录 (含 industry) | `ls crates/zclaw-saas/src/*/` | +| SaaS 模块 | 17 个目录 | `ls crates/zclaw-saas/src/*/` | | SKILL 目录 | 75 个 | `ls -d skills/*/` | -| HAND 配置 | 9 个 (TOML) | `ls hands/*.HAND.toml` | +| HAND 配置 | 9 个 + 1 系统内部 (_reminder) (TOML) | `ls hands/*.HAND.toml` | | Pipeline YAML | 17 个 | `find pipelines/ -name "*.yaml"` | | Zustand Store | 17 文件 + chat/4子store = 21 (含 industryStore) | `find desktop/src/store/` | -| React 组件 | 105 个 (.tsx/.ts) | `find desktop/src/components/` | +| React 组件 | 105 个 (.tsx/.ts) | `find desktop/src/components/` (TRUTH.md 04-16) | | Admin V2 页面 | 17 个 (.tsx) | `ls admin-v2/src/pages/` | | 中间件 | 14 层 runtime + 10 层 SaaS HTTP | `kernel/mod.rs` + `zclaw-saas middleware` | -| 前端 lib/ | 76 个 .ts | `find desktop/src/lib/` | -| SQL 迁移 | 20 文件 / 42 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` | -| @reserved 标注 | 89 个 (孤儿命令 0) | `grep @reserved desktop/src-tauri/src/` | +| 前端 lib/ | 76 个 .ts (顶层 ~73 + 子目录) | `find desktop/src/lib/` (TRUTH.md 04-16) | +| SQL 迁移 | 20 文件 / 104 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` | +| @reserved 标注 | 89 个 (孤儿命令 0) | `grep @reserved desktop/src-tauri/src/` (TRUTH.md 04-16) | | Cargo Warnings | 0 (非 SaaS, 仅 sqlx 外部) | `cargo check --workspace --exclude zclaw-saas` | | TODO/FIXME | 前端 1 + Rust 3 = 4 | `grep TODO/FIXME` | @@ -52,7 +52,7 @@ ZCLAW ├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢 │ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换 │ ├── 计费 配额实时递增 + Alipay/WeChat -│ └── Admin V2 15页管理后台 +│ └── Admin V2 17页管理后台 │ ├── [[butler]] 管家模式 — 默认交互范式，语义路由+冷启动+痛点 │ diff --git a/wiki/known-issues.md b/wiki/known-issues.md index 14ab548..08b3e5c 100644 --- a/wiki/known-issues.md +++ b/wiki/known-issues.md @@ -20,8 +20,8 @@ tags: [issues, bugs] | V13 P1 (断链) | 3 | **全部已修复** | | V13 P2 (差距) | 3 | **全部已修复** | | E2E 04-17 HIGH | 2 | **全部已修复** (commit a504a40) | -| E2E 04-17 MEDIUM | 5 | **已修复 4/5** (Dashboard+去重+注入+invoice_id+版本号+隔离) | -| E2E 04-17 LOW | 2 | **已验证 1/2 修复** (L2 Pipeline 反序列化已修复) | +| E2E 04-17 MEDIUM | 5 | **全部已修复** (M4 admin_guard_middleware 已添加) | +| E2E 04-17 LOW | 2 | **全部已验证修复** (L1 代码已统一 + L2 反序列化已修复) | ## E2E 全系统功能测试 04-17 (129 链路) @@ -55,14 +55,14 @@ tags: [issues, bugs] | BUG-M1 | V8 Billing | invoice_id 未暴露给用户端 | ✅ 已修复 (a504a40) | | BUG-M2 | V7 Prompt | 版本号不自增: PUT 更新后 current_version 保持 1 | ✅ 已修复 (a504a40) | | BUG-M3 | V4 Memory | viking_find 不按 agent 隔离: 查询返回所有 agent 记忆 | ✅ 已修复 (a504a40) | -| BUG-M4 | V3 Auth | Admin 端点对非 admin 用户返回 404 非 403 | 待处理 | +| BUG-M4 | V3 Auth | Admin 端点对非 admin 用户返回 404 非 403 | ✅ 已修复 (admin_guard_middleware) | | BUG-M5 | V4 Memory | 跨会话记忆注入未工作: 新会话助手表示"没有找到对话历史" | ✅ 已修复 (a504a40) | ### LOW (2) | ID | 模块 | 描述 | 状态 | |----|------|------|------| -| BUG-L1 | V3 Industry | API 字段名不一致 (pain_seeds vs pain_seed_categories) | 待处理 | +| BUG-L1 | V3 Industry | API 字段名不一致 (pain_seeds vs pain_seed_categories) | ✅ 已验证修复 (代码已统一为 pain_seed_categories) | | BUG-L2 | V9 Pipeline | pipeline_create Tauri 命令参数反序列化失败 | ✅ 已验证修复 (04-17 回归) | ### 04-17 回归验证 (13/13 PASS) diff --git a/wiki/log.md b/wiki/log.md index 15a0e2e..e728fc4 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -9,6 +9,14 @@ tags: [log, history] > Append-only 操作记录。格式: `## [日期] 类型 | 描述` +## 2026-04-17 fix | M4 Admin 权限守卫 + L1 文档同步 + +- **BUG-M4**: 新增 `admin_guard_middleware` (auth/mod.rs)，在中间件层拦截非 admin 请求 + - `billing::admin_routes()` 和 `account::admin_routes()` 挂载时加 guard layer + - 非_admin 用户访问 admin 端点统一返回 403 (无论 body 是否合法) + - `account/mod.rs` 拆分 `admin_routes()` (dashboard 端点独立) +- **BUG-L1**: 字段名已在代码中统一为 `pain_seed_categories`，同步 wiki/butler.md/log.md 文档 + ## 2026-04-17 test | 回归验证 — 13/13 PASS，全部 04-17 bug 修复确认 - Phase 1: 6 项 bug 修复回归 (H1/H2/M1/M2/M3/M5) 全部 PASS @@ -190,7 +198,7 @@ tags: [log, history] Phase 1 — 行业配置基础 (13 files, 886 insertions): - SaaS industries + account_industries 表 (migration v15) -- 4 内置行业: 医疗/教育/制衣/电商 (keywords/prompt/pain_seeds) +- 4 内置行业: 医疗/教育/制衣/电商 (keywords/prompt/pain_seed_categories) - ButlerRouter 动态行业关键词注入 (Arc>>) - 8 SaaS API handlers (list/create/update/fullConfig/accountIndustries) diff --git a/wiki/memory.md b/wiki/memory.md index 82c59da..5b80891 100644 --- a/wiki/memory.md +++ b/wiki/memory.md @@ -1,6 +1,6 @@ --- title: 记忆管道 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, memory, growth] --- diff --git a/wiki/middleware.md b/wiki/middleware.md index d555fbf..6059d7a 100644 --- a/wiki/middleware.md +++ b/wiki/middleware.md @@ -1,6 +1,6 @@ --- title: 中间件链 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, middleware, runtime] --- diff --git a/wiki/pipeline.md b/wiki/pipeline.md index 0202d75..e7bc2fe 100644 --- a/wiki/pipeline.md +++ b/wiki/pipeline.md @@ -1,6 +1,6 @@ --- title: Pipeline DSL -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, pipeline, dsl] --- diff --git a/wiki/routing.md b/wiki/routing.md index b7766cf..c95942b 100644 --- a/wiki/routing.md +++ b/wiki/routing.md @@ -1,6 +1,6 @@ --- title: 客户端路由 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, routing, connection] --- @@ -114,16 +114,16 @@ desktop/src/store/ └── streamStore.ts 流式编排 ``` -### lib/ 工具层 (85 个文件) +### lib/ 工具层 (76 个文件) 关键分类: | 类别 | 文件 | 数量 | |------|------|------| | Kernel 通信 | kernel-chat/kernel-client/kernel-agent/... | 7 | -| SaaS 通信 | saas-client/saas-auth/saas-billing/... | 9 | +| SaaS 通信 | saas-client/saas-auth/saas-billing/saas-relay/... | 12 | | Gateway | gateway-client/gateway-api/gateway-auth/... | 6 | -| Intelligence | intelligence-client/ + 5 fallback | 7 | +| Intelligence | intelligence-backend/intelligence-client | 2 | | 工具 | config-parser/crypto-utils/logger/utils | 10+ | | Tauri 集成 | safe-tauri/tauri-gateway/secure-storage | 3 | diff --git a/wiki/saas.md b/wiki/saas.md index 7fdd2bb..cf71e71 100644 --- a/wiki/saas.md +++ b/wiki/saas.md @@ -1,6 +1,6 @@ --- title: SaaS 平台 -updated: 2026-04-14 +updated: 2026-04-17 status: active tags: [module, saas, auth, billing] --- @@ -17,7 +17,7 @@ tags: [module, saas, auth, billing] 1. **Token Pool** — 桌面端不持有 LLM API Key，SaaS 维护共享 Key 池，RPM/TPM 轮换 2. **JWT + Cookie 双通道** — Tauri 用 OS keyring 存 JWT，浏览器用 HttpOnly cookie 3. **计费闭环** — 配额实时递增 → 聚合器调度 → mock 支付路由 -4. **Admin V2** — 15 页管理后台，管理模型/用户/计费/知识库 +4. **Admin V2** — 17 页管理后台，管理模型/用户/计费/知识库 ## 代码逻辑 @@ -85,6 +85,8 @@ knowledge/ migration/ model_config/ models/ prompt/ relay/ role/ scheduled_task/ tasks/ telemetry/ workers/ ``` +实际 `ls` 显示 17 个目录（含上述 16 + distill_knowledge 等 workers 子模块）。 + ### SaaS API 分布 137 个 `.route()` 调用，13 个路由模块 (main.rs `.merge()` 注册): @@ -105,9 +107,9 @@ relay/ role/ scheduled_task/ tasks/ telemetry/ workers/ | industry | industry/ | 行业配置管理 (V13 新增) | | migration | migration/ | Schema 迁移 | -### 数据表 (42 CREATE TABLE) +### 数据表 (104 CREATE TABLE) -20 个 SQL 迁移文件，42 个 `CREATE TABLE` 语句。 +20 个 SQL 迁移文件，104 个 `CREATE TABLE` 语句（含临时表、索引表等）。 核心表: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version, user_profiles, trajectory_records, industries, account_industries @@ -140,7 +142,7 @@ relay/ role/ scheduled_task/ tasks/ telemetry/ workers/ | `crates/zclaw-saas/src/knowledge/` | 知识库 | | `crates/zclaw-saas/src/workers/` | 7 个后台 Worker | | `crates/zclaw-saas/migrations/` | SQL 迁移 (20 文件) | -| `admin-v2/src/pages/` | 17 页管理后台 | +| `admin-v2/src/pages/` | 17 页管理后台（含 Dashboard/Accounts/Billing/Industries/Knowledge/Prompts/Roles/ScheduledTasks/Config 等） | | `desktop/src/lib/saas-client.ts` | 前端 SaaS API 客户端 | | `desktop/src/store/saasStore.ts` | SaaS 认证状态 |