ZK-Andy/dsh-frecency

dsh-frecency

English | 中文

A DeepSeek Harness plugin that takes over the built-in grep / glob file-search tools: grep runs on a resident index with frecency ranking, glob mirrors the built-in discovery semantics exactly when ripgrep is available (and degrades to the resident index otherwise).

The built-in tools spawn a fresh ripgrep process on every call and scan from scratch. In long sessions with many parallel subagents, the same searches run dozens of times. dsh-frecency keeps one resident index per working directory (the Rust fff engine via @ff-labs/fff-node), so repeated searches answer from that hot memory instead of spawning ripgrep per call, ranked by access/modification frecency.

Install

dsh plugin --profile <profile> add dsh-frecency

Restart dsh and start a session — grep / glob keep their names and schemas; grep hits the resident index and glob serves the same results as the built-in tool, whatever agent preset you use. The built-in search tools are mounted per-session on the agent plane, which beats any host-plane registration, so the plugin registers into each agent's own layer at agent creation (first-party precedent: dsh-tool-subagent). Config enabled: false or removing the plugin falls back to the built-in ripgrep tools.

Host packages come from the running installation: @deepseek-ai/dsh-tools, @deepseek-ai/dsh-tool-fs-search, @deepseek-ai/dsh-output-retention and @deepseek-ai/schemastery are resolved through the profile's module resolution, never installed alongside the plugin. Built and tested against DSH 0.1.2-alpha.3 through 0.2.1-alpha.1.

What you get

• Same tool names — grep / glob keep their names and schemas; the model switches with zero prompt changes.
• Resident index (grep) — repeated content searches reuse one in-memory index instead of spawning ripgrep per call; measured 2.5–2.7× faster on a 14k-file tree (baseline).
• Frecency ranking (grep) — frequently opened / recently modified files surface first.
• Built-in-parity glob — glob runs the same fixed rg --files invocation as the built-in tool: hidden and ignored files included, VCS metadata excluded, modification-time order. If ripgrep is unavailable, it degrades to the resident index.
• Annotated grep output — engine-classified isDefinition and per-file gitStatus ride along in grep results, so the model can spot definition lines and modified files without re-reading.
• Git-aware index — the engine tracks working-tree state per file and surfaces it as gitStatus in results.
• Graceful fallback — if the native engine can't load, the plugin steps aside and the built-in ripgrep tools keep working.

See docs/design.md for the full design rationale.

Development

pnpm install
pnpm check      # typecheck + build + test
scripts/setup-hooks.sh   # point git hooks at .githooks/ (pre-commit / pre-push)

Local e2e against a real harness: build, then boot the default headless profile with a --patch overlay pointing at ./dist/index.js.

Quality gates: python3 scripts/verify-adr-format.py && python3 scripts/verify-handoff-structure.py && python3 scripts/verify-doc-budgets.py --manifest scripts/doc-budgets.manifest.json && python3 scripts/verify-md-links.py.

License

MIT