dsh-live-trace 0.1.0

package/README.zh.md

@@ -0,0 +1,790 @@
+# dsh-live-trace
+
+[English](README.md) · **中文**
+
+两扇**只读**的窗口，投向一个正在运行的 DeepSeek Harness 会话，渲染在*不是*运行你
+agent 的那个终端里：
+
+| 命令 | 是什么 |
+| :--- | :--- |
+| **`dsh-live-trace`** | 轨迹面板：轮次、步骤、工具、输出、token 的实时轨迹 |
+| **`dsh-live-working`** | 小鲸鱼：一个动画场景，展示 agent 此刻在做什么 |
+
+两者都通过同一个本地 socket 连接到同一个正在运行的 Harness 进程，并且都不会向 agent
+发送任何东西。
+
+![轨迹面板，含推理、一次 bash 调用及其输出](picture/tui2.png)
+
+![小鲸鱼在打电话，接收子代理的回复](picture/call2.png)
+
+| 思考 | 睡觉 |
+| :---: | :---: |
+| ![小鲸鱼在 room 里思考](picture/type1.png) | ![小鲸鱼在暮色天空下睡着](picture/sleep1.png) |
+
+## `dsh-live-trace` — 轨迹面板
+
+Harness Web UI 展示的是一段对话。这里展示的是*机器*：循环正处于哪个轮次、哪个步骤，
+正在执行哪个工具，返回了什么，模型此刻在流式输出什么，已经运行了多久，以及消耗了多少
+token —— 它持续更新，所以你能一眼看出 agent 是在干活还是卡住了。
+
+```
+┌─ dsh-live-trace ─────────────────────────────────────────────────────────────┐
+│ Session: …8-4222-8d66-0bb3b8c30c45 · live trace demo       Status: ⠇ running │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ 10:19:00 [TURN 3]    ─────────────────────────────────────────────────────── │
+│ 10:19:00 [STEP 1]    model call started                                      │
+│ 10:19:00 [USER]      把登录逻辑抽到 src/auth.ts，并补上测试                  │
+│ 10:19:02 [ASSISTANT] 先读一下现有的登录代码，确认调用点，再决定抽象边界。    │
+│ 10:19:02   [TOOL]      read_file path="src/login.ts"                         │
+│ 10:19:02   [RESULT]    ✓ 返回 234 行  0.2s                                   │
+│ 10:19:03   [TOOL]      bash command="npm test" description="Run the test…"   │
+│ 10:19:03   [RESULT]    ✓ 测试通过 (12 passed)  0.2s                          │
+│ 10:19:05   [APPROVAL]  bash — runs outside the sandbox                       │
+│ 10:19:06   [APPROVAL]  decision: allowed-once                                │
+│ 10:19:06 [STEP 2]    model call started                                      │
+│ 10:19:06 [ASSISTANT] 已完成：登录逻辑抽到了 src/auth.ts，12 个测试通过。     │
+│ 10:19:06 [TURN 3 END] completed                                              │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ ⠇ running   T3 · S2   12.3s     Tokens 4.2K/1.0M (↑3.8K ↓180)   q:quit       │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+四个面板共用同一套外观：
+
+| 面板 | 按键 | 显示内容 |
+| :--- | :--- | :--- |
+| **轨迹** | `1` / `t` | 按时间顺序的事件日志，模型正文按 Markdown 渲染，每次工具调用一个块 |
+| **会话** | `2` / `s` | 每个并发的 `dsh` 会话，实时；有多个在运行时，它也是首屏 |
+| **改动** | `3` / `d` | 模型改过的每个文件，附 unified diff |
+| **命令** | `4` / `c` | 每条 shell 命令及其输出、退出状态和耗时 |
+
+```
+┌─ dsh-live-trace · commands ──────────────────────────────────────────────────┐
+│ Session: …a-412e-ac3d-c0f6a5bc824f · explain the plugin     Status: ● idle   │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ COMMANDS                                                               2 run │
+│ ──────────────────────────────────────────────────────────────────────────── │
+│   ✓ ls -1 dsh-live-trace && echo "--- entry ---" && head -4 …   0.1s  exit 0 │
+│     Inspect the plugin package layout                                        │
+│     README.md  bin  cordis.patch.yml                                         │
+│     … 13 more lines                                                          │
+│                                                                              │
+│ ▸ ✓ cd dsh-live-trace && node --test test/width.test.js …      0.3s  exit 0 │
+│     Run the measurement and tool-helper tests                                │
+│     ✔ every wrapped line fits the width budget (30.5ms)                      │
+│     ℹ tests 22                                                               │
+├──────────────────────────────────────────────────────────────────────────────┤
+│ ● idle   T1   2.9s           Tokens 21K/1.0M   ↓7   1:trace  d:edits  ?:help │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+模型正文按 Markdown 渲染 —— 标题、列表、表格、行内样式 —— 每个围栏代码块都会做语法
+高亮，包括仍在流式输出的文本。**思考默认是收起的**：只显示几行，外加一个标记说明还有
+多少；`e` 会展开所有块。shell 命令按终端的方式显示，命令本身带有语法高亮：
+
+```
+│                      ┊ 先确认 login() 的所有调用点，再决定抽象边界。         │
+│                      ┊ 1. 只有两处直接调用，都在 src/routes/ 里。            │
+│                      ┊ … 5 more lines  e to expand                           │
+│ 11:58:09   [TOOL]      bash Run the test suite  ✓ exit 0 0.2s                │
+│                        $ npm test                                            │
+│                        测试通过 (12 passed)                                  │
+```
+
+`$` 是暗色，命令名用函数色，flag 是属性色，运算符和带引号的字符串各有自己的 token
+颜色。
+
+```
+│                       │ 检查 │ 结果       │
+│                       │ 测试 │ 12 passed  │
+│                       │ lint │ 2 warnings │
+│                       │                                                 bash │
+│                       │ $ npm test                                           │
+│                       │ ✓ 12 passed                                          │
+```
+
+它**不是** TUI 聊天客户端。它从不向 agent 发送任何东西。
+
+---
+
+## 工作原理
+
+```
+┌──────────────────────────── dsh web / dsh headless / dsh tui ─────────────────┐
+│  Host process                                                                 │
+│                                                                               │
+│   Cordis event bus ──► dsh-live-trace plugin ──► TraceHub ──► unix socket     │
+│   session/event                (normalize)      (state)      $DSH_HOME/       │
+│   agent/assistant-stream                                      live-trace/     │
+│   agent/status, agent/error                                   sockets/*.sock  │
+└───────────────────────────────────────────────────────────────────────────────┘
+                                                                     ▲
+                                                    newline-delimited JSON
+                                                                     │
+┌──────────────────────────── another terminal window ─────────────┐ │
+│  dsh-live-trace (separate process, read-only)  ──────────────────┘ │
+│  alternate screen · ANSI renderer · scroll · replay on attach       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**对显而易见的那个设计做一处纠正。** Cordis 插件不是一个独立进程：
+`ctx.on('session/event', …)` 会在运行 Harness 的那个进程内部触发。所以拆成了两部分：
+
+- 一个 **Host 插件**（`index.js`），在进程内观察，并把归一化后的记录发布到一个 Unix
+  域 socket 上；
+- 一个**独立查看器**（`bin/dsh-live-trace.js`），在它自己的终端里运行，连接那个
+  socket 并渲染。
+
+插件在可做到的范围内是最强的只读：它不追加任何会话事件，不注册工具钩子，不改写
+prompt，也从不写 stdout。它只是监听。
+
+选择 Unix socket（而不是 TCP 端口）是刻意的：它无法从另一台主机访问，不会和 Web UI
+的端口冲突，不需要一套认证方案，而它的文件权限本身就是访问控制。
+
+### 实际用到的事件词汇
+
+Harness 发布的事件集合很小且精确。轨迹面板的映射如下；其它都是插件自己的事件类型，
+除非 `showUnknownEvents: true`，否则会被隐藏。
+
+| 来源事件 | 标签 | 说明 |
+| :--- | :--- | :--- |
+| `session/created` / `session/disposed` | `[SESSION]` | 会话生命周期 |
+| `turn/start` / `turn/end` | `[TURN n]` / `[TURN n END]` | 轮次开始会渲染成一条分隔线 |
+| `step/start` / `step/end` | `[STEP n]` / `[STEP n END]` | 每个步骤一次模型调用 |
+| `user/message` | `[USER]` / `[CONTEXT]` | 注入的上下文按其 `source.kind` 打标签 |
+| `assistant/message` | `[ASSISTANT]` | 正文加一段 `thinking:` 摘录；携带 token 用量 |
+| `assistant/attempt` | `[ATTEMPT]` | 一次没有提交任何消息的尝试 |
+| `tool/call` + `tool/result` | `[TOOL]` | **一个块**：名称、它运行的命令、它的输出、`✓`/`✗ exit N` 和耗时。两条记录共享同一个 `key`，所以结果会原地升级正在显示的那一行。 |
+| `tool/result` `meta.diffs` | `[TOOL]` + *改动* | 已应用的文件 hunk；新建文件（此前没有文本）会从这次调用的 `content` 参数重建 |
+| `approval/asked` / `approval/decided` | `[APPROVAL]` | 同时会触发**等待审批** |
+| `session/title` | `[TITLE]` | 同时更新头部 |
+| `permission/preset`, `sandbox/mode`, `approval/policy` | `[POLICY]` | 启动时各占一行 |
+| `agent/assistant-stream` (live) | `thinking` / `writing` | 合并后发布，绝不按 chunk；推理和可见文本各有自己的行 |
+| `agent/status`, `agent/error` (live) | 状态栏 / `[ERROR]` | |
+| `request/context` | *页脚* | 提供上下文窗口的分母 |
+
+总线上没有 `assistant/chunk` 事件 —— 实时流是 `agent/assistant-stream`，它的 chunk
+帧会被累积，并按固定节奏（`streamIntervalMs`，默认 500 ms）发布，这样再快的模型也
+刷不爆终端。持久事件 `assistant/message` 才让流落定。
+
+---
+
+## 安装
+
+它分两半：**插件**，由 Harness 加载，用来发布会话事件；以及**查看器**，也就是你运行的
+那个命令。
+
+### 插件
+
+在 npm 上发布为 [`dsh-live-trace`](https://www.npmjs.com/package/dsh-live-trace)。
+插件必须被你的 Harness 启动时所用的 profile 选中。
+
+**A. 从 npm 安装**
+
+```sh
+dsh plugin --profile web add dsh-live-trace
+```
+
+然后把 `"dsh-live-trace"` 加到 `$DSH_HOME/profiles/web/package.json` 里的
+`dsh.profile.bundles` 中。
+
+**B. 文件级安装器（离线，无包管理器）**
+
+```sh
+node /path/to/dsh-live-trace/scripts/install-profile.mjs --profile web
+```
+
+它会把 `dsh-live-trace` 加进该 profile 的 `dsh.profile.bundles`，添加一条 `link:`
+依赖，并把包软链到该 profile 的 `node_modules`。重启 Harness（或者让热重载自动加载）。
+
+**C. 从本地检出安装，由 pnpm 管理**
+
+```sh
+dsh plugin --profile web add /path/to/dsh-live-trace
+```
+
+然后把 `"dsh-live-trace"` 加到 `$DSH_HOME/profiles/web/package.json` 里的
+`dsh.profile.bundles` 中。这条路径需要 `PATH` 上有 `pnpm`。
+
+要撤销以上任一方式：`node scripts/install-profile.mjs --profile web --uninstall`。
+
+### 查看器
+
+```sh
+npm install -g dsh-live-trace
+```
+
+这会把三个命令放进 `PATH`：`dsh-live-trace`（轨迹面板）、`dsh-live-working`
+（小鲸鱼）和 `dsh-glyph-probe`（打印你的字体能渲染出什么）。如果是从检出目录运行，
+就直接从 `bin/` 里跑，或者手动 link：
+
+```sh
+npm install -g .
+```
+
+不启动任何东西，先验证组合是否正确：
+
+```sh
+dsh --profile web --dump-config | grep -A4 'dsh-live-trace'
+```
+
+### 运行轨迹面板
+
+```sh
+dsh-live-trace
+```
+
+插件加载后，Harness 会在 `$DSH_HOME/live-trace/servers/` 下发布一条发现记录，写明它的
+socket、工作目录和会话。查看器会清理掉已死的记录，优先选择当前工作目录里的进程，并绑定
+到最新的活跃会话。
+
+```
+dsh-live-trace --list                       # what was discovered, then exit
+dsh-live-trace --session <id>               # bind one session
+dsh-live-trace --socket <path>              # bypass discovery entirely
+dsh-live-trace --runtime-dir <path>         # non-default $DSH_HOME
+dsh-live-trace --plain                      # one line per event, pipe-friendly
+dsh-live-trace --wait                       # poll until a Harness appears
+```
+
+### 按键
+
+| 按键 | 动作 |
+| :--- | :--- |
+| `1` / `t` | 轨迹面板 |
+| `2` / `s` | 会话选择器（`esc` 返回到下层那个面板） |
+| `3` / `d` | 文件改动面板 |
+| `4` / `c` | 命令面板 |
+| `tab` | 循环切换面板 |
+| `↑` / `↓` | 滚动轨迹，或在列表面板里移动选中项 |
+| `PgUp` / `PgDn` | 翻一页 |
+| `Home` / `End` | 最早 / 最新 |
+| `enter` | 绑定高亮的会话 |
+| `esc` | 先离开选择器，再离开面板；只有从轨迹里才会退出 |
+| `e` | 展开或收起所有思考块 |
+| `m` | 切换 Markdown 渲染（显示原始源码） |
+| wheel | 任何面板下，滚轮每格滚动三行 |
+| click | 选中指针下的那一行 |
+| `p` | 暂停或恢复跟随新条目 |
+| `r` | 请求插件重放本会话 |
+| `?` | 按键帮助 |
+| `q`, `Ctrl-C` | 退出 |
+
+### 首屏
+
+当有多个会话在运行、又没有给 `--session` 时，`dsh-live-trace` 会打开**会话选择器**
+—— 同时跑着好几个 `dsh` 会话时，做选择是你第一件要做的事。只有一个会话时它直接进入
+轨迹，而显式给出 `--session <id>` 永远优先。
+
+## 多会话切换
+
+Harness 知道的每个会话都会实时列出，带上它的活动、轮次、步骤、安静了多久、标题和工作
+目录。`↑`/`↓` 移动选中项，`enter` 绑定它；插件随后重放该会话的积压内容，所以切换过去
+永远不会看到空白面板。如果你正在跟随的会话结束了，查看器会自动跟随下一个活跃会话。
+
+---
+
+## 配置
+
+每个键都是可选的；插件会防御性地校验，并在取值不合法时回落到默认值，而不是拒绝启动。
+把它们写进 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`：
+
+```yaml
+- id: dsh-live-trace
+  config:
+    enabled: true
+    streamIntervalMs: 500      # 50…60000 — coalesced streaming cadence
+    backlogSize: 2000          # 10…100000 — entries retained per session
+    heartbeatMs: 5000          # discovery/heartbeat cadence
+    replayLimit: 500           # entries replayed to a late-joining viewer
+    showSystemMessages: false  # render the system prompt as an entry
+    showRequestMetadata: false # render request/header as entries
+    showUnknownEvents: false   # render unrecognized plugin events
+    mutedEventTypes:           # `*` is a prefix match
+      - 'session-log-deepseek/*'
+    textLimit: 4000            # cap on one entry's primary text
+    outputLines: 200           # 1…100000 — command output lines retained
+    outputChars: 20000         # 200…1000000 — command output characters retained
+    runtimeDir: null           # override $DSH_HOME/live-trace
+    socketPath: null           # override the derived socket path
+```
+
+插件刻意不声明 `Config` schema：它必须能在解析不到 schema 包的 profile 里加载，而写错
+的选项应该退化到默认值，而不是阻塞启动。
+
+---
+
+## 线路协议（v1）
+
+socket 上跑的是按行分隔的 JSON。每条记录都带 `v` 和 `kind`；未知的 kind 在双向都会被
+忽略，所以任意一半都可以先升级。
+
+**插件 → 查看器：** `hello`（服务器身份、会话列表、活跃会话）、`sessions`、`entry`
+（一行归一化的轨迹）、`stream`（合并后的实时文本）、`stream-end`、`status`、
+`usage`、`edits`、`heartbeat`、`error`。
+
+**查看器 → 插件：** `select`（绑定一个会话；省略 id 表示"服务器的默认会话"）、
+`replay`、`ping`。
+
+一条 `entry` 可以带 `key`；两条 key 相同的记录是同一行，后一条原地替换前一条。工具调用
+和它的落定之所以能保持为一个块、而不是两条半截的行，靠的就是这个。
+
+会话作用域的记录只会到达绑定该会话的查看器，而 `sessions` 记录会按每个查看器实际持有的
+`boundSessionId` 做个性化。没有指定会话的查看器会一直询问，直到出现一个会话，然后跟随
+它 —— 所以在第一个会话出现之前就打开轨迹面板是可以的，而会话结束后视图会交给下一个。
+
+---
+
+## 验证
+
+`npm test` 会运行 243 个测试（`node --test`），包括：
+
+- **渲染器不变量** —— 宽度 24…200、高度 8…60 时，每一帧的每一行都*恰好*等于终端宽度，
+  包括含 CJK 文本、emoji，以及试图注入转义序列的内容。
+- **测量** —— `displayWidth` 把汉字/假名/谚文/emoji 算作两个单元格，把组合字符算作
+  零；折行和截断从不切开一个宽字符。
+- **归一化** —— 每一种被映射的事件类型，外加畸形参数、未知错误和未知事件类型。
+- **Markdown 与高亮** —— 对每种受支持的语言都有一条强制的字符保真不变量；一组文档样本
+  和一轮对抗性 fuzz 在六种宽度下的宽度约束；未闭合的围栏（流式场景）；以及表格。
+- **工具块、diff 与命令** —— 按 key 配对调用/结果、shell 退出状态标记契约
+  （`[exit code: N]`、`[killed by signal: X]`）、diff 元数据的收窄、新建文件的整文件
+  重建，以及反复编辑时按路径累积。
+- **面板** —— 每个面板在每种尺寸下都守住所占宽度精确的契约，并且每个面板都会解释空
+  会话，而不是显示一个空盒子。
+- **窗口化** —— 在每种尺寸和滚动位置下，窗口化的帧逐字节地画出无界渲染会画的行，并且
+  回滚环形缓冲在裁剪时不会丢失它的 key 索引。
+- **输入** —— 方向/导航键、被拆分到多次 read 里的 SGR 鼠标上报、滚轮映射、点击的按下
+  与抬起、移动事件被拒绝，以及未终止序列的有界缓冲。
+- **传输** —— 跨分片的 NDJSON 分帧、按查看器的会话路由、接入时重放、服务器重启后重
+  连，以及拆卸清理。
+- **对真实 Harness 的集成** —— 在真实的 Cordis 上下文里启动随包发布的
+  `@deepseek-ai/dsh-session` 插件，创建并追加真实会话，并断言查看器从一个真实 socket
+  上收到了什么。没有安装 Harness 时它会干净地跳过。
+- **端到端 CLI** —— 针对真实的观察器 socket 启动真正的 `dsh-live-trace` 可执行文件：
+  发现流程、`--list`、备用屏幕面板在 `q` 时退出、捕获输出里 80 列的行宽、plain 模式，
+  以及找不到观察器时的诊断信息。
+- **拆卸后不留东西** —— 三轮 mount/unmount 循环不会累积任何实例、socket 或注册表
+  记录；另一个把一切都启动再 dispose 的独立程序必须**自己退出**，所以一个还活着的
+  socket 或定时器会让它挂住。把这个程序里的 dispose 调用去掉它就会挂住，这就是证明该
+  检查确实有效的反向对照。
+
+在测试套件之外，这个包还针对一个已安装的 Harness 验证过：
+
+1. `dsh --profile web --dump-config` 会组合出插件的配置行，并把用户的 patch 层应用
+   上去。
+2. 一个真实的 `dsh web` 进程会启动插件，插件创建自己的 socket 和发现记录；
+   `dsh-live-trace --list` 能找到它，面板也就接上了。
+3. 一个真实的 `dsh headless` agent 循环（由 `scripts/mock-provider.mjs` 驱动，那是一个
+   离线的 Messages API 服务器）会把真实的轮次、步骤、工具、结果和 token 事件流进
+   面板，其中包括一次真实的 `write`，它实际应用的 diff 会出现在改动面板里。
+
+## `dsh-live-working` — 小鲸鱼
+
+轨迹面板告诉你*发生过*什么。这个告诉你正在发生什么：一只像素画小鲸鱼坐在桌前，桌上有
+键盘、一摞书和一部红色电话，动画会跟着会话变化。
+
+```
+                    ▄█接 2 号子代理████████████████▄
+                    ██把 auth 模块里的校验逻辑抽出来██
+                    ▀██████████████████████████▀
+                       ▄█▀
+                      ▀▀                     ▄▄██▄▄▄▄
+                                             ▀▀▀▀▀▀▀▀    ▄▄
+                                   ████████            ██████▄▄
+                                     ▄▄▀▀              ████████▄▄
+                                   ████████            ████████████
+        ██████████   ▄▄██████████████████▄▄▄▄            ▀▀██████████
+        █        █ ▄▄████████████████████████▄▄▄▄          ████████▀▀
+               ▄▄█████████████████████████████████▄▄    ▄▄██████
+               ██████████████████████████████████████▄▄▄▄██████
+               ████████████████████████████████████████████████
+               ██████████████████████████████████████████████
+               ▀▀██████████████████████████████████████████▀▀
+                 ▀▀██████████████████████████████████████▄▄▄▄▄▄
+                   ▄▄██████████████████████████████████████████
+                   ████████████████████████████████████████████
+ ▄██████████▄      ██████████████████████      ████████████████
+ ████████████      ██████████████████████      ████████████████
+     ██████████████████████████████████████████████████████████████████
+     ██████████████████████████████████████████████████████████████████
+        ███                                                      ███
+```
+
+场景会**按你的终端调整尺寸** —— 最宽到 200 个单元格，小鲸鱼会视可用空间按 1×、2× 或
+3× 绘制，所以宽终端会得到一只更大的生物，而不是同一只漂在巨大空桌子上。像素画只按整数
+倍缩放；非整数倍会产生大小不一的块，看起来像渲染故障。
+
+精灵图是按参考美术的**原生 64×40 像素网格**采样的（那份美术里的块宽为五个源像素），
+所以原图一行都不会丢。源图里鲸鱼上方的灰色痕迹，是一张*睡觉的*鲸鱼插画里的三个 `Z`
+字形 —— 采样时把它们排除掉，于是这只生物落在干净的透明背景上，由场景自己画 `z`，而且
+只在它真的睡着时才画。
+
+### 它做什么，以及为什么
+
+| 状态 | 触发条件 | 动画 |
+| :--- | :--- | :--- |
+| `sleep` | 没有工作；**或者**某条正在运行的命令已经 8 秒没有输出 | 闭眼、慢慢上下浮动、`z` 向上飘 |
+| `thinking` | 推理正在流式输出，或者 agent 正在等待审批 | 手离开键盘，一串思考的点 |
+| `typing` | 正文或代码正在流式输出 | 按键成排亮起 |
+| `writing` | 正在运行 write/edit 工具 | 桌上的一张纸增加一行 |
+| `waiting` | shell 命令正在运行且仍在输出 | 一个带闪烁光标的终端块 |
+| `reading` | 正在运行 read/glob/grep 工具 | **眯起眼睛，每隔几秒眨一次**，举着一本打开的书 |
+| `searching` | 正在运行网络搜索或抓取 | **翻过一页**，从右向左扫过书脊 |
+| `calling` | 启动了一个子代理 | **红色电话被拿起，斜着贴在耳边**，手离开键盘，并出现一个气泡 |
+| `ringing` | 一个子代理结束了 | 电话**响起并震动**，气泡里显示它带回了什么 |
+
+### 两种背景：`room` 与 `nature`
+
+`--scene room`（默认）是一张靠窗的桌子：一堵墙，墙上开着一扇窗，天空被限制在窗格里。
+`--scene nature` 拿掉了墙 —— 背景*就是*户外，于是天气覆盖整个场景，地面一直延伸到屏幕
+底部、桌子就立在上面，针叶树沿地平线排开。任何时候按 `b` 都能在两者之间切换。
+
+两者都由同一片天空构成。窗户和户外都会先在自己的画布上合成内容，再做 blit，所以"任何
+东西都不会跑出分配给它的区域"这条约束对两者都成立。
+
+### 房间
+
+**房间由它的窗户照亮。** 墙面、墙面的明暗、踢脚线和地板每一帧都从天空推导出来，所以
+房间夜里会变暗、正午会变亮，而不是固定的中灰色 —— 黑色天空旁边一块亮灰色板，是夜景里
+最糟糕的一点。墙面从正午的 `181,176,166` 变到午夜的 `64,66,75`，并且从不下探到某个
+下限以下，所以房间始终清晰可读。
+
+这个场景是一个房间，而不是一只漂在终端背景色上的精灵图：一堵带浅色纸条纹的墙，墙与
+地板相接处的踢脚线，以及立在那块地板上的桌子。窗户是**墙上的一个开口**，于是其它一切
+都有东西作为衬托来阅读 —— 尤其是睡觉的 `z`：它以前画在天空上，会消失在云里；搬到墙上
+之后又变成了中灰色墙上的中灰色。现在它有了自己的颜色。
+
+窗户里的一切 —— 天空、太阳和月亮、云、雨、雪、雾 —— 都在窗户自己的画布上合成后再
+blit 进来，所以它们谁都不能飘出这个开口、爬到墙上。
+
+### 窗外
+
+墙上开着一扇窗，窗外是一个按自己的时间运行的世界。**每过一秒真实时间，游戏内就过去
+一分钟**，所以一整天是二十四分钟真实时间，天空也从不静止：颜色从午夜蓝经黎明橙走到
+正午蓝再走回来，太阳和月亮在窗格间沿弧线轮流出现，星星只在夜里现身。
+
+那里也会下雨。天气每三个游戏内小时自行变化一次，取值来自这段天气的序号，而不是随机数
+生成器，所以两个看着同一会话的查看器看到的是同一片天空。它是淡入淡出而不是硬切，并且
+**白天下的雨到夜里就变成雪** —— 同一种天气，只差一个温度。
+
+窗户是一幅画，不是一块色卡：
+
+- **天空是渐变的。** 终端没有 alpha，但它有网格：两种颜色加一个 4x4 Bayer 抖动，让
+  天空在头顶更暗、靠近地平线更亮，并在黎明和黄昏把地平线染暖、同时顶部保持冷色。两种
+  平涂颜色看起来是一条色带；加上抖动才像天空。
+- **有山。** 窗格底部一道起伏的山脊让这扇窗有了归属，太阳和月亮沉到它后面。
+- **太阳和月亮有光晕**，经过抖动，所以是淡出而不是戛然而止。
+- **云是积云**：三个互相重叠的椭圆，下面一边是平的 —— 不是它们最初那样的横条。
+- **雾是一片薄霭，不是一条带。** 它覆盖窗格的四分之一而不是三分之一，最多只填一半，
+  越往上越稀，颜色取自天空而不是固定的浅灰 —— 所以它融进天气里，而不是看起来像一条
+  灰条纹。实测下来，它从占窗格的 23% 降到 5%。
+- **星星有两种亮度**，各按自己的节奏闪烁。
+
+天气会**从天空里抽走光**：晴天的正午是 765 中的 535，多云 439，下雨 331，暴风雨 240。
+恶劣天气还会遮住太阳或月亮，这正是它看起来"恶劣"的原因。只有天空真正暗下来时星星才会
+出现 —— 若改成按昼夜阶段来决定，就会在明亮的橙色黎明里点出白点。页脚显示游戏内时钟和
+当前天气。
+
+**雨可以下出声。** `--sound`（或任何时候按 `n`）会通过 `aplay`、`paplay`、`sox` 或
+`ffplay` 中已安装的那个播放雨声，而且只在真的下雨时播放。它**默认关闭**，因为一条会
+自己开始放声音的命令，是那种人们会不再运行的命令。
+
+**音量是单独的一项控制。** `--rain-volume <0-100>` 设定它（默认 `40`），命令运行期间
+`-` 和 `+` 每次调整 5，页脚会在声音状态旁边显示当前音量。它从 40 而不是满量程起步是
+刻意的：那段录音的峰值是 -6.1 dBFS，属于前景音量；而在 40% 时峰值约 -14 dBFS —— 是
+环境音，而不是需要关掉的东西。合成的噪声按同一比例缩放，所以平均采样值从 2023 变成
+809（峰值从 5898 到 2359，从 -14.9 到 -22.9 dBFS）：同样的雨，只是少一些。
+
+除了一条路径，音量在所有路径上都能到达扬声器。在 **file** 模式下 `paplay` 收到
+`--volume`，`sox` 收到 `-v`，`ffplay` 收到 `-volume`；合成流把音量做进自己的采样里，
+所以每个播放器在那里都遵守它。**`aplay` 根本没有音量参数**，所以通过 `aplay` 播放的
+录音，听到的就是它被录制时的音量。这一点没有被悄悄忽略：页脚会写
+`aplay cannot change a file level`，而不是打印一个会撒谎的百分比。如果你在一台只有
+`aplay` 的机器上想要更安静的录音，就传一个更安静的 `--rain-file`，或者装上 `paplay`、
+`sox` 或 `ffplay`。
+
+默认音源是随包附带的那段录音。`--rain-file` 可以指定别的。如果文件不存在 —— 或者资源
+读不出来 —— 就会回落到**合成**噪声：一段经过低通的伪随机采样流，永续播放，没有循环点。
+正是靠它，这个功能在一台只有一个播放器的机器上也能用。
+
+录音播放期间改变音量会重启播放器，因为音量存在于它的命令行里；合成流则会在下一个块
+无缝地采用新音量。
+
+改变音量会重启播放器，因为音量是它的一个参数。旧播放器会先被停掉，但它的退出事件是在
+新播放器已经跑起来*之后*才到的 —— 所以状态更新只在来自当前那个进程时才被接受，而所有
+启动过的进程都会被跟踪并一起杀掉。两者缺一，改一次音量就会留下两路雨声在响，以及一个
+在命令退出后还在继续的孤儿播放器。
+
+一个刚启动就死掉的播放器说明没有音频设备；它会重试三次，然后就不再管它，而不是永远重启
+下去。
+
+**包里附带一段雨声循环。** `assets/rain.ogg`（30 秒、单声道、64 kbps、242 KB）是默认
+音源，所以 `--sound` 不需要任何参数。它是从那段 8 小时的录音
+`42130539966-1-192.mp4`（其音频为 aac 48 kHz 立体声）的一小时处剪下来的，并把尾部
+交叉淡入到开头，让循环没有咔哒声：两端音量相差在 20% 以内，接缝处的采样落差是全量程的
+0.35%。它的峰值是 -6.1 dBFS；在默认的 40% 音量下约为 -14 dBFS。`--rain-file` 可以
+覆盖它。
+
+**关于这个目录里那个 2.2 GB 的 `42130539966-1-192.mp4`：** 它不是包的一部分
+（`package.json` 的 `files` 列表里没有它，`.gitignore` 也忽略了 `*.mp4`），而这台机器
+上没有 `ffprobe`、`ffmpeg`、`aplay`、`paplay`、`sox` 或 `mpv` —— `ffplay` 倒是有，
+但它只能播放文件、不能检查文件 —— 所以这个视频在这里既看不了也放不了。`--rain-file`
+接受的是音频文件；`.mp4` 是视频容器，得先把音轨抽出来，而那需要 `ffmpeg`：
+
+```
+ffmpeg -i 42130539966-1-192.mp4 -vn -ac 1 -ar 44100 rain.wav
+dsh-live-working --sound --rain-file rain.wav
+```
+
+要放真实录音，就传 `--rain-file`；`--rain-volume` 在所有带音量参数的播放器上对它依然
+有效：
+
+```
+dsh-live-working --sound --rain-volume 25 --rain-file ~/sounds/rain-loop.wav
+```
+
+不存在的文件会被放弃并回落到合成噪声，而不是变成静音。`ffplay` 原生支持循环播放文件；
+其它播放器会在文件结束时被重启，但只在还在下雨的时候。授权由你判断、也由你负责 ——
+本项目自己不分发任何音频：
+
+- [Wikimedia Commons: Sounds of rain](https://commons.wikimedia.org/wiki/Category:Sounds_of_rain) —— 自由许可，逐文件条款
+- [Freesound](https://freesound.org/) —— 按许可证筛选；CC0 无需署名
+- [Creazilla: Ambience Rainstorm](https://creazilla.com/media/audio/15525146/ambience-rainstorm) —— 免版税
+- [Internet Archive: Red Library — Nature Rain](https://archive.org/details/Red_Library_Nature_Rain)
+
+```
+工作台 · 等待命令   06:13 雾            c4c9e25b082a  T23·S19  关闭本帮助:?
+```
+
+### 小鲸鱼自身的动作
+
+- **尾巴是画出来的，每个状态一个姿态。** 源美术只有一条竖直的尾巴，没有可动的地方：
+  尾鳍顶到身体的最后一行和精灵图的右边缘，而桌子就压在最后一行上。对着它试过六种
+  变换 —— 剪切、折叠、旋转、锥形剪切、整体平移、水平折叠 —— 每一种都只是把一种瑕疵
+  换成另一种：边缘毛糙、轮廓撕裂、尾巴跑到桌子下面、桌子上面多出尖角，或者透出背景的
+  空洞。现在有**两个姿态**，由身体加一条尾巴组合而成：
+
+  - `up` 直接从源美术里逐像素取出，所以醒着的小鲸鱼就是参考图画的那个样子；
+  - `sleep` 是画出来的：尾鳍垂下来，沿身体贴在桌线处，末端收成圆头；它的边缘是生成
+    出来的，而不是丢给渲染器去猜。
+
+  画出来的姿态不会丢像素、撕裂或留下空隙 —— 这些故障在结构上就不可能发生，而不只是被
+  修好了。
+
+- **醒着的尾巴从根部摆动。** 以前整条尾巴是刚性平移的，这会让它离开身体、从接缝处透出
+  背景；现在最靠近身体的那些列被锚定，只有外面的一部分摆动，于是尾巴是绕轴转，而不是
+  平移。小鲸鱼打电话时它保持不动，因为鳍正忙着。
+
+- **夜里它会揉眼睛** —— 工作期间时不时闭上眼、把一只鳍抬到脸上，然后接着做原来的事。
+  只在夜里，而且睡着或打电话时绝不会。
+
+### 桌子
+
+桌子是"搭"出来的，而不是贴上去的：键盘是桌上一小条深色横条，而**右上角一个带边框的
+窗口显示正在输入的文本** —— 模型输出的尾部，或者它正在运行的工具的参数。有文本时就会
+画这个窗口的边框，因为没有边框的文本看起来像一个漂在终端顶部的野气泡。
+
+小鲸鱼打字时**鳍会动**，用的是一种和身体略有色差的蓝，这样这条肢体才看起来像肢体。
+采样的参考美术是侧视图，没有单独的胸鳍，所以这些划水的鳍是画上去并叠在按键上的动画；
+**睡着时它们会被收起来**。打电话会完全停止打字 —— 听筒贴在脸上，上到眼睛、下过下巴，
+而不是横在身体上或者直立在桌上。
+
+书是有明暗的，这正是让翻页看起来清楚的原因：摊开的两页受光不同，中间的书脊落在阴影
+里，而翻到一半的那一页是侧对着的，比两边都暗。
+
+电话气泡上写的是 `接 N 号子代理，<instructions>`（英文下是
+`Subagent #N — <instructions>`），其中 N 是本会话里子代理的序号，instructions 是这次
+调用收到的参数。
+
+### 电话
+
+派发一个子代理就是一通电话，整个交互都是照这个来建模的：
+
+- **气泡显示的是调用原本写成的样子**，不只是里面的指令：
+  `task(description="…", prompt="…")`，连工具名和每一个参数一起。同时有多个子代理在
+  外面时，抬头会变成一个队列 —— `接 3 号子代理（共 5 个，排队 2 个）`。
+- **消息是一个字一个字"说"出来的**，气泡一次显示三行。更长的消息会滚动。抬头被钉在
+  上面：它说明电话那头是谁，若被长指令挤掉，气泡就变成了无名的。
+- **子代理挂断时电话会响。** 听筒震动，电话两边出现铃声弧线，气泡显示子代理自己的收尾
+  文本 —— 它的回答，而不是对回答的概括。
+- **后台派发是"收到"，不是"回答"。** 在后台启动一个子代理会立刻返回
+  `started subagent <id>`；回答稍后作为那个 agent 的消息到达。只有后者才算数，所以后台
+  子代理会保住它在队列里的位置，而不是一启动就好像已经结束。
+- **听筒是被拿起和放下的**，不是瞬间移动：它从容地离开支架，旋转到耳边，放下时沿同
+  一条路径返回，电话线随着它升起而松开。
+- **历史不是新闻。** 查看器启动时会重放积压内容，而每条记录都带自己的时间戳。若改用
+  墙上时钟给事件打时间戳，一小时的历史看起来就像全都正在发生，于是电话会为几分钟前就
+  已经结束的子代理响起来。现在每个时间戳都来自事件本身。
+- **活派出去、没别的事可做，就是打个盹。** 子代理在外面、又没有别的工具在跑时，小
+  鲸鱼就像空闲时一样在桌前打盹，而叫醒它的是响起的电话。
+
+气泡锚定在小鲸鱼头顶上方，尾巴指向说话者，并会裁剪以避开预览窗口。一个钉在场景角落的
+对话气泡什么都没指着，看起来就像一个漂在界面外的野盒子 —— 这正是它两次被反馈的问题。
+
+```bash
+dsh-live-working                    # follow the server's default session
+dsh-live-working -s <session-id>    # follow a specific one
+dsh-live-working --state reading    # pin one animation, ignore the session
+dsh-live-working --list             # show observers and sessions
+```
+
+有多个会话在运行时，它打开的是**会话选择器**，而不是去猜你指的是哪个；`s` 重新打开
+它，`↑`/`↓` 选择，`enter` 绑定，`esc` 取消。
+
+按键：`1`-`8` 固定某个动画，`0` 回到自动，`s` 选择会话，`n` 开关雨声，`-` 和 `+`
+调整雨声音量，`l` 切换语言，`?` 开关帮助，`q` 退出。
+
+```
+dsh-live-working — a live orca animation for a DeepSeek Harness session
+
+States: sleep, thinking, typing, writing, waiting, reading, searching, calling
+```
+
+`node scripts/demo-working.mjs` 会循环播放每一个状态，不需要会话；
+`node scripts/demo-working.mjs reading` 则固定在某一个状态。
+
+### 一个终端单元格能承载多少分辨率
+
+一个字符单元格的高度大约是宽度的两倍，所以选哪种字形，同时决定了像素的分辨率和*形状*：
+
+| 打包方式   | 每格像素    | 像素形状    | 字形                  | 说明                                     |
+| :--------- | :---------- | :---------- | :-------------------- | :--------------------------------------- |
+| `half`     | 1 x 2       | 正方形      | `▀ ▄ █`               | 这个轨迹面板用的就是它                   |
+| `quadrant` | 2 x 2       | 1:2 高      | `▘ ▝ ▖ ▗ ▚ ▞ ▛ ▜ ▙ ▟` | 边缘更细，但一切都拉长了                 |
+| `braille`  | 2 x 4       | 正方形      | `U+2800..U+28FF`      | 像素是 4 倍，但每一个都是一个点          |
+
+`half` 是唯一既**正方形**又**实心**的打包方式，而实心像素画正需要这个。`quadrant` 把
+横向数量翻倍，但它的像素高是宽的两倍，所以为正方形像素画的图会显得被拉长。`braille`
+用正方形像素给出四倍的像素，但点与点之间有间隙，所以实心区域会填成点画 —— 画图表很好，
+画鲸鱼很差。
+
+它们能不能用取决于你的字体，而缺少这些字形的字体不会大声报错：它会替换成方框或空白，
+于是画面悄悄散架。所以先看一眼：
+
+```
+dsh-glyph-probe
+```
+
+它会打印每种打包方式的样例，以及一个按该打包方式自身分辨率栅格化的圆盘。看起来圆润
+无缝的那个圆盘，就是你的字体支持的那一种。
+
+### 程序能让终端字体变小吗？
+
+**不能。** 没有这样的转义序列。`ESC[?3h` 只是在 80 列和 132 列之间切换，并不改变
+字体，而 VTE/GNOME Terminal 根本没有办法做到 —— 这可以直接从[源码讨论](https://stackoverflow.com/revisions/0162962e-7b66-4d60-8df4-4278446e6220/view-source)里读到。kitty 的[文本缩放协议](https://github.com/kovidgoyal/kitty/blob/f13c8cd4/docs/text-sizing-protocol.rst)缩放的是单段文本，而且只适用于 kitty。
+
+即便在可能生效的地方，把它交给应用去管也是一笔坏交易：一次崩溃、一个 `SIGKILL`、一个
+被关掉的终端或一次断开的 SSH 会话，都会让字体留在小号状态，而没有任何东西能把它恢复。
+
+终端*愿意*做的是**报告自己的几何尺寸**，而这一半是值得要的 —— `CSI 16t` 返回以像素
+为单位的单元格尺寸，`CSI 14t` 返回文本区域。`dsh-glyph-probe` 两者都问，并做这道
+算术：
+
+```
+Cell size      9x18 px   (aspect 0.50)
+Cells          148x40
+Drawing budget 11,840 pixels (two per cell)
+Half the font  333x80 cells -> 53,280 pixels
+```
+
+把字体缩小并不改变窗口的像素；它改变的是能塞进这些像素的**单元格**数量，而每多一个
+单元格，就多两个像素的绘制预算。那才是真正的收益，而且这份收益该由用户自己去拿。
+
+在伸手去够更高分辨率的打包方式之前，有两件事值得知道：
+
+- **鲸鱼就是它源文件的分辨率。** 参考美术是一个 64x40 的精灵图，给不出更多细节；放大
+  它只会得到更大的块。想要更精细的鲸鱼，需要更精细的美术，而不是更精细的渲染器。
+- **场景已经占满终端。** 它最宽按 200 个单元格渲染，并且用满它能用的每一行，所以想更
+  精确，最便宜的办法是开一个更大的窗口 —— 不管用什么字形，单元格更多就是像素更多。
+
+## 两个会话列表都以标题开头
+
+`dsh-live-working` 的选择器和 `dsh-live-trace` 的会话面板都把会话标题放在最前面，缩短
+过的 id 跟在后面。id 是你要输入的东西，而标题并不唯一，所以两者都显示 —— 但能让你认
+出来的是标题，所以它排在前面。没有标题的会话回落到它的 id。
+
+## 曾经是 bug 的布局规则
+
+- **实时思考是一个块，不是一行。** 仍在流式输出的推理会折行并尾部优先显示，收起时深度
+  为 `--thinking-lines`，展开时是它的四倍。它以前只是一行，装着整个块最后几个字符，
+  偏偏在你想看的时候完全没法读。
+- **实时思考会走 Markdown 渲染器。** 它以前按纯文本折行，于是 `**bold**`、反引号和
+  `[links](url)` 都按字面语法显示，而它下面已经落定的块却会把它们渲染出来 —— 同一段
+  推理，两种格式。
+- **头部永远不会弄丢会话。** 各段带优先级：会话 id 和状态标签是必需的，永远不会被丢掉；
+  标题、路径和错误文本会被丢弃 —— 先丢标题 —— 然后宁可缩短状态文本，也不把会话挤掉。
+
+## 性能
+
+`npm run bench` 用不断增长的日志来渲染帧。因为一帧只显示尾部，每帧的开销必须保持平坦：
+
+```
+entries=    50  per-frame=   2.3ms
+entries=  1000  per-frame=   2.9ms
+entries= 10000  per-frame=   9.2ms
+```
+
+早先的实现每一帧都渲染所有条目 —— 3000 条时每帧 2100 ms，这就是长会话里滚轮感觉卡的
+原因。最坏情况超过 30 ms 时，基准测试会失败。
+
+### 离线复现实时演示
+
+```sh
+node scripts/mock-provider.mjs &
+DSH_HOME=/tmp/dsh-demo dsh --profile headless "explain the plugin" &
+DEEPSEEK_BASE_URL=http://127.0.0.1:8799 DEEPSEEK_API_KEY=sk-mock dsh-live-trace
+```
+
+### 不启动任何 Harness 也能看到面板
+
+```sh
+npm run demo          # scripts/demo.mjs — a scripted trace on the real renderer
+```
+
+---
+
+## 设计说明
+
+- **零运行时依赖。** 渲染器是手写的 ANSI，而不是 `blessed`/`chalk`。`blessed` 测量
+  CJK 有误（Harness 的主要用户写中文），不再维护，而且会迫使 profile 里做一次联网
+  安装；基于 `Segment[]` 的渲染器把颜色挡在字符串解析之外，也让 80 列的契约不需要 TTY
+  就能测试。
+- **插件无法弄坏 agent。** 每一次 hub 调用都被包住，所以观察器的一个 bug 只会变成丢一
+  行，而不会变成一次失败的轮次。什么都不写 stdout —— 它属于 Harness 正在驱动的那个
+  界面。
+- **清理由 Cordis fiber 负责。** 每个 `ctx.on` 的 disposer 都被收集，每个定时器都被
+  清除，socket 被关闭并 unlink，发现记录被删除 —— 但仅当它仍然是我们的：这样一代热重
+  载就不会删掉它继任者的记录。
+- **重复会被折叠，而不是隐藏。** 连续相同的条目只渲染一次，显示为 `×N` 并带上最新的
+  时间戳。
+- **每次工具调用一行。** 插件给一次调用和它的结果同一个 `key`，并在结果落定时打上
+  耗时，所以轨迹里每条命令是一个块，而不是两行等着读者自己去配对。
+- **推理和输出是分开的。** 它们是两样不同的东西，所以实时指示器各给一行，而不是一个
+  覆盖另一个。
+- **一帧只渲染它显示的内容。** 轨迹是底部锚定的，所以渲染器从后往前走条目，直到覆盖住
+  窗口，并按身份缓存每个条目的行。两者都需要：窗口化给工作量封顶，缓存让稳定的重绘几乎
+  不花代价。
+- **鼠标是刻意接管的。** 很多终端把滚轮上报成方向键，这与按键无法区分，而且每格只滚一
+  行。用 SGR 坐标接管鼠标能让滚动变精确；`--no-mouse` 会把旧行为还回来，而 Shift+拖拽
+  依然可以选中文本。
+- **已用时间指的是当前轮次**，没有打开的轮次时则是处在当前状态的时间。对恢复过的会话来
+  说，会话总时长会产生误导。
+
+## 限制
+
+- socket 传输只支持 Unix 域；Windows 命名管道没有实现。
+- `--plain` 模式会打印条目，但不打印实时流预览。
+- 页脚里的 `S<n>/<m>` 中，分母是当前轮次里见过的最大步骤号，而不是计划总数 ——
+  Harness 不发布计划总数。
+- diff 面板没有行号：Harness 上报的是带三行上下文的已应用 hunk，而不是位置区间，所以
+  凭空造行号就是在猜。
+- Markdown 渲染是一个专门做的子集（标题、列表、表格、引用、分隔线、围栏、行内样式），
+  配一个自带的、支持 14 种语言的高亮器，不是完整的 CommonMark 实现。任何时候按 `m`
+  都能看到原始源码。
+- 模型**新建**的文件是从调用的 `content` 参数重建的，因为新建没有此前的文本，也就没有
+  hunk。
+- 轨迹面板在设计上就是只读的：没有办法从它那里批准、取消或干预。
+
+## 许可证
+
+MIT