轮次小结 littepointR/dsh-turn-recap

Turn Recap for DSH

给 DeepSeek Harness（DSH）用的常驻插件：每轮对话结束后，在 Web UI 的对话流末尾给出一段模型生成的简短小结，也可以用 /recap 主动重算。

功能

- 轮次结束、会话安静下来之后，在该轮末尾出现一张卡片：一到三句话说明这一轮做成了什么，必要时补一句尚未完成的部分。
卡片会先等过一段安静窗口（默认两分钟），而且如果你在窗口内又发了新提示词，这一轮的卡片就不会出现——它是「上次做到哪」的提示，而不是你正在读的那条回复的第二份摘要。正文跟随对话语言。
- /recap：按需为最近一轮立即生成同样的小结——适合某一轮没等到安静窗口、你翻过去了、或者想重新看一下当前进展的时候。
- 没有可总结内容的轮次（被中断、失败、空轮）不出卡片；子代理会话默认跳过。
- 如果这一轮确实留下了一个明确的下一步——待用户回答的问题、已商定的后续动作、或解除当前阻塞的具体办法——卡片会在正文下方多一行「下一步」。干净收尾的轮次没有这一行。

卡片使用宿主的主题变量，跟随明暗主题与当前语言（随包提供中英两套词条）。

环境要求

- DSH >=0.2.1-rc.2 —— 本插件的开发与验证都基于这个运行时版本，package.json 用 engines.dsh 声明了下限。启动器会在两处校验它：安装 bundle 时，以及包含它的 profile 启动时。运行时低于下限会被 incompatible-version 拒绝，并给出未满足的范围。
- 用 dsh --version 查看 profile 实际会用的运行时版本。
- 这个下限对应的是插件实际绑定的 API 集合，不是拍脑袋定的：agent/turn-stopping、带客户端可见 wire 视图的 session 投影、commands 注册表（含 command/done 的结果文本）、llm.prepareCall() 流式调用，以及客户端的 conversation.chat.turnTail / conversation.chat.commandview 槽位和 remote.session.projections。提供了这些 API 的相邻版本大概率也能用，但只有这里声明的下限是实际验证过的组合。

刻意没有声明 peerDependencies：这个 bundle 不 import 任何 @deepseek-ai/* 模块，只在运行时解析 Cordis 服务，写 peer 范围反而是在描述一个并不存在的依赖。

确实要在更低版本上跑，启动器提供的口子是精确版本豁免，而不是范围：

dsh plugin --profile <profile> allow-version '@local/dsh-turn-recap@1.0.1' --dsh-version '<runtime>' --accept-risk

Plugin Manager 里也有同样的授权入口。它等于让未经验证的进程内代码跑在你的运行时上——文档明确的风险是崩溃与数据丢失，而且授权只对一个确切的插件版本 + 一个确切的运行时版本生效。

安装

这是一个 DSH bundle：声明了 dsh.bundle.patch 与 dsh.client 两半，用启动器自带的插件命令装进 profile，不发布到 npm。

默认分支最新提交
dsh plugin add github:littepointR/dsh-turn-recap

或锁定 tag 版本
dsh plugin add github:littepointR/dsh-turn-recap#v1.0.1

dsh plugin 会把参数转发给 profile 目录里的 pnpm，安装成功后选中该 bundle。profile 的 YAML 里启用了 HMR 时组合会立即重载，否则下次启动生效。装进指定 profile 时把 profile 名传进去：

dsh plugin --profile <name> add github:littepointR/dsh-turn-recap

bundle 的 patch 会插入一行 Loader 配置：

- insert:
- id: turn-recap
name: '@local/dsh-turn-recap'

从本地检出安装

git clone https://github.com/littepointR/dsh-turn-recap.git
dsh plugin --profile <name> add link:D:/path/to/dsh-turn-recap

也可以在 DSH 会话里让 agent 用 profile 的 plugin manager 从这个目录安装。

重新安装或启停插件不需要重启 Harness：禁用再启用该行即可重新导入宿主模块。

配置

所有字段都可选。在 profile 的 cordis.patch.yml 里给这一行加 config 块即可——这层配置能跨包升级保留。

| 字段 | 默认值 | 含义 |
| enabled | true | false 时不注册投影、轮次监听与 /recap |
| maxTokens | 200 | 小结请求的输出上限 |
| temperature | 0.2 | 采样温度 |
| timeoutMs | 12000 | 单次小结请求的硬超时（毫秒） |
| digestChars | 6000 | 送给模型的轮次摘要长度上限 |
| idleMs | 120000 | 卡片出现前该轮需要保持的安静窗口；0 表示立即出现 |
| skipSubagents | true | 子代理会话不自动出小结 |
| provider、model | 未设置 | 显式指定路由；默认复用本轮自己的请求路由 |

- insert:
- id: turn-recap
name: '@local/dsh-turn-recap'
config:
maxTokens: 300
skipSubagents: false

工作原理

agent/turn-stopping ──▶ 抽取本轮摘要 ──▶ 模型调用 ──▶ 待定表 │ turn/end（提交）──▶ 投影 apply ──▶ recap 投影 ──▶ useProjection("recap") │ conversation.chat.turnTail

1. agent/turn-stopping 是 agent loop 在提交 turn/end 之前派发的串行事件。插件从 session 日志里抽取本轮内容——用户请求、最近的工具调用（标注失败）、以及本轮的最后一条助手回复——向服务本轮请求的模型索取一段小结。
2. 随后的 turn/end 提交把文本折进客户端可见的 recap session 投影，卡片与结束的轮次同一帧到达。
3. 客户端半边注册到 conversation.chat.turnTail 槽位，用 useProjection("recap") 读取投影。每个条目带一个 revealAt 截止时刻：在它之前、或者期间已经开始了新一轮，卡片都不会出现——安静窗口不产生成本，也不会打断正在进行的操作。

为什么用投影而不是 session 事件？ 插件不能追加新的事件类型：日志里出现当前构建不认识的事件类型会导致会话无法重新打开，而 appendPluginRecord() 只留给一方实验包。session 投影才是承载「会话派生客户端状态」的正规通道。

为什么要在 turn/end 之前生成？ 投影状态是从已提交事件同步折叠出来的，只有提交事件改变状态时 Value 才会被重新读取。
在轮次边界还开着的时候拿到文本，才能让它随提交一起折进状态——延后的只是出现，不是请求本身，所以安静窗口既不改成本也不改延迟。

要模型写什么。 单条纯文本提示：一到三句、跟随对话语言；要求精确说明工作推进到哪一步（proposed、queued、 implemented、tested、published、installed 是不同状态），保留「尚未安装」「还没验证」这类未解决的前提，并且把最新一条用户消息当作「范围」而不是「已完成的证据」。确实存在下一步时，它会以最后一行 Next: 返回，宿主把它解析成独立字段，卡片才好加标签并单独排版。

/recap 是一个普通的 DSH 命令：它不产生 turn，结果随 command/done 落日志。客户端半边通过 conversation.chat.commandview 槽位的 recap 键接管该命令行，自己渲染「生成中 / 成功 / 失败」三态。

代价与限制

- 每轮多一次模型请求。 请求很短，但会由你的 provider 计费；由于没有追加助手消息，它不会出现在会话的 token 统计里。
- 轮次会等小结就绪后才关闭。 生成发生在 turn/end 之前，provider 慢时边界最多延后 timeoutMs；失败只会退化成「没有卡片」，绝不会让轮次失败。安静窗口只影响你看到的时间，不影响成本。
- 小结失败会说清原因。 /recap 会区分超时、被中断、provider 拒绝（带错误码）、以及返回里没有正文；自动路径会把同样的原因记进投影，而不是静默失败。请求还会显式选用该路由的最低推理档，避免 200 token 的输出预算被推理吃光。
- 没等到窗口的卡片不会出现。 如果在 idleMs 之内就发出了新提示词，那一轮不会留下卡片；确实想要时用 /recap 补一张。
- 小结文本无法从日志重建。 它存放在投影缓存里，重启后仍在；如果投影单元格只能从日志重新折叠（例如插件被重新注册），历史卡片会从空白开始。
- stateVersion 控制旧口径缓存。 提升它会让上一套取材规则产出的小结失效，而不是继续展示旧文本。

开发

两半都是零依赖的 JavaScript：宿主半边是普通 ESM，客户端半边是只向页面索取 react 的模块加载器工厂。

npm test # 在假的 Cordis 上下文里跑宿主半边，除了 Node 什么都不需要
npm run check # 对所有 JavaScript 入口做语法检查

宿主测试覆盖投影折叠、轮次摘要抽取、/recap 处理器以及各条失败路径，所以多数改动不必启动 Harness 就能验证。

许可

MIT，详见 LICENSE。