sanguo_llmwiki/docs/02-design-review.md

sanguo_llmwiki 设计文档评审报告 v2

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

---

一、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 新增以下章节：

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 节）— 版本历史

---

三、设计亮点

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

---

四、下一步行动

1. ✅ 设计文档修订完成
2. ✅ 评审通过
3. 🚀 进入 Phase 3：编码实现

---

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