dsh-filetransfer

Readme

# dsh-filetransfer

[简体中文](README.zh-CN.md)

Native-feeling file drafts and local deliverable downloads for
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web.

![CI](https://github.com/kerlyken/dsh-filetransfer/actions/workflows/ci.yml/badge.svg)

## What it does

- Drop or select non-image files and review them as draft cards before sending.
- Send a file by itself or together with ordinary user text.
- Keep images on DSH's official image-attachment path.
- Render Word, Excel, and generic files as distinct transcript cards.
- Remove a draft file only through its close button, without exposing or
  editing the hidden reference placeholder.
- Download agent-produced files from a loopback-only deliverables panel.

Uploading is stage-only: it never calls `session.prompt`. The file reaches the
agent only after the user presses DSH's normal Send button.

## Compatibility

Version `0.2.5` targets `@deepseek-ai/dsh` `0.1.0-rc.7` and Node.js 22.19 or
newer. DSH is a developer preview, so later releases may require a compatibility
update.

DSH `0.1.0-rc.7` has a native image block but no generic file block. This
plugin stores a compact workspace-relative `<dsh-file>` marker in the message
and projects it as a file card in the Web UI. The internal path is not rendered
as visible conversation text.

## Install from GitHub

From the directory that should be the DSH workspace:

```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
```

For reproducible installs, replace the GitHub spec with
`github:kerlyken/dsh-filetransfer#<commit-sha>`.

Do **not** install `@deepseek-ai/dsh-cordis-host-runner`; DSH Web already ships
the Host runner.

## Configuration

The included `cordis.patch.yml` uses these defaults:

- Host endpoint: `http://127.0.0.1:3199`
- Workspace: the directory from which DSH is launched
- Inbox: `<workspace>/bridge/inbox`
- Deliverables: `<workspace>/deliverables`
- Maximum decoded upload: 64 MiB
- Allowed DSH Web origins: `http://127.0.0.1:3080` and
  `http://localhost:3080`

Override the `filetransfer` row in the profile's `cordis.patch.yml` when paths,
origins, or ports differ. A later patch replaces the row's entire `config`, so
repeat every required setting.

## Optional local integrations

The core plugin has no dependency on WeCom or any other messaging platform.
Trusted local integrations can opt into the same card renderer by submitting a
normal user text block containing a workspace-relative marker:

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

Append the user's optional instruction on the next line. Reject files outside
the configured workspace before constructing the marker.

`integrations/wecom/` contains optional, dependency-free reference modules for
matching WeCom's separate text and file events. That directory is tested in CI
but excluded from the npm package and is not required by the plugin.

## Security

The upload and download server binds to `127.0.0.1`, checks allowed origins,
sanitizes file names, enforces path containment, and applies an upload limit.
Do not expose port 3199 to a network without adding authentication and a
separate threat model. See [SECURITY.md](SECURITY.md).

## Development

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

The pack check should contain the plugin, tests, documentation, and license,
but not `integrations/`, local configuration, inbox files, or deliverables.

## Community status

DeepSeek Harness currently asks community plugins to live in standalone
repositories and use the [`dsh-plugin`](https://github.com/topics/dsh-plugin)
topic. External pull requests to the official repository are not currently
accepted, so this project follows that ecosystem route.

## License

[MIT](LICENSE)