前言¶

DeepSeek Harness（dsh）是 DeepSeek AI 开源的智能体框架，官方仓库把架构概括成一句话：一切皆插件。当前仍处于开发者预览阶段，Web UI 默认跑在 http://127.0.0.1:3080。日常写代码时，真正费事的往往不是模型本身，而是怎么把「就看这个文件」说清楚：完整相对路径要手敲，复制粘贴又容易把无关内容塞进上下文。

OpenAI Codex 一类工具用 @文件 解决这件事。社区插件 dsh-at-file 把类似交互接到了 DeepSeek Harness 的 Web 输入框：输入 @ 搜索当前工作区，选中后把路径引用进提示词。需要说明的是，社区插件目录页仍写着「把内容直接附进提示词」；仓库 README 和 package.json 对 0.3.0 及之后版本的描述不同——插件只附路径，不注入文件正文。本文按目录页、GitHub 仓库 README（含中文版）和 package.json 交叉核对后整理。

社区目录站点 deepseek-harness-plugin.com 是独立收录站，与 DeepSeek / 幻方没有官方从属关系，不要把它当成官方应用商店。

这是什么¶

dsh-at-file 是一款面向 DeepSeek Harness Web 界面 的工作区路径引用插件，由组织账号 omdsh-dev 维护，许可证为 MIT，主要语言是 JavaScript。社区目录把它归在「工具与能力」，并标为精选；仓库创建于 2026-08-13，GitHub 主题为 dsh、dsh-plugin。2026-08-17 核对该仓库时，星标为 271（目录页当时显示 172，以 GitHub 为准）。

它解决的问题很具体：在输入框里用 @ 搜索并插入工作区文件或目录路径，让后续步骤知道「目标在哪」，而不是把整份文件塞进提示词。package.json 里的一句话更直白：search workspace paths without injecting file content。

当前仓库 package.json 版本为 0.6.1，Git 标签同样有 v0.6.1。dsh.client.platform 声明为 web，因此它服务的是 Web GUI，不是 headless 会话。

核心功能¶

1. 在输入框用 @ 选路径¶

在 composer（输入框）里输入 @，插件会搜索当前工作区，弹出路径选择器。选中一项后，路径会留在草稿里；输入框上方的引用栏可以打开该路径，也可以移除引用。仓库给出的示例是：

请检查 @docs/spec.pdf

普通关键词只匹配文件名。完整名称、前缀和紧凑匹配会排在前面，不会因为长目录路径里碰巧散落几个字母就给出无关结果。关键词里带 / 时，按路径片段依次匹配，例如 src/view 可以找到 src/client/view.ts；输入 src/ 则在该路径下继续搜。

高亮某个目录后，按右方向键可以进入该目录：草稿会变成 @路径/，末尾不加空格，候选菜单保持打开。回车或鼠标点选目录，则直接完成这次目录引用。

候选项优先显示文件名，下方是父目录；重名文件会把父目录写进主标题。内置 SVG 图标用来区分目录、源代码、文本、PDF、图片、数据与配置、压缩包以及其他文件。

2. 提交时只附加路径引用，不读文件内容¶

每次 agent 开始处理前，插件会确认该路径仍在当前工作区且确实存在，然后补充一条短消息：

<workspace-reference path="docs/spec.pdf" kind="file" />

引用里只有工作区相对路径和类型（kind）。插件不会打开被引用的文件，也不会列出被引用目录的内容。真正读文件、看图、解析 PDF，都交给当前会话里已有的工具。README 写明：DSH 的 read 用于 UTF-8 文本，read_image 用于支持的图片；PDF 能否处理，取决于这次会话装了什么工具。

文件格式和文件大小都不会改这条流程。PDF 和普通源码走同一套路径引用。仓库明确说：以上机制适用于 0.3.0 及后续版本；更早的版本会在提交时读取文件内容，并受文件大小限制。如果目录页或第三方列表仍写「把内容附进提示词」，那是旧行为，不要按旧版预期来用现在的插件。

3. 默认跳过噪音目录，过滤规则可改¶

默认索引会跳过常见版本控制目录、IDE 元数据、依赖树、缓存和构建产物，覆盖 VS Code、Visual Studio、JetBrains IDE、Fleet、Eclipse、Android / Gradle、Xcode、CMake、Flutter、.NET、Unity、Unreal，以及常见 JavaScript、Python 输出目录。desktop.ini、Thumbs.db、.DS_Store 也会默认排除。

需要再收紧时，打开 设置 → 文件提及：

• 全局：所有工作区共用
• 工作区：当前所选工作区路径的附加规则；面板会同时显示继承来的全局规则

每条规则可单独选匹配方式和大小写：

• Exact：匹配一个完整文件名，不接受路径分隔符
• Regex：用 JavaScript 正则匹配完整文件名，不包含父目录或工作区路径
• 区分大小写：默认关闭，Exact 和 Regex 都能开

无效正则会在保存前报错，Host 也会拒绝。恢复默认值只重置全局列表；清空工作区规则只删当前工作区的附加项。设置通过插件自己的 Host 接口写进 DSH web profile。旧的字符串规则会继续当成不区分大小写的 Exact 规则。改规则会清掉相关索引缓存，下一次输入 @ 就会用新规则。

4. 索引范围可以写进 profile¶

路径选择器还有两项配置，写在所选 profile 的 cordis.patch.yml 里，常用路径是 ~/.dsh/profiles/web/cordis.patch.yml：

• maxIndexedFiles：工作区索引条目上限
• ignoreDirs：替换内置忽略目录列表；设成 [] 会索引所有目录

仓库给出的示例只改上限：

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

省略 ignoreDirs 就继续用内置列表；一旦填写，就要列出全部想排除的目录名，不是在默认列表上追加。

路径处理还有几条硬约束，都来自 README：

• 只索引常规文件和目录，跳过已配置的目录名与符号链接
• 全局和工作区文件名规则在 Host 遍历时合并；被过滤的条目不占用 maxIndexedFiles，也不会发到浏览器
• Host 只接受工作区相对路径；绝对路径、越出工作区的路径会被忽略
• 只有用户自己输入的文本会生成引用消息
• 点击引用路径会调用 Harness 的 host.openPath
• 每个会话的路径索引缓存 30 秒
• @路径 不能包含空白，也不能再含另一个 @
• maxIndexedFiles 只限制选择器结果；手动输入的路径只要在工作区且存在，仍可引用

安装与启用¶

社区目录页给出的安装命令是：

dsh plugin add github:omdsh-dev/dsh-at-file

需要可复现安装时，目录页建议固定 commit：

dsh plugin add github:omdsh-dev/dsh-at-file#commit

把 #commit 换成实际提交哈希。仓库 README 写明：lib/ 里的构建产物会提交进仓库，profile 安装不必再跑包构建脚本。

README 另外给出了针对 web profile、并钉到标签包的写法（文档示例仍是 v0.6.0）：

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.0.tar.gz

同一条命令也可用来更新已有安装。装完后重启 dsh web，让 Host 和浏览器客户端都加载对应版本。仓库当前最新标签是 v0.6.1，与 package.json 的 0.6.1 一致；README 安装段尚未改到这个标签。若要跟文档走，用上面的 v0.6.0 包；若要跟最新标签，把 URL 里的 v0.6.0 换成 v0.6.1 即可。

目录页有一条安全提示，安装前应当看完：插件以当前 dsh 进程的权限运行，安装时可能执行代码。先检查源代码仓库和许可证，再决定是否安装。

典型用法¶

装好并重启 Web UI 之后，流程就是：打开工作区 → 在输入框输入 @ → 选文件或目录 → 用自然语言写任务。

下面这个例子直接来自仓库文档，可以按原样试：

请检查 @docs/spec.pdf

提交后，agent 侧会看到类似：

<workspace-reference path="docs/spec.pdf" kind="file" />

它拿到的是路径，不是 PDF 正文。接下来会不会调用 read、别的解析工具，或告诉你当前会话没有合适工具，取决于这次会话的工具集，而不是插件本身。

需要引用某个子目录时，可以输入 src/ 缩小范围，或在目录候选上按右方向键进入后再选文件。路径里不要加空格，也不要写第二个 @。选择器没列出的文件，只要路径确实在工作区内，仍可手动写成 @相对路径 再提交。

索引太大或太吵时，先改 设置 → 文件提及 的文件名规则；还不够再改 cordis.patch.yml 里的 maxIndexedFiles 和 ignoreDirs。改完不必重装插件，但 ignoreDirs 是整表替换，漏写内置目录名会把原先跳过的依赖目录重新编进索引。

适用场景与注意事项¶

比较适合这些情况：

• 主要在 dsh web 里工作，需要反复指向某个源文件、配置、文档或目录
• 希望交互接近 Codex 的 @ 提及，但不想把大文件或 PDF 整份打进提示词
• 工作区里噪音目录多，需要默认忽略规则，或按仓库再加一层文件名过滤

使用前注意：

1. 平台是 Web。package.json 把 client 平台写成 web，不要默认它在 headless / TUI 里同样可用。
2. 它是路径引用，不是自动贴正文。0.3.0 之后不再在提交时读文件；agent 读不读、读不了某种格式，取决于会话工具。
3. 安全边界按工作区切。绝对路径和逃出工作区的路径会被忽略；符号链接默认不进索引。
4. DeepSeek Harness 仍在开发者预览，官方 README 写明会有破坏兼容性的变更。插件也在快速发版（仓库已有 v0.2.0 到 v0.6.1 一串标签），安装时尽量钉 commit 或标签。
5. 插件以当前 dsh 进程权限运行。安装前读一遍源码和 MIT 许可证，只装自己信任的来源。

小结¶

dsh-at-file 给 DeepSeek Harness 的 Web 输入框补了一层 Codex 风格的 @ 路径选择：搜索工作区、插入相对路径、在 agent 起步前附上 <workspace-reference />。当前实现刻意不注入文件内容，把「打开、阅读、解析」留给会话里的工具。这和部分目录摘要里的旧表述不一致，以仓库 README 为准。

目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-at-file/

GitHub：https://github.com/omdsh-dev/dsh-at-file