m1khal3v/dsh-tool-codegraph

dsh-tool-codegraph

面向 DeepSeek Harness 的 CodeGraph 导航工具。
一个 DSH 插件，将开源的 codegraph CLI
（一个 AST/tree-sitter 代码索引）封装为十个专注的 agent 工具 —— status、search、
callers/callees、impact、explore 等。

本包只是一个轻量封装。 所有索引和查询工作均由
codegraph CLI 完成 —— 请先安装它，
并确保其二进制文件位于 PATH 中。

⚡️ 亮点

- 🧭 以定位为先的工作流 —— 使用规则（status → sync → explore → 定向查找）会自动注入到 agent 系统提示中。
- 🧰 十个专注的工具，每个操作对应一个 —— 没有带 action 参数的巨型工具。
- ⚡ O(1) 索引查找 —— 主会话使用轻量输出，重量级的 explore 构建被路由到子 agent。
- ⚠️ 对可靠性保持诚实 —— callers/callees/impact 可能遗漏动态分派边；提示中会告诉模型何时回退到 grep。

🛠 要求

- Node ^22.19 || >=24
- codegraph CLI 位于 PATH 中（可通过 executable 配置项覆盖）

🚀 快速开始

1. 安装插件

dsh plugin add --profile web @m1khal3v/dsh-tool-codegraph

2. 检查被封装的 CLI

codegraph status

如果二进制文件缺失，工具会回复一条安装提示，agent 会回退到基于 grep 的搜索。

3. 初始化索引 —— 由你决定

上述工具集中刻意没有 init 工具：遵循 codegraph 项目自身的建议，索引应由用户发起，而非由 agent 发起。当 codegraph status 报告索引缺失时，请自行运行：

codegraph init

在你完成之前，工具会报告索引缺失，agent 会继续使用其他搜索工具工作。

🧰 工具

| 工具 | 用途 | 输出 |
|---|---|---|
| codegraph_status | 索引健康状况与统计信息 | 轻量 |
| codegraph_sync | 同步自上次索引以来的变更 | 长 |
| codegraph_search | 按名称查找符号 | 轻量 |
| codegraph_explore | 用逐字源代码和调用路径绘制某个区域 | 重量级 |
| codegraph_callers | 谁调用了此符号（不可靠） | 轻量 |
| codegraph_callees | 此符号调用了什么 | 轻量 |
| codegraph_impact | 更改某个符号的影响范围 | 轻量 |
| codegraph_node | 一个符号的详细信息或文件视图 | 轻量 |
| codegraph_files | 来自索引的项目文件结构 | 轻量 |
| codegraph_affected | 查找受更改源文件影响的测试文件 | 轻量 |

⚙️ 配置

| 键 | 默认值 | 描述 |
|---|---|---|
| executable | codegraph | 被包装 CLI 的二进制文件名或路径 |
| queryTimeoutMs | 10000 | 常规命令的超时时间 |
| initTimeoutMs | 60000 | init / sync 的超时时间 |

🧑‍💻 开发

pnpm install
pnpm run verify    # typecheck + test
pnpm run build

📄 许可证

MIT

基于 colbymchenry/codegraph 构建。