---

安装

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