zclaw_openfang/docs/wiki-methodology.md

# 项目 Wiki 知识库编制方法论

> 基于 ZCLAW 项目实战经验（10 crates + React 前端，~155KB wiki 重构）提炼。
> 适用于任何有 AI 辅助开发参与的中大型项目。
> **一句话总结**：Wiki 只记录代码无法告诉你的东西。

---

## 一、设计原则

### 原则 1：Wiki 记录"代码不能告诉你的"

| 记录在 Wiki ✅ | 不记录在 Wiki ❌ |
|---------------|-----------------|
| 为什么这样设计（WHY） | 字段列表、函数签名 |
| 跨模块数据流走向 | 单文件内的代码逻辑 |
| 历史踩坑和教训 | 可用 `grep` 直接查到的信息 |
| 必须始终成立的约束（不变量） | CRUD 操作、getter/setter |
| 模块间调用接口（集成契约） | 具体的行号、变量名 |

**判断标准**：如果 `git log` 或 `grep` 能在 30 秒内回答这个问题，就不需要写在 wiki 里。

### 原则 2：每个模块页统一 5 节结构

按**阅读优先级**排列（先给最重要的信息）：

```
1. 设计决策 (WHY)     — 为什么这样设计、历史背景、权衡取舍
2. 关键文件 + 数据流    — 3-7 个核心文件 + 跨模块接口
3. 代码逻辑           — 数据流走向 + 不变量 + 非显而易见的算法
4. 活跃问题 + 陷阱     — 当前未解决 + 历史教训
5. 变更记录           — 最近 5 条，超出的归入全局日志
```

**为什么是这个顺序**：新的 AI 会话（或开发者）首先需要知道"这个模块为什么存在"和"文件在哪"，然后才是"怎么工作的"，最后是"有什么问题"。

### 原则 3：页面大小必须有预算

| 页面类型 | 行数预算 | 原因 |
|---------|---------|------|
| 首页/索引 | ≤ 120 行 | 需要快速扫描，AI 一次加载 |
| 模块页 | 100-200 行 | AI 一次加载 2-3 个模块不爆 context |
| 全局日志 | ≤ 50 条活跃 | 防止无限膨胀，旧条目归档 |

**超过预算怎么办**：把详细内容归档到 `archive/` 目录，模块页只保留摘要 + 链接。

### 原则 4：单一真相源

同一信息只出现在一个页面。其他需要该信息的地方只放引用。

```
错误：安全认证流程同时写在 saas.md、security.md、middleware.md
正确：security.md 拥有完整描述，saas.md 只写"详见 [[security]]"
```

**检查方法**：`grep` 关键内容，如果出现在 ≥ 3 个页面，就需要去重。

### 原则 5：Append-only 内容必须封顶

日志、问题列表等只增不减的内容，必须设置上限并定期归档。

```
活跃日志 ≤ 50 条 → 旧条目归入 archive/log-{YYYY-MM}.md
活跃问题 ≤ 5 条/模块 → 修复后立即移除
变更记录 ≤ 5 条/模块 → 旧记录在全局 log.md
```

### 原则 6：用症状导航补充模块导航

模块导航解决"这个模块是什么"的问题。但实际开发中，人们更多是在解决"出了问题该看哪里"。

**症状导航表**格式：

| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
| 流式响应卡住 | routing | chat → middleware | 连接断开 / 超时 |
| 数据没持久化 | data-model | 对应模块 | 表结构 / 迁移缺失 |

放在首页/索引页，让新来的人（或 AI 会话）0 跳就能定位排查方向。

---

## 二、结构模板

### 2.1 三级层级

```
项目 Wiki
├── Level 1: index.md       — 纯导航 + 症状索引（≤ 120 行）
├── Level 2: {module}.md    — 每个功能模块一个页面（100-200 行）
├── Level 3: archive/       — 历史内容归档
└── (可选) known-issues.md  — 活跃问题全局索引
```

### 2.2 首页模板 (index.md)

```markdown
# {项目名} 知识库

> 一句话定位。使用方式说明。

## 关键数字
| 指标 | 值 | 验证方式 |
|------|-----|---------|

## 系统数据流
{ASCII 全景图}

## 模块导航
- [[module-a]] — 一句话说明
- [[module-b]] — 一句话说明

## 症状导航
| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
```

### 2.3 模块页模板 ({module}.md)

```markdown
---
title: {模块名}
updated: {YYYY-MM-DD}
status: active | stable | developing
tags: [{tags}]
---

# {模块名}

> 从 [[index]] 导航。关联: [[related-1]] [[related-2]]

## 1. 设计决策

{为什么这样设计、历史背景、权衡取舍}
{用 Q&A 格式记录关键架构决策}

## 2. 关键文件 + 数据流

### 核心文件
| 文件 | 职责 |
|------|------|
| `path/to/file` | 一句话说明 |

### 数据流
{ASCII 流程图}

### 集成契约
| 方向 | 模块 | 接口 | 触发时机 |
|------|------|------|---------|
| 调用 → | {module} | `{function/API}` | {when} |
| 被调用 ← | {module} | `{function/API}` | {when} |

## 3. 代码逻辑

### 关键数据流
{跨函数/跨文件的完整路径，附意图说明}

### 不变量
⚡ {不变量 1}: {必须始终成立的约束}
⚡ {不变量 2}: {描述}

### 非显而易见的算法
{读代码难以理解的逻辑}

## 4. 活跃问题 + 陷阱

### 活跃问题
| 问题 | 级别 | 状态 | 说明 |
|------|------|------|------|
{0-5 条，修复后移除}

### 历史教训
- {教训}: {一句话描述}

### 注意事项
⚠️ {易出错的地方}

## 5. 变更记录
| 日期 | 变更 |
|------|------|
{最近 5 条}
```

---

## 三、关键机制详解

### 3.1 集成契约

**问题**：跨模块边界的信息（谁调谁、接口形状）是最难从代码中获取的知识，也是 wiki 最大的结构性缺口。

**做法**：每个模块页的"关键文件"节下增加一个"集成契约"小表，回答四个问题：

| 问题 | 对应列 |
|------|--------|
| 这个模块调用了谁？ | 调用 → |
| 这个模块被谁调用？ | 被调用 ← |
| 通过什么接口？ | 接口（函数名/API路径） |
| 什么时候触发？ | 触发时机 |

**示例**（中间件模块）：

| 方向 | 模块 | 接口 | 触发时机 |
|------|------|------|---------|
| 被调用 ← | kernel | `create_middleware_chain()` | 内核启动 |
| 调用 → | runtime | `run_before_completion()` | 每次聊天请求 |
| 提供 → | 所有模块 | `AgentMiddleware` trait | 14 个实现 |

### 3.2 不变量标记

**问题**：系统中有一些"必须始终成立的约束"，它们不像代码那样显式存在，但一旦被违反就会产生隐蔽的 bug。

**做法**：用 ⚡ 标记不变量，放在"代码逻辑"节下。

```
⚡ Priority 是升序排列：0-999，数值越小越先执行
⚡ memories.db 和 data.db 是独立数据库，跨库查询需确认目标库
⚡ 记忆注入在中间件@150，在管家路由@80之后，技能索引@200之前
```

**判断什么是好的不变量**：
- 它描述的是一种**关系或顺序**，不是单个组件的行为
- 如果有人不知道这个约束，修改代码时很可能无意中违反它
- 违反的后果不会立即显现，而是演化几轮后变成隐性 bug

### 3.3 去重规则

| 重复类型 | 处理方式 |
|---------|---------|
| 完整描述出现在 A 和 B | 选择一个为真相源，另一个只引用 |
| 相同信息出现在 ≥ 3 页 | 必须去重，指定唯一归属 |
| 概述 vs 详情 | 概述页保留一句话 + 链接，详情页拥有完整描述 |

**去重检查命令**：
```bash
grep -l '关键内容' wiki/*.md | wc -l
# 结果 ≥ 3 → 需要去重
```

### 3.4 症状导航

**为什么需要**：模块导航是"模块→功能"方向，但排查问题时需要的是"症状→模块"方向。

**编制方法**：
1. 收集团队/AI 会话中反复出现的调试场景（8-12 个）
2. 每个场景记录：症状、先查哪个页面、再查哪个、最常见根因
3. 放在首页，新会话/新人 0 跳可达

**示例**：

| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
| API 返回 502 | saas | routing | Token 耗尽 / 服务超时 |
| 数据不持久 | data-model | 对应模块 | 表缺失 / 字段不匹配 |
| 流式中断 | chat | middleware | 连接断开 / 超时守护 |

---

## 四、维护工作流

### 4.1 什么时候更新 Wiki

| 触发事件 | 更新什么 |
|---------|---------|
| 修复 bug | 对应模块页"活跃问题" + 全局 known-issues 索引 |
| 架构变更 | 对应模块页"设计决策" + 集成契约 |
| 文件结构变化 | 对应模块页"核心文件"表 |
| 跨模块接口变化 | 涉及双方的"集成契约"表 |
| 发现新不变量 | 对应模块页"代码逻辑"节的 ⚡ 项 |
| 每次更新 | 模块页"变更记录"(保持5条) + 全局 log.md |

### 4.2 防止 drift 的策略

| 策略 | 做法 |
|------|------|
| 页面大小预算 | 超过 200 行强制裁剪，移入 archive/ |
| 活跃问题生命周期 | 修复后立即移除，不保留已修复项 |
| 变更记录滑动窗口 | 只保留最近 5 条，旧的自然滚入全局日志 |
| 数字验证 | 关键数字标注验证命令，定期执行确认 |
| "最后验证"日期 | 在 frontmatter 的 `updated` 字段记录，超过 30 天需要复查 |

### 4.3 重构 Wiki 的执行顺序

如果需要对已有 wiki 进行重构，按依赖关系分阶段：

```
Phase 1: 归档/封顶 — 压缩日志、归档旧内容（无依赖）
Phase 2: 确立真相源 — 最被其他页面引用的模块优先重构
Phase 3: 依赖页面 — 引用 Phase 2 模块的页面去重
Phase 4: 剩余模块 — 独立页面逐一重构
Phase 5: 首页/索引 — 最后改（依赖所有模块页完成）
```

**关键约束**：每个模块页独立提交，可安全 `git revert` 回滚单个页面。

---

## 五、AI 辅助开发的特殊考量

### 5.1 Wiki 的主要读者可能是 AI

在 AI 辅助开发中，wiki 的主要读者是每次新会话的 AI 实例（context 从零开始）。这改变了 wiki 的设计优先级：

| 传统 wiki | AI 辅助 wiki |
|-----------|-------------|
| 详细、全面 | 精炼、可快速加载 |
| 按主题组织 | 按任务场景导航 |
| 历史记录丰富 | 只保留活跃信息 |
| 人工索引 | 症状→页面直接映射 |

### 5.2 Context 预算思维

AI 的 context window 是有限资源。wiki 的每个字节都在消耗这个预算。

**优化策略**：
- 首页只放导航，不放内容（让 AI 按需读取模块页）
- 模块页控制在 100-200 行（一次加载 2-3 个不爆 context）
- 代码逻辑只写流向和不变量，不写可从代码读取的细节
- 使用 `archive/` 存放低频需要的历史内容

### 5.3 Wiki 作为新会话的启动燃料

设计 wiki 时要问：**一个全新的 AI 会话，读完首页后能定位问题吗？读完 2 个模块页后能开始工作吗？**

如果答案是"不能"，说明 wiki 的导航层不够好（首页缺症状导航）或模块页的结构不对（信息不在前两节）。

---

## 六、检查清单

### 创建 Wiki 时

- [ ] 首页 ≤ 120 行，包含：项目一句话定位、关键数字、模块导航、症状导航
- [ ] 每个模块页统一 5 节结构
- [ ] 每个模块页有集成契约表
- [ ] 每个模块页有 ⚡ 不变量
- [ ] 每个模块页 100-200 行
- [ ] 无内容重复出现在 ≥ 3 个页面
- [ ] 全局日志封顶 50 条，有归档机制

### 维护 Wiki 时

- [ ] 修复 bug 后更新对应模块"活跃问题"
- [ ] 架构变更后更新对应模块"设计决策"+ 集成契约
- [ ] 每次更新追加全局 log.md 条目
- [ ] 每次更新模块页变更记录（保持 5 条）
- [ ] 定期检查页面是否超过大小预算

---

## 附录：ZCLAW 重构效果

| 指标 | 重构前 | 重构后 | 变化 |
|------|--------|--------|------|
| 模块页总行数 | ~2,800 | ~1,547 | -45% |
| 重复内容 | 安全×3, 进化×3 | 各×1 | 消除 |
| 集成契约覆盖 | 0/10 页 | 10/10 页 | 全覆盖 |
| 症状导航 | 无 | 8 条路径 | 新增 |
| 首页 | 144 行 | 101 行 | +症状导航 |
| 最大单页 | 424 行 | 199 行 | 控住 |