dsh-audio-cue
DeepSeek Harness 思考或工作时播放环境音频，并在需要你时发出提示音。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue#3e3058f397eced807cf8b85044e24be6a9dbf525
Audio Cue 以 dsh-audio-cue 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Ambient audio while DeepSeek Harness is thinking or working — and a chime the moment it needs you.
中文说明 · Install · The panel · How it decides · Troubleshooting
Install straight from GitHub:
dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue
Pin a release instead of tracking the default branch:
dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue#v0.1.0
Once the package is on npm, the short form works too:
dsh plugin --profile web add dsh-audio-cue
Then restart the profile, so the host mounts the new plugin row.
In the desktop app the profile lives in the app's own harness home, so point the CLI at it first:
$env:DSH_HOME = "$env:APPDATA\dsh-desktop\harness"
dsh plugin --profile web add dsh-audio-cue
Uninstall:
dsh plugin --profile web remove dsh-audio-cue
If you would rather not run any of this by hand, paste the following to the agent you are already talking to. It is written to fail loudly rather than report success it did not verify, because every step below has a quiet failure mode.
Install the DeepSeek Harness plugin `dsh-audio-cue` into the `web` profile, then
verify it. Do not publish anything and do not modify the plugin's repository.
Two things will send you down the wrong path unless you check them first:
1. DSH_HOME. A profile lives at `$DSH_HOME/profiles/<name>`, and the default home
is `~/.dsh`. The desktop app uses its own (on Windows,
`%APPDATA%\dsh-desktop\harness`). Installing into the wrong home quietly
creates a second, empty profile that has no other plugins in it, so work out
which home the running harness uses first, and set DSH_HOME for every command.
2. The CLI. `dsh` is not necessarily on PATH: the desktop app ships it inside its
application resources, at
`…/resources/app/node_modules/@deepseek-ai/dsh/lib/bin.js`, runnable with the
Node bundled beside it at `…/resources/app/node_modules/node/bin/node`. Note
that `dsh plugin` forwards its arguments to pnpm, so pnpm must be on PATH too.
Then:
1. Tell me which harness home you found and which profile you will install into.
2. Run: dsh plugin --profile web add dsh-audio-cue
3. Show me that the profile's package.json now lists `dsh-audio-cue` in both
`dependencies` and `dsh.profile.bundles`.
4. Ask me to restart the host, and stop there until I confirm: the plugin row is
only mounted when the host starts, and restarting it would end your own
session, so it is my job, not yours.
5. After the restart, verify and show the actual output of each check:
- GET http://127.0.0.1:<port>/dsh-audio-cue/state.json returns 200 with JSON
containing `working` and `waiting`. <port> is the one the GUI is served on;
on the desktop the current URL (including its token) is in the host log
under `%APPDATA%\dsh-desktop\logs\harness.log`, on the `dsh web:` line.
- The page HTML contains `<script src="/dsh-audio-cue/client.js">`.
- `$DSH_HOME/dsh-audio-cue/settings.json` exists after the plugin has been used
once.
6. Tell me plainly which checks passed and which did not, quoting the responses.
If something failed, say so instead of summarising it as done.
To uninstall: dsh plugin --profile web remove dsh-audio-cue, then restart the host
again.
Click the button beside the sidebar.
┌────────────────────────────────────────┐
│ dsh-audio-cue × │
│ 启用 [🔊 已开启] │
│ 音量 [======●=====] 65% │
│ 播放方式 [继续播放 ▾] │
│ 工作中音效 [let me go（默认）▾] ▶ 导入…│
│ 需审批音效 [默认 ▾] ▶ 导入…│
│ │
│ 已导入 │
│ my-loop.mp3 1.2 MB ▶ 删除 │
└────────────────────────────────────────┘
| Control | What it does |
|---|---|
| 启用 | Mutes everything. The corner icon follows it. |
| 音量 | One volume for both the loop and the chime. |
| 播放方式 | 继续播放 picks up where the track stopped. 从头开始 rewinds it whenever the loop starts again. |
| 工作中音效 | 无 (silent), one of the shipped cues, or one of your imports. |
| 需审批音效 | The same choice for the chime. |
| 导入… | Uploads a file for that cue and selects it. |
| ▶ | Auditions the cue. The loop is auditioned for 3 seconds, the chime plays once. |
| 删除 | Removes an import and resets any cue that used it. |
The volume applies to the chime as well, so a volume of 0 is silent — the panel says so by showing the icon muted, not just turned down.
On the host, not in the browser:
$DSH_HOME/dsh-audio-cue/
settings.json mute, volume, playback mode, and which cue each slot uses
uploads/ files you imported, plus their index
So the configuration follows the harness home: it survives a browser cache wipe, a different browser, and a restart. A session pointed at a different home has its own store, and no plugin.
The settings file is written through a temporary file and a rename, so a crash cannot leave it half-written. A corrupt or unreadable one falls back to defaults instead of refusing to load, and a cue whose file is gone is repaired back to the default rather than left silent with no explanation.
For scripting, and for when the panel is not enough:
__DSH_AUDIO_CUE__.state() // { enabled, volume, last, legacy }
__DSH_AUDIO_CUE__.toggle() // returns the new on/off state
__DSH_AUDIO_CUE__.setVolume(0.4)
__DSH_AUDIO_CUE__.setEnabled(false) // false = muted
__DSH_AUDIO_CUE__.open() // open or close the panel
__DSH_AUDIO_CUE__.settings() // the last payload from the host
__DSH_AUDIO_CUE__.refresh() // re-read the store
__DSH_AUDIO_CUE__.history() // the last state changes, and what each one did
__DSH_AUDIO_CUE__.setPosition(520) // nudge the button; resetPosition() undoes it
The host subscribes to the session event log, checks it against the agent registry, and reduces the result to one number:
| Session event | Effect |
|---|---|
turn/start | the session becomes working |
turn/end | the session goes idle, and any open question is cleared |
approval/asked | the session becomes waiting for you |
approval/decided | back to working |
tool/call that is asking you something | waiting for you |
tool/result that answers it | back to working |
assistant/chunk, assistant/message, tool/call, tool/result, step/start, step/end | working, if that session was not already open |
The result is published as a Server-Sent Events stream at
/dsh-audio-cue/events, with a full snapshot on connect and a snapshot every 15
seconds; the browser half turns it into sound:
working === 0 -> silence
working > 0, waiting === 0 -> ambient loop, faded in
waiting > 0 -> silence + one chime per transition
A few properties fall out of that:
turn/end at all, and a listener that follows only the log then
believes the session is busy forever: the sound plays until the next turn ends,
or indefinitely when there is no next turn. Whether a session is mid-turn is
therefore asked of the agent registry — the same source the product's own
session list uses — with the log as the fallback. A poll every five seconds
publishes a change that no event announced.ask_user_question, or any tool whose arguments
carry questions), and the answer is matched back through the result's
sourceEventSeqs so a parallel tool result cannot clear it early.The state is also available as plain JSON, which is the quickest way to debug it:
curl http://127.0.0.1:<port>/dsh-audio-cue/state.json
# {"bootId":"k3f9a1","seq":7,"working":1,"waiting":0,"sessions":[{"id":"27410d27","waiting":false}]}
Use the port your GUI is served on — it is in DSH_WEB_URL, and it changes
between launches. sessions is the breakdown behind the counts: work in any
session keeps the sound on, so it is what answers "why is it still playing?"
Import a file in the panel, or replace the built-in cues in assets/ and restart
the host. Imports are copied into the store, so the original can move or be
deleted afterwards.
| Accepted formats | mp3, ogg/oga/opus, wav, m4a, aac, flac, webm |
| Size limit | 8 MB per file |
| How the type is decided | the Content-Type header, or the file name when the browser reports an opaque type |
The shipped cues are real choices in the panel, not one option and one hidden fallback:
let me go — the default working cue. Third-party work, bundled with the
author's permission: see CREDITS.md. It ships as AAC (.m4a)
because every browser decodes it, Safari included.let me go SSR — a 20-second clip from the same work, bundled at the
author's request. Short enough to loop without your noticing where it starts.ffmpeg (the command is in CHANGELOG.md).Whatever a slot is set to still has to be decodable: the pad ships in both Ogg and MP3 and sits last in that order, so a browser that cannot play AAC ends up with it rather than a 404.
A loop that is not seamless will click at every repeat. The synthesized placeholder is measured at a wrap discontinuity of about −96 dBFS; a song will not be, which is what the 从头开始 / 继续播放 choice is about.
Everything the plugin serves lives under /dsh-audio-cue/. Useful when
diagnosing:
| Route | Purpose |
|---|---|
GET /events | the state stream (SSE) |
GET /state.json | the same snapshot as JSON |
GET /api/settings | the store, in one payload |
PUT /api/settings | replace it (validated) |
POST /api/uploads?slot= | store an import; the body is the raw audio and x-file-name carries its name, so there is no multipart parser |
DELETE /api/uploads/<id> | forget an import, and reset every cue that used it |
GET /uploads/<id> | one import, for the panel's previews |
GET /audio/<slot> | what a cue resolves to: 404 when off, the import, or the built-in |
GET /asset/<name> | the shipped files |
GET /client.js | the browser half |
Audio answers are cached for a year when the URL pins the bytes: /audio/<slot>?v=…
carries the host's boot id and the file the slot resolved to, and /uploads/<id>
is addressed by an id that is never reused. Unversioned requests, and the
built-in assets an author may replace in place, are never cached.
No sound at all. A browser refuses to start audio before a user gesture: click anywhere once (opening the panel counts) and the loop starts. The desktop app loads its window over HTTP from the local server and normally allows sound outright; a plain browser tab is the strict case. Also check the volume — 0 is silent, and the panel will show the icon muted.
No button on the page. The browser half is injected into the index; if it is
missing, check the profile's dsh.profile.bundles really lists dsh-audio-cue,
then restart the host. (Plugins are only mounted at host start.)
It worked, then the tab went dead. The host restarted: both the port and the token change on every launch, so an open tab and a bookmark both stop working. The current URL is in the host log:
Select-String -Path "$env:APPDATA\dsh-desktop\logs\harness.log" -Pattern 'dsh web:' | Select-Object -Last 1
The plugin is missing from a browser session, along with every other plugin.
That session is running against a different harness home — most often a dsh web
started without DSH_HOME, which falls back to ~/.dsh and initialises a fresh
profile with no plugins at all.
Two audio streams at once. The page is open in more than one tab; each plays independently. Mute one.
It never stops playing. Check state.json: if working stays above 0 while
nothing is running, please open an issue with that response body.
The plugin's routes are not authenticated, matching the rest of the plugin
ecosystem here. With the default loopback bind that is local-only. If the profile
binds 0.0.0.0, these routes are reachable from the network — and
POST /api/uploads writes files under $DSH_HOME — so treat a LAN bind as
exposing them.
git clone https://github.com/Goothe13-gugu/dsh-audio-cue
cd dsh-audio-cue
dsh plugin --profile web add link:$PWD # a link: install needs no publish
npm test
Two halves, with different iteration costs:
| File | A change needs | |
|---|---|---|
| host | lib/index.js | a host restart (the module is loaded at mount) |
| browser | client/audio-cue.js | only a page refresh (served no-store from disk) |
lib/index.js host half: event state machine, the store, routes, injection
client/audio-cue.js browser half: state -> sound, and the panel (no build step)
assets/ the shipped audio
test/smoke.test.mjs host half, against a fake Cordis context
test/client-load.test.mjs browser half, executed in a DOM stand-in
cordis.patch.yml the mount declaration
npm test needs no dependencies and no harness: the host suite mounts the plugin
into a fake context and talks to its routes, while the browser suite actually
runs the client script against a small DOM so that a syntax error or a broken
mount fails the build rather than the user.
Verified against DeepSeek Harness 0.1.2-alpha.1 (DSH Desktop 0.7.1). The
plugin depends on the webServer service and on a handful of session event
names; it imports nothing from the harness, so it is not tied to a release line.
The desktop window loads the harness page over HTTP from the local server, so the event stream and the asset requests take the same path in the desktop app and in a browser tab.
Issues and pull requests are welcome. Please run npm test before opening a pull
request; the suites are the reason the last two regressions were caught before
release rather than after.
MIT for the code. The bundled track is third-party and used with permission — see CREDITS.md.