dsh-visual
Interactive cards inside a DeepSeek Harness conversation. The model publishes a self-contained HTML card (or a draggable flowchart), the tool blocks until the user submits, and the user's click, comments, form fields and card state come back as the tool result.
No assistant text, no chat message, no artifact preview — a real card in the message stream.
dsh-visual card
Features
- Blocking, not fire-and-forget.
visual stays pending until the user submits, so the answer arrives as the tool result and the agent continues in the same turn.
- Scriptable cards. Inline
<script> runs per card through a small bridge (dshVisual.root, dshVisual.setState), so cards can toggle, validate and prefill themselves.
- Structured answers. Buttons (
data-visual-action), inputs (data-visual-field), comments and card state are merged into one JSON answer.
- Comments with pins. Right-click any element to leave a comment; the answer carries the element's selector and label so the model knows exactly what each note is about.
- Flow editor. Pass a
flow graph instead of HTML: drag nodes, double-click to rename, connect, delete, then hand the edited graph back.
- Parallel safe. Several cards in one turn each get their own bridge and state; nothing leaks between them.
- Cancellable and time-bounded.
timeoutMs and a stop button turn the card read-only instead of hanging forever.
Requirements
- DeepSeek Harness 0.1.0-rc.1 and newer, below 0.3 (prerelease builds included)
- Node.js 20 or newer
Install
dsh plugin --profile desktop add dsh-visual
Restart DeepSeek Harness once so the host half loads. After that, changes to lib/client.js only need a page refresh (⌘R).
For local development, link the directory instead:
dsh plugin --profile desktop add /path/to/dsh-visual
dsh plugin --profile desktop remove dsh-visual # uninstall
Quick start
Ask for a card in plain language:
用 visual 发一张发布确认卡，让我选版本并留一句备注
The model calls the tool roughly like this:
{
"title": "发布确认",
"height": 360,
"html": "<h3>发 0.1.1 到 npm？</h3><textarea data-visual-field=\"note\"></textarea><button data-visual-action=\"approve\">发</button><button data-visual-action=\"hold\">先别发</button>",
"actions": [{ "id": "approve", "label": "发" }, { "id": "hold", "label": "先别发" }],
"timeoutMs": 600000
}
When the user clicks, the tool returns one answer object:
{
"action": "approve",
"payload": { "fields": { "note": "记得打 tag" } },
"state": { "checks": ["install"] },
"comments": [{ "selector": "h3", "label": "h3", "text": "标题再短一点" }]
}
Parameters
| Parameter | Type | Description |
|---|
title | string | Card header title. |
html | string | Complete, self-contained HTML document. Styles are scoped; scripts run per card. |
flow | object | Flow graph {nodes, edges} rendered as an editable canvas instead of HTML. |
data | object | Initial state exposed as dshVisual.data to the card script. |
height | number | Initial card height in px (160–900). The card can resize itself. |
actions | array | Action registry {id, label} for the footer chips and button labels. |
timeoutMs | number | How long to wait for a submit (default 10 min, max 1 h). |
Every field is optional except one of html or flow.
Card protocol
Buttons and fields
data-visual-action="id" — clicking submits that action together with the fields, state and comments.data-visual-field="name" — read from the card on submit and returned under answer.payload.fields.- The footer always shows a neutral 交还 button (
answer.action = "done"). It never implies approval: review cards should carry an explicit approve/revise action of their own.
Scripts and state
<script>
(function (dshVisual) {
var state = Object.assign({ on: false }, dshVisual.data || {})
dshVisual.root.querySelector('.toggle').addEventListener('click', function () {
state.on = !state.on
this.textContent = state.on ? '开' : '关'
dshVisual.setState(state) // returned as answer.state
})
})(dshVisual)
</script>
Each card is compiled as new Function('dshVisual', source)(bridge), so parallel cards cannot see each other's state.
Comments
Right-click any element inside the card, type a note, and it is pinned with a number. The answer carries them in answer.comments as { selector, label, text }.
Timeout and cancel
When timeoutMs elapses the call returns action: "timeout"; stopping the turn returns action: "cancelled". In both cases the card becomes read-only and its footer explains why.
Development
npm run check # syntax of both entries + docs/code consistency guard
npm pack --dry-run # inspect the published file list
The client half is a hand-written module-loader bundle, so no build step is required.
Releasing
Publishing is automatic: pushing a v* tag runs the release workflow, which verifies npm run check, publishes to npm with provenance, and opens a GitHub Release.
npm version patch # or minor / major
git push --follow-tags
Publishing uses npm trusted publishing: the workflow exchanges the GitHub OIDC token for a short-lived npm credential, so no NPM_TOKEN secret is stored. Configure it once under the package's Settings → Trusted publishing on npmjs.com (owner MjxUpUp, repository dsh-visual, workflow publish.yml).
License
MIT © MjxUpUp
