dsh-at-file 是什么？为 DSH 网页界面加 @ 文件引用

dsh-at-file 是 DeepSeek Harness（DSH Plugin）生态中的 @ 文件引用插件，为网页界面带来 Codex 风格的 @file 提及：在 composer 输入 @ 即可搜索当前工作区并插入文件或目录路径，agent 执行前会验证路径存在。 本文基于官方 README，介绍它是什么、核心功能、安装启用、典型用法与常见排错。

dsh-at-file 是什么？

dsh-at-file 解决「网页界面里手动复制粘贴文件路径」的低效：输入 @ 唤起路径选择器、搜索工作区、选中即插入，让文件引用像 IDE 一样顺畅。 以下定位与事实均来自官方 README（来源）：

dsh-at-file 由 fsmargoo 维护、用 JavaScript 开发、以 MIT 协议开源，为 DeepSeek Harness 网页界面提供工作区路径引用。输入 @ 会弹出候选菜单，普通查询按文件名匹配，含 / 的查询按路径段顺序匹配，如 src/view 可找到 src/client/view.ts。选中后路径常驻草稿的引用栏，可打开或移除。agent 开始执行前，插件确认路径在当前工作区内存在，并追加一条 <workspace-reference path="docs/spec.pdf" kind="file" /> 引用消息；它不会打开文件、也不会列出目录内容。需要留意的是，README 特别提示：最新官方 DeepSeek Harness 已内置 @file 与 @session 引用功能，新安装建议优先使用官方实现，本插件对现有环境仍可用、按尽力维护。

dsh-at-file 的核心功能有哪些？

dsh-at-file 的核心能力是「@ 搜索插入、路径校验与引用消息、目录逐级导航、智能默认索引、全局与工作区两级过滤」：把 @ 提及做成稳定可预期的交互。 功能事实来自官方 README（来源）：

• @ 路径选择器：最多展示 50 个候选，浅路径靠前、同深度目录优先；精确、前缀、紧凑匹配排名在前。
• 路径校验与引用消息：agent 执行前确认路径存在，注入 workspace-reference 标记；不读取文件内容、不展开目录。
• 目录逐级导航：目录高亮时按 ArrowRight 进入，草稿推进到 @path/ 且不带尾随空格，候选菜单保持打开。
• 智能默认索引：跳过版本控制目录、IDE 元数据、依赖树、缓存与构建输出，以及 desktop.ini、Thumbs.db、.DS_Store 等系统元数据文件。
• 全局/工作区两级文件过滤：Exact 与 Regex 两种匹配模式，大小写独立开关；非法正则表达式在保存前即被拒绝。
• 索引配置项：maxIndexedFiles 控制索引条目上限，ignoreDirs 可整体替换内置的排除目录列表。

怎么安装与启用 dsh-at-file？

启用 dsh-at-file 只需一步：安装插件后重启 Web profile，0.3.0 及以上的 DeepSeek Harness 即可在 composer 使用 @ 引用。 安装命令来自官方 README（来源）：

1. 安装插件：本插件为 GitHub 源、无 npm 包，用目录站标准命令安装：

dsh plugin --profile web add github:fsmargoo/dsh-at-file

2. 重启启用：重启 Web profile，让 Host 与浏览器端加载插件：

dsh --profile web

3. 更新插件：用更新命令升级到最新版本（README 也提供 tag 压缩包直装方式）：

dsh plugin --profile web update dsh-at-file

4. 移除插件：不再需要时移除：

dsh plugin remove dsh-at-file

安装后回到网页界面，在 composer 输入 @ 即可唤起路径选择器。插件适用于 DeepSeek Harness 0.3.0 及以上版本；0.3.0 之前的版本在提交时会读取文件内容并强制文件大小限制，行为不同。

dsh-at-file 典型用法

日常用法就是「输入 @ → 搜索 → 选中」三步，再加上目录导航、粘贴文本策略与文件过滤三个可选项。 用法细节来自官方 README（来源）：

1. 搜索并插入路径：在 composer 输入 @ 唤起选择器，输入关键字过滤候选，选中后路径插入草稿并在引用栏显示：

Review @docs/spec.pdf

2. 逐级进入目录：目录被高亮时按 ArrowRight 进入，草稿更新为 @path/ 且不带尾随空格，候选菜单保持打开以便继续选择；Enter 或指针选择完成目录引用。

3. 处理粘贴文本：默认情况下，从其他应用粘贴的 @path 被视为普通文本，不会触发选择器或创建引用标记；需要旧行为时，在 Settings -> File mentions 关闭 Ignore @ mentions in pasted text。

4. 配置文件过滤与索引：过滤规则在 Settings -> File mentions 管理；索引配置写入当前 profile 的 cordis.patch.yml（默认路径 ~/.dsh/profiles/web/cordis.patch.yml）：

cat ~/.dsh/profiles/web/cordis.patch.yml

nano ~/.dsh/profiles/web/cordis.patch.yml

- id: dsh-at-file
  config:
    maxIndexedFiles: 10000

dsh-at-file 常见问题与排错

dsh-at-file 的常见问题集中在「输入 @ 没反应」「引用失效或列表缺文件」「粘贴 @path 行为不对」「深层目录难找」四类，下面给出症状、原因与解决步骤。 排错依据来自官方 README（来源）：

1. 症状：输入 @ 没有弹出选择器。 原因：插件未安装或 Web profile 未重启。解决：用安装命令装好插件并重启 profile（dsh --profile web）；0.3.0 以下版本不支持该机制。

2. 症状：引用路径失效，或文件不在候选列表。 原因：路径超出工作区、被过滤规则排除，或超过 maxIndexedFiles 上限。解决：只引用工作区内的相对路径，检查 File mentions 规则与索引配置；重装可刷新会话索引缓存：

dsh plugin --profile web add github:fsmargoo/dsh-at-file

3. 症状：粘贴的 @path 触发了选择器或变成了引用标记。 原因：默认策略应把它视为普通文本。解决：确认 Settings -> File mentions 中 Ignore @ mentions in pasted text 处于开启状态（默认开启）。

4. 症状：深层目录里的文件搜索不到。 原因：候选菜单最多 50 条，深层条目会被浅路径挤掉。解决：用含 / 的查询按路径段匹配（如 src/view），或先进入目录再继续选择。

适用场景与注意

dsh-at-file 适合「重度在网页界面引用工作区文件」的 DSH 用户，尤其是习惯 Codex 风格 @ 提及、不想手动复制路径的工作流。 事实来自官方 README（来源）：

适用场景：日常把文件或目录路径交给 agent 处理；需要引用 PDF、图片等非文本文件（只传路径、不读内容）；在多个工作区之间切换、希望各自维护过滤规则。

注意与限制：

• 官方 DeepSeek Harness 已内置 @file/@session 引用，新装优先官方实现；本插件面向现有环境，按尽力维护；
• 仅支持 0.3.0 及以上版本；更早版本提交时会读取文件内容并强制文件大小限制；
• @path 不能包含空白或另一个 @ 字符；绝对路径与逃逸工作区的路径会被忽略；
• 引用 dock 只渲染当前会话工作区索引中存在的 token；索引每会话缓存 30 秒。

项目链接

dsh-at-file 是 fsmargoo 维护的 MIT 开源项目，源码托管在 GitHub。

前往插件详情页查看完整信息：dsh-at-file。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：FSMargoo/dsh-at-file。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。