# sanguo_llmwiki - Claude Code 项目配置

## 项目说明

混合架构 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 (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 (开发模式)
python3 -m mcp_server.main

# 部署到安装目录
scripts/deploy.sh

# 启动生产服务
pm2 start ecosystem.config.cjs
pm2 list                  # 查看状态
pm2 logs wiki-mcp         # 查看日志
```

## MCP 工具 (8 个)

| 工具 | 功能 | 方法 |
|------|------|------|
| `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 (11 个)

| 优先级 | 技能 | 功能 |
|--------|------|------|
| **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` - 使用手册