sanguo/sanguo_llmwiki
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8aa2776e186d5fbce1675d44a17883a249878238
sanguo_llmwiki/docs/01-requirements.md
T
claude_dev 70e337462e docs: add requirements document (Phase 1) 
- 添加需求文档 docs/01-requirements.md
- 更新 README.md
- Phase 1: 需求评审

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 09:56:15 +08:00

5.0 KiB
Raw Blame History

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. 功能需求

2.1 MCP Server 功能

功能 描述 优先级
wiki_query 基于 SQLite 索引查询 wiki，支持关键词和语义搜索 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

2.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

2.3 索引系统

功能 描述 优先级
页面索引 索引所有 wiki 页面的元数据和内容 P0
全文搜索 基于 FTS5 的全文搜索能力 P0
链接图 记录页面间的链接关系 P1
增量更新 只更新变化的页面，避免全量重建 P0
标签索引 按标签快速查找页面 P1

3. 非功能需求

3.1 性能

  • 查询 10 页响应时间 < 100ms
  • 全文搜索响应时间 < 200ms
  • 索引 1000 页耗时 < 10s
  • 增量更新单页耗时 < 50ms

3.2 可靠性

  • SQLite 写入失败不影响原始 wiki
  • 索引损坏可自动重建
  • MCP 服务崩溃可自动恢复

3.3 可维护性

  • 代码覆盖率 > 80%
  • 关键功能有集成测试
  • 有完整的 API 文档

3.4 兼容性

  • 兼容 Claude Code MCP 协议
  • 兼容 Obsidian Markdown 格式
  • 支持 Python 3.11+

4. 技术约束

4.1 部署环境

  • macOS（开发和生产）
  • Wiki 路径：/Volumes/KnowledgeBase/wiki-vault（默认，可配置）

4.2 技术栈

  • Python 3.11+
  • SQLite 3.38+
  • MCP SDK（最新版）

4.3 外部依赖

  • Gitea MCP Server 作为参考实现（stdio 模式）
  • Claude Code Skills 规范

5. 验收标准

5.1 MCP Server

  • 所有 8 个 MCP Tools 可正常调用
  • wiki_query 返回结果准确，带 wikilink 引用
  • 索引更新后查询结果实时生效
  • MCP 服务崩溃后可自动重启

5.2 Wiki Skills

  • 11 个 Skills 可独立触发
  • wiki-ingest 能正确蒸馏文档
  • wiki-capture 能保存当前对话

5.3 性能

  • 查询 10 页耗时 < 100ms
  • 全文搜索耗时 < 200ms
  • 增量更新单页耗时 < 50ms

5.4 测试

  • 单元测试覆盖率 > 80%
  • 集成测试通过
  • E2E 测试通过

5.5 文档

  • README 完整（安装、配置、使用）
  • API 文档完整
  • 部署文档完整

6. 项目里程碑

阶段 交付物 状态
Phase 0 仓库初始化 ✅ 完成
Phase 1 需求文档 + 评审 🚧 进行中
Phase 2 设计文档 + 评审 ⏳ 待开始
Phase 3 编码实现 + 评审 ⏳ 待开始
Phase 4 测试 + 评审 ⏳ 待开始
Phase 5 部署 + 文档 ⏳ 待开始

7. 参考资料

  • 现有 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

文档版本：v1.0 创建时间：2026-06-26

Reference in New Issue View Git Blame Copy Permalink