代码图谱与知识库

代码图谱是实验性功能，其界面、数据格式和索引行为可能会在后续版本中发生变化。

代码图谱使用 CodeGraph 分析项目中的符号及其相互关系。会话知识库保存设计决策、约束和经验教训。代码引用将两者联系起来，让你既能看到代码当前的结构，也能了解背后的原因。

页面

代码图谱以对话框形式打开，包含「概览」「符号」「代码探索」和「文件」四个标签页。其中的「知识库」按钮会打开知识库。

概览：文件、符号和关系的数量，语言与符号类型的分布，以及同步状态（「自动同步已启用」或「查询前同步」）。点击某个分布项可以查看相应的结果。
符号：按名称或文件路径搜索（「搜索符号或文件路径…」）。符号页面显示带语法高亮的源码，以及按关系类型和文件分组的「传入关系」和「传出关系」。由分析推断出的关系标记为「推断关系」，点击行号可跳转到调用位置。
代码探索：描述一个功能或流程，或者给出文件名或符号名，即可查看相关的源码和关系。此查询在本地运行，不使用 AI 模型。
文件：浏览已索引的文件；点击某个文件可列出其中的符号。
调用者和被调用者：在符号页面上显示多层调用关系。「遍历深度」默认为 3，最大为 6。最多显示 500 条结果；超出时会显示总数和提示。
影响分析：在符号页面上显示修改可能影响到的符号和文件，范围不超过所选深度（默认为 3，最大为 6）。最多显示 500 个符号和 2,000 条关系；结果被截断时，会显示总数和提示。
调用路径：在符号页面上搜索目标符号（「搜索目标符号…」），即可查看沿调用关系的最短路径。「索引中未找到有向调用路径。」仅表示索引中没有这样的路径。

可以通过目录菜单切换工作目录，该菜单也会显示完整路径。当前页面、代码探索中的问题、符号、深度、目标符号和源码行都包含在 URL 中，因此可以刷新页面、在新标签页中打开，或使用浏览器的后退和前进按钮。只要在同一后端上且登录有效，链接即可使用。

为项目启用索引

在左栏中右键点击项目或集合，选择「实验性功能」→「代码图谱」。
首次使用时，点击「下载 CodeGraph」。你所连接的后端会从 GitHub 下载固定的 CodeGraph 1.6.0 版本，并用内置的 SHA-256 校验值进行核对（显示「下载文件的校验值不匹配，未安装运行时。」表示核对失败）。无需另外安装 Node.js。
选择「工作目录」并点击「启用索引」。项目目录以及该项目中会话和分组使用的其他工作目录会分别列出；每个 Git 工作树都有自己的索引。集合中至少需要有一个会话具有有效的工作目录。
等待状态变为「可用」后，即可搜索符号或文件路径。索引在后台运行（「索引任务正在运行。可以关闭此页面，或停用索引以停止任务。」），关闭页面不会取消索引。

「同步索引」用于手动更新索引，或在失败后重试。每次代码查询之前，VelaTerm 也会先将索引更新到最新状态。同一后端和工作目录会复用同一个查询进程，该进程运行期间会实时获取文件的变化。连续五分钟没有查询时，该进程会退出；下一次查询会重新打开索引并补齐变化。概览每 30 秒刷新一次同步状态；自动同步不可用时，VelaTerm 仍会在每次查询前进行同步，绝不会把过时的结果当作最新结果呈现。

「停用索引」会停止正在运行的索引任务，但保留索引文件以及与知识条目的关联，以便之后重新启用。任务中断后，大约两分钟内其状态会变为可重试的失败状态（「上一次任务被中断。请同步索引以重试。」）。单个索引任务最多运行 30 分钟。

索引存储在各工作目录下的 .codegraph/ 文件夹中，由 CodeGraph 管理。索引过程由 VelaTerm 自行执行；它不会运行 CodeGraph 的智能体安装程序，也不会安装 Git 钩子。如果项目目录是某个仓库的子文件夹，则只索引该文件夹。

查看代码关系

搜索结果显示每个符号的名称、类型和位置。符号页面显示其源码、传入和传出关系，以及关联的知识条目；点击相邻的符号可以继续浏览。

关系来自静态分析，可能不完整或不确定（界面提示为「关系来自静态分析，可能不完整或存在不确定性。」），不能替代实际运行代码。符号页面在每个方向上最多显示 200 条关系和 600 行源码，超出时会给出提示。大于 4 MiB 的源文件不会显示。如果在查看期间文件发生了变化，VelaTerm 会提示你先重新同步，再依据其中的行号。

关联与复核条目

在符号页面上选择「关联知识条目」，选取一个现有条目，将其内容与代码对照后保存。在条目页面上，「代码引用」可以跳回代码；代码图谱中的条目链接则会打开完整的条目。

关联会保存项目、工作目录、文件路径、符号标识，以及复核时该文件的 SHA-256 摘要。文件发生变化后，关联显示「需要复核」；文件无法再读取或已被删除时，显示「不可用」；其他情况下显示「未变更」。检查以文件为单位，因此同一文件中的任何改动都会触发复核。已打开的条目页面会定期检查其引用。

选择「核对代码与条目」可以查看当前代码；如果条目内容仍然成立，选择「确认已复核」。后端会再次检查文件和条目在此期间是否有变化，如有变化会提示你重新加载。确认只会更新代码引用，不会改变条目的正文。如需修改结论，请照常编辑条目。

符号被删除或重命名后，关联不会转移到另一个同名符号上。请使用「移除关联」，再关联正确的符号。删除条目会移除其关联；删除项目会移除该项目的索引记录和关联，但不会删除其他条目或各工作目录中的索引文件。

在会话中查询

VelaTerm 启动的每个终端会话和智能体会话中都有 vkb 命令。其他能够运行终端命令的智能体也可以使用它。如果更新后已有会话找不到 vkb，请重启该会话。

安装「Vela 技能」（「设置 ▸ 通用」）后，Claude 可以使用 /vkb，Codex 可以使用 $vkb。只有在你明确要求时，该技能才会运行；智能体在处理其他工作时不会自行调用它。如果更新后智能体没有列出该技能，请点击「重新安装」并重启该智能体的会话。

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore 返回的结果与「代码探索」相同。
callers、callees 和 impact 可接受一个可选的深度参数；其结果包含 relations、total、depth 和 truncated。
path 接受两个取自搜索结果的确切符号 ID；files 可以按路径筛选。
search 分别返回代码结果（按相关度排序，还有更多结果时带有 hasMore）、知识条目和本地笔记。
node 返回符号的源码、关系和关联的条目。
memories 和 memory 用于搜索和读取会话知识库中的条目，包括来源、修订版本和代码引用。
notes 和 note 用于搜索和读取本地知识库（见本地知识库）。

代码查询使用命令所在目录的索引。子文件夹使用其所属项目的索引；嵌套在其中的独立工作树绝不会借用主检出目录的索引。未启用索引或查询失败时，结果会说明代码不可用，但知识查询仍可正常使用。这些命令不会安装任何内容、启用索引或修改条目。

数据存放位置

CodeGraph 运行时安装在应用数据目录下的 codegraph/1.6.0/ 中。索引任务和条目关联存储在应用数据库中（knowledge_* 表）。索引在代码所在的后端上运行；浏览器客户端和 SSH 连接通过现有连接读取结果，因此不会额外开放端口。每个后端都有自己的索引设置和知识库。

CodeGraph 的遥测、更新检查和独立的后台服务均已关闭。VelaTerm 管理查询进程，并通过私有的标准输入输出通道与其通信，不监听任何端口。索引过程本身不使用 AI。智能体用 vkb 读取的代码或条目，可能会被发送到该智能体所配置的模型服务，这与智能体读取源文件时的情况相同。

代码图谱的事件写入应用数据目录下的 logs/runtime-*.log。未设置 VLX_LOG_DIR 时，由 VLX_KNOWLEDGE_LOG_DIR 指定其目录。VLX_KNOWLEDGE_LOG_LEVEL 用于过滤这些事件（例如 error 或 off）。日志中不包含源码、查询文本、条目正文或凭据。

CodeGraph 的开发地址为 github.com/colbymchenry/codegraph，以 MIT 许可证发布。