dsh-codegraph

dsh-codegraph 通过模型上下文协议（MCP）把 DeepSeek Harness（DSH）连接到上游 @colbymchenry/codegraph。CodeGraph 负责 SQLite 符号图、语言解析、索引同步、调用路径和有界源码检索；本插件只负责 DSH 侧的工具桥接、提示、 workspace 隔离、子进程生命周期和部署配置。

模型侧只提供查询能力，默认只公开 codegraph_explore；可按配置公开其他上游查询工具。插件默认会在某个受限 workspace 第一次查询前调用官方 CodeGraph 命令创建缺失索引，但不会向模型公开初始化、更新、导出或删除索引的工具，也不会修改 CodeGraph 或 DSH 源码。

插件通过 @muou000/dsh-codegraph npm 包发布；Git 标签目前不作为安装依据。部署应固定插件版本、 CodeGraph 版本和运行时摘要，不要依赖浮动的 Git checkout 或自动下载。

前置条件

DSH 0.1.2-alpha.1 的公开包接口。
已装载 ctx.subprocess 的 DSH 子进程提供方；DSH 标准 web、headless profile 已包含本地提供方。
DSH 宿主使用 Node.js 22.19.0，或 package.json 允许的更新版本。
从源码构建插件时使用 Corepack 和 pnpm 10.33.0。
已单独安装并验证 CodeGraph。仓库验证过 1.6.0；官方资产摘要记录在源码仓库的 docs/RUNTIME.md，版本要求也可查看 v1.6.0 发布页。

插件不会随 npm 安装下载 CodeGraph。生产配置应固定 CodeGraph 的版本、可执行文件和参数。

安装 CodeGraph CLI（必需）

安装 DSH 插件前，必须在运行 DSH 的同一台主机上单独安装 CodeGraph CLI。Windows 上可使用已经验证的 1.6.0：

npm install --global '@colbymchenry/[email protected]' `
  --registry=https://registry.npmjs.org/

安装后从将要启动 DSH 的同类终端验证命令确实可解析：

Get-Command codegraph
codegraph --version

如果刚安装后当前终端仍找不到命令，请新开一个 PowerShell 再验证。使用本插件时不需要为了 DSH 额外运行 codegraph install；DSH 的 MCP 连接由本插件管理。上游的 codegraph install 会为其支持的其他 Agent 客户端写入配置，属于独立操作。

CodeGraph 子进程必须与 DSH Agent 的 workspace 处于同一台主机、同一文件系统命名空间，并能用同一个绝对路径访问它。当前没有容器、WSL、SSH 或远程文件系统的路径映射；如果 DSH 的文件工具访问远端 workspace，而 CodeGraph 在本机启动，则不受支持。

自动创建项目索引

默认 autoIndex: true。某个 session-workspace 第一次执行 CodeGraph 查询时，如果项目根下完全没有 <workspace>/.codegraph，插件会通过 DSH 的受管子进程服务执行：

codegraph init --yes D:\path\to\project

同一 workspace 的并发首次查询会共用一次初始化；初始化成功并复核 codegraph.db 是 workspace 内的普通文件后，原查询才会继续。已有合格索引不会重建。已有索引目录但缺少数据库、索引路径是符号链接或 Windows junction、初始化超时或命令失败时，请求会失败关闭，插件不会删除或覆盖现场。

每个 DSH session workspace 都会在自己的根目录建立索引，不能借用父目录或相邻仓库的索引。 autoIndex 只允许与默认的 projectScope: session-workspace 一起使用，避免模型通过跨项目参数触发任意目录写入。需要继续手工管理索引时，显式设置 autoIndex: false，再运行：

codegraph init --yes D:\path\to\project
codegraph status --json D:\path\to\project

自动创建只负责首次 init，不会替代后续的 status、版本升级重建、损坏修复、备份或删除。

从本仓库安装

npm 发布名为 @muou000/dsh-codegraph，可直接从 registry 安装。执行本命令前必须先完成前面的 CodeGraph CLI 安装和命令验证；npm 插件安装成功不代表外部 codegraph 命令已经存在：

dsh plugin --profile web add '@muou000/dsh-codegraph@latest'

源码 checkout 的包入口指向构建后的 lib/，因此不要把未构建目录直接交给 dsh plugin add。先安装依赖、检查、打包，再用已经安装的 dsh 命令安装绝对路径 tarball：

corepack pnpm install --frozen-lockfile
corepack pnpm run check
corepack pnpm pack
$tarball = (Resolve-Path .\muou000-dsh-codegraph-0.1.0.tgz).Path
dsh plugin --profile web add $tarball

其他 profile 分别安装，例如：

dsh plugin --profile headless add $tarball

dsh plugin 在 profile 目录中管理依赖，使用绝对 tarball 路径可避免相对路径被解析到错误目录。若没有独立安装 dsh，但正在从 DSH 源码 checkout 运行，先在该 checkout 安装好依赖，再把上面的 dsh 命令替换为：

Set-Location path\to\deepseek-harness
corepack pnpm dsh plugin --profile web add $tarball
corepack pnpm dsh --profile web --dump-config
corepack pnpm dsh --profile web

这种方式只从 DSH 源码启动 CLI，不需要修改 DSH 仓库。

启动时报 `codegraph` 不在 PATH

以下错误表示 DSH 插件包已经安装，但外部 CodeGraph CLI 缺失或对启动 DSH 的进程不可见：

dsh-codegraph: cannot resolve automatic-index command "codegraph"
subprocess-local: command "codegraph" was not found on PATH

先执行前面的 Get-Command codegraph 和 codegraph --version。如果命令不存在，安装 CodeGraph CLI；如果命令只在另一个终端可见，请从能解析该命令的新终端启动 DSH。插件默认 failOnStartupError: true，因此缺少运行时会让整个 profile 失败关闭，而不是静默移除 CodeGraph 工具。

需要先恢复 Web、暂时不启用 CodeGraph 时，可移除该 bundle：

pnpm dsh plugin --profile web remove '@muou000/dsh-codegraph'
pnpm dsh web

配置

安装 bundle 后，cordis.patch.yml 会插入 dsh-codegraph 配置行。生产环境建议在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中按同一 id 覆盖它。DSH patch 会替换整个 config，不是逐字段合并，因此要重述所有需要保留的字段。

下面示例使用 CodeGraph 1.6.0 Windows 独立发行包。serverCwd 应是稳定且未建立索引的网关目录，且其父目录也不应包含 .codegraph：

- id: dsh-codegraph
  config:
    command: C:\Tools\codegraph-1.6.0\node.exe
    args:
      - --liftoff-only
      - --disable-warning=ExperimentalWarning
      - C:\Tools\codegraph-1.6.0\lib\dist\bin\codegraph.js
      - serve
      - --mcp
    indexArgs:
      - --liftoff-only
      - --disable-warning=ExperimentalWarning
      - C:\Tools\codegraph-1.6.0\lib\dist\bin\codegraph.js
      - init
      - --yes
      - '{projectPath}'
    serverCwd: C:\Tools\codegraph-gateway
    serverName: codegraph
    projectScope: session-workspace
    autoIndex: true
    indexTimeoutMs: 120000
    indexGraceMs: 5000
    codeGraphDir: .codegraph
    mcpTools: [explore]
    toolCallTimeoutMs: 60000
    failOnStartupError: true
    disableTelemetry: true
    disableUpdateCheck: true

主要配置含义：

配置	默认值	作用
`command` / `args`	`codegraph` / `serve --mcp`	启动官方 CodeGraph MCP 服务器。生产环境应固定绝对路径。
`serverCwd`	DSH 运行目录	子进程工作目录。多 workspace 部署应显式使用未索引的网关目录。
`serverName`	`codegraph`	DSH 工具命名空间。
`projectScope`	`session-workspace`	限制查询只能使用当前 Agent workspace；`unrestricted` 会允许跨项目读取。
`codeGraphDir`	`.codegraph`	workspace 内预期的专用索引目录名；创建索引时必须使用同一设置。
`autoIndex`	`true`	在受限 workspace 首次查询前自动创建完全缺失的索引；不修复或覆盖已有目录。
`indexArgs`	`init --yes {projectPath}`	自动初始化的完整参数；必须恰好包含一个独立的 `{projectPath}`。使用 Node 独立包时要重述入口前缀。
`indexTimeoutMs`	`120000`	自动初始化的最长运行时间，超时后终止完整进程树。
`indexGraceMs`	`5000`	初始化进程从终止请求升级到强制终止的宽限时间。
`mcpTools`	`[explore]`	允许公开的上游查询工具白名单。
`toolCallTimeoutMs`	`60000`	单次 MCP 调用超时。
`failOnStartupError`	`true`	CodeGraph 启动或列举工具失败时中止插件加载。
`disableTelemetry`	`true`	给子进程设置 CodeGraph 遥测关闭标志。
`disableUpdateCheck`	`true`	关闭子进程的自动更新检查。升级由运维人员执行。
`env`	`{}`	额外的普通子进程环境变量；插件控制的保留变量不能在这里覆盖。
`reconnect`	启用，`500` ms 起步、`30000` ms 上限、最多 `10` 次	MCP 子进程断开后的有限重连策略。

组合仓库默认 patch 也接受 CODEGRAPH_BIN、CODEGRAPH_GATEWAY_CWD 和 CODEGRAPH_DIR，其中 CODEGRAPH_DIR 会映射到专用 codeGraphDir 字段。插件再从该字段给子进程设置 CODEGRAPH_DIR；不能从通用 env 重复覆盖。显式 profile 配置更容易审计和复现。不要在 env 中保存密钥； CodeGraph 输出会进入模型上下文和 DSH session log。

codeGraphDir 只接受 .codegraph，或 .codegraph- 加 1 到 64 个字母、数字、下划线或连字符的专用目录名。不能使用 src、.git、docs 等项目目录：CodeGraph 会把该名称作为索引数据排除，而 codegraph uninit 会删除对应目录。系统提示只列出同时位于 mcpTools 白名单且当前对 Agent 可见的工具；连接尚未建立或没有可见 CodeGraph 工具时，不注入误导性的工具指导。

mcpTools 可选值为 explore、search、callers、callees、impact、node、status 和 files。CODEGRAPH_MCP_TOOLS、CODEGRAPH_DIR、CODEGRAPH_TELEMETRY、 CODEGRAPH_NO_UPDATE_CHECK 和 NO_COLOR 由专用配置控制，不能放进通用 env。env 同时传给 MCP 和自动初始化进程；不要放入初始化不需要的凭据。

workspace 隔离

默认 session-workspace 模式在 MCP 调用前执行以下检查：

调用必须来自有 session workspace 的 Agent，并显式给出绝对 projectPath。
projectPath 的规范路径必须是当前 session workspace，不能是父目录、子目录或相邻仓库。
<workspace>/<codeGraphDir> 完全不存在时，autoIndex: true 才允许进入自动初始化；关闭自动创建时，codegraph.db 必须已经存在。父目录中更近或更大的索引不能替代它。
已存在但不完整的索引目录不会被自动修复或覆盖。
索引目录和 codegraph.db 不能是符号链接或 Windows junction，避免借用 workspace 外的索引。

DSH 界面中的“仅可查看”“工作区内修改”“完全权限”控制 Agent 的文件和命令权限，与这里的 projectScope 独立。选择“完全权限”不需要把 CodeGraph 改成 unrestricted；通常仍应保留 projectScope: session-workspace 和 autoIndex: true。

只有受信部署确实需要跨项目查询时才使用 projectScope: unrestricted。该模式取消上述 workspace 门禁，但不会取消精确的 mcpTools 白名单。不适合多用户或会处理不可信仓库的 DSH 主机。

门禁保护的是查询目标，不会把不可信 CodeGraph 二进制变安全，也不会逐一审计 workspace 内的所有源码链接。若仓库包含指向 workspace 外部的 symlink/junction，应在建索引前移除或明确排除，并检查索引内容；不要假定上游索引器一定不会跟随这类链接。

启用和验证

先预览 profile 的最终配置，确认存在 dsh-codegraph 层，且命令、workspace 策略和索引目录符合预期：

dsh --profile web --dump-config
dsh --profile web

从 DSH 源码运行时，对应使用 corepack pnpm dsh ...。启动成功后，在根目录尚未建立索引的测试项目中新建 session，并检查：

工具目录只出现当前已连接且列入 mcpTools 的 mcp__codegraph__codegraph_<工具名>。
第一次查询完成后，该 workspace 出现自己的 <codeGraphDir>/codegraph.db，查询结果来自该项目。
第二次查询不重新初始化；并发首次查询也只启动一个初始化进程。
用仅有父目录索引的子目录作为 workspace 时，会在子目录创建独立索引，不会返回父目录内容。
停止或卸载 profile 后，MCP 与仍在运行的自动初始化进程都退出，工具消失。

pnpm run check 只覆盖类型检查、普通测试和构建。真实 CodeGraph、profile 启动和真实模型评测是独立证据，不能由该命令代替；证据边界记录在源码仓库的 evals/README.md。

开发者可分别运行普通检查、打包检查和真实运行时测试：

corepack pnpm run check
corepack pnpm run test:integration
corepack pnpm run eval:pack
$env:DSH_CODEGRAPH_REAL_NODE = 'C:\Tools\codegraph-1.6.0\node.exe'
$env:DSH_CODEGRAPH_REAL_ENTRY = 'C:\Tools\codegraph-1.6.0\lib\dist\bin\codegraph.js'
corepack pnpm run test:real

test:real 要求两个运行时路径都存在；缺少配置不是通过结果。它会验证插件通过官方运行时自动创建夹具索引并完成查询，但不包含真实模型和生产 profile。上述自动检查也不能代替前面的 profile 手工 smoke。

停用和回滚

先停止使用该 profile 的 DSH 进程，再移除 bundle：

dsh plugin --profile web remove '@muou000/dsh-codegraph'
dsh --profile web --dump-config

回滚到旧插件版本时，移除当前包，再安装已保存的旧版本 tarball，并重新执行 profile 验证。回滚 CodeGraph 运行时时还必须恢复与旧运行时匹配的索引备份，或用旧版本重新建索引；不要让两个版本同时写同一个数据库。普通 DSH 文件搜索和读取工具不依赖本插件。

数据、备份和删除

CodeGraph 默认把数据库和元数据写入 <workspace>/.codegraph/；自定义 codeGraphDir 时位置随之改变。目录可能包含源码派生的结构信息，应排除在版本控制之外，并按源码敏感数据保护。

本插件没有自己的索引副本，也不提供通用导出格式。需要备份时，应先停止所有使用该项目的 DSH、 CodeGraph MCP 和索引进程，再连同数据库、WAL/SHM 文件、CodeGraph 配置、源码版本和运行时版本一起保存整个索引目录。恢复后用相同运行时执行 codegraph status --json <project>；跨版本恢复不应代替升级要求的重新建索引。

自定义 codeGraphDir 时，执行 status、index 或 uninit 前必须给运维进程设置相同的 CODEGRAPH_DIR；否则命令针对的是另一个索引目录。删除前先核对项目绝对路径，然后执行：

codegraph uninit D:\path\to\project

移除插件不会删除项目索引，包括插件自动创建的索引。插件查询返回的源码还会按 DSH 的正常 tool/result 事件写入 session log，其备份、保留和删除遵循 DSH 的 session 持久化配置，而不是 .codegraph 的删除流程。

已知限制

自动创建只处理“索引目录完全不存在”的首次初始化；已有不完整或损坏目录仍需人工处理。
自动创建完成后不会主动执行周期性 sync、升级重建或健康检查；索引新鲜度仍由 CodeGraph 运行时行为和运维流程决定。
CodeGraph 报告文件已变化、陈旧或不可用时，必须用权威文件读取和编译/测试结果确认。
当前只桥接 MCP 工具，不桥接 MCP resources 或服务器 instructions。
门禁检查与独立 CodeGraph 进程打开数据库不是原子操作；宿主文件系统必须由受信运维方控制，不能允许不可信进程并发替换索引路径。
确定性测试和真实运行时夹具可验证集成与隔离，不能证明生产任务一定减少 token、延迟或错误。
尚需在独立保留任务上进行真实模型评测，才能形成性能或质量结论。

文档

运行时来源与摘要：已核对的 CodeGraph 发行资产及部署记录方式。
评测说明：Loader、真实运行时和性能结论的证据边界。

许可证

MIT，见 LICENSE。

Navigation Menu

Repository files navigation

dsh-codegraph

前置条件

安装 CodeGraph CLI（必需）

自动创建项目索引

从本仓库安装

启动时报 `codegraph` 不在 PATH

配置

workspace 隔离

启用和验证

停用和回滚

数据、备份和删除

已知限制

文档

许可证

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
docs		docs
evals		evals
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
cordis.patch.yml		cordis.patch.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts

Latest commit

History

Folders and files

Repository files navigation

dsh-codegraph

前置条件

安装 CodeGraph CLI（必需）

自动创建项目索引

从本仓库安装

启动时报 codegraph 不在 PATH

配置

workspace 隔离

启用和验证

停用和回滚

数据、备份和删除

已知限制

文档

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

启动时报 `codegraph` 不在 PATH