拖拽文件路径注入 bleamayaka/dsh-file-beam

English · 简体中文

dsh-file-beam

把文件拖入 DSH Web 输入区：解析出文件的真实绝对路径（不复制文件），以附件 chip 登记；发送消息时由 Host 把路径清单隐藏注入给 Agent（UI 只显示一行摘要，输入框内不出现路径文本），Agent 直接读取源文件进行分析。

dsh-plugin
DSH
License

兼容性

要求 DSH ≥ 0.1.5（客户端使用 slots / locale / uiConversation 服务，插件注册走 0.1.5 的 uiConversation.events 定义注册表——该服务的前身 conversationEvents 已在 0.1.5 移除）。

注意：DSH 的插件 manifest 没有版本约束字段（dsh.client 只接受 platform / inject / external / immediately），因此这里只能以文档形式声明最低版本。

安装

dsh plugin --profile web add github:bleamayaka/dsh-file-beam

安装完成后重启 DSH Web（dsh web）并刷新浏览器生效。

功能

- 附件 chip 交互：把文件或文件夹拖到页面任意位置，输入框上方出现 chip
- 路径秒取：浏览器通过 text/uri-list 暴露真实路径时直接使用（零搜索）；否则由 Host 按名称在 会话工作区 + ~/Downloads、~/Desktop、~/Documents 中搜索，返回候选绝对路径（如 C:\Users\...\Desktop\报告.docx），你点选正确的那个
- mtime 相近度排序：同名多候选时按磁盘修改时间与拖入文件的接近度排序，最近修改的优先展示
- 不复制文件：只登记路径字符串，绝不读取或传输文件内容，Agent 用自己的文件工具直接读源文件
- 隐藏路径注入：选定路径不会写入输入框文本（输入框保持干净）；发送消息时，Host 在 agent/pre-step 阶段把路径清单作为插件 notice 消息插入请求——模型看到完整路径，UI 只显示一行「📎 文件 N 个」摘要
- 免输入发送：文件全部登记后，芯片栏出现「发送」按钮，点一下即可让 Agent 读取文件（无需打字）；用不可见字符占位激活输入框，提交时由 Host 剥离
- 历史附件卡片：发送过的文件以迷你卡片保留在对话历史中（路径元数据存于消息 source 字段，UI 侧数据，不进模型上下文）
- 跨工作区可用：搜索基于会话工作区 + 配置目录，无论 Agent 工作区切到哪都能定位
- 唯一匹配自动登记：同名文件只有一个候选时自动登记，无需点击；多个同名文件才显示候选按钮
- 发送后自动清理：消息发送成功后 chip 自动消失（宿主端已消费登记），切换会话时也会自动清理，不会残留
- 图片走原生流程：纯图片拖拽交给 DSH 原生多模态上传；含非图片文件才走路径引用
- 健壮性：重复 drop 去重、同名去重、连接重建清理、搜索可取消

使用

1. 把文件（如 report.docx、data.csv）拖入 DSH Web 页面任意位置
2. 输入框上方出现 chip：先显示「搜索路径中…」，随后列出候选路径按钮（浏览器暴露了真实路径时直接登记，无需等待）
3. 点选正确路径 → chip 变为「已登记 」（可点 × 移除）
4. 正常输入你的指令并发送，或直接点芯片栏的「发送」按钮 → 输入框内没有路径文本，但 Agent 会收到隐藏的路径清单消息，直接读取源文件分析；发送后 chip 自动消失，历史消息中保留附件卡片

配置（可选）

在 profile 的 cordis.patch.yml 中覆盖：
- id: dsh-file-beam
config:
searchDirs: ["~/Downloads", "~/Desktop", "~/Documents"] # 额外搜索目录
workspaceDepth: 10 # 工作区搜索深度 searchDirsDepth: 3 # 额外目录搜索深度 maxResults: 20 # 候选上限

结构

- lib/index.js — Host half：路径搜索、会话登记（attach/detach/pending）、agent/pre-step 隐藏注入
- lib/client.js — Browser half：拖拽捕获、dock chip（conversation.input.dock slot）、候选选择
- cordis.patch.yml — bundle 层声明（insert 自身）

官方社区

本插件属于 DeepSeek Harness 生态，欢迎到官方社区交流、反馈问题或分享使用体验：

- DeepSeek Harness GitHub Discussions — 官方讨论区：反馈、提问、插件分享
- DeepSeek Harness Discord — 官方 Discord 社区
- 本仓库已携带 dsh-plugin topic，可在 GitHub 上被检索发现

借鉴与致谢

本插件在实现过程中参考了以下开源项目与官方资料，特此致谢：

交互与路径解析
- 交互设计（dock chip、按文件名搜索真实路径、候选点选、唯一匹配自动登记）：参考 gezg/dsh-drag-file（MIT）——本插件在其基础上改为“路径不写入输入框、由 Host 隐藏注入”。
- 芯片栏发送按钮与路径优化（AKIRACOD/dsh-drag-and-drop，BSD-3-Clause，fork 自 omdsh-dev/dsh-drag-and-drop）：
- 免输入发送：芯片栏放置发送按钮，通过 conversation.input.for(scope).submit() 直接提交，无需打字
- 路径秒取：从 drop 的 text/uri-list / text/plain 解析 file:// URL（含 UNC 网络路径）直接得到真实路径，跳过宿主搜索
- mtime 相近度排序：同名多候选时按磁盘 mtime 与拖入文件 lastModified 的差值排序，最近修改的优先

隐藏注入与持久化

- 隐藏注入机制（agent/pre-step 插入插件 notice 消息，模型可见完整清单、UI 只显示一行摘要）：参考 re-ITRT/dsh-file-fix 的附件桥接实现思路。
- 免输入提交技巧与历史卡片（WJZ-P/dsh-attachments，MIT）：
- U+2063 不可见字符占位：文件就绪且输入框为空时写入不可见字符以激活原生发送，提交时由 Host 剥离（该字符不是 JS 空白，用户看不到任何合成文本）
- 持久化附件元数据：把文件元数据写入消息 source 字段（UI 侧、不进模型上下文），配合 conversationEvents 事件定义 + conversation.chat.node 键控插槽在对话历史中渲染附件卡片

规范与文档

- DSH 插件形态与契约（dsh.bundle / dsh.client / cordis entry / client bundle 包装）：参考 DeepSeek Harness 官方文档 cordis-tutorial 与社区 make-dsh-plugin 规范。

License

MIT