Kzone - 本地 AI 知识空间

本地优先的个人知识管理系统，AI 友好，支持语义检索。通过 MCP 协议为 Claude Code、Codex 等 AI CLI 工具提供知识库搜索能力。

架构

Kzone/
├── CLAUDE.md              # AI 导航指南（Droid 自动加载）
├── .mcp.json              # MCP 服务器配置
├── knowledge/             # 知识内容（Markdown + YAML frontmatter）
│   ├── topics/            # 主题知识（按技术领域）
│   ├── projects/          # 项目知识（架构决策、经验教训）
│   ├── references/        # 参考资料（论文笔记、工具推荐）
│   └── daily/             # 每日学习日志
├── mcp-server/            # MCP 知识搜索服务器（FastMCP + ChromaDB）
├── templates/             # 知识条目模板
├── scripts/               # 工具脚本
├── index/                 # 向量索引（gitignored）
└── docs/                  # 项目文档（方案、进度、未来计划）

技术栈

组件	用途
Markdown + YAML frontmatter	内容格式，LLM 原生理解
Ollama + bge-m3	本地嵌入模型，中英文支持
ChromaDB	内嵌向量数据库，语义检索
FastMCP	MCP 服务器框架
uv	Python 包管理

快速开始

前置条件

• Python 3.11+
• uv
• Ollama

安装

# 1. 启动 Ollama 并拉取嵌入模型
ollama serve &
ollama pull bge-m3

# 2. 安装 Python 依赖
cd mcp-server && uv sync && cd ..

# 3. 构建索引
./scripts/build-index.sh

# 4. 全局安装（可在任意目录使用 kzone MCP 工具）
bash scripts/install-global.sh

使用

通过 AI CLI 工具（推荐）

全局安装后，在任意目录启动 AI CLI 即可使用 kzone 工具：

claude          # Claude Code
codex           # OpenAI Codex

在对话中直接使用：

• "搜索知识库中关于 RAG 的内容"
• "浏览 AI 主题下的所有条目"
• "帮我创建一个关于 Docker Compose 的知识条目"

通过脚本

# 创建新条目
./scripts/new-entry.sh topic "RAG 检索增强生成"
./scripts/new-entry.sh daily
./scripts/new-entry.sh project "My App"
./scripts/new-entry.sh reference "Attention Is All You Need"

# 重建索引（新增/修改文件后）
./scripts/build-index.sh

MCP 工具

MCP 服务器暴露以下工具，任何 MCP 兼容的 AI 客户端均可调用：

工具	功能
search_knowledge	语义搜索知识库（支持标签和分类过滤）
browse_topics	浏览目录结构
read_entry	读取条目完整内容
get_related	获取相关条目（显式关联 + 语义相似）
list_tags	列出所有标签及条目数
get_overview	知识库统计概览
add_entry	创建新条目（自动索引）
rebuild_index	重建搜索索引

知识条目格式

所有条目使用 Markdown + YAML frontmatter：

---
title: "条目标题"
tags: [ai/llm, tool/mcp]
category: topics/ai
created: 2026-04-11
updated: 2026-04-11
status: active
related:
  - topics/ai/mcp-protocol.md
summary: "一句话摘要，用于 AI 快速理解此条目内容"
---

# 条目标题

正文内容...

标签命名规范

前缀	领域	示例
ai/	AI 相关	ai/llm, ai/embedding, ai/agent, ai/rag
lang/	编程语言	lang/python, lang/go, lang/typescript
infra/	基础设施	infra/docker, infra/k8s, infra/linux
tool/	工具链	tool/git, tool/ollama, tool/mcp
concept/	通用概念	concept/architecture, concept/design-pattern

配置

全局接入（推荐）

运行一键安装脚本后，kzone-mcp 全局命令可用，自动配置 Claude Code 和 Codex：

bash scripts/install-global.sh

脚本完成：

1. uv tool install 安装全局命令 kzone-mcp
2. 写入 ~/.claude/settings.json（Claude Code 全局配置）
3. 写入 ~/.codex/config.json（Codex 全局配置）
4. 安装 systemd HTTP 服务（如 systemd 可用）

各客户端接入

stdio 模式（本地客户端 spawn 进程）

适用于 Claude Code、Codex、Cursor、VS Code 等。在对应客户端的配置中添加：

{
  "mcpServers": {
    "kzone": {
      "command": "kzone-mcp",
      "env": { "KZONE_ROOT": "/root/Kzone" }
    }
  }
}

客户端	配置文件路径
Claude Code	~/.claude/settings.json
Codex	~/.codex/config.json
Cursor	~/.cursor/mcp.json
VS Code (Copilot)	.vscode/mcp.json

HTTP 模式（持久服务，任意客户端）

启用 systemd 后，kzone 作为后台 HTTP 服务运行，任意 MCP 客户端通过 URL 连接：

# 安装并启动服务
sudo cp scripts/kzone-mcp.service /etc/systemd/system/
sudo systemctl enable --now kzone-mcp

客户端连接地址：

http://127.0.0.1:8765/sse

WSL 用户需先在 /etc/wsl.conf 中设置 [boot] systemd=true 并重启 WSL。

详细配置说明见 docs/client-configs.md。

项目级接入（仅 Kzone 目录）

.mcp.json 保留项目级配置，在 Kzone 目录下工作时自动生效：

{
  "mcpServers": {
    "kzone": {
      "command": "uv",
      "args": ["run", "--directory", "/root/Kzone/mcp-server", "python", "server.py"],
      "env": {
        "KZONE_ROOT": "/root/Kzone",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

服务器 CLI 参数

kzone-mcp                                          # stdio 模式（默认）
kzone-mcp --transport sse --port 8765               # SSE HTTP 模式
kzone-mcp --transport streamable-http --port 8765   # Streamable HTTP 模式

环境变量

变量	默认值	说明
KZONE_ROOT	/root/Kzone	项目根目录
KZONE_EMBED_MODEL	bge-m3	Ollama 嵌入模型名称
OLLAMA_HOST	http://localhost:11434	Ollama 服务地址

未来计划

详见 docs/future.md：

• Phase 2：LightRAG 知识图谱、混合检索、更强嵌入模型
• Phase 3：Obsidian 集成、VitePress 静态站点
• Phase 4：自动索引更新、AI 辅助知识整理、Mem0 记忆层