dsh-doc-rail

Readme

# dsh-doc-rail

A resizable right-side **document rail** for the DeepSeek Harness **web GUI**
(`dsh web`). It shows a Markdown or plain-text file beside your conversation —
the natural home for a session handover note — with:

- **Light (warm paper) and deep-navy dark themes**, switchable in the panel;
- **drag-to-resize width** (double-click the left edge to reset to 400 px);
- **open any local `.md` / `.txt` path** (paste a path, or pick from Recent);
- **auto-sync**: the file is re-read every 4 s, so saves show up by themselves;
- appearance, width, last-opened file and recent history are kept in process
  memory (survive page refreshes; reset on restart, like the plugin itself).

The panel mounts in the frame-wide `shell.overlay` seat — additive only, it
never replaces shipped UI.

## Screenshots

Sample-content previews (no real documents), light and dark themes:

| Light theme | Dark theme |
| --- | --- |
| ![dsh-doc-rail light theme](assets/preview-light.png) | ![dsh-doc-rail dark theme](assets/preview-dark.png) |

## Requirements

- DeepSeek Harness running from a source checkout or release that composes the
  **web GUI** profile (`dsh web`), Node.js **>= 24** (the node half is plain
  TypeScript run directly; the browser half ships pre-built as `lib/client.js`).
- The plugin needs the `webServer` service, so it only activates under the web
  profile. Installed into a CLI-only profile it stays inert on purpose.

> Compatibility note: `dsh-doc-rail` targets the web client slot/layout APIs as
> of this package's development snapshot. If you use a published `dsh` release,
> prefer a matching dsh-doc-rail version (see releases) and verify the panel
> appears once after install.

## Install

From the registry (once published):

```sh
dsh plugin --profile web add dsh-doc-rail
```

From a local checkout or tarball instead:

```sh
dsh plugin --profile web add /path/to/dsh-doc-rail
# or
dsh plugin --profile web add ./dsh-doc-rail-0.1.0.tgz
```

Restart the web GUI (`dsh web`) — the page then boots with the rail on the
right. Click ✕ to collapse it; the small **📄 文档面板** pill reopens it.

## Set a default document (optional)

The panel starts with a path input and no default file, so it is safe to ship
to anyone. To pin your handover note (or any file), override the row config in
the profile's own `cordis.patch.yml`:

```yaml
- replace:
    - id: dsh-doc-rail
      name: dsh-doc-rail
      config:
        defaultPath: 'C:/Users/you/Documents/handover.md'
```

Paths may use `/` or `\\` separators; the file is read as UTF-8 text.

## Usage

1. Paste a full path (`.md`, `.txt`, or any UTF-8 text file) and press Enter,
   or click **打开**.
2. Use **最近** to jump back to an earlier file and **清空输入** to reset the
   field. Files you open are added to the recent list automatically.
3. **浅色 / 深色** switches the palette immediately; the choice is remembered.
4. Drag the thin bar on the panel's left edge to resize; double-click it to
   reset.

## Privacy

Everything is local: the node half reads files inside your own `dsh web`
process and the browser half talks to it over the same-origin JSON routes
`/dsh-doc-rail/api/doc` and `/dsh-doc-rail/api/pref`. No network service, no
telemetry, no path leaves your machine.

## Development

```sh
npm install
npm run typecheck   # tsc --noEmit
npm run bundle      # tsdown → lib/client.js (lazy-CJS module-table factory)
npm run smoke       # structural checks
```

The browser bundle contract is documented in
`packages/client/tsdown.client.ts` of the harness checkout (external packages
must replicate it until the preset ships to npm).

## Layout

```
package.json          # dsh.bundle + dsh.client manifests, exports
cordis.patch.yml      # inserts the plugin row by package name
src/index.ts          # node half: doc + pref JSON routes over ctx.webServer
src/client/index.ts   # browser half: registers shell.overlay
src/client/Rail.tsx   # panel UI (themes, resize, path input, markdown render)
src/client/styles.ts  # injected stylesheet (CSS variables, no CSS pipeline)
scripts/smoke.mjs     # structural smoke check
```

## License

MIT — see [LICENSE](LICENSE).