dsh-task-progress
长时间运行的 DSH 任务的实时进度：脚本将结构化进度报告到每个会话的目录中，Web UI 会在浮动叠加层和右侧边栏标签页中显示这些进度。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:chen8923/dsh-task-progress#fa4417e23ef97dcf20b025dc0b279caddf035a92Task Progress 以 dsh-task-progress 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →Live progress for long-running tasks in DeepSeek Harness. A script reports structured progress to a file; the Web UI shows it in a floating overlay and a right-sidebar tab — no polling the agent, no waiting for the command to finish.
Version 0.1.0 · MIT · 中文 · Changelog
┌──────────────────────────────────────┐
│ ⟳ 2 tasks running │ ← floating pill, appears only while
└──────────────────────────────────────┘ something is running
┌──────────────────────────────────────┐
│ Long-task progress 2 running · 1│
│ ██████████░░░░░░░░░░ 52% build │ ← click the pill, or open the
│ linking objects │ "Task progress" sidebar tab
│ 12m04s elapsed · 5/9 files · ~11m left│
└──────────────────────────────────────┘
DSH's pwsh/bash tools are not streaming: a foreground command's output
appears only when it finishes, and a background job's output lives behind the
model's job_output cursor. The session-header job list shows status, but not a
single line of output. So a ten-minute build is a black box to the human watching
the GUI.
This plugin gives long tasks a second, purpose-built channel that is theirs to write and the human's to read.
# from npm (once published)
dsh plugin --profile web add dsh-task-progress
# from a git checkout
dsh plugin --profile web add github:chen8923/dsh-task-progress
# from a local checkout of this repository (see Development)
./tools/rebuild.ps1 -Profile web -Checkout <path-to-dsh-checkout>
DSH mounts a profile bundle at startup, so restart DSH afterwards. The plugin
requires the Web profile (webServer, connection, shellEnv, and the right
sidebar); in a composition without them it stays unloaded and changes nothing.
The git install is one command with nothing to allow: the built plugin is committed, so there is no build step for pnpm to gate.
Inside a DSH shell call the plugin hands the script its directory:
# PowerShell — one append per event
$line = '{"v":1,"task":"build","state":"running","pct":42,"msg":"linking"}'
[System.IO.File]::AppendAllText(
(Join-Path $env:DSH_PROGRESS_DIR 'build.jsonl'), $line + "`n",
[System.Text.UTF8Encoding]::new($false))
# bash
printf '{"v":1,"task":"build","pct":42,"msg":"linking"}\n' >> "$DSH_PROGRESS_DIR/build.jsonl"
# Python (any language works — it is just a file)
import json, os
path = os.path.join(os.environ["DSH_PROGRESS_DIR"], "build.jsonl")
with open(path, "a", encoding="utf-8") as handle:
handle.write(json.dumps({"v": 1, "task": "build", "pct": 42, "msg": "linking"}) + "\n")
Or let the bundled helper do the quoting:
node "$DSH_PROGRESS_CLI" emit --task build --pct 42 --msg "linking"
node "$DSH_PROGRESS_CLI" done --task build --msg "shipped"
node "$DSH_PROGRESS_CLI" list # print what the directory currently says
Try it with no setup at all:
pwsh ./examples/simulate.ps1 -Task demo -Steps 30 -DelayMs 500
Then open the Task progress tab in the right sidebar (or click the floating pill once it appears).
Installing the plugin is enough for the agent to know the convention: the host
half contributes a short section to the system prompt, right where the
background-jobs guidance already is, so the model arranges progress reporting for
long commands on its own. There is nothing to configure and no AGENTS.md edit —
a feature that only works after you edit your own instructions is not one you can
install.
If you want it stronger, or you run a composition without that prompt seam, the
same instruction can live in your workspace AGENTS.md:
## Long-running tasks
For any command expected to run longer than ~30s, report progress from inside the
script to `$DSH_PROGRESS_DIR/<task>.jsonl` (one JSON line per event, see the
dsh-task-progress protocol), or use
`node "$env:DSH_PROGRESS_CLI" emit --task <id> --pct N --msg "..."`.
Never read the progress file back — it is for the human.
The panel shows what scripts report; it never reads a running job's output. A background job started by a script that does not report is therefore invisible here, and existing jobs cannot be retrofitted — but the sidebar tab says so instead of looking broken: with jobs live and nothing reported, its empty state names the count.
The plugin registers one settings namespace, so its knobs are editable where every plugin's are: Settings → Plugins → Plugin configuration → Task progress.
| Field | Default | Meaning |
|---|---|---|
| Scan interval (ms) | 1000 | How often the Host half re-reads changed progress files. |
| Poll interval (ms) | 2000 | How often the browser asks for progress. |
| Keep finished for (ms) | 1800000 | How long a finished task stays listed. |
| Messages per task | 30 | Recent messages kept per task. |
| Max tasks | 200 | Cap on tasks in one state document. |
| File tail bytes | 262144 | Bytes read from the tail of one progress file. |
| Extra roots | – | Absolute paths whose .dsh-progress is scanned too. |
Saving writes the namespace's user layer into $DSH_HOME/settings.yaml; pressing
Reset (or emptying a field) removes the override, so the value falls back to
the plugin row's config and then to the schema default. Changes apply live: a
new scan interval re-arms the Host loops on their next tick, and the state
document's pollMs follows the value the browser should use.
dirName is deliberately absent from the panel — it is part of every path
already written, so it stays a composition-level setting on the plugin row.
Three layers, each independently replaceable — the point is that neither a producer nor the UI knows about the other, and neither knows about DSH internals.
| Layer | What it is | Why it is shaped that way |
|---|---|---|
Protocol (docs/PROTOCOL.md) | Append-only JSONL, one file per task | Any language, no IPC, no ports, no auth, survives restarts. Works with the plugin uninstalled — the files are just files. |
| Host half | ctx.shellEnv contributor + directory poll + one HTTP route + a system-prompt section | Uses only public DSH seams (webServer, connection, shellEnv, settings, systemPrompt), and never touches the job registry. |
| Browser half | One polling store, two panels (shell.overlay + a sidebar tab), and a settings card | The panels read the same snapshot and the card reads its own namespace scope, so adding or removing a surface never touches the data path. |
Why the plugin does not read job output. ctx.jobs.read() consumes a
single-consumer cursor that belongs to the model's job_output tool; a browser
path reading it would silently steal bytes the model can then never see (DSH
pins that as a tested invariant). Progress here is therefore something the
script chooses to report, which is what makes this plugin safe to install
alongside anything else.
Why polling instead of push. The data is a couple of kilobytes of JSON on localhost, and a poll loop is the one design that cannot desynchronize: every reader sees the same last-wins document, a missed tick costs one interval, and there is no reconnect logic to get wrong. The interval comes from the Host half's configuration.
Zero dependencies. The host half imports Node built-ins only; the browser
half bundles everything it owns and treats react as a platform external. That
extends to the settings schema: ctx.settings.register takes a schemastery
schema, and this plugin supplies a minimal compatible node — callable for
resolution, toJSON() in schemastery's reference-graph form, and walkable by the
settings redactor — instead of depending on a package that a profile install
cannot resolve. Its own browser card passes a decoder so it never has to
rehydrate a schema envelope at all.
job_kill (a human-initiated
interrupt needs a delivery-semantics decision this plugin does not own).npm test # 38 tests, one process (works in restricted sandboxes)
npm run test:runner # the same suite through node --test
npm run build # requires tsdown
Source layout:
src/protocol.ts the shared contract (pure, bundled into both halves)
src/host/ settings namespace, store, shell-environment contributor, HTTP route, prompt section, entry
src/client/ polling store, formatting, settings form, React components, slots, styles
bin/dsh-progress.mjs the dependency-free producer CLI
docs/PROTOCOL.md the file contract and every configuration key
test/ protocol, store, formatting, host-wiring, settings, prompt, and release suites
tools/ test entry and the build/pack/install script
lib/ is committed, and that is load-bearing. A git-hosted package that has
to build needs pnpm's build-script allowlist, whose key contains the exact commit
— so the install would take two steps and the second one would change on every
push. Shipping the build makes it one command, at the cost of discipline: after
any source change, run npm run build and commit lib/ in the same commit.
test/bundle.test.ts fails if the build is missing, is not a loader bundle, or
no longer carries what the sources define. prepublishOnly still builds for
npm publish. The suites run on Node 22.18+ (they execute the TypeScript sources
directly through type stripping), while the plugin itself runs on Node 20+.
npm test # 69 checks, one process
npm publish # builds first, then publishes
git tag v0.1.0 && git push --tags
test/release.test.ts fails if the version in package.json is not also stated
in both READMEs and the changelog, if a documented example is missing from
files, or if the repository links disagree with the install instructions — so
the four places a version or a URL appears cannot drift apart.
MIT