三个等价入口 + 首次上手完整流程

CGB 提供三个命令入口，pip install 后全部自动注册到 PATH。日常使用推荐 cgb（最短）；MCP 模式用 cgb-mcp。

code-graph-builder

完整名称，安装后可用

cgb

推荐缩写

cgb-mcp

MCP server 模式

环境变量 vs config.yaml

CGB 优先读取环境变量，再读 ~/.code-graph-builder/config.yaml。生产/CI 环境推荐用环境变量（不落盘），本地开发推荐写 config.yaml（避免每次 export）。支持的变量名：LLM_API_KEY、LLM_BASE_URL、LLM_MODEL、DASHSCOPE_API_KEY、EMBED_* 系列、CGB_WORKSPACE、CGB_DEBUG。

索引、库管理与搜索命令详解

cgb index 是最核心的命令，触发完整或增量的索引流程。 cgb index 每次执行都可以用 flag 控制粒度：只重建图、只重建文档、或只重建 Embedding。

搜索与查询命令

CLI 完整工作流：从代码库到可查询知识图谱

cgb index 背后触发了一个四阶段流水线。每个阶段产出的 artifact 会被下游阶段消费，形成完整的知识图谱。

🌲

Scan

graph.db

→

📝

API Docs

api_docs/

→

🎯

Embed

vectors.pkl

→

📚

Wiki

可选

→

✅

Ready

可查询

点击"下一步"开始 Step 0 / 5

底层命令：cgb scan（调试专用）

典型场景演示

两个实际场景展示 CLI 的完整使用节奏：初次索引大型项目，以及日常增量更新。

场景 A：初次索引大型 C++ 项目

# 不含 Wiki，加速初次索引

$ cgb index /path/to/cpp-project --no-wiki

→ [=========] 100% Done. ~3-5 min

$ cgb status

→ Functions: 12,450 | Classes: 890

→ Files: 1,203 | Indexed: 3m ago

$ cgb search "GPU initialization"

→ 1. cuda.init_device (0.87)

→ 2. vulkan.create_context (0.82)

场景 B：日常增量更新

# 改了几个文件，提交前快速同步

$ git add -p && git commit -m "fix: ..."

$ cgb index -i

→ Detected 3 changed files

→ Rebuilding affected nodes...

→ Done: 28s (vs full 5min)

# MCP 下次调用时自动同步，

# 无需手动触发

CLI 操作流 — 增量更新后精确查询

0 / 6 messages

进度条格式

[========> ] 45% Step 2/4: Generating docs...

单行滚动：ANSI escape code 覆写同一行，不污染终端滚动历史

自适应宽度：检测 shutil.get_terminal_size()，动态调整进度条长度

Windows 兼容：检测 VT100 支持，不支持时退化为纯文本输出

cgb query：最强的调试工具

当你想验证图数据库里到底存了什么、某个关系是否正确建立，直接用 cgb query 跑 Cypher 查询是最直接的方式。比如 MATCH (f:Function)-[:CALLS]->(g) WHERE f.qualified_name='auth.login' RETURN g.qualified_name 马上验证调用关系是否正确。加 --format json 可以把结果管道给 jq 做进一步处理。