Code Graph zh CN

代码图

语言： English · 简体中文

LWC 集成固定版本的 CodeGraph 运行时，用于回答当前检出代码的结构问题。它把文件、符号、定义、调用和依赖组织成图，让 Agent 能够先确定最小相关源码面，再阅读准确文件。

代码图与文档知识图彼此独立：前者描述源码结构，后者描述 Wiki Page、Source、引用与语义关系。两项能力必须分别启用、分别验收。

什么时候使用

以下问题适合 CodeGraph：

• 符号定义与签名；
• 调用者与被调用者；
• 源码和测试依赖；
• 文件拓扑；
• 围绕一项功能探索代码结构；
• 修改共享符号前分析影响范围。

字面文本、注释、日志字符串、配置键，以及已经通过精确搜索定位的单文件修改，应使用 rg。CodeGraph 用来辅助阅读源码，不能取代源码本身。

运行时与项目索引

LWC 把运行时安装与项目索引分开：

固定运行时 -> 每个版本和平台只需全局安装一次
项目索引   -> 每个项目分别保存在 .lwc/codegraph

第一个执行 cg init 的项目可能需要下载经过校验的固定运行时。后续项目复用同一份全局运行时，但各自建立并维护独立索引。版本升级时才下载新的固定版本，普通项目初始化不会重复下载相同运行时。

LWC 不会调用 PATH 中任意版本的 codegraph；它会关闭遥测，并管理项目本地索引路径。

先检查就绪状态

lwc --scope project cg status

status 只读，并会分别报告运行时可用性与项目索引是否初始化。已有且经过用户授权的索引可以直接查询，无需重复询问。

运行时或项目索引缺失时，应先说明下载、本地索引和存储影响，再只询问一次授权。检测到缺失并不代表可以下载或索引代码。

初始化

取得授权后：

lwc --scope project cg init
lwc --scope project cg status

只有需要详细索引进度时才使用 --verbose。status 同时报告固定运行时已安装且健康、当前项目 initialized=true 后，初始化才算完成。

禁止通过 wrapper 传入其他项目路径，禁止指向无关工作树，也不能直接编辑 .lwc/codegraph。

查询流程

先搜索符号：

lwc cg query "checkpoint restore" --limit 10
lwc cg node checkpoint_restore
lwc cg callers checkpoint_restore --limit 20
lwc cg callees checkpoint_restore --limit 20

• query 搜索已索引符号，并可按符号 kind 过滤。
• node 返回一个符号的源码及调用上下文；配合 --file 时会读取带行号的有界文件窗口。
• callers 回答“谁调用了它”。
• callees 回答“它调用了谁”。

常见符号名需要通过准确文件消歧，或沿索引位置回到当前 checkout。不能只根据一个符号名称就给出最终实现结论。

探索与拓扑检查

lwc cg explore "checkpoint recovery"
lwc cg files --filter src/store --format tree --max-depth 3
lwc cg impact checkpoint_restore --depth 2
lwc cg affected src/store/checkpoints.rs

• explore 为一个主题组合相关符号、源码和调用路径。
• files 展示索引中的文件结构，并支持目录与 glob 过滤。
• impact 遍历符号变更可能影响的代码。
• affected 识别源码文件变化影响的测试。

深度和结果数应保持有界。先用图定位候选文件，再阅读准确实现和测试。

让未提交代码进入最新索引

索引可能落后于尚未提交的修改。任务依赖当前 dirty code 时，应在第一次结构查询前、相关代码修改后，以及最终结构结论前同步：

lwc --scope project cg sync
lwc --scope project cg status

CodeGraph 使用文档粒度事务协调文件。同步成功只会更新项目索引，不会提交 Git 变更，也不会写入 LWC Wiki 知识。

MCP 集成

lwc serve --mcp 通过唯一只读工具 lwc_explore 提供 CodeGraph 能力。只探索代码时使用 mode=code；同时需要 Wiki 记忆与代码结构时使用 mode=all。

MCP 不会初始化运行时或项目索引。CodeGraph 尚不可用时，它只返回 readiness 指引，必须在只读工具之外显式执行 CLI cg init。

安全边界

• 只能索引当前授权项目根。
• Wiki 记忆与当前代码不一致时，把当前 checkout 视为实现证据。
• 不要把 CodeGraph 数据库作为 Wiki Source 导入。
• 不得手工编辑索引数据库、跨项目复制或直接删除。
• 索引成功不代表构建、测试或运行行为已经验证。
• 声明修改安全前，仍需运行原生测试并检查准确源码。

完成证据

CodeGraph 使用只有满足以下条件才算完成：

• cg status 报告预期固定运行时和已初始化项目索引；
• 相关 dirty code 修改后已经同步索引；
• 结构查询已经定位相关符号与文件；
• 准确 checkout 源码和测试支持最终结论；
• 项目索引仍位于 .lwc/codegraph，且遥测保持关闭。

下一篇：词图