dsh-codegraph-native

Readme

# dsh-codegraph-native

把 [codegraph](https://github.com/colbymchenry/codegraph) CLI（`@colbymchenry/codegraph`）
包装成 DSH 原生模型工具的 bundle。取代之前的 `dsh-mcp-client` + `codegraph serve --mcp`
配置：工具始终可用（不依赖 MCP 的「未索引即 0 工具」行为），且模型能自举和维护索引。

## 工具

默认（`surface: 'full'`）注册全部 13 个：

| 工具 | CLI | 用途 |
|---|---|---|
| `codegraph_status` | `status --json <path>` | 索引状态（是否已初始化等） |
| `codegraph_init` | `init -y <path>` | 初始化并建索引（模型被指引先询问用户） |
| `codegraph_index` | `index <path>` | 全量重建索引 |
| `codegraph_sync` | `sync <path>` | 增量同步（改码后调用） |
| `codegraph_uninit` | `uninit --force <path>` | 删除索引（模型被指引先确认） |
| `codegraph_query` | `query --json --path <p>` | 按名搜索符号 |
| `codegraph_node` | `node --path <p>` | 单符号源码 + 调用轨迹 / 文件模式 |
| `codegraph_explore` | `explore --path <p>` | 自然语言探索区域，一次返回源码+调用链 |
| `codegraph_files` | `files --json --path <p>` | 索引内文件结构 |
| `codegraph_callers` | `callers --json --path <p>` | 谁调用了某符号 |
| `codegraph_callees` | `callees --json --path <p>` | 某符号调用了什么 |
| `codegraph_impact` | `impact --json --path <p>` | 改动波及分析 |
| `codegraph_affected` | `affected --json --path <p>` | 改动后应跑哪些测试 |

`surface: 'core'` 只注册 `status` / `init` / `sync` / `explore`。

## 与社区版 dsh-codegraph 的差异

- **依赖用 `inject` 声明**（`tools` / `systemPrompt` / `subprocess`）：cordis 等服务就绪才加载插件，
  无惰性解析、无 shell 回退。
- **非零退出是报告不是抛错**：输出追加 `[exit code: N]` marker（官方 bash 工具的约定），
  仅 spawn 级故障走 isError。
- **`init` 带 `-y`**（非交互），避免交互提示挂住工具调用。
- **温和指引**：`guideSearch`（默认开）注入 order 98 的系统提示段——已索引时优先
  `codegraph_explore`，未索引时**先问用户**是否 init，查询无果时回退内置 grep/glob/read。
  无 MUST/INSTEAD 措辞。
- **无 frontload**：社区版的 `agent/inbox/inserted` 事件在 DSH 0.1.1-rc.2 中不存在（死代码），
  这里不实现任何 prompt 前置注入。

## 安装

```bash
dsh plugin --profile web add /Users/bruceplxl/Workspace/dsh-related/dsh-codegraph-native
dsh plugin --profile headless add /Users/bruceplxl/Workspace/dsh-related/dsh-codegraph-native
dsh plugin --profile desktop add /Users/bruceplxl/Workspace/dsh-related/dsh-codegraph-native
```

前置要求：`codegraph` CLI 在 PATH 上（`npm i -g @colbymchenry/codegraph`）。
依赖解析：web profile 的 node_modules 为 hoisted 布局，`@deepseek-ai/dsh-tools` 等以
peerDependencies 声明，与 harness 同源（与 dsh-arc-context 同一模式）。

## 配置

在 profile 的 `cordis.patch.yml` 里覆盖该行 config：

```yaml
- id: dsh-codegraph-native
  config:
    surface: core        # 默认 full；core 只注册 4 个工具
    guideSearch: false   # 默认 true；false 则不注入系统提示段
```

注意：补丁替换整行 config，需重申全部键。

## 测试

```bash
node test/run.mjs   # 24 项检查：注册/门控/真实 CLI 往返/失败路径
```

目录里的 `node_modules` 是指向 `~/.dsh/profiles/node_modules` 的符号链接，
仅供独立运行测试用；profile 内安装时不参与。