前言¶
在 DeepSeek Harness（DSH）里和智能体协作时，回复里经常出现文件路径：相对路径、绝对路径，或带 ~/ 的主目录写法。官方渲染器会把 URL 自动变成链接，但本地路径通常只是普通文本，复制后再去文件管理器或终端里打开，多一步操作。
下面介绍社区插件 dsh-file-mentions（维护者 a903067276-rgb）。它把反引号包裹的路径变成可点击的行内链接，并在回合末尾汇总「mentioned files」芯片列表，交互方式接近 Codex 风格。插件为零依赖实现，归类为 DSH 客户端插件，当前 GitHub 星标 11、fork 3，采用 MIT 许可证。
这是什么¶
dsh-file-mentions 是一个 DSH web 插件（bundle + client，见仓库根目录 package.json）。核心能力有三块：
- 行内路径点击：用系统默认应用打开文件，或打开所在目录。
- 路径旁文件夹按钮：在文件管理器中定位（reveal）。
- 回合末尾「mentioned files」芯片列表：点击文件名可在 DSH 内预览内容；列表中的文件夹按钮同样可 reveal。
URL 仍由官方渲染器处理，本插件不改动 URL 行为。项目为社区成员独立维护，非 DeepSeek 官方产品。
核心功能¶
插件把反引号包裹的路径识别为可交互对象，支持 ~/ 展开、相对路径（相对当前会话工作目录解析），以及 macOS / Linux / Windows 形式的绝对路径。路径不存在时静默忽略，不会报错打断阅读。
| 交互位置 | 操作 | 效果 |
|---|---|---|
| 行内路径文本 | 点击 | 用默认应用打开文件，或打开目录 |
| 行内路径后的文件夹图标 | 点击 | 在文件管理器中 reveal |
| 「mentioned files」芯片 | 点击名称 | 在 DSH 内预览文件内容 |
| 芯片列表中的文件夹图标 | 点击 | 在文件管理器中 reveal |
| 行内 URL | 点击 | 由官方 autolink 在浏览器中打开 |
路径可见范围： 用户主目录下的本地文件默认可点击，无需配置。外置盘或网络卷（例如 macOS 上的 /Volumes/USB）需在外置盘白名单中登记根路径，一行一个。系统盘保护会自动拒绝包含 /System、/etc 或 Windows 下 \Windows 等标记目录的白名单根路径。
平台： macOS 已完整测试（含中文路径）；Linux 与 Windows 尚未在仓库中完整验证，但已实现对应命令分支与路径解析。
与官方能力的关系： 行内点击依赖智能体用反引号包裹路径（与 Codex 输出约定一致），正文里未加反引号的裸路径不会变成可点击。官方的「produced files」列表与本插件可共存：官方有输出时优先显示官方列表，否则由本插件展示 mentioned files 列表。
安装与启用¶
插件通过 DSH 官方 profile 管理器安装，仓库为 bundle 插件（dsh.bundle + dsh.client）。安装前需确保 pnpm 在 PATH 中（dsh plugin 会转发到 pnpm）。
dsh plugin --profile web add "github:a903067276-rgb/dsh-file-mentions#main"
安装完成后需要重启 dsh web。bundle 层在启动时组装，热更新（HMR）不会生效。
版本兼容（README 说明，尽力维护，不保证覆盖所有 DSH 版本）：
- 要求 DSH web >= 0.1.0-rc.6（例如
npx @deepseek-ai/dsh web）。 - DSH 0.1.0-rc.6 及更新版本（含 0.1.1-rc.1/rc.2）：默认使用
main分支。 - 保守回退：DSH 0.1.0-rc.7/rc.8 可安装
#v1.0.8；DSH 0.1.0-rc.6 可使用冻结标签rc6-compat（不再维护）。
dsh plugin add github:a903067276-rgb/dsh-file-mentions#v1.0.8
手动挂载方式见仓库 docs/install.md。注意：官方 bundle 安装与手动挂载只能选其一；手动挂载时 ~/.dsh/cordis.patch.yml 只能有一条入口，重复注册会导致路由冲突。
社区目录页：SkillHub — dsh-file-mentions。SkillHub 为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
让智能体在回复里用反引号包裹路径，行内即可点击，末尾芯片列表会自动出现，无需额外配置。
示例（智能体输出）：
请查看 `~/docs/plan.md` 和 `./src/index.js`。
点击 `~/docs/plan.md` 会用系统默认应用打开该文件；点击路径旁文件夹图标会在文件管理器中定位。
外置盘路径： 若路径位于主目录之外（例如 /Volumes/USB/project/readme.txt），打开 DSH 设置 → Plugins → file-mentions，在外置盘白名单中添加 /Volumes/USB，保存后立即生效，无需重启。
适用场景与注意¶
适合谁： 经常在 DSH web 里阅读带本地路径的智能体回复、希望少复制粘贴一步的开发者。macOS 用户可直接按 README 预期使用；Linux / Windows 用户可先试用，遇到问题可向仓库提 issue 或 PR。
运行权限： 打开文件、reveal 目录等操作通过插件宿主路由（/api/file-mentions/open 等）调用系统命令完成，以当前 dsh 进程的用户权限执行。安装前建议阅读 源码 与 MIT 许可证，确认行为符合你的安全预期。路径探测与白名单校验在同源守卫下进行，使用 Node 标准库与 execFile，避免 shell 注入。
实现概要（便于排查问题）： 宿主 lib/index.js 提供存在性检查、打开/reveal、白名单读写三条 API；客户端 lib/client.js 从对话事件中收集路径、用 document 级点击委托处理行内点击，并用 MutationObserver 在 React 重渲染后恢复文件夹按钮。详见 docs/architecture.md。
结尾¶
dsh-file-mentions 把 DSH 回复里反引号路径变成可点击的行内链接，并用 mentioned files 芯片列表兜底汇总，适合需要频繁跳转本地文件的 DSH web 用户。当前版本 1.0.11。
