dsh-codegraph
DSH（DeepSeek Harness）host 插件：把 lazycodex（omo 插件）里向上下文注入 CodeGraph的工具提取出来，移植到 DSH。
来源 / Source：lazycodex → plugins/omo/components/codegraph/
（@sisyphuslabs/codex-codegraph，CodeGraph MCP 包装 + 引导/初始化指引 hooks）
它做了什么
| 能力 | lazycodex（Codex） | dsh-codegraph（DSH） |
|---|
| 工具注入 | .mcp.json 的 codegraph MCP server → codegraph_explore | spawn vendored serve.js 作为 MCP server，把 codegraph_explore 注册为 mcp__codegraph__codegraph_explore |
| 上下文指引 | SessionStart/PostToolUse hooks 与 skills 注入 CodeGraph 使用说明 | 工具调用前：ctx.systemPrompt.section({ name: 'codegraph:policy' }) 注入系统提示词；连接成功后优先用 codegraph MCP server 自带的 instructions（权威详尽），未连接时回退到配置的 guidanceSection |
| 自动索引引导 | SessionStart hook → codegraph init | agent/session-start → 复用 vendored cli.js hook session-start 后台执行 codegraph init（含项目锁、指数退避冷却、后台 worker） |
| 未初始化指引 | PostToolUse hook → additionalContext | tools/result 监听 codegraph 工具，检测到「未初始化」→ agent.inject() 向下一次请求注入指引 |
结构
dsh-codegraph/
├── package.json # dsh bundle 插件清单（dsh.bundle.patch = cordis.patch.yml）
├── cordis.patch.yml # bundle patch：要插入的 loader 行（id: codegraph）
├── dsh.plugin.json # 插件注册表清单
├── lib/
│ ├── index.js # host 半 cordis 插件：工具注册 + 提示词注入 + 引导 + 结果指引
│ ├── config.js # 配置 schema（schemastery）
│ ├── constants.js # 环境变量名 / 工具名匹配 / 默认指引文本
│ ├── guidance.js # 「未初始化」检测 + 指引文本（提取自 cli.js 的 guidance.ts）
│ ├── mcp-client.js # 最小自包含 MCP stdio 客户端桥（无 SDK 依赖）
│ ├── bootstrap.js # 会话开始引导驱动
│ └── codegraph/ # 从 lazycodex 原样提取的自包含产物（零 Node 外依赖）
│ ├── serve.js # codegraph MCP 包装器（自动解析/安装二进制、Node 版本门、unavailable stub）
│ └── cli.js # hook CLI（session-start / post-tool-use / session-start-worker）
└── test/ # node --test 自测
lib/codegraph/serve.js / cli.js 是 lazycodex 构建产物（bun build 打成自包含 Node ESM，
无运行时依赖），原样复制，未做改动。
挂载
本地挂载（开发）
手动改 profile（~/.dsh/profiles/web/）：
package.json 的 dependencies 加 "dsh-codegraph": "link:C:/Git/dsh-codegraph"package.json 的 dsh.profile.bundles 追加 "dsh-codegraph"cordis.patch.yml 追加：
- insert:
- id: codegraph
name: 'dsh-codegraph'
挂载后 pnpm install（profile 目录），完全退出并重开 DSH web（bundle 型插件需要重启加载），
然后重启会话。模型侧应能看到 mcp__codegraph__codegraph_explore 工具。
本地 link 时，插件目录需要能解析 @deepseek-ai 的 host peer 包；仓库已把这些包放进
devDependencies，clone 后先 npm install 即可。
npm 已发布
dsh plugin --profile web add dsh-codegraph
配置
通过 profile 的 cordis.patch.yml 里的 loader 行 config: 传入，或在代码里以
{ name: 'dsh-codegraph', config: {...} } 方式加载：
- insert:
- id: codegraph
name: 'dsh-codegraph'
config:
enabled: true
serverName: codegraph
projectRoot: '' # 留空 = DSH_CODEGRAPH_PROJECT_CWD → 进程 cwd
codegraphBin: '' # 二进制路径覆盖（原 OMO_CODEGRAPH_BIN）
installDir: '' # 受管安装目录（原 CODEGRAPH_INSTALL_DIR），默认 ~/.omo/codegraph
mcpEnabled: true
toolCallTimeoutMs: 120000
bootstrap: true
initGuidance: true
# guidanceSection: '自定义系统提示词指引…'
| 字段 | 类型 | 默认 | 说明 |
|---|
enabled | boolean | true | 总开关 |
serverName | string | codegraph | 工具名前缀 mcp__<serverName>__… |
projectRoot | string | '' | CodeGraph 索引起点；留空自动 |
codegraphBin | string | '' | 二进制覆盖（原 OMO_CODEGRAPH_BIN） |
installDir | string | '' | 受管安装目录（原 CODEGRAPH_INSTALL_DIR） |
mcpEnabled | boolean | true | 是否注册 MCP 工具 |
toolCallTimeoutMs | number | 120000 | 单次工具调用超时 |
bootstrap | boolean | true | 会话开始后台 codegraph init |
initGuidance | boolean | true | 未初始化时注入指引 |
guidanceSection | string | 内置 | 系统提示词里的 CodeGraph 指引 |
注意：vendored 运行时内部的 auto_provision、session_start_cooldown_ms、
trustedCodegraphInstallDir 等仍由 OMO 配置（~/.omo/omo.jsonc 或项目 .omo/omo.jsonc）或
其默认值决定；插件配置不重复实现，只通过环境变量（OMO_CODEGRAPH_BIN / CODEGRAPH_INSTALL_DIR）
覆盖二进制与安装目录。
验证
# 1) 单元自测（纯 Node，无 DSH 依赖）
cd C:/Git/dsh-codegraph && node --test test/*.test.mjs
# 2) 冒烟：用假 codegraph 二进制跑一遍 vendored MCP 包装器（test/serve-smoke.test.mjs）
# 3) 在 DSH 里
dsh web --dump-config | grep codegraph # 组合里能看到插件行
重启后在任意会话里问「用 codegraph 看看 X 是怎么工作的」，模型应优先调用
mcp__codegraph__codegraph_explore。若项目未索引，会看到后台 bootstrap 生成 .codegraph/，
且工具结果会附带初始化指引。
环境变量（透传给 vendored 运行时）
| 变量 | 说明 |
|---|
OMO_CODEGRAPH_BIN / CODEGRAPH_BIN | codegraph 可执行文件路径覆盖 |
OMO_CODEGRAPH_PROJECT_CWD / OMO_CODEGRAPH_SESSION_START_CWD | 项目根目录覆盖 |
CODEGRAPH_INSTALL_DIR | 受管安装目录（默认 ~/.omo/codegraph） |
OMO_CODEGRAPH_DEBUG=1 | 打开 vendored 运行时调试日志 |
DSH_CODEGRAPH_PROJECT_CWD | 插件专用项目根目录覆盖（优先级低于 config.projectRoot） |
与 lazycodex 的映射
| lazycodex 文件 | 本仓库 |
|---|
plugins/omo/components/codegraph/dist/serve.js | lib/codegraph/serve.js（原样复制） |
plugins/omo/components/codegraph/dist/cli.js | lib/codegraph/cli.js（原样复制） |
src/post-tool-use-hook.ts + utils/src/codegraph/guidance.ts | lib/guidance.js（提取 + DSH 化文本） |
src/hook.ts / src/session-start-worker.ts（SessionStart 引导） | lib/bootstrap.js + 复用 cli.js hook session-start |
.codex-plugin/plugin.json hooks | lib/index.js 的 ctx.systemPrompt / agent/session-start / tools/result |
.mcp.json server codegraph | lib/mcp-client.js（DSH 侧 MCP 客户端桥） |
与 lazycodex 的行为对齐与已知差异
完全对齐（字节级复用，行为一致）
lib/codegraph/serve.js / cli.js 为 lazycodex 构建产物原样复制：二进制解析顺序、auto-provision、
Node 版本门、项目排除策略、unavailable stub、includeCode 契约重写、daemon 模式、
CODEGRAPH_NO_DOWNLOAD / telemetry 关闭等全部保留。- 会话开始引导全流程：精确
.codegraph/codegraph.db 探测、祖先覆盖（skipped-nested-root）、
原子锁（skipped-locked）、stale 锁恢复 + 指数冷却（15min 起、翻倍至 24h）、后台 worker、
~/.omo/codegraph/session-start.jsonl 落盘。
- 未初始化检测逻辑（正则集）与
mcp__codegraph__codegraph_explore 工具命名一致；
工具调用前指引（含 codegraph 服务器自带 instructions）已注入系统提示词。
已知差异 / 限制
| 项 | lazycodex | dsh-codegraph | 影响 |
|---|
| 受管安装目录 | trusted_install_dir（仅 OMO config） | 插件 installDir 只映射 CODEGRAPH_INSTALL_DIR 环境变量 | 重定向二进制安装目录需在 OMO config 配 [codex].codegraph.install_dir |
| 组件 Node 运行时 | 用 Node 24 LTS 跑 serve.js/cli.js（规避 Node≥25 崩溃） | 默认用 DSH 的 process.execPath | provisioned 解析不受影响；PATH 解析在 Node≥25 下会被 node gate 拦（可设 CODEGRAPH_ALLOW_UNSAFE_NODE=1） |
| 未暴露的配置键 | auto_provision / excluded_roots / daemon / session_start_cooldown_ms / watch_debounce_ms（OMO config） | 未暴露为插件配置 | 这些键仍被 vendored 代码从 OMO config 读取，如需控制请写 ~/.omo/omo.jsonc 或项目 .omo/omo.jsonc |
许可
本仓库的插件胶水代码为 MIT（见 LICENSE）；lib/codegraph/ 下的构建产物与其
NOTICE / NODE-RUNTIME-LICENSES.md 一并保留 lazycodex / OmO 的原始归属与第三方许可声明。
