# dsh-file-uploads

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4f46e5)](https://github.com/deepseek-ai/deepseek-harness)

[English](README.md) | 简体中文

为 DeepSeek Harness Web 输入框增加任意文件上传功能：文件以待发送卡片显示，提交时把容器内路径提供给模型，并可在设置中统一下载和删除。

## 功能

- 在现有输入框控制区旁增加 **文件** 按钮。
- 支持一次选择多个任意类型的本地文件，不限于图片。
- 待发送文件以类似图片附件的卡片悬浮显示在输入框上方。
- 保持编辑框干净：上传后不会向草稿写入可见路径或自动描述。
- 发送消息时，才通过 Harness 内置引用序列化管线把文件绝对路径加入模型内容。
- 提交后清空待发送卡片；提交失败时恢复卡片。
- 所有文件统一保存到固定目录，默认是 `$DSH_HOME/uploads`。
- 在 **设置 → 上传文件** 中查看文件，并支持下载和删除。
- 同名文件不会覆盖，自动保存为 `name (1).ext`、`name (2).ext` 等名称。
- 支持单文件上限和上传目录总容量限制。

## 兼容性

- DeepSeek Harness `0.1.0-rc.6`
- Web Profile
- Node.js 22 或更高版本

Harness 当前的原生附件传输只支持栅格图片。本插件针对任意文件采用 Agent 环境可用的路径方案：先把文件存入 Harness Host/容器，再通过内置输入引用序列化器把路径加入提交内容。

## 安装

把带版本标签的 GitHub Release 安装到 Web Profile：

```sh
dsh plugin --profile web add "github:l541402398/dsh-file-uploads#v1.0.0"
```

安装后重启正在运行的 Web Profile，并刷新浏览器页面。

如需安装最新开发分支：

```sh
dsh plugin --profile web add "github:l541402398/dsh-file-uploads#main"
```

卸载：

```sh
dsh plugin --profile web remove dsh-file-uploads
```

## 使用方法

1. 在 Harness Web GUI 中打开一个会话。
2. 点击输入工具栏中的 **文件**。
3. 选择一个或多个本地文件。
4. 在输入框上方检查待发送卡片，也可以点击 × 移除。
5. 输入普通提示词，或者让编辑框保持为空。
6. 发送消息。模型实际收到的内容中会包含类似：

   ```text
   上传文件：`/path/to/.dsh/uploads/report.pdf`
   ```

这行生成内容在提交前不会显示在编辑框中。文件路径是 Harness Host 所见的路径；在 Docker 部署中，它指容器内部路径。

## 设置页

插件会新增 **上传文件** 设置区，显示：

- 固定存储目录；
- 单文件和目录总容量限制；
- 当前空间占用；
- 文件名、大小、修改时间和绝对路径；
- 下载与删除操作。

文件会持续保存，直到手动删除。

## 配置

插件默认无需配置，可以使用以下环境变量覆盖默认值：

| 环境变量 | 默认值 | 用途 |
|---|---:|---|
| `DSH_UPLOAD_DIR` | `$DSH_HOME/uploads` | 上传目录的绝对路径。 |
| `DSH_UPLOAD_MAX_BYTES` | `104857600` | 单个文件最大字节数（100 MiB）。 |
| `DSH_UPLOAD_TOTAL_MAX_BYTES` | `1073741824` | 上传目录最大总字节数（1 GiB）。 |

Docker Compose 示例：

```yaml
services:
  dsh:
    environment:
      DSH_UPLOAD_DIR: /data/dsh/uploads
      DSH_UPLOAD_MAX_BYTES: 104857600
      DSH_UPLOAD_TOTAL_MAX_BYTES: 1073741824
    volumes:
      - ./dsh-data:/data/dsh
```

## 安全模型

- 文件列表、上传、下载和删除接口使用与 Harness 内置 Web API 相同的回环地址/可信 Host 和 Origin 检查。
- 拒绝浏览器跨站请求。
- 文件名会被规范化，并移除路径片段和控制字符。
- 下载和删除只接受配置目录中的普通文件，不跟随符号链接。
- 上传内容先写入私有临时文件，完成同步后原子发布，不覆盖同名文件。
- 插件启动时自动清理异常中断留下的 `.upload-*` 临时文件。
- 意外服务端错误只写日志，不把内部路径返回给浏览器。

这套可信边界不是用户账号认证系统。如果 Harness Web GUI 会暴露给其他用户或公网，请使用带身份验证的反向代理保护整个部署，并正确配置 Harness 的 trusted hosts。

## 开发

运行检查：

```sh
npm test
npm run check
```

这是一个持久化的 Host + Client 双端 Cordis Bundle：

- `index.js`：Host HTTP 路由、存储、容量和可信请求检查。
- `client.js`：上传按钮、待发送文件卡片、隐藏引用序列化和设置页 UI。
- `cordis.patch.yml`：可由 `dsh plugin add` 安装的 `dsh.bundle` Composition。
- `test/upload-manager.test.js`：Host 存储与安全回归测试。

本地链接开发方式见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

[MIT](LICENSE)