dsh-turn-tools

Readme

# dsh-turn-tools

[English](#english) | [中文](#中文)

## English

A [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) web plugin that adds two tools to the chat interface:

1. **Per-turn deliverable buttons** — when an agent turn produces output files, buttons for each file are rendered at the end of that turn. Clicking a button opens the file with the OS default application (via the harness `host.openPath` API).
2. **Turn navigator dot rail** — a floating dot rail on the right side of the chat; one dot per conversation turn. Clicking a dot scrolls to that turn.

### Requirements

- DeepSeek Harness (`@deepseek-ai/dsh`) with the `web` profile.

### Install

Via `dsh plugin add` (npm package or git URL), or install manually:

1. Copy this repo into `$DSH_HOME/profiles/web/node_modules/dsh-turn-tools/`.
2. Append the contents of `cordis.patch.yml` to `$DSH_HOME/profiles/web/cordis.patch.yml`.
3. Restart dsh.

### How it works

- `lib/client.js` registers two slots via the `slots` service:
  - `conversation.chat.turnTail` — reads `turn.data.get('deliverables')` and renders one button per deliverable.
  - `shell.overlay` — a `MutationObserver` scans `[data-dsh-turn-anchor]` elements to build the dot rail.
- `exports.inject = ['slots']` (cordis service names); `connection` is fetched lazily via `ctx.get('connection')` at click time.

### FAQ

**Buttons / dots don't appear after installing.**

- Restart dsh after copying the files — there is no hot reload.
- Check `window.__DSH_BOOT__.entries` in the browser console: the `dsh-turn-tools` entry should be active, with no `waiting for services` note.
- Deliverable buttons only render on turns that actually produced output files.

**How do I uninstall?**

- Delete `$DSH_HOME/profiles/web/node_modules/dsh-turn-tools/`, remove the `turn-tools` insert entry from `$DSH_HOME/profiles/web/cordis.patch.yml`, and restart dsh.

## 中文

一个 DeepSeek Harness（dsh）web 插件，为聊天界面增加两个工具：

1. **每轮产出文件按钮** — 当某轮对话产生输出文件时，在该轮末尾为每个文件渲染一个按钮，点击后调用系统默认程序打开（通过 harness 的 `host.openPath` API）。
2. **轮次导航圆点栏** — 聊天区右侧的浮动圆点栏，每轮对话一个圆点，点击圆点滚动跳转到对应轮次。

### 前置要求

- DeepSeek Harness（`@deepseek-ai/dsh`），使用 `web` profile。

### 安装

可通过 `dsh plugin add` 安装（npm 包或 git URL），或手动安装：

1. 将本仓库拷贝到 `$DSH_HOME/profiles/web/node_modules/dsh-turn-tools/`。
2. 将 `cordis.patch.yml` 的内容追加到 `$DSH_HOME/profiles/web/cordis.patch.yml`。
3. 重启 dsh。

### 实现说明

- `lib/client.js` 通过 `slots` 服务注册两个 slot：
  - `conversation.chat.turnTail` — 读取 `turn.data.get('deliverables')`，为每个产出渲染一个按钮。
  - `shell.overlay` — 用 `MutationObserver` 扫描 `[data-dsh-turn-anchor]` 元素构建圆点栏。
- `exports.inject = ['slots']`（cordis 服务名）；`connection` 在点击时通过 `ctx.get('connection')` 延迟获取。

### 常见问题

**安装后按钮 / 圆点没有出现？**

- 拷贝文件后需要重启 dsh——没有热加载。
- 在浏览器 console 检查 `window.__DSH_BOOT__.entries`：`dsh-turn-tools` 条目应为 active，且没有 `waiting for services` 提示。
- 产出文件按钮只在该轮确实产生了输出文件时才会渲染。

**如何卸载？**

- 删除 `$DSH_HOME/profiles/web/node_modules/dsh-turn-tools/`，从 `$DSH_HOME/profiles/web/cordis.patch.yml` 中移除 `turn-tools` 的 insert 条目，然后重启 dsh。

## License

MIT