Shell 步骤进度 9087/dsh-shell-progress

dsh-shell-progress

一个 DeepSeek Harness 插件：在多步 shell 命令的工具卡片里显示一条分段进度条，一眼就能看出「这条命令现在执行到哪一步」。

┌──────────────────────────────────────────────────┐
│ Shell 步骤进度 · 构建并运行测试 2/7 │
│ [████|████|▓▓▓| | | | ] ▶ 47s │ ← 收起态就有
├──────────────────────────────────────────────────┤
│ ● 1 $total = 0 │
│ ● 2 if ($true) { │ ← 展开后： │ ▶ 3 Write-Output "adding $n" │ 每步代码 + 该步输出 │ → adding 1 │ │ ○ 4 Write-Output "done" │ └──────────────────────────────────────────────────┘

它回答的问题是「命令还在跑，还是卡住了？」——因此实时位置是功能本体，不是加分项。
进度条常驻在收起态：瞄一眼就能定位，藏进展开区就失去了意义。

安装

dsh plugin --profile web add dsh-shell-progress

或直接在 profile 的 cordis.patch.yml 里挂载：

- insert:
- id: shell-progress
name: dsh-shell-progress

然后重启 dsh web（宿主只在启动时加载一次插件）。

模型看到什么

什么都不变。shell_progress 注册的工具，其模型可见文本与 pwsh 工具跑同一条命令 逐字节一致：同样的 stdout、同样的 [stderr] 段、同样的 [exit code: N] 标记。
步骤信息从不进入对话，它走工具结果的 presentationMeta，由宿主持久化到 tool/result 事件上。

模型能读到的地方没有 nonce、没有标记、没有重排序。

配置

| 字段 | 默认值 | 含义 |
| enabled | true | 是否注册 shell_progress 工具。 |
| pollIntervalMs | 120 | 宿主读取运行中进程输出的间隔。 |
| maxStepOutputChars | 8192 | 每步输出在持久化进度里保留的字符数。 |
| maxSteps | 400 | 超过此步数的命令按原样执行。 |
| liveRetentionMs | 300000 | 已结束调用的实时记录保留多久，供迟到的轮询读取。 |

工作原理

1. 切分：只在顶层步骤打点——非空行、起始于第 0 列、不以 } 开头、花括号深度为 0。
计数时跳过单引号串、双引号串（含反引号转义）与 # 注释。循环体永远不是步骤，所以迭代多少次都只产生一个标记。
2. 插桩：标记前缀在该步骤自己那一行，不新增行，其余行逐字保留。
3. 执行：插桩后的文本走 ctx.shell，与 pwsh 工具完全同路——同样的超时、沙箱策略、受管环境与取消语义。
4. 跟随：命令运行期间读增量输出，把每个标记变成「当前步骤」，并用单调时钟打时间戳。
5. 持久化：每步起止时间与输出走 output.presentationMeta，因此重新加载会话后，整张卡片可以只凭会话日志复现。

埋点必须内联

src/instrument.ts 里有完整说明；一句话版：PowerShell 里函数调用本身也是一条命令，它会覆盖 $?。所以把埋点写成辅助函数，就会悄悄改掉被插桩命令读到的值——而且调用方之后读到的 $? 是辅助函数的成功状态，即使在函数内部捕获并恢复也无济于事。
本机实测（Windows PowerShell 5.1，即未装 PowerShell 7 时 shell 能力缝实际解析到的那个）：

| 埋点形态 | 紧接失败命令之后的 $? |
| 不插桩（对照） | False ✅ |
| 辅助函数（内部捕获+恢复） | True ❌ |
| 内联捕获+恢复 | False ✅ |

tests/powershell.spec.ts 会把两种形态都真的跑一遍并断言这个差别，所以将来若有人把埋点重构成函数，测试会失败。

什么时候不跟踪

以下任一条件成立时，命令按原样执行，卡片降级为「知道有几步、但不知道在哪一步」：

- 切分器遇到无法判定的结构（未闭合引号、块注释、here-string、续行符、花括号或圆括号不平衡）；
- 命令只有 1 步或更少；
- 命令里已经出现本方案的标记形状，或已经使用 $__ok；
- 解析出的沙箱模式是 read-only；
- 步数超过 maxSteps。

这些都不是错误：模型拿到的与 pwsh 完全一致。

结构

| 半边 | 源码 | 运行环境 |
| Host | src/index.ts（以及旁边的纯函数模块） | DSH 宿主进程（Node） |
| Client | src/client/*（React） | 浏览器 |

两边只共享 src/types.ts 与 src/split.ts。

实时通道是轮询，不是推送。 安装在 DSH 仓库之外的插件收不到宿主事件（转发事件白名单是构建里的静态数组），所以浏览器在调用进行期间每隔约 250ms 向本插件自己的已认证请求/响应通道 /shell-progress 问一次。已结束的状态不需要轮询：它本来就在会话日志里。

开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build

详见 DEVELOP.md 与 PUBLISH.md。

许可

MIT