# Wiki 生成质量对比实验

## 实验目标

对比 **Two-Step 模式**（先分析后生成）与 **Single-Step 模式**（直接生成）在 Wiki 内容生成质量上的差异。

## 实验设计

- **测试文件**: `raw/呼吸之间_李谨伯/第一编 从身体入手.md`
- **金标准**: 66 个术语（概念、方法、实体）
- **评估维度**:
  - 40% 内容完整性
  - 30% 技术规范性
  - 20% 可维护性
  - 10% 效率成本

## 目录结构

```
tools/experiments/wiki-generation-compare/
├── prompts/
│   ├── twostep-analysis.md       # A组 Step 1 分析 prompt
│   ├── twostep-generation.md     # A组 Step 2 生成 prompt
│   └── singlestep.md             # B组 单步生成 prompt
├── scripts/
│   ├── run-a-group.ps1           # 执行 A 组
│   ├── run-b-group.ps1           # 执行 B 组
│   ├── evaluate.ps1              # 评估脚本
│   └── cleanup.ps1               # 清理环境
├── output/
│   ├── group-a/                  # A 组输出
│   │   ├── analysis.json         # Step 1 分析结果
│   │   ├── wiki/                 # 生成的 Wiki 页面
│   │   └── metadata.json         # 执行元数据
│   ├── group-b/                  # B 组输出
│   │   ├── wiki/                 # 生成的 Wiki 页面
│   │   └── metadata.json         # 执行元数据
│   └── report.md                 # 最终对比报告
└── gold-standard.json             # 金标准数据
```

## 执行步骤

### 1. 执行 A 组（Two-Step 模式）

```powershell
cd tools/experiments/wiki-generation-compare
.\scripts\run-a-group.ps1
```

**说明**:
- Step 1: 调用 LLM 分析源文件，提取结构化信息
- Step 2: 基于分析结果生成 Wiki 页面
- 预计耗时：30-45 分钟（取决于 LLM API 响应速度）

### 2. 执行 B 组（Single-Step 模式）

```powershell
.\scripts\run-b-group.ps1
```

**说明**:
- 直接调用 LLM 生成 Wiki 页面
- 预计耗时：15-30 分钟（取决于 LLM API 响应速度）

### 3. 评估与报告

```powershell
.\scripts\evaluate.ps1
```

**说明**:
- 对比 A/B 两组的输出
- 评估术语覆盖度、Frontmatter 规范性、Wikilink 质量
- 生成完整的对比报告

### 4. 清理环境（可选）

```powershell
.\scripts\cleanup.ps1
```

## 配置要求

### LLM API 配置

脚本支持多种 LLM API：

1. **opencode-mem**（优先）
   - 自动使用系统配置的记忆系统
   - 无需额外配置

2. **OpenAI API**（备用）
   ```powershell
   $env:OPENAI_API_KEY = "your-api-key"
   ```

3. **其他 API**
   - 需要修改脚本中的 API 调用代码

## 评估标准

### 1. 术语覆盖度（40%）

- 覆盖率：覆盖术语数 / 金标准术语数
- 定义质量：有定义的页面占比
- 来源链接：有来源链接的页面占比
- 行号标注：有行号标注的页面占比

### 2. 技术规范性（30%）

- Frontmatter 完整度：必需字段占比
- 布尔值合规率：布尔值用引号包裹的占比
- Wikilink 质量：有效链接占比

### 3. 可维护性（20%）

- 元数据完整性
- 文件组织结构

### 4. 效率成本（10%）

- 执行时间
- Token 消耗（如果支持）

## 预期结果

| 维度 | Two-Step | Single-Step | 预测 |
|------|----------|-------------|------|
| 术语覆盖度 | 高 | 中 | A > B |
| 定义准确度 | 高 | 高 | A ≈ B |
| 来源标注 | 强制 | 手动 | A < B（粒度） |
| Frontmatter 规范 | 自动生成 | 手动维护 | A > B |
| Wikilink 质量 | 高 | 中 | A > B |
| 索引/日志 | 自动更新 | 手动更新 | A > B |
| Token 消耗 | 高（两步） | 低（单步） | A > B |
| 时间成本 | 长 | 短 | A > B |
| 可定制性 | 低 | 高 | A < B |
| 人工干预 | 异步 | 同步 | A ≈ B |

## 故障排查

### LLM 调用失败

如果 LLM API 调用失败，脚本会：

1. 显示错误信息
2. 尝试生成模拟数据用于测试
3. 继续执行评估脚本

### 文件解析失败

如果 Wiki 页面解析失败：

1. 检查 LLM 输出格式
2. 检查 `---FILE: … ---END FILE---` 标记
3. 查看生成的原始输出文件

### 评估脚本错误

如果评估脚本报错：

1. 检查金标准文件是否存在
2. 检查输出目录是否生成
3. 查看 PowerShell 错误信息

## 注意事项

1. **API 成本**: Two-Step 模式需要两次 LLM 调用，Token 消耗更高
2. **执行时间**: Two-Step 模式需要更长时间
3. **质量差异**: Two-Step 模式预期内容质量更高，但效率更低
4. **实验环境**: 确保有足够的磁盘空间和网络连接

## 扩展实验

### 测试更多文件

修改脚本中的 `$sourceFile` 变量：

```powershell
$sourceFile = "raw/呼吸之间_李谨伯/第四编 怎样调整呼吸.md"
```

### 调整权重

修改 `evaluate.ps1` 中的权重配置：

```powershell
$weights = @{
    contentCompleteness = 0.5  # 提高内容完整性权重
    technicalCompliance = 0.2
    maintainability = 0.2
    efficiency = 0.1
}
```

### 添加新的评估维度

在 `evaluate.ps1` 中添加新的评估函数，并修改得分计算逻辑。

## 参考资料

- [AGENTS.md - Wiki 工作流](../../../AGENTS.md)
- [nashsu/llm_wiki - Two-Step Ingest](https://github.com/nashsu/llm_wiki)
- [Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

---

**实验创建时间**: 2026-07-03
**实验维护者**: opencode Agent