zclaw_openfang/docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md

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 标准章节模板

---
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 并检查输出后填入，不使用假设值。

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