# 基础安装（包含 FTS5 全文检索、模糊搜索、多 Vault、Git 同步及 Web 控制台）
uv tool install kb-mcp-lite

# 🌟 推荐：安装包含向量/语义搜索支持（自动集成 sqlite-vec + pysqlite3）
uv tool install "kb-mcp-lite[vec]"

# 🚀 全功能完整版（包含向量语义搜索 + 原生事件驱动文件监听 watchfiles）
uv tool install "kb-mcp-lite[vec,v0_8]"

# 基础安装
pip install kb-mcp-lite

# 开启语义搜索 (Semantic / Vector Search)
pip install "kb-mcp-lite[vec]"

# 开启全功能扩展 (包含 vec 与高性能文件监听)
pip install "kb-mcp-lite[vec,v0_8]"

kb init

kb add --type project \
       --title "kb-mcp-lite" \
       --tags "mcp,knowledge-base,python" \
       --body "面向AI代理的轻量级本地知识库，基于SQLite + FTS5 + MCP协议开发。"

# 默认搜索
kb search "MCP 知识库"

# 按类型过滤
kb search "sqlite" --type decision

# 模糊搜索
kb search "ft5" --fuzzy

# 查看所有文档
kb list

# 按类型过滤
kb list --type lesson

# 按标签过滤
kb list --tags "sqlite,bug"

# 查看文档详情（完整）
kb get <文档ID>

# 按章节获取文档内容（仅提取特定标题内容，节省Token）
kb get <文档ID> --section "Architecture"

# 更新文档
kb update <文档ID> --title "新标题"

# 删除文档
kb delete <文档ID>

# 查看版本历史
kb history <文档ID>

# 对比版本差异
kb diff <文档ID> --v1 1 --v2 2

# 恢复到指定版本
kb restore <文档ID> --version 2

# 创建文档链接
kb link --from <文档ID1> --to <文档ID2> --rel "relates-to"

# 查看文档链接
kb links <文档ID>

# 影响分析
kb impact <文档ID>

# 决策演进链追踪
kb chain <决策文档ID>

# 关系类型管理
kb rel list                    # 列出所有标准关系类型
kb rel show supersedes         # 查看特定关系详情

# 自动监听 Markdown 目录实时增量同步入库
kb watch --interval 1.0

# 启动Web管理后台
kb admin start

# 计划任务管理
kb scheduler list              # 列出所有任务
kb scheduler status            # 查看调度器状态
kb scheduler run auto-commit   # 手动触发任务
kb scheduler history           # 查看执行历史

# 健康检查
kb doctor

# 统计信息
kb stats

# 清理软删除文档
kb prune --older-than 30

# Git差异分析
kb diff-check

# 1. 克隆团队知识库Git仓库
git clone <团队Git仓库地址> ~/team-kb

# 2. 创建本地vault
kb vault create team --desc "XX团队公共知识库"
kb vault switch team

# 3. 关联Git同步目录
kb vault init-git --sync-dir ~/team-kb

# 4. 拉取并导入所有文档
kb vault pull

graph LR
A[AI自动/手动添加修改文档] --> B[拉取最新变更]
B --> C{是否有冲突?}
C -->|是| D[解决Markdown文件冲突]
C -->|否| E[提交本地变更]
D --> E
E --> F[推送到远程仓库]

# 写文档前先拉取最新
kb vault pull

# AI添加/修改文档后，提交变更
kb vault commit -m "添加XX项目部署流程文档"

# 推送到远程仓库
kb vault push

hooks:
  post_add: "kb vault commit -m 'AI自动添加文档: {doc_title}' && kb vault push"
  post_update: "kb vault commit -m 'AI自动更新文档: {doc_title}' && kb vault push"

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

"args": ["serve", "--vault", "team"]

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

from kb_mcp_lite.schema import Document, Field


class ApiDoc(Document):
    """API接口文档类型"""

    type: str = "api"
    id_prefix: str = "api"

    # 自定义字段
    endpoint: str = Field(description="接口路径")
    method: str = Field(description="HTTP方法")
    version: str = Field(description="接口版本")

    class Config:
        schema_extra = {
            "example": {
                "title": "用户获取接口",
                "endpoint": "/api/v1/user/{id}",
                "method": "GET",
                "version": "v1",
                "tags": ["user", "api"],
                "body": "接口返回用户的基本信息...",
            }
        }

# 导入目录下所有Markdown文件
kb import ./docs/

# 试运行，查看会导入什么，不实际写入
kb import ./docs/ --dry-run

# 导入后输出JSON格式报告
kb import ./docs/ --json

# 导出所有文档到指定目录
kb export ./export_dir/

# 强制覆盖已有文件
kb export ./export_dir/ --force

git clone https://github.com/HelloTomBruce/kb-mcp-lite
cd kb-mcp-lite

# 安装依赖（推荐使用uv）
uv sync --extra dev

# 运行测试
uv run pytest

# 代码检查
uv run ruff check .
uv run mypy src/

# 格式化代码
uv run ruff format .
uv run ruff check --fix .

src/kb_mcp_lite/
├── cli.py              # Click CLI (28 commands)
├── mcp_server.py       # FastMCP server (25 tools, 13 resources, 7 prompts)
├── schema.py           # Document, Link, SearchHit, TypeRegistry, exceptions
├── store.py            # Store Protocol (interface contract)
├── store/              # SQLite存储核心
│   ├── sqlite.py       # SqliteStore (composes 4 mixins)
│   ├── search.py       # SearchMixin — FTS5 + vec0 hybrid search
│   ├── embedding.py    # EmbeddingMixin — vec0 vectors, similarity, duplicates
│   ├── versioning.py   # VersioningMixin — history, snapshots, diff, restore
│   ├── maintenance.py  # MaintenanceMixin — doctor, prune, stats, subgraph
│   ├── embedding_queue.py # EmbeddingQueue — async queue with state machine
│   └── connection.py   # Shared sqlite3 connection factory
├── md_io.py            # Markdown frontmatter parser + bulk import/export
├── vault.py            # Multi-vault management
├── admin/              # FastAPI 后端与静态托管
│   ├── routes_docs.py  # Document CRUD + search
│   └── routes_meta.py  # Overview, links, graph, settings
├── static/app/         # 构建后的现代化 SPA 静态资源
├── migrations/         # Forward-only SQL migration runner
├── config.py           # XDG config loader
├── embedder.py         # OpenAI-compatible embedding client
├── worker.py           # Background embedding worker thread
├── watcher.py          # File watcher (event/poll modes)
├── scheduler.py        # APScheduler task scheduler (5 built-in tasks)
├── graph_query.py      # Multi-hop graph query engine (BFS)
├── relations.py        # Typed relation vocabulary + impact analysis
├── link_parser.py      # Body-level reference parser [text](id)
├── context_guard.py    # Git diff → relevant decisions/lessons
├── merge.py            # 3-way Markdown merge
├── migrations.py       # Forward-only SQL migration runner
└── concurrency/
    └── write_lock.py   # Cross-process flock-based write lock

web/                    # 前端单页应用源码 (React + Tailwind + HeroUI)
├── src/                # 前端组件与页面
│   ├── pages/          # Documents, DocDetail, Git, Links, Graph, Scheduler 等
│   └── components/     # MarkdownRenderer, DiffViewer, Badges 等
└── package.json        # 前端构建配置