前言¶
DeepSeek Harness (DSH) 允许通过插件扩展能力。在代码辅助场景中，模型不仅需要文本匹配，更需要结构化的代码上下文，如符号定义、调用关系和影响范围。传统的 grep 搜索往往效率低下且缺乏上下文。dsh-codegraph-plugin 通过将 codegraph CLI 封装为工具，为 DSH 提供了结构化的代码智能支持。
插件简介¶
这是由 errrepe 维护的 DSH profile bundle。它将 codegraph 工具集暴露为 8 个模型可调用的接口，并保持本地代码库索引的同步。插件在会话的当前工作目录 (CWD) 中执行 codegraph 命令，利用 SQLite WAL 机制在受限工作空间内读取索引数据。
先决条件¶
该插件依赖宿主机安装的 codegraph CLI，并不负责安装或管理该 CLI。
- 安装
codegraphCLI（通过 cargo）：
cargo install codegraph
- 验证安装：
codegraph --version
- 确保
codegraph可执行文件在系统PATH中。
安装¶
安装为指定的 DSH profile 添加 bundle：
dsh plugin --profile web add github:errrepe/dsh-codegraph-plugin
安装后，需重启该 profile 的 DSH 进程以使插件生效。
核心功能¶
插件提供以下 8 个工具接口，根据操作类型返回 JSON 或格式化文本：
codegraph_query：按名称搜索符号（函数、类、方法），支持按类型过滤，返回 JSON。codegraph_callers：查询调用指定符号的代码位置，用于重构前的依赖分析，返回 JSON。codegraph_callees：查询符号调用的目标，返回 JSON。codegraph_impact：分析修改符号可能产生的影响（依赖方及测试覆盖情况），返回 JSON。codegraph_explore：对开放性问题进行探索，一次性返回相关符号、源码、调用路径及影响范围，返回文本。codegraph_node：读取符号的完整源码或指定文件，包含行号及依赖关系，返回文本。codegraph_status：检查索引状态，显示文件、节点、边的统计信息，返回文本。codegraph_sync：将代码变更同步到索引，返回文本。
配置¶
在 DSH 的 Settings > Plugins (Configurables) 中会注册一个名为 codegraph 的配置项：
- enabled（默认
true）：控制插件工具的注册。关闭时工具返回错误提示，不会阻塞 DSH 启动。 - injectPrompt（默认
true）：控制是否在 System Prompt 中注入codegraph-guidance指引。该指引位于 Prompt 组合的第 50 位，教导模型优先使用代码图而非grep。
配置持久化在 ~/.dsh/settings.yaml 的 codegraph 命名空间下。
典型用法¶
- 首次使用：在搜索前调用
codegraph_status检查索引是否存在。若不存在，需在项目根目录手动运行一次codegraph init。 - 开放性问题：优先使用
codegraph_explore，它能在一个调用中返回符号、源码、调用路径和影响范围。 - 代码修改后：编辑文件后调用
codegraph_sync，确保后续查询反映最新代码。 - 精确读取：使用
codegraph_node读取特定符号或文件的详细源码。
兼容性与降级¶
插件具备容错能力：
* DSH 服务缺失：如果宿主机缺少 dsh-settings 等服务，插件会优雅降级（默认开启且无 bridge），不阻断 DSH 启动。
* CLI 缺失或无索引：工具会直接透传 codegraph CLI 的错误信息给模型。
* Headless 场景：在没有会话 CWD 的环境下（如纯脚本调用），工具会返回明确错误而非崩溃。
结尾¶
该插件通过统一接口将静态分析能力注入 DSH 生态，适合需要深度理解代码结构和依赖关系的场景。源码与目录可参考下方链接。
