前言¶
用 DeepSeek Harness（DSH）做智能体开发时，经常需要让模型「盯住」某个具体文件：审查一份 PDF 规格、对照 src/client/view.ts 改代码、或者只讨论某个目录下的配置。如果每次都要手动复制路径、粘贴进提示词，对话一多就容易出错，上下文也容易变得冗长。
社区插件 dsh-at-file（维护者 FSMargoo）把 Cursor / Codex 里常见的 @file 体验搬到了 DSH 的 Web 输入区：在 composer 里输入 @，搜索当前工作区文件或目录，选中后把路径挂到提示词上。截至 2026 年 8 月，该仓库在 GitHub 上约有 466 个 Star、19 个 Fork，采用 MIT 许可证。
需要提前说明：官方 DeepSeek Harness 较新版本已内置 @file 与 @session 引用能力，新环境可优先用官方实现；dsh-at-file 仍适合已有插件化部署、需要独立配置过滤规则或沿用旧工作流的场景，维护者表示会尽力继续维护。
这是什么¶
dsh-at-file 是一款面向 DSH Web 界面的社区插件。它在输入框提供工作区路径检索与引用，而不是在后台替模型做推理。
一句话概括：在 composer 里用 @ 搜索工作区，把文件或目录的相对路径附到提示词；智能体开始执行前，插件会校验路径是否落在当前工作区内，并插入一条简短的引用标记，由会话中的工具按需读取内容。
在 SkillHub 插件库 中，该插件归类为「模型推理」；在 DeepSeek Harness 社区插件目录 中则归入「工具与能力」。无论目录怎么分，它的核心价值都在于降低「指定文件上下文」的操作成本。
核心功能与亮点¶
Codex 风格的 @ 路径选择器¶
在 composer 输入 @ 后会弹出可滚动候选列表（最多 50 条）。纯文件名查询时，精确匹配、前缀匹配会排在更前面；空查询时，浅层路径优先于深层路径，同深度下目录排在文件前面。
查询里带 / 时按路径段顺序匹配，例如 src/view 可定位到 src/client/view.ts；src/ 则在该目录下继续筛选。高亮目录时按 ArrowRight 可进入子目录，草稿会变成 @path/ 并保持菜单打开；Enter 或鼠标点选则完成引用。
每条结果上方显示完整文件名，下方显示父目录；重名文件会在主标签里附带父目录，并用内置 SVG 图标区分文件夹、源码、文本、PDF、图片、配置、压缩包等类型。
路径引用，而非强行塞全文¶
自 v0.3.0 起，插件不再在提交时直接把文件内容读进提示词，也不再对文件大小做硬性截断。选中路径后，智能体启动前会生成类似下面的引用标记：
<workspace-reference path="docs/spec.pdf" kind="file" />
标记只包含工作区相对路径与类型（file / directory）。插件本身不会打开文件，也不会列出目录内容；需要时由当前会话里的 read、read_image 等工具处理。PDF 与文本文件走同一套路径引用流程。
智能过滤与可配置忽略规则¶
默认索引会跳过常见版本库目录、IDE 元数据、依赖树、构建产物与缓存（覆盖 VS Code、JetBrains、Gradle、Xcode、CMake、Flutter、.NET、Unity 等生态），并排除 desktop.ini、Thumbs.db、.DS_Store 等系统文件。
在 Settings → File mentions 中可管理过滤规则：
- Global：所有工作区共享；
- Workspace：仅对当前工作区追加规则，并继承全局列表。
每条规则支持 Exact（完整 basename）或 Regex（对 basename 做 JavaScript 正则），可单独开关大小写敏感。无效正则在保存前会被拦截；Restore defaults 可恢复内置全局列表，Clear workspace rules 只清空当前工作区附加项。
粘贴行为与安全边界¶
默认情况下，从外部粘贴的 @path 文本不会触发选择器、不会出现在引用栏，也不会生成 workspace-reference 标记，避免误把聊天记录里的 @ 当成文件引用。若需要旧行为，可在 Settings → File mentions 关闭 Ignore @ mentions in pasted text。
Host 只接受工作区相对路径；绝对路径或试图逃逸工作区的路径会被忽略。@path 令牌不能包含空白或第二个 @。点击引用栏中的路径会调用 Harness 的 host.openPath 打开文件。
安装与启用¶
社区目录页给出的通用安装命令如下：
dsh plugin add github:FSMargoo/dsh-at-file
如需可复现安装，可固定 commit：
dsh plugin add github:FSMargoo/dsh-at-file#<commit-hash>
该插件主要服务 Web profile。仓库 README 中推荐的带版本号安装方式如下（安装后需重启 dsh web，以便 Host 与浏览器客户端加载 v0.6.8）：
dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.8.tar.gz
说明：README 安装包 URL 指向 omdsh-dev/dsh-at-file 的 release 归档，与当前主仓库 FSMargoo/dsh-at-file 为同一插件线的发布来源，以仓库文档为准。
⚠️ 安全提示：DSH 插件以当前 dsh 进程权限运行，安装过程可能执行构建或初始化脚本。安装前请阅读 GitHub 源码 与 MIT 许可证，确认来源可信。
典型用法示例¶
在提示词里引用单个文件¶
在 composer 输入 @，搜索并选择 docs/spec.pdf，草稿可能类似：
Review @docs/spec.pdf
发送后，插件校验路径存在，再插入 workspace-reference 标记；智能体随后可用会话工具打开并阅读该 PDF。
引用目录¶
用 @ 选中目录（例如 src/components/），引用类型为 directory。插件不会自动枚举目录内容，适合表达「请在这个目录范围内改动」这类意图，具体文件仍由智能体按需读取。
通过 cordis.patch.yml 调整索引规模¶
若工作区文件极多，可在 Web profile 的配置补丁中限制索引条目数或自定义忽略目录。配置文件通常位于 ~/.dsh/profiles/web/cordis.patch.yml：
- id: dsh-at-file
config:
maxIndexedFiles: 10000
ignoreDirs 若省略，则沿用内置忽略列表；若显式提供，则需自行列出所有要排除的目录名。设为 [] 表示索引时不跳过任何目录（大型 monorepo 需谨慎）。
适用场景与注意事项¶
适合谁用
- 已在 DSH Web 界面高频对话、希望用
@快速点名文件或目录的开发者； - 需要细粒度文件过滤（Exact / Regex、全局与工作区分级）的团队；
- 暂时无法升级到有内置
@file的 Harness 版本、但仍想保留路径引用体验的旧环境。
使用注意
- 与官方能力重叠：新装 DSH 可先确认内置
@file/@session是否已满足需求，再决定是否单独安装本插件。 - Web 场景为主：安装命令与设置面板均围绕
--profile web；CLI-only 工作流收益有限。 - 索引缓存：路径索引按会话缓存约 30 秒；修改过滤规则后会清空相关缓存，下次
@搜索会重建索引。 maxIndexedFiles只影响选择器：超出索引上限时，仍可通过手动输入存在的相对路径完成引用。- 工具能力取决于会话：UTF-8 文本通常可用
read，图片可用read_image；PDF 等格式能否处理，取决于当前智能体绑定的工具集。 - 社区目录非官方商店：SkillHub 与 deepseek-harness-plugin.com 均为社区维护的插件索引，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 的架构理念，安装决策仍应回到源码与许可证。
结尾¶
如果你希望在 DSH 的 Web composer 里用 @ 像写 IDE 一样引用工作区路径，而不是反复复制粘贴绝对路径，dsh-at-file 是目前社区里较成熟的选择之一：搜索体验完整、过滤可配置、引用语义与官方 Harness 工具链衔接清晰。即便官方已内置类似能力，了解这款插件的路径标记与过滤机制，也有助于理解 DSH 如何把「文件上下文」从 UI 层传到智能体层。
