CodeGraph 使用教程：把本地代码库做成知识图谱，用 cpolar 远程给团队看架构关系
CodeGraph 使用教程：把本地代码库做成知识图谱，用 cpolar 远程给团队看架构关系
本地项目一大，架构评审就容易变成“谁熟悉谁讲”。后端同事说调用链在这里，前端同事说入口在那边，新人打开仓库只看到一堆目录，半小时过去还没摸到主线。
这篇就把 CodeGraph 跑起来：在本地给代码库建立知识图谱，导出一份可读的架构关系材料，再用 cpolar 临时开一个 HTTPS 地址发给团队看。代码不需要上传到第三方平台，演示结束关掉隧道，适合做代码走读、PR 影响范围说明、项目交接。
说明：这篇是代码理解工具方向的补充篇，重点放在 CodeGraph 的图谱索引和团队远程评审场景，不展开 AI IDE 插件接入。
1 什么是 CodeGraph？
CodeGraph 是一个面向代码库的本地代码知识图谱工具。它会解析项目里的函数、类、导入关系、调用链等结构信息，再把这些信息提供给 MCP 客户端、VS Code 扩展或命令行任务使用。
官方 README 里明确写到，CodeGraph 支持通过 tree-sitter 解析多语言代码，并提供 MCP tools、VS Code 扩展和持久化 memory 能力。换句话说，它不是简单全文搜索，而是把“文件之间怎么依赖、函数之间怎么调用、改一处会影响哪里”整理成结构化信息。
这篇文章里，我们只抓一个实用目标：
- 在本地项目里初始化 CodeGraph
- 生成一份图谱分析材料
- 用本地静态页面展示给同事
- 通过 cpolar 开临时公网访问地址
这里别急着把生产私有仓库直接拿来演示。建议先用脱敏仓库、示例项目，或者只包含核心模块的副本。架构评审要看关系，不需要把密钥、配置和客户数据一起端出去。
2 环境准备：Node、CodeGraph 和一个待分析项目
CodeGraph 官方安装入口使用 npm 执行安装器，因此本机需要先有 Node.js 和 npm。先在终端确认版本：
node -v
npm -v
能正常输出版本号再继续。这里建议在一个干净终端里做，后面生成图谱、启动页面、开启 cpolar 都会用到命令行。
准备一个待分析项目，本文用 /Users/admin/demo/shop-api 作为示例路径。你换成自己的项目时，只要把命令里的路径替换掉就行：
cd /Users/admin/demo/shop-api
git status --short
git status --short 这一步不是为了提交代码，而是确认自己站在正确仓库里。如果输出了一堆不认识的文件，先停一下，检查当前目录是否进错了。
3 安装 CodeGraph：先装全局工具，再初始化项目
进入项目目录后，执行官方安装器：
npx @colbymchenry/codegraph
安装器会询问要配置哪些 Agent、是否把 codegraph 放到 PATH、配置作用于全局还是当前项目。这里按团队实际使用选择即可；如果只是跟着本文做一次本地分析，选择当前项目会更稳，后面清理也轻松。
安装完成后，在当前项目里初始化索引：
codegraph init -i
这一步会在项目内建立本地知识图谱索引。大仓库耗时更长，先让它跑完。看到命令退出并回到终端提示符后，再执行下一步。
如果命令提示 codegraph 找不到，优先检查安装器里是否选择了安装到 PATH。也可以关闭终端重新打开一次，让新的 PATH 生效。
4 生成架构关系材料：用 graph-only 模式跑一次分析
CodeGraph 官方文档给了一个适合脚本化的方式：--graph-only 跳过 embedding 生成，只构建结构图谱；--run-tool 执行一个工具后退出。这很适合 CI 或本地快速生成评审材料。
在项目根目录执行：
codegraph-server --graph-only \
--run-tool codegraph_pr_context \
--tool-args '{"baseBranch":"main","format":"markdown"}' \
> codegraph-review.md
这条命令会输出 Markdown 格式的图谱分析内容，并保存成 codegraph-review.md。如果你的默认分支叫 master，把 baseBranch 改成 master。
这里建议把第一次生成的文件原样保存一份，例如 codegraph-review-first.md。后面你调整代码、补测试、重跑分析时，就能直接对比两份材料的变化。评审会上最怕只讨论“我感觉影响不大”，有了前后两份图谱输出，讨论会更容易落到具体模块和具体调用链上。
这里重点看三个信息：
- 改动涉及哪些模块
- 哪些调用链和依赖关系被影响
- 哪些测试或文档需要同步检查
如果输出文件为空，先检查当前目录是不是 Git 仓库，再确认 main 分支名是
否存在：
git branch --show-current
git branch --list main master
ls -lh codegraph-review.md
这一步不是为了把 CodeGraph 用到极致，而是先把“架构关系材料”稳定产出来。团队能看懂这份材料，后面再接 MCP、VS Code、PR 自动评论都顺手。
5 做一个本地展示页：把 Markdown 转成可访问页面
团队评审时，直接把 Markdown 文件丢群里也能看，但体验不够直观。我们把它放到一个本地目录，用 Python 启一个静态服务。
新建一个展示目录：
mkdir -p /tmp/codegraph-share
cp codegraph-review.md /tmp/codegraph-share/index.md
cd /tmp/codegraph-share
再生成一个简单 HTML 页面，把 Markdown 原文放进页面里：
cat > index.html <<'EOF'
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>CodeGraph 架构关系评审</title>
<style>
body { max-width: 960px; margin: 40px auto; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; line-height: 1.7; }
pre { background: #f6f8fa; padding: 16px; overflow: auto; border-radius: 8px; }
</style>
</head>
<body>
<h1>CodeGraph 架构关系评审</h1>
<p>这份材料由本地 CodeGraph 分析生成，用于团队代码走读和架构评审。</p>
<pre id="content"></pre>
<script>
fetch('./index.md').then(r => r.text()).then(t => {
document.getElementById('content').textContent = t;
});
</script>
</body>
</html>
EOF
启动本地静态服务：
python3 -m http.server 8088
浏览器打开 http://127.0.0.1:8088，能看到标题和 CodeGraph 输出内容，说明本地展示页已经跑通。
如果页面空白，先看终端里有没有 404，再确认 index.md 和 index.html 是否都在 /tmp/codegraph-share 目录下。
6 用 cpolar 远程给团队看：临时开一个 HTTPS 地址
本地页面只能自己看，远程同事访问不到。这里引入 cpolar：把本机 8088 端口临时映射成公网 HTTPS 地址，发给同事即可打开。
如果本机还没安装 cpolar，macOS 可以按官方口径用 Homebrew 安装：
brew tap probezy/core && brew install cpolar
sudo cpolar service install
sudo cpolar service start
Linux 可以用官方一键脚本安装：
curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash
安装后先确认本地控制台可访问：
cpolar version
curl -s http://127.0.0.1:9200 || echo "cpolar 服务未启动"
保持前面的 Python 静态服务不要关，再开一个新终端，创建 HTTP 隧道：
cpolar http 8088
命令输出里会出现公网访问地址。把 HTTPS 地址发给同事，对方就能看到本机展示页。
这里有三个提醒：
- 免费随机地址会在 24 小时内变化，适合临时评审
- 需要固定二级子域名时，使用基础套餐或以上
- 演示结束后关闭 Python 服务和 cpolar 隧道，避免页面长时间暴露
如果同事打不开，按顺序排查：本机 http://127.0.0.1:8088 是否能打开、cpolar http 8088 是否仍在运行、发出去的是不是 HTTPS 公网地址。
7 评审时怎么用：别只发链接，要带着问题看
CodeGraph 页面发出去之后，不建议只说“大家看看”。架构评审最好带着问题走，否则同事打开页面也不知道该看哪一段。
我一般会按这几个问题组织讨论：
- 这个模块的入口在哪里，调用链从哪里开始
- 核心业务函数被哪些地方调用
- 当前改动会影响哪些文件、测试和文档
- 有没有循环依赖、过深调用链或长期没人维护的模块
如果是新人交接，可以让新人先看 CodeGraph 输出，再回到代码里定位对应文件。这样比直接丢一个仓库链接友好很多，至少他知道从哪个模块开始读。
如果是 PR 评审，可以把 codegraph-review.md 作为评审附件。核心代码仍然要人工 review，CodeGraph 负责把依赖关系和影响范围提前摊开，减少“漏看边缘模块”的情况。
8 总结
到这里，我们已经把一个本地代码库交给 CodeGraph 建立图谱索引，生成了 Markdown 格式的架构关系材料，又用 Python 起了本地展示页，借助 cpolar 临时发给远程同事访问。整个过程不需要把仓库上传到公网平台，适合代码走读、架构评审、项目交接这类短时协作场景。
关键步骤就三件事：
- 用
npx @colbymchenry/codegraph安装 CodeGraph，并在项目里执行codegraph init -i - 用
codegraph-server --graph-only --run-tool codegraph_pr_context生成图谱分析材料 - 用
python3 -m http.server 8088本地展示，再用cpolar http 8088给团队开临时访问地址
后续要继续扩展，可以把 CodeGraph 接到 MCP 客户端或 VS Code 扩展里，让 AI 助手直接查询结构化代码关系。团队协作层面，cpolar 负责把本地演示页面安全、短时地送到远端同事面前；评审结束就关，既省部署时间，也能减少把内部代码材料长期放在外部平台上的麻烦。
北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台
更多推荐
6
0- 0
已为社区贡献1条内容
所有评论(0)