diff --git a/README.md b/README.md index f11e5e5..91a1053 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## 状态 -🚧 开发中 - Phase 2: 设计评审 +🚧 开发中 - Phase 3: 编码实现 ## 项目概述 @@ -53,7 +53,9 @@ python -m mcp_server.main ## 文档 - [需求文档 v1.1](docs/01-requirements.md) ✅ 评审通过 -- [设计文档 v1.0](docs/02-design.md) 🚧 评审中 +- [需求评审报告](docs/01-requirements-review.md) ✅ 通过 +- [设计文档 v1.1](docs/02-design.md) ✅ 评审通过 +- [设计评审报告](docs/02-design-review.md) ✅ 通过 ## 开发流程 diff --git a/docs/02-design-review.md b/docs/02-design-review.md new file mode 100644 index 0000000..0e500c9 --- /dev/null +++ b/docs/02-design-review.md @@ -0,0 +1,77 @@ +# 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* +*评审类型: 独立背靠背评审* diff --git a/docs/02-design.md b/docs/02-design.md index 028bd8a..b67309d 100644 --- a/docs/02-design.md +++ b/docs/02-design.md @@ -25,12 +25,12 @@ │ │ │ │ ┌───────────────────────▼───────────────────────────────┐ │ │ │ Tool Layer │ │ -│ │ query │ status │ lint │ linker │ taxonomy │ synthesize│ │ +│ │ query │ memory │ status │ lint │ linker │ taxonomy │ synthesize│ │ │ └───────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌───────────────────────▼───────────────────────────────┐ │ │ │ Service Layer │ │ -│ │ indexer │ cache │ graph │ parser │ │ +│ │ indexer │ query │ cache │ graph │ parser │ │ │ └───────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌───────────────────────▼───────────────────────────────┐ │ @@ -95,56 +95,205 @@ class MCPServer: | wiki_synthesize | concepts, threshold | synthesis | SynthesizeTool | | daily_update | - | updated, new | DailyTool | +**MemoryBridgeTool 详细设计：** + +```python +class MemoryBridgeTool: + """memory_bridge 工具实现""" + + async def handle(self, tool_name: str, date_range: str) -> dict: + """ + 按 AI 工具来源浏览和对比 wiki 知识 + + Args: + tool_name: AI 工具名称（如 "claude", "web_reader", "gitea"） + date_range: 日期范围（如 "2024-01-01:2024-12-31"） + + Returns: + { + "entries": [ + { + "path": "practices/moziplus-orchestration.md", + "title": "moziplus 编排实践", + "summary": "...", + "updated_at": "2024-06-15", + "relevance_score": 0.85 + } + ], + "total": 12, + "tool_name": "claude", + "date_range": "2024-01-01:2024-12-31" + } + """ + # 1. 查询符合条件的 wiki 页面 + # 2. 按 tool_name 和 date_range 过滤 + # 3. 计算相关性分数 + # 4. 返回结果列表 +``` + ### 2.3 Service Layer **IndexerService（索引服务）：** ```python class IndexerService: - def index_page(self, path: str) -> None - def index_batch(self, paths: List[str]) -> None - def rebuild_index(self) -> None - def get_dirty_pages(self) -> List[str] # 增量更新 + async def index_page(self, path: str) -> None + async def index_batch(self, paths: List[str]) -> None + async def rebuild_index(self) -> None + async def get_dirty_pages(self) -> List[str] # 增量更新 +``` + +**QueryService（查询服务）：** +```python +class QueryService: + """查询服务 - 负责所有查询逻辑""" + + def __init__(self, db: Database, cache: CacheService): + self.db = db + self.cache = cache + + async def search(self, query: str, limit: int) -> List[WikiPage]: + """FTS5 全文搜索""" + # 1. 检查缓存 + cache_key = f"search:{query}:{limit}" + cached = await self.cache.get(cache_key) + if cached: + return cached + + # 2. FTS5 搜索 + results = await self.db.fts_search(query, limit) + + # 3. 缓存结果 + await self.cache.set(cache_key, results, ttl=3600) + + return results + + async def search_by_tags(self, tags: List[str]) -> List[WikiPage]: + """按标签搜索""" + return await self.db.search_by_tags(tags) + + async def get_page(self, path: str) -> Optional[WikiPage]: + """获取单个页面""" + return await self.db.get_page(path) + + async def get_links(self, path: str) -> Set[str]: + """获取页面的出链""" + return await self.db.get_links(path) + + async def get_backlinks(self, path: str) -> Set[str]: + """获取页面的反向链接""" + return await self.db.get_backlinks(path) + + async def find_orphans(self) -> Set[str]: + """查找孤立页面（无反向链接）""" + all_pages = await self.db.get_all_pages() + orphans = set() + for page in all_pages: + backlinks = await self.db.get_backlinks(page.path) + if not backlinks and page.path != "index.md": + orphans.add(page.path) + return orphans ``` **CacheService（缓存服务）：** ```python class CacheService: - def get(self, key: str) -> Optional[Any] - def set(self, key: str, value: Any, ttl: int) - def invalidate(self, pattern: str) + async def get(self, key: str) -> Optional[Any] + async def set(self, key: str, value: Any, ttl: int) + async def invalidate(self, pattern: str) ``` **GraphService（图服务）：** ```python class GraphService: - def get_links(self, path: str) -> Set[str] - def get_backlinks(self, path: str) -> Set[str] - def find_orphans(self) -> Set[str] - def find_missing_links(self) -> List[Tuple[str, str]] + async def get_links(self, path: str) -> Set[str] + async def get_backlinks(self, path: str) -> Set[str] + async def find_orphans(self) -> Set[str] + async def find_missing_links(self) -> List[Tuple[str, str]] ``` **ParserService（解析服务）：** ```python class ParserService: - def parse_frontmatter(self, content: str) -> dict - def extract_links(self, content: str) -> List[str] - def validate_page(self, path: str) -> List[str] # 返回问题列表 + async def parse_frontmatter(self, content: str) -> dict + async def extract_links(self, content: str) -> List[str] + async def validate_page(self, path: str) -> List[str] # 返回问题列表 ``` ### 2.4 Storage Layer -**数据库连接（带并发保护）：** +**数据库连接（使用 aiosqlite 实现异步）：** + ```python +import aiosqlite +import asyncio + class Database: - def __init__(self, path: str): - self.conn = sqlite3.connect(path, check_same_thread=False) - self.conn.execute("PRAGMA journal_mode=WAL") - self.conn.execute("PRAGMA busy_timeout=10000") # 10s - self.lock = asyncio.Lock() + """SQLite 数据库封装，使用 aiosqlite 实现真正的异步支持""" - async def execute(self, sql: str, params: tuple): - async with self.lock: - return self.conn.execute(sql, params) + def __init__(self, path: str): + self.path = path + self._conn = None + self._lock = asyncio.Lock() + + async def connect(self): + """建立连接，启用 WAL 模式和并发保护""" + self._conn = await aiosqlite.connect(self.path) + await self._conn.execute("PRAGMA journal_mode=WAL") + await self._conn.execute("PRAGMA busy_timeout=10000") # 10s + await self._conn.execute("PRAGMA synchronous=NORMAL") + await self._conn.commit() + + async def execute(self, sql: str, params: tuple = ()): + """执行 SQL（带写入锁）""" + async with self._lock: + cursor = await self._conn.execute(sql, params) + await self._conn.commit() + return cursor + + async def fetch_all(self, sql: str, params: tuple = ()): + """查询所有结果（读操作无需锁，WAL 自动处理）""" + cursor = await self._conn.execute(sql, params) + return await cursor.fetchall() + + async def fts_search(self, query: str, limit: int) -> List[WikiPage]: + """FTS5 全文搜索""" + sql = """ + SELECT path, title, category, tags, summary, + lifecycle, created_at, updated_at, indexed_at + FROM wiki_fts + WHERE wiki_fts MATCH ? + ORDER BY rank + LIMIT ? + """ + rows = await self.fetch_all(sql, (query, limit)) + return [self._row_to_page(row) for row in rows] + + async def close(self): + """关闭连接""" + if self._conn: + await self._conn.close() +``` + +**fix_dirty_states 恢复机制：** + +```python +async def fix_dirty_states(db: Database): + """启动时清理可能的脏状态""" + try: + # 1. 检查 WAL 文件是否损坏 + await db.execute("PRAGMA wal_checkpoint(PASSIVE)") + + # 2. 检查数据库完整性 + result = await db.fetch_all("PRAGMA integrity_check") + if result and result[0][0] != "ok": + raise Exception(f"数据库损坏: {result}") + + # 3. 清理可能的锁文件 + # （WAL 模式下通常不需要） + + except Exception as e: + logger.warning(f"检测到索引问题，尝试重建: {e}") + await rebuild_index(db) ``` --- @@ -163,7 +312,6 @@ class WikiPage: summary: str # 摘要（≤200 字符） content_hash: str # MD5 哈希 lifecycle: str # draft/verified/archived/disputed - sources: List[str] # 来源页面 created_at: datetime updated_at: datetime indexed_at: datetime @@ -172,6 +320,8 @@ class WikiPage: return (datetime.now() - self.updated_at).days > days ``` +> **注：** 删除了 `sources` 字段（v1.0 遗留问题），页面来源可通过 backlinks 推断 + ### 3.2 WikiIndex（索引模型） ```python @@ -193,6 +343,105 @@ class IndexStats: dirty_pages: int ``` +### 3.3 SQLite 表结构（完整设计） + +**页面索引表：** +```sql +CREATE TABLE wiki_pages ( + path TEXT PRIMARY KEY, + title TEXT NOT NULL, + category TEXT, + tags TEXT, -- JSON 数组: ["tag1", "tag2"] + summary TEXT, + content_hash TEXT NOT NULL, + lifecycle TEXT DEFAULT 'draft', -- draft|verified|archived|disputed + created_at TIMESTAMP, + updated_at TIMESTAMP, + indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- 索引优化 +CREATE INDEX idx_pages_category ON wiki_pages(category); +CREATE INDEX idx_pages_lifecycle ON wiki_pages(lifecycle); +CREATE INDEX idx_pages_updated ON wiki_pages(updated_at); +``` + +**FTS5 全文搜索表：** +```sql +-- 使用 FTS5 创建全文搜索虚拟表 +CREATE VIRTUAL TABLE wiki_fts USING fts5( + path UNINDEXED, -- 路径不参与全文搜索 + title, -- 标题参与搜索 + content, -- 内容参与搜索 + summary, -- 摘要参与搜索 + tokenize = 'porter unicode61' -- 英文词干 + Unicode 分词 +); + +-- 内容表（FTS5 外部内容表） +CREATE TABLE wiki_content ( + path TEXT PRIMARY KEY, + content TEXT NOT NULL +); + +-- 将 FTS5 关联到内容表 +CREATE VIRTUAL TABLE wiki_fts USING fts5( + path UNINDEXED, + title, + content, + summary, + content=wiki_content, + content_rowid=rowid +); +``` + +**链接关系表：** +```sql +CREATE TABLE wiki_links ( + source TEXT NOT NULL, + target TEXT NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (source, target) +); + +-- 反向链接查询优化 +CREATE INDEX idx_links_target ON wiki_links(target); +``` + +**标签索引表：** +```sql +CREATE TABLE wiki_tags ( + tag TEXT PRIMARY KEY, + count INTEGER DEFAULT 0, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- 页面-标签关联表（多对多） +CREATE TABLE wiki_page_tags ( + path TEXT NOT NULL, + tag TEXT NOT NULL, + PRIMARY KEY (path, tag), + FOREIGN KEY (path) REFERENCES wiki_pages(path) ON DELETE CASCADE, + FOREIGN KEY (tag) REFERENCES wiki_tags(tag) ON DELETE CASCADE +); + +CREATE INDEX idx_page_tags_tag ON wiki_page_tags(tag); +``` + +**索引元数据表：** +```sql +CREATE TABLE wiki_meta ( + key TEXT PRIMARY KEY, + value TEXT, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- 存储索引状态 +INSERT INTO wiki_meta (key, value) VALUES + ('index_version', '1'), + ('last_full_reindex', ''), + ('page_count', '0'); +``` + --- ## 4. 接口设计 @@ -214,6 +463,20 @@ class IndexStats: } ``` +**memory_bridge:** +```json +{ + "name": "memory_bridge", + "inputSchema": { + "type": "object", + "properties": { + "tool_name": {"type": "string"}, + "date_range": {"type": "string"} + } + } +} +``` + **wiki_status:** ```json { @@ -235,9 +498,11 @@ async def get_dirty_pages() -> List[str] # QueryService async def search(query: str, limit: int) -> List[WikiPage] async def search_by_tags(tags: List[str]) -> List[WikiPage] +async def get_page(path: str) -> Optional[WikiPage] # GraphService async def get_links(path: str) -> Set[str] +async def get_backlinks(path: str) -> Set[str] async def find_orphans() -> Set[str] ``` @@ -249,36 +514,41 @@ async def find_orphans() -> Set[str] ```python async def incremental_update(): + """增量更新索引 - 只处理变化的页面""" # 1. 获取所有 wiki 页面 all_pages = scan_wiki_vault() # 2. 检查每个页面的哈希 for page in all_pages: current_hash = md5(page.content) - stored = db.get_page_hash(page.path) + stored = await db.get_page_hash(page.path) if stored != current_hash: # 3. 只重索引变化的页面 await index_page(page) # 4. 处理删除的页面 - indexed_paths = db.get_all_indexed_paths() + indexed_paths = await db.get_all_indexed_paths() for path in indexed_paths: if path not in all_pages: - db.delete_page(path) + await db.delete_page(path) ``` ### 5.2 查询算法 ```python async def wiki_query(query: str, tags: List[str], limit: int): + """组合查询算法""" # 1. FTS5 全文搜索 if query: - results = fts_search(query, limit) + results = await query_service.search(query, limit) # 2. 标签过滤 if tags: - results = filter_by_tags(results, tags) + results = await query_service.search_by_tags(tags) + if query: + # 交叉引用：全文搜索结果中也需匹配标签 + results = [r for r in results if any(t in r.tags for t in tags)] # 3. 按相关性排序 sorted_results = rank_by_relevance(results, query) @@ -291,8 +561,9 @@ async def wiki_query(query: str, tags: List[str], limit: int): ```python async def find_missing_links(): + """查找缺失的交叉引用""" # 1. 获取所有页面内容 - pages = load_all_pages() + pages = await load_all_pages() # 2. 提取所有 [[wikilinks]] all_links = extract_all_links(pages) @@ -301,12 +572,43 @@ async def find_missing_links(): missing = [] for source, targets in all_links.items(): for target in targets: - if not page_exists(target): + if not await page_exists(target): missing.append((source, target)) return missing ``` +### 5.4 hot.md 生成算法 + +```python +async def generate_hot_md(): + """生成热点文件 - 记录最近活动和关键发现""" + # 1. 获取最近更新的页面（7 天内） + recent_pages = await db.get_recent_pages(days=7) + + # 2. 获取新增标签 + new_tags = await db.get_new_tags(days=7) + + # 3. 检测新的孤立页面（可能需要链接） + orphans = await query_service.find_orphans() + + # 4. 生成 markdown + hot_content = f"""# Wiki Hot - {datetime.now().strftime('%Y-%m-%d')} + +## 最近更新 +{format_page_list(recent_pages)} + +## 新增标签 +{format_tag_list(new_tags)} + +## 待链接页面 +{format_orphan_list(orphans)} +""" + + # 5. 写入 hot.md + await write_file("hot.md", hot_content) +``` + --- ## 6. 配置设计 @@ -329,6 +631,7 @@ performance: query_timeout_ms: 5000 cache_ttl_seconds: 3600 fts_cache_size_mb: 100 + max_concurrent_indexing: 5 logging: level: "INFO" @@ -343,6 +646,7 @@ WIKI_VAULT_PATH=/custom/path WIKI_INDEX_PATH=/custom/index.db MCP_MODE=sse LOG_LEVEL=DEBUG +MAX_CONCURRENT_INDEXING=10 ``` --- @@ -359,6 +663,7 @@ LOG_LEVEL=DEBUG | 页面解析失败 | 记录日志 + 跳过该页面 | | MCP 协议错误 | 返回标准错误格式 | | 查询超时 | 返回部分结果 + WARN | +| 重试失败 | 降级为文件扫描（性能降低） | ### 7.2 错误响应格式 @@ -373,6 +678,21 @@ LOG_LEVEL=DEBUG } ``` +### 7.3 重试策略 + +```python +async def execute_with_retry(db: Database, sql: str, params: tuple, max_retries: int = 2): + """带重试的数据库操作""" + for attempt in range(max_retries): + try: + return await db.execute(sql, params) + except aiosqlite.OperationalError as e: + if "database is locked" in str(e) and attempt < max_retries - 1: + await asyncio.sleep(0.1 * (2 ** attempt)) # 指数退避 + continue + raise +``` + --- ## 8. 安全考虑 @@ -402,6 +722,7 @@ LOG_LEVEL=DEBUG ### 9.3 并发优化 - SQLite WAL 模式 +- aiosqlite 真正的异步支持 - asyncio.Lock 写入串行化 - busy_timeout=10s @@ -434,55 +755,166 @@ description: > ... ``` -### 10.2 Skills 列表 +### 10.2 Skills 列表（与需求对齐） **优先级 P0（核心）：** -1. wiki-setup - 初始化 wiki +1. wiki-setup - 初始化 wiki vault 2. wiki-ingest - 蒸馏文档 3. wiki-capture - 保存对话 **优先级 P1（重要）：** 4. wiki-rebuild - 重建 wiki -5. data-ingest - 录入数据 +5. data-ingest - 录入非结构化数据 6. ingest-url - 抓取 URL -7. wiki-agent - 录入历史 -8. wiki-export - 导出 +7. wiki-export - 导出知识图谱 **优先级 P2（可选）：** -9. wiki-research - 研究 -10. impl-validator - 验证 -11. graph-colorize - 着色 +8. wiki-research - 多轮搜索研究 +9. impl-validator - 验证实现 +10. graph-colorize - 着色 +11. wiki-agent - 录入历史 --- -## 11. 测试设计 +## 11. 性能基准测试 -### 11.1 单元测试 +### 11.1 benchmark.py 设计 + +```python +#!/usr/bin/env python3 +""" +Wiki MCP Server 性能基准测试 +参考 BitNet 实践 - 可验证的性能指标 +""" + +import asyncio +import time +import statistics +from typing import List + +class Benchmark: + """基准测试类""" + + def __init__(self, query_service: QueryService): + self.query_service = query_service + self.results = [] + + async def benchmark_query(self, query: str, iterations: int = 100) -> dict: + """测试查询性能""" + latencies = [] + + for _ in range(iterations): + start = time.perf_counter() + await self.query_service.search(query, limit=10) + end = time.perf_counter() + latencies.append((end - start) * 1000) # ms + + return { + "query": query, + "iterations": iterations, + "avg_ms": statistics.mean(latencies), + "p50_ms": statistics.median(latencies), + "p99_ms": statistics.quantiles(latencies, n=100)[98], + "min_ms": min(latencies), + "max_ms": max(latencies), + "qps": iterations / sum(latencies) * 1000 + } + + async def benchmark_indexing(self, page_count: int = 1000) -> dict: + """测试索引性能""" + start = time.perf_counter() + + # 模拟索引 N 个页面 + pages = generate_mock_pages(page_count) + await indexer_service.index_batch(pages) + + end = time.perf_counter() + total_ms = (end - start) * 1000 + + return { + "page_count": page_count, + "total_ms": total_ms, + "avg_ms_per_page": total_ms / page_count + } + + async def run_all(self) -> dict: + """运行所有基准测试""" + results = {} + + # 1. 查询性能测试 + queries = [ + "SQLite 并发", + "性能优化", + "架构设计" + ] + for query in queries: + results[f"query_{query}"] = await self.benchmark_query(query) + + # 2. 索引性能测试 + results["indexing"] = await self.benchmark_indexing() + + # 3. 内存占用测试 + results["memory"] = measure_memory_usage() + + return results + +# 基准测试目标（参考需求 4.1） +TARGETS = { + "query_p99_ms": 100, # P99 延迟 < 100ms + "fts_search_p99_ms": 200, # 全文搜索 < 200ms + "index_avg_ms_per_page": 10, # 索引 < 10ms/页 + "memory_mb": 500 # 内存 < 500MB +} + +if __name__ == "__main__": + # 运行基准测试 + benchmark = Benchmark(query_service) + results = asyncio.run(benchmark.run_all()) + + # 输出结果 + print("=== Wiki MCP Server Benchmark ===") + print(json.dumps(results, indent=2)) + + # 检查是否达标 + for key, target in TARGETS.items(): + actual = results.get(key) + if actual and actual > target: + print(f"WARNING: {key} ({actual}) exceeds target ({target})") +``` + +--- + +## 12. 测试设计 + +### 12.1 单元测试 覆盖所有 Service 层的核心逻辑： - IndexerService 测试 - QueryService 测试 - GraphService 测试 - ParserService 测试 +- Database 并发测试（模拟并发写入） -### 11.2 集成测试 +### 12.2 集成测试 - MCP 协议层测试（使用 MCP SDK mock） - SQLite 操作测试 - Wiki 解析测试 +- FTS5 搜索测试 -### 11.3 E2E 测试 +### 12.3 E2E 测试 使用真实 wiki 数据集测试： - 查询场景 - 搜索场景 - 索引更新场景 +- 并发查询场景 --- -## 12. 部署设计 +## 13. 部署设计 -### 12.1 开发部署 +### 13.1 开发部署 ```bash # 手动启动 @@ -490,7 +922,7 @@ cd ~/.openclaw/sanguo_projects/sanguo_llmwiki python -m mcp_server.main ``` -### 12.2 生产部署 +### 13.2 生产部署 ```bash # PM2 配置 @@ -506,7 +938,8 @@ module.exports = { watch: false, max_memory_restart: '500M', env: { - PYTHONUNBUFFERED: '1' + PYTHONUNBUFFERED: '1', + LOG_LEVEL: 'INFO' } }] } @@ -516,7 +949,7 @@ pm2 start ecosystem.config.cjs pm2 save ``` -### 12.3 MCP 配置 +### 13.3 MCP 配置 **stdio 模式（开发）：** ```json @@ -546,7 +979,36 @@ pm2 save } ``` +> **注：** SSE 模式需要 MCP Server 实现 HTTP 端点，v1.0 暂不实现，v1.1 预留接口 + --- -*文档版本：v1.0* +## 14. 修订记录 + +### v1.1（2026-06-26） + +**修复的问题：** + +**Critical（必须修复）：** +- ✅ **C1**: 补充 QueryService 模块设计（第 2.3 节） +- ✅ **C2**: 补充完整的 SQLite 表结构设计（第 3.3 节） + +**Major（建议修复）：** +- ✅ **M1**: Database 类改用 aiosqlite 实现真正的异步（第 2.4 节） +- ✅ **M2**: 补充 MemoryBridgeTool 详细设计（第 2.2 节） +- ✅ **M3**: 配置项与需求对齐（第 6.1 节） +- ✅ **M4**: Wiki Skills 优先级与需求对齐（第 10.2 节） +- ✅ **M5**: 新增 benchmark.py 设计（第 11 节） + +**Minor（可选改进）：** +- ✅ **m1**: 删除 WikiPage.sources 字段并添加说明 +- ✅ **m2**: 补充 hot.md 生成算法（第 5.4 节） +- ✅ **m3**: 补充重试策略和降级方案（第 7.3 节） +- ✅ **m4**: 明确 SSE 模式为 v1.1 预留（第 13.3 节） +- ✅ **m5**: 补充 Python 3.11+ 版本要求（需求文档） + +--- + +*文档版本：v1.1* *创建时间：2026-06-26* +*更新时间：2026-06-26*