前言¶
在 DeepSeek Harness（DSH）里给当前会话带上某个工作区文件，常见做法是手打 @，再在候选里一层层点选。侧栏「工作区文件」树只有左键：点文件打开预览、点目录展开，没有「把这条路径塞进输入框」的入口；消息里已交付的文件卡片同样缺少引用快捷方式。dsh-file-reference 是社区维护的客户端插件，在文件树行和交付卡片上补右键菜单，走宿主自带的引用通道，插入与拖拽文件进输入框同类的 @ 引用 chip，而不是自造协议。
这是什么¶
- 仓库： dyhdesu/dsh-file-reference
- 维护者：dyhdesu
- 分类：客户端（纯前端，
host侧apply()为空操作） - 当前版本（package.json）：0.3.0
- 许可：MIT
插件定位可以概括为：在右侧栏工作区文件树，或消息里已交付的文件卡片上右键，一键把文件/文件夹以原生 @路径 chip 写入当前会话输入框，也可仅复制 @路径 文本到剪贴板。
核心功能¶
下面介绍菜单项与行为（与 README 一致）。
| 菜单项 | 行为 |
|---|---|
| 引用到会话 | 以 @路径 chip 插入当前会话输入框，与拖文件进输入框同一条宿主通道；发送时由宿主按文件引用解析 |
| 复制引用文本 | 将 @路径 写入剪贴板 |
路径与交互细节：
- 路径折算为相对当前会话工作区的相对路径；含空格时自动加引号（例如
@"my dir/readme.md"）；目录引用尾随/。 - 插入成功会聚焦输入框；会话未挂载、正在发送或输入框拒绝插入时会提示，不静默失败。
- 判定不到有效路径时不拦截右键，浏览器默认菜单照常。
- 菜单样式使用宿主主题令牌，亮暗主题跟随；点击别处、Esc、滚动、窗口失焦会关闭菜单。
- 中英双语，跟随宿主语言。
引用语义与官方 @ 对齐：chip 只携带路径，不读取、不附带文件内容；模型要看内容需自行使用文件系统相关工具。
安装与启用¶
发布状态：插件目前仅在 GitHub 发布，尚未发布到 npm；README 中标注「npm 未发布」的包名安装方式暂不可用。
插件以当前 DSH 进程权限运行；安装前建议浏览仓库源码与 MIT 许可证，确认符合你的环境策略。
方式一 · 插件页添加（桌面版，推荐）¶
DSH 桌面版：打开侧边栏插件页 → 添加插件 → 粘贴下面一行 → 安装后点启用 → 按提示重启或刷新。
https://github.com/dyhdesu/dsh-file-reference
方式二 · 命令行（web / headless profile）¶
dsh plugin --profile web add github:dyhdesu/dsh-file-reference
装完后重启 dsh web，并在浏览器做一次硬刷新。
npm 发布后 README 预留的包名安装（当前不可用）：
dsh plugin --profile web add dsh-file-reference
方式三 · 本地目录接线（开发用）¶
desktop profile 由 Electron 应用独占管理，官方 CLI 会拒绝直接写入。开发时需在 ~/.dsh/profiles/desktop 的 package.json 里用 file: 依赖接线，并在 dsh.profile.bundles 中追加 "dsh-file-reference"，再执行 pnpm install 并重启桌面版。改源码后可用 README 中的 rsync 命令同步到 node_modules 副本，client 半区刷新即生效。
典型用法¶
- 在右侧栏「工作区文件」面板中，对任意文件或文件夹行右键，选择「引用到会话」或「复制引用文本」。
- 在消息里对已交付的文件卡片（例如收尾回复下方的文件卡片）右键，同样两项菜单可用。
- 选「引用到会话」后，输入框会出现与官方
@、拖拽一致的引用 chip；确认会话已挂载且未在发送中即可继续编辑并发送。
多会话时，插件会按文件树根路径与会话 cwd 比对，尽量把引用插进归属正确的会话。
原理与依赖（简要）¶
命中右键目标由 contextTarget() 统一判定，主要包括：
- 侧栏文件树行：官方组件
@deepseek-ai/dsh-client-ui-sidebar-files的行节点带data-files-entry、data-files-path，树根带data-files-root。 - 交付文件卡片：官方
@deepseek-ai/dsh-client-ui-deliverables的div[data-presented-file]；绝对路径取自卡片内首个带非空title的节点（预览按钮）。取不到路径则不拦截右键。
插入走宿主 conversation 服务的 input.shell(sessionId).addFiles，即 SessionInputShell.addFiles，chip 形态与官方 @ 菜单、拖文件一致。当前会话由 uiSession.current.value.key 提供。
兼容性与已知局限¶
- 在 DSH 0.2.1-rc.2（macOS 桌面版）上开发与验证；Windows 路径逻辑有单元测试覆盖，尚未在 Windows 实机验收。
- 依赖官方文件树行属性、交付卡片 DOM 结构及
SessionInputShell.addFiles；官方若改动，插件需跟进；服务缺失或结构不匹配时会降级，不抛异常、不拦右键。
已知局限（README 原文）：
- 一次只处理单行，不支持多选批量引用。
- 不覆盖消息里已渲染的
@chip、改动文件卡片行、正文行内文件链接等表面。 - 交付卡片依赖预览按钮
title这一内部实现，官方改版后可能仅表现为右键无菜单。 - 目录引用为
@目录/，不展开目录内容。 - 引用插入需要会话已挂载且输入框可编辑；发送中会被宿主拒绝并提示。
仓库内 npm test 有 45 项用例，覆盖路径归一化、Windows 形态、右键命中与菜单生命周期等。
结尾¶
dsh-file-reference 用最小手势补上「从文件树或交付卡片到输入框引用」这一步，复用宿主原生 chip 与解析路径，装卸无 host 侧残留。社区目录页：skillhub.cn/plugins/dyhdesu/dsh-file-reference；源码与完整说明：GitHub 仓库。
