前言¶

在 DeepSeek Harness（DSH）里跑代理任务时，模型可能连续调工具、长时间推理，却迟迟不向对话区输出可见文字。界面上没有新内容，很难判断是还在执行还是已经卡住。单靠提示词让模型「中途说一句」往往也不奏效：宿主代理循环里，一条不带工具调用的纯文本消息会被判定为回合结束，模型真开口了，任务反而停在那里。

dsh-narrator 是社区维护者 Asza-other 发布的 DSH 插件（分类：模型推理），针对上述静默场景：超过可配置阈值后，在合适的 step 边界注入提示，让模型用正文说明进展，且不关闭当前回合；汇报原文可同步显示在对话区左下角浮窗。插件带分钟级图形设置卡，无额外运行时依赖。

这是什么¶

dsh-narrator（仓库 Asza-other/dsh-narrator）通过 Cordis 补丁挂接 DSH 的 agent/pre-step 等钩子，监听助手流中的文字输出，按「多久没有正文」计时（工具调用与 reasoning 不计入）。到点后先记账，等到下一个 step 边界再向请求追加一条带 source: { kind: 'narrator', form: 'notice' } 的上下文消息；模型据此生成可见汇报，回合因仍有有效决策路径而继续。用户侧可在设置页「进度旁白」调整阈值、间隔、提示词与浮窗行为。

核心功能¶

回合不中断的注入时机¶

插件不在静默到点时立刻改请求，而是在 agent/pre-step 的 waterfall 里合并消息，保证 decision.messages.length 不为 0，避免被宿主当成「纯文本结束回合」。注入内容对用户默认隐藏（归为 context 节点），模型仍能读取；若需要在对话流里看到注入原文，可在设置中打开「在对话里显示这条提示词」。

按「无文字输出」计时¶

触发基准是距最后一次正文输出的时长，不是单步执行时长。连续多次工具调用却一句话不说，仍会触发。汇报成功后计时器会推到当前时刻，避免立刻再次触发。新回合（turn/end）会清零计时。

左下角浮窗与等待阶段¶

开启「同时把汇报内容弹到对话区左下角浮窗」时，模型汇报的原文会贴在对话正文左下角，支持常见 Markdown（标题、列表、表格、行内代码等）渲染，颜色跟随宿主 --dsw-alias-* 令牌，浅色深色主题均可用。

从到点到真正注入之间可能有延迟（例如 step 在等待子智能体）。浮窗会分阶段提示：还在等 → 正在整理汇报 → 正在汇报，并说明是在等子任务、查资料、跑命令或读文件等。主窗口派出子代理后，也可通过设置决定是否对子任务会话同样注入（默认关闭，因子代理界面不可见时注入会多耗一次模型调用）。

图形设置与本地 API¶

设置入口：设置 → 进度旁白。主要项包括：总开关、无文字输出阈值（默认 1 分钟，1～60 分钟）、两次汇报最小间隔、可整段替换的四点式汇报提示词、浮窗透明度与停留时长等。配置持久化在 ~/.dsh/narrator/config.json，优先级高于 cordis.patch.yml 中的预置值。卡片底部提供「测试」区块，可临时把阈值压到几秒验证效果，关闭后恢复真实配置。

安装成功后，本机可访问自检接口（仅 127.0.0.1）：

curl http://127.0.0.1:<端口>/api/narrator/status

端口以 DSH 窗口地址栏为准；返回示例中含 {"ok":true,"version":"0.12.5",...}。

安装与启用¶

前置条件：DeepSeek Harness 0.2.1+（依赖 dsh.client 与 shell.overlay 等槽位）、Node.js 18+。插件包本身无 npm 运行时依赖，无需在插件目录执行 npm install。

下面介绍将插件装入某一 profile 的步骤（desktop 请换成你在 DSH 设置里看到的 profile 名）。

1、拷贝插件到 profile 的 node_modules

从 GitHub 仓库 取得 dsh-narrator 源码目录后，复制到 profile 对应路径：

cp -r dsh-narrator ~/.dsh/profiles/desktop/node_modules/dsh-narrator

Windows 对应：%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-narrator。

2、修改该 profile 的 package.json（两处都要加）

{
  "dependencies": {
    "dsh-narrator": "file:../../path/to/dsh-narrator"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-narrator"]
    }
  }
}

dependencies 与 dsh.profile.bundles 缺一不可：只写 bundles 可能在 pnpm 重装时被清掉；只写 dependencies 则插件不会加载。若 DSH 自动执行了 pnpm install，建议复查 bundles 数组是否仍在。

3、重启 DSH

agent/pre-step 在后端注册，刷新页面不够，需重启 DSH 进程。

4、验证

设置里出现「进度旁白」即表示加载成功；也可用上面的 curl 访问 /api/narrator/status。

典型用法与调参¶

1. 保持默认「让模型定期汇报」开启，阈值 1 分钟、间隔 1 分钟，适合希望频繁看到进展说明的场景。
2. README 建议：单步耗时常见约 5～7 秒；若只想在明显卡住时提醒，可将阈值调到 3～5 分钟；30 分钟以上基本不会触发。
3. 需要自定义汇报结构时，在设置卡中编辑「汇报内容怎么给模型说」，留空则使用内置四点（正在做什么 / 已完成什么 / 接下来做什么 / 卡在哪）。
4. 开发调试可用仓库内脚本（需在克隆或下载的源码树中执行）：npm test 跑单测；node test/check-status.mjs <端口> 读取运行中实例的自检信息。

适用场景与注意¶

适合谁： 经常在 DSH web 端跑长链路代理、且模型习惯长时间只调工具或推理的用户；希望在不打断任务的前提下，用模型自己的话同步进度。

已知限制（摘自官方 README）：

• 注入不能保证模型汇报后一定继续执行，默认提示词末尾要求「说完必须继续执行」以降低停下来的概率。
• 到点记账与真正注入之间存在 step 边界延迟；等待子智能体时浮窗会显示等待状态。
• 当前仅支持 web 端，未做桌面外壳原生 UI。
• 修改前端 bundle 需刷新页面；后端配置即时生效。

安全与权限： 插件随当前 DSH 进程与用户 profile 加载，以该进程的权限访问会话与本地配置。安装前请阅读 MIT 许可证 与源码，确认符合你的环境策略。社区插件目录 skillhub.cn 为独立生态站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-narrator 用宿主认可的 agent/pre-step 注入方式，在长静默时让模型自己用正文交代进展，并通过左下角浮窗把原文呈现给用户，任务回合保持不中断。更多截图与排错说明见仓库内的《安装与功能说明.md》《功能介绍.md》。

• 目录页：https://www.skillhub.cn/plugins/Asza-other/dsh-narrator
• GitHub：https://github.com/Asza-other/dsh-narrator