dsh-tui-compact-carry

> A TUI-only plugin for DeepSeek Harness (dsh):
> compaction count + live progress in the status line, and /carry to bring a cached
> compaction summary into the current session.

> ⚠️ 只支持 TUI（@deepseek-harness-tui/dsh-tui）。状态行依赖 ctx.tuiStatus，
> Web / headless 没有这个服务，装上去不会报错但也没有状态行。命令本身在两端都能跑，
> 但本插件刻意只面向 TUI 场景。

一个零依赖的小插件（只用 Node 内置模块），解决 TUI 里压缩体验的三个痛点：

1. 看不到压缩在跑 —— 自动压缩在 TUI 主界面完全无声，十几秒里没有任何指示。
2. 数不清压过几次 —— 一屏之外的历史压缩次数没有地方可看。
3. /new 之后上下文归零 —— 刚压缩出来的完整摘要带不到新会话里。

它做什么

为什么要进度行：自动压缩在 TUI 主界面是无声的——channel.compact() 里的「正在压缩会话…」
只属于手动 /compact；全包响应 compaction/start|end 的只有轨迹页投影
（trajectory/projection.js）。所以插件把这两个事件搬到了状态行上。

安装

要求：Node.js ^22.19.0 || >=24.0.0，dsh 已在 PATH 上。

方式 A：按 bundle 安装（推荐）

dsh plugin --profile dsh-tui add github:sailoflight/dsh-tui-compact-carry

package.json 里声明了 dsh.bundle，所以 dsh plugin add 会把它作为一层配置装进 profile。
装完重启该 profile 才生效（manifest/包元数据不热更新；只有用户自己的
cordis.patch.yml 才热重载）。

方式 B：绝对路径挂载（零依赖，不需要 pnpm）

本插件零外部依赖，所以也可以直接把 index.js 放到插件目录，再用绝对路径挂一行：

mkdir -p "$HOME/.dsh/plugins/dsh-tui-compact-carry"
cp index.js "$HOME/.dsh/plugins/dsh-tui-compact-carry/"

在 $DSH_HOME/profiles/dsh-tui/cordis.patch.yml（默认 $DSH_HOME = ~/.dsh）里加：

- insert:
- id: dsh-tui-compact-carry
name: /home//.dsh/plugins/dsh-tui-compact-carry/index.js
config: {}

⚠️ 方式 A 与方式 B 二选一，别同时用（同一个 id 挂两次会报 duplicate loader entry id）。

用法（三步）

/compact        # ① 官方手动压缩一次（拿到含最近几轮的最新全量摘要）
/new            # ② 起新会话 —— dsh-tui 原生行为，插件不参与
/carry          # ③ 在**新会话里**敲：把刚缓存的摘要写进本会话（首条是折叠的「压缩检查点」）

• ②③ 之间的顺序不重要，重要的是 ③ 要在你希望摘要落在的那个会话里敲——插件写的是
  "当前 agent 的会话"，不猜、不追、不抢。
• 想先看内容：/carry show；想带全部压缩记录：/carry all；改主意：/carry off。
• 摘要缓存默认 30 分钟内有效（autoArmWindowMs），过期就提示"过期"并要求重新 /compact。
• 没有摘要可带时 /carry 直接报错，让你先按官方 /compact（不猜测、不虚报、绝不自己动手压）。
• 摘要缓存是进程内的：/compact 之后没敲 /carry 就重启了 TUI，缓存就没了，重新压一次即可。

设计约束（三条硬规则）

一、不订阅任何 TUI 决策事件

tui/session-switched、tui/input、tui/compact 等属于 TUI 决策事件
（TUI_DECISION_EVENT_NAMES）。TUI 装了全局钩子 ctx.on('internal/listener', …)
（dsh-adapter/decision-guard.js 的 installDecisionGuard），cordis 对每一次订阅都会触发它。
插件用裸 ctx.on 注册决策事件时：

• 若插件没有 Component 身份 → 记 warn 并返回 () => false（空 disposer），监听器根本没注册；
• 若有身份但没有 tui.dsh/v1alpha1#DecisionEvents 契约 → registerDecisionHandler 抛错，
  同样被捕获、告警、拒绝。

dsh-adapter/extension-events.js 也写得很明白："Handlers come from the host-mediated
DecisionEvents registry. Raw Cordis ctx.on listeners are intentionally absent from this path."

⇒ 普通插件订阅决策事件是死代码。要用决策事件，得把一个完整 TUI 扩展组件
（manifest + DecisionEvents 契约 + 权限声明 + 授权文件）装进 dsh-tui 自己的扩展宿主里——
那是另一量级的工程，而且正好是"插件深度介入 /new 切换"的高风险区。
本插件的选择是退出这条路径：计数/进度/缓存全部走 session/event
（普通事件，决策守卫不管）。

> 排查提示：如果你看到"状态行更新了、但新会话里什么都没发生"，八成就是踩了这个区别——
> 普通事件能用，决策事件被静默拒绝。

二、插件绝不自己触发压缩

TUI 把「手动压缩」做成了一个必须在会话切换前结算的事务
（dsh-adapter/channel/compaction.js："Owns the one manual compaction transaction that must
settle before a switch."），settleCompaction 被注入 newSessionAction / fork / rewind /
session-tree。

插件绕过这个事务直接触发压缩 → /new 的 settle 无事可等 → 切换与压缩赛跑，会卡在半路
（表现为：压缩完成后输入栏不再接受输入、盲打 /new 后卡在选择界面、方向键以 [[A
之类的原始序列堆进输入行）。

⇒ TUI 没有给插件留"安全触发官方压缩"的入口（tui/compact 是给插件用的否决钩子，
不是触发器）。所以：压缩只由用户按官方 /compact，插件只负责"取现成的摘要 + 搬运"。
离线冒烟的最后一道门就是 engineCalls.length === 0。

三、完全不参与 /new 的切换事务

插件连"新会话出现了"这件事都不需要知道：/carry 是在新会话里敲的，写的是
invocation.agent.session（就是"当前会话"），不依赖任何切换通知。
/new 的建会话/清屏流程逐字保持 dsh-tui 原样。

有一个默认关闭的可选自动版（autoCarryOnNew）：新会话出现后延迟
autoCarryDelayMs 自动写入。它走的是普通事件 session/created，刻意绕开 /new 的切换事务；
那条监听器抛错会让 attach 回滚，所以全程 try/catch，里面只做"读字段 + 调度定时器"。
默认选择仍是手动 /carry。

与宿主版本的耦合：session format V4（0.6.0）

DSH 的会话格式升到 V4 之后，/carry 会报
format v4 message requires a producer-owned source kind。原因是 0.5.0 写的是 V3 时代的
泛型包装 source: { kind: 'plugin', plugin: 'compact' }；V4 的准入校验直接拒绝
kind: 'plugin'，要求消息源报出「生产者自己的 kind」：

判据在 dsh-session-format-v3-to-v4/lib/index.js 的 assertV4SourceRowAdmission /
assertV4MessageSources，编码与解码两条路径都调用——所以既是写不进去、也是读不出来。
compact-checkpoint 与 dsh-compaction 的 COMPACT_CHECKPOINT_MARKER 逐字一致；
TUI/客户端用 isCompactCheckpointSource 只比对它。压缩不变量只作用于「替换型 surface 事件」，
而本插件用 surfaceOp: 'append'，不受 compactionId 配对约束。

同一版还删掉了 Session.events（只剩 snapshotEvents() / ownEvents()），
所以 0.5.0 里遍历 session.events 的兜底读取会 TypeError；0.6.0 改用 snapshotEvents()。

> 提示：这类耦合会随宿主升级漂移。升级 dsh / dsh-tui 之后先跑一遍离线冒烟。

离线冒烟

node smoke.mock.mjs      # 或 npm test

60 项硬断言，失败则 exit≠0，不需要装进任何 profile（用假 ctx）。四道核心回归门：

• 引擎门：假压缩引擎当陷阱，整场跑完断言 engineCalls.length === 0（插件一次都没碰引擎）。
• 决策事件门：断言 listeners 里没有 tui/session-switched。
• V4 生产者 kind 门：本地镜像规则扫过每一条注入消息（kind 非空、≠ plugin、无 plugin
  字段、compactionId 非空）；若本机装了 @deepseek-ai/dsh，还会加载宿主真实的
  assertV4RowAdmission 复核同样这批消息，并做一次「旧形状必须被拒」的反向对照（防止假绿）。
• 会话快照门：假 session 不暴露 events，并构造一条"只存在于会话日志里、插件从没观察到"
  的压缩记录，验证 /compactstats、/carry show 能从 snapshotEvents() 补出历史。

其余覆盖：状态行的计数/进度/待带出/已带出流转、/new 纯净性（没有任何写入动作）、
不重复注入、/carry all|show|off|now、非法参数、carry- 的全局唯一 id、
可选自动版（fork/子会话不注入、延迟调度、监听器绝不抛错）。

已知限制

配置项（index.js 顶部 CONFIG）

许可

MIT