diff --git a/docs/01-requirements-review.md b/docs/01-requirements-review.md new file mode 100644 index 0000000..89bb183 --- /dev/null +++ b/docs/01-requirements-review.md @@ -0,0 +1,105 @@ +# sanguo_llmwiki 需求文档评审报告 + +**文档路径**: `docs/01-requirements.md` + +**评审日期**: 2026-06-26 + +**评审人**: 独立需求评审专家 + +--- + +## 一、总体评价 + +**评级**: ⚠️ **有条件通过** + +需求文档在整体结构和核心功能方面较为完整,但在需求细节、验收标准、风险控制等方面存在多处不足,建议在进入设计阶段前进行补充完善。 + +--- + +## 二、问题清单 + +### 🔴 Critical(严重问题) + +| ID | 问题 | 位置 | 改进建议 | +|----|------|------|----------| +| **C1** | **性能目标缺乏可验证的基准测试** | 3.2 性能 | "查询性能提升 40-150 倍"缺乏对比基准。建议明确:(1)当前系统的基线性能数据;(2)测试环境(硬件、数据量);(3)测试方法 | +| **C2** | **增量更新机制的技术细节缺失** | 2.3 索引系统 | "增量更新"是核心功能,但未说明如何检测变化、如何处理删除/重命名、并发冲突处理。这是技术风险点 | +| **C3** | **SQLite 并发安全未提及** | 技术约束 | SQLite 的写入并发限制未说明。Wiki 索引可能同时被多个进程访问,需要明确 WAL 模式或其他策略 | +| **C4** | **语义搜索的技术实现未说明** | 2.1 MCP Server 功能 | `wiki_query` 提到"语义搜索",但未说明使用何种 embedding 模型、如何存储、如何更新索引 | + +### 🟡 Major(重要问题) + +| ID | 问题 | 位置 | 改进建议 | +|----|------|------|----------| +| **M1** | **MCP 与 Skill 的划分标准不清晰** | 2.1 & 2.2 | 为什么 `wiki_lint` 是 MCP 而 `wiki-ingest` 是 Skill?划分标准(频率、状态性、复杂度)需要明确说明 | +| **M2** | **"索引损坏可自动重建"缺乏具体方案** | 3.2 可靠性 | 如何检测损坏?重建的触发条件是什么?重建过程中系统是否可用? | +| **M3** | **MCP 服务崩溃恢复机制未说明** | 3.2 可靠性 | "自动恢复"是否指 systemd/pm2 监控?还是 MCP 协议层的重连?需要明确 | +| **M4** | **测试策略不完整** | 5.4 测试 | 单元/集成/E2E 的边界不清。E2E 测试是否需要真实的 Claude Code 环境?是否需要 mock MCP 协议? | +| **M5** | **配置管理未提及** | 技术约束 | Wiki 路径"可配置"但未说明配置文件位置、格式、环境变量支持 | +| **M6** | **与现有 21 个 Skills 的兼容性未说明** | 1.3 范围 | "不包含迁移",但新系统是否与旧 Skills 兼容共存?是否有数据迁移路径? | +| **M7** | **`cross_linker` 和 `tag_taxonomy` 的实现逻辑过于模糊** | 2.1 | 这些功能的算法复杂度高,需要更详细的需求描述(如:如何判断"缺失"的链接?标签冲突如何解决?) | + +### 🟢 Minor(次要问题) + +| ID | 问题 | 位置 | 改进建议 | +|----|------|------|----------| +| **U1** | **术语缺乏定义** | 全文 | "蒸馏"、"受控词表"、"hot.md" 等术语缺乏首次定义 | +| **U2** | **部署环境范围过窄** | 4.1 部署环境 | 仅提到 macOS,虽然明确但建议增加"未来扩展"说明 | +| **U3** | **项目里程碑缺乏时间估算** | 6. 项目里程碑 | 只有阶段划分,没有时间估计 | +| **U4** | **E2E 测试通过标准模糊** | 5.4 测试 | "E2E 测试通过"未定义测试场景数量和覆盖率 | + +--- + +## 三、改进建议 + +### 1. 需求完整性 + +**建议补充内容:** + +1. **数据模型章节**:描述 wiki 页面、索引、链接的实体关系 +2. **索引结构设计**:SQLite 表结构预览 +3. **错误处理策略**:各类失败场景的预期行为 +4. **日志与监控**:日志级别、关键指标 +5. **安全考虑**:虽然本地系统,但应说明权限控制 + +### 2. 需求清晰性 + +**建议明确:** + +1. `wiki_query` 的查询语法(是否支持布尔操作、通配符等) +2. `memory_bridge` 的"AI 工具来源"分类标准 +3. `wiki_synthesize` 的触发条件和输出模板 +4. 各功能的失败回退行为 + +### 3. 验收标准 + +**建议细化:** + +1. 性能测试应基于具体数据集(如:1353 页,平均大小 N KB) +2. 增加"兼容性验收":与现有 Skills 的互操作性 +3. 增加"可观测性验收":日志输出、健康检查接口 +4. 增加"边界测试":空 wiki、超长页面、特殊字符等 + +### 4. 风险与约束 + +**建议增加风险分析章节:** + +| 风险 | 影响 | 缓解措施 | +|------|------|----------| +| Wiki 路径挂载失败 | 系统不可用 | 启动时验证,提供友好错误提示 | +| 索引文件损坏 | 查询失败 | 自动重建 + 通知 | +| MCP 协议变更 | 兼容性问题 | 版本锁定 + 升级路径 | +| SQLite 性能退化 | 查询变慢 | 定期 VACUUM + 监控 | + +--- + +## 四、下一步行动 + +1. **作者处理**:根据评审意见修订需求文档 +2. **重新评审**:Critical 问题修复后重新提交评审 +3. **冻结需求**:评审通过后标记为 v1.1,进入设计阶段 + +--- + +*评审完成时间: 2026-06-26* +*评审类型: 独立背靠背评审*