dsh-repo-explore

August 13, 2026 · View on GitHub

Give your DeepSeek Harness coding agent a narrow repo_explore({ query }) tool: a local READ / GREP / GLOB loop that locates the exact files and line ranges a task needs — so the main agent stops burning tokens on blind searching.

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

No GPU, no local model, no external CLI by default — model and endpoint are pure configuration.

Plugins

PackageRole
@local/dsh-subagent-openai-explorerDefault provider. In-process explorer loop against any OpenAI-compatible chat completions API (GLM-4.7 default, thinking disabled).
@local/dsh-subagent-fastcontextControl-group provider: runs the Microsoft FastContext CLI.
@local/dsh-tool-repo-exploreModel-facing repo_explore tool; provider is configurable (openai-explorer | fastcontext); parses <final_answer> citations.

repo_explore only answers "which files and line ranges should the main agent read?" — the main agent still verifies, implements and tests.

Quick start

Prereqs: DeepSeek Harness installed (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

Configure the key (defaults already point at 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=...

Remove disabled: true from the mounted rows (or re-run mount-dsh.sh), restart the profile, and a new conversation has repo_explore.

Smoke test without a key (mock model server):

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."

Explorer loop controls

Aligned with FastContext so small models cannot flood the context: maxTurns=6, grepMaxResults=50, globMaxResults=100, readMaxLines=200, maxCitations=8, maxOutputTokens=1000. Code tools always run locally; only the snippets the model asks to read cross the wire.

Benchmarks / 实测结论

Measured on this repo's scripts (node scripts/bench-openai-explorer.mjs, node scripts/bench-usage.mjs --repo <path> --query <q> --naive <a,b>), real GLM-4.7 (thinking disabled), 2026-08.

Narrow "find something" task on the 80 MB deepseek-harness monorepo — "Where is the SubagentProvider interface defined?":

Naive (main agent searches itself)repo_explore (GLM-4.7 loop)
Tokens in the main context~2,000 (grep 64 matches ≈5.7 KB + read target ≈2.3 KB)1 citation line ≈10–50
Model API tokensmain model re-reads those ~2 K (often several rounds)GLM-4.7 isolated loop 5.4 K–12.6 K (trajectory never enters the main context)
Latencyseveral grep/read rounds11–19 s per call
Accuracy—3/3 runs returned the same line-accurate citation packages/subagent/subagent/src/types.ts:285-324

Main-context reduction ≈ 40–200×; the explorer's own cost lands on a separate small/cheap model.

Findings to know before you trust it:

  • Single-focus queries converge reliably (3/3 above; fixture repo 2/3 with line-accurate ranges).
  • On tiny repos the naive search is cheap too (~2×), so the tool pays off on real monorepos, not toy fixtures.
  • Broad multi-part queries ("locate X and trace how Y calls it") do not converge inside maxTurns=6 (0/3, ~43 K prompt tokens) — keep the query single-focus, or raise maxTurns.
  • GLM-4.7-Flash is free but was rate-limited (1302/1305) and its output format was unstable in testing — that's why the default model is GLM-4.7 (thinking disabled).

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

BigModel invite poster

License

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 可切换;解析 <final_answer> 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 <a,b>,真实 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 关闭)。

相关链接(中文版)

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

License

MIT