From ed77095a37e3cf105b3628e3316712387299752d Mon Sep 17 00:00:00 2001 From: iven Date: Tue, 21 Apr 2026 23:48:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E7=B3=BB=E7=BB=9F=E6=80=A7?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20=E2=80=94=20L0=E9=80=9F=E8=A7=88+L1?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=A0=87=E5=87=86=E5=8C=96+L2=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E9=93=BE=E8=B7=AF=E6=98=A0=E5=B0=84(33=E6=9D=A1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 三层架构增强: - L0 index.md: 用户功能清单+跨模块数据流全景图+导航树增强 (92→143行) - L1 8个模块页标准化: 功能清单/API接口/测试链路/已知问题 routing(252→326) chat(101→157) saas(153→230) memory(182→333) butler(137→179) middleware(121→159) hands-skills(218→257) pipeline(111→156) - L1 新增2页: security.md(157行) data-model.md(180行) - L2 feature-map.md: 33条端到端功能链路映射(408行) 维护机制: CLAUDE.md §8.3 wiki触发规则 5→9条 设计文档: docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md --- CLAUDE.md | 10 +- ...6-04-21-wiki-systematic-overhaul-design.md | 311 +++++++++++++ wiki/butler.md | 44 +- wiki/chat.md | 58 ++- wiki/data-model.md | 180 ++++++++ wiki/feature-map.md | 408 ++++++++++++++++++ wiki/hands-skills.md | 41 +- wiki/index.md | 69 ++- wiki/log.md | 14 + wiki/memory.md | 163 ++++++- wiki/middleware.md | 40 +- wiki/pipeline.md | 47 +- wiki/routing.md | 76 +++- wiki/saas.md | 79 +++- wiki/security.md | 157 +++++++ 15 files changed, 1672 insertions(+), 25 deletions(-) create mode 100644 docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md create mode 100644 wiki/data-model.md create mode 100644 wiki/feature-map.md create mode 100644 wiki/security.md diff --git a/CLAUDE.md b/CLAUDE.md index 6e63603..f3c1a6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -359,9 +359,13 @@ docs/ 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` + - 架构变更 → 更新对应模块页 (routing/chat/saas/memory/...) + - 文件结构变化 → 更新对应模块页的"关键文件"表 + - 模块状态变化 → 更新对应模块页的"功能清单"表 + - 功能清单变化 → 更新 `wiki/feature-map.md` 对应链路 + - API 接口增删 → 更新对应模块页的"API 接口"表 + - 测试增删 → 更新对应模块页的"测试链路"表 + - 数字变化 → 更新 `wiki/index.md` 关键数字表 + `docs/TRUTH.md` - 每次更新 → 在 `wiki/log.md` 追加一条记录 6. **docs/TRUTH.md** — 数字（命令数、Store 数、crates 数等）变化时 diff --git a/docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md b/docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md new file mode 100644 index 0000000..779a489 --- /dev/null +++ b/docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md @@ -0,0 +1,311 @@ +# Wiki 系统性更新设计文档 + +> **日期**: 2026-04-21 +> **状态**: Draft +> **目标**: 解决 AI 会话上下文重建 token 浪费、测试链路映射缺失、文档碎片化三大痛点 + +--- + +## 1. 背景与问题 + +### 现状 + +- wiki/ 目录有 13 个 .md 文件（index + 11 模块页 + 1 参考文档 hermes-analysis.md），总计约 2800 行 +- 内容覆盖路由、聊天、SaaS、管家、记忆、中间件、Hands/Skills、Pipeline 等模块 +- 每个页面有"设计思想"和"代码逻辑"概要，但缺少完整的功能清单、API 接口表、测试链路 + +### 核心痛点 + +1. **AI 上下文重建** — 新会话的 AI 每次从零理解系统架构、数据流、模块关系，大量 token 花在建立上下文上 +2. **测试链路映射缺失** — 缺少功能→代码→API→测试的完整映射，导致测试覆盖不全、重复审计 +3. **文档碎片化** — 同一概念在 wiki/memory/CLAUDE.md/docs/ 多处描述，内容不一致 + +### 期望效果 + +- 新 AI 会话加载 index.md 后 30 秒内建立全局认知 +- 任何功能可通过 feature-map.md 追踪完整链路 +- 模块页格式统一，降低阅读和更新成本 + +--- + +## 2. 方案：分层混合架构（C 方案） + +三层设计，每层独立有用： + +| 层 | 内容 | 文件 | 目的 | +|----|------|------|------| +| L0 速览 | 1 页精简索引 | `wiki/index.md` (增强) | 30 秒内建立全局认知 | +| L1 模块 | 12+ 个模块页，标准化章节 | `wiki/routing.md` 等 (增强) | 深入理解单个模块 | +| L2 链路 | 功能→代码→API→测试映射 | `wiki/feature-map.md` (新增) | 系统性测试验证和审计 | + +--- + +## 3. L0 — index.md 增强 + +当前 92 行，目标 **≤200 行**。新增约 80 行。 + +### 3.1 新增「用户功能清单」表格 + +按用户视角列出所有可做之事： + +| 类别 | 功能 | 用户入口 | Wiki 详情 | +|------|------|----------|-----------| +| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] | +| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] | +| 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] | +| 记忆 | 搜索历史、自动注入上下文 | 设置 > 语义记忆 | [[memory]] | +| 配置 | 模型/API/工作区设置 | 设置面板 (19 页) | [[development]] | +| SaaS | 登录注册、订阅计费、Admin | SaaS 平台 / Admin 后台 | [[saas]] | +| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] | +| Pipeline | YAML 模板、DAG 执行 | 工作流面板 | [[pipeline]] | +| 安全 | JWT 认证、TOTP 2FA、操作审计 | 设置 > 安全存储 | [[security]] | +| 数据 | PostgreSQL (SaaS 42表) + SQLite/FTS5/TF-IDF (本地记忆) | — | [[data-model]] | + +### 3.2 新增「跨模块数据流全景图」 + +展示主路径（SaaS relay）的完整请求生命周期，格式如下： + +``` +用户输入 → React组件 → Zustand Store → getClient() → KernelClient/SaaSRelay + → Tauri Event / SSE → Kernel → Runtime → Middleware Chain (15层) + → LLM Driver → 流式返回 → Store.onDelta → UI 更新 +``` + +图中标注关键分支点（本地 Kernel vs SaaS relay），并注明详细流程图在 [[routing]] 和 [[chat]] 页面。此图作为索引而非完整复制。 + +### 3.3 关键数字表 + +保持现有格式不变，确保数字与 TRUTH.md 同步。 + +### 3.4 导航树增强 + +每个模块条目加"这个页解决什么问题"的提示。 + +--- + +## 4. L1 — 模块页标准化 + +### 4.1 标准章节模板 + +```markdown +--- +title: 模块名 +updated: YYYY-MM-DD +status: active +tags: [module, ...] +--- + +# 模块名 + +> 导航提示 + 关联模块链接 + +## 设计思想 +核心架构决策的"为什么" + +## 功能清单 +| 功能 | 描述 | 入口文件 | 状态 | + +## 代码逻辑 +关键实现路径说明 + +## API 接口 +| 接口 | 类型 | 参数 | 返回值 | 权限 | + +## 数据流 +ASCII 图 + 文字描述 + +## 测试链路 +| 功能 | 测试文件 | 测试数 | 覆盖状态 | + +## 关联模块 +- [[related-module-a]] — 交互关系说明 +- [[related-module-b]] — 交互关系说明 + +## 关键文件 +| 文件路径 | 用途 | + +## 已知问题 +链接到 known-issues.md 相关条目 +``` + +> 注：frontmatter（title/updated/status/tags）是强制性的，所有现有页面均已包含。 + +### 4.2 需要增强的现有页面 + +| 页面 | 当前行数 | 缺失章节 | 预计新增行 | +|------|---------|----------|-----------| +| routing.md | 252 | API 接口表、测试链路 | ~80 | +| chat.md | 101 | 功能清单、API 接口表、测试链路 | ~100 | +| saas.md | 153 | 功能清单、API 接口完整表、测试链路 | ~120 | +| butler.md | 137 | 功能清单、测试链路 | ~60 | +| memory.md | 182 | 功能清单、API 接口表、测试链路 | ~80 | +| middleware.md | 121 | 功能清单、测试链路 | ~60 | +| hands-skills.md | 218 | API 接口表、测试链路 | ~80 | +| pipeline.md | 111 | 功能清单、API 接口表、测试链路 | ~80 | +| known-issues.md | 259 | 已完整，保持不变 | 0 | +| development.md | 199 | 已完整，保持不变 | 0 | +| log.md | 498 | append-only 日志，保持不变 | 0 | +| hermes-analysis.md | 463 | 参考文档，保持不变 | 0 | + +### 4.3 需要新增的页面 + +| 新页面 | 覆盖内容 | 预计行数 | +|--------|---------|---------| +| security.md | 安全体系：JWT/Cookie/TOTP/CSP/限流/加密 | ~200 | +| data-model.md | 数据模型：42 表 + 关键关系 + ER 图 | ~200 | + +> data-model.md 数据源：`crates/zclaw-saas/migrations/*.sql`（38 个 SQL 文件，42 个 CREATE TABLE），通过 `grep 'CREATE TABLE'` 提取表名，通过 `FOREIGN KEY` 约束提取关系。ER 图覆盖核心表（users, agents, conversations, messages, billing_*, knowledge_*），不逐一列出全部 42 表。 + +### 4.4 数据收集方法 + +填充标准化章节需要从代码库收集实际数据： + +| 章节 | 数据收集方式 | +|------|-------------| +| 功能清单 | 从 Tauri 命令分组 + Store 方法 + 前端组件分析 | +| API 接口表 | `grep '#\[.*tauri::command'` 提取命令签名 + `grep .route(` 提取 SaaS 路由 | +| 测试链路 | `cargo test --workspace --exclude zclaw-saas` + `pnpm vitest run` 提取测试名 | +| 数据流 | 从代码逻辑追踪函数调用链，参考已有 routing.md/chat.md 中的流程图 | + +### 4.5 各层行数限制 + +| 层 | 文件类型 | 行数限制 | +|----|---------|---------| +| L0 | index.md | ≤200 行 | +| L1 | 模块页 (routing/chat/saas/...) | ≤400 行 | +| L2 | feature-map.md | ≤600 行 | + +### 4.6 原则 + +- 每个模块页控制在行数限制内（见上表） +- API 接口表只列本模块接口，不重复其他模块 +- 数据流图用 ASCII，不依赖外部工具 +- 测试链路表只列与该模块直接相关的测试 + +--- + +## 5. L2 — 功能链路映射 (feature-map.md) + +> 注：以下示例中的文件路径和测试数量仅供参考。实际内容必须通过 `cargo test`、`pnpm vitest run` 并检查输出后填入，不使用假设值。 + +```markdown +### F-01: 智能对话 +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天输入框 → chatStore.sendMessage() | +| 前端关键文件 | chatStore, streamStore, ChatPanel.tsx | +| 通信层 | getClient() → KernelClient/SaaS Relay | +| Tauri 命令 | send_message → kernel::chat::send | +| 中间件链 | ButlerRouter@80 → ... → Memory@150 → ... | +| Rust 核心 | kernel → runtime → LLM Driver | +| 流式返回 | LLM → runtime → Tauri Event → streamStore.onDelta | +| SaaS API | POST /api/v1/chat/completions | +| 测试文件 | tests/e2e/chat.spec.ts (12 tests) | +| 测试状态 | ✅ 12/12 PASS | +``` + +### 5.2 覆盖范围 + +按 TRUTH.md §2.1 "确认可用"的 11 项功能为骨架，展开子功能形成 **33 条链路**。展开逻辑： + +| TRUTH.md 项 | 展开子功能 | 链路数 | +|-------------|-----------|--------| +| 智能对话 | 发消息、流式响应、模型切换、上下文管理、取消 | 5 | +| Agent 分身管理 | 创建 Agent、切换、配置、删除 | 4 | +| 模型切换 | 模型列表、切换、配置持久化 | 合并到对话 | +| Hand 触发 | 触发 Hand、审批流程、结果查看、Browser 自动化 | 4 | +| Hand 审批 | 合并到 Hand 触发 | — | +| 记忆搜索 | 搜索历史、自动注入、手动管理 | 3 | +| 配置读写 | 模型设置、工作区、数据隐私 | 3 | +| SaaS 登录/注册 | 注册、登录、Token 刷新 | 3 | +| SaaS 配置同步 | 配置拉取、推送、订阅状态 | 合并到 SaaS | +| Admin V2 管理 | Agent 管理、用户管理、系统配置 | 3 | +| 支付集成 | 创建订单、回调处理、发票 | 3 | +| 管家模式 | 简洁/专业切换、行业配置、痛点积累 | 3 | +| Pipeline 执行 | 选择模板、配置参数、执行工作流 | 3 | + +| 大类 | 链路数 | 示例 | +|------|--------|------| +| 对话 | 5 | 发消息、流式响应、模型切换、上下文管理、取消 | +| 分身 | 4 | 创建 Agent、切换、配置、删除 | +| 自主能力 | 4 | 触发 Hand、审批、结果查看、Browser 自动化 | +| 记忆 | 3 | 搜索历史、自动注入、手动管理 | +| SaaS | 5 | 注册、登录、订阅、计费、Admin 管理 | +| 管家 | 3 | 简洁/专业切换、行业配置、痛点积累 | +| Pipeline | 3 | 选择模板、配置参数、执行工作流 | +| 配置 | 3 | 模型设置、工作区、数据隐私 | +| 安全 | 3 | JWT 认证、TOTP 2FA、操作审计 | + +> F 编号排序原则：按用户流程优先级排列 — 对话 > Agent > Hands > 记忆 > SaaS > 管家 > Pipeline > 配置 > 安全。 + +### 5.3 原则 + +- 每条链路 10-15 行，可快速扫描 +- 文件路径用相对路径，可直接定位 +- 测试状态标注实际运行结果，不猜测 +- 总计 **500-600 行** + +--- + +## 6. 维护机制 + +### 6.1 收尾流程增强（约定级） + +在 CLAUDE.md §8.3 wiki/ 触发规则中增加： + +``` +改动涉及功能清单变化 → 更新 wiki/feature-map.md 对应链路 +改动涉及 API 接口增删 → 更新对应模块页的 API 接口表 +改动涉及测试增删 → 更新对应模块页的测试链路表 +改动涉及数字变化 → 更新 wiki/index.md 关键数字表 +``` + +### 6.2 一致性校验脚本（可选，自动化级） + +实现为 Node 脚本（与 `scripts/` 中现有 validate-config.ts 一致），可在 Windows/跨平台运行： + +- index.md 数字 vs TRUTH.md 数字 → 不一致警告 +- feature-map.md 文件路径是否存在 → 不存在警告 +- 模块页 API 接口数 vs 代码实际数 → 偏差>5% 警告 + +不做 CI 阻断，只在本地提醒。可选实现。 + +### 6.3 更新责任人 + +- 遵循"谁改动谁更新"原则（已在 §8.3 约定） +- 无固定更新周期，跟随代码变更 + +--- + +## 7. 交付物清单 + +| # | 交付物 | 预计行数 | 说明 | +|---|--------|---------|------| +| 1 | wiki/index.md 增强 | 92→200 | 新增功能清单+数据流全景图+导航增强 | +| 2 | wiki/routing.md 增强 | 252→330 | 补充 API 接口表+测试链路 | +| 3 | wiki/chat.md 增强 | 101→200 | 补充功能清单+API 接口表+测试链路 | +| 4 | wiki/saas.md 增强 | 153→270 | 补充功能清单+API 接口表+测试链路 | +| 5 | wiki/butler.md 增强 | 137→200 | 补充功能清单+测试链路 | +| 6 | wiki/memory.md 增强 | 182→260 | 补充功能清单+API 接口表+测试链路 | +| 7 | wiki/middleware.md 增强 | 121→180 | 补充功能清单+测试链路 | +| 8 | wiki/hands-skills.md 增强 | 218→300 | 补充 API 接口表+测试链路 | +| 9 | wiki/pipeline.md 增强 | 111→190 | 补充功能清单+API 接口表+测试链路 | +| 10 | wiki/security.md 新增 | ~200 | 安全体系完整文档 | +| 11 | wiki/data-model.md 新增 | ~200 | 数据模型+ER 图 | +| 12 | wiki/feature-map.md 新增 | ~600 | 功能链路映射（30-40 条） | +| 13 | CLAUDE.md §8.3 更新 | ~10 | 增加 wiki 触发规则 | + +**总计**: 现有 8 个页面增强 + 2 个新页面 + 1 个核心新页面 + CLAUDE.md 更新 + +--- + +## 8. 验证方式 + +完成后的验证清单（每项含可衡量标准）： + +- [ ] **全局认知**: 新 AI 会话仅加载 wiki/index.md 后，能准确回答"系统有哪些模块、数据怎么流转"（无需翻其他文件） +- [ ] **链路完整性**: feature-map.md 中每条链路引用的文件路径 100% 存在且正确（0 个失效路径） +- [ ] **接口一致性**: 模块页 API 接口数与代码实际数偏差 < 5% +- [ ] **测试覆盖**: 测试链路表中列出的测试文件均存在，且数量与 `cargo test` / `pnpm vitest run` 输出一致 +- [ ] **格式统一**: 所有 10 个增强模块页包含标准模板的全部 8 个章节 +- [ ] **校验脚本**: wiki-check 脚本通过（如实现），0 个警告 diff --git a/wiki/butler.md b/wiki/butler.md index 0587104..7864a48 100644 --- a/wiki/butler.md +++ b/wiki/butler.md @@ -1,6 +1,6 @@ --- title: 管家模式 -updated: 2026-04-19 +updated: 2026-04-21 status: active tags: [module, butler, interaction] --- @@ -115,6 +115,40 @@ desktop/src-tauri/src/intelligence/ └── validation.rs 验证逻辑 ``` +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| 语义路由 | TF-IDF 匹配 75 技能关键词 | butler_router.rs | ✅ | +| 管家主动引导 | 冷启动 4 阶段 + 追问 | use-cold-start.ts | ✅ | +| 痛点积累 | 对话中提取痛点 → 方案建议 | pain_storage.rs | ✅ | +| 双模式 UI | simple/professional 渐进式 | uiModeStore.ts | ✅ | +| 行业配置 | 4 内置行业 + 自定义 | industryStore.ts | ✅ | +| 跨会话连续 | 痛点回访 + 经验检索 | butlerStore.ts | ✅ | +| ButlerContext 注入 | XML fencing 增强系统提示 | ButlerRouter@80 | ✅ | +| 个性化检测 | personality_detector 自动分类 | personality_detector.rs | ✅ | +| 方案生成 | 痛点 → 解决方案建议 | solution_generator.rs | ✅ | + +## 测试链路 + +| 功能 | 测试文件 | 测试数 | 覆盖状态 | +|------|---------|--------|---------| +| 管家路由 | intelligence/butler_router.rs (middleware/) | 12 | ✅ | +| 冷启动 | intelligence/cold_start_prompt.rs | 7 | ✅ | +| 痛点聚合 | intelligence/pain_aggregator.rs | 9 | ✅ | +| 痛点存储 | intelligence/pain_storage.rs | 11 | ✅ | +| 方案生成 | intelligence/solution_generator.rs | 5 | ✅ | +| 个性化 | intelligence/personality_detector.rs | 8 | ✅ | +| 触发信号 | intelligence/triggers.rs | 7 | ✅ | +| 用户画像 | intelligence/user_profiler.rs | 9 | ✅ | +| 经验 | intelligence/experience.rs | 9 | ✅ | +| 身份 | intelligence/identity.rs | 5 | ✅ | +| 反思 | intelligence/reflection.rs | 4 | ✅ | +| 压缩 | intelligence/trajectory_compressor.rs | 11 | ✅ | +| 验证 | intelligence/validation.rs | 5 | ✅ | +| 提取适配 | intelligence/extraction_adapter.rs | 3 | ✅ | +| **合计** | 15 文件 | **99** | | + ## 关联模块 - [[middleware]] — ButlerRouter 是中间件链中的第一层 @@ -135,3 +169,11 @@ desktop/src-tauri/src/intelligence/ | `desktop/src/store/uiModeStore.ts` | 双模式切换 | | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 | | `desktop/src/components/ButlerPanel.tsx` | 管家面板 (洞察/方案/记忆) | + +## 已知问题 + +- ✅ **行业 API 字段名不一致** — BUG-L1 已修复。`pain_seeds` vs `pain_seed_categories` +- ✅ **industryStore 无组件导入** — V13-GAP-02 已修复 (已连接 ButlerPanel) +- ✅ **行业选择 500** — 类型不匹配已修复 +- ✅ **桌面端未接入 Knowledge Search** — V13-GAP-03 已修复 (saas-knowledge mixin) +- ⚠️ **SkillIndex 条件注册** — 无技能时中间件不注册，长期观察 diff --git a/wiki/chat.md b/wiki/chat.md index f79f720..04fe204 100644 --- a/wiki/chat.md +++ b/wiki/chat.md @@ -1,6 +1,6 @@ --- title: 聊天系统 -updated: 2026-04-17 +updated: 2026-04-21 status: active tags: [module, chat, stream] --- @@ -26,6 +26,20 @@ tags: [module, chat, stream] { onDelta, onThinkingDelta, onTool, onHand, onComplete, onError } ``` +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| 发送消息 | 流式/非流式，支持 thinking | streamStore.ts | ✅ | +| 流式响应 | SSE/Tauri Event 实时推送 | streamStore.ts | ✅ | +| 模型切换 | 运行时切换 LLM 模型 | conversationStore.ts | ✅ | +| 上下文管理 | 会话持久化 + 跨会话恢复 | conversationStore.ts | ✅ | +| 取消流式 | 原子标志位中断 | kernel-chat.ts | ✅ | +| Agent 聊天 | 指定 agent_id 独立对话 | streamStore.ts | ✅ | +| 课堂聊天 | 教育场景专用 | classroomStore.ts | ✅ | +| 消息持久化 | IndexedDB 存储 | messageStore.ts | ✅ | +| 聊天产物 | 附件/代码块管理 | artifactStore.ts | ✅ | + ## 代码逻辑 ### 发送消息流 @@ -79,6 +93,41 @@ UI 选择模型 → conversationStore.currentModel = newModel → 本地模式: 直接使用用户配置的模型 ``` +## API 接口 + +### Tauri 命令 + +**聊天核心** (`desktop/src-tauri/src/kernel_commands/chat.rs`): + +| 命令 | 参数 | 返回值 | 说明 | +|------|------|--------|------| +| `agent_chat` | ChatRequest { agent_id, message, thinking_enabled?, model? } | `ChatResponse` | 非流式聊天 | +| `agent_chat_stream` | StreamChatRequest { +session_id } | Tauri Event 流 | 流式聊天（主路径） | +| `cancel_stream` | session_id | `()` | 取消当前流式 | + +**课堂聊天** (`desktop/src-tauri/src/classroom_commands/chat.rs`): + +| 命令 | 参数 | 返回值 | 说明 | +|------|------|--------|------| +| `classroom_chat` | { classroom_id, user_message, scene_context? } | `Vec` | 课堂对话 | +| `classroom_chat_history` | classroom_id | `Vec` | 历史消息 | + +**流式事件类型** (agent_chat_stream emit): +`Delta` / `ThinkingDelta` / `ToolStart` / `ToolEnd` / `HandStart` / `HandEnd` / `SubtaskStatus` / `IterationStart` / `Complete` / `Error` + +### SaaS Relay 路由 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/v1/relay/chat/completions` | OpenAI 兼容格式，支持 session_key/agent_id 透传 | + +## 测试链路 + +| 功能 | 测试文件 | 测试数 | 覆盖状态 | +|------|---------|--------|---------| +| ChatStore 完整流程 | `tests/desktop/chatStore.test.ts` | 11 | ✅ sendMessage/sessionKey/agent隔离/stream相关 | +| 类型契约测试 | `tests/seam/chat-seam.test.ts` | 8 | ✅ StreamChatRequest/ChatResponse camelCase/Event tagged union | + ## 关联模块 - [[routing]] — 路由决定使用哪种 client @@ -99,3 +148,10 @@ UI 选择模型 → conversationStore.currentModel = newModel | `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) | | `desktop/src/components/ChatArea.tsx` | 聊天区域 UI | | `crates/zclaw-runtime/src/loop_runner.rs` | Rust 主聊天循环 | + +## 已知问题 + +- ⚠️ **B-CHAT-07: 混合域截断** — P2 Open。跨域消息时可能截断上下文 +- ✅ **SSE Token 统计为 0** — P2 已修复 (SseUsageCapture stream_done flag) +- ✅ **Tauri invoke 参数名 snake_case** — P1 已修复 (commit f6c5dd2) +- ✅ **Provider Key 解密致 relay 500** — P1 已修复 (commit b69dc61) diff --git a/wiki/data-model.md b/wiki/data-model.md new file mode 100644 index 0000000..f3b9040 --- /dev/null +++ b/wiki/data-model.md @@ -0,0 +1,180 @@ +--- +title: 数据模型 +updated: 2026-04-21 +status: active +tags: [module, database, schema] +--- + +# 数据模型 + +> 从 [[index]] 导航。关联模块: [[saas]] [[memory]] + +## 设计思想 + +**双存储架构: PostgreSQL (SaaS 多租户) + SQLite (本地单用户)** + +- PostgreSQL: SaaS 后端，42 表，42 CREATE TABLE，支持多用户/多 Agent/计费/知识库 +- SQLite: 本地桌面端，记忆存储 + 会话持久化 + FTS5 全文索引 +- 两者通过 SaaS relay + 配置同步实现数据桥接 + +## 功能清单 + +| 功能 | 描述 | 存储层 | 状态 | +|------|------|--------|------| +| 用户管理 | 账户 CRUD + 角色权限 | PostgreSQL | ✅ | +| 认证数据 | JWT + 密码 + TOTP | PostgreSQL | ✅ | +| 计费系统 | 订阅/支付/发票/配额 | PostgreSQL | ✅ | +| 知识库 | 分类/条目/向量/结构化 | PostgreSQL | ✅ | +| 模型管理 | Provider/模型/Key 池 | PostgreSQL | ✅ | +| Agent 配置 | 模板/分配/行业 | PostgreSQL | ✅ | +| 本地会话 | 会话/消息持久化 | SQLite | ✅ | +| 本地记忆 | 记忆 CRUD + FTS5 搜索 | SQLite | ✅ | +| 用户画像 | 结构化偏好/兴趣 | SQLite | ✅ | +| 轨迹记录 | 工具调用链 + 压缩摘要 | SQLite | ✅ | + +## 代码逻辑 + +### PostgreSQL (SaaS) — 42 表 + +**迁移文件**: `crates/zclaw-saas/migrations/` (21 up + 17 down) + +#### 认证与账户域 (5 表) + +| 表 | 说明 | 关键关系 | +|----|------|---------| +| `accounts` | 用户账户 (邮箱/密码/pwv/角色) | → api_tokens, operation_logs, subscriptions | +| `api_tokens` | API 访问令牌 | FK → accounts | +| `roles` | 角色定义 | — | +| `permission_templates` | 权限模板 | — | +| `refresh_tokens` | JWT 刷新令牌 (单次使用) | FK → accounts | + +#### Provider 与模型域 (6 表) + +| 表 | 说明 | 关键关系 | +|----|------|---------| +| `providers` | LLM Provider 配置 | → models, provider_keys | +| `models` | 模型定义 (白名单) | FK → providers | +| `provider_keys` | 加密 API Key 池 | FK → providers, accounts | +| `key_usage_window` | Key RPM/TPM 滑动窗口 | — | +| `model_groups` | 模型组 (故障转移) | → model_group_members | +| `model_group_members` | 组成员 | FK → model_groups, providers | + +#### 计费域 (5 表) + +| 表 | 说明 | 关键关系 | +|----|------|---------| +| `billing_plans` | 计费计划目录 | → subscriptions | +| `billing_subscriptions` | 用户订阅 | FK → accounts, billing_plans | +| `billing_invoices` | 发票 | FK → accounts, subscriptions, plans | +| `billing_payments` | 支付记录 | FK → billing_invoices, accounts | +| `billing_usage_quotas` | 用量配额 | FK → accounts, billing_plans | + +#### 知识库域 (7 表) + +| 表 | 说明 | 关键关系 | +|----|------|---------| +| `knowledge_categories` | 分类 (自引用 parent_id) | → knowledge_items | +| `knowledge_items` | 知识条目 | FK → categories, accounts | +| `knowledge_chunks` | 向量分块 (pgvector) | FK → knowledge_items | +| `knowledge_versions` | 版本历史 | FK → items, chunks, accounts | +| `knowledge_usage` | 使用统计 | FK → knowledge_items | +| `structured_sources` | 结构化数据源 | FK → accounts | +| `structured_rows` | 结构化行数据 | FK → structured_sources | + +#### 其他域 (19 表) + +| 域 | 表 | 说明 | +|----|----|------| +| API & Relay | `account_api_keys`, `usage_records`, `relay_tasks` | API Key/用量/异步任务 | +| 配置 | `config_items`, `config_sync_log` | KV 配置/同步日志 | +| Prompt | `prompt_templates`, `prompt_versions`, `prompt_sync_status` | 模板/版本/同步 | +| Agent | `agent_templates` | Agent 模板配置 | +| 设备 | `devices` | 设备管理 | +| 遥测 | `operation_logs`, `telemetry_reports`, `saas_schema_version` | 操作日志/统计/版本 | +| 调度 | `scheduled_tasks` | 定时任务 | +| 限流 | `rate_limit_events` | 限流事件日志 | +| Webhook | `webhook_subscriptions`, `webhook_deliveries` | Webhook 订阅/投递 | +| 行业 | `industries`, `account_industries` | 行业配置/账户关联 | + +### SQLite 本地存储 + +**zclaw-memory** (`crates/zclaw-memory/src/schema.rs`): + +| 表 | 说明 | 版本 | +|----|------|------| +| `agents` | Agent 定义 | v1 | +| `sessions` | 聊天会话 | v1, FK → agents | +| `messages` | 会话消息 | v1, FK → sessions | +| `kv_store` | Agent KV 存储 | v1, FK → agents | +| `facts` | 提取的事实 | v2, FK → agents | +| `user_profiles` | 用户画像 | v2 | +| `trajectory_events` | 工具调用链事件 | v3 | +| `compressed_trajectories` | 压缩轨迹摘要 | v3 | +| `hand_runs` | Hand 执行追踪 | v1 | +| `schema_version` | 迁移版本 | v1 | + +**zclaw-growth** (`crates/zclaw-growth/src/storage/sqlite.rs`): + +| 表 | 说明 | +|----|------| +| `memories` | 记忆条目 (uri, memory_type, content, keywords, importance, access_count) | +| `metadata` | KV 元数据 | + +**FTS5 虚拟表**: + +| 虚拟表 | 定义 | 分词器 | +|--------|------|--------| +| `memories_fts` | `fts5(uri, content, keywords)` | `trigram` (CJK 支持) | + +> FTS5 使用 `trigram` 分词器（从 `unicode61` 迁移）支持中文/日文/韩文。CJK 查询零结果时 fallback 到 LIKE 搜索。 + +## 数据流 + +``` +桌面端聊天 + → SQLite: sessions + messages (本地持久化) + → SaaS Relay: relay_tasks (异步任务追踪) + → PostgreSQL: usage_records (用量记录) + +记忆管道 + → SQLite: memories + memories_fts (FTS5 全文索引) + → SQLite: facts + user_profiles (结构化提取) + → PostgreSQL: knowledge_chunks (pgvector 向量, embedding deferred) + +计费闭环 + → PostgreSQL: billing_usage_quotas (实时递增) + → PostgreSQL: billing_subscriptions → invoices → payments + → Worker: aggregate_usage (聚合器调度) +``` + +## 测试链路 + +| 功能 | 测试文件 | 覆盖状态 | +|------|---------|---------| +| 全模块 | `crates/zclaw-saas/tests/` (17 文件) | ✅ | +| SQL 迁移 | `crates/zclaw-saas/migrations/` (21 up) | ✅ 启动时自动执行 | +| 本地存储 | `crates/zclaw-memory/src/store.rs` (20 tests) | ✅ | +| 用户画像 | `crates/zclaw-memory/src/user_profile_store.rs` (20 tests) | ✅ | +| 轨迹存储 | `crates/zclaw-memory/src/trajectory_store.rs` (9 tests) | ✅ | +| 记忆存储 | `crates/zclaw-growth/src/storage/sqlite.rs` (6 tests) | ✅ | + +## 关联模块 + +- [[saas]] — PostgreSQL 由 SaaS 后端管理 +- [[memory]] — SQLite 本地记忆存储 + FTS5 +- [[routing]] — relay_tasks 异步任务追踪 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-saas/migrations/` | 21 up SQL 迁移 (42 CREATE TABLE) | +| `crates/zclaw-saas/src/models/` | 数据模型 struct 定义 | +| `crates/zclaw-memory/src/schema.rs` | SQLite schema 定义 | +| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 存储 | +| `docker-compose.yml` | PostgreSQL 容器配置 | + +## 已知问题 + +- ⚠️ **pgvector embedding 生成未实现** — 索引就绪，`generate_embedding.rs` Worker 逻辑 deferred +- ⚠️ **FTS5 CJK 零结果** — trigram 分词器已启用，极短查询可能仍 fallback 到 LIKE diff --git a/wiki/feature-map.md b/wiki/feature-map.md new file mode 100644 index 0000000..1b60936 --- /dev/null +++ b/wiki/feature-map.md @@ -0,0 +1,408 @@ +--- +title: 功能链路映射 +updated: 2026-04-21 +status: active +tags: [reference, feature-map, testing] +--- + +# 功能链路映射 + +> 从 [[index]] 导航。每条链路追踪一个功能从前端到后端的完整路径 + 测试覆盖。 +> 排序: 用户流程优先级 — 对话 > Agent > Hands > 记忆 > SaaS > 管家 > Pipeline > 配置 > 安全 + +--- + +## 对话 (5 条) + +### F-01: 发送消息 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天输入框 → streamStore.sendMessage(content) | +| 前端关键文件 | streamStore.ts, conversationStore.ts, kernel-chat.ts | +| 通信层 | getClient() → KernelClient (Tauri) / SaaSRelay (SSE) | +| Tauri 命令 | `agent_chat_stream` → desktop/src-tauri/src/kernel_commands/chat.rs | +| 中间件链 | ButlerRouter@80 → ... → Memory@150 → ... → Guardrail@400 → ... | +| Rust 核心 | kernel → runtime → loop_runner → LLM Driver | +| SaaS API | POST /api/v1/relay/chat/completions | +| 流式返回 | LLM → runtime → Tauri Event (stream:chunk) → streamStore.onDelta → UI | +| 测试文件 | tests/desktop/chatStore.test.ts (11), tests/seam/chat-seam.test.ts (8) | +| 测试状态 | ✅ 19/19 PASS | + +### F-02: 流式响应接收 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天面板实时显示文字流 | +| 前端关键文件 | streamStore.ts (onDelta/onThinkingDelta/onTool/onComplete) | +| 通信层 | Tauri Event emit → streamStore 回调 | +| 流式事件 | Delta / ThinkingDelta / ToolStart / ToolEnd / HandStart / HandEnd / Complete / Error | +| 超时守护 | kernel-chat.ts:76 — 5 分钟超时防挂起 | +| 测试文件 | tests/desktop/chatStore.test.ts (stream correlation via runId) | +| 测试状态 | ✅ PASS | + +### F-03: 模型切换 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天面板模型选择器 | +| 前端关键文件 | conversationStore.ts (currentModel), connectionStore.ts | +| 决策链 | UI 选择 → conversationStore.currentModel = newModel → 下次 sendMessage 生效 | +| SaaS 验证 | relay 白名单精确匹配 model_id (无别名解析) | +| 降级 | SaaS 不可达 → 降级到本地 Kernel + 用户自定义模型 | +| 测试文件 | tests/desktop/chatStore.test.ts | +| 测试状态 | ✅ PASS | + +### F-04: 上下文管理 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 跨会话恢复对话历史 | +| 前端关键文件 | conversationStore.ts (sessionKey), messageStore.ts (IndexedDB) | +| 持久化 | IndexedDB 消息存储 + SQLite sessions/messages | +| Tauri 命令 | kernel_init 时传入 session_id | +| 测试文件 | tests/desktop/chatStore.test.ts (session isolation) | +| 测试状态 | ✅ PASS | + +### F-05: 取消流式 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天面板停止按钮 | +| 前端关键文件 | streamStore.ts → cancelStream() | +| Tauri 命令 | `cancel_stream` → kernel_commands/chat.rs (原子标志位) | +| 机制 | AtomicBool cancel flag → 流式任务检测 → emit Error 事件 | +| 测试状态 | ✅ (chatStore test 覆盖) | + +--- + +## 分身 / Agent (4 条) + +### F-06: 创建 Agent + +| 维度 | 内容 | +|------|------| +| 用户入口 | 侧边栏 → 新建 Agent | +| 前端关键文件 | agentStore.ts | +| Tauri 命令 | `agent_create` → kernel_commands/agent.rs | +| Rust 核心 | kernel → zclaw-memory → SQLite agents 表 | +| 测试文件 | tests/desktop/chatStore.test.ts (agent isolation) | +| 测试状态 | ✅ PASS | + +### F-07: 切换 Agent + +| 维度 | 内容 | +|------|------| +| 用户入口 | 侧边栏 Agent 列表点击切换 | +| 前端关键文件 | agentStore.ts (currentAgent), conversationStore.ts | +| 机制 | 切换 agent_id → 新 session_key → 下次 sendMessage 使用新 Agent | +| 测试状态 | ✅ PASS | + +### F-08: 配置 Agent + +| 维度 | 内容 | +|------|------| +| 用户入口 | Agent 设置面板 (名称/模型/系统提示) | +| 前端关键文件 | agentStore.ts | +| Tauri 命令 | `agent_update` → kernel_commands/agent.rs | +| 存储 | config.toml (本地) / agent_templates 表 (SaaS) | +| 测试状态 | ✅ | + +### F-09: 删除 Agent + +| 维度 | 内容 | +|------|------| +| 用户入口 | Agent 列表 → 删除确认 | +| 前端关键文件 | agentStore.ts | +| Tauri 命令 | `agent_delete` → kernel_commands/agent.rs | +| 级联 | SQLite agents + sessions + messages 级联删除 | +| 测试状态 | ✅ | + +--- + +## 自主能力 / Hands (4 条) + +### F-10: 触发 Hand + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天中 LLM 决定调用 Hand / 自动化面板手动触发 | +| 前端关键文件 | handStore.ts, streamStore.ts (onHand 回调) | +| Tauri 命令 | `hand_execute` → kernel_commands/hand.rs → HandRegistry | +| Rust 核心 | zclaw-hands → 具体 Hand 实现 (Browser/Collector/Twitter/Quiz/...) | +| 流式事件 | HandStart / HandEnd (via agent_chat_stream) | +| 测试文件 | crates/zclaw-hands/src/hands/ (117 tests) | +| 测试状态 | ✅ 117/117 PASS | + +### F-11: Hand 审批 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 审批弹窗 (needs_approval 状态) | +| 前端关键文件 | handStore.ts (approval UI) | +| Tauri 命令 | `hand_approve` / `hand_cancel` → kernel_commands/hand.rs | +| 机制 | Hand TOML 配置 needs_approval=true → 执行前暂停等审批 | +| 测试状态 | ✅ | + +### F-12: Hand 结果查看 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天面板中 Hand 结果展示 | +| 前端关键文件 | handStore.ts | +| Tauri 命令 | `hand_run_status` / `hand_run_list` | +| 机制 | Hand 执行完成 → HandEnd 事件 → UI 展示结果 | +| 测试状态 | ✅ | + +### F-13: Browser 自动化 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天中触发浏览器操作 | +| 前端关键文件 | browserHandStore.ts | +| Tauri 命令 | 23 个 browser_* 命令 → desktop/src-tauri/src/browser/commands.rs | +| 依赖 | WebDriver (需要外部 WebDriver 进程) | +| 测试文件 | crates/zclaw-hands/src/hands/browser.rs (11 tests) | +| 测试状态 | ✅ 11/11 PASS | + +--- + +## 记忆 (3 条) + +### F-14: 记忆搜索 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 语义记忆 / 管家面板记忆搜索 | +| 前端关键文件 | memoryGraphStore.ts | +| Tauri 命令 | `memory_search` → memory_commands.rs → FTS5 + TF-IDF | +| Rust 核心 | zclaw-growth → retriever.rs → QueryAnalyzer → SemanticScorer | +| 查询类型 | Preference / Knowledge / Experience / Code / General | +| 测试文件 | crates/zclaw-growth/ (181 tests), zclaw-memory/ (54 tests) | +| 测试状态 | ✅ 235/235 PASS | + +### F-15: 记忆自动注入 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 无感 — 聊天时自动触发 | +| 触发链 | Memory 中间件@150 → 检测对话内容 → 提取记忆 | +| Tauri 命令 | `extract_and_store_memories` → memory/extractor.rs | +| 注入链 | PromptInjector.inject(system_prompt, memories) → token 预算控制 | +| 测试文件 | crates/zclaw-growth/src/injector.rs (9 tests) | +| 测试状态 | ✅ PASS | + +### F-16: 记忆手动管理 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 语义记忆 — 查看/删除/导出/导入 | +| 前端关键文件 | memoryGraphStore.ts | +| Tauri 命令 | `memory_stats` / `memory_export` / `memory_import` / `memory_delete_all` | +| 测试文件 | crates/zclaw-growth/src/storage/sqlite.rs (6 tests) | +| 测试状态 | ✅ PASS | + +--- + +## SaaS (6 条) + +### F-17: 用户注册 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 登录页 > 注册 | +| 前端关键文件 | saasStore (auth.ts) | +| SaaS API | POST /api/v1/auth/register (3次/小时 IP 限流) | +| Rust 核心 | auth/handlers.rs → Argon2id + OsRg 盐 + 邮箱 RFC 5322 校验 | +| 存储 | PostgreSQL accounts 表 | +| 测试文件 | crates/zclaw-saas/tests/auth_test.rs | +| 测试状态 | ✅ PASS | + +### F-18: 用户登录 + +| 维度 | 内容 | +|------|------| +| 用户入口 | SaaS 平台登录页 | +| 前端关键文件 | saasStore (auth.ts) | +| SaaS API | POST /api/v1/auth/login (5次/分钟 IP 限流 + 持久化) | +| 安全机制 | 账户锁定 (5 次失败 → 15 分钟) + JWT pwv 机制 | +| Token 存储 | Tauri: OS keyring / 浏览器: HttpOnly Cookie | +| 测试文件 | crates/zclaw-saas/tests/auth_test.rs, auth_security_test.rs | +| 测试状态 | ✅ PASS | + +### F-19: Token 刷新 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 无感 — access token 过期时自动触发 | +| 前端关键文件 | saasStore (auth.ts) | +| SaaS API | POST /api/v1/auth/refresh | +| 安全机制 | 单次使用 refresh token → 旧 token 撤销到 DB → 签发新对 | +| 测试状态 | ✅ PASS | + +### F-20: 订阅管理 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > SaaS 平台 / Admin 后台 | +| 前端关键文件 | saasStore (billing.ts) | +| SaaS API | GET /billing/subscription, GET /billing/plans | +| 数据表 | billing_plans, billing_subscriptions | +| 测试文件 | crates/zclaw-saas/tests/billing_test.rs | +| 测试状态 | ✅ PASS | + +### F-21: 支付/计费 + +| 维度 | 内容 | +|------|------| +| 用户入口 | SaaS 平台支付页 / Admin 管理计费 | +| 前端关键文件 | saasStore (billing.ts) | +| SaaS API | POST /billing/payments, GET /billing/invoices/:id/pdf | +| 支付渠道 | Alipay + WeChat (mock 路由用于开发) | +| 回调 | POST /billing/callback/:method | +| 实时配额 | billing_usage_quotas 递增 + aggregate_usage Worker | +| 测试文件 | crates/zclaw-saas/tests/billing_test.rs | +| 测试状态 | ✅ PASS | + +### F-22: Admin 后台管理 + +| 维度 | 内容 | +|------|------| +| 用户入口 | Admin V2 后台 (admin-v2/) | +| 前端关键文件 | admin-v2/src/pages/ (17 页面) | +| SaaS API | 118 个路由覆盖 13 个模块 | +| 认证 | Admin HttpOnly Cookie + admin_guard_middleware 权限验证 | +| 测试文件 | admin-v2/tests/pages/ (17 文件) + crates/zclaw-saas/tests/ (17 文件) | +| 测试状态 | ✅ PASS | + +--- + +## 管家 (3 条) + +### F-23: 简洁/专业模式切换 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 聊天面板右上角模式切换 | +| 前端关键文件 | uiModeStore.ts, SimpleSidebar.tsx | +| 机制 | simple 模式隐藏高级功能 / professional 模式展示完整功能 | +| 测试状态 | ✅ | + +### F-24: 行业配置 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 管家面板 > 行业选择 / Admin > 行业配置 | +| 前端关键文件 | industryStore.ts, ButlerPanel.tsx | +| SaaS API | GET /industries, GET /accounts/me/industries, PUT /accounts/:id/industries | +| 内置行业 | 4 个 (医疗/教育/金融/法律) | +| 中间件 | ButlerRouter@80 动态行业关键词匹配 | +| 测试状态 | ✅ 4 行业已验证 | + +### F-25: 痛点积累 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 无感 — 聊天中自动提取 | +| 触发链 | ButlerRouter → pain_aggregator → pain_storage (双写内存+SQLite) | +| Tauri 命令 | `butler_record_pain_point`, `butler_list_pain_points` | +| 方案生成 | 痛点积累到阈值 → `butler_generate_solution` | +| 测试文件 | intelligence/pain_aggregator.rs (9), pain_storage.rs (11), solution_generator.rs (5) | +| 测试状态 | ✅ 25/25 PASS | + +--- + +## Pipeline (3 条) + +### F-26: 选择模板 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 工作流面板 → 模板列表 | +| 前端关键文件 | workflowStore.ts, pipeline-client.ts | +| Tauri 命令 | pipeline discovery 命令 (8 个已接通前端) | +| 模板来源 | pipelines/ 目录 18 个 YAML (8 行业目录) | +| 测试文件 | crates/zclaw-pipeline/src/parser_v2.rs (11 tests) | +| 测试状态 | ✅ 11/11 PASS | + +### F-27: 配置参数 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 工作流面板 → 参数填写 | +| 前端关键文件 | workflowStore.ts | +| Tauri 命令 | pipeline discovery 配置命令 | +| YAML 结构 | 步骤 + 依赖 + 输入/输出定义 | +| 测试文件 | crates/zclaw-pipeline/src/parser.rs (5 tests) | +| 测试状态 | ✅ PASS | + +### F-28: 执行工作流 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 工作流面板 → 执行按钮 | +| Tauri 命令 | `orchestration_execute` (@reserved, 无前端 UI) | +| Rust 核心 | zclaw-pipeline → executor.rs → DAG 拓扑排序 + 并行执行 | +| 测试文件 | crates/zclaw-pipeline/src/executor.rs (2 tests) | +| 测试状态 | ✅ PASS | + +--- + +## 配置 (3 条) + +### F-29: 模型设置 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 模型与 API | +| 前端关键文件 | configStore.ts, settingsStore | +| 机制 | UI → config.toml 写入 → Kernel 热重载 | +| 8 Provider | Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local | +| 测试状态 | ✅ | + +### F-30: 工作区配置 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 工作区 | +| 前端关键文件 | configStore.ts | +| 持久化 | config.toml + environment variable 插值 ${VAR_NAME} | +| 测试状态 | ✅ | + +### F-31: 数据隐私 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 数据与隐私 | +| 前端关键文件 | configStore.ts | +| 功能 | 清除对话历史 / 导出数据 / 记忆管理 | +| Tauri 命令 | `memory_delete_all`, `memory_export` | +| 测试状态 | ✅ | + +--- + +## 安全 (2 条) + +### F-32: JWT 认证 + +| 维度 | 内容 | +|------|------| +| 用户入口 | 登录时自动触发 | +| 前端关键文件 | saasStore (auth.ts) → secure_storage.ts | +| SaaS API | POST /auth/login → JWT 签发 → Cookie 设置 | +| 验证链 | auth_middleware → JWT 解码 → Claims.pwv vs DB.pwv 比对 | +| 存储 | Tauri: OS keyring (DPAPI/Keychain/Secret Service) | +| 刷新 | POST /auth/refresh → 单次使用 rotation | +| 测试文件 | crates/zclaw-saas/tests/auth_test.rs, auth_security_test.rs | +| 测试状态 | ✅ PASS | + +### F-33: TOTP 2FA + +| 维度 | 内容 | +|------|------| +| 用户入口 | 设置 > 安全存储 > 2FA 设置 | +| 前端关键文件 | securityStore.ts | +| SaaS API | POST /auth/totp/setup → QR 码 / verify → 激活 / disable → 禁用 | +| 加密 | TOTP 密钥 AES-256-GCM 加密存储, 独立 ZCLAW_TOTP_ENCRYPTION_KEY | +| 测试文件 | crates/zclaw-saas/src/auth/totp.rs (inline tests) | +| 测试状态 | ✅ PASS | diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md index f94e1fa..7492fc5 100644 --- a/wiki/hands-skills.md +++ b/wiki/hands-skills.md @@ -1,6 +1,6 @@ --- title: Hands + Skills + MCP -updated: 2026-04-19 +updated: 2026-04-21 status: active tags: [module, hands, skills, mcp] --- @@ -191,6 +191,39 @@ LLM 对话调用: MCP 工具在 ToolRegistry 中使用限定名 `service_name.tool_name` 避免冲突。 例如：`filesystem.read_file`, `database.query`。 +## API 接口 + +### Hand Tauri 命令 (`desktop/src-tauri/src/kernel_commands/hand.rs`) + +| 命令 | 状态 | 说明 | +|------|------|------| +| `hand_list` | @connected | 列出可用 Hands | +| `hand_execute` | @connected | 执行 Hand | +| `hand_approve` | @connected | 审批 Hand 执行 | +| `hand_cancel` | @connected | 取消执行 | +| `hand_get` | @connected | 获取 Hand 详情 | +| `hand_run_status` | @connected | 运行状态查询 | +| `hand_run_list` | @connected | 运行列表 | +| `hand_run_cancel` | @reserved | 取消运行 (无前端 UI) | + +## 测试链路 + +| 功能 | Crate | 测试数 | 覆盖状态 | +|------|-------|--------|---------| +| Browser | zclaw-hands | 11 | ✅ | +| Clip (视频) | zclaw-hands | 32 | ✅ | +| Collector | zclaw-hands | 9 | ✅ | +| DailyReport | zclaw-hands | 5 | ✅ | +| Quiz | zclaw-hands | 5 | ✅ | +| Researcher | zclaw-hands | 25 | ✅ | +| Twitter | zclaw-hands | 30 | ✅ | +| **Hands 小计** | | **117** | | +| 语义路由 | zclaw-skills | 7 | ✅ | +| WASM Runner | zclaw-skills | 2 | ✅ | +| 编排 (7 文件) | zclaw-skills | 17 | ✅ | +| **Skills 小计** | | **26** | | +| **合计** | | **143** | | + ## 关联模块 - [[chat]] — 消息流中可能触发 Hand/Skill @@ -215,4 +248,10 @@ MCP 工具在 ToolRegistry 中使用限定名 `service_name.tool_name` 避免冲 | `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 | | `desktop/src/lib/mcp-client.ts` | 前端 MCP 客户端 | | `desktop/src-tauri/src/kernel_commands/mcp.rs` | MCP Tauri 命令 (4) + Kernel 桥接 | + +## 已知问题 + +- ✅ **skill_execute 反序列化崩溃** — SEC2-P0-01 已于 04-02 修复 +- ✅ **Hands E2E 通过率 70%** — 10 Hand 全部启用，审批机制正常 +- ⚠️ **hand.rs TODO** — P2-03: tool_count/metric_count 待从实际 Hand 实例填充 | `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) | diff --git a/wiki/index.md b/wiki/index.md index c4f450f..04257bf 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,6 +1,6 @@ --- title: ZCLAW 项目知识库 -updated: 2026-04-19 +updated: 2026-04-21 status: active --- @@ -45,27 +45,78 @@ status: active | TODO/FIXME | 前端 1 + Rust 1 = 2 | `grep TODO/FIXME` (2026-04-19 验证) | | dead_code | 0 个 | `grep '#\[dead_code\]'` (2026-04-19 验证) | +## 用户功能清单 + +> ZCLAW 能做什么？按用户视角组织，快速定位功能所属模块。 + +| 类别 | 功能 | 用户入口 | Wiki 详情 | +|------|------|----------|-----------| +| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] | +| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] | +| 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] | +| 记忆 | 搜索历史、自动注入上下文 | 设置 > 语义记忆 | [[memory]] | +| 配置 | 模型/API/工作区/安全存储 | 设置面板 (19 页) | [[development]] | +| SaaS | 登录注册、订阅计费、Admin 管理 | SaaS 平台 / Admin 后台 | [[saas]] | +| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] | +| Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] | +| 安全 | JWT 认证、TOTP 2FA、操作审计 | 设置 > 安全存储 | [[security]] | +| 数据 | PostgreSQL (SaaS 42表) + SQLite/FTS5 (本地记忆) | — | [[data-model]] | + +## 跨模块数据流全景图 + +> 一个请求的完整生命周期（SaaS relay 主路径）。详细流程见 [[routing]] 和 [[chat]]。 + +``` +用户输入 + ↓ +React 组件 (ChatPanel.tsx) + ↓ +Zustand Store (chatStore.sendMessage) + ↓ +getClient() 路由决策 ──→ SaaS Relay (主路径) ──→ 本地 Kernel (降级) + ↓ ↓ ↓ +Tauri invoke SSE 连接 直接调用 + ↓ ↓ ↓ +Kernel Runtime SaaS → Token Pool Runtime + ↓ → LLM Provider ↓ +Middleware Chain (15层) ↓ Middleware Chain + ↓ 流式 SSE 返回 ↓ +LLM Driver ←─────────────────┘ LLM Driver + ↓ ↓ +Tauri Event emit Tauri Event emit + ↓ ↓ +streamStore.onDelta ←────────────────────────────┘ + ↓ +UI 更新 (消息气泡渲染) +``` + ## 模块导航树 ``` ZCLAW -├── [[routing]] 客户端路由 — 5分支+降级，SaaS Relay是主路径 -│ └── [[chat]] 聊天系统 — 3种ChatStream，Store拆为4+1 +├── [[routing]] 客户端路由 — 连接断了吗？数据走哪条路？看这里 +│ └── [[chat]] 聊天系统 — 消息怎么发？流式怎么接？Store 怎么拆？ │ -├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢 +├── [[saas]] SaaS平台 — 用户/计费/Admin API 都在这里 │ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换 │ ├── 计费 配额实时递增 + Alipay/WeChat │ └── Admin V2 17页管理后台 │ -├── [[butler]] 管家模式 — 默认交互范式，语义路由+冷启动+痛点 +├── [[butler]] 管家模式 — 用户看到什么？行业怎么配？痛点怎么积？ │ -├── [[middleware]] 中间件链 — 15层runtime + 10层SaaS HTTP +├── [[middleware]] 中间件链 — 请求经过哪些处理？优先级怎么排？ │ -├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入+进化引擎 +├── [[memory]] 记忆管道 — 对话怎么变记忆？怎么检索？怎么注入？ │ -├── [[hands-skills]] Hands(7注册) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议 +├── [[hands-skills]] Hands(7注册) + Skills(75) — Agent能做什么动作？懂什么技能？ │ -├── [[pipeline]] Pipeline DSL — YAML+DAG执行器+18模板 +├── [[pipeline]] Pipeline DSL — 工作流怎么配？DAG怎么跑？有哪些模板？ +│ +├── [[security]] 安全体系 — JWT/Cookie/TOTP/CSP/限流/加密 +│ +├── [[data-model]] 数据模型 — 42表PostgreSQL + FTS5本地存储 +│ +├── [[feature-map]] 功能链路映射 — 每个功能从前端到后端的完整路径+测试 │ ├── [[development]] 开发规范 — 闭环工作法/验证命令/提交规范 ├── [[known-issues]] 已知问题 — P0/P1已修复，P2待处理 diff --git a/wiki/log.md b/wiki/log.md index 3af231c..f148673 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -496,3 +496,17 @@ Phase 5 — 主动行为激活 (3 files, 152 insertions): - P1: AgentInfo 扩展 UserProfile 桥接; 反思阈值降低 5→3; 反思 state restore peek+pop 竞态修复 - P2: 演化历史可展开差异视图; 管家 Tab 条件 header + 空状态引导 - 文件: 14 个 (Rust 5 + TS 9), 10 次提交 + +## 2026-04-21: Wiki 系统性更新 + +**变更**: wiki 三层架构增强 — L0 速览 + L1 模块标准化 + L2 功能链路映射 + +- L0: index.md 增强 — 用户功能清单(10类) + 跨模块数据流全景图 + 导航树增强(含3新页面) +- L1: 8 个模块页标准化 — 新增功能清单/API接口/测试链路/已知问题标准章节 + - routing.md (252→326), chat.md (101→157), saas.md (153→230), memory.md (182→333) + - butler.md (137→179), middleware.md (121→159), hands-skills.md (218→257), pipeline.md (111→156) +- L1: 新增 security.md (157行) + data-model.md (180行) +- L2: 新增 feature-map.md (408行, 33条功能链路, 覆盖对话/Agent/Hands/记忆/SaaS/管家/Pipeline/配置/安全) +- 维护: CLAUDE.md §8.3 wiki 触发规则扩展 (6→9条规则) +- 设计文档: docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md +- 文件: 11 个修改 + 3 个新增, 总计 ~1400 行新增内容 diff --git a/wiki/memory.md b/wiki/memory.md index d8c45fe..cd80a48 100644 --- a/wiki/memory.md +++ b/wiki/memory.md @@ -1,6 +1,6 @@ --- title: 记忆管道 -updated: 2026-04-19 +updated: 2026-04-21 status: active tags: [module, memory, growth] --- @@ -19,6 +19,23 @@ tags: [module, memory, growth] 3. **Token 预算控制** — 注入 system prompt 时有 token 上限，防止溢出 4. **EmbeddingClient trait 已预留** — 接口已写，激活即可升级到向量搜索 +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| 记忆提取 | LLM 从对话中提取偏好/知识/经验 | extractor.rs | ✅ | +| FTS5 全文检索 | SQLite FTS5 + TF-IDF 权重搜索 | storage/sqlite.rs | ✅ | +| 语义检索 | 意图分类 + CJK 关键词 + 混合评分 | retriever.rs, retrieval/query.rs | ✅ | +| Prompt 注入 | token 预算控制 + 结构化上下文注入 | injector.rs | ✅ | +| 经验管理 | pain→solution→outcome CRUD | experience_store.rs | ✅ | +| 用户画像 | 结构化偏好/兴趣/能力管理 | profile_updater.rs | ✅ | +| 进化引擎 | 行为模式检测 → 技能/工作流建议 | evolution_engine.rs | ✅ | +| 质量门控 | 长度/标题/置信度/去重校验 | quality_gate.rs | ✅ | +| 自动技能生成 | 从模式生成 SkillManifest | skill_generator.rs | ✅ | +| 上下文压缩 | 超长对话压缩摘要 | summarizer.rs | ✅ | +| 嵌入向量 | EmbeddingClient trait + NoOp 默认 | retrieval/semantic.rs | 🚧 接口就绪 | +| SaaS pgvector | knowledge_chunks 向量索引 | saas/generate_embedding.rs | 🚧 索引就绪，生成未实现 | + ## 代码逻辑 ### 闭环数据流 @@ -149,13 +166,139 @@ crates/zclaw-growth/src/ ### 前端 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` +> 完整 API 接口详情见下方 `## API 接口` 章节。 -加上 `memory/extractor.rs` 的 2 个: `extract_session_memories, extract_and_store_memories` -和 `memory/context_builder.rs` 的 1 个: `estimate_content_tokens` +**Memory CRUD** (`desktop/src-tauri/src/memory_commands.rs`, 11 命令): -总计 16 个 memory 相关 Tauri 命令。 +| 命令 | 参数 | 说明 | +|------|------|------| +| `memory_store` | MemoryEntryInput | 存储记忆条目 | +| `memory_get` | id | 按 ID 获取 | +| `memory_search` | MemorySearchOptions | FTS5 + TF-IDF 搜索 | +| `memory_delete` | id | 删除单条 | +| `memory_delete_all` | agent_id | 删除 Agent 全部记忆 | +| `memory_stats` | — | 记忆统计 | +| `memory_export` | — | 导出全部 | +| `memory_import` | Vec\ | 批量导入 | +| `memory_build_context` | agent_id, query, max_tokens? | 构建检索增强上下文 | +| `memory_db_path` | — | SQLite 路径 | +| `memory_init` | — | 初始化 (no-op, Viking 自动初始化) | + +**VikingStorage** (`desktop/src-tauri/src/viking_commands.rs`, 14 命令): + +| 命令 | 说明 | +|------|------| +| `viking_add` / `viking_add_with_metadata` | 添加记忆 (URI scheme: agent://{id}/{type}/{category}) | +| `viking_find` | 语义/关键词搜索 | +| `viking_grep` | 正则搜索 | +| `viking_ls` / `viking_tree` / `viking_read` | 浏览/读取 | +| `viking_remove` | 删除 | +| `viking_inject_prompt` | 记忆注入 prompt | +| `viking_configure_embedding` | 配置 embedding provider | +| `viking_configure_summary_driver` | 配置摘要 LLM | +| `viking_store_with_summaries` | 自动摘要存储 | +| `viking_status` | 存储健康检查 | +| `viking_load_industry_keywords` | 加载行业关键词 | + +**Intelligence** (`desktop/src-tauri/src/intelligence/`, ~40 命令): + +| 模块 | 命令数 | 功能 | +|------|--------|------| +| identity.rs | 13 | Agent 身份/SOUL.md 管理 | +| heartbeat.rs | 11 | Heartbeat 引擎配置+记录 | +| pain_aggregator.rs | 5 | 痛点追踪+方案生成 | +| reflection.rs | 6 | 自我反思引擎 | +| compactor.rs | 4 | 上下文压缩 | +| health_snapshot.rs | 1 | 综合健康快照 | + +**记忆提取** (`desktop/src-tauri/src/memory/`, 3 命令): +`extract_session_memories`, `extract_and_store_memories`, `estimate_content_tokens` + +**Embedding** (`desktop/src-tauri/src/llm/`, 2 命令): +`embedding_create`, `embedding_providers` + +**总计 ~74 个** memory/growth/intelligence 相关 Tauri 命令。 + +## API 接口 + +### Memory CRUD (`desktop/src-tauri/src/memory_commands.rs`, 11 命令) + +| 命令 | 参数 | 说明 | +|------|------|------| +| `memory_store` | MemoryEntryInput | 存储记忆条目 | +| `memory_get` | id | 按 ID 获取 | +| `memory_search` | MemorySearchOptions | FTS5 + TF-IDF 搜索 | +| `memory_delete` | id | 删除单条 | +| `memory_delete_all` | agent_id | 删除 Agent 全部记忆 | +| `memory_stats` | — | 记忆统计 | +| `memory_export` | — | 导出全部 | +| `memory_import` | Vec\ | 批量导入 | +| `memory_build_context` | agent_id, query, max_tokens? | 构建检索增强上下文 | +| `memory_db_path` | — | SQLite 路径 | +| `memory_init` | — | 初始化 (no-op) | + +### VikingStorage (`desktop/src-tauri/src/viking_commands.rs`, 14 命令) + +| 命令 | 说明 | +|------|------| +| `viking_add` / `viking_add_with_metadata` | 添加记忆 (URI: agent://{id}/{type}/{category}) | +| `viking_find` | 语义/关键词搜索 | +| `viking_grep` | 正则搜索 | +| `viking_ls` / `viking_tree` / `viking_read` | 浏览/读取 | +| `viking_remove` | 删除 | +| `viking_inject_prompt` | 记忆注入 prompt | +| `viking_configure_embedding` | 配置 embedding provider | +| `viking_configure_summary_driver` | 配置摘要 LLM | +| `viking_store_with_summaries` | 自动摘要存储 | +| `viking_status` / `viking_load_industry_keywords` | 健康检查/行业关键词 | + +### Intelligence (`desktop/src-tauri/src/intelligence/`, ~40 命令) + +| 模块 | 命令数 | 功能 | +|------|--------|------| +| identity.rs | 13 | Agent 身份/SOUL.md 管理 | +| heartbeat.rs | 11 | Heartbeat 引擎配置+记录 | +| pain_aggregator.rs | 5 | 痛点追踪+方案生成 | +| reflection.rs | 6 | 自我反思引擎 | +| compactor.rs | 4 | 上下文压缩 | +| health_snapshot.rs | 1 | 综合健康快照 | + +### 记忆提取 + Embedding (5 命令) + +`extract_session_memories`, `extract_and_store_memories`, `estimate_content_tokens` (memory/) ++ `embedding_create`, `embedding_providers` (llm/) + +**总计 ~74 个** memory/growth/intelligence 相关 Tauri 命令。 + +## 测试链路 + +| 功能 | Crate | 测试文件 | 测试数 | 覆盖状态 | +|------|-------|---------|--------|---------| +| 记忆存储/检索 | zclaw-growth | storage/sqlite.rs | 6 | ✅ | +| 经验 CRUD | zclaw-growth | experience_store.rs | 12 | ✅ | +| 提取器 | zclaw-growth | extractor.rs | 8 | ✅ | +| 注入器 | zclaw-growth | injector.rs | 9 | ✅ | +| 质量门控 | zclaw-growth | quality_gate.rs | 9 | ✅ | +| 进化引擎 | zclaw-growth | evolution_engine.rs | 5 | ✅ | +| 技能生成 | zclaw-growth | skill_generator.rs | 6 | ✅ | +| 工作流编排 | zclaw-growth | workflow_composer.rs | 5 | ✅ | +| 意图分类+CJK | zclaw-growth | retrieval/query.rs | 11 | ✅ | +| 语义评分 | zclaw-growth | retrieval/semantic.rs | 9 | ✅ | +| Embedding | zclaw-growth | retrieval/cache.rs | 7 | ✅ | +| 模式聚合 | zclaw-growth | pattern_aggregator.rs | 6 | ✅ | +| 反馈收集 | zclaw-growth | feedback_collector.rs | 10 | ✅ | +| 摘要 | zclaw-growth | summarizer.rs | 5 | ✅ | +| 类型定义 | zclaw-growth | types.rs | 13 | ✅ | +| 进化闭环 | zclaw-growth | tests/evolution_loop_test.rs | 6 | ✅ | +| 经验链 | zclaw-growth | tests/experience_chain_test.rs | 6 | ✅ | +| 集成 | zclaw-growth | tests/integration_test.rs | 9 | ✅ | +| **zclaw-growth 小计** | | 29 文件 | **181** | | +| 记忆存储 | zclaw-memory | store.rs | 20 | ✅ | +| 用户画像 | zclaw-memory | user_profile_store.rs | 20 | ✅ | +| 轨迹记录 | zclaw-memory | trajectory_store.rs | 9 | ✅ | +| 事实提取 | zclaw-memory | fact.rs | 5 | ✅ | +| **zclaw-memory 小计** | | 4 文件 | **54** | | +| **合计** | | 33 文件 | **235** | | ## 关联模块 @@ -180,3 +323,11 @@ Memory 相关命令 (13 个，来自 `memory_commands.rs` + `memory/`): | `desktop/src/store/memoryGraphStore.ts` | 前端记忆 UI | | `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 | | `desktop/src-tauri/src/memory_commands.rs` | 13 个 memory CRUD 命令 | + +## 已知问题 + +- ✅ **记忆去重失败** — BUG-H2 已修复 (commit a504a40)。`viking_add` 同 URI+content 重复添加 +- ✅ **记忆非 Agent 隔离** — BUG-M3 已修复 (commit a504a40)。`viking_find` 返回所有 Agent 记忆 +- ✅ **跨会话注入断裂** — BUG-M5 已修复 (commit a504a40)。新会话报 "no conversation history found" +- ⚠️ **NoOpEmbeddingClient 是默认值** — 正常设计，用户配置 provider 后替换 +- ⚠️ **SaaS pgvector embedding 生成未实现** — 索引就绪，生成逻辑 deferred diff --git a/wiki/middleware.md b/wiki/middleware.md index 1f616bd..6c6e079 100644 --- a/wiki/middleware.md +++ b/wiki/middleware.md @@ -1,6 +1,6 @@ --- title: 中间件链 -updated: 2026-04-17 +updated: 2026-04-21 status: active tags: [module, middleware, runtime] --- @@ -104,6 +104,37 @@ trait AgentMiddleware: Send + Sync { `crates/zclaw-kernel/src/kernel/mod.rs:248-361` — `create_middleware_chain()` 方法，15 次 `chain.register()`（含 2 个条件注册: SkillIndex, Compaction）。注册顺序与执行顺序不同，chain 按 priority 升序排列后执行。 +## 功能清单 + +| 优先级 | 中间件 | 功能 | 状态 | +|--------|--------|------|------| +| @78 | EvolutionMiddleware | 进化引擎注入 | ✅ | +| @80 | ButlerRouter | 管家语义路由 + XML fencing | ✅ | +| @90 | DataMasking | PII 脱敏 | ✅ | +| @100 | Compaction | 上下文压缩 (条件注册) | ✅ | +| @150 | Memory | 记忆自动提取 + 注入 | ✅ | +| @180 | Title | 对话标题生成 | ✅ | +| @200 | SkillIndex | 技能索引注入 (条件注册) | ✅ | +| @300 | DanglingTool | 悬空工具清理 | ✅ | +| @350 | ToolError | 工具错误处理 | ✅ | +| @360 | ToolOutputGuard | 工具输出守卫 | ✅ | +| @400 | Guardrail | 安全护栏 | ✅ | +| @500 | LoopGuard | 循环检测 (防无限) | ✅ | +| @550 | SubagentLimit | 子代理数量限制 | ✅ | +| @650 | TrajectoryRecorder | 轨迹记录+压缩 | ✅ | +| @700 | TokenCalibration | Token 校准 | ✅ | + +## 测试链路 + +| 功能 | 测试文件 | 测试数 | 覆盖状态 | +|------|---------|--------|---------| +| 管家路由 | middleware/butler_router.rs | 12 | ✅ | +| 数据脱敏 | middleware/data_masking.rs | 9 | ✅ | +| 进化中间件 | middleware/evolution.rs | 4 | ✅ | +| 轨迹记录 | middleware/trajectory_recorder.rs | 4 | ✅ | +| 其余 11 层 | — | 0 | ⚠️ 无独立测试 | +| **合计** | 4/15 文件有测试 | **29** | | + ## 关联模块 - [[butler]] — ButlerRouter 是管家模式的核心 @@ -119,3 +150,10 @@ trait AgentMiddleware: Send + Sync { | `crates/zclaw-runtime/src/middleware/` | 15 个中间件实现 (15个 .rs 文件) | | `crates/zclaw-kernel/src/kernel/mod.rs:248-361` | 注册入口 | | `crates/zclaw-saas/src/main.rs` | SaaS HTTP 中间件注册 (10 层) | + +## 已知问题 + +- ✅ **TrajectoryRecorder 未注册** — V13-GAP-01 已修复 (在 @650 注册) +- ✅ **Admin 端点 404 而非 403** — admin_guard_middleware 已修复 +- ⚠️ **SkillIndex 条件注册** — 无技能时不注册，长期观察 +- ⚠️ **11/15 中间件无独立测试** — 仅 butler_router/data_masking/evolution/trajectory_recorder 有测试 diff --git a/wiki/pipeline.md b/wiki/pipeline.md index 00c853b..974eefb 100644 --- a/wiki/pipeline.md +++ b/wiki/pipeline.md @@ -1,6 +1,6 @@ --- title: Pipeline DSL -updated: 2026-04-17 +updated: 2026-04-21 status: active tags: [module, pipeline, dsl] --- @@ -95,6 +95,45 @@ Pipeline Tauri 命令 (12 个): `parser_v2.rs`: 11 tests — YAML 解析和 DAG 构建验证。 +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| YAML 解析 | v2 解析器，支持 DAG 依赖 | parser_v2.rs | ✅ | +| DAG 执行 | 拓扑排序 + 并行执行 | executor.rs | ✅ | +| 模板发现 | 18 模板 + 8 行业目录 | pipeline_commands/ | ✅ | +| 模型意图 | Pipeline 意图匹配 | intent.rs | ✅ | +| 状态管理 | Pipeline 运行状态 | state.rs | ✅ | +| 触发器 | 定时/事件触发 | trigger.rs | ✅ | +| 演示分析 | Pipeline 结果分析 | presentation/ | ✅ | + +## API 接口 + +### Tauri 命令 + +| 命令 | 状态 | 说明 | +|------|------|------| +| `orchestration_execute` | @reserved | 执行工作流 (无前端 UI) | +| `orchestration_validate` | @reserved | 验证工作流 (无前端 UI) | + +> 另有 12 个 pipeline discovery 命令在 `desktop/src-tauri/src/pipeline_commands/`，8 个已接通前端。 + +## 测试链路 + +| 功能 | 测试文件 | 测试数 | 覆盖状态 | +|------|---------|--------|---------| +| YAML 解析 v2 | parser_v2.rs | 11 | ✅ | +| DAG 执行 | executor.rs | 2 | ✅ | +| 意图匹配 | intent.rs | 5 | ✅ | +| 状态管理 | state.rs | 6 | ✅ | +| 触发器 | trigger.rs | 5 | ✅ | +| 类型 | types.rs + types_v2.rs | 4 | ✅ | +| 解析 v1 | parser.rs | 5 | ✅ | +| 引擎上下文 | engine/context.rs | 7 | ✅ | +| 引擎阶段 | engine/stage.rs | 1 | ✅ | +| 演示 | presentation/ (3文件) | 13 | ✅ | +| **合计** | 13 文件 | **59** | | + ## 关联模块 - [[hands-skills]] — Pipeline 步骤可能调用 Hand/Skill @@ -109,3 +148,9 @@ Pipeline Tauri 命令 (12 个): | `pipelines/` | 18 个 YAML 模板 (8 目录) | | `desktop/src/lib/pipeline-client.ts` | 前端 Pipeline 客户端 | | `desktop/src-tauri/src/pipeline_commands/` | 12 个 Tauri 命令 (4 文件) | + +## 已知问题 + +- ✅ **pipeline_create 反序列化失败** — BUG-L2 已修复 (04-17 回归) +- ⚠️ **Pipeline+Skill E2E 通过率 37.5%** — Tauri IPC 可用但参数格式问题 +- ⚠️ **Deepseek 中继任务卡 processing** — P3，Provider Key 禁用后已有任务不自动清理 diff --git a/wiki/routing.md b/wiki/routing.md index 4546b12..b296fb0 100644 --- a/wiki/routing.md +++ b/wiki/routing.md @@ -1,6 +1,6 @@ --- title: 客户端路由 -updated: 2026-04-19 +updated: 2026-04-21 status: active tags: [module, routing, connection] --- @@ -19,6 +19,20 @@ tags: [module, routing, connection] 3. **模型白名单** — Admin 配置哪些模型可用，`listModels()` 返回白名单 4. **降级保障** — SaaS 挂了自动切本地 Kernel，桌面端不变砖 +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| 连接管理 | 5 分支路由决策 + 自动降级 | connectionStore.ts | ✅ | +| SaaS Relay 中转 | Tauri 通过 SaaS Token Pool 中转 LLM | connectionStore.ts | ✅ | +| 浏览器模式 | SSE 连接 SaaS relay | saas-relay-client.ts | ✅ | +| 本地 Kernel | Tauri 内置 Kernel 直连 LLM | kernel-client.ts | ✅ | +| 外部 Gateway | WebSocket 独立进程 | gateway-client.ts | ✅ | +| Gateway 进程管理 | 启动/停止/重启/状态/诊断 | gateway/commands.rs | ✅ | +| 健康检查 | 端口检测 + 完整诊断 | health_check.rs | ✅ | +| 设备配对 | 设备审批 + 公钥交换 | gateway/commands.rs | ✅ | +| 模型路由 | 白名单验证 + fallback + 别名解析 | connectionStore.ts | ✅ | + ## 代码逻辑 ### 5 分支 + 降级决策树 @@ -232,6 +246,61 @@ chatStream() → saasClient.chatCompletion({ model: getModel() }) POST /api/v1/relay/chat/completions → SSE 流 ``` +## API 接口 + +### Tauri 命令 + +**Gateway 管理** (`desktop/src-tauri/src/gateway/commands.rs`): + +| 命令 | 参数 | 返回值 | 说明 | +|------|------|--------|------| +| `zclaw_status` | — | `LocalGatewayStatus` | Kernel 运行状态 | +| `zclaw_start` | — | `LocalGatewayStatus` | 启动 Kernel | +| `zclaw_stop` | — | `LocalGatewayStatus` | 停止 Kernel | +| `zclaw_restart` | — | `LocalGatewayStatus` | 重启 Kernel | +| `zclaw_local_auth` | — | `LocalGatewayAuth` | 获取本地认证 token | +| `zclaw_prepare_for_tauri` | — | `LocalGatewayPrepareResult` | 更新 Tauri allowed origins | +| `zclaw_approve_device_pairing` | device_id, public_key_base64, url? | `PairingApprovalResult` | 设备配对审批 | +| `zclaw_doctor` | — | `String` | 诊断报告 | +| `zclaw_process_list` | — | `ProcessListResponse` | 进程列表 | +| `zclaw_process_logs` | pid?, lines? | `ProcessLogsResponse` | 进程日志 | +| `zclaw_version` | — | `VersionResponse` | 版本信息 | + +**健康检查** (`desktop/src-tauri/src/health_check.rs`): + +| 命令 | 参数 | 返回值 | 说明 | +|------|------|--------|------| +| `zclaw_health_check` | port?, timeout_ms? | `HealthCheckResponse` | 完整健康检查 | +| `zclaw_ping` | — | `bool` | 快速端口检测 | + +### SaaS Relay 路由 (`crates/zclaw-saas/src/relay/`) + +| 方法 | 路径 | 权限 | 说明 | +|------|------|------|------| +| POST | `/api/v1/relay/chat/completions` | 认证+配额 | 主聊天中转 | +| GET | `/api/v1/relay/models` | 认证 | 可用模型列表 | +| GET | `/api/v1/relay/tasks` | 认证 | 任务列表 | +| GET | `/api/v1/relay/tasks/:id` | 认证 | 任务详情 | +| POST | `/api/v1/relay/tasks/:id/retry` | admin | 重试失败任务 | + +### Provider Key 管理 (`crates/zclaw-saas/src/relay/handlers.rs`) + +| 方法 | 路径 | 权限 | 说明 | +|------|------|------|------| +| GET | `/api/v1/providers/:id/keys` | admin | 列出 Provider Key | +| POST | `/api/v1/providers/:id/keys` | admin | 添加加密 Key | +| PUT | `/api/v1/providers/:id/keys/:kid/toggle` | admin | 启停 Key | +| DELETE | `/api/v1/providers/:id/keys/:kid` | admin | 删除 Key | + +## 测试链路 + +| 功能 | 测试文件 | 测试数 | 覆盖状态 | +|------|---------|--------|---------| +| Admin 路由解析 | `tests/desktop/connectionStore.adminRouting.test.ts` | — | ✅ parseAdminRouting() 纯函数 | +| 连接流程 | `tests/desktop/gatewayStore.test.ts` | — | ✅ connect() + 数据加载 | +| GatewayClient | `tests/gateway/ws-client.test.ts` | — | ✅ WS 连接/事件/断连 | +| Mock Server | `tests/fixtures/zclaw-mock-server.ts` | — | ✅ HTTP+WS 模拟 | + ## 关联模块 - [[chat]] — 路由决定使用哪种 ChatStream @@ -250,3 +319,8 @@ POST /api/v1/relay/chat/completions → SSE 流 | `desktop/src/lib/saas-relay-client.ts` | SaaS SSE 中继 | | `desktop/src/lib/saas-client.ts` | SaaS API 客户端 | | `desktop/src/store/index.ts` | Store 协调器 + client 注入 | + +## 已知问题 + +- ✅ **Tauri invoke 参数名 snake_case vs camelCase** — P1 已修复 (commit f6c5dd2)。Tauri 2.x 默认 `rename_all = "camelCase"`，所有 invoke 调用必须用 camelCase +- ✅ **Provider Key 解密失败导致 relay 500** — P1 已修复 (commit b69dc61)。`key_pool.rs` 现在 decrypt 失败时 warn+skip 到下一个 key，启动时 `heal_provider_keys()` 自动重新加密有效 key diff --git a/wiki/saas.md b/wiki/saas.md index 96d1105..e3b4837 100644 --- a/wiki/saas.md +++ b/wiki/saas.md @@ -1,6 +1,6 @@ --- title: SaaS 平台 -updated: 2026-04-19 +updated: 2026-04-21 status: active tags: [module, saas, auth, billing] --- @@ -19,6 +19,28 @@ tags: [module, saas, auth, billing] 3. **计费闭环** — 配额实时递增 → 聚合器调度 → mock 支付路由 4. **Admin V2** — 17 页管理后台，管理模型/用户/计费/知识库 +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| 用户认证 | 注册/登录/JWT刷新/登出 | auth/handlers.rs | ✅ | +| TOTP 2FA | 设置/验证/禁用 | auth/handlers.rs | ✅ | +| Token Pool | RPM/TPM 轮换 Key 分配 | relay/handlers.rs | ✅ | +| 聊天中转 | OpenAI 兼容 relay | relay/handlers.rs | ✅ | +| 计费系统 | 配额递增/订阅/支付回调 | billing/ | ✅ | +| 用户管理 | CRUD/状态/设备/token | account/ | ✅ | +| 模型管理 | Provider/模型/Key CRUD | model_config/ | ✅ | +| Agent 模板 | 模板 CRUD + 自动分配 | agent_template/ | ✅ | +| 知识库 | 分类/条目/搜索/pgvector | knowledge/ | ✅ | +| Prompt 管理 | 版本控制/回滚 | prompt/ | ✅ | +| 角色权限 | RBAC + 权限模板 | role/ | ✅ | +| 行业配置 | 行业 CRUD + 账户分配 | industry/ | ✅ | +| 定时任务 | 任务调度 CRUD | scheduled_task/ | ✅ | +| 用量统计 | Telemetry 上报/查询 | telemetry/ | ✅ | +| 配置同步 | 项 CRUD/分析/seed/sync/diff | migration/ | ✅ | +| Admin Dashboard | 系统概览 + 运营指标 | account/admin_routes | ✅ | +| Mock 支付 | 开发环境模拟支付 | billing/mock_routes | ✅ | + ## 代码逻辑 ### 认证流 @@ -123,6 +145,52 @@ relay/ role/ scheduled_task/ tasks/ telemetry/ workers/ | aggregate_usage | workers/ | 用量聚合 | | generate_embedding | workers/ | 内容分块 (embedding deferred) | +## API 接口 + +~118 个唯一路由，分布在 13 个模块中（详见上方「SaaS API 分布」和各模块 `mod.rs`）。 + +| 模块 | 路由数 | 核心端点 | +|------|--------|---------| +| auth | 9 | POST /auth/{register,login,refresh,logout} + TOTP + password | +| relay | 5 | POST /relay/chat/completions + GET /relay/models | +| billing | 12 | 订阅/用量/支付/mock/回调/invoice | +| knowledge | 24 | 分类/条目/搜索/上传/版本/分析/结构化 | +| model_config | 19 | Provider/模型/Key/模型组/用量 | +| account | 12 | CRUD/状态/token/设备/操作日志/dashboard | +| agent_template | 11 | 模板 CRUD + 创建 Agent + 分配 | +| industry | 8 | 行业 CRUD + 账户分配 | +| prompt | 6 | Prompt CRUD + 版本/回滚 | +| role | 6 | 角色/权限模板 CRUD | +| telemetry | 4 | 上报/统计/日报/审计 | +| scheduled_task | 2 | 定时任务 CRUD | +| migration | 8 | 配置项 CRUD + 分析/seed/sync/diff | + +## 测试链路 + +| 功能 | 测试文件 | 说明 | +|------|---------|------| +| 认证 | `crates/zclaw-saas/tests/auth_test.rs` | 注册/登录/刷新/登出 | +| 认证安全 | `crates/zclaw-saas/tests/auth_security_test.rs` | 安全边界场景 | +| 账户 | `crates/zclaw-saas/tests/account_test.rs` | CRUD/token/设备 | +| 账户安全 | `crates/zclaw-saas/tests/account_security_test.rs` | 安全边界 | +| Agent 模板 | `crates/zclaw-saas/tests/agent_template_test.rs` | 模板 CRUD | +| 计费 | `crates/zclaw-saas/tests/billing_test.rs` | 计划/订阅/支付 | +| 知识库 | `crates/zclaw-saas/tests/knowledge_test.rs` | CRUD/搜索 | +| 模型配置 | `crates/zclaw-saas/tests/model_config_test.rs` | Provider/模型/Key | +| 模型配置扩展 | `crates/zclaw-saas/tests/model_config_extended_test.rs` | 扩展覆盖 | +| Prompt | `crates/zclaw-saas/tests/prompt_test.rs` | 版本管理 | +| 权限矩阵 | `crates/zclaw-saas/tests/permission_matrix_test.rs` | 角色/权限 | +| Relay | `crates/zclaw-saas/tests/relay_test.rs` | 聊天中转 | +| Relay 验证 | `crates/zclaw-saas/tests/relay_validation_test.rs` | 请求验证 | +| 角色 | `crates/zclaw-saas/tests/role_test.rs` | 角色 CRUD | +| 定时任务 | `crates/zclaw-saas/tests/scheduled_task_test.rs` | 任务 CRUD | +| Telemetry | `crates/zclaw-saas/tests/telemetry_test.rs` | 上报/查询 | +| 配置同步 | `crates/zclaw-saas/tests/migration_test.rs` | sync/diff/seed | +| Admin 启动 | `crates/zclaw-saas/tests/smoke_saas.rs` | 启动冒烟 | +| Admin V2 UI | `admin-v2/tests/pages/*.test.tsx` (17文件) | 每页独立测试 | +| 桌面端 SaaS | `tests/desktop/connectionStore.adminRouting.test.ts` | Admin 路由 | +| 桌面端集成 | `tests/desktop/integration/zclaw-api.test.ts` | API 集成 | + ## 关联模块 - [[routing]] — SaaS Relay 是 Tauri 的主路径 @@ -151,3 +219,12 @@ relay/ role/ scheduled_task/ tasks/ telemetry/ workers/ - Cookie Secure (dev=false, prod=true) - JWT 签名密钥 >= 32 字符 (release fallback 拒绝启动) - 独立 TOTP 加密密钥 + +## 已知问题 + +- ⚠️ **Admin 用量统计显示 0/0** — P2 Open。Dashboard 显示 17 requests / 6304 tokens，但 Usage 页显示 0/0，数据源不一致 +- ⚠️ **SaaS Embedding 生成未实现** — Open。pgvector 索引就绪，`generate_embedding.rs` Worker 存在但生成逻辑未实现 +- ⚠️ **AuthGuard 竞态条件** — P1-04 Deferred。并发请求时可能绕过认证 +- ✅ **Dashboard 404** — BUG-H1 已修复。`/api/v1/admin/dashboard` 路由注册遗漏 +- ✅ **invoice_id 未暴露** — BUG-M1 已修复 +- ✅ **非 Admin 返回 404 而非 403** — BUG-M4 已修复 (admin_guard_middleware) diff --git a/wiki/security.md b/wiki/security.md new file mode 100644 index 0000000..7f8f9a1 --- /dev/null +++ b/wiki/security.md @@ -0,0 +1,157 @@ +--- +title: 安全体系 +updated: 2026-04-21 +status: active +tags: [module, security, auth, encryption] +--- + +# 安全体系 + +> 从 [[index]] 导航。关联模块: [[saas]] [[routing]] [[middleware]] + +## 设计思想 + +**核心原则: 多层防御，深度安全。** + +1. **认证层** — JWT + Cookie + TOTP 2FA + 账户锁定 +2. **传输层** — CORS 白名单 + Cookie Secure + HTTPS (反向代理) +3. **存储层** — Argon2id 密码 + AES-256-GCM 加密 + OS Keyring +4. **运行时层** — 限流 + 配额 + CSP + Guardrail 中间件 + +完整审计报告: `docs/features/SECURITY_PENETRATION_TEST_V1.md` + +## 功能清单 + +| 功能 | 描述 | 入口文件 | 状态 | +|------|------|----------|------| +| JWT 认证 | 签发/验证/刷新/失效 | auth/handlers.rs | ✅ | +| Cookie 双通道 | Tauri keyring + 浏览器 HttpOnly | auth/handlers.rs | ✅ | +| TOTP 2FA | 设置/验证/禁用 | auth/totp.rs | ✅ | +| 密码安全 | Argon2id + OsRng 盐 + pwv 失效 | auth/handlers.rs | ✅ | +| Token 池加密 | AES-256-GCM + 随机 Nonce | relay/key_pool.rs | ✅ | +| OS Keyring | Win DPAPI/macOS Keychain/Linux Secret | secure_storage.rs | ✅ | +| 本地记忆加密 | AES-256-GCM (可选) | memory/crypto.rs | ✅ | +| 账户锁定 | 5 次失败锁 15 分钟 | auth/handlers.rs | ✅ | +| 限流 | IP 级 + 账户级滑动窗口 | middleware.rs | ✅ | +| CORS 白名单 | 生产缺失拒绝启动 | main.rs CorsLayer | ✅ | +| CSP | Tauri 移除 unsafe-inline | desktop/src-tauri/ | ✅ | +| Admin 权限 | admin_guard + RBAC | middleware.rs | ✅ | + +## 代码逻辑 + +### 认证流程 + +``` +用户登录 (POST /api/v1/auth/login) + → Argon2id + OsRng 验证密码 + → 账户锁定检查 (5 次失败 → 15 分钟锁定) + → 签发 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) + Secure: dev=false, prod=true | SameSite=Strict + +前端存储: + → Tauri: OS keyring → saasStore.token + → 浏览器: HttpOnly Cookie (JS 不可读) + → localStorage: 仅 saasUrl + account 非敏感信息 +``` + +### JWT Password Version 失效机制 + +``` +JWT Claims 含 pwv (password_version) 字段 + → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv + → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效 +``` + +### Token 池安全 + +``` +Provider Key 存储: AES-256-GCM + 随机 Nonce 加密 + → 解密失败: warn + skip 到下一个 Key (不阻塞 relay) + → 启动时: heal_provider_keys() 自动重新加密有效 Key + → TOTP 加密密钥: 生产环境强制独立 ZCLAW_TOTP_ENCRYPTION_KEY +``` + +### SaaS HTTP 中间件栈 (10 层) + +| # | 中间件 | 路由组 | 功能 | +|---|--------|--------|------| +| 1 | public_rate_limit | Public | IP 限流: login 5/min, register 3/hour | +| 2 | auth_middleware | Protected+Relay | JWT/Cookie/API Token 身份验证 | +| 3 | rate_limit_middleware | Protected+Relay | 账户级请求频率限制 | +| 4 | quota_check_middleware | Relay | 月度配额检查 (relay_requests + input_tokens) | +| 5 | request_id_middleware | All | UUID 请求追踪 | +| 6 | api_version_middleware | All | API 版本头 | +| 7 | TimeoutLayer (15s) | Protected | 非流式请求超时 | +| 8 | admin_guard | Admin 子路由 | admin 权限验证 | +| G1 | TraceLayer | All | HTTP 请求追踪 | +| G2 | CorsLayer | All | CORS 白名单 (生产缺失拒绝启动) | + +## API 接口 + +### Auth 公开路由 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/v1/auth/register` | 注册 (邮箱 RFC 5322 + 254 字符限制) | +| POST | `/api/v1/auth/login` | 登录 (5 次/分钟 IP 限流) | +| POST | `/api/v1/auth/refresh` | 刷新 Token (单次使用，旧 token 撤销到 DB) | +| POST | `/api/v1/auth/logout` | 登出 | + +### Auth 受保护路由 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/auth/me` | 当前用户信息 | +| PUT | `/api/v1/auth/password` | 修改密码 (触发 pwv 失效) | +| POST | `/api/v1/auth/totp/setup` | TOTP 设置 (生成 QR) | +| POST | `/api/v1/auth/totp/verify` | TOTP 验证激活 | +| POST | `/api/v1/auth/totp/disable` | TOTP 禁用 (需密码) | + +### Tauri 安全命令 + +| 命令 | 说明 | +|------|------| +| `secure_store_set` | OS Keyring 存储 | +| `secure_store_get` | OS Keyring 读取 | +| `secure_store_delete` | OS Keyring 删除 | +| `secure_store_is_available` | Keyring 可用性检测 | + +## 测试链路 + +| 功能 | 测试文件 | 覆盖状态 | +|------|---------|---------| +| 认证流程 | `crates/zclaw-saas/tests/auth_test.rs` | ✅ | +| 认证安全边界 | `crates/zclaw-saas/tests/auth_security_test.rs` | ✅ | +| 账户安全 | `crates/zclaw-saas/tests/account_security_test.rs` | ✅ | +| 权限矩阵 | `crates/zclaw-saas/tests/permission_matrix_test.rs` | ✅ | +| TOTP | `crates/zclaw-saas/src/auth/totp.rs` inline | ✅ | +| 本地加密 | `desktop/src-tauri/src/memory/crypto.rs` inline | ✅ | + +## 关联模块 + +- [[saas]] — 安全体系运行在 SaaS 后端 +- [[routing]] — SaaS JWT 用于 relay 认证 +- [[middleware]] — Guardrail + LoopGuard + SubagentLimit 运行时安全 + +## 关键文件 + +| 文件 | 职责 | +|------|------| +| `crates/zclaw-saas/src/auth/handlers.rs` | 认证端点实现 | +| `crates/zclaw-saas/src/auth/totp.rs` | TOTP 2FA 实现 | +| `crates/zclaw-saas/src/middleware.rs` | HTTP 中间件栈 | +| `crates/zclaw-saas/src/relay/key_pool.rs` | Token Pool + Key 加密 | +| `desktop/src-tauri/src/secure_storage.rs` | OS Keyring 接口 | +| `desktop/src-tauri/src/memory/crypto.rs` | 本地 AES-256-GCM | +| `docs/features/SECURITY_PENETRATION_TEST_V1.md` | 安全审计报告 | + +## 已知问题 + +- ✅ **JWT 签名密钥 fallback** — `#[cfg(debug_assertions)]` 保护，release 拒绝启动 +- ✅ **TOTP 加密密钥解耦** — 生产环境强制独立 `ZCLAW_TOTP_ENCRYPTION_KEY` +- ✅ **Cookie Secure 标志** — dev=false, prod=true +- ✅ **CORS 白名单** — 生产缺失拒绝启动 +- ✅ **Admin 404→403** — admin_guard_middleware 已修复