# 0.8.2-rc.1 发版说明（候选版）

> **发布方式：只上 `next`。** 这是候选版（RC）：`latest` 保持 **0.8.1**，只有显式装 `@next` 或指定
> 版本号的人才会拿到它。上一次发版：**0.8.1**（2026-09-30，`latest` + `next`）。
> 这一版是**架构收尾 + 稳定性**：把 0.8.x 期间分批落地的终端架构（screen / 表示管线 / 工作区区域）
> 冻结下来，并修掉两处**只有全新安装或弱链路才会遇到**的问题。

## 头等事：全新安装**第一次就会出现配置向导**（此前根本不会出现）

0.8.1 及以前，一台**没有任何配置**的机器上装好插件、启动 `dsh --profile tui`，看到的是：
一个空工作区、一行都没有的提示，模型调用必然失败 —— **配置向导永远不会自动出现**。

原因不在向导本身（它是好的），而在触发它的判断：前端拉起后台 Host 时**永远**带上
`--resume=<id>`（连它自己刚生成的那个新 id 也带），而首启判定把 `--resume` 当成"这台机器配置过"，
于是直接跳过了首启流程。

0.8.2 起这条判断只看**凭据存不存在**：没有凭据、环境里也没有 key，就是首启，向导自动打开（Enter 走步骤、
Esc 随时退出），并且工作区会同时留下一行说明告诉你怎么手动重开 `/setup`。**第二次启动不会再出现**。

这同时修掉一个连带问题：向导不再借用 composer 的输入框。0.8.1 里进入向导会**清掉你已经打了一半的草稿**；
现在向导有自己的字段、自己的光标，工作区里的草稿、历史、正在进行的输入一个字都不动。

## 工具卡与输入法：两处"画面串行"的修复

- **工具卡内容含多行代码时不再窜到输入区**。`bash` 卡片的标题就是命令行原文，遇到 heredoc（`<<'PY'`）会带
  着换行进入"一行"——终端因此真的换了行，而这一版之前按绝对行号绘制的帧随后把下面每一行都写错位：卡片内容
  落在输入框和页脚上，甚至两段文字拼在同一行。现在标题行会把换行折成空格，单行裁剪器也不再把换行交给终端。
- **Windows Terminal + 微软输入法：预输入不再在处理中卡片那一行闪烁**。终端把输入法的预输入画在光标处，
  而"写一行"会把光标留在该行末尾；跑一轮时实时区域每 tick 重画又正好在输入框上方，所以光标停在处理中卡片
  上。现在每写完一行就把光标交还输入框，预输入只会出现在它该在的地方。

## resume 不再黑屏，思考卡片不再"发白"，`q` 真的能关掉报告

- **resume 进入时的 1–3 秒黑屏**。前端先在备用屏打出"正在载入历史会话…"，relay 接入时宿主又写了一次
  `?1049h`——终端已经在备用屏时这个序列会**清屏**，而重建会话日志期间按设计不合成任何帧，于是那块加载
  提示被擦掉、屏幕空着，直到历史重建完成（实测 20k 事件：9.1 s 清屏、12.6 s 首帧落地，中间 3.5 s 全黑）。
  现在这条"进屏"序列跟着第一帧一起发出，同一 tick 内清屏并重画；没有东西要等的重连行为不变。
- **思考卡片的文字不再发白**。"思考 / 已思考"这一角色此前只写 `2;3` 两个**属性**、不写颜色——"暗"完全
  靠 faint，而不实现 faint 的终端（报告的 256 色终端）于是退回**默认前景色**，看起来和旁边的回复一样亮。
  四个调色板现在各自给出 muted 颜色，属性保留给支持的终端（`mono` 仍然只用属性）。
- **`q` / `Q` 能关掉报告**。`inspectClosesOn` 一直声明接受它们（"全屏报告理应响应 q"），但可打印字符的
  提示分支在它之前返回，于是这两个键只会打印"这是报告视图，按 Esc 返回"。

## 状态行不再把"绘制节奏"当成"链路延迟"

现场报告（`/diag`）：Linux + xterm-256color + SSH，`探测 未知（终端未回 DSR）`——这台终端**多数时候不回答
`CSI 6n`**，于是状态行常年显示 `SSH ○○○○ 160ms`。两个部分要分开看：

- **空心圆是对的**：没测到往返就是 `unknown`，不该假装知道链路好坏。
- **`160ms` 是错的**：那不是延迟，是**回退的绘制节奏**（探测不到时用的安全默认值）。它出现在"延迟"该在的
  位置上，读者无法分辨"离我 160ms"和"从来没测过"。这一格现在改为 `SSH ○○○○ 未测` / `SSH ○○○○ n/a`；
  测到过的链路照旧显示真实值，绘制节奏仍然出现在 `/diag` 那一行、并且写明是"绘制"。

另外两个"看起来像 bug"的现象是设计使然，不是缺陷：

- **有回 DSR 时数值也不怎么动**：显示的是最近 3 次测量的**中位数**，重测间隔 20 秒；稳定的 SSH 链路上
  中位数本来就该是一条直线。Windows 本机之所以看得见跳动，是因为那些数字只有 1–12ms，同样抖动在两位数
  里显得大。
- **连续 3 次探测失败后不再每 20 秒重试**：退避到 10 分钟——避免"不回答 DSR 的终端被永远每 20 秒扫一次"。

## 命令提示会自己让位（排队提示除外）

命令的确认（"已复制 412 字"）与警告（命令失败）从此**显示约 6 秒后自动让位**，恢复原来的遥测行；按 Enter
提交仍会立刻清掉。**唯一的例外**是"运行中已提交，将在下个步骤生效"这条：它显示到那条消息**真正被提交**
为止——它是"你有话在排队"的唯一标记，提前消失等于把排队这件事藏起来。

## 弱链路 / SSH：画面更稳，流式不再整屏重画

这一版把 0.8.x 期间逐块落地的渲染架构冻结下来，对**远程、跳板机、弱网**最直接的三条：

- **流式输出不再每个 tick 整屏重画**：正在生成的回复是一个**投影**，不再是往历史里追加行，所以每个
  token 批次只重画它自己那几行。实测（100×20）：一次流式 delta 寻址 **3 行 / 478 字节 / 0 次全屏清屏**。
- **报告不再污染对话记录**：`/status`、`/help`、`/doctor`、`/subagents`、`/diag` 现在是**独立的屏**，
  打开不改变历史窗口位置，翻页只重画正文，Esc 回到你原来的位置，也不会在重连后被重新画出来。
- **断线重接后表示一致**：提问、审批、计划三种卡片从**会话日志**折叠出来，因此掉线重接、换窗口、
  `--resume` 之后读到的状态与当时一致，而不是"重连后多出一张卡"或"状态回到未知"。

## `/clear` 只清可见视图

`/clear` 不删除任何东西：不删会话日志、不动模型上下文、不动计划 artifact。它只是把**可见视图**切到
当前时刻之后（并且用一行提示告诉你这件事）。`/resume` 进来仍然是完整历史。`/find` 只在你**看得见**的
范围里搜索，这一点也在提示里说明。

## 计划与实时处理的抢占关系

计划条（Plan Dock）不再被"处理中"的实时区域盖住：实时区域现在是**自己的行**，而不是画在历史上面。
计划条高度上限为工作区一半，所以它不会把输入框和光标挤出屏幕（中文输入法的预输入串也不会再落到
计划卡上）。终端很矮时计划条按三档降级（完整 / 紧凑 / 极简），不会直接消失。

## 反馈去哪了（"我执行了命令但没有任何提示"）

- 控制面的确认（切主题、切视图、preset 写入…）进**页脚**，显示到下一次输入为止；
- 警告与失败进**身份行**（原来 `目录:` 那一行），不盖住你正在读的内容；
- 只有**会改变历史**的事实才进对话记录。
  页脚挤不下时确认会退到身份行显示，所以再也不会有"执行了但什么都没有"。

## 上游 400：现在会告诉你它是什么

`command-code` 这类思考模式网关偶尔会**成串**拒收请求（实测：一次长会话里 13 个失败轮次中 12 个是这种），
以前你只看到一行原始错误。现在：

- 明确说出**网关拒收的是请求本身、不是你的 key**；
- 指名已知的那一族缺陷（上游 #1780 / #231，思考模式的 reasoning 回传）；
- 给出可操作的两条绕法（该路线 `/effort off`，或换同一网关的 command-code-messages）；
- **不会自动重试** —— 实测这类失败会成串出现（连续 8 轮），重发通常值得，但同一个请求确定性失败时
  自动重试会白花一整段上下文。什么时候重发由你决定。

## 数字（本版实测，100×20）

| 动作 | 毫秒（中位） | 字节 | 寻址行 | 全屏清屏 |
|---|---|---|---|---|
| 流式 delta | 1.43 | 501 | 3 | **0** |
| 等待卡时钟 | 1.25 | 465 | 3 | **0** |
| 报告屏翻页 | 1.19 | 2457 | 17 | **0** |
| 菜单光标移动 | 0.97 | 588 | 4 | **0** |
| 向导字段打字 | 0.22 | 140 | 1 | **0** |

发版候选（`c2fe073`）自检，逐条可复现：

| 自检 | 结果 | 命令 |
|---|---|---|
| 冻结不变量 | 八条全绿 · 七条退役路径 **0 命中** | `npm run freeze` |
| 性能基线 | 上表五行 · 全部 **0 次整屏清屏** | `npm run bench` |
| 全套测试（Linux） | 1376 项 · **1372 通过 · 0 失败 · 4 跳过** | `npm test` |
| 全套测试（Windows 实机） | 1376 项 · **1365 通过 · 0 失败 · 11 跳过**（跳过均为平台互斥用例） | `npm test` |
| 打包 | **243 个文件** · tarball **1.4 MB** · 解包 **4.2 MB** · shasum `92b7f517…` · 无凭据 / 无 home / 无 sqlite | `npm pack --dry-run` |

跳过只代表"这台机器上没跑"，不代表通过：`verify-batch` 见到 `SKIP:` 就收尾 `INCOMPLETE`（见
[`release.md`](release.md)）。

## 兼容

上游兼容窗口与 0.8.1 相同（`0.2.0-rc.1` / `0.2.0-rc.2` / `0.1.7-rc.1` / `0.1.7-rc.2`）。
这一版**不改协议、不加命令、不动上游接口**。

## 安装 / 升级

```sh
dsh plugin --profile tui add dsh-ssh-tui@0.8.2-rc.1
```

装完退出再启动。`/status` 可确认当前版本；装不上先看 `/doctor`。

## 已知限制

- **Windows / ConPTY 实机人工验收：已完成（2026-10-03，维护者）**。用一份单独安装的 CLI dsh 逐条走过
  12 项清单，逐项结论见 [`checkpoints.md`](checkpoints.md)「Windows 实机轮」。分三类：
  **可自动化的部分全绿**（`verify-batch --home <dir>`：12 PASS · 2 SKIP · 0 FAIL）；**两处 ConPTY 盲区**
  明确打印 `SKIP:` 并附理由（ConPTY 自己回 `CSI 6n`，"慢链路"与"终端静默但没断连"这两个形状它扮演不了）；
  **没有自动化、只能人眼的两目已由维护者确认通过**——微软拼音 IME 组合、多行中文粘贴（清单与走法见
  [`release.md`](release.md)「发布前人工门槛」）。两处 `SKIP` 是**覆盖边界**，不是通过：它们
  **在 Linux 腿上是真跑的**（`link` 第一段、`cut` 的"静默终端"那一半），在 ConPTY 上才无信号。
- **`未测` 那一格在 Windows 本机看不到**：ConPTY 代答光标位置，本机链路芯片因此永远是"已测量"。
  该形状由 `scripts/tui-unmeasured-probe.mjs` 用管道父进程覆盖（两条腿：不回话读 `未测`、每条必答读
  真值），已进 CI 两条腿。
- **拖放探针此前约 1/7 概率误报**（探针自身与自己的 `/status` 重试竞态，不是产品行为）。本版已修，
  并连跑 20 次验证。
- `--resume` 与首启的关系见上文：本版修的是"新机器不显示向导"，不是"resume 不再触发向导"。
- 依赖旧版 inbox 通知（inbox P3）与新协议的命令不在本版范围内。