dsh-file-mention — 文件路径引用

DSH(DeepSeek Harness)Web GUI 插件:在输入框里用 @(或 /file 命令)模糊搜索 会话工作区(cwd)下的文件路径,pick 后插入 @相对路径 引用随消息发出。 Agent 自带本地文件工具,按路径自行读取或操作(查、改、测试、移动)—— 不把文件内容灌进上下文(引用自读语义,与内容注入型插件不同)。

用法

@ 内联触发(推荐):

1. 输入 @ 即弹出工作区浅层条目菜单(开头或空格后输入 @ 触发, 与 TUI 惯例一致);继续输入路径片段(如 @src/butt)自然过滤;
2. 候选菜单「file」分组列出匹配的文件与目录(最多 20 条,带路径副标题);
3. 键盘选中后按 Enter 或 Tab 补全当前高亮项(鼠标点击同样生效)。 补全遵循文件系统惯例:文件补全为 @file (空格结束);目录补全为 @dir/——确认空目录才补空格结束,有子内容(或未确认)则不加空格, 光标停在斜杠后继续输入子路径浏览;想提前结束目录浏览,手动输一个 空格即可(token 遇空白断开)。

/file 命令(@ 触发异常的备用入口):

1. 输入 /file 后直接接路径片段(如 /fileAGENTS,无空格——harness 的 trigger 检测在 token 含空格时失效);
2. pick 后同样插入 @相对路径 。

示例:请修复 @src/main.go 里的空指针 → agent 按 src/main.go 定位并操作。

功能特性

• 附件条 dock:composer 上方实时显示 draft 中所有 @路径 引用 (📁/📄 图标 + 去重),× 精确删除该引用(引用自读语义下点击打开由 agent 按路径自行完成);
• 引用装饰(lexicon):纯单词形态的文件名(如 LICENSE/Makefile)在被 引用时由管线高亮装饰,与其他引用(技能/命令)同视觉;含 .// 的路径 引用受管线 token 语法([@/][\w-]+)限制不参与装饰(官方机制,如实降级);
• 空查询浅层菜单:只输入 @ 也弹出工作区顶层条目(BFS 遍历天然浅层 优先),无需先想路径片段;
• warm 预热:打开会话即后台预热该工作区的索引(官方 warm 钩子),输入 @ 时几乎零延迟弹菜单(命中服务端 30s 缓存),无 1.5s 首查等待;
• 搜索排名:子序列模糊匹配(打错中间字母也能命中)+ basename 命中加权
  • 浅层优先(深度轻微惩罚);同等匹配质量下目录略优先;
• 目录候选:目录与文件同列(📁/📄 图标区分),pick 目录插入 @dir/ 尾斜杠引用;目录按"是否有子内容"决定补全后是否自动加空格(空目录加, 有子内容不加、允许继续浏览);
• 延迟策略:服务端 BFS 遍历 + 30s 内存缓存 + 快照文件兜底 (~/.dsh/storages/file-mention/<hash>.json)+ 1.5s 预算部分返回
  • 启动 3s 预暖;打字连发即时命中缓存;
• 新文件秒级可见:缓存命中时比对该 root 的 mtime——缓存建立后有增删 立即重扫(创建/删除文件无需等 30s 窗口);
• fetch 不互相 abort:击键产生的过时信号只丢弃对应结果,在途请求继续 存活(避免打字快于首查时菜单永远收不到结果);
• 目录副标题:候选行显示条目所在目录(ui-input-trigger 管线原生渲染)。

配置(环境变量,均可选)

变量	默认	说明
FILE_MENTION_ALLOWED_ROOTS	不启用	逗号分隔的允许搜索根目录(绝对路径)。设置后才启用白名单,白名单外的 root 返回 400;不设置则放行(与 host.listDirectory 的浏览暴露面一致)
FILE_MENTION_IGNORE_DIRS	内置剪枝表	追加剪枝目录 basename,逗号分隔
FILE_MENTION_MAX_FILES	600000	单次遍历收集文件数上限

安装

dsh plugin --profile web add github:Seryta/dsh-file-mention

安装后重启 dsh web 并刷新页面。纯手写 JS,零构建、零第三方依赖。

与同类插件的差异

项目	发送时行为	本插件的取舍
dsh-at-file	内容注入(host 在 pre-step 读文件并注入 <file> 内容)	本插件只插路径引用、agent 用工具自读:省 token、agent 可操作文件、host 不读文件内容;代价是模型需自行决定读哪些文件
dsh-wikilink	[[wikilink]] 笔记内容注入	场景不同(笔记 vs 文件路径)

已知限制

• 符号链接不跟随;不返回文件大小。
• token 语法与 harness 触发检测一致:引用路径不能含空格(含空格的文件名 无法通过输入完整路径选中)。
• 插入的是路径引用而非文件内容——agent 需要读文件时会自己调 read 工具 (这也是"操作文件"的必需信息)。超大/二进制文件不在菜单里做任何预览。
• 端点 GET /plugins/dsh-file-mention/api/search?root=&q=&limit= 仅暴露 路径列表(不读内容),与现有目录选择器的信息暴露面一致。

License

MIT