sanguo_llmwiki/docs/02-design-review.md

sanguo_llmwiki 设计文档评审报告 v3

评审者： 独立软件设计评审专家 评审日期： 2026-06-26 需求文档版本： v1.1 设计文档版本： v1.0 → v1.2 总体评价： 通过 ✅

---

一、v1.0 发现的问题（第一轮评审）

🔴 Critical（已修复）

ID	问题	位置	修复方案	状态
C1	缺少 QueryService 模块设计	第 2.3 节	补充完整的 QueryService 设计，包括 search/search_by_tags/get_page/get_links/get_backlinks/find_orphans 方法	✅
C2	FTS5 表设计不完整	第 3 节	补充完整的 SQLite 表结构（wiki_pages/wiki_fts/wiki_links/wiki_tags/wiki_meta/wiki_content）	✅

🟡 Major（已修复）

ID	问题	位置	修复方案	状态
M1	Database 类并发问题	第 2.4 节	使用 aiosqlite 实现真正的异步支持，配合 asyncio.Lock 和 WAL 模式	✅
M2	缺少 MemoryBridgeTool	第 2.2 节	补充 MemoryBridgeTool 详细设计，包括接口和返回格式	✅
M3	配置项不一致	第 6.1 节	与需求 5.3 节对齐，补充 max_concurrent_indexing 配置项	✅
M4	Skills 优先级不一致	第 10.2 节	与需求 3.2 节对齐（P0: 3 个，P1: 4 个，P2: 4 个）	✅
M5	缺少 benchmark 设计	第 11 节	新增完整的 benchmark.py 设计，包括 query/indexing/memory 测试	✅

🟢 Minor（已修复）

ID	问题	修复方案	状态
m1	WikiPage.sources 字段	删除字段并添加说明	✅
m2	缺少 hot.md 生成	补充 hot.md 生成算法（第 5.4 节）	✅
m3	重试失败处理	补充重试策略和降级方案（第 7.3 节）	✅
m4	SSE 模式实现	明确为 v1.1 预留（第 13.3 节）	✅
m5	MCP SDK 版本	补充 Python 3.11+ 要求	✅

---

二、v1.1 发现的问题（第二轮评审）

🟡 Major（已修复）

ID	问题	位置	修复方案	状态
M1	FTS5 表结构语法错误	第 3.3 节	删除重复定义，调整表创建顺序（先创建 wiki_content，再创建 wiki_fts）	✅
M2	memory_bridge 的 tool_name 来源不明确	第 2.2 节 / 3.1 节	在 WikiPage 中添加 source_tool 字段，在 wiki_pages 表中添加对应列和索引	✅
M3	QueryService 缓存策略可能导致内存泄漏	第 2.3 节	补充 CacheService 详细实现，包括 LRU 缓存、最大容量 1000 条、TTL 3600 秒、asyncio.Lock 保护	✅

🟢 Minor（建议实现阶段补充）

ID	问题	建议
m1	Wiki Skills 缺少触发条件定义	实现阶段补充每个 Skill 的触发条件
m2	增量更新算法缺少并发安全说明	实现阶段添加全局锁或页面级锁
m3	daily_update 工具缺少详细设计	实现阶段补充 "源新鲜度" 检查逻辑

---

三、新增内容（v1.1）

1. QueryService 完整设计（第 2.3 节）— 包括所有查询方法
2. MemoryBridgeTool 详细设计（第 2.2 节）— 包括接口和返回格式
3. aiosqlite Database 类（第 2.4 节）— 真正的异步支持
4. fix_dirty_states 恢复机制（第 2.4 节）— 启动时恢复
5. 完整 SQLite 表结构（第 3.3 节）— 包括索引优化
6. hot.md 生成算法（第 5.4 节）— 热点文件生成
7. 重试策略（第 7.3 节）— 指数退避重试
8. benchmark.py 设计（第 11 节）— 完整的基准测试
9. 修订记录（第 14 节）— 版本历史

新增内容（v1.2）

1. FTS5 表结构修正（第 3.3 节）— 删除重复定义，调整表创建顺序
2. WikiPage.source_tool 字段（第 3.1 节）— 用于 memory_bridge 功能
3. CacheService 详细实现（第 2.3 节）— LRU 缓存、最大容量、TTL、线程安全
4. wiki_pages.source_tool 列（第 3.3 节）— 支持按工具来源查询
5. idx_pages_source_tool 索引（第 3.3 节）— memory_bridge 查询优化

---

四、设计亮点

1. 真正的异步支持：使用 aiosqlite 而非简单的 sqlite3 包装
2. 完整的 FTS5 设计：包括外部内容表、索引优化、正确的表创建顺序
3. 可验证的性能目标：benchmark.py 参考 BitNet 实践
4. 健壮的错误处理：重试、降级、自动恢复
5. 与需求完全对齐：配置、Skills 优先级、数据模型
6. 内存安全缓存：LRU 缓存 + 最大容量限制 + TTL 过期

---

五、下一步行动

1. ✅ 设计文档修订完成（v1.2）
2. ✅ 两轮独立评审通过
3. 🚀 进入 Phase 3：编码实现

---

评审完成时间: 2026-06-26 评审类型: 独立背靠背评审（两轮）