Leankg

LeanKG

为 AI 编码 Agent 打造的企业级代码知识图谱
多仓库 · 环境治理 · 事故与服务 · 需求↔代码 · 令牌减少 65% / 工具调用减少 85%

在线演示 · 文档 · pkg.go.dev · 更新日志

---

什么是 LeanKG？

LeanKG 是面向 AI 编码 Agent 的代码知识图谱，以单个无 CGO 依赖的 Go 二进制文件形式发布 （github.com/FreePeak/LeanKG，根模块——参见 pkg.go.dev）。 Agent 通常需要通过 grep → 打开文件 → 填充大量上下文来重建代码结构；而 LeanKG 可通过 MCP 返回 针对性子图（调用者、依赖项、影响范围、测试、文档），以及团队层信息（环境、 服务、事故、需求）。在功能对齐切换时，Rust 引擎已移除； 使用 make go-build 构建，使用 make go-test 测试。参见 docs/prd.md 中的 功能对齐记录。

不使用 LeanKG	使用 LeanKG
工具调用繁多，上下文庞大	精简子图 + TOON（负载约小 40%）
无法了解影响范围	按严重程度分级的影响分析
仅支持关键词	关键词 + HNSW 语义搜索 + 本体
单仓库分析只能靠猜测	多仓库索引 + 运维工具

快速开始

# 1. Per project: one-shot index, then an incremental embed (sqlite default — zero config,
#    store at .leankg/leankg.db). In a git repo root it reads the HEAD commit's objects, so
#    uncommitted, untracked and ignored files are not indexed. Add --no-embed to skip the embed.
cd your-project
leankg index .

# 2. Wire up an AI client — one command (claude-code | cursor | codex | gemini | opencode | omp).
#    The stdio entry is `serve --stdio --memory`: the agent gets the code graph AND the
#    markdown memory layer (per-project at <project>/.leankg/memory), no second server.
leankg install --target claude-code  # `connect claude-code` is the same writer
#    Restart the client afterwards so it picks the entry up.

# 3. ...or serve MCP over HTTP yourself (endpoint /mcp; GET /health returns 200 when ready)
leankg serve --http 127.0.0.1:9699 --rest 127.0.0.1:8080 --memory
leankg install --target claude-code --http --url http://127.0.0.1:9699/mcp

语义（L3）搜索是唯一的可选层：它需要嵌入。设置 LEANKG_EMBED_PROVIDER（参见 docs/embedding.md 和 .env.example）；随后 leankg index 会在 索引后增量生成嵌入。在运行嵌入任务之前，查询会基于精确匹配和模糊匹配作答。

检查任意部署：运行 leankg doctor——它会打印存储路径、元素和 文件数量，以及写入水位标记（通过时退出码为 0 / 失败时为 2）。

通过 HTTP 使用 MCP：服务会根据其进程的当前工作目录解析项目——请从 代码检出目录运行，或传入 --project DIR 来指定项目。

安装

无需安装——sqlite 是默认存储引擎。不需要 Postgres，也不需要 Docker。

Postgres 仍可作为显式选择启用（LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL），用于服务器级部署，但默认流程不会触及它。

已发布模块——引擎是一个 Go 模块，因此工具链会从 pkg.go.dev 直接将两个二进制文件安装到 $(go env GOPATH)/bin：

go install github.com/FreePeak/LeanKG/cmd/leankg@latest         # server + CLI
go install github.com/FreePeak/LeanKG/cmd/leankg-embed@latest   # embedding pipeline

预构建归档——releases 提供适用于 linux/darwin × amd64/arm64 的 leankg-<os>-<arch>.tgz，归档根目录中包含两个二进制文件以及一个 .sha256 文件。leankg update 使用相同渠道。

从代码仓库检出版本构建——需要 Go 1.25+ 和 git；安装到 ~/.local/bin（传入 PREFIX 可更改安装位置）：

git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG
scripts/install-go.sh                # or: make install-go

# Or fetch and run the installer directly (clones over HTTPS, same behavior):
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install-go.sh | bash

容器——Dockerfile 采用无需 CGO 的三阶段构建：先构建引擎二进制文件，再从此代码仓库的一部分构建演示图，最后由非特权运行时以只读方式提供该存储。

docker build -t leankg .
docker run --rm -p 8080:10000 -e PORT=10000 leankg   # dashboard + its /api on :8080

MCP 接口

使用 query 进行发现——默认情况下，它会沿阶梯逐级路由（L1 精确匹配 → L2 关键词 → L3 语义；自然语言问题在 L1 未命中后会直接进入 L3，由其融合关键词和向量排名），出现问题时会降级而非报错，并且每个答案都会附带 retrieval{rung,reason} + freshness。

问题	方法
任意标识符（默认）	query "Alpha"（精确匹配，然后模糊回退）
会话开始时的记忆	query action=memory args.command=session_recall
会话结束时保留记忆	import action=memory command=session_retain
影响范围	leankg impact <file> 或 query --action impact --to <qn>
谁调用了 X？	query --action callers --to <qn>
A↔B 之间如何连接？	query --action path --to <qn>
元素详情	query --action explain --to <qn>
模式搜索	query --action pattern --pattern "func $_(...)"
PRD 可追溯性	leankg prd-trace FR-3T-01
文件（压缩）	query --action read --path src/main.go

3 个工具：import（索引/PRD/记忆/会话/本体/读取）· query（阶梯 + 图操作动词 + 操作）· status（清单/新鲜度/配置）。

功能特性

• MCP 原生 — 搜索、影响分析、调用图、本体、架构、团队知识
• 默认使用 SQLite（零配置，无需 Postgres 或 Docker），并支持选择使用 Postgres/pgvector 后端（LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL）
• 本体 — 概念目录 + 流程层（工作流、步骤、决策点、故障模式）、query --action ontology、POST /api/v1/ontology/match，以及通过 leankg prd / prd-trace 实现需求 ↔ 代码可追溯性
• 影响分析与依赖 — contains、calls、imports 边；BFS 影响范围（leankg impact）
• 多仓库服务 — MCP HTTP 127.0.0.1:9699；LEANKG_PROJECT_DIRS 可服务多个项目，通过 ?project=<dir|name>（REST 和 MCP）或 MCP project 工具参数按请求选择项目；如果两者都未指定，多项目服务会拒绝请求，而不会从错误的图中作答。默认使用 sqlite，可选择启用 PG
• 环境治理 — query --action env_conflicts、按环境创建快照、leankg obsidian
• 运维与归属 — query --action service_context / incidents、leankg incident / note / team-map
• 需求 ↔ 代码 — leankg prd / prd-trace、query --action prd、本体可追溯性矩阵
• Web UI v2 — Force / Tree / Circles 浏览器（cd ui-v2 && npm run dev；嵌入式构建由 leankg serve --ui 提供）
• 部署 — 单个无 CGO 二进制文件，无运行时依赖：Dockerfile 可为 Render 构建只读演示镜像，/health 响应容器探测，且 --ui / --http / --rest / --rpc 各自绑定独立地址
• 语言 — 40 种语言配置：Go、Rust、TypeScript/TSX、JavaScript/JSX、Python、Markdown、Java、Kotlin、Swift、Objective-C、Dart、C/C++、C#、PHP、Ruby、Scala、Perl、Lua、Haskell、Elixir、Crystal、CUDA、Cypher、Elm、Erlang、F#、GLSL、HLSL、Nim、OCaml、SQL、PowerShell、Q#、Solidity、SystemVerilog、Verilog、Zig
• Agent 经济效益 — A/B 测试：Token 减少 65%，工具调用减少 85%，较 grep/cat 快 2.5 倍；该领域的同类产品大多面向个人或单仓库。深度分析（已归档）：竞争分析 · 与 Graphify 的 ROI 对比 · 研究矩阵

嵌入

语义（L3）搜索需要嵌入；请参阅 docs/embedding.md，了解提供方（local / openai / deterministic）、EmbeddingGemma 2 + Hugging Face Storage Bucket 批量处理路径，以及 .env.example 中的变量列表。目录条目（模型 ID、固定版本、维度、前缀）位于 internal/embed/catalog.go。

性能

• Go 冷启动到首次产生价值的时间 — 17.8 秒（macOS arm64）；CI 预算为 300 秒，门禁为 .github/workflows/ci.yml 中的“Cold TTFV”，每次运行的数据位于 ttfv-go-cold 工件中。
• 快速入门顺利路径 — 在生成的 10 文件 Go 测试夹具上，热启动耗时 1.4 秒（索引 0.05 秒，服务绑定 1.08 秒，首次查询 0.05 秒，doctor 0.03 秒）；scripts/quickstart_smoke.sh 可在本地运行相同步骤（QUICKSTART_DRY_RUN=1 会打印执行计划）。

CLI

leankg index .                          # one-shot index + incremental embed -> .leankg/leankg.db (--no-embed skips the embed)
leankg index --hook <dir>               # SessionStart mode: skips over LEANKG_HOOK_MAX_FILES (10000) files or LEANKG_HOOK_MAX_EMBED (500) elements needing vectors
leankg writer                           # index once, then watch; a git-backed store re-indexes on each new commit (unsaved edits do not change the graph)
leankg query "parseConfig"              # name lookup (exact, then fuzzy) — JSON out
leankg query "parseConfig" --compress   # one line per result
leankg impact src/main.go --depth 3     # blast radius of a file or element
leankg status                           # health, inventory, freshness, embed state
leankg doctor                           # store path, element/file counts, watermark
leankg connect claude-code              # MCP entry: claude-code|cursor|codex|gemini|opencode|omp
leankg install --target cursor          # same wiring, flag form (--register-cwd: async claude-code SessionStart hook running `index --hook`)
leankg serve --stdio                    # MCP over stdio (what harnesses spawn)
leankg serve --http 127.0.0.1:9699      # MCP over streamable HTTP (/mcp, /health)
leankg serve --rest 127.0.0.1:8080      # REST API (/health, /api/v1/*)
leankg serve --ui 127.0.0.1:8081        # embedded dashboard (/api/* data API served here)
leankg serve --rpc 127.0.0.1:9090       # ConnectRPC (gRPC + gRPC-Web + JSON)
leankg version

拒绝绑定到非回环地址。 除非已配置 bearer token，否则 leankg serve --http/--rest/--rpc <non-loopback> 会报错退出，因为未配置 token 时，每个调用方都会被视为 Admin — 项目图、 文件读取器和记忆写入路径都会向局域网开放。可通过两种方式解决：绑定回环 地址（默认），或先配置 token （leankg auth token create，或 LEANKG_TOKEN_ADMIN / LEANKG_TOKEN_CONTRIBUTOR / LEANKG_TOKEN_VIEWER）。--ui 是刻意公开的唯一监听器（容器演示会通过 --read-only 在临时构建的图上提供服务），因此它会保留警告，而不会拒绝请求。

UI 热重载：cd ui-v2 && npm install && npm run dev → http://127.0.0.1:5173

完整用法：leankg help 和 leankg <command> --help。已归档的 CLI 参考：docs/archive/cli-reference.md

已知限制

• 调用边仅限于包内。 不解析导入或类型，因此同一包中的同名调用可以解析，跨包分派则尽力处理；后续升级方案是使用 tree-sitter 符号表。
• internal/index/relations.go 中的启发式保护：跳过 ≥ 1 MiB 的文件（视为 vendor 或压缩后的资源包），将短于 4 个字符的调用目标作为噪声丢弃，并限制每个元素和每个文件的外向调用数量。
• 作用范围以代码库为单位。 包含数万个嵌套文件的项目组合根目录不算一个项目；请逐个注册其子项目。
• --ui 会绑定一个未经身份验证的数据 API（query/read/导入路由）。请将其绑定到 loopback 地址，或在前面配置代理；公开演示容器会使用 --read-only 模式，为该 API 提供一个预先构建且可丢弃的图。

故障排除

问题	解决方法
提供了错误的项目	使用 --project DIR 启动服务（query/impact 也支持 LEANKG_PROJECT）
嵌入 / 冷启动嵌入	运行 leankg-embed status，然后运行 leankg-embed full（提供方环境变量：LEANKG_EMBED_*）

要求： macOS 或 Linux · 仅从源代码构建时需要 Go 1.25+。无需 Docker，也无需 Postgres——默认存储为 sqlite。

文档

文档集位于 docs/ 中——包含一份统一的 PRD（docs/prd.md）和任务跟踪表（docs/prd-task-tracker.md）。所有历史设计文档、分析、报告和计划均保存在 docs/archive/ 下。

文档
PRD	统一的产品需求 + HLD（唯一事实来源）
任务跟踪表	已完成 / 进行中 / 待办
架构（已归档）	设计与数据模型（历史资料）
MCP 工具（已归档）	工具目录（历史资料）
CLI（已归档）	所有命令（历史资料）
基准测试（已归档）	方法论（历史资料）
嵌入	提供方 + EmbeddingGemma 2 / Hugging Face 批量处理路径
AGENTS.md	Agent 说明

贡献

1. Fork 并创建功能分支（建议使用 worktree）
2. 行为变更时更新文档
3. go build ./... && go vet ./... && go test ./...
4. 提交 PR，附上摘要和测试计划

许可证

Apache License 2.0