diff --git a/CLAUDE.md b/CLAUDE.md index a1398cb..5033bd6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,48 +4,144 @@ 混合架构 Wiki 系统 - MCP Server (Python) + Wiki Skills -## 开发/安装目录 +## 路径 - **开发目录**: `~/.openclaw/sanguo_projects/sanguo_llmwiki` - **安装目录**: `~/.sanguo_projects/sanguo_llmwiki` +- **Wiki Vault**: `/Volumes/KnowledgeBase/wiki-vault` -## 项目结构 +## 架构设计 + +### 四层架构 + +``` +┌─────────────────────────────────────┐ +│ MCP Protocol Layer │ stdio 通信 +├─────────────────────────────────────┤ +│ Tool Layer (8 tools) │ wiki_query, memory_bridge... +├─────────────────────────────────────┤ +│ Service Layer │ Query, Indexer, Parser... +├─────────────────────────────────────┤ +│ Storage Layer (SQLite + FTS5) │ wiki_pages, wiki_fts... +└─────────────────────────────────────┘ +``` + +### 技术栈 + +- **语言**: Python 3.10+ +- **数据库**: SQLite (WAL 模式) +- **搜索**: FTS5 全文搜索 +- **通信**: MCP stdio 协议 +- **部署**: PM2 进程管理 + +## 目录结构 ``` sanguo_llmwiki/ -├── mcp_server/ # MCP Server 实现 (Python) -├── skills/ # Wiki Skills (11 个) -├── tests/ # 测试套件 -├── docs/ # 文档 +├── mcp_server/ # MCP Server (4 层架构, 21 文件) +│ ├── __init__.py +│ ├── main.py # MCP 协议入口 +│ ├── protocol/ # Protocol Layer +│ ├── tools/ # Tool Layer (8 tools) +│ ├── services/ # Service Layer +│ └── storage/ # Storage Layer +├── skills/ # Wiki Skills (11 个) +│ ├── llmwiki/ # 汇总技能 +│ ├── wiki-setup/ +│ ├── wiki-ingest/ +│ └── ... +├── tests/ # 测试套件 (90+ 用例) +├── docs/ # 设计文档 +├── config.yaml # 配置文件 └── ecosystem.config.cjs # PM2 配置 ``` -## 快速命令 +## 开发命令 ```bash -# 运行测试 +# 测试 pytest -# 启动 MCP Server (开发) +# 启动 MCP Server (开发模式) python3 -m mcp_server.main # 部署到安装目录 -# 从 ~/.openclaw/sanguo_projects/sanguo_llmwiki -# 到 ~/.sanguo_projects/sanguo_llmwiki +scripts/deploy.sh + +# 启动生产服务 +pm2 start ecosystem.config.cjs +pm2 list # 查看状态 +pm2 logs wiki-mcp # 查看日志 ``` -## MCP 工具 +## MCP 工具 (8 个) -服务器提供 8 个工具： -- wiki_query: 搜索 wiki -- memory_bridge: 记忆桥接 -- wiki_status: 状态查询 -- wiki_lint: 健康审计 -- cross_linker: 交叉链接 -- tag_taxonomy: 标签分类 -- wiki_synthesize: 主题综合 -- daily_update: 日常维护 +| 工具 | 功能 | 方法 | +|------|------|------| +| `wiki_query` | FTS5 全文搜索 + 标签过滤 | `wiki_query(query, tags, limit)` | +| `memory_bridge` | 按工具来源浏览 | `memory_bridge(tool_name, date_range)` | +| `wiki_status` | 索引状态查询 | `wiki_status()` | +| `wiki_lint` | 健康审计 | `wiki_lint(path, level)` | +| `cross_linker` | 发现缺失的交叉链接 | `cross_linker(path, dry_run)` | +| `tag_taxonomy` | 标签一致性检查 | `tag_taxonomy(path, enforce)` | +| `wiki_synthesize` | 跨概念综合分析 | `wiki_synthesize(concepts, threshold)` | +| `daily_update` | 日常维护 | `daily_update()` | -## Wiki Skills +## Wiki Skills (11 个) -11 个一次性操作技能位于 skills/ 目录下。 +| 优先级 | 技能 | 功能 | +|--------|------|------| +| **P0** | `wiki-setup` | 初始化 wiki vault | +| **P0** | `wiki-ingest` | 蒸馏文档为 wiki 页面 | +| **P0** | `wiki-capture` | 保存对话为 wiki 笔记 | +| **P1** | `wiki-rebuild` | 重建 wiki 索引 | +| **P1** | `data-ingest` | 录入非结构化数据 | +| **P1** | `ingest-url` | 抓取 URL 内容 | +| **P1** | `wiki-export` | 导出知识图谱 | +| **P2** | `wiki-research` | 多轮搜索研究 | +| **P2** | `impl-validator` | 验证实现 | +| **P2** | `graph-colorize` | 着色 Obsidian 图形 | +| **P2** | `wiki-agent` | 录入 agent 历史 | + +详细用法见 `skills/*/SKILL.md` + +## 配置说明 + +### config.yaml + +```yaml +# Wiki 路径 +wiki_vault_path: "/Volumes/KnowledgeBase/wiki-vault" + +# 数据库路径 +database_path: "/Volumes/KnowledgeBase/wiki-vault/.wiki-index.db" + +# 搜索配置 +search: + max_results: 10 + snippet_length: 200 +``` + +### 环境变量 + +```bash +export WIKI_INDEX_PATH="/Volumes/KnowledgeBase/wiki-vault/.wiki-index.db" +export WIKI_VAULT_PATH="/Volumes/KnowledgeBase/wiki-vault" +``` + +## 搜索改进 + +### 连字符扩展 +`multi-agent` → 自动搜索 `multi` AND `agent` + +### 中文同义词映射 +`多智能体` → 自动扩展为 `multi-agent` + +### 搜索片段显示 +返回匹配文本片段，快速定位相关内容 + +## 相关文档 + +- `docs/01-requirements.md` - 需求文档 +- `docs/02-design.md` - 设计文档 +- `skills/llmwiki/SKILL.md` - 使用手册 diff --git a/skills/llmwiki/SKILL.md b/skills/llmwiki/SKILL.md new file mode 100644 index 0000000..e792642 --- /dev/null +++ b/skills/llmwiki/SKILL.md @@ -0,0 +1,113 @@ +--- +name: llmwiki +description: LLM Wiki 知识库系统 - 支持搜索、蒸馏、维护 +trigger: 当用户查询知识库、优秀实践，总结经验、或管理 wiki 时 +--- + +# /llmwiki + +LLM Wiki 是你的持久化知识库，支持跨会话记忆、自动索引、智能关联。 + +## 使用场景 + +### 查询知识库 +``` +"我的 wiki 里有什么关于 multi-agent 的内容？" +"查一下我之前记录的 SQLite 并发经验" +``` + +### 查询优秀实践 +``` +"我的优秀实践有哪些？" +"根据我的 wiki，多智能体编排的最佳实践是什么？" +"wiki 里关于测试的实践" +``` + +### 总结经验 +``` +"总结这次项目的经验教训" +"把这次对话蒸馏到 wiki" +"记录这个问题的解决过程" +``` + +### 管理 wiki +``` +"检查 wiki 健康状况" +"更新 wiki 索引" +"发现缺失的交叉链接" +``` + +## MCP 工具 + +后台自动调用，无需手动： + +| 工具 | 功能 | +|------|------| +| `wiki_query` | FTS5 全文搜索 + 标签过滤 | +| `memory_bridge` | 按工具来源浏览 (claude/web_reader/gitea/other) | +| `wiki_status` | 索引状态查询 | +| `wiki_lint` | 健康审计 (格式、链接、frontmatter) | +| `cross_linker` | 发现缺失的交叉链接 | +| `tag_taxonomy` | 标签一致性检查 | +| `wiki_synthesize` | 跨概念综合分析 | +| `daily_update` | 日常维护 (索引更新、hot.md 生成) | + +## Wiki Skills + +一次性操作技能，详细用法见各技能目录： + +| 优先级 | 技能 | 功能 | +|--------|------|------| +| **P0** | `wiki-setup` | 初始化 wiki vault | +| **P0** | `wiki-ingest` | 蒸馏文档为 wiki 页面 | +| **P0** | `wiki-capture` | 保存对话为 wiki 笔记 | +| **P1** | `wiki-rebuild` | 重建 wiki 索引 | +| **P1** | `data-ingest` | 录入非结构化数据 | +| **P1** | `ingest-url` | 抓取 URL 内容 | +| **P1** | `wiki-export` | 导出知识图谱 | +| **P2** | `wiki-research` | 多轮搜索研究 | +| **P2** | `impl-validator` | 验证实现 | +| **P2** | `graph-colorize` | 着色 Obsidian 图形 | +| **P2** | `wiki-agent` | 录入 agent 历史 | + +## Wiki 结构 + +``` +wiki-vault/ +├── practices/ # 最佳实践、经验教训 +├── concepts/ # 概念、思维模型 +├── entities/ # 人物、公司、工具 +├── projects/ # 项目文档 +├── skills/ # 如何做教程 +├── references/ # 外部资料摘要 +├── synthesis/ # 跨项目分析 +├── journal/ # 日常笔记 +├── index.md # 主索引 +└── hot.md # 热门内容 +``` + +## Frontmatter 模板 + +```yaml +--- +name: page-slug +description: 一句话摘要 +metadata: + type: practice | concept | entity | project | skill | reference | synthesis + created: YYYY-MM-DD + tags: [tag1, tag2] +--- +``` + +## 相关命令 + +```bash +# 查询 wiki +/wiki-query "关键词" + +# 重建索引 +/wiki-rebuild + +# 健康检查 +/wiki-lint +```