# dsh-narrator 功能介绍

> 模型想得太久时，先让它说一句话，然后接着干。

## 一句话

给 DeepSeek Harness 装一个小插件：模型闷头思考太久时，它会自己开口说清「在做什么、做到哪了」，**而任务不会因此停下**。

![模型思考 12 分钟没有任何正文输出时，左下角浮窗显示它刚说清的四点进展](assets/screenshot-1.png)

## 它解决的是什么问题

用 AI 干长活的人大概都遇到过这个场面：你发了任务，屏幕上几十分钟一动不动。你不知道它是在认真研究，还是已经卡死、在空转、在等一个永远不会回来的响应。要么傻等，要么打断重来——两个都不是好选项。

想解决这件事，最直觉的办法是「在提示词里让模型中途说一句进度」，但这条路在 DeepSeek Harness 里**走不通**。它的代理循环有这么一条判断：

```js
if (turnEnds && decision.messages.length === 0) break;
```

一条不带工具调用的纯文本消息，会被判定为「回合结束」。也就是说，**模型一旦开口说进度，任务当场就停了。** 这是宿主语义层的规则，不是提示词能绕的小聪明。

## 它是怎么绕过去的

关键在一个字：**等**。

静默超过阈值时，插件什么都不做，只在内存里记一笔「该汇报了」。等模型走到**下一个 step 边界**——也就是它自然停下来准备下一步的那一刻——再从 `agent/pre-step` 这个钩子往请求里多带一条消息。请求里多了一条消息，`decision.messages.length` 就不为 0，回合关不掉，模型于是继续说下去。

```
模型只思考、不出声
      │
      ▼   静默超过阈值（默认 60 秒）
只记一笔「该汇报了」          ← 界面上什么都还没动
      │
      ▼   下一个 step 边界
注入一段提示词
      │
      ▼
模型用正文说一段
      │
      ├─→ 对话区左下角浮窗显示这段原文
      └─→ 正文继续走，回合不关闭
```

为什么必须等这个边界：模型往往正卡在两次工具调用中间。这时候硬塞消息，会落在「调用」和「调用结果」之间，宿主直接报错。

## 你会看到什么

### 1. 对话区左下角的小浮窗

模型报完进度，这张卡就贴在正文左下角，显示它刚说的原文。它是**信息补位**，不抢你的主视野，也不挡正文。

![浮窗贴在对话区左下角，显示模型刚说的四点进展](assets/screenshot-1.png)

浮窗分三个阶段，你一眼能看出它现在在干什么：

| 阶段 | 标题 | 说明 |
|---|---|---|
| 到点，还没轮到它说 | **还在等** | 等子任务返回时会显示等了多久 |
| 已经提醒，模型正憋这段话 | **正在整理汇报** | 说明提示词送到了 |
| 模型开口了 | **正在汇报** | 显示模型的原话 |

**它什么时候走**，三条规则：

- **模型重新开口，浮窗立刻撤。** 它一说话，你就有新东西可看了
- **叉掉就是叉掉。** 点 `×` 关掉后，切走再切回同一条汇报不会重新弹出来；等下一条新汇报才再出现
- 平时停 90 秒自动消失（可调）

### 2. 设置卡（设置 → 进度旁白）

![设置卡：阈值、浮窗透明度、停留时长都是滑杆，提示词可整段替换](assets/screenshot-2.png)

全是滑块和开关，没有要你手改配置文件的字段（下面写的是界面上真实的名字）：

| 项目 | 说明 |
|---|---|
| **让模型定期汇报** | 总开关 |
| **多久没有文字输出就让它说一句** | 1~60 分钟，默认 1 分钟。从最后一次正文输出开始算，只思考、只调工具都不算 |
| **两次汇报至少间隔** | 1~60 分钟，默认 1 分钟。防止刷屏，设得越小汇报越频繁 |
| **同时把汇报内容弹到对话区左下角浮窗** | 默认开。关掉后仍然会汇报，只是不显示浮窗 |
| **浮窗透明度** | 35%~100%，默认 100%，只影响浮窗底色 |
| **浮窗停留多久后自动消失** | 5 秒~600 秒，默认 90 秒 |
| **汇报内容怎么给模型说** | 想让它从特定角度汇报就改这里；留空用内置四点式 |
| 在对话里显示这条提示词（默认隐藏） | 默认关。开了对话流里能看到注入的原文 |
| 子任务里也照样汇报 | 默认关（子代理会话你在界面上看不到） |

底部固定着两个按钮：**保存**（没有改动时显示「已保存」）与**恢复默认**。置灰状态下是「已保存」——说明当前值就是磁盘上的值。

![滚到底时保存与恢复默认贴在卡片下沿，按钮下方底色铺满，不会透出滚过去的文字](assets/screenshot-3.png)

### 3. 想当场看效果

设置卡底部有个「测试」区块，能把阈值临时压到几秒，马上就能看到浮窗长什么样。关掉后恢复真实配置，**真实配置一个字节都不会被改**。

## 建议阈值

实测单步耗时通常在 5~7 秒，偶尔十几秒。所以：

- **想经常看到** → 设 1 分钟
- **只在明显卡住时提示** → 设 3~5 分钟
- 上限 60 分钟。设到 30 分钟以上基本不会触发

## 它不做什么

- **不改你的任务。** 注入的只是一条提醒，模型接着干它原来的活，上下文不丢
- **不额外花钱。** 零运行时依赖，不调用任何外部服务，只在本机跑
- **不抢你的视线。** 对话流里默认看不到那条注入的提示词，只有浮窗
- **不上传任何东西。** 配置存在 `~/.dsh/narrator/config.json`，就你本机

## 装与不装的差别

|  | 没装 | 装上 |
|---|---|---|
| 模型长时间沉默 | 一片空白，不知道在干什么 | 左下角浮窗说清进展 |
| 判断是否卡死 | 只能靠猜或打断 | 看浮窗的等待时长和阶段 |
| 任务连续性 | —— | 汇报不打断任务 |

## 已知限制

1. **注入不是硬保证。** 机制保证回合不关闭，但如果模型自己写完就停下，那还是会停。默认提示词末尾那两句「说完必须继续执行，不要结束任务」就是在防这个
2. **注入有延迟。** 到点只是记账，真正注入要等下一个 step 边界。那一 step 如果在等子智能体，可能要多等几分钟——这期间浮窗显示「还在等」，所以不会看起来像卡死
3. **只支持 web 端**
4. **子代理的汇报默认关闭。** 那些会话界面上看不到，注入属于浪费一次模型调用

## 怎么装

见同目录的 [安装与功能说明.md](安装与功能说明.md)，五分钟能装完。简要三步：

1. 把整个 `dsh-narrator` 目录拷进 `<profile>/node_modules/`
2. 在该 profile 的 `package.json` 里，`dependencies` 和 `dsh.profile.bundles` **两处**都登记
3. 重启 DSH，打开 **设置 → 进度旁白**

---

MIT 许可。源码与完整技术文档见 [README.md](README.md)。