QuantumKuba/dsh-graphify-plugin

dsh-graphify

为 DeepSeek Harness 提供一份当前、本地的代码库地图。

dsh-graphify 将 Graphify 的代码知识图谱连接到 DeepSeek Harness (DSH)。它帮助智能体从一个问题出发，找到相关的符号、依赖关系、架构社区以及变更影响，而无需将代码仓库视为一堆无结构的文件。

dsh-graphify 将 DeepSeek Harness 连接到 Graphify 知识图谱

为什么使用它？

Graphify 是本地图引擎；dsh-graphify 是 DSH 原生层，使其在智能体会话中切实可用。

| 使用原始代码搜索工作流 | 使用 dsh-graphify |
| --- | --- |
| 智能体反复猜测路径、执行 grep 并阅读大量文件。 | 智能体可以从符号、依赖路径、社区以及由图谱支持的项目上下文入手。 |
| 图谱可能悄无声息地描述一个较旧的代码检出。 | 新鲜度检查可识别过期的图谱，并可以警告或安全地运行增量代码更新。 |
| 即使较小的模型只需要导航功能，也会暴露所有图谱能力。 | 紧凑模式为本地 20B–30B 模型提供六个聚焦工具；完整模式则暴露完整工具集。 |
| MCP 设置和故障与 DSH 会话相互独立。 | 该插件解析当前会话项目、管理 Graphify 进程，并提供 graphify_status 用于诊断。 |

这并不是声称图谱可以取代源码阅读或测试。它为智能体提供了一张可靠的起始地图，使其能够将上下文预算花在真正重要的代码上。

安装并使用它

开始之前

你需要一个可用的 DSH 配置文件、Node.js 22.18 或更高版本、Python 3.10 或更高版本，以及 uv。该插件已在 macOS 和 Ubuntu Linux 上测试；Windows 尚未验证。

1. 将插件添加到你的 DSH 配置文件

dsh plugin --profile  add dsh-graphify

例如，将  替换为你通常用于运行 DSH 的配置文件。该 bundle 会自行激活；对于默认设置，你无需手动编辑 Cordis 配置。

2. 安装本地 Graphify 运行时

uv tool install 'graphifyy[mcp]==0.9.57'

如果 Graphify 不可用，DSH 仍可启动。安装后请求 graphify_status；该插件会在下一次检查或工具调用时发现运行时，无需重启 DSH。

3. 为代码仓库构建图谱

从你想要探索的代码仓库启动 DSH：

cd /path/to/your/repository
dsh --profile

然后，在 DSH 对话中运行：

/graphify

该命令会执行完整构建，并在该代码仓库中写入 graphify-out/graph.json。使用以下命令检查结果：

graphify_status

4. 提出架构性问题

尝试那些受益于关系而非文件名匹配的请求：

这个代码仓库的入口点和连接最紧密的模块是什么？

在我更改此接口之前，请展示到其调用方的依赖路径，并总结可能的影响范围。

哪个社区拥有身份验证，它在哪里连接到 API 层？

选择模式

默认的 full 模式会公开完整的 Graphify 能力集，包括社区、god 节点和拉取请求影响。当你的模型具有充足的工具选择能力，或者你需要那些专业查询时，请使用它。

对于本地 20B–30B 模型，请使用 compact。它会注册六个高频工具：status、graph query、node inspection、neighbours、shortest path 以及会话作用域的 graph 资源。更少的选择有助于较小的模型一致地使用图谱。

仅在你需要某一项时才添加覆盖：

- insert:
- id: dsh-graphify
name: dsh-graphify
config:
toolMode: compact
freshness:
mode: warn

freshness.mode 默认为 warn。当你希望插件在查询前合并安全的增量更新时，请选择 auto；仅当你刻意接受静态图谱时，才选择 off。在文档或其他非代码更改之后，需要进行一次完整的 /graphify 构建，因为增量 Graphify 更新仅涵盖代码提取。

该插件添加了什么

- 会话感知的项目解析： 图谱请求会遵循活动的 DSH 工作区。默认情况下，在该工作区之外由模型发起的访问会被阻止。
- 可检查的新鲜度： graphify_status 会报告解析后的项目、图谱路径、运行时可用性、连接状态，以及图谱是否与已索引的源状态匹配。
- 安全的更新策略： 增量更新仅针对插件能够证明是纯代码的更改运行；否则它会将图谱标记为过期，并要求进行完整构建。
- DSH 原生操作： /graphify 会构建或更新接收会话的项目，并在 DSH Web 中显示其持久结果。
- 弹性本地运行时： 该插件会自动发现 Graphify，并在 MCP 进程意外退出后重新连接。

常见任务

| 目标 | 在 DSH 中 |
| --- | --- |
| 构建或完全刷新图谱 | /graphify 或 /graphify build |
| 更新已更改的代码文件 | /graphify update |
| 诊断安装、项目选择或过期数据 | graphify_status |
| 查找符号及相关架构 | 让代理查询图谱，然后检查返回的节点和路径。 |
| 分析有风险的更改 | 在编辑前询问依赖项、最短路径、社区或 PR 影响。 |

/graphify update 有意保持保守。在对 Markdown、包元数据、配置或任何其他应体现在图谱中的非代码源进行更改后，请运行 /graphify。

配置参考

默认值适用于大多数单仓库会话。以下是用户常更改的设置：

| 设置 | 默认值 | 何时使用 |
| --- | --- | --- |
| toolMode | full | 对于较小的本地模型，设置为 compact 以进行聚焦导航。 |
| freshness.mode | warn | 设置为 auto 以在查询前安全地更新代码，或设置为 off 以使用有意保持静态的图。 |
| graphifyVersion | 未设置 | 固定自动 uv 回退所使用的 Graphify 版本。 |
| graphPath | 自动检测 | 指向非标准的 graph.json 位置。 |
| cwd | 活动会话项目 | 当会话没有工作区时，提供回退项目目录。 |
| allowExternalProjects | false | 允许模型工具访问会话工作区之外的项目。 |
| toolPrefix | 空 | 在更大的 DSH 配置文件中避免工具名称冲突。 |

有关完整、带类型的配置架构和默认值，请参阅 src/config.ts。

故障排除

| 症状 | 该怎么做 |
| --- | --- |
| graphify_status 显示运行时不可用 | 运行上面的 uv tool install 命令，然后再次运行 graphify_status。 |
| 找不到图 | 在仓库中启动 DSH 并运行 /graphify。 |
| 文档或配置编辑后图已过时 | 运行 /graphify 进行完整构建。 |
| 选择了错误的项目 | 从预期的仓库启动 DSH，或配置 cwd 或 graphPath。 |
| 某个模型需要另一个检出 | 尽可能保持默认隔离；否则有意设置 allowExternalProjects: true。 |

兼容性与开发

该包支持 @deepseek-ai/cordis >=4.0.0 <5，并已使用 Graphify 0.9.57 进行测试。它附带预构建的 DSH 包，并可在本地通过以下方式开发：

pnpm run typecheck
pnpm run build
pnpm test
pnpm run test:drift

使用 GRAPHIFY_E2E=1 pnpm run test:e2e 来测试本地实时 Graphify 安装。贡献指南见 CONTRIBUTING.md。

证据与后续步骤

BENCHMARK.md 定义了针对基线的 Graphify 辅助代理的计划性、可复现评估。它是一个实验性协议，而非性能结果。有关 Graphify 的图引擎、支持的语言以及上游 CLI 文档，请访问 Graphify。