前言¶
DeepSeek Harness (DSH) 插件生态旨在扩展智能体的代码操作能力。在编写代码时，智能体需要回答三个结构化问题：符号在哪里声明、谁调用了它、修改它会产生什么影响。传统的文本搜索（如 grep）无法回答“谁调用它”这类关系问题，而 LSP 虽然精确，但依赖于光标位置且需要为每种语言运行单独的服务。dsh-plugin-codegraph 解决了这个问题，它通过在本地构建代码符号图，为智能体提供了 codegraph 和 codegraph_index 两个工具，使其能够基于图结构而非文本搜索来回答上述问题。
核心能力¶
该插件为智能体提供两个主要工具，它们在功能和设计上相互独立。
codegraph：只读查询工具¶
codegraph 提供 10 个只读操作，用于从预构建的索引中获取信息：
search：查找符号在哪里声明。node：获取某个符号及其直接调用者和被调用者。callers：列出调用当前符号的所有位置。callees：列出当前符号调用的所有目标。impact：分析修改当前符号可能产生的影响范围。trace：追踪两个符号之间的路径。files：列出被索引的文件，支持目录或通配符。status：检查索引的大小和新鲜度。explore：探索与查询相关的多个声明及其源码。context：获取与特定任务相关的所有上下文信息。
codegraph_index：索引构建工具¶
该工具负责构建或刷新代码图索引。索引过程与查询过程分离，因为构建大型工作区的索引需要数分钟，而查询仅需毫秒级。将两者合并会导致超时预算配置困难：要么太紧导致索引无法完成，要么太松导致查询无法感知卡顿。
安装与启用¶
安装过程通过一条命令完成，它会自动获取包并将插件配置到指定 Profile 中：
dsh plugin --profile <name> add dsh-plugin-codegraph
安装后，智能体即可直接使用上述两个工具。如果索引尚未构建，status 操作会明确告知索引不存在，并指出需要运行 codegraph_index。
典型用法¶
- 查找符号声明：
codegraph search query
- 查看符号的调用关系：
codegraph node symbol
- 检查修改影响：
codegraph impact symbol
- 追踪路径：
codegraph trace from to
- 列出索引文件：
codegraph files
- 构建或刷新索引：
codegraph_index
技术细节¶
- 语言支持：内置索引器支持 TypeScript、TSX、JavaScript、JSX、Python、Go、Java、C、C++、C#、PHP、Rust、Ruby、Zig、Kotlin、Swift、Dart 和 Scala。语法解析器按语言惰性加载，仅在使用匹配文件时加载对应的解析器。
- 存储格式：插件与
codegraphCLI 共享磁盘格式（schema version 4），存储路径为<projectRoot>/.codegraph/codegraph.db。这意味着既可以使用插件构建索引，也可以使用 CLI 构建，两者可互操作。 - 调用解析逻辑：插件不会对未解决的调用进行猜测。解析顺序遵循固定规则：首先匹配导入的文件，其次匹配全局唯一的名称。如果都不匹配，该调用会被记录为
unresolved，而不是生成错误的边。
注意事项¶
- 只读与构建分离：
codegraph工具始终是只读的，codegraph_index是构建索引的专用工具。任何查询都不会隐式触发索引构建，这是为了防止长时间运行的索引任务与查询混淆。 - 未解决的记录：未解析的调用被明确标记为
unresolved。智能体不应依赖这些标记来假设调用的存在，而应将其视为需要进一步确认的信息。
结语¶
dsh-plugin-codegraph 通过进程内索引和图查询，为 DeepSeek Harness 提供了与 LSP 不同维度的代码理解能力。它不猜测调用关系，而是基于明确的解析规则提供结构化数据。如需了解更多或贡献代码，请访问项目仓库。
