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