sanguo_llmwiki/docs/01-requirements.md

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）：

-- 页面索引表
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

配置项：

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 页面模型

@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 索引模型

@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 — 性能基准测试方法论
• practices/moziplus-orchestration-practices — MCP/Skill 划分原则

---

文档版本：v1.1 创建时间：2026-06-26 更新时间：2026-06-26