仓库探索器kkllxy/dsh-repo-explore

dsh-repo-explore — 面向 DeepSeek Harness 的仓库探索器

为你的 DeepSeek Harness 编码智能体提供一个窄接口的 repo_explore({ query }) 工具：一个本地 READ / GREP / GLOB 循环，用于定位任务所需的精确文件和行范围——这样主智能体就不会再把 token 浪费在盲目搜索上。

Main DeepSeek agent
│ repo_explore({query})
▼
local explorer loop (in the session cwd)
├── GREP ──► repo
├── GLOB ──► repo
└── READ ──► repo
│ OpenAI-compatible HTTP
▼
GLM-4.7 (default) · GLM-4.7-Flash (free) · Qwen · any compatible endpoint

默认情况下无需 GPU、无需本地模型、无需外部 CLI——模型和端点纯靠配置。

插件

| 包 | 角色 |
| --- | --- |
| @local/dsh-subagent-openai-explorer | 默认提供方。 进程内探索器循环，对接任意 OpenAI 兼容的 chat completions API（默认 GLM-4.7，禁用思考）。 |
| @local/dsh-subagent-fastcontext | 对照组提供方：运行 Microsoft FastContext CLI。 |
| @local/dsh-tool-repo-explore | 面向模型的 repo_explore 工具；提供方可配置（openai-explorer \| fastcontext）；解析  引用。 |

repo_explore 只回答“主智能体应该读取哪些文件和行范围？”——主智能体仍需验证、实现和测试。

快速开始

前置条件：已安装 DeepSeek Harness（npm i -g @deepseek-ai/dsh）、Node ≥ 22、pnpm。

pnpm bootstrap:deps   # resolve the local Harness install for build deps
pnpm install
pnpm build            # compile all packages -> packages//lib/

bash scripts/mount-dsh.sh web headless   # symlink plugins + write profile patch
dsh --profile web --dump-config          # expect subagent-openai-explorer / tool-repo-explorer rows

配置密钥（默认值已指向 GLM-4.7）：

export GLM_API_KEY=your-key
free alternative: export OPENAI_EXPLORER_MODEL=glm-4.7-flash
Alibaba Bailian Qwen: OPENAI_EXPLORER_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 \
OPENAI_EXPLORER_MODEL=qwen3.7-flash DASHSCOPE_API_KEY=...

从已挂载的行中移除 disabled: true（或重新运行 mount-dsh.sh），重启该 profile，新对话中就有 repo_explore 了。

无需密钥的冒烟测试（模拟模型服务器）：

node scripts/mock-glm-server.mjs --port 30100 &
dsh --profile headless --patch smoke/glm-overlay.patch.yml \
"Use repo_explore to locate where request validation happens in this repo, then read the cited files and summarize."

探索器循环控制

与 FastContext 保持一致，这样小模型就不会淹没上下文：maxTurns=6、grepMaxResults=50、globMaxResults=100、readMaxLines=200、maxCitations=8、maxOutputTokens=1000。代码工具始终在本地运行；只有模型要求读取的代码片段才会通过网络传输。

基准测试 / 实测结论
在本仓库的脚本上实测（node scripts/bench-openai-explorer.mjs、node scripts/bench-usage.mjs --repo  --query  --naive ），真实 GLM-4.7（thinking 关闭），2026-08。

在 80 MB 的 deepseek-harness monorepo 上的窄「找东西」任务 —— 「SubagentProvider 接口定义在哪里？」*：

| | 朴素方式（主 Agent 自己搜索） | repo_explore（GLM-4.7 循环） |
| --- | --- | --- |
| 主上下文中的 token | ~2,000（grep 64 处匹配 ≈5.7 KB + 读取目标 ≈2.3 KB） | 1 行引用 ≈10–50 |
| 模型 API token | 主模型重新读取那 ~2 K（通常多轮） | GLM-4.7 隔离循环 5.4 K–12.6 K（轨迹从不进入主上下文） |
| 延迟 | 多轮 grep/read | 每次调用 11–19 s |
| 准确率 | — | 3/3 次运行返回相同的行级精确引用 packages/subagent/subagent/src/types.ts:285-324 |

主上下文缩减约 40–200×；探索器自身的成本落在另一个小型/廉价模型上。

在你信任它之前需要了解的发现：

- 单一焦点查询能可靠收敛（上述 3/3；fixture 仓库 2/3 行级精确范围）。
- 在很小的仓库上，朴素搜索也很便宜（~2×），所以该工具在真实 monorepo 上才有回报，而非玩具 fixture。
- 宽泛的多部分查询（「定位 X 并追踪 Y 如何调用它」）在 maxTurns=6 内不会收敛（0/3，~43 K prompt token）——保持查询单一焦点，或提高 maxTurns。
- GLM-4.7-Flash 免费但被限流（1302/1305），且其输出格式在测试中不稳定——这就是默认模型为 GLM-4.7（thinking 关闭）的原因。

链接

- Microsoft FastContext —— 本插件可作为对照组运行的 4B 专用探索器
- DeepSeek Harness —— 宿主平台
- 智谱 BigModel 开放平台 —— 默认模型提供方（文档）

邀请链接：我正在智谱大模型开放平台 BigModel.cn 上打造 AI 应用，智谱新一代旗舰模型 GLM-5.2 已上线，在推理、代码、智能体综合能力达到开源模型 SOTA 水平。通过我的邀请链接注册即可获得 2000 万 Tokens 大礼包，期待和你一起在 BigModel 上畅享卓越模型能力。
链接：https://www.bigmodel.cn/invite?icode=a8p6eEcjG8uRqi0vG1lvPpmwcr074zMJTpgMb8zZZvg%3D

BigModel 邀请海报

许可证

MIT

中文版

给 DeepSeek Harness 加一个窄工具 repo_explore({ query })：本地 READ / GREP / GLOB 探索循环，先定位任务相关的文件和精确行号，主 Agent 不再盲搜烧 token。默认走云端 OpenAI-compatible API（GLM-4.7，thinking 关闭；免费备选 GLM-4.7-Flash），不需要 GPU / 本地模型 / 外部 CLI，模型与端点纯配置。

插件

| 包 | 作用 |
| --- | --- |
| @local/dsh-subagent-openai-explorer | 默认 provider：进程内探索循环，对接任意 OpenAI-compatible chat completions（GLM-4.7 默认） |
| @local/dsh-subagent-fastcontext | 对照组 provider：运行 Microsoft FastContext CLI |
| @local/dsh-tool-repo-explore | 主模型面对的 repo_explore 工具；provider 可切换；解析  citations |

repo_explore 只回答「主 Agent 该读哪些文件和行号」，复核/实现/测试仍由主 Agent 负责。

快速开始
pnpm bootstrap:deps && pnpm install && pnpm build
bash scripts/mount-dsh.sh web headless    # 挂载插件
export GLM_API_KEY=你的key                # 默认即 GLM-4.7

无 key 冒烟测试:node scripts/mock-glm-server.mjs --port 30100 & 后,按上面的 headless 示例跑即可。循环上限与 FastContext 对齐(maxTurns=6、grep 50、glob 100、read 200 行、citations 8)。代码工具始终在本地,只有模型要求阅读的片段会发往云端。

实测结论

数据来源:本仓库脚本 node scripts/bench-openai-explorer.mjs、node scripts/bench-usage.mjs --repo  --query  --naive ,真实 GLM-4.7(thinking 关闭),2026-08 实测。

窄「找东西」任务(80MB deepseek-harness monorepo)——"SubagentProvider 接口定义在哪?"

| | 主 Agent 盲搜 | repo_explore(GLM-4.7 循环) |
| --- | --- | --- |
| 主上下文占用 | ≈2,000 tokens(grep 64 处匹配 ≈5.7KB + 读目标 ≈2.3KB) | 1 行 citation ≈10–50 tokens |
| 模型 API 用量 | 主模型消化 ≈2K tokens(通常还要多轮) | GLM-4.7 独立循环 5.4K–12.6K(轨迹不进主上下文) |
| 延迟 | 多轮 grep/read | 每次调用 11–19s |
| 准确度 | — | 3/3 轮返回同一行号准确结果 packages/subagent/subagent/src/types.ts:285-324 |

主上下文约省 40–200×;explorer 自身开销落在独立的小/便宜模型上。

用之前要知道的结论:

- 单目标问题收敛稳定(上面 3/3;fixture 小仓库 2/3,行号准确)。
- 小仓库上盲搜本身也便宜(约 2×),所以这个工具的价值在大 monorepo,不在玩具 fixture。
- 宽泛多段问题("定位 X 并追踪 Y 的调用链")在 maxTurns=6 内不收敛(0/3,约 43K prompt tokens)——保持 query 单目标,或调大 maxTurns。
- GLM-4.7-Flash 免费但实测限流(1302/1305)且输出格式不稳定——所以默认模型是 GLM-4.7(thinking 关闭)。

相关链接(中文版)

- Microsoft FastContext — 4B 专科探索模型(对照组)
- DeepSeek Harness — 宿主平台
- 智谱 BigModel 开放平台(文档) — 默认模型提供方

邀请链接:我在智谱 BigModel.cn 上打造 AI 应用,GLM-5.2 旗舰模型已上线。通过邀请链接注册可获 2000 万 Tokens 礼包:https://www.bigmodel.cn/invite?icode=a8p6eEcjG8uRqi0vG1lvPpmwcr074zMJTpgMb8zZZvg%3D

License

MIT