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>

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*