docs(wiki): 系统性更新 — L0速览+L1模块标准化+L2功能链路映射(33条)

三层架构增强:
- 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

@@ -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 数等）变化时
 

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 个警告

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 条件注册** — 无技能时中间件不注册，长期观察

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<ClassroomChatMessage>` | 课堂对话 |
+| `classroom_chat_history` | classroom_id | `Vec<ClassroomChatMessage>` | 历史消息 |
+
+**流式事件类型** (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)

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

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 |

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) |

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待处理

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 行新增内容

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\<PersistentMemory\> | 批量导入 |
+| `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\<PersistentMemory\> | 批量导入 |
+| `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

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 有测试

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 禁用后已有任务不自动清理

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

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)

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 已修复