# dsh-filetransfer

[English](README.md)

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web
提供接近原生体验的文件草稿、文件卡片与本地交付文件下载。

## 功能

- 拖放或选择非图片文件，先以草稿卡片显示，确认后再发送。
- 支持只发文件，也支持“文件＋用户文字”。
- 图片继续使用 DSH 官方图片附件流程。
- Word、Excel 和其他文件使用不同颜色、图标和类型标签。
- 隐藏内部文件引用；草稿文件只通过卡片右侧的关闭按钮移除。
- 从仅监听本机的交付面板下载 Agent 产出的文件。

上传操作只负责暂存文件，不会调用 `session.prompt`。只有用户点击 DSH
原有的发送按钮以后，文件才会交给 Agent。

## 兼容性

`0.2.5` 版本面向 `@deepseek-ai/dsh` `0.1.0-rc.7`，要求 Node.js 22.19
或更高版本。DSH 仍处于开发者预览阶段，后续版本可能需要适配。

DSH `0.1.0-rc.7` 已有原生图片块，但还没有通用文件块。本插件在消息内部保存
一个精简的工作区相对路径 `<dsh-file>` 标记，并在网页对话中将其投影成文件卡片；
内部路径不会作为可见文字显示。

## 从 GitHub 安装

在准备作为 DSH 工作区的目录中运行：

```powershell
npx @deepseek-ai/dsh plugin --profile web add github:kerlyken/dsh-filetransfer
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web
```

若需要固定版本，请把安装地址写成
`github:kerlyken/dsh-filetransfer#<commit-sha>`。

不要安装 `@deepseek-ai/dsh-cordis-host-runner`；DSH Web 已自带 Host runner。

## 默认配置

- Host 接口：`http://127.0.0.1:3199`
- 工作区：启动 DSH 时所在的目录
- 收件目录：`<工作区>/bridge/inbox`
- 交付目录：`<工作区>/deliverables`
- 单文件解码后大小上限：64 MiB
- 默认允许的 DSH Web 来源：`http://127.0.0.1:3080` 和
  `http://localhost:3080`

路径、端口或网页来源不同时，请在 profile 的 `cordis.patch.yml` 中覆盖
`filetransfer` 行。后应用的 patch 会替换整份 `config`，因此要写全所需配置。

## 可选本地集成

核心插件不依赖企业微信或其他消息平台。可信的本地集成可以主动提交工作区相对标记，
复用同一套文件卡片渲染：

```xml
<dsh-file path="bridge/inbox/example.docx"></dsh-file>
```

用户说明可以放在标记下一行。构造标记前必须确认文件位于配置的 DSH 工作区内。

`integrations/wecom/` 只是一套可选参考模块，用于匹配企业微信分开发送的文字和
文件事件。该目录会参加 CI 测试，但不会进入 npm 包，也不是安装插件的必要条件。

## 安全

上传/下载服务只监听 `127.0.0.1`，检查网页来源、清洗文件名、限制路径范围和
上传大小。不要在缺少身份验证和独立威胁模型的情况下把 3199 端口暴露到网络。
详见 [SECURITY.md](SECURITY.md)。

## 开发验证

```powershell
npm test
npm run pack:check
```

打包清单应包含插件、测试、文档和许可证，但不应包含 `integrations/`、本机配置、
收件文件或交付文件。

## 社区发布方式

DeepSeek Harness 目前建议社区插件使用独立仓库，并添加
[`dsh-plugin`](https://github.com/topics/dsh-plugin) topic。官方仓库暂不接受外部
Pull Request，因此本项目采用官方推荐的生态插件方式发布。

## 许可证

[MIT](LICENSE)