前言¶

在 DeepSeek Harness（DSH）里用 pwsh 或 bash 跑构建、测试、批量脚本时，有一个很具体的观察问题：前台命令的输出往往要等进程结束才一次性出现；后台任务则把输出留在模型侧的 job_output 游标之后。会话头部的任务列表能看状态，却看不到脚本正在做什么。一条跑十分钟的命令，对盯着 Web 界面的人来说仍是黑盒。

下面介绍社区插件 dsh-task-progress（维护者 chen8923，分类为客户端）。它不给 DSH 增加新的工具，而是让脚本把结构化进度写入工作区文件，Web UI 通过悬浮层、右侧栏「任务进度」tab 和设置页读取并展示——不必轮询 agent，也不必等命令结束。

这是什么¶

dsh-task-progress 当前版本 0.3.0，MIT 许可证，npm 包名与 GitHub 仓库名一致（dsh-task-progress / chen8923/dsh-task-progress）。定位可以概括成：长任务的第二条专用通道——生产者往 JSONL 文件追加事件，宿主进程轮询并暴露状态，浏览器半定时拉取同一份快照，在界面上画进度条、消息、耗时与 ETA 等。

插件依赖 Web profile（宿主侧需要 webServer、connection、shellEnv；浏览器侧需要 slots、locale、sidebarRightTabs）。在缺少这些接缝的组合里，插件保持未加载，对现有行为无影响。构建与验证针对 @deepseek-ai/dsh 0.1.7-rc.1；插件本体要求 Node 20+。

核心功能¶

经过上面的定位，可以把已核实的能力拆成几块：

1. Shell 环境注入：每次带会话的模型 shell 调用会获得 DSH_PROGRESS_DIR（进度文件目录）；若随包 CLI 可用，还会设置 DSH_PROGRESS_CLI。
2. Web 展示：同一套状态出现在悬浮 overlay（可点击展开）和右侧栏 Task progress / 任务进度 tab；设置页提供扫描间隔、轮询间隔、任务上限等可调项。
3. HTTP 状态端点：同源 GET/HEAD /plugins/task-progress/state，经 DSH 的 connection.requestRejection 围栏，一次只服务当前会话，响应中不含文件系统路径。
4. Job 镜像行：未主动上报的后台任务仍会显示一行（命令标签、运行时长、结束方式等），数据来自 DSH 自带的 job 镜像，不经过本插件路由；没有脚本上报时不会出现虚假的百分比。
5. 模型提示：宿主半追加一段静态系统提示词（紧挨 DSH 后台任务说明）；可选地，后台任务超过 remindAfterMs（默认 30000 ms，0 关闭）仍无上报时，最多发一条提醒。
6. 终态兜底：脚本被 job_kill 等强行终止、无法写入终态时，宿主半会结合 job 注册表推断 killed / failed / 完成，并在 UI 标明是推断而非上报。
7. 随包 CLI：dsh-progress（bin/dsh-progress.mjs）支持 emit、done、list，以及 run --task <id> -- <命令> 包装长命令并尝试从输出解析进度。

运行时零 npm 依赖；不向工具目录注册新 tool，因此不会额外占用工具说明的缓存前缀。

安装与启用¶

DSH 在启动时挂载 profile bundle，安装后需要重启 DSH。官方 README 给出的安装方式如下。

从 npm 安装并注册到 web profile：

dsh plugin --profile web add dsh-task-progress

从 GitHub 安装同一仓库的已提交构建产物：

dsh plugin --profile web add github:chen8923/dsh-task-progress

本地开发/checkout 场景可使用仓库内的 rebuild 脚本（需已有 DSH 源码路径）：

./tools/rebuild.ps1 -Profile web -Checkout <path-to-dsh-checkout>

安装包未声明 install、postinstall 或 prepare，因此安装阶段不会在机器上执行维护者脚本；之后实际运行的是包内的 lib/index.js（宿主）与 lib/client.js（浏览器）。若需自行核对发布 tarball 与源码重建是否一致，README 提供了 npm pack、diff -r 与 npm view dsh-task-progress dist.integrity 的比对流程。

插件目录页：https://www.skillhub.cn/plugins/chen8923/dsh-task-progress（SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系）。

典型用法¶

1、在脚本里追加 JSONL¶

插件为每次 shell 调用准备好目录，脚本只需向 $DSH_PROGRESS_DIR/<task>.jsonl 追加一行 JSON（协议详见仓库 docs/PROTOCOL.md）。

PowerShell 示例（每个事件一行）：

$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：

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")

2、使用随包 CLI¶

避免手写转义时，可直接调用环境变量指向的 CLI：

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

长命令可交给包装器（README 建议在预计超过约 30 秒的命令上使用）：

node "$env:DSH_PROGRESS_CLI" run --task <id> -- <你的命令>

3、零配置试跑¶

仓库提供模拟脚本，安装插件后可在 DSH shell 中执行：

pwsh ./examples/simulate.ps1 -Task demo -Steps 30 -DelayMs 500

然后打开右侧栏「任务进度」tab，或等待悬浮胶囊出现并点开。

装完插件后，宿主半会在系统提示词中加入进度约定，模型对长命令通常会自行安排上报；若组合里没有 systemPrompt 接缝，可把 README 中的 AGENTS.md 片段抄到工作区作为补充约束。

设置页与主要配置¶

在 Web UI 的插件页打开 任务进度设置 卡片（标题来自插件注册的 slot）。保存写入本条目在 profile 中的 config，改动实时生效。README 列出的字段包括：

进度文件默认位于各 workspace 下的 .dsh-progress/<session-id>/，插件只 tail 读取这些 jsonl（及配置的额外绝对路径根），不发起外网请求。

适用场景与注意¶

适合谁：经常在 DSH Web 界面盯长构建、数据导入、测试矩阵或 Agent 触发的后台 job，且希望人在环内能看到百分比、阶段消息和 ETA，而不是只看「运行中」状态。

脚本侧习惯（来自 README「脚本被杀掉时」一节）：

• 尽量让 task id 出现在命令行（例如 --task sync-catalog），便于与 job 镜像行配对。
• 一个 task id 对应一个写入者，或按阶段拆分 id。
• 正常路径仍应用 try/finally 写入终态；进程被强杀时依赖宿主推断兜底。

安装前须知：DSH 插件运行在 DSH 宿主进程权限内，不是沙箱安装。本插件声明的触碰范围包括：读取/创建上述 .dsh-progress 路径、注入 shell 环境变量、注册一条 HTTP 路由与 UI slot、追加系统提示词段；无出站网络、无遥测、不新增 tool。完整表格见仓库 SECURITY.md。安装前建议阅读源码、LICENSE（MIT）及发布完整性说明，并按自身安全策略决定是否启用。

刻意不做的事（避免错误预期）：不做历史归档、不做界面取消按钮（停任务仍用 DSH 的 job_kill）、不做跨会话或远程生产者。

结尾¶

DSH 生态强调「一切皆插件」；dsh-task-progress 用文件协议把长任务进度从 agent 输出流里解耦出来，让人在 Web UI 里实时看见进展。若你的 workflow 以 Web profile 为主、且长命令较多，可以先按 npm 一条命令安装，重启后用 examples/simulate.ps1 验证悬浮层与侧栏 tab，再按协议或 CLI 接到自己的脚本。

• 插件目录：https://www.skillhub.cn/plugins/chen8923/dsh-task-progress
• 源码与文档：https://github.com/chen8923/dsh-task-progress