附件选择面板 navid-kianfar/dsh-add-assets

@achasoft/dsh-add-assets

DeepSeek Harness（dsh）Web Client 的插件。它把输入框的 + 按钮换成一个菜单，用来添加文件、添加文件夹、上传图片，或打开斜杠命令菜单。文件和文件夹来自一个选择器，可以浏览项目，也可以浏览整台 Host 机器。选中的路径以行内引用 chip 的形式进入草稿。待发送的附件显示为卡片，图片可以打开全尺寸预览。

输入框的 + 菜单展开，显示 Add files、Add folders、Upload from this device 和 Slash command 及其快捷键

功能

+ 菜单

菜单位于输入框工具行的开头。replaceCommandButton 开启时，harness 自带的 + 会隐藏，工具行只保留一个 +。

| 行 | 作用 | 默认快捷键（macOS / 其他） |
| Add files | 以文件模式打开选择器。 | ⌘U / Ctrl+U |
| Add folders | 以文件夹模式打开选择器：只列出目录，且目录可选中。 | ⇧⌘U / Ctrl+Shift+U |
| Upload from this device | 打开浏览器的文件选择框，支持 PNG、JPEG、WebP 和 GIF 图片。输入框按校验粘贴和拖拽的同一套规则校验这些图片。仅在 deviceUpload 开启时显示。 | 无 |
| Slash command | 打开输入框自带的斜杠命令菜单。 | ⌘/ / Ctrl+/ |

两个选择器作用域都不可用时，两行选择器会禁用并给出提示。harness 没有触发管线（@deepseek-ai/dsh-client-ui-input-trigger）时，命令行同样禁用。提交消息期间，整个菜单禁用。

选择器：Project 与 This machine

Add files 选择器的 Project 标签页，勾选了两个文件，底部显示「2 selected」和「Add 2」

两个作用域都可用时，选择器顶部的标签页可以切换：

- Project 通过 harness 的文件引用服务商列出会话的工作目录（原版 web 配置档里是 @deepseek-ai/dsh-file-reference-local）。在根目录输入名称会搜索整个工作区。输入含 / 的路径会列出该目录。路径相对于工作区。
- This machine 通过本插件自己的 addAssets.browse 端点列出 Host 文件系统。它从 Host 账户的主目录打开，一次显示一层，目录排在前面。面包屑从文件系统根目录开始，主目录那一级标为 Home。路径是绝对路径。仅在 outsideWorkspace 开启时提供该标签页。
两种范围下，你都可以在搜索框里输入路径，列出该目录。最后一个分隔符之后的内容用来过滤列表。在 This machine 下，/tmp/x 列出 /tmp，并按 x 过滤；~/Down 列出你的主目录，并按 Down 过滤。Windows 上只接受盘符路径（C:\Users\）和 ~\。

在 This machine 标签页输入路径后的选择器：从 / 到该文件夹的面包屑，以及列出的文件夹

切换目录、过滤或切换标签页时，已选内容都会保留。你可以从两种范围里收集文件，一步全部添加。Show hidden 会显示以点开头的条目。

| 按键（在搜索框内） | 操作 |
| ↑ / ↓ | 移动高亮 |
| Enter | 文件模式：打开高亮的文件夹，或勾选高亮的文件。文件夹模式：勾选高亮的文件夹。 |
| →（光标在输入框末尾） | 打开高亮的文件夹 |
| ←（光标在输入框开头） | 返回上一级 |
| Cmd+Enter 或 Ctrl+Enter | 添加所有已选内容 |
| Esc | 关闭，不添加 |

输入法组合期间，Enter、方向键和 Esc 交给输入法处理。

引用 chip

撰写区草稿：两枚文件 chip 和一枚文件夹 chip，放在已输入的文字之后

每个选中的路径都会变成一个行内引用 chip。chip 显示 basename，文件夹末尾带 /。它隐藏的值就是撰写区自带 @ 补全会写入的 @path 提及。路径含空白字符时会加引号，如 @"My Files/a.txt"。消息发送时，模型收到的是这段提及文本。复制 chip 也会复制它。

如果 harness 没有触发管线，发送时就没有东西能把 chip 变成文本。这种情况下，插件改为把纯 @path 文本追加到草稿里。

路径含双引号或控制字符时，无法写成提及。这类选择会被跳过，+ 下方会提示跳过了多少个。

附件预览

附件行：一张图片卡片显示缩略图和「PNG · 640×400 · 18KB」，一张文本文件卡片，以及带文件和文件夹 chip 的草稿

插件接管撰写区的附件行（conversation.input.attachments）：

- 图片卡片显示缩略图、文件名，以及一行详情：格式、像素尺寸、字节大小。点击卡片打开全尺寸预览。预览中，← 和 →（或两侧按钮）在图片间切换，垃圾桶按钮移除当前图片，Esc、关闭按钮或点击变暗的背景都能关闭预览。
全尺寸图片预览，图片上方显示文件名、详情、移除按钮和关闭按钮

- 文件卡片用于展示输入框支持的非图片附件。文件上传过程中，卡片会显示上传状态。上传失败时，点击卡片重试。
- 每张卡片都有移除按钮。
- 把文件拖到页面上会显示放置目标。由插件处理放置，因为它替换掉的内置附件行原本负责这件事。如果输入框当时无法接收文件，放置目标会给出提示。

设置卡片

在 Settings > Plugins 中展开的 Add assets 卡片，显示 Options 面板、Browse scope、Shortcuts 和 Attachment preview 分组

Settings → Plugins 里的 Add assets 卡片可以编辑所有配置项。改动会暂存，点击 Save 才生效，点 Discard 则丢弃。快捷键或数字字段无效时，Save 保持禁用。如果 harness 报告该分区不可写，卡片为只读。

环境要求

- dsh 0.1.5-rc.2，使用 web 配置档（dsh web）。插件基于该版本构建并测试。它与输入框的集成依赖该版本的若干细节，详见已知限制。
- Node.js ^22.19 || >=24（package.json 中的 engines）。
- PATH 中有 pnpm，dsh plugin 用它安装包。

插件把 @deepseek-ai/cordis、@deepseek-ai/dsh-file-reference、@deepseek-ai/schemastery 和 @deepseek-ai/dsh-typert-protocol 声明为 peerDependencies。这四个包都随 harness 一起发布。插件的浏览器端会请求 harness 注入 dsh-api-remotes、dsh-client-locale、dsh-client-ui-conversation、dsh-client-ui-input-trigger、dsh-client-ui-settings 和 dsh-client-ui-settings-plugins（即 package.json 中的 dsh.client.inject 字段）。

以下 harness 服务是可选的，没有它们插件也能工作：

| Harness 服务 | 缺少时 |
| 文件引用服务商（remote.fileReferences） | 没有 Project 标签页。选择器只提供 This machine。 |
| 输入触发器管线（inputTriggers） | Slash command 行被禁用，选中的项以纯 @path 文本写入，而不是 chip。 |
| 设置服务商（settings） | 直接使用配置档中的值，设置卡片无法修改它们。 |

操作系统。 POSIX 主机使用绝对路径。Windows 主机只接受盘符路径：UNC（\\server\share）和无盘符（\foo）路径会被拒绝。Windows 路径规则只有单元测试覆盖，尚未在真实 Windows 主机上验证。

安装

dsh plugin --profile <name> 会把命令的其余部分作为 pnpm 命令，在该配置档的目录中执行。安装成功后，它会把声明了 dsh.bundle 的包加入配置档的 bundle 列表：

bash
dsh plugin --profile web add @achasoft/dsh-add-assets

打包好的 tarball 也用同样方式安装： bash
dsh plugin --profile web add ./achasoft-dsh-add-assets-0.1.0.tgz

装完重启 dsh web。想确认插件是否加载，导出合成后的配置，找它那一层 # == @achasoft/dsh-add-assets： bash
dsh --profile web --dump-config

卸载： bash
dsh plugin --profile web remove @achasoft/dsh-add-assets

这一步也会把包从配置档的 bundle 列表里删掉。如果配置档的 cordis.patch.yml 里还有针对 add-assets 的补丁，harness 会警告 patch: entry "add-assets" not found 并跳过它。记得把这个补丁也删掉。

补丁如何分层

包的 cordis.patch.yml 会成为配置档的一层。它插入两行：

| 行 id | name | 作用 |
| add-assets | @achasoft/dsh-add-assets/host | 宿主侧：设置区块和 addAssets.browse 端点。承载配置。 |
| add-assets-ui | @achasoft/dsh-add-assets | 浏览器侧。必须保持裸包名，因为 Web Client 靠解析 <name>/package.json 来找插件的浏览器侧。 |

层按以下顺序生效：先按 bundle 列表顺序应用 bundle 补丁，然后是 $DSH_HOME/profiles/<name>/cordis.patch.yml，再是 $DSH_HOME/cordis.patch.yml，最后是任何 --patch 文件。要覆盖配置，就在更靠后的层里按 id 定位那一行。补丁会替换整行的 config，而 schema 要求每个键都在，所以十个键要全部列出： yaml
- id: add-assets
config:
replaceCommandButton: true
deviceUpload: true
outsideWorkspace: false
browseMaxEntries: 500
filesShortcut: mod+u
foldersShortcut: mod+shift+u
commandShortcut: alt+/
pickerResultLimit: 20
previewDensity: compact
previewDetails: true

补丁文件是顶层的补丁列表，如上所示。不要用 patch: 键包一层：harness 会拒绝，并报 patch: id is required for non-insert patches。

配置档里的值只是起始值。从设置卡片保存的任何内容都由 harness 的 settings 服务商存储，优先级高于这些起始值。

配置

schema 不定义默认值，行里缺任何一个键都会在加载时失败。下表默认值就是随包发布的 cordis.patch.yml 里的值。设置卡片可以编辑每个键。

| 键 | 默认值 | 允许值 | 含义 |
| replaceCommandButton | true | boolean | 隐藏 harness 自带的 +。设为 false 时两个按钮都显示：harness 的 + 仍然打开斜杠命令菜单，本插件的 + 就在旁边。 |
| deviceUpload | true | boolean | 显示 Upload from this device 行。粘贴和拖放两种方式都照常可用。 |
| outsideWorkspace | true | boolean | 提供 This machine 标签页。端点每次调用都会检查这个值。见安全。 |
| browseMaxEntries | 500 | integer 1–2000 | Host 为单层目录返回的最大条目数。 |
| filesShortcut | mod+u | 快捷键或 "" | 以文件模式打开选择器。 |
| foldersShortcut | mod+shift+u | 快捷键或 "" | 以文件夹模式打开选择器。 |
| commandShortcut | mod+/ | 快捷键或 "" | 打开斜杠命令菜单。 |
| pickerResultLimit | 20 | integer 1–200 | 选择器每次查询显示的行数。在 Project 作用域下，服务商会套用自己的上限 maxResults（默认 20），所以这个设置也要一并调高。 |
| previewDensity | card | card、compact | card 显示缩略图、名称和详情行。compact 只显示小缩略图和名称，没有详情行。 |
| previewDetails | true | boolean | 在 card 密度下显示详情行。上传进度和失败信息始终显示。 |

快捷键语法

- 快捷键是用 + 分隔、不区分大小写的修饰键列表，后面跟且只跟一个按键。
- 修饰键： mod、cmd、command、ctrl、control 都指平台加速键：Apple 设备上是 Command，其他平台是 Ctrl。alt 和 option 指 Alt。shift 指 Shift。
- 按键： 单个字符，或 enter、escape/esc、space、tab、backspace、delete、up、down、left、right 之一。
- 每个快捷键都必须包含 mod 或 alt。 只有 Shift 不算。快捷键监听整个页面，纯按键的快捷键会把该按键从所有文本输入框里抢走。
- "" 关闭快捷键。
- 快捷键无效时，Host 在加载阶段直接报错，错误信息会指出是哪个字段；设置卡片也不会保存无效的快捷键。
- 输入法组合输入期间、消息提交期间，快捷键不生效。在 macOS 上，同时按住 Ctrl 和 Command 会让 mod 快捷键不再匹配。

RPC 端点

Host 侧注册一个 Typert Remote 端点。浏览器侧把它挂载为 ctx.remote.addAssets，通过 harness 网关在 /api 路由上调用。传输格式由 harness 自己定义。这个端点不是独立的 HTTP API。

addAssets.browse(path: string, query: string) → AssetBrowseResult

| 参数 | 含义 |
| path | 要列出的目录："" 或 ~ 表示 Host 主目录，~/…，或完整路径。 |
| query | 对条目名称做不区分大小写的子串过滤，在条目上限生效前应用。 |

成功时返回 { ok: true, listing }。listing 包含：

- path：列出的目录。
- home：Host 账户的主目录。
- crumbs：从文件系统根目录到 path 的每一级目录，格式为 { name, path }。
- entries：{ name, path, kind: 'file' | 'directory', hidden }，目录在前，每组按名称排序。
- truncated：上限是否截断了该层。

失败也以值的形式返回，{ ok: false, code, message }，code 取值如下：

| code | 触发条件 |
| disabled | outsideWorkspace 为 false |
| not-a-directory | 该路径指向的不是目录 |
| unreadable | 该路径不是完整限定路径、不存在，或无法读取 |

契约放在 generated/ 里，类型从 @achasoft/dsh-add-assets/host 导出。

安全与信任模型

- 身份认证。 浏览调用走 harness 的 /api 路由。Host 头不受信任时（回环地址、局域网 IP 地址，或配置好的 trustedHosts 条目），该路由返回 403 拒绝请求；缺少浏览器会话 cookie 时返回 401。cookie 由启动 token 签发。
- 浏览能看到什么。 Host 进程账号能读的任何目录。它返回条目名称、类型、绝对路径和主目录路径。遇到符号链接会跟随，报告它指向什么；断链则省略。其他条目类型（套接字、FIFO、设备）跳过。
- 浏览不做什么。 它从不打开文件，也不返回文件内容：只列目录、对符号链接做 stat。chip 发给模型的是 @path 文本，不是文件本身。智能体之后能否读到该路径，取决于它自己的工具和权限。
- outsideWorkspace 是偏好设置，不是安全边界。 任何使用 Web Client 的人都能在设置卡片里把它重新打开。设计上假定此人是已认证的操作者，其智能体本来就能在 Host 上执行 shell 命令。如果某些浏览器用户不该看到这台机器的目录树，就不要给他们安装这个插件，也不要给他们能执行 shell 的智能体。在配置档里设成 false 拦不住他们。
- 限制。 schema 把 browseMaxEntries 上限锁在 2000，所以浏览器端的写入无法把它调高。读取目录时按流式读入一个有序窗口，窗口最多容纳这么多条目，因此超大目录对 Host 的开销只有这个窗口。同时最多解析 8 个符号链接。Windows 上拒绝 UNC 路径，Host 因此永远不会连接浏览器指定的网络服务器。

已知限制

- chip 放在草稿末尾，不在光标处。斜杠命令菜单也在草稿末尾打开，因为 dsh 0.1.5-rc.2 的输入框是富文本（Lexical）编辑器，插件不读取它的光标位置。
- 选择可能被静默丢弃。 如果还有多个 chip 正在放置时草稿发生变化（比如你正好在这时打字），剩下的选择会被放弃，且不给提示。
- 无法引用的路径会跳过。 路径里含 " 或控制字符时，无法写成提及。
- 取消列表只在条目之间生效。 读取卡在挂起的网络挂载上时，你继续操作也可能停不下来。
- 这台机器没有 Home 按钮。 一旦浏览到主目录之外，面包屑里就不再包含 Home。在搜索框里输入 ~ 可以回去。
- 这台机器一次只过滤一层。 只有 Project 范围会搜索整棵树。
- 项目范围本身有上限。 服务商把每个回答限制在 maxResults（默认 20）以内，却不说明自己做了截断，所以选择器无法报告该层级已被截断。服务商还会隐藏点开头的条目，除非你输入的名称以 . 开头；它也会跳过被排除的目录，因此 Show hidden 在那里什么也显示不出来。
- 选择器标题写的是「Add workspace files」和「Add workspace folders」，即使在 This machine 标签页上也是如此。
- harness 的 + 是被隐藏，而不是被替换。 harness 没有为这个按钮提供插槽。插件在 composer 卡片内通过 button[aria-haspopup="listbox"] 找到它，并标记为隐藏。如果未来的 harness 改动了这段标记，两个按钮都会显示出来。
- 附件行会替换自带的附件行。 插槽只渲染优先级最低的那一项，而本插件注册的优先级是 -1。另一个插件若以更低的优先级注册到同一位置，就会替换本插件的行，包括它的拖放处理。
- 全尺寸预览不会把焦点困住。 它会设置 aria-modal，并在关闭时恢复焦点，但 Tab 键仍能到达它后面的页面。
- Windows 的路径处理尚未在真实主机上验证过。

开发

开发需要一个同级的 ../deepseek-harness 检出，因为 package.json 里的 link: devDependencies 指向它。构建产物（lib/、types/、tsbuild/）不提交。

| 命令 | 作用 |
| npm run build | 先跑 tsc -p tsconfig.build.json，再跑 tsdown（写出 lib/host.js、lib/client.js 及其他入口） |
| npm test | 检查 generated/ 与 src/host/ 是否一致（check:typert），然后运行 vitest run |
| npm run check:typert | 单独运行 Typert 新鲜度检查 |
| npm run typecheck | tsc --noEmit |

先跑 npm run build，再跑 npm test。tests/client-bundle.spec.ts 会渲染构建出的 lib/client.js，当该文件缺失或比 src/ 旧时就会失败，并指出修复方法： bash
npm run build && npm test

generated/ 存放 addAssets.browse 的 Typert 契约。只有 harness 的生成器能产出它，所以它被提交进仓库。改动端点或它用到的任何类型后，重新生成： bash
node scripts/regen-typert.mjs ../deepseek-harness

脚本会修改 harness 检出里的文件，并在结束时从 git 恢复它们。绝不要同时运行两次重新生成。

许可证

MIT。见 LICENSE。