dsh-large-proj-perf 1.16.0 → 1.16.1

package/CHANGELOG.md

@@ -12,6 +12,9 @@
 > [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md)。下文提到的
 > `RUNTIME-ANALYSIS.md` / `MEMORY-ANALYSIS.md` 已于 1.10.0 并入 MEASUREMENTS，
 > 路径只作文物引用。
+>
+> **版本号规则见 [docs/VERSIONING.md](docs/VERSIONING.md)**：版本在发布时决定，
+> 开发中的变更先记在 `[Unreleased]`，不逐次改 `package.json`。
 
 ## 重要版本速览
 
@@ -40,6 +43,27 @@
 
 ## [Unreleased]
 
+<a id="v1-16-1"></a>
+## [1.16.1] — 2026-11-14
+
+文档与元数据修补：补上渲染优化的能力/效果描述，并把版本号策略写进文档。
+**行为零变化。**
+
+### 文档
+
+- 新增 [docs/VERSIONING.md](docs/VERSIONING.md)：**版本号只在发布时决定**；记录
+  npm 序列 `1.4.0 → 1.10.1 → 1.16.0` 的跳跃原因；`engines.dsh` 收紧一律算 MAJOR。
+- `docs/PUBLISHING.md`、README、本文件指向该策略；`tests/verify_docs.mjs` 增加
+  `package.json` ↔ CHANGELOG 首条版本的一致性断言。
+
+### 元数据
+
+- `package.json` 的 `description` 与 `locale/{zh,en}.json` 补上浏览器侧离屏行
+  containment 的效果（批量翻页阻塞约 −47%）与渲染耗时诊断。
+- README 的「最近重要更新」补 1.12.0 的渲染里程碑与 1.16.0；「能力与效果」表补
+  containment 的最长任务指标，并明确 `clientContainment` 是唯一有实测收益的
+  渲染优化、`renderTiming` 只采集数据。
+
 <a id="v1-16-0"></a>
 ## [1.16.0] — 2026-11-13 — ⚠️ 重要（文档归一 + 结构债）
 

package/README.md

@@ -6,15 +6,17 @@
 [![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1-green)]()
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> **⚠️ 最近发生重要更新**（1.10.x，破坏性）
+> **⚠️ 最近发生重要更新**
 >
-> - **1.10.0 移除三项在 dsh 0.2.2 上恒不生效的能力**，配置键从 22 个减到 17 个
->   （`warmupEnabled` / `warmOnCreated` / `fastInitFor` / `preparedCacheTrim` /
+> - **1.10.0（破坏性）**移除三项在 dsh 0.2.2 上恒不生效的能力，配置键从 22 个减到
+>   17 个（`warmupEnabled` / `warmOnCreated` / `fastInitFor` / `preparedCacheTrim` /
 >   `preparedCacheSize` 已删除），并修掉「改配置不生效」的晚绑定 bug。
 > - 支持范围收紧为 **dsh >= 0.2.2-rc.1 且 < 0.3.0**。更旧的 dsh 上会被加载门禁
 >   跳过（日志 `skipping profile bundle`）。
-> - 性能里程碑来自 **1.8.0**（冷读 21.2 s → 3.0 s）与 **1.9.0**（稳态
->   RSS 1324 → 690 MB）。
+> - 性能里程碑：**1.8.0** 冷读 21.2 s → 3.0 s；**1.9.0** 稳态 RSS 1324 → 690 MB；
+>   **1.12.0** 浏览器侧离屏行 containment，批量翻页阻塞 2 836 → 1 489 ms（约 −47%），
+>   首次实测渲染链路。
+> - **1.16.0** 收敛测量文档并修诊断设施的结构债，无用户可见能力变化。
 >
 > 从 1.4.0 或更早升级的用户，升级前请先读
 > [CHANGELOG 的重要版本速览](CHANGELOG.md#重要版本速览)。
@@ -37,15 +39,19 @@ DeepSeek Harness（dsh）**大会话**性能插件。针对数十万事件的长
 |---|---|---|---|
 | **turnOutline 折叠加速** | 该投影单元每次 turn 整数组复制（O(n²)），占冷读 76% | 冷读 **21.2 s → 3.0 s** | 开 |
 | **事件缓存字节预算** | dsh 的缓存只按「会话条数」限容；6 个 18 MB 会话涨到 1.2 GB | 稳态 RSS **1324 → 690 MB** | 开（512 MiB） |
-| **离屏行 containment** | 聊天列表没有虚拟滚动，已加载的每一行都参与布局 | 批量翻页阻塞 **2836 → 1489 ms**（-47%） | 开 |
+| **离屏行 containment** | 聊天列表没有虚拟滚动，已加载的每一行都参与布局 | 批量翻页阻塞 **2 836 → 1 489 ms**（约 −47%），最长任务 416 → 244 ms；未测到滚动漂移 | 开 |
 | 分片 materialize | 落盘时把整个会话序列化成一个巨大字符串 | 2 帧 → 6 帧，消除 `RangeError` | 开 |
 | 零拷贝 fork | fork 时逐事件深拷贝整个会话 | 直测 -16% ~ -21%（**但 UI 不走这条路**，见下） | 开 |
-| 渲染耗时诊断 | 打开会话慢在哪一段无从得知 | 分段计时（流→首行→首帧→稳定）、LoAF 脚本归属、跳转与滚动窗口 | 关 |
+| 渲染耗时诊断 | 打开会话慢在哪一段无从得知 | 五段归因（请求/服务端/响应/派发/挂载）、`ws.send` 拆写队列与 deflate、LoAF 脚本归属、跳转与滚动窗口 | 关 |
 | 历史窗口预算 | 一页只按消息条数切，无字节上限 | 长会话 70 KB/页、重会话 1.7 MB/页；默认不动，按需收紧 | 关 |
 | 冷读回写 | 冷读后把投影状态写成缓存行 | **无耗时收益**，只让列表读看到新数据 | 关 |
 | 冷会话补行 | 磁盘上的大会话没有投影缓存行 | 启动 15 s 后批量补写 | 关 |
 | heap 上限告警 | V8 heap 上限过低时无任何提示 | 启动时检查并告警 | — |
 
+> 浏览器侧唯一有实测收益的**优化**是 `clientContainment`；`renderTiming` 只采集
+> 数据，不改变渲染行为。两者的测量条件与边界见
+> [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md) §7/§9。
+
 ### 两条必须知道的限制
 
 **① `stats.patches` 显示 `active` 不等于在真实链路上被调用。**
@@ -275,6 +281,11 @@ npm test
 `e2e_real_components` 用真实实现类（原型链驱动）验证补丁装上后的行为；其余套件
 覆盖逻辑与边界。
 
+**版本号只在发布时决定**：开发轮次的变更先记入 `CHANGELOG.md` 的 `[Unreleased]`，
+不逐次改 `package.json`。选号规则与发布清单见
+[`docs/VERSIONING.md`](docs/VERSIONING.md)；`tests/verify_docs.mjs` 会断言
+`package.json` 与 CHANGELOG 首条版本一致。
+
 这三层都**不验证真实 dsh 进程里的调用链**。那需要起一个隔离实例并驱动 HTTP RPC，
 工具在 [`tools/runtime-probe/`](tools/runtime-probe/README.md)：
 

package/docs/PUBLISHING.md

@@ -98,12 +98,15 @@ git push origin v<version>
 
 ## 版本号策略
 
-- 插件版本（`1.x.y`）与 dsh 版本区间各自独立演进。
-- **仅扩展支持的 dsh 版本、不改任何插件行为** → patch。
-- **新增能力，或适配 dsh 破坏性变更并改代码** → minor。
-- **破坏插件自身 API**（配置键移除、导出变更） → major。
+选号规则、开发中的 `[Unreleased]` 约定、预发布号与发错处理见
+[VERSIONING.md](VERSIONING.md)。发布相关的两条硬约束：
+
+- **版本号只在发布时决定**：开发轮次不逐次改 `package.json`，变更先记在
+  `CHANGELOG.md` 的 `[Unreleased]`；发布时再按变更性质选 MAJOR / MINOR / PATCH。
+- **`engines.dsh` 收紧算 MAJOR**：即使用户代码零改动，旧 dsh 会被加载门禁拒绝。
 
 升级 dsh 大版本（如 0.3）时，**必须同步更新 `engines.dsh` 的上界**，否则 dsh 会因
 门禁跳过本插件（见 `docs/COMPATIBILITY.md`「两个版本的区分」）。
 
 **版本号以 `package.json` 为唯一来源。** 文档中不写死版本号，避免漂移。
+`CHANGELOG.md` 的第一个版本条目必须与它相等——`tests/verify_docs.mjs` 会断言。

package/docs/VERSIONING.md

@@ -0,0 +1,74 @@
+# 版本号与发布节奏
+
+> 本文是版本号规则的唯一来源。当前版本值只看 `package.json` 的 `version`；
+> 本文不写死版本号，避免漂移。
+
+## 1. 一句话
+
+**版本号在发布时决定，不在每轮开发结束时决定。** 开发中的变更先累积在
+[CHANGELOG.md](../CHANGELOG.md) 的 `[Unreleased]` 下；决定发布时，才按变更性质
+选 MAJOR / MINOR / PATCH。
+
+## 2. 为什么改
+
+npm 上可见的版本序列是 `1.4.0 → 1.10.1 → 1.16.0`，看起来像跳号。实际原因是：
+
+| npm 可见 | 本地 CHANGELOG | 说明 |
+|---|---|---|
+| 1.4.0 | 1.4.0 | 旧习惯发布 |
+| — | 1.5–1.9 | 开发轮次，版本号每轮 +1，但从未 publish |
+| 1.10.1 | 1.10.1 | 最后一次按旧习惯发布 |
+| — | 1.11–1.15 | 开发轮次，未 publish |
+| 1.16.0 | 1.16.0 | 当前发布；含 1.11–1.16 全部变更 |
+
+内容没有丢，但版本号失去了发布语义，而且把破坏性变更（1.11.0 收紧
+`engines.dsh`）埋进了 minor。从 1.16.0 起执行本文规则；**已发布的 1.16.0 不回滚、
+不重发**。
+
+## 3. 选号规则
+
+| 变更性质 | 号 | 例子 |
+|---|---|---|
+| **破坏性**：`engines.dsh` 收紧到不兼容、移除配置键或能力、改变默认行为、导出变更 | **MAJOR** | 1.11.0 把 engines 从 `>=0.1.0-rc.6` 收紧到 `>=0.2.2-rc.1`，按本规则应为 2.0.0 |
+| **新增能力**：新配置键（默认关）、新诊断字段、可观察的行为改进 | **MINOR** | 新增 `renderTiming` / `stats.render.sends` |
+| **修复与杂项**：bug 修复、文档、元数据、只扩展支持的 dsh 版本且不改行为 | **PATCH** | 1.10.1 |
+
+判定顺序：先看有没有破坏性，再看有没有新增能力，最后才是 patch。
+
+**`engines.dsh` 的收紧一律算 MAJOR**，即使代码零改动——用户升级后插件会被加载
+门禁拒绝，这是实实在在的破坏。
+
+## 4. 开发中的版本
+
+- 不逐轮改 `package.json`。内部轮次的变更全部写在 `## [Unreleased]`。
+- 需要发布测试版时用预发布号：`X.Y.Z-dev.N` / `X.Y.Z-rc.N`，并显式
+  `npm publish --tag next`；`latest` 只指向稳定版。
+- 一个版本号只能发布一次。发布前先确认不存在：
+  `npm view dsh-large-proj-perf@<version> version`。
+
+## 5. 发布清单
+
+1. `npm test` 全绿（`prepublishOnly` 会再跑一次）。
+2. 把 `[Unreleased]` 改成 `## [X.Y.Z] — YYYY-MM-DD`，按 §3 选号。
+3. `package.json` 的 `version` 改成同一个值。
+4. `npm pack --dry-run` 核对文件清单。
+5. 提交 `release: X.Y.Z`，打 `vX.Y.Z` tag。
+6. `npm publish --registry https://registry.npmjs.org`。
+7. `npm view dsh-large-proj-perf version dist-tags.latest` 确认指向新版本。
+8. push commit 与 tag。
+
+具体命令与 registry 注意事项见 [PUBLISHING.md](PUBLISHING.md)。
+
+## 6. 发错了怎么办
+
+- 优先**向前修**：发一个新的 PATCH / MINOR，而不是删版本。
+- 只有发布 72 小时内、且属于安全 / 法律 / 不可修复的元数据错误时，才考虑
+  `npm unpublish`；它会让已安装的用户看到版本消失。
+- 已 push 的 tag 不删改；补一个新版本，tag 跟着新版本走。
+
+## 7. 与文档的关系
+
+- `package.json` 的 `version` 是当前值；`CHANGELOG.md` 的第一个版本条目必须与它
+  相等。这条由 `tests/verify_docs.mjs` 断言。
+- 文档正文不写死当前版本号；需要指代版本时用「当前发布」或相对描述。
+- 历史条目保留发布当时的版本号与数字，不随新版本回改。

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Large Session Performance",
-    "description": "Cuts the load latency and memory footprint of very large sessions: turnOutline folding goes from O(n²) to O(n) (cold read 21.2s → 3.0s), event caches are capped by bytes instead of entry count (steady-state RSS 1324 → 690 MB), chunked materialize removes the RangeError on huge persistence writes, plus zero-copy fork and a V8 heap-limit warning."
+    "description": "Cuts the load latency and memory footprint of very large sessions: turnOutline folding goes from O(n²) to O(n) (cold read 21.2s → 3.0s), event caches are capped by bytes instead of entry count (steady-state RSS 1324 → 690 MB), offscreen-row containment in the browser cuts batch-paging blocking by about 47%, chunked materialize removes the RangeError on huge persistence writes, plus zero-copy fork, render-timing diagnostics and a V8 heap-limit warning."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "大会话性能优化",
-    "description": "降低数十万事件长会话的打开延迟与内存占用：turnOutline 折叠从 O(n²) 改 O(n)（冷读 21.2s → 3.0s）、事件缓存按字节限容（稳态 RSS 1324 → 690 MB）、分片 materialize 消除超大会话落盘的 RangeError、零拷贝 fork，以及 V8 heap 上限告警。"
+    "description": "降低数十万事件长会话的打开延迟与内存占用：turnOutline 折叠从 O(n²) 改 O(n)（冷读 21.2s → 3.0s）、事件缓存按字节限容（稳态 RSS 1324 → 690 MB）、浏览器侧离屏行 containment（批量翻页阻塞约 −47%）、分片 materialize 消除超大会话落盘的 RangeError、零拷贝 fork，以及渲染耗时诊断与 V8 heap 上限告警。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-large-proj-perf",
-  "version": "1.16.0",
-  "description": "DSH 大会话性能插件：turnOutline 折叠加速（冷读 21.2s → 3.0s）+ 事件缓存字节预算（RSS 1324 → 690 MB）+ 分片 materialize + 零拷贝 fork + heap 上限告警",
+  "version": "1.16.1",
+  "description": "DSH 大会话性能插件：turnOutline 折叠加速（冷读 21.2s → 3.0s）+ 事件缓存字节预算（RSS 1324 → 690 MB）+ 离屏行 containment（批量翻页阻塞约 −47%）+ 分片 materialize + 零拷贝 fork + 渲染耗时诊断",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.svg",