前言¶
在 DeepSeek Harness（DSH）里，模型经常通过 Shell 工具一次下发多条语句：先装依赖、再编译、再跑测试。默认情况下，工具调用卡片往往要等整段命令跑完才呈现完整输出，进行中时很难判断「现在卡在第几步、前面几步是否已经结束」。dsh-shell-progress 是社区维护的工作流类插件，在工具调用卡片里用分段进度条标出多步 Shell 命令当前所在步骤，并在展开或悬停时查看各步命令、输出与耗时。下面介绍它的定位、能力与安装配置方式。
这是什么¶
dsh-shell-progress（npm 包名 dsh-shell-progress，仓库 9087/dsh-shell-progress）是 DeepSeek Harness 插件：在 pwsh / Shell 工具 执行可被拆分的多步命令时，在工具调用卡片内展示 分段进度条，标明「当前跑到第几步」。维护者为 9087；当前 npm 版本为 0.8.0，许可证 MIT，运行环境要求 Node.js >= 20.11。插件目录页见 SkillHub。
核心功能¶
折叠态：一眼看到进度¶
卡片折叠时，摘要行旁会出现分段条：每个顶层步骤对应一段，状态为 pending、running 或 done，并配有类似 3/4 的计数，便于快速判断进度与剩余步数。
悬停与展开：逐步查看输出¶
悬停某一段可打开该步的卡片，显示该行的命令、输出与耗时。悬停卡片中，命令行上方还有模型生成的一行说明（默认开启，可在 DSH 设置页「Shell Progress」下关闭）；说明与命令一并写入记录，避免运行时再等待生成。
展开整张卡片后，各步各占一行：命令、耗时与输出；正在执行的步骤会显示运行中的时钟。
后台任务与无法拆分的命令¶
若模型以 run_in_background: true 运行命令，卡片标题为「run a background job」，带警告标记（悬停可看说明），不显示进度条与计数——任务在启动时即写入记录，插件无法观测逐步位置。展开后仅列出命令语句；输出留在对话顶部的 Background jobs 列表，命令本身不经插件改写，输出与 Shell 一致。
若命令无法拆分或插件选择不跟踪，仍作为 单条命令 处理：卡片只画一段进度条，标题后的 ⚠ 悬停说明「未拆分」，进度条表示整段命令而非逐步。命令执行方式与未装插件时相同，输出仍受 Shell 工具原有的每步预算约束。
配置项¶
在 profile 的 cordis.patch.yml 中可为插件传入 config（字段与默认值见下表）。maxStepOutputChars 控制卡片内保留的每步输出长度；超出部分在卡片中截断并标注缺失字符数，不影响模型从 Shell seam 看到的完整 stdout（seam 自身的 truncated / spillPath 逻辑不变）。
| 字段 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
是否注册 shell_progress 工具 |
pollIntervalMs |
120 |
主机轮询运行中进程输出的间隔（毫秒） |
maxStepOutputChars |
8192 |
持久化进度中每步保留的输出字符上限 |
maxSteps |
400 |
拆分步数超过此值时，命令原样执行、不逐步跟踪 |
liveRetentionMs |
300000 |
已结束调用的 live 记录在迟到的轮询前保留时长（毫秒） |
安装与启用¶
DSH 在启动时加载插件，安装或修改挂载后需要 重启 dsh web。
方式一：DSH 界面
打开 Plugins 页面，点击 Add plugin，输入 npm 包名 dsh-shell-progress。
方式二：命令行
dsh plugin --profile web add dsh-shell-progress
方式三：手动写入 patch
在所用 profile 的 cordis.patch.yml 中插入：
- insert:
- id: shell-progress
name: dsh-shell-progress
需要自定义行为时，可在同一条目下增加 config，例如：
- insert:
- id: shell-progress
name: dsh-shell-progress
config:
enabled: true
pollIntervalMs: 120
maxStepOutputChars: 8192
maxSteps: 400
liveRetentionMs: 300000
经过上面的步骤并重启 Web 端后，模型通过 Shell 工具执行的多步命令在支持拆分时，卡片上会出现分段进度与步数计数。
典型用法¶
本插件 不单独提供 CLI 子命令；典型用法是安装并启用后，在 DSH 对话中让模型照常调用 Shell（pwsh）工具。当模型一次提交多条顶层语句（例如连续的 npm install、npm run build、npm test）且插件能够解析拆分时，你会在对应工具卡片上看到分段条与 已完成步数/总步数。需要看某一步细节时，悬停对应分段或展开卡片即可。
若模型将长耗时任务设为后台运行（run_in_background: true），应到对话顶部的 Background jobs 查看输出与控制任务，而不是依赖本插件的进度条。
适用场景与注意¶
适合谁： 经常在 DSH 里跑多步构建、测试或部署脚本，希望在等待过程中看清「第几步、是否卡住」的开发者。
权限与安全： 插件随当前 DSH 进程加载，与宿主共享权限；安装前请阅读 GitHub 仓库 源码与 MIT 许可证，仅从可信来源（npm 包名 dsh-shell-progress 或上述仓库）安装。
生态说明： DSH 采用「一切皆插件」的扩展方式；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-shell-progress 把多步 Shell 工具调用的执行位置可视化到工具卡片里，减少「黑盒等待」带来的不确定感。若要进一步了解实现或参与贡献，可访问目录页 https://www.skillhub.cn/plugins/9087/dsh-shell-progress 与 GitHub https://github.com/9087/dsh-shell-progress。
