From 70e337462e469333acc34f1d3e35dba5c197cd20 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Fri, 26 Jun 2026 09:56:15 +0800 Subject: [PATCH] docs: add requirements document (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加需求文档 docs/01-requirements.md - 更新 README.md - Phase 1: 需求评审 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 73 ++++++++++++++++- docs/01-requirements.md | 169 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 241 insertions(+), 1 deletion(-) create mode 100644 docs/01-requirements.md diff --git a/README.md b/README.md index 7424be2..a266266 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,74 @@ # sanguo_llmwiki -混合架构 Wiki 系统 - MCP Server + Wiki Skills \ No newline at end of file +混合架构 Wiki 系统，将高频查询和维护功能 MCP 化，保留一次性操作为 Skill。 + +## 状态 + +🚧 开发中 - Phase 1: 需求评审 + +## 项目概述 + +sanguo_llmwiki 是一个完整的知识管理系统，包含： +- **Wiki MCP Server** - 高性能查询和维护服务（Python） +- **Wiki Skills** - 11 个一次性操作 Skills +- **SQLite 索引** - 持久化索引缓存系统 + +## 项目结构 + +``` +sanguo_llmwiki/ +├── docs/ # 文档（需求、设计、API） +├── mcp_server/ # MCP Server 实现 +├── skills/ # Wiki Skills +├── tests/ # 测试 +├── deployment/ # 部署配置 +└── scripts/ # 脚本 +``` + +## 功能矩阵 + +| 类型 | 功能 | 实现方式 | +|------|------|----------| +| 查询 | wiki_query, memory_bridge | MCP | +| 维护 | wiki_status, wiki_lint, daily_update | MCP | +| 分析 | cross_linker, tag_taxonomy, wiki_synthesize | MCP | +| 操作 | wiki-ingest, wiki-capture, ingest-url | Skill | +| 管理 | wiki-setup, wiki-rebuild, wiki-export | Skill | +| 研究 | wiki-research, impl-validator | Skill | + +## 快速开始 + +```bash +# 克隆仓库 +git clone http://192.168.2.154:3000/sanguo/sanguo_llmwiki.git + +# 安装依赖 +cd sanguo_llmwiki +pip install -r requirements.txt + +# 启动 MCP Server +python -m mcp_server.main +``` + +## 文档 + +- [需求文档](docs/01-requirements.md) +- [设计文档](docs/02-design.md) - 待完成 + +## 开发流程 + +1. 需求 → 评审 → 设计 → 评审 → 编码 → 评审 → 测试 → 评审 → 部署 +2. 每个阶段由独立的 sub-agent 评审 +3. 所有成果物提交到 Gitea + +## 许可证 + +MIT License + +## 作者 + +sanguo team + +--- + +*最后更新：2026-06-26* diff --git a/docs/01-requirements.md b/docs/01-requirements.md new file mode 100644 index 0000000..b726ddc --- /dev/null +++ b/docs/01-requirements.md @@ -0,0 +1,169 @@ +# 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*