claude_dev
ed58d12c7e
根据 wiki 优秀实践修订需求文档： 修复 Critical 问题： - C1: 补充性能基准测试方案（参考 BitNet 实践） - C2: 详细说明增量更新机制和索引结构 - C3: 明确 SQLite 并发策略（参考三国团队经验） - C4: 明确使用 FTS5，语义搜索留作扩展 新增章节： - 术语表、数据模型、错误处理、日志监控 - 风险分析、测试策略、配置管理 评审结果：✅ 通过 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
# sanguo_llmwiki 需求文档
|
||
|
||
## 1. 项目背景
|
||
|
||
### 1.1 现状
|
||
- 用户已有 21 个 Wiki Skills，功能完整但分散
|
||
- Wiki 位于 `/Volumes/KnowledgeBase/wiki-vault`，约 1353 页
|
||
- 高频查询操作（wiki-query）性能较差，每次都需全文扫描
|
||
- 缺乏统一的索引缓存机制
|
||
|
||
### 1.2 目标
|
||
构建混合架构 Wiki 系统，将高频查询和维护功能 MCP 化，保留一次性操作为 Skill，实现：
|
||
- 查询性能提升 40-150 倍
|
||
- 统一的知识管理接口
|
||
- 持久化的索引缓存
|
||
|
||
### 1.3 范围
|
||
**包含：**
|
||
- Wiki MCP Server（Python 实现）
|
||
- 11 个一次性操作 Skills
|
||
- SQLite 索引系统
|
||
- 完整的测试和文档
|
||
|
||
**不包含：**
|
||
- 现有 21 个 Skills 的迁移（OpenClaw 专用）
|
||
- Obsidian 客户端集成
|
||
- Wiki 内容的编辑功能
|
||
|
||
---
|
||
|
||
## 2. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| **蒸馏** | 将原始文档转化为结构化 wiki 页面的过程 |
|
||
| **受控词表** | 预定义的标签集合，用于保持标签一致性 |
|
||
| **hot.md** | Wiki 热点文件，记录最近活动和关键发现 |
|
||
| **FTS5** | SQLite 全文搜索扩展 |
|
||
| **WAL** | SQLite Write-Ahead Log 模式，提升并发性能 |
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 MCP Server 功能
|
||
|
||
| 功能 | 描述 | 优先级 |
|
||
|------|------|--------|
|
||
| **wiki_query** | 基于 SQLite 索引查询 wiki，支持关键词（FTS5）和标签搜索 | P0 |
|
||
| **memory_bridge** | 按 AI 工具来源浏览和对比 wiki 知识 | P1 |
|
||
| **wiki_status** | 显示 wiki 当前状态（页面数、待处理项、增量差异）| P0 |
|
||
| **wiki_lint** | 审计 wiki 健康（格式、链接、frontmatter 规范）| P1 |
|
||
| **cross_linker** | 扫描 wiki，自动发现缺失的交叉引用 | P2 |
|
||
| **tag_taxonomy** | 用受控词表强制标签一致性 | P2 |
|
||
| **wiki_synthesize** | 发现跨概念的综合分析机会，生成 synthesis 页面 | P2 |
|
||
| **daily_update** | 日常维护（检查源新鲜度、更新 index、重新生成 hot.md）| P1 |
|
||
|
||
**MCP/Skill 划分原则：**
|
||
- **MCP**：高频访问、需要状态、持续运行的功能（查询、维护、分析）
|
||
- **Skill**：一次性任务、触发式操作、无需状态的功能（录入、导出、研究）
|
||
|
||
### 3.2 Wiki Skills 功能（保留为 Skill）
|
||
|
||
| Skill | 描述 | 优先级 |
|
||
|-------|------|--------|
|
||
| **wiki-setup** | 初始化新 wiki vault，创建目录结构 | P0 |
|
||
| **wiki-rebuild** | 归档现有 wiki 并重建，或从历史备份恢复 | P1 |
|
||
| **wiki-ingest** | 将文档蒸馏为互联的 wiki 页面 | P0 |
|
||
| **data-ingest** | 录入非结构化数据（对话记录、日志等）| P1 |
|
||
| **ingest-url** | 抓取 URL 内容并蒸馏入 wiki | P1 |
|
||
| **wiki-capture** | 将当前对话保存为结构化 wiki 笔记 | P1 |
|
||
| **wiki-agent** | 从特定 AI agent 的历史记录中定向录入 | P2 |
|
||
| **wiki-export** | 导出知识图谱为结构化格式 | P1 |
|
||
| **wiki-research** | 多轮 web 搜索 → 综合发现 → 存入 wiki | P2 |
|
||
| **impl-validator** | 验证实现是否符合其声明目标 | P2 |
|
||
| **graph-colorize** | 重写 Obsidian graph.json 按分类着色节点 | P2 |
|
||
|
||
### 3.3 索引系统
|
||
|
||
| 功能 | 描述 | 优先级 |
|
||
|------|------|--------|
|
||
| **页面索引** | 索引所有 wiki 页面的元数据和内容 | P0 |
|
||
| **全文搜索** | 基于 FTS5 的全文搜索能力 | P0 |
|
||
| **链接图** | 记录页面间的链接关系 | P1 |
|
||
| **增量更新** | 只更新变化的页面，避免全量重建 | P0 |
|
||
| **标签索引** | 按标签快速查找页面 | P1 |
|
||
|
||
**索引结构设计（SQLite）：**
|
||
|
||
```sql
|
||
-- 页面索引表
|
||
CREATE TABLE wiki_pages (
|
||
path TEXT PRIMARY KEY,
|
||
title TEXT,
|
||
category TEXT,
|
||
tags TEXT,
|
||
summary TEXT,
|
||
content_hash TEXT,
|
||
lifecycle TEXT,
|
||
created_at TIMESTAMP,
|
||
updated_at TIMESTAMP,
|
||
indexed_at TIMESTAMP
|
||
);
|
||
|
||
-- 全文搜索表（FTS5）
|
||
CREATE VIRTUAL TABLE wiki_fts USING fts5(
|
||
path, title, content, summary
|
||
);
|
||
|
||
-- 链接关系表
|
||
CREATE TABLE wiki_links (
|
||
source TEXT,
|
||
target TEXT,
|
||
PRIMARY KEY (source, target)
|
||
);
|
||
|
||
-- 标签索引
|
||
CREATE TABLE wiki_tags (
|
||
tag TEXT PRIMARY KEY,
|
||
count INTEGER
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 非功能需求
|
||
|
||
### 4.1 性能
|
||
**基线测试环境：**
|
||
- 数据集：1353 页，平均 5KB/页
|
||
- 硬件：MacOS M1/M2，16GB RAM
|
||
- 当前系统基线：查询 10 页 ~2s，全文搜索 ~5s
|
||
|
||
**性能目标：**
|
||
- 查询 10 页响应时间 < 100ms
|
||
- 全文搜索响应时间 < 200ms
|
||
- 索引 1000 页耗时 < 10s
|
||
- 增量更新单页耗时 < 50ms
|
||
|
||
**基准测试方法（参考 BitNet 实践）：**
|
||
- 内置 `benchmark.py` 测量查询/搜索性能
|
||
- 关键指标：QPS、P99 延迟、内存占用
|
||
- 部署前必跑基准测试
|
||
|
||
### 4.2 可靠性
|
||
- SQLite 写入失败不影响原始 wiki
|
||
- 索引损坏可自动重建
|
||
- MCP 服务崩溃可自动恢复（PM2 监控）
|
||
|
||
**SQLite 并发保护（参考三国团队实战经验）：**
|
||
1. `asyncio.Lock` 写入串行化（进程内）
|
||
2. `busy_timeout=10s` 跨进程等待
|
||
3. `fix_dirty_states()` 启动恢复
|
||
4. 启用 WAL 模式提升并发性能
|
||
|
||
**索引恢复方案：**
|
||
- 检测：启动时验证索引完整性
|
||
- 触发：检测到损坏或超时未更新
|
||
- 重建：全量扫描 wiki 并重建索引
|
||
- 可用性：重建期间降级为文件扫描（性能降低）
|
||
|
||
### 4.3 可维护性
|
||
- 代码覆盖率 > 80%
|
||
- 关键功能有集成测试
|
||
- 有完整的 API 文档
|
||
|
||
### 4.4 兼容性
|
||
- 兼容 Claude Code MCP 协议
|
||
- 兼容 Obsidian Markdown 格式
|
||
- 支持 Python 3.11+
|
||
- 与现有 21 个 Wiki Skills 共存（无冲突）
|
||
|
||
---
|
||
|
||
## 5. 技术约束
|
||
|
||
### 5.1 部署环境
|
||
- macOS（开发和生产）
|
||
- Wiki 路径：`/Volumes/KnowledgeBase/wiki-vault`（默认，可配置）
|
||
|
||
### 5.2 技术栈
|
||
- Python 3.11+
|
||
- SQLite 3.38+（支持 FTS5）
|
||
- MCP SDK（最新版）
|
||
|
||
### 5.3 配置管理
|
||
**配置优先级：** 环境变量 > 配置文件 > 默认值
|
||
|
||
**配置文件位置：** `~/.sanguo-llmwiki/config.yaml`
|
||
|
||
**配置项：**
|
||
```yaml
|
||
wiki:
|
||
vault_path: "/Volumes/KnowledgeBase/wiki-vault"
|
||
index_path: "~/.sanguo-llmwiki/index.db"
|
||
|
||
mcp:
|
||
mode: "stdio" # stdio 或 SSE
|
||
host: "localhost"
|
||
port: 8080
|
||
|
||
performance:
|
||
max_page_size_kb: 500
|
||
query_timeout_ms: 5000
|
||
```
|
||
|
||
### 5.4 外部依赖
|
||
- Gitea MCP Server 作为参考实现（stdio 模式）
|
||
- Claude Code Skills 规范
|
||
|
||
---
|
||
|
||
## 6. 数据模型
|
||
|
||
### 6.1 Wiki 页面模型
|
||
|
||
```python
|
||
@dataclass
|
||
class WikiPage:
|
||
path: str # wiki 相对路径
|
||
title: str # 标题
|
||
category: str # 分类
|
||
tags: List[str] # 标签列表
|
||
summary: str # 摘要
|
||
content_hash: str # 内容哈希（MD5）
|
||
lifecycle: str # 生命周期状态
|
||
created_at: datetime
|
||
updated_at: datetime
|
||
indexed_at: datetime
|
||
```
|
||
|
||
### 6.2 索引模型
|
||
|
||
```python
|
||
@dataclass
|
||
class WikiIndex:
|
||
pages: Dict[str, WikiPage]
|
||
links: Dict[str, Set[str]] # source -> {targets}
|
||
tags: Dict[str, Set[str]] # tag -> {pages}
|
||
fts_index: FTS5Index
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 错误处理策略
|
||
|
||
| 错误场景 | 预期行为 |
|
||
|----------|----------|
|
||
| Wiki 路径不存在 | 启动失败，友好错误提示 |
|
||
| 索引文件损坏 | 自动重建 + 通知 |
|
||
| MCP 协议错误 | 记录日志 + 返回标准错误 |
|
||
| SQLite 写入失败 | 回滚事务 + 重试一次 |
|
||
| 页面解析失败 | 记录日志 + 跳过该页面 |
|
||
|
||
---
|
||
|
||
## 8. 日志与监控
|
||
|
||
### 8.1 日志级别
|
||
- **DEBUG**：索引操作详情
|
||
- **INFO**：正常操作（查询、更新）
|
||
- **WARN**：降级操作（索引损坏降级为文件扫描）
|
||
- **ERROR**：操作失败
|
||
|
||
### 8.2 关键指标
|
||
- QPS（查询每秒）
|
||
- P99 延迟
|
||
- 索引大小
|
||
- 缓存命中率
|
||
|
||
---
|
||
|
||
## 9. 风险分析
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|----------|
|
||
| Wiki 路径挂载失败 | 系统不可用 | 启动时验证，友好错误提示 |
|
||
| 索引文件损坏 | 查询失败 | 自动重建 + 降级为文件扫描 |
|
||
| MCP 协议变更 | 兼容性问题 | 版本锁定 + 升级路径 |
|
||
| SQLite 性能退化 | 查询变慢 | 定期 VACUUM + 监控 |
|
||
| 并发写入冲突 | 数据损坏 | asyncio.Lock + WAL + 事务 |
|
||
|
||
---
|
||
|
||
## 10. 验收标准
|
||
|
||
### 10.1 MCP Server
|
||
- [ ] 所有 8 个 MCP Tools 可正常调用
|
||
- [ ] wiki_query 返回结果准确，带 [[wikilink]] 引用
|
||
- [ ] 索引更新后查询结果实时生效
|
||
- [ ] MCP 服务崩溃后可自动重启（PM2）
|
||
|
||
### 10.2 Wiki Skills
|
||
- [ ] 11 个 Skills 可独立触发
|
||
- [ ] wiki-ingest 能正确蒸馏文档
|
||
- [ ] wiki-capture 能保存当前对话
|
||
|
||
### 10.3 性能
|
||
- [ ] 查询 10 页耗时 < 100ms
|
||
- [ ] 全文搜索耗时 < 200ms
|
||
- [ ] 增量更新单页耗时 < 50ms
|
||
- [ ] 基准测试通过
|
||
|
||
### 10.4 测试
|
||
- [ ] 单元测试覆盖率 > 80%
|
||
- [ ] 集成测试通过（MCP 协议、SQLite 操作）
|
||
- [ ] E2E 测试通过（真实 wiki 数据集）
|
||
|
||
### 10.5 文档
|
||
- [ ] README 完整（安装、配置、使用）
|
||
- [ ] API 文档完整
|
||
- [ ] 部署文档完整
|
||
|
||
---
|
||
|
||
## 11. 测试策略
|
||
|
||
### 11.1 单元测试
|
||
- 覆盖所有 MCP Tool 的核心逻辑
|
||
- 覆盖索引操作的边界条件
|
||
|
||
### 11.2 集成测试
|
||
- MCP 协议层测试（使用 MCP SDK mock）
|
||
- SQLite 操作测试
|
||
- Wiki 解析测试
|
||
|
||
### 11.3 E2E 测试
|
||
- 使用真实 wiki 数据集（1353 页）
|
||
- 测试场景：查询、搜索、索引更新
|
||
- 不需要真实 Claude Code 环境
|
||
|
||
---
|
||
|
||
## 12. 项目里程碑
|
||
|
||
| 阶段 | 交付物 | 状态 |
|
||
|------|--------|------|
|
||
| Phase 0 | 仓库初始化 | ✅ 完成 |
|
||
| Phase 1 | 需求文档 v1.1 + 评审通过 | 🚧 进行中 |
|
||
| Phase 2 | 设计文档 + 评审 | ⏳ 待开始 |
|
||
| Phase 3 | 编码实现 + 评审 | ⏳ 待开始 |
|
||
| Phase 4 | 测试 + 评审 | ⏳ 待开始 |
|
||
| Phase 5 | 部署 + 文档 | ⏳ 待开始 |
|
||
|
||
---
|
||
|
||
## 13. 参考资料
|
||
|
||
- 现有 21 个 Wiki Skills：`~/.sanguo_projects/sanguo_mozi/skills/wiki/`
|
||
- Gitea MCP Server：`/opt/homebrew/bin/gitea-mcp`
|
||
- nvk/llm-wiki AGENTS.md 协议
|
||
- Obsidian Wiki：`/Volumes/KnowledgeBase/wiki-vault`
|
||
- [[practices/sanguo-team-experience|三国团队实战经验]] — SQLite 并发保护
|
||
- [[practices/bitnet-practices|BitNet 实践]] — 性能基准测试方法论
|
||
- [[practices/moziplus-orchestration-practices|moziplus 编排实践]] — MCP/Skill 划分原则
|
||
|
||
---
|
||
|
||
*文档版本：v1.1*
|
||
*创建时间：2026-06-26*
|
||
*更新时间：2026-06-26*
|