前言¶
在 DSH Web GUI 中让模型读取工作区文件时，常见做法是手动把文件路径写进输入框，或在提示里说明“请看某个文件”。在多文件项目里，这样容易漏选文件、写错路径，也容易被 .gitignore、项目文档、编译产物等边界干扰。
dsh-file-mention 是 DSH（DeepSeek Harness）Web GUI 的一个客户端插件。它在聊天输入框里提供 @ 文件引用能力：输入 @ 后实时过滤工作区文件，选中后插入 @相对路径，模型即可直接读取该文件。下面介绍它的定位、核心功能、安装方式和适用场景。
插件定位¶
- 插件名：
@hucj/dsh-file-mention - 仓库：
hucj09/dsh-file-mention - 许可证：MIT © 2026 hucj
- 平台：
dsh.client.platform为web - 运行环境：
package.json要求 Node >= 22 - 用途：在 DSH Web GUI 输入框中，通过
@选择工作区文件并插入相对路径
核心功能¶
输入 @ 触发文件候选¶
在输入框输入 @，会触发工作区文件候选菜单。
插件支持按文件名或完整路径实时过滤，大小写不敏感，最多展示 30 条。选中文件后，输入框会插入 @相对路径，用于让模型读取该文件。
扫描范围¶
插件的文件候选来源包括：
- git 跟踪文件
- 未跟踪且未被忽略的新文件
这意味着新建文件即使没有 git add，也可以被 @ 引用；同时插件天然遵守 .gitignore，被忽略的文件和目录默认不会进入候选。
如果 git 不可用或当前目录不是仓库，插件会回退为 .gitignore 解析与全量扫描。
.aiinclude 重新纳入¶
有些文件虽然被 .gitignore 忽略，但模型或开发者仍然希望在 @ 菜单中引用，例如本地文档、配置草稿或辅助材料。
可以在工作区根目录创建 .aiinclude，使用 .gitignore 语法，把被忽略的文件或目录重新纳入扫描范围。
# 使用 .gitignore 语法，把需要纳入扫描的文件或目录写在这里
子目录也可以配置 .aiinclude。子目录中的规则相对该目录生效，并覆盖根配置。
修改 .aiinclude 后，数据约 90 秒内收敛；刷新页面可加速客户端部分生效。
目录引用与排序¶
插件支持目录引用，并支持逐级展开和单段查询直达子目录。
候选排序支持以下匹配优先级：
- 精确匹配
- 前缀匹配
- 子串匹配
在同等匹配条件下，插件优先展示变更文件。最近修改或新增的变更文件会置顶，上限 5 个。
菜单、缓存与边界¶
插件将候选菜单加宽至 720px，并调整字号与行高，用于提升文件候选的可读性。
缓存方面：
- 客户端按工作区
cwd共享缓存，并采用 stale-while-revalidate - Host 侧对 git 结果做分层缓存
安全边界方面，插件限制：
- 文件总数上限 10000
- 遍历深度 32
- 跳过重型目录
安装与卸载¶
npm 方式安装¶
先执行安装命令：
dsh plugin --profile web add @hucj/dsh-file-mention
执行后重启 dsh web，在浏览器中按 Ctrl+F5 强刷页面。进入输入框输入 @，如果出现 file 分组，即表示安装成功。
本地路径安装¶
如果需要在本地调试，也可以使用本地路径安装：
dsh plugin --profile web add file:D:/path/to/dsh-file-mention
需要注意，file: 安装是一次性拷贝。源码改动后，需要重新编译并重新安装，安装目录不会自动同步源码变化。
宿主依赖¶
插件需要宿主已组装 input-trigger 相关依赖。README 注明标准 web 部署默认包含该依赖。
卸载¶
卸载命令如下：
dsh plugin --profile web remove @hucj/dsh-file-mention
执行后重启 dsh web 使卸载生效。
典型用法¶
- 在 DSH Web GUI 输入框中输入
@，弹出工作区文件候选菜单。 - 按文件名或完整路径继续输入，实时过滤候选文件。
- 选择目标文件后，输入框中插入
@相对路径。 - 将消息发送给模型，模型即可基于该路径读取对应文件。
如果项目中存在被 .gitignore 忽略但需要被 @ 引用的文件，可以这样做：
- 在工作区根目录创建
.aiinclude。 - 使用
.gitignore语法，将目标文件或目录写入.aiinclude。 - 等待约 90 秒内收敛，或刷新页面加速客户端部分更新。
- 重新输入
@，确认目标文件进入候选列表。
如果某个子目录需要单独调整纳入规则，也可以在子目录中放置 .aiinclude。规则相对该目录生效，并覆盖根配置。
适用场景与注意¶
适合以下情况使用：
- 在 DSH Web GUI 中频繁让模型读取工作区文件
- 希望减少手工输入路径带来的错误
- 需要把 git 跟踪文件和未跟踪新文件统一纳入候选
- 需要遵循
.gitignore边界，同时保留部分本地文档或配置的引用能力 - 需要在目录结构中快速定位子目录或子文件
使用注意：
- 插件以当前
dsh进程权限运行，安装前建议检查源码与许可证。 .aiinclude会扩大可被引用的文件范围，不要把敏感文件无差别纳入。- 本地
file:安装是一次性拷贝，源码修改后需要重新编译并重新安装。 - DSH 插件生态强调可扩展性；社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不应把它写成官方应用商店。
