DSH 文件上传插件（File Upload）v2.1.0

把 DSH Web GUI 原版只支持图片的附件通道，扩展为任意文件上传：拖入任意文件（PDF、3MF、ZIP、Excel、代码、图片……）→ 文件上传/引用到本机中转目录 → 输入框出现一个蓝色文件 chip → agent 可以直接读取该文件。

定位说明（v2.0.0 起）：本插件的本质是文件上传功能，不是"路径展示"。路径只是内部机制——agent 读取文件必须依赖磁盘路径，浏览器又拿不到（见下文"为什么必须上传"），所以插件负责把文件物化到本机、并把路径交给 agent。用户界面不再出现任何路径概念：chip 只显示文件名，用户只需知道"文件上传好了，agent 能读了"。

本仓库是持久化 profile 插件（dsh.bundle + dsh.client 双声明）：按官方方式安装一次，DSH 重启后自动生效。

功能特性

• 🖱️ 页面任意位置拖入任意文件（多文件、图片均可）；拖拽时全屏提示"松开以接收文件"
• 📦 任意文件类型：原版"仅图片"附件通道被完全静默接管，任何文件都可拖入
• 📍 本机文件零上传直引：Chromium（Edge/Chrome）拖拽会经 entry API 暴露源文件路径——直接引用，零上传、零复制（你电脑里那份文件就是唯一的一份）；仅当浏览器拿不到路径（如 Firefox）时才走上传中转
• 🔵 文件以一个整体 chip 插入输入框：蓝色文字（只显示文件名+格式）、不可被局部删改（Backspace/Delete 一次删除整个引用）
• 📐 篮筐宽度随文件名自适应：插入时用 composer 真实字体实测文件名宽度，pill 精确贴合（误差

`dsh plugin` 会 pnpm link 本包到 `$DSH_HOME/profiles/web` 并追加 `dsh.profile.bundles`。之后**无论用 npx 版还是源码版启动 DSH，插件都自动加载**。

验证：`dsh web --dump-config` 应出现 `# == dsh-file-upload` 层。

> 从旧名 `dsh-drop-file-to-path` 升级：插件 id 与路由已更名为 `file-upload`，重装后旧版本无需卸载（同一 bundle 行被覆盖）。

## 工作原理

| 部件 | 位置 | 职责 |
|---|---|---|
| Host 半（`lib/index.js`） | 宿主进程，`inject: ['webServer']` | HTTP 路由 `/api/file-upload/begin\|chunk\|end\|abort\|list\|clean`：分块校验、两级去重（lastModified+sha256）、manifest 清单、Origin 校验、node:fs 落盘、清理接口 |
| Client 半（`lib/client.js`） | 浏览器（`__ModuleLoader__` bundle，`dsh.client` 声明） | 全局拖拽监听（capture 接管）、fetch 分块上传、待机圆环、注册 trigger source、经 `conversation.input.insertReference` 插入文件 chip、侧边栏清理入口 |

### 文件 chip

文件引用走 composer 原生的参考引用机制（U+FFFC 占位符 + occurrence 表 + 提交时 codec 序列化）：占位符在草稿里只占一个字符，因此整个引用是不可分割的整体；提交时经插件注册的 `file-upload` source 的 codec 把占位符展开为真实路径（含 `.b64`）。

**篮筐宽度自适应**：插件在插入前用 composer 的真实字体实测文件名宽度，算出 NBSP 空格数 `pad`，随 chip 一起插入（占位符 + pad 个 NBSP）。chip 单元格宽度 = 基础 1em + pad×空格宽 ≈ 文件名宽——**先有文件名，后有篮筐**。为此需要两处配套（都在本 DSH 发行版内）：

- **加宽字体**：用 `tools/patch-chip-font.mjs` 把 `DshChipCell` 的 U+FFFC advance 从 composer 默认 4em 改为 **1em**（同名字体族、后声明者生效，textarea/镜像/背板三层共享同一 advance，对齐关系不变）；
- **核心 composer 扩展**（`dsh-client-ui-conversation`）：occurrence 支持 `pad` 扩展占位区间——插入、序列化、复制/剪切投影、Backspace/Delete 整删、backdrop 渲染全部按 `[offset, offset+1+pad)` 整段处理。

**无该 composer 扩展的公开版 DSH（降级模式）**：`pad` 缺失时插件自动退回 `[offset, offset+1)`——chip 为固定 1em 宽（文件名按 composer 默认样式显示），提交/复制/刷新草稿全部正确，**不会损坏草稿**。

### 上传、校验与去重

- **分块**：4194303 字节（4MiB−1，**3 的倍数**）——每满块的 base64 无中间填充符，拼接流可无损解码（4MiB 整块会在流中间嵌入 `==`，Node/Python 解码器都会在首个 `==` 处截断，>4MB 文件会损坏；v1.2.1 起修复）。
- **完整性**：`chunk` 阶段校验每块精确长度与 base64 合法性；`end` 阶段校验分块齐全、总量一致、解码后字节数 === 声明大小——截断/缺块/伪造数据一律拒绝，绝不落盘损坏文件。
- **两级去重（防误复用）**：`begin` 快路径命中需要「同名 + 同大小 + manifest 登记的源修改时间一致」——重复拖同一文件秒回、零上传；**编辑过但字节数未变的文件不会走快路径**（v2.1.0 修复的误复用问题），而是完整上传后由 `end` 的 sha256 逐字节比对裁决：内容相同复用旧路径、不产生新副本；内容不同落 `_1` 副本，绝不复用错误内容。v2.1.0 之前上传的旧文件首次重拖也会走完整上传（缺 manifest 记录），由 end 哈希兜底并补登记。
- **清单登记**：每次落盘（含去重复用命中）都把文件登记进 `.dsh-manifest.json`（原名、源修改时间、sha256、是否自动编号副本）；清理时同步注销。清单缺失或损坏时所有行为保守化（不做快路径复用、不标冗余副本），不影响上传本身。

### 待机圆环（插入点加载动画）

- **触发**：只有真正需要等待的上传才显示——上传开始后延迟 150ms，若期间完成（极小文件、秒回去重）则**从不出现**；超过 150ms 才在插入点显示。
- **位置**：直接测量 composer 自己的 mirror 镜像层（与输入框同字体、同宽度、同滚动，天然对齐），定位到**光标/草稿末尾**，圆心再右移一个字符宽（"第二个字"位置）——不遮住已输入的文字。
- **外观**：16px DeepSeek 蓝（`#4d6bfe`）弧线圆环，渐隐拖尾 + 光晕，0.85s/圈持续旋转。
- **消失**：chip 插入的**同一瞬间**圆环立即移除（命令式 DOM 直接挂在 `document.body`，不经过 React/slot，无中间环节可吞掉它）。

### 清理入口

侧边栏脚部的**垃圾桶图标**（`sidebar.footer.action` 槽位，渲染在设置图标上方；悬停显示"清理上传目录"）点击后弹出右下角清理浮层，复用同一套清理逻辑（`/api/file-upload/list` + `/clean`）。

依赖官方服务：`webServer`（HTTP 路由）、`slots`（shell.overlay + conversation.composer.dock + sidebar.footer.action）、`inputTriggers`（source 注册与序列化）、`conversation`/`sessions`（按 session 解析输入门面）。除上述核心 occurrence 扩展外不修改 dsh 源码。

## 版本历史

- **v2.1.0**（当前）：修复一批实测发现的问题——
  - **P1 快路径误复用**：begin 快路径从"同名同大小即复用"改为"同名同大小 + 源修改时间一致才复用"，编辑过但字节数没变的文件不再被静默引用旧内容（`File.lastModified` ↔ manifest 登记时间，1s 容差）
  - **P2 清理误标**：新增 `.dsh-manifest.json` 清单，冗余副本标记只认清单登记的自动编号副本，`notes_2024.txt` 这类自然命名不再被误标、不会被误删
  - **P3 失败泄漏**：客户端上传任一步失败立即 abort 宿主会话，不再滞留内存到 10 分钟超时
  - **P4 静默丢弃**：移除 16 个文件上限截断，一次拖更多文件也不会丢引用
  - **P5 插入乱序**：多文件 chip 严格按拖拽顺序插入（此前按完成顺序）
  - **P6 busy 卡死**：composer 忙时插入失败改为定时重试，不再等可能不来的事件
  - **P7 sanitize 兜底**：纯非法字符文件名（如 `::::`）落盘为 `file` 而非 `____`
  - **P8 跨源防护**：HTTP 路由拒绝跨源请求（Origin ≠ Host 时 403）；无 Origin 的本地调用不受影响
- **v2.0.0**：正式更名 **`dsh-file-upload`**——定位从"拖拽文件转路径"改为"**任意文件上传**"（把原版仅图片的附件通道扩展为任意文件）；用户界面移除全部"路径"概念（ready 卡片不再显示/复制路径，提示文案统一为"接收文件"）；内部机制（上传、两级去重、完整性校验、待机圆环、清理入口）与 v1.4.8 完全一致
- **v1.4.8**：待机圆环最终形态——延迟 150ms 显示（瞬间完成不出圈）、镜像层测量定位（光标右侧一个字符）、chip 插入瞬间同步消失
- **v1.4.0**：清理入口改为**侧边栏垃圾桶图标**（设置图标上方，悬停提示）；移除设置内导航页
- **v1.3.0**：新增**上传目录清理**功能（文件清单、冗余副本/按大小/清空三种清理模式、删除前确认）
- **v1.2.3**：恢复 **begin 先查后传**快速去重（同名同大小秒回，零上传）；end 内容哈希兜底保留
- **v1.2.2**：chip 样式机制回退为全局规则（v1.2.0/1.2.1 的动态规则存在时序 bug）
- **v1.2.1**：修复 >4MB 文件解码截断（分块改为 3 的倍数）、end 完整性校验、草稿投影 pad 回退、Windows 保留名 sanitize
- **v1.1.0**：路径以蓝色 chip 整体插入、篮筐宽度自适应、begin 快速去重

## 开发

```sh
node --check lib/index.js lib/client.js   # 语法检查
node --test tests/host.test.mjs           # 宿主行为测试（27 例：上传/完整性/两级去重/防误复用/清单/清理/跨源/安全）

CI（.github/workflows/ci.yml）在 push/PR 时自动执行以上两步。

文件说明

├── lib/index.js            # Host 半：HTTP 上传路由 + 校验/去重/清理 + node:fs 落盘
├── lib/client.js           # Client 半：全局拖拽 + 待机圆环 + 文件 chip + 侧边栏清理入口
├── tools/patch-chip-font.mjs  # 生成加宽 DshChipCell 字体的工具（改宽度后重跑）
├── tests/host.test.mjs     # 宿主行为测试（node --test，免 DSH 服务器）
├── chip-cell-font.b64      # 加宽字体产物（client.js 内嵌同一份）
├── cordis.patch.yml        # bundle 补丁层（insert 插件行）
├── .github/workflows/ci.yml # CI：语法检查 + 宿主测试
├── .gitignore
└── package.json            # dsh.bundle.patch + dsh.client 声明

落盘与读取约定

• 中转目录：C:\Users\\.dsh-dropbox\（os.homedir() 解析；测试可用 DSH_DROPBOX_DIR 覆盖）
• 清单文件：~/.dsh-dropbox/.dsh-manifest.json（插件内部登记，勿手动编辑；删除中转文件时建议用清理面板，保证清单同步）
• .b64 解码（agent 侧）：见上文 .b64 说明

已知限制（v2.1.0）

• 上传内存：单文件上传期间，宿主进程在内存中持有该文件全部 base64 分块（512MB 文件 ≈ 683MB 字符串），随后在 end 落盘。单机单用户够用；并发多个大文件会明显吃内存（架构级优化待后续版本）。
• 本机直引路径（零上传）：依赖 Chromium webkitGetAsEntry() 返回的真实磁盘路径，无存在性/大小校验；OneDrive 占位文件、虚拟文件系统拖入时可能得到不可读路径（此时会看到 agent 报文件不存在，建议改用"复制文件再拖"）。Firefox 等拿不到路径的浏览器自动走上传兜底，无此问题。
• 清理不可逆：清理浮层删除的是中转目录副本，历史会话引用的路径会失效——操作前弹窗会明确提示。

License

MIT