npm 版本落后仓库整整一个号——dsh-at-file 八个真实坑位

dsh-at-file 是给 DeepSeek Harness Web 界面做「工作区路径引用」的插件：敲 @ 搜索工作区，插入文件或目录路径。它由 FSMargoo 维护，MIT 许可，站内星标 503★，综合分 67.1，周下载 1,529，更新放缓——最近一次提交在 36 天前。这篇不讲「怎么装」，只讲「装上之后会踩到什么」：八个坑，全部来自插件文档与详情页里能核对的事实。

先把底线交代了：本插件 README 置顶声明，最新官方 DeepSeek Harness 已经内置 @file 与 @session 引用，新安装请优先用官方实现，本插件为既有安装保留、best-effort 随缘维护。所以这八个坑，适合「已经在用、想少踩点坑」的读者；若想先看同类插件在站内的分类与汉化对照，可以翻这份 完整插件清单与汉化避坑指南，本文的坑位清单也建议配合它一起看。

坑一 · 官方已经把这功能做进内核了

现象。 你按教程一路装好、用着也顺，回头读 README 才发现顶部有一条 [!IMPORTANT]：最新官方 DeepSeek Harness 已内置 @file 与 @session 引用功能，新安装请优先使用官方实现，本插件仅为既有安装保留。 原因。 这个能力被上游吸收进了内核。 解决。 新装先看官方内置用法；只有当你已经养成习惯，或者确实需要本插件额外的过滤器、选择器细节时才继续用。

坑二 · npm 上的版本比仓库 tag 落后一个号

现象。 npm 的 latest 是 0.6.3，而 README 的安装命令指向 GitHub 的 v0.7.0 tarball，两边对不上。 原因。 仓库 tag 与 npm 发布不同步。 解决。 要 0.7.0 的行为，就按 README 的 tarball 命令装；只求「装上能用」，走站内给的 dsh plugin --profile web add dsh-at-file 最省事——npm 已经发布，且发布者账号与仓库一致。两种装法在站内的收录形态，可以对照 完整插件清单与汉化避坑指南 一起看。

坑三 · 0.3.0 前后是两套行为，别拿旧教程套

现象。 你照着某篇老教程操作，以为「提交时会读文件内容、还有文件大小上限」，实际根本对不上。 原因。 行为在 0.3.0 被重写：0.3.0 起只做路径引用、不读文件内容；更早版本才会在提交时读取文件内容并施加强制文件大小限制。 解决。 升级后重新验证自己的用法；老教程里「提交时读文件 / 有大小上限」的描述已经过时。

坑四 · 从别处粘贴的 @path 什么都不会发生

现象。 你从别的应用复制一段带 @path 的文本贴进输入框，它不打开选择器、不进引用栏、不产生任何标记，看着像坏了。 原因。 Ignore @ mentions in pasted text 默认开启，粘贴文本被当成普通文本。 解决。 去 设置 → 文件提及，关掉「忽略粘贴文本中的 @」，即可恢复旧行为。

坑五 · 引用标记只在「已 settle 的索引」里生效

现象。 手打的 @xxx 有时一直是普通文本；或者 @ 后面带空格、带第二个 @ 就失效。 原因。 引用栏只渲染当前会话已 settle 的工作区索引里确实存在的 token；且 @path token 不能含空白或第二个 @。 解决。 等索引 settle 之后再操作，或者干脆用选择器点选，而不是手打。

坑六 · ignoreDirs 是替换不是追加

现象。 你只写了想排除的一两个目录名，结果 node_modules、.git 这些反而全被索引进来了；一气之下改成 []，选单又被一堆构建产物淹没。 原因。 ignoreDirs 替换内置排除名单，只有省略该字段才保留内置名单。 解决。 要给 ignoreDirs，就得把想排除的目录名全部列全；如果只是想加一两条，干脆别动这个字段。

坑七 · 过滤器写错的地方不会报错给你看

现象。 Exact 规则里写了带 / 的路径却不生效；Regex 想按「父目录 + 文件名」匹配，怎么都匹配不到。 原因。 Exact 不接受路径分隔符；Regex 只对完整 basename 跑，拿不到父目录或工作区路径。 解决。 路径段匹配交给选择器的 / 语法；过滤器只管文件名。非法正则会保存前提示，且 Host 也会拒绝——看到提示就改，别指望它自动兜底。

坑八 · 索引有上限、有缓存、也有边界

现象。 文件明明就在工作区里却搜不到；刚改完设置结果没变。 原因。 选择器索引受 maxIndexedFiles 限制、按会话缓存 30 秒、菜单最多给 50 个候选；Host 又只接受工作区相对路径，绝对路径与逃出工作区的路径会被直接忽略。 解决。 调完 maxIndexedFiles 重新搜索；改完过滤器会清缓存，等一次刷新即可；路径一律用工作区相对写法。

这八个坑的三条共性

把八条摆在一起看，规律很清楚。

第一条是版本口径。坑二和坑三都源于「你装的到底是哪个版本」：npm 的 0.6.3 与仓库 tag 的 v0.7.0 不同步，0.3.0 又恰好是行为分水岭。动手前先确认版本号，能避开一大半困惑。

第二条是默认值的方向。坑四、坑五、坑六都是「默认开启或默认替换」造成的错觉：粘贴被忽略、索引要 settle、ignoreDirs 是替换。这些默认值本身是合理设计，只是反直觉，读到就能绕开。

第三条是作用域边界。坑七与坑八都关于「谁管什么」：过滤器只管文件名、不管路径段；索引有上限、有缓存、只吃工作区相对路径。记住这条边界，就不会把期待放错地方。

总结

这八个坑，一半来自版本口径（npm 与 tag、0.3.0 前后），一半来自你没读到的默认值（粘贴、settle、ignoreDirs、过滤器作用域）。想对照同类插件的中文清单与安装形态，见 完整插件清单与汉化避坑指南。

适合与不适合

适合：已经在用 dsh-at-file 的既有安装；正被粘贴 / settle / ignoreDirs 这类默认值卡住的人；想在升级后重新核对老用法是否仍然成立的人；需要 Exact / Regex 过滤细节的人。 不适合：全新环境、可以直接用官方内置 @file / @session 的人；期望插件替你读取 PDF 正文的人；不接受第三方插件读写本地文件的人。

标签：dsh-at-file、DeepSeek Harness、避坑指南、插件安装

本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。