docs: add requirements review report (Phase 1)
- 独立 agent 评审完成 - 评级: 有条件通过 - 4 Critical, 7 Major, 4 Minor 问题 - 评审报告已提交 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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*
|
||||
*评审类型: 独立背靠背评审*
|
||||
Reference in New Issue
Block a user