# dsh-frecency

[English](./README.md) | 中文

<p align="center">
  <a href="https://www.npmjs.com/package/dsh-frecency"><img src="https://img.shields.io/npm/v/dsh-frecency?style=flat&label=npm&color=4D6BFE" alt="npm"></a>
  <a href="https://www.npmjs.com/package/dsh-frecency"><img src="https://img.shields.io/npm/dt/dsh-frecency?style=flat&label=downloads&color=4D6BFE" alt="downloads"></a>
  <a href="https://github.com/ZK-Andy/dsh-frecency/stargazers"><img src="https://img.shields.io/github/stars/ZK-Andy/dsh-frecency?style=flat&label=stars&color=4D6BFE" alt="stars"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://github.com/ZK-Andy/dsh-frecency/actions/workflows/ci.yml"><img src="https://github.com/ZK-Andy/dsh-frecency/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="./docs/testing.md"><img src="https://img.shields.io/badge/tests-69%2F69-brightgreen" alt="tests"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-339933" alt="node >= 22"></a>
</p>

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：接管内置 `grep` / `glob` 文件搜索——`grep` 跑在**常驻索引 + frecency 排序**上，`glob` 在 ripgrep 可用时与内置发现语义完全对齐（不可用时降级到常驻索引）。

内置工具每次调用都 spawn 一个全新的 ripgrep 进程、从零扫描；长会话与多子代理场景下同样的搜索会重复执行数十次。dsh-frecency 为每个工作目录保留一份常驻索引（Rust [fff](https://github.com/dmtrKovalenko/fff) 引擎，经 `@ff-labs/fff-node`），复用热内存索引、省去每次 spawn，结果按访问/修改 frecency 排序。

## 安装

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

重启 dsh 并开一个会话即可——`grep` / `glob` 工具名与参数不变，`grep` 命中常驻索引、`glob` 与内置工具同结果，且**无论你用哪个 agent 预设都生效**。内置搜索工具由 agent 预设挂载在会话近端（agent 平面），host 平面注册赢不了它，所以插件在**每个 agent 创建时把工具注册进 agent 自己的层**（第一方先例：`dsh-tool-subagent`）。配置 `enabled: false` 或卸载插件即回退内置 ripgrep 工具。

## 你得到什么

- **同名工具**——`grep` / `glob` 工具名与参数不变，模型零提示词改动即切换。
- **常驻索引（grep）**——重复内容检索复用同一份内存索引，省去每次 spawn ripgrep；14k 文件实测 2.5–2.7×（[基线](docs/performance.md)）。
- **frecency 排序（grep）**——常打开、最近改的文件优先呈现。
- **内置平价 glob**——glob 跑与内置工具同一条固定 `rg --files` 命令：含 hidden 与 ignored 文件、排除 VCS 元数据、按修改时间排序。ripgrep 不可用时降级到常驻索引。
- **标注的 grep 输出**——引擎分类的 `isDefinition` 与逐文件 `gitStatus` 随 grep 结果一起返回，模型无需重读即可识别定义行与已改文件。
- **git 感知索引**——引擎按文件跟踪工作区状态，并以 `gitStatus` 暴露在结果中。
- **优雅降级**——native 引擎加载失败时插件自动让位，内置 ripgrep 工具照常工作。

设计动机与取舍详见 [docs/design.md](./docs/design.md)。

## 开发

```sh
pnpm install
pnpm check      # typecheck + build + test
scripts/setup-hooks.sh   # git hooks 指向 .githooks/（pre-commit / pre-push）
```

真实 harness 的本地 e2e：构建后用默认 headless profile 加 `--patch` 覆盖层（指向 `./dist/index.js`）启动。

质量门禁：`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`。

## 许可

[MIT](./LICENSE)