claude_dev
67a53d82de
- M1: 修复 FTS5 表结构语法错误（删除重复定义，调整表创建顺序） - M2: 在 WikiPage 中添加 source_tool 字段，解决 memory_bridge 的 tool_name 数据来源问题 - M3: 补充 CacheService 详细实现（LRU 缓存 + 最大容量 1000 条 + TTL 3600 秒 + asyncio.Lock） 两轮独立评审均通过，设计文档 v1.2 完成。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
105 lines
4.8 KiB
Markdown
105 lines
4.8 KiB
Markdown
# 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*
|
||
*评审类型: 独立背靠背评审（两轮）*
|