# `dsh-file-reference-everything`

[English](README.md) | 中文

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 `ctx.fileReferences` 全盘实现。它把对话框 `@` 文件补全从"当前工作区"升级为"全盘定位":[Everything](https://www.voidtools.com/) 运行时,裸文本查询通过 `es.exe` 命令行客户端毫秒级返回;否则回退到插件内建的有界全盘索引。回退索引同样支持 macOS 和 Linux,因此插件是跨平台的。工作区结果始终参与合并,并排在全盘结果之前。

## 环境要求

最佳体验——Windows 上同时满足三项:

- [Everything](https://www.voidtools.com/) 已安装并在运行。
- [es.exe](https://www.voidtools.com/support/everything/command_line_interface/) 可被发现:在 `PATH` 中、在常见安装位置(官方安装器、`%LOCALAPPDATA%\Everything`、chocolatey、scoop),或由配置键 `esPath` 指定。
- Windows(Everything 实时索引 NTFS)。

缺少任何一项插件仍可工作:它自动检测后端缺失,改用内建的有界扫描索引响应全盘查询。

关于安装 dsh CLI 本体的注记:建议使用 pnpm(如 `pnpm add -g @deepseek-ai/dsh`,或在独立目录中 `pnpm add @deepseek-ai/dsh`)。实测中 npm/npx 解析该包的大量 peer 依赖会长时间卡住(超过 10 分钟)。

## 安装

从 GitHub 安装到 `web` profile(推荐):

```sh
dsh plugin --profile web add github:lumose0/dsh-file-reference-everything
```

dsh 的 Web UI 是一个独立 profile(`dsh web` ≡ `dsh --profile web`),`@` 文件补全 UI 只存在于其中;官方 `file-reference-local` 行也只在 web profile 存在。装进其他 profile 也可以,但 `--dump-config` 会打印预期警告 `patch: entry "file-reference-local" not found`——无害,本插件自己的行照常插入。

git 安装获取的是源码而非构建产物;本包自带 `prepare` 脚本,在安装时从源码构建 `lib/`。pnpm ≥ 10 在你显式允许前拒绝运行该脚本——第一次 `add` 会失败并打印需要复制到 profile 的 `pnpm-workspace.yaml` 的包键:

```yaml
allowBuilds:
  dsh-file-reference-everything: true
```

然后重新运行 `add`。这一允许意味着授权本包在安装时于你的机器上执行代码,请审阅源码并固定 commit(`github:lumose0/dsh-file-reference-everything#<sha>`),以防后续推送悄然改变实际运行的内容。待本包发布到 npm 后,`dsh plugin --profile web add dsh-file-reference-everything` 安装的是预构建代码,无需任何构建授权。

## 生效机制

本包是一个 dsh bundle:其 `cordis.patch.yml` 层禁用官方"仅工作区"提供方的行(`id: file-reference-local`,即 `dsh-web-app` bundle 插入的同一行),并在其位置插入本插件的行。若 profile 中不存在该行(非 web profile),禁用补丁会警告并跳过,本提供方仍会挂载。不启动即可验证组合后的层:

```sh
dsh --profile web --dump-config
```

输出中应包含 `# == dsh-file-reference-everything` 层,其中 `file-reference-everything` 行被插入;在 web profile 中,官方 `file-reference-local` 行显示 `disabled: true`。

## 查询语法

`@`(路径含空格时用 `@"`)之后的内容即查询。正则模式之外,`\` 等同于 `/`。

| 查询 | 行为 |
|---|---|
| `@config`(裸文本) | 在工作区索引与全盘后端的合并结果上模糊搜索;工作区结果排在前面。 |
| `@re:pattern` / `@regex:pattern` | 正则表达式匹配,覆盖工作区与全盘。 |
| `@D:/...`、`@//server/share/...`、`@/usr/...`、`@~/...` | 浏览对应绝对目录(`~` 展开为用户主目录)。 |
| `@src/comp`(含 `/` 的相对路径) | 相对 agent cwd 浏览,与官方提供方一致。 |

由 Everything 响应时,裸查询原样透传为 Everything 原生语法:空格表示 AND,通配符及其余 [Everything 搜索语法](https://www.voidtools.com/support/everything/searching/)照常可用。

## 配置

| 配置键 | 默认值 | 契约 |
|---|---:|---|
| `maxResults` | `20` | 单次查询返回的候选项最大数量。 |
| `workspaceMaxEntries` | `10000` | 每个 agent 工作区建立索引的文件和目录最大数量。 |
| `globalMaxEntries` | `200000` | 全盘回退索引中建立索引的文件和目录最大数量。 |
| `excludedDirectories` | `[".git", "node_modules", "$Recycle.Bin", "System Volume Information", "Windows", "Program Files", "Program Files (x86)", "ProgramData", "AppData", ".cache", ".npm", ".pnpm-store", "Library", "proc", "sys", "dev"]` | 回退索引永不遍历、永不提供的目录基名。 |
| `roots` | `[]` | 全盘扫描根;空数组表示自动探测——Windows 上为所有存在的盘符,其他平台为用户主目录。 |
| `esPath` | 未设置 | 显式 `es.exe` 路径;未设置时自动探测(先 `PATH`,再常见安装位置)。 |
| `everythingTimeoutMs` | `2000` | 单次 `es.exe` 调用的超时毫秒数;超时后回退到内建索引。 |
| `refreshSeconds` | `600` | 全盘回退索引的保鲜秒数,过期后下一次查询触发惰性重建。 |
| `workspaceBonus` | `100` | 合并结果中施加给工作区候选项的加分,使其保持在全盘结果之前。 |

在 profile 的 `cordis.patch.yml`(应用于所有 bundle 层之后)覆盖该行:

```yaml
- id: file-reference-everything
  name: dsh-file-reference-everything
  config:
    maxResults: 30
    roots: ['C:/', 'D:/']
```

补丁会整体替换该行的 `config` 值而非按键深合并,因此需写出你想要的全部非默认键;省略的键取上表的 schema 默认值。

## 模型体验

### `read` 可用时的文件引用指引

#### 模型看到什么

当指定 agent 有实际生效的 `read` 工具时,本提供方贡献与官方提供方相同的稳定系统提示词段:

```markdown
Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
```

#### Token 影响

该影响有条件且固定:只要 `read` 对指定 agent 可见,这一句就会存在;候选查询本身不增加 token,所选路径只贡献普通用户消息中的对应字符。

## 已知限制

- **选中的路径只是文本引用。**读取其内容仍需模型调用 `read` 工具,并受部署的文件系统命名空间与权限约束——补全中可见的全盘路径可能对工具不可读。
- **回退索引有界且惰性。**超出 `globalMaxEntries` 的路径被省略;索引仅在 `refreshSeconds` 过期后的下一次查询时重建;没有忽略文件语义——只跳过 `excludedDirectories` 中的目录基名。
- **`es.exe` 选项冲突。**以 `-` 开头的查询可能被 `es.exe` 解析为选项而非搜索词。
- **`where.exe` 非 ASCII 输出。**某些控制台代码页下 `where.exe` 无法可靠报告 `es.exe` 路径(非 ASCII 路径)时,探测回退到静态安装位置列表。
- **可能出现重复条目。**同一文件可能出现两次:一次为工作区相对候选项,一次为全盘绝对候选项。
- **Everything 专属语法得固定分。**本插件自有评分器无法匹配的结果(例如通配符命中)得到固定低分,而非精确排名。

## 开发

```sh
npm install
npx vitest run
npx tsdown
```

不要用 `dsh plugin --profile <name> add <本地目录>` 验证 RPC 链路:目录安装走 pnpm `link:`,Node 按 realpath 从开发目录自身的 `node_modules` 解析依赖,会加载 `@deepseek-ai/dsh-file-reference` 的私有副本,宿主的 Typert 网关因模块实例不一致而无法发现 `fileReferences/list` 远程方法——补全静默为空。请改用打包产物验证:`npm pack` 后 `dsh plugin --profile web add ./dsh-file-reference-everything-<version>.tgz`(或直接 `github:` 安装),此时 peer 依赖解析到宿主实例,链路开箱即用。

## 许可证

MIT