在 DSH (DeepSeek Harness) 中开发智能体时，让 Agent 读写本地文件是常见需求。直接将文件内容灌入上下文会消耗大量 token，且可能包含无关信息。dsh-file-mention 插件提供了在输入框中直接引用文件路径的方案。Agent 收到该引用后，会通过自带的本地文件工具按路径自行读取或操作文件，而不是将内容注入上下文。
功能概述¶
这是由 Seryta 维护的 DSH Web GUI 插件。核心能力是在输入框里用 @（或 /file 命令）模糊搜索会话工作区下的文件路径，选中后插入 @相对路径。
主要特性包括：
- 双入口触发：支持
@内联触发（推荐）和/file命令触发。 - 模糊搜索：支持子序列模糊匹配，如输入
src/butt可命中src/button.go。 - 实时索引：打开会话即后台预热索引，利用服务端 BFS 遍历和 30s 内存缓存，新文件秒级可见。
- 交互体验：输入
@即弹出工作区顶层条目菜单。支持键盘（Enter/Tab）或鼠标选择。Composer 上方会显示附件条 dock，列出 draft 中的所有引用。纯单词形态的文件名（如Makefile）会被高亮装饰。 - 并发控制：击键产生的过时信号只丢弃对应结果，在途请求继续存活，避免打字快于首查时菜单无法更新。
安装与启用¶
使用官方安装命令添加插件：
dsh plugin --profile web add github:Seryta/dsh-file-mention
安装后重启 dsh web 并刷新页面。
典型用法¶
1. @ 内联触发¶
这是推荐的用法。
- 在输入框开头或空格后输入
@，弹出工作区浅层条目菜单。 - 继续输入路径片段（如
@src/butt）进行过滤。 - 候选菜单按
file分组列出匹配的文件与目录。 - 键盘选中后按 Enter 或 Tab 补全当前高亮项（鼠标点击同样生效）。
补全遵循文件系统惯例：文件补全为 @file（空格结束）；目录补全为 @dir/。如果是空目录，补全后自动加空格；有子内容（或未确认）则不加空格，光标停在斜杠后继续输入子路径浏览。想提前结束目录浏览，手动输入一个空格即可。
2. /file 命令¶
如果 @ 触发异常，可使用此备用入口。
- 输入
/file后直接接路径片段（如/fileAGENTS，无空格）。 - pick 后同样插入
@相对路径。
示例¶
输入：请修复 @src/main.go 里的空指针
Agent 会按 src/main.go 路径定位并操作。
配置项¶
插件提供可选的环境变量配置：
FILE_MENTION_ALLOWED_ROOTS：逗号分隔的允许搜索根目录（绝对路径）。设置后才启用白名单，白名单外的 root 返回 400；不设置则放行（与host.listDirectory的浏览暴露面一致）。FILE_MENTION_IGNORE_DIRS：追加剪枝目录 basename，逗号分隔（默认为内置剪枝表）。FILE_MENTION_MAX_FILES：单次遍历收集文件数上限，默认为600000。
已知限制¶
- 空格问题：引用路径不能含空格，含空格的文件名无法通过输入完整路径选中。
- 符号链接：符号链接不跟随；不返回文件大小。
- 内容预览：插入的是路径引用而非文件内容，Agent 需要读文件时会自己调 read 工具。超大/二进制文件不在菜单里做任何预览。
- 端点暴露：API 端点仅暴露路径列表，不读内容。
与同类插件的区别¶
| 项目 | dsh-at-file | dsh-file-mention (本插件) |
|---|---|---|
| 行为 | 发送时内容注入 | 发送时路径引用，Agent 自读 |
| 优缺点 | 模型可直接看到内容，但不便操作文件 | 省 token，Agent 可操作文件，模型需自行决定读哪些文件 |
总结¶
dsh-file-mention 解决了在 Web GUI 中快速引用本地文件的需求，通过路径引用而非内容注入，节省了 token 并保持了 Agent 对文件操作的灵活性。开发者可以根据需要调整搜索范围（ALLOWED_ROOTS）和忽略目录（IGNORE_DIRS）。
