subzone/knowledge-master
GitHub: subzone/knowledge-master
面向开发者的本地优先知识图谱工具，通过图原生 RAG 和 MCP 协议为 AI agent 提供代码库的结构化记忆与依赖分析能力。
Stars: 1 | Forks: 0
# ⚡ Knowledge Master
**你代码库的记忆。** 一个本地知识图谱，让 AI agent 真正理解你的架构——而不仅仅是文本搜索。
[](LICENSE)
## 为什么需要
每次你开启新的 AI 对话，它都会忘记一切。你必须重新解释你的架构、规范和依赖。Knowledge Master 赋予你的 AI 关于整个系统的**永久、结构化的记忆**。
与那些仅返回“关于 X 的文本块”的传统扁平化 RAG 工具不同，Knowledge Master 构建了一个**图谱**——因此它可以通过遍历实际的关系来回答“如果我修改了 X，会产生什么影响？”。
## 核心功能
- 🔍 **语义搜索** 覆盖你所有的代码、文档和配置
- 🕸️ **知识图谱** — 展示服务、人员、仓库、技术之间的关系
- 💥 **影响范围分析** — “谁依赖这个服务/文件/技术？”
- 📏 **规范强制执行** — 检测并强制执行团队的开发模式
- 🤖 **MCP server** — 直接接入 AI agent（Kiro, Claude, Cursor）
- 🖥️ **Web UI** — 搜索、浏览、可视化你的知识图谱
- 🔒 **本地优先** — 数据绝不离开你的设备
## 前置条件
| 依赖 | macOS | Ubuntu/Debian | Windows |
|---|---|---|---|
| **Docker** | `brew install colima && colima start` 或 Docker Desktop | `sudo apt install docker.io docker-compose-plugin` | [Docker Desktop](https://docker.com/products/docker-desktop/) |
| **Ollama** | `brew install ollama && ollama serve` | `curl -fsSL https://ollama.com/install.sh \| sh` | [Ollama installer](https://ollama.com/download) |
| **Python 3.11+** | `brew install python@3.12` | `sudo apt install python3.12 python3.12-venv` | [python.org](https://python.org/downloads/) |
## 快速开始
```
# 安装（选择其一）
pipx install knowledge-master # recommended (isolated, clean)
pip install knowledge-master # or with pip
# 或通过 Homebrew (macOS)
brew install pipx && pipx install knowledge-master
# 或从 source 构建
git clone https://github.com/subzone/knowledge-master.git
cd knowledge-master
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
# 一键设置
km start
# 索引你的第一个 repo
km index ~/path/to/your/project
# 搜索
km search "authentication flow"
# 检查 blast radius
km blast-radius postgres
# 启动带 graph visualization 的 web UI
km serve
```
**要求：** Docker, Ollama, Python 3.11+
## 功能特性
### 结合图谱上下文的语义搜索
```
$ km search "how does auth work"
┌────────┬──────────────────────┬─────────────────────┬──────────────────────┐
│ Score │ Source │ Context │ Preview │
├────────┼──────────────────────┼─────────────────────┼──────────────────────┤
│ 0.847 │ src/auth/service.py │ repo:myapp, by:Alex │ JWT token validat... │
│ 0.791 │ docs/auth.md │ repo:myapp │ Authentication f... │
└────────┴──────────────────────┴─────────────────────┴──────────────────────┘
```
### 影响范围分析
```
$ km blast-radius auth-service
💥 Blast radius: auth-service
├── ⚙️ user-service (Service, via DEPENDS_ON)
├── ⚙️ payment-service (Service, via DEPENDS_ON)
├── 📦 frontend (Repo, via USES_SERVICE)
└── 👤 Alex (Person, via AUTHORED)
4 entities affected
```
### 规范强制执行
```
$ km check-conventions ~/my-project
✓ src/ directory (structure)
✓ separate test directory (testing)
✗ snake_case files (file-naming)
✓ Repository pattern (design-pattern)
1 convention(s) violated
```
### Web UI 与图谱可视化
```
$ km serve
Knowledge Master UI → http://127.0.0.1:9999
```
交互式力导向图，展示你完整的知识拓扑结构：
- 📦 仓库 (蓝色) → 🔧 技术 (红色)
- ⚙️ 服务 (橙色) → 依赖
- 👤 人员 → 作者身份
- 📏 规范 (紫色)
### MCP 集成 (AI Agents)
添加到你的 Kiro/Claude agent 配置中：
```
{
"mcpServers": {
"knowledge": {
"command": "km-server"
}
}
}
```
你的 AI agent 将获得以下工具：
- `search` — 结合图谱上下文的语义搜索
- `blast_radius` — 依赖分析
- `check_conventions` — 验证代码是否遵循团队模式
- `index_repo` — 将新仓库添加到知识库中
## 架构
```
┌─────────────────────────────────────────────────┐
│ Your AI Agent │
│ (Kiro / Claude / Cursor) │
└────────────────────┬────────────────────────────┘
│ MCP Protocol
┌────────────────────▼────────────────────────────┐
│ Knowledge Master │
│ │
│ ┌──────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Search │ │Blast Radius│ │ Conventions│ │
│ └────┬─────┘ └─────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ ┌────▼───────────────▼───────────────▼──────┐ │
│ │ FalkorDB (Graph + Vector) │ │
│ │ │ │
│ │ [Repo]──USES_TECH──▶[Tech] │ │
│ │ │ │ │
│ │ ├──DEFINES_SERVICE──▶[Service] │ │
│ │ │ │ │ │
│ │ ├──FOLLOWS──▶[Convention] │ │
│ │ │ │ │
│ │ [Person]──AUTHORED──▶[Document] │ │
│ │ │ │ │
│ │ [Chunk + Embedding] │ │
│ └───────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ Ollama (nomic-embed-text) │ │
│ └───────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
## 命令
| 命令 | 描述 |
|---|---|
| `km start` | 启动 Docker 并拉取 embedding 模型 |
| `km stop` | 停止容器 |
| `km index ` | 索引一个 git 仓库或文档目录 |
| `km search ` | 带有重排序功能的语义搜索 |
| `km blast-radius ` | 多层级依赖分析 |
| `km safe-to-change ` | 风险评估 (安全/有风险/危险) |
| `km who-owns ` | 文件归属 (git blame，按近期加权) |
| `km check-conventions ` | 验证代码是否遵循检测到的模式 |
| `km connect ` | 从外部 MCP (邮件、Slack) 拉取数据 |
| `km setup ` | 为 AI 工具自动配置 MCP |
| `km watch ` | 文件监控，自动重新索引 |
| `km upgrade` | 迁移图 schema |
| `km prune` | 移除陈旧或孤立的数据 |
| `km changelog` | 生成 CHANGELOG.md |
| `km list` | 显示已索引的仓库、技术和统计信息 |
| `km remove ` | 移除某个来源 |
| `km serve` | 在 http://127.0.0.1:9999 启动 Web UI |
| `km status` | 检查系统健康状态 |
## 自动提取的内容
当你索引一个仓库时，Knowledge Master 会自动检测：
| 类别 | 示例 |
|---|---|
| **技术栈** | 从依赖文件中提取语言、框架、包 |
| **服务** | 从 docker-compose.yml 和 K8s manifests 中提取 |
| **依赖关系** | 服务与服务之间的关联 |
| **规范** | 文件命名 (snake_case/kebab-case)、目录结构、设计模式 |
| **人员** | Git commit 提交者和文件归属 |
| **代码结构** | 函数、类，按 AST 感知的边界进行分块 |
## 功能状态
| 功能 | 状态 | 备注 |
|---|---|---|
| 语义搜索 + 重排序 | ✅ 稳定 | 两阶段检索，带置信度评分 |
| 知识图谱 (FalkorDB) | ✅ 稳定 | 节点、边、向量索引、schema 版本控制 |
| CLI (14 条命令) | ✅ 稳定 | start, index, search, blast-radius, safe-to-change, who-owns 等 |
| MCP server (8 个工具) | ✅ 稳定 | search, blast_radius, safe_to_change, who_owns, check_conventions, index, status |
| REST API | ✅ 稳定 | /api/v1/，包含 OpenAPI 文档 |
| Web UI + 图谱可视化 | ✅ 稳定 | htmx + D3，搜索、文件浏览器、图谱 |
| Git 仓库索引 | ✅ 稳定 | 解析代码、提取作者、检测技术栈 |
| 多语言静态分析 | ✅ 稳定 | Python (ast), TypeScript, Go, Rust (tree-sitter) |
| 影响范围分析 (多层级) | ✅ 稳定 | Imports → 服务 → 人员，包含置信度级别 |
| `safe-to-change` 风险评估 | ✅ 稳定 | 影响范围 + 测试覆盖率 = 风险评分 |
| Git blame 归属 | ✅ 稳定 | 按近期加权 (3x/2x/1x) |
| Schema 迁移 | ✅ 稳定 | 自动迁移，km upgrade |
| 去重 | ✅ 稳定 | 内容哈希，自动跳过未更改内容 |
| 规范检测 | ⚡ 基础 | 目录结构 + 文件命名模式 |
| 邮件连接器 (ms-365) | 🧪 实验性 | 可用，需要外部 MCP 设置 |
| `km watch` | 🧪 实验性 | 基于轮询，可能会发生变化 |
**图例：** ✅ 稳定 — ⚡ 基础 (可用，范围受限) — 🧪 实验性 (可能会发生变化)
## 横向对比
| 功能 | Knowledge Master | 通用 RAG | GitHub Copilot | Glean |
|---|---|---|---|---|
| 图谱关系 | ✅ | ❌ | ❌ | 部分 |
| 影响范围分析 | ✅ | ❌ | ❌ | ❌ |
| 规范强制执行 | ✅ | ❌ | ❌ | ❌ |
| 本地优先 (无云端) | ✅ | ✅ | ❌ | ❌ |
| MCP 集成 | ✅ | ❌ | ❌ | ❌ |
| 多仓库智能分析 | ✅ | 部分 | ❌ | ✅ |
| 费用 | 免费 | 免费 | $19/月 | $15-30/月 |
## 开发
```
# 运行测试
pytest
# Lint
ruff check knowledge_master/
# 直接运行 MCP server
python -m knowledge_master.server
# 直接运行 CLI
python -m knowledge_master.cli status
```
## 安全性
Knowledge Master **完全在你的本机运行**。没有任何数据会离开 localhost。
- 所有端口均绑定至 `127.0.0.1`（局域网无法访问）
- Ollama 在本地运行 — 没有任何云端 API 调用
- MCP server 使用 stdio（无网络暴露）
- 为 REST endpoint 提供可选的 API key 认证
```
# 启用 API key auth
export KM_API_KEY=$(openssl rand -hex 32)
km serve
```
请参阅 [SECURITY.md](SECURITY.md) 以获取完整的安全模型、风险提示和加固指南。
## 常见问题排查
| 问题 | 解决方案 |
|---|---|
| `km start` 失败并提示 "Docker not running" | 启动 Docker：`colima start` (macOS) 或 `sudo systemctl start docker` (Linux) |
| `km start` 失败并提示 "Ollama not found" | 从 https://ollama.com 安装 Ollama 并运行 `ollama serve` |
| `km index` 运行缓慢 | 首次运行会下载 embedding 模型 (约 274MB)。后续运行会很快。 |
| Web UI 提示 "Connection refused" | 确保容器正在运行：`km start` |
| 搜索结果质量不佳 | 索引更多内容。图谱中的上下文越丰富，质量越高。 |
| 9999 端口已被占用 | 使用 `km serve --port 8888` |
## 许可证
MIT
标签：AI智能体, AI风险缓解, RAG, SOC Prime, 代码库分析, 开发工具, 本地优先, 请求拦截, 逆向工具