全盘文件引用lumose0/dsh-file-reference-everything

dsh-file-reference-everything

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

环境要求

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

- Everything 已安装并在运行。
- es.exe 可被发现:在 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(推荐):

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 的包键:

allowBuilds:
dsh-file-reference-everything: true

然后重新运行 add。这一允许意味着授权本包在安装时于你的机器上执行代码,请审阅源码并固定 commit(github:lumose0/dsh-file-reference-everything#),以防后续推送悄然改变实际运行的内容。待本包发布到 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),禁用补丁会警告并跳过,本提供方仍会挂载。不启动即可验证组合后的层:

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 搜索语法照常可用。

配置

| 配置键 | 默认值 | 契约 |
|---|---:|---|
| 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 层之后)覆盖该行:

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

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

模型体验

read 可用时的文件引用指引

模型看到什么

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

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 专属语法得固定分。本插件自有评分器无法匹配的结果(例如通配符命中)得到固定低分,而非精确排名。

开发

npm install
npx vitest run
npx tsdown

不要用 dsh plugin --profile  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-.tgz(或直接 github: 安装),此时 peer 依赖解析到宿主实例,链路开箱即用。

许可证

MIT