dsh-insight-dock
English | 中文
An insight dock for the DSH Web GUI.
While an agent is focused on a task it can park a short, strictly-bounded side
observation — "wait, that other thing could…" — without derailing what it is
doing. The note shows up above the composer, and you decide later whether to hear
it out.
The point is the context anchor. Every note remembers the session sequence it
was created at, so insight_load can read the real conversation log back from
that moment. That read comes from the durable session log, which is why a note
still works after the agent's own context has been compacted away.
Install
dsh plugin --profile <profile> add dsh-insight-dock
dsh plugin is a thin wrapper over pnpm, run inside the profile directory. It
reconciles dsh.profile.bundles against the installed packages, sees the
dsh.bundle.patch declaration in this package, and appends it to the bundle
stack; the profile boot then merges cordis.patch.yml — a single insert of the
plugin row. No profile file has to be edited by hand.
The bundle stack is read once at boot, so restart dsh before the plugin
appears.
Installing from a local checkout instead
dsh plugin --profile <profile> add link:/absolute/path/to/dsh-insight
Mind the realpath trap: Node resolves a symlinked package to its real location
before resolving its imports, so a linked checkout can only find @deepseek-ai/*
if it has its own node_modules
(ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/dsh-tools'). A
registry install materializes the package inside the profile and has no such
problem.
What you get
Above the composer, a single-line dock — 💡 3 条见解 — that expands to the
current note; the arrows step through the rest.
| Action | Effect |
|---|
| 说来听听 | Asks the agent to talk through this note, from the log window it anchored. |
| 关闭 | Removes the note. |
| 关闭并告诉 agent 为什么 | Removes the note and injects a one-line notice carrying your reason. |
In Settings, a 见解 section: enable/disable, prompt strength (below), the
concurrent-open cap (1–50), and the lifetime in minutes (1–1440, default 5).
Prompt strength
The dock only works if the agent thinks to use it, and that is governed almost
entirely by one ambient line in its context. The 提示强度 setting picks which
line, and when:
| Level | Injected when | Content |
|---|
| 关闭 | never — a close-with-reason notice still gets through | — |
| 弱 | only while insights are open | the open-insight reminder |
| 中 | always | a positive criterion: real, currently unactionable, lost if not written down |
| 强 | always | that criterion plus a standing "scan for one before you start" |
The four levels are one ordinal axis; the table's last two columns are what each
point on it actually does.
The default is 弱, which preserves the historical behaviour — and it is
structurally unable to produce a first insight, because the reminder it gates
on does not exist until one has already been recorded. 中 and 强 inject with zero
insights open, which is the only way a first one can appear.
Every earlier version of this text was a list of prohibitions — not a to-do,
not an escape hatch for deferring work, if you can do it now, do it now. The
measured effect was abstention. Across 94 recorded sessions and 625 turns, the
only insights ever recorded were the ones created while building this plugin:
17 calls, every one of them a test fixture, and zero in the other 93 sessions.
A description made entirely of reasons not to act produces exactly that. 中 and 强
state a positive criterion instead.
Two faces
Host — exports "." → lib/index.js:
| Surface | What it does |
|---|
insight_add | Records a note. Title ≤ 60, reason ≤ 200, a required why_not_now ≤ 120, one note per turn, ≤ 5 open. |
insight_list | Lists this session's notes. |
insight_load | Reads the log window around the note's anchor — and consumes the note. |
insight_withdraw | Lets the agent retract its own note. |
| prompt context | One ambient line while notes are open: these are not a to-do list, and a note that turns out to belong to the current task has to be done, not filed. |
/insight/api/<op> | The browser half's channel. |
Client — exports "./client" → lib/client.js, served at
/plugins/dsh-insight-dock/client.js: the dock in conversation.input.dock
(order 30), and the settings page in settings.section.
Lifecycle
Every ending deletes the record. There is no archive.
| Transition | Trigger | Result |
|---|
active → gone | the lifetime elapsed and nobody asked to hear it | deleted |
active → heard | you click 说来听听 | the host steers one message into the agent |
heard → gone | the agent reads it via insight_load | its context has been handed over, so the note is removed |
heard → gone | the agent never got there (abandoned or failed turn) | deleted once the lifetime elapses from the moment it was heard |
active / heard → gone | the agent withdraws its own note | deleted |
active / heard → gone | you close it | deleted — a close with a reason still injects its one-line notice first |
A heard note therefore normally lives for seconds, not minutes: insight_load
deletes it at the instant it hands the content over. The heardAt lifetime is
only the backstop that keeps an unanswered note from sitting in the dock forever.
Notes live in memory only. Nothing about a note is written to disk. With a
lifetime measured in minutes that costs almost nothing — a restart outlives every
note anyway, so persistence would only ever preserve an empty set — and it
removes a whole class of failure: a silently failed write, serial bookkeeping,
and the fork / workspace / storage-layer caveats a side-car would have brought.
Known limitations
Measured, not guessed.
-
The UI text is Chinese. Every user-facing string (说来听听,
关闭并告诉 agent 为什么, the settings labels) and every tool description is a
literal Chinese string. There is no locale binding, so an English-locale
session still sees Chinese everywhere.
-
Every ending deletes; nothing is archived. There is no "已归档" row and no
record behind it. Expiry in particular is irreversible: shortening the
lifetime destroys notes outright, and lengthening it again cannot bring them
back.
-
A restart clears the dock. Notes are held in memory, so they do not
survive a dsh restart, and a forked session does not inherit them. At the
default five-minute lifetime this is invisible; it only bites if you set a long
lifetime and restart with notes still open.
Making them log-resident — session.append of a log-only, non-surface event
plus sessionProjections.register — would make them fork-inheriting and
checkpointed. That needs the event type registered through TypeScript module
augmentation, which a hand-written lib/*.js package cannot do. Deliberately
not paid for: with a time-based lifetime, persistence buys very little.
-
Settings are persisted (~/.dsh/insight-settings.json), on purpose — a
lifetime or cap that reset on every restart would be useless. They are a
side-car rather than a registered ctx.settings namespace.
-
The settings-nav icon is the shell's fallback gear. A settings.section
registration projects only id, order and label; the nav glyph comes from
a closed list of built-in ids (models / agent-presets / plugins, else a
gear), so a plugin cannot supply one.
-
Icons degrade. The dock asks
@deepseek-ai/dsh-client-ui-primitives for IconLightOutline16,
IconChevronLeftOutline14 and IconChevronRightOutline14, and falls back to
hand-drawn 16px inline SVG if that require fails. A missing baseline entry is
therefore a cosmetic loss, not a dead panel.
Notification behaviour
Closing a note with a reason makes the host inject a one-line notice message
into the agent — deliberately without waking the driver, so the agent cannot
reply to it. Closing without a reason notifies nobody.
Development
lib/index.js and lib/client.js are the shipped artifacts and are
hand-written; there is no build step. lib/client.js is a lazy-CJS bundle in the
shape the client module loader expects:
window.__ModuleLoader__.load({
id: "dsh-insight-dock", // must equal the package.json name
factory: (require) => { /* … */ return module.exports },
})
node --check proves syntax only. Every real bug found during development — a
join() separator emitted as content, heard notes escaping the lifetime, and a
stateful helper called as a plain function (which charged its useState to the
caller, changed the hook count between renders, and made React discard the whole
settings section) — passed the syntax check, and the first two passed a stubbed
smoke test as well. They only appeared once the plugin was actually run.
One regression test covers the failure a syntax check cannot see:
node test/hook-order.mjs lib/client.js
It renders the settings section twice — once while its config is still loading,
once loaded — and asserts the root component consumes the same number of hooks
both times. It fails on the shape above, so it is a test rather than a
decoration: turning the fix back into a plain function call makes it exit 1.
License
MIT
