dsh-paperclip

Readme

# dsh-paperclip

> A zero-intrusion bundle for DeepSeek Harness: 📎 upload button with popover · `read_document` multi-format reader · Settings → General toggle. Adapts to light / dark themes.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
[![Version](https://img.shields.io/badge/version-0.1.0-orange)](package.json)

**English** | [中文](README.zh-CN.md)

## Features

- **📎 Upload button + popover** — Borderless 📎 button in the composer. A small ▴ next to it shows the count; click to expand upward and see pending files (filename only). Click × to remove. Files are uploaded immediately and the server path is appended to the message on send.
- **`read_document` tool** — Read `txt / json / conf / md / ini / pdf / docx / xlsx` with `offset` / `limit` paging. Text formats work zero-dependency; `pdf / docx / xlsx` show a hint when optional deps are missing.
- **One toggle** — **Settings → General** has an “Enable file uploads” switch. Off hides the button and blocks uploads. No extra tabs.
- **Theme-aware** — Uses DSH design tokens, looks correct in light and dark mode.
- **Zero-intrusion** — Standard Cordis `bundle` plugin, no DSH source changes.

## Requirements

- DeepSeek Harness `dsh >= 0.1.0-rc.8` (`web` profile)
- Node.js `>= 22`

## Install

```bash
git clone https://github.com/runfali/dsh-paperclip.git
cd dsh-paperclip
pnpm install
pnpm build        # builds lib/client.js (browser bundle)
dsh plugin --profile web add .
# restart manually: dsh web
```

Uninstall:

```bash
dsh plugin --profile web remove dsh-paperclip
```

Restart `dsh web` to apply.

## Configuration

Edit in **Settings → Plugin Config → paperclip** or override in `~/.dsh/profiles/web/cordis.patch.yml` (full replacement):

| Field | Default | Description |
|---|---|---|
| `enabled` | `true` | Show button and enable uploads |
| `maxBytes` | `67108864` | Per-upload byte cap |
| `uploadDir` | `""` | Persist directory; empty → `~/.dsh/uploads/paperclip` (content-addressed, deduped) |
| `allowedExtensions` | `[]` | Whitelist (empty = allow all) |
| `readLimit` | `2000` | `read_document` line window |
| `maxFileBytes` | `67108864` | `read_document` per-file byte cap |
| `sheetRowLimit` | `200` | `xlsx` rows kept per sheet |

Example:

```yaml
- id: paperclip
  config:
    enabled: true
    maxBytes: 67108864
    uploadDir: ""
    allowedExtensions: []
    readLimit: 2000
    maxFileBytes: 67108864
    sheetRowLimit: 200
```

## Usage

**Upload**: Click 📎 to pick files. If needed, click ▴ to expand the list above the input; × removes a file. Type a message and Send — the list clears and paths are sent with the message.

**Read**: The model calls `read_document({ file_path, format: "auto", offset: 1, limit: 2000 })`.

## Security

- Only loopback `Host`, same-origin `Origin`, `Sec-Fetch-Site` check; only `POST` / `DELETE`.
- Byte cap checked twice, filename sanitized, `DELETE` confined to `uploadDir`.
- Default dir `~/.dsh/uploads/paperclip`, content-addressed and deduped.

## Known Limitations

- Pending list is in-memory; reload clears it (files remain).
- No GC — only × deletes.
- `pdf / docx / xlsx` need optional deps (`pnpm add pdf-parse mammoth xlsx` inside the plugin directory); text formats work without them.

## License

[MIT](LICENSE)