# dsh-stream-upload

[English](README.md) | 中文

一个 DeepSeek Harness 混合附件插件：

- PNG/JPEG/WebP/GIF 通过官方 `createDraftImages` → `addImages` attachment 管线进入原生预览和模型输入。
- 代码、文本、PDF、DOCX/XLSX、压缩包等普通文件，以原始字节流写入当前会话工作区。
- 图片不会在 `.dsh-uploads` 下保存重复副本。

## 安全与资源边界

- Host、Origin、Fetch Metadata 复用当前 DSH `trustedHosts` 信任边界。
- 只接受存在且可解析工作区的 session；不存在 anonymous 共享目录。
- 上传根固定为 `<session-workspace>/.dsh-uploads/<sessionId>/`。
- 工作区、上传根和会话目录执行 realpath 包含校验，拒绝符号链接目录。
- 目录权限收敛到 `0700`，文件使用独占 `0600` 临时文件。
- 请求体边接收边写入临时文件并增量计算完整 SHA-256，不使用 `Buffer.concat` 或 Base64。
- 通过完整摘要去重，配额通过后用同文件系统硬链接原子发布。
- 请求失败、客户端中断、超限或配额不足时清除临时文件。
- API 只返回工作区相对路径，不返回服务器绝对路径。
- 支持单文件、会话、工作区总量、文件数、并发、超时、磁盘余量和逐文件 TTL 限制。

## 默认配置

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `maxBytes` | 99614720（95 MiB） | 单个普通文件上限；低于 Cloudflare 100 MB 请求上限 |
| `allowedExtensions` | `[]` | 扩展名白名单；空表示允许所有普通文件 |
| `uploadDirName` | `.dsh-uploads` | 固定安全子目录，不接受其它值 |
| `uploadTtlMs` | 604800000（7 天） | 文件保留期 |
| `sweepIntervalMs` | 3600000（1 小时） | 清理周期 |
| `maxConcurrentUploads` | 2 | 并发上传数 |
| `maxSessionBytes` | 1073741824（1 GiB） | 单会话保留容量 |
| `maxTotalBytes` | 2147483648（2 GiB） | 单工作区上传根总容量 |
| `maxFilesPerSession` | 100 | 单会话文件数 |
| `minFreeBytes` | 536870912（512 MiB） | 文件系统保留空间 |
| `requestTimeoutMs` | 120000 | 上传请求空闲超时 |

## 使用边界

- 暂不支持文件夹上传或全局拖放；统一使用回形针按钮选择一个或多个文件。
- 普通文件按原样保存，不在上传请求中解析、执行或自动解压。
- PDF/DOCX/XLSX 等格式由 agent 的受控读取工具后续处理。
- 插件 UI 有错误边界；locale 增强缺失或失败时退回英文，不阻止上传入口加载。

## 上传状态与输入框引用

- 选择文件后，通过官方 `conversation.input.dock` 在当前输入框正上方显示紧凑横向状态条；回形针仍在
  `conversation.input.left`。按钮和状态条按 session 共享隔离的可观察状态，不使用全局浮层。
- 每个横向 chip 分别展示文件名、大小以及等待、上传/添加附件、完成、失败或取消状态。普通文件显示
  真实字节百分比，原生图片显示 attachment 添加状态；超出宽度时横向滚动而不撑高输入区。
- 状态条与输入框保持相同的 `780px` 最大宽度并自动居中，使用无描边的统一轻量底色。单个附件自动
  拉伸填满状态条，取消/关闭操作位于同一视觉面内；多个附件共享整行，达到紧凑最小宽度后才横向滚动。
- 活跃批次可以取消；全部成功或取消后保留 5 秒再自动收起。失败结果和服务端原因持续保留，直到用户
  主动关闭。
- 可视进度使用 ARIA `progressbar`，关键状态转换通过 `aria-live="polite"` 通知读屏软件。
- 普通文件上传成功后，每个文件独占一行，以标准 CommonMark 资源链接回填输入框：
  `[显示文件名](<工作区相对路径>)`。显示文本会转义，目标只使用服务端验证过的相对路径。
- 进度使用浏览器 `XMLHttpRequestUpload.progress`；到达 100% 只代表字节发送完成，必须收到并验证
  服务端响应后才显示“上传完成”。服务端原始字节流协议不变。
- 当前不是分块/断点续传；取消会触发服务端清理 `.part`，失败后重新选择文件即可重试。

## 安装与验证

本包是 ESM，没有 `prepare` 脚本，从 Git 安装不需要 `allowBuilds`。请把 DSH 钉在 `@deepseek-ai/dsh@0.1.2-rc.1`。

```bash
dsh plugin --profile web add github:roojay/dsh-stream-upload#v0.4.0
```

从 npm 安装（发布后）：

```bash
dsh plugin --profile web add dsh-stream-upload@0.4.0
```

从 GitHub Release 的 tarball 安装：

```bash
dsh plugin --profile web add https://github.com/roojay/dsh-stream-upload/releases/download/v0.4.0/dsh-stream-upload-0.4.0.tgz
```

从本地目录安装：

```bash
cd /absolute/path/to/dsh-stream-upload
pnpm install --ignore-scripts
dsh plugin --profile web add "$PWD"
```

安装后必须完整重启 `dsh.service`（或等价的 `dsh web` 重启），并验证普通文件上传、原生图片附件、非可信 Host 403 和服务日志。

```bash
npm test
```

从 `web` profile 移除：

```bash
dsh plugin --profile web remove dsh-stream-upload
```