dsh-large-proj-perf 1.4.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,156 +1,296 @@
1
- # dsh-large-proj-perf
1
+ # DSH Large Project Performance
2
2
 
3
- [![Version](https://img.shields.io/badge/version-1.4.0-blue)]()
4
- [![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6..0.2.2--rc.1-green)]()
3
+ [![npm version](https://img.shields.io/npm/v/dsh-large-proj-perf.svg)](https://www.npmjs.com/package/dsh-large-proj-perf)
4
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-large-proj-perf.svg?label=npm%20monthly)](https://www.npmjs.com/package/dsh-large-proj-perf)
5
+ [![npm total downloads](https://img.shields.io/npm/d18m/dsh-large-proj-perf.svg?label=npm%20total)](https://www.npmjs.com/package/dsh-large-proj-perf)
6
+ [![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1-green)]()
5
7
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
8
 
7
- DSH(DeepSeek Harness)大会话性能插件。消除 fork、历史会话加载、超大会话落盘对
8
- 事件循环的阻塞,并治理冷会话内存——面向数十万事件的会话。
9
+ > **⚠️ 最近发生重要更新**(1.10.x,破坏性)
10
+ >
11
+ > - **1.10.0 移除三项在 dsh 0.2.2 上恒不生效的能力**,配置键从 22 个减到 17 个
12
+ > (`warmupEnabled` / `warmOnCreated` / `fastInitFor` / `preparedCacheTrim` /
13
+ > `preparedCacheSize` 已删除),并修掉「改配置不生效」的晚绑定 bug。
14
+ > - 支持范围收紧为 **dsh >= 0.2.2-rc.1 且 < 0.3.0**。更旧的 dsh 上会被加载门禁
15
+ > 跳过(日志 `skipping profile bundle`)。
16
+ > - 性能里程碑来自 **1.8.0**(冷读 21.2 s → 3.0 s)与 **1.9.0**(稳态
17
+ > RSS 1324 → 690 MB)。
18
+ >
19
+ > 从 1.4.0 或更早升级的用户,升级前请先读
20
+ > [CHANGELOG 的重要版本速览](CHANGELOG.md#重要版本速览)。
9
21
 
10
- 所有优化都带**源码特征校验 + 协议探测 + 三层回退**(能力探测 / try-catch / 配置
11
- 开关):dsh 内部结构变化时补丁自动跳过并告警,绝不盲补。上游原生实现了某项能力后,
12
- 对应补丁自动从 `active` 转为 `retired`。
22
+ DeepSeek Harness(dsh)**大会话**性能插件。针对数十万事件的长会话,降低打开时的
23
+ 延迟与内存占用。
24
+
25
+ > 包名里的 "large-proj" 是历史遗留;它优化的对象是**会话规模**,与项目大小无关。
26
+
27
+ 每项能力都带**源码特征校验 + 协议探测 + 三层回退**(能力探测 / try-catch / 配置
28
+ 开关)。dsh 内部结构变化时对应补丁会自动跳过并告警,功能回退到官方实现,不会出错。
13
29
 
14
30
  ## 能力与效果
15
31
 
16
- | 能力 | 症状 | 效果 | 当前状态 |
32
+ 数字都是 dsh 0.2.2 上的实测值,来源与测量边界见
33
+ [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md)(时间/空间)与
34
+ [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md)(浏览器渲染)。
35
+
36
+ | 能力 | 解决什么 | 实测效果 | 默认 |
17
37
  |---|---|---|---|
18
- | 零拷贝 fork | fork 逐事件 `snapshotJsonValue` 深拷贝 | 49ms → 5.9ms | 活跃 |
19
- | 分片投影预热 | 打开历史会话时同步冷折叠冻结事件循环 | 74 万事件 20 分钟 → ~200ms | 活跃 |
20
- | fork 缓存回填 | 子会话无投影缓存行,重开走全量读 | 分钟级 → 秒级 | 活跃 |
21
- | 分片 materialize | 落盘单巨字符串:60 万事件 501MB、74 万 RangeError | 多帧 zstd,字节兼容 | 活跃 |
22
- | 冷会话 LRU 裁剪 | 冷会话事件树 ~700MB/个 × 5 叠加 OOM | 省 ~2.8GB | 上游已代偿 |
23
- | fast initFor | persistence 的 `structuredClone(seed)` | 135ms → ~0ms | 已退役 |
24
- | heap 检测 | V8 heap 上限过低无提示 | 启动告警并给出参数建议 | 活跃 |
38
+ | **turnOutline 折叠加速** | 该投影单元每次 turn 整数组复制(O(n²)),占冷读 76% | 冷读 **21.2 s → 3.0 s** | 开 |
39
+ | **事件缓存字节预算** | dsh 的缓存只按「会话条数」限容;6 个 18 MB 会话涨到 1.2 GB | 稳态 RSS **1324 → 690 MB** | 开(512 MiB) |
40
+ | **离屏行 containment** | 聊天列表没有虚拟滚动,已加载的每一行都参与布局 | 批量翻页阻塞 **2836 → 1489 ms**(-47%) | 开 |
41
+ | 分片 materialize | 落盘时把整个会话序列化成一个巨大字符串 | 2 帧 → 6 帧,消除 `RangeError` | 开 |
42
+ | 零拷贝 fork | fork 时逐事件深拷贝整个会话 | 直测 -16% ~ -21%(**但 UI 不走这条路**,见下) | 开 |
43
+ | 渲染耗时诊断 | 打开会话慢在哪一段无从得知 | 分段计时(流→首行→首帧→稳定)、LoAF 脚本归属、跳转与滚动窗口 | 关 |
44
+ | 历史窗口预算 | 一页只按消息条数切,无字节上限 | 长会话 70 KB/页、重会话 1.7 MB/页;默认不动,按需收紧 | 关 |
45
+ | 冷读回写 | 冷读后把投影状态写成缓存行 | **无耗时收益**,只让列表读看到新数据 | 关 |
46
+ | 冷会话补行 | 磁盘上的大会话没有投影缓存行 | 启动 15 s 后批量补写 | 关 |
47
+ | heap 上限告警 | V8 heap 上限过低时无任何提示 | 启动时检查并告警 | — |
48
+
49
+ ### 两条必须知道的限制
50
+
51
+ **① `stats.patches` 显示 `active` 不等于在真实链路上被调用。**
52
+
53
+ 零拷贝 fork 挂在 `SessionStore.prototype.fork` 上,而 dsh 0.2.2 的服务端
54
+ `session/fork` RPC 改走 `agents.create({seed})`,**不再调用该方法**——实测 Web UI
55
+ 分支会话后 `stats.forks = 0`。补丁本身有效(用 `debugApi` 的 `debug.fork` 直测),
56
+ 但在 UI 链路上是死代码。
25
57
 
26
- 运行时状态经 `stats.get` 的 `patches` 字段暴露:`active`(已安装生效)、
27
- `retired`(上游已原生实现)、`inactive`(环境缺失或特征漂移)、`off`(配置关闭)。
58
+ **② 插件日志在默认配置下不可见。**
59
+
60
+ 正常日志走 `ctx.logger.info`,dsh 默认日志级别会过滤掉它——隔离实例里
61
+ `[dsh-perf]` 行数为 0,尽管插件已正常装载。排错请用 `stats.get`,不要靠 grep 日志。
28
62
 
29
63
  ## 安装
30
64
 
31
- 要求 Node **≥ 22.15.0**(`node:zlib` 的 zstd 接口),dsh `0.1.0-rc.6` ~ `0.2.2-rc.1`。
65
+ 要求 Node **≥ 22.15.0**(需要 `node:zlib` 的 zstd 接口)与 **dsh ≥ 0.2.2-rc.1**。
32
66
 
33
67
  ```sh
34
- # 从 GitHub 安装(推荐)
35
- dsh plugin --profile web add github:orangeofcarl0-sys/dsh-large-proj-perf
36
-
37
- # 从 npm 安装
68
+ # 从 npm 安装(推荐)
38
69
  dsh plugin --profile web add dsh-large-proj-perf
39
70
 
40
- # 本地开发
71
+ # 从 GitHub 安装
72
+ dsh plugin --profile web add github:orangeofcarl0-sys/dsh-large-proj-perf
73
+
74
+ # 本地开发(指向工作副本)
41
75
  dsh plugin --profile web add file:<本仓库路径>
76
+
77
+ # 卸载
78
+ dsh plugin --profile web remove dsh-large-proj-perf
42
79
  ```
43
80
 
44
- 重启 `dsh web` 后,启动日志出现 `[dsh-perf] installed (...)` 即装载成功。
81
+ 重启 `dsh web` 后,用 `stats.get` 确认装载成功(日志默认不可见,见上):
45
82
 
46
- > `file:` 安装不跟随源码改动。改完代码需把 `lib/`、`cordis.patch.yml`、
47
- > `package.json`、`icon.svg`、`locale/` 同步到
48
- > `<DSH_HOME>/profiles/web/node_modules/dsh-large-proj-perf/`,或重新 `dsh plugin add`。
83
+ ```sh
84
+ curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/stats.get
85
+ ```
86
+
87
+ `file:` 安装是拷贝而非链接,不跟随源码改动。改完代码需要重新
88
+ `dsh plugin --profile web add file:<路径>`,或手动同步 `lib/`、`cordis.patch.yml`、
89
+ `package.json`、`icon.svg`、`locale/` 到
90
+ `<dsh home>/profiles/web/node_modules/dsh-large-proj-perf/`(dsh home 默认 `~/.dsh`)。
49
91
 
50
92
  ### 建议同时调高 V8 heap 上限
51
93
 
52
- 多个大会话并存时,每个 live 事件树约 700MB,默认 ~4GB 上限容易 OOM。heap 上限是
53
- **启动期参数**,进程内改不了。用仓库脚本启动(内置 `--max-old-space-size=8192`):
94
+ 多个大会话并存时,每个 live 事件树可达数百 MB(实测 24 万事件 = 87.7 MB 堆对象,
95
+ 首次读的 RSS 增量可达 242 MB)。heap 上限是**启动期参数**,进程内改不了:
54
96
 
55
97
  ```powershell
98
+ # 仓库自带脚本,内置 --max-old-space-size=8192
56
99
  powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dsh.ps1
100
+
101
+ # 或自己加参数
102
+ node --max-old-space-size=8192 <dsh 入口> web
57
103
  ```
58
104
 
59
- 插件会在上限低于 6GB 时打告警,但不代为修改。
105
+ 插件会在上限低于 6 GiB 时打告警,但不会代为修改。
60
106
 
61
107
  ## 配置
62
108
 
63
- 可经 Settings 卡片、`config.set` API 或 settings 持久化修改。数值项带下限钳制
64
- (如 `materializeChunkEvents ≥ 1000`、`chunkSize ≥ 1`),NaN/Infinity 直接拒绝。
65
-
66
- | 键 | 默认 | 说明 |
67
- |---|---|---|
68
- | `zeroCopyFork` | `true` | 零拷贝 fork |
69
- | `fastInitFor` | `true` | fast initFor(新版 dsh 自动退役) |
70
- | `slowForkWarnMs` | `100` | fork 耗时告警阈值(ms) |
71
- | `warmupEnabled` | `true` | 投影分片预热总开关 |
72
- | `minEvents` | `20000` | 低于此事件数不预热 |
73
- | `chunkSize` | `5000` | 每片折叠事件数(片间让出事件循环) |
74
- | `chunkYieldMs` | `0` | 让出方式:0 = `setImmediate`,>0 = `setTimeout(ms)` |
75
- | `warmOnCreated` | `true` | `session/created`(含 resume)即预热 |
76
- | `backfillOnBoot` | `false` | 磁盘冷会话补投影缓存行(大文件解码同步,默认关) |
77
- | `backfillMaxSessions` | `8` | 补行扫描会话数上限 |
78
- | `backfillMinBytes` / `backfillMaxBytes` | `1MB` / `32MB` | 补行文件大小范围 |
79
- | `chunkedMaterialize` | `true` | 分片落盘 |
80
- | `materializeChunkEvents` | `50000` | 每帧事件数(下限 1000) |
81
- | `preparedCacheTrim` | `true` | 冷会话 LRU 裁剪总开关 |
82
- | `preparedCacheSize` | `1` | 裁剪目标容量(官方默认 5) |
83
- | `keepRecent` | `50` | 内存保留的最近统计记录数 |
84
- | `heapWarnBytes` | `6GB` | heap 上限告警阈值 |
85
-
86
- ## 验证是否生效
87
-
88
- 启动日志会打印探测到的 dsh 版本与各补丁安装结果:
89
-
90
- ```
91
- [dsh-perf] dsh version: 0.2.1-rc.3 (verified)
92
- [dsh-perf] zero-copy fork installed (SessionStore.prototype.fork patched, protocol: 0.1.7 forkSeed)
93
- [dsh-perf] chunked materialize installed (chunk=50000 events/frame, protocol: 0.1.3)
94
- ```
95
-
96
- 出现 `signature mismatch` 说明 dsh 内部结构已变,对应补丁跳过(功能回退到官方实现,
97
- 不会出错)。此时升级插件或运行兼容性检查:
109
+ 可经 dsh 的 Settings 卡片、`config.set` API 或 settings 持久化修改。数值项带下限
110
+ 钳制(非法值被收敛到下限),NaN / Infinity 直接拒绝。
98
111
 
99
- ```sh
100
- node tests/verify_compat.mjs
101
- ```
112
+ | 键 | 默认 | 单位 | 说明 |
113
+ |---|---|---|---|
114
+ | `fastTurnOutline` | `true` | — | `turnOutline` 的 O(n²) → O(n) |
115
+ | `memoryBudgetBytes` | `536870912` | 字节 | 事件缓存总预算(512 MiB);`0` 关闭 |
116
+ | `clientContainment` | `true` | — | 长转录离屏行 `content-visibility`(批量翻页阻塞约 −47%) |
117
+ | `heapWarnBytes` | `6442450944` | 字节 | heap 上限告警阈值(6 GiB) |
118
+ | `zeroCopyFork` | `true` | — | 零拷贝 fork |
119
+ | `slowForkWarnMs` | `100` | ms | fork 耗时超过此值打告警 |
120
+ | `chunkedMaterialize` | `true` | — | 分片落盘 |
121
+ | `materializeChunkEvents` | `50000` | 事件 | 每帧事件数(下限 1000) |
122
+ | `minEvents` | `20000` | 事件 | 低于此事件数的会话不做额外处理 |
123
+ | `chunkSize` | `5000` | 事件 | 分片遍历每片的事件数(下限 1) |
124
+ | `chunkYieldMs` | `0` | ms | 让出方式:0 = `setImmediate`,>0 = `setTimeout` |
125
+ | `keepRecent` | `50` | 条 | 内存保留的最近统计记录数 |
126
+ | `renderTiming` | `false` | — | 渲染诊断:服务端分页/投影计时 + 浏览器首行/长任务 |
127
+ | `maxInitialMessages` | `0` | 条 | 首屏消息上限(同时压 `turnWindow.minMessages`);`0` 不限制 |
128
+ | `maxPageBytes` | `0` | 字节 | 单页估算字节上限;`0` 不限制 |
129
+ | `coldWriteBack` | `false` | — | 冷读后回写投影缓存行(无耗时收益) |
130
+ | `backfillOnBoot` | `false` | — | 启动后补写磁盘冷会话的投影缓存行 |
131
+ | `backfillMaxSessions` | `8` | 个 | 补行扫描会话数上限 |
132
+ | `backfillMinBytes` | `1048576` | 字节 | 补行的最小文件大小(1 MiB) |
133
+ | `backfillMaxBytes` | `33554432` | 字节 | 补行的最大文件大小(32 MiB) |
134
+ | `debugApi` | `false` | — | 暴露 `debug.fork` 调试端点(仅用于测量) |
135
+
136
+ **哪些键运行期改得动**:`fastTurnOutline` / `chunkedMaterialize` / `zeroCopyFork` /
137
+ `maxInitialMessages` / `maxPageBytes` / `renderTiming` / `memoryBudgetBytes` /
138
+ `heapWarnBytes` 只在**安装时**读一次,改了要重启(或用启动期环境变量,见下);
139
+ `clientContainment` 由浏览器在启动时取一次。其余键在下次使用时重读。
140
+
141
+ 启动期还可用环境变量覆盖任意配置键(仅用于离线测量):键名是大写蛇形加
142
+ `DSH_PERF_` 前缀,例如 `DSH_PERF_CHUNKED_MATERIALIZE=false`。
143
+
144
+ ## 验证与排错
102
145
 
103
146
  ### HTTP API
104
147
 
105
- `POST http://127.0.0.1:3080/dsh-large-proj-perf/api/<method>`(仅回环 + 同源):
148
+ `POST http://127.0.0.1:<dsh 端口>/dsh-large-proj-perf/api/<method>`,仅接受回环地址
149
+ 且校验同源。端口由 dsh 的 web app 决定(默认 3080):
106
150
 
107
151
  | 端点 | 说明 |
108
152
  |---|---|
109
- | `stats.get` | 版本探针、各补丁状态、fork/预热/补行计数与最近记录 |
110
- | `stats.reset` | 清零计数(保留版本探针与补丁状态) |
111
- | `config.get` / `config.set` | 运行时开关,`set` 同时写 settings 持久化 |
153
+ | `stats.get` | 版本探针、各补丁状态与命中计数 |
154
+ | `stats.reset` | 清零计数(保留 `patches` 与 `dshVersion`) |
155
+ | `config.get` / `config.set` | 读取/修改运行时开关,`set` 同时写 settings 持久化 |
156
+ | `debug.fork` | 仅当 `debugApi=true` 时存在:直接调用 `SessionStore.prototype.fork` |
157
+ | `perf.report` | 仅当 `renderTiming=true` 时存在:浏览器回传首行/稳定/长任务样本 |
112
158
 
113
159
  ```sh
114
160
  curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/stats.get
161
+
162
+ # config.set 提交「键 → 值」扁平对象,可一次改多个键
115
163
  curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/config.set \
116
- -H 'Content-Type: application/json' -d '{"key":"backfillOnBoot","value":true}'
164
+ -H 'Content-Type: application/json' -d '{"backfillOnBoot":true}'
165
+ ```
166
+
167
+ 请求体是扁平对象(如 `{"minEvents":20000,"chunkSize":5000}`),**不是**
168
+ `{"key":...,"value":...}`——后者会被静默忽略:接口仍返回 200 和当前配置,
169
+ 但一个键都没改。
170
+
171
+ ### `stats.get` 怎么读
172
+
173
+ ```jsonc
174
+ {
175
+ "dshVersion": "0.2.2-rc.1",
176
+ "patches": { "zeroCopyFork": "active", "fastTurnOutline": "active", ... },
177
+ "forks": 0, "zeroCopy": 0, "fallbacks": 0, "forkRecent": [],
178
+ "memoryBudget": { "budgetBytes": 536870912, "cachedEntries": 0, "estimatedBytes": 0 }, // 关闭时恒为 null
179
+ "memoryBudgetTrimmed": 0, "memoryBudgetFreedBytes": 0, "memoryBudgetOverBudget": 0,
180
+ "coldWriteBacks": 0, "backfilled": 0, "backfillSkipped": 0,
181
+ "render": {
182
+ "snapshotCount": 0, "snapshotMs": 0, "snapshotMaxMs": 0, "lastUnits": 0,
183
+ "pages": [], "sends": [], "jumps": 0,
184
+ "clients": [], "reports": 0, "dropped": 0
185
+ }
186
+ }
117
187
  ```
118
188
 
189
+ `memoryBudget` 在预算关闭/不适用时恒为 `null`——字段始终存在,消费端不必判断键是否
190
+ 存在。`render` 只在 `renderTiming=true` 时有值:`pages` 是服务端每页的
191
+ `{kind, ms, startedAt, records, bytes}`(jump 条目用 `recordsTotal` / `bytesTotal`,
192
+ 表示跨页合计);`sends` 是 `ws.send` 的 `{t, sentAt, bytes}`;`clients` 是浏览器回传的
193
+ `{kind, rows, firstRowMs, firstFrameMs, settleMs, longTasks, blockingMs, maxTaskMs,
194
+ heartbeatMaxLagMs, streams, timeline}`;`jumps` 是服务端识别出的回合跳转次数
195
+ (连续分页聚合)。读法与实测见 [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md)。
196
+
197
+ 诊断模式还会暴露 `window.__dshPerf`:`state()` 看流表、WS 帧与最近样本,
198
+ `jumpToTurn(n)` / `scrollTest({rounds})` / `benchMarkdown({text, iterations})`
199
+ 驱动固定动作,`stop()` 停采集并还原 `$stream` / `socket.send`(`pagehide` 也会调用)。
200
+
201
+ 判断某能力是否真的在起作用,看命中计数而不是 `patches`:
202
+
203
+ | 想知道 | 看 |
204
+ |---|---|
205
+ | 零拷贝 fork 有没有被调用 | `zeroCopy`(长期 0 = 没被调用) |
206
+ | 内存预算有没有在淘汰 | `memoryBudgetTrimmed`(>0 说明生效) |
207
+ | 冷读回写 / 补行有没有跑 | `coldWriteBacks` / `backfilled` |
208
+ | 有没有发生回合跳转 | `render.jumps` / `render.pages` 里的 `kind:'jump'` |
209
+
210
+ ### 常见问题
211
+
212
+ **看不到任何 `[dsh-perf]` 日志**
213
+ 这是**默认配置下的常态**,不是故障(见上文「两条必须知道的限制」)。用 `stats.get`
214
+ 判断插件状态。
215
+
216
+ **`stats.patches` 显示 `active`,但好像没效果**
217
+ `active` 只表示装上了,不表示被调用。用上表的命中计数判断。
218
+
219
+ **日志出现 `signature mismatch`**
220
+ dsh 内部结构已变,对应补丁已自动跳过(功能回退到官方实现,不影响正确性)。升级本
221
+ 插件到与新 dsh 匹配的版本即可。注意 `tests/` 不随 npm 包发布,从 npm 安装的情况下
222
+ 无法在安装目录里跑兼容性检查——升级插件是唯一正解。
223
+
224
+ **日志出现 `skipping profile bundle`**
225
+ 插件被 dsh 的版本门禁拦下了。从 dsh 0.2.1 起,门禁读插件 `package.json` 的
226
+ `engines.dsh`;本插件声明 `>=0.2.2-rc.1 <0.3.0-0`。dsh 超出该范围时,要么升级插件,
227
+ 要么用 `dsh plugin allow-version <pkg>@<ver> --profile web` 做精确版本豁免(有风险)。
228
+
229
+ **API 请求 404 或连不上**
230
+ 端口可能不是 3080。看 `dsh web` 启动日志里打印的 URL,或 `dsh web --help` 确认。
231
+
232
+ **改完配置没反应**
233
+ 三种情况:`fastTurnOutline` / `chunkedMaterialize` / `zeroCopyFork` /
234
+ `maxInitialMessages` / `maxPageBytes` 只在安装时读一次,改了要重启;
235
+ `clientContainment` 由浏览器在页面启动时取一次,改完刷新页面;`backfillOnBoot`
236
+ 相关的补行任务在启动 15 秒后才跑;其余开关通过 `config.set` 修改后即时生效。
237
+
238
+ **没有任何 `[dsh-perf]` 日志且 `stats.get` 也连不上**
239
+ 插件没被加载。检查 `dsh --profile web --dump-config` 里是否有 `large-proj-perf`
240
+ 条目,以及启动日志有无 `skipping profile bundle`。
241
+
119
242
  ## 已知限制
120
243
 
121
- - **这是被动优化**,削减不了正在使用的 live 事件树(每会话几百 MB 是物理成本)。
244
+ - **这是被动优化**,削减不了正在使用的 live 事件树(每会话数百 MB 是物理成本)。
122
245
  建议配合 [dsh-fresh-start](https://github.com/orangeofcarl0-sys/dsh-fresh-start)
123
- 主动控制会话规模:`/fresh` 一键「总结 → 开新会话 → 归档老会话」。
124
- - `backfillOnBoot` 的解码在插件层同步执行(虽按 `chunkSize` 分片让出),超大文件
125
- 仍可能短暂冻结事件循环,故默认关闭。
126
- - `preparedCacheTrim` 在新版 dsh 上自动跳空为 `inactive`(上游已系统代偿);仅在
127
- 老版本 dsh 上真正生效。
128
- - 与其他插件不冲突,但若某个行管理类插件禁用了 `session-projection-cache`,
129
- 本插件的缓存与预热能力会被削弱。
246
+ 主动控制会话规模。
247
+ - **零拷贝 fork 在 dsh 0.2.2 的 UI fork 链路上不生效**(原因见上)。
248
+ - **只验证过 dsh 0.2.2**。`engines.dsh` 声明为 `>=0.2.2-rc.1 <0.3.0-0`——更旧的
249
+ dsh 上插件能力已基本为零(v1.10.0 移除三项依赖旧结构的能力后,0.1.x 只剩零拷贝
250
+ fork 与分片 materialize),因此直接由门禁拒绝,而不是让用户装上一个近乎空转的
251
+ 插件。0.3.x 上会被同样拒绝,届时需要新版本插件。
252
+ - **打开一个会话的字节大头取决于会话类型**:长会话(30 000 turn)是投影主导——
253
+ 实测 74 KB 消息 + **6.76 MB 投影**(`turnOutline` 装着全部 turn);重会话
254
+ (300 turn / 620 次工具调用)反过来,**1.73 MB 消息 + 68 KB 投影**。两种都不是
255
+ 插件能削减的部分,诊断数据与上游建议见
256
+ [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md) §5。
257
+ - **浏览器侧没有虚拟滚动**(上游 `ChatFlow` 直接 `entries.map()`)。插件只能用
258
+ `content-visibility` 减轻离屏行的布局代价,不能减少挂载数量;向上翻页会持续
259
+ 累积 DOM 与堆(实测 600 行区间约 73 KiB/行)。**回合跳转是最极端的路径**:一次
260
+ 跳到早期 turn 会挂载上千行(实测 +1 375 行、主线程阻塞 1.7 秒)。
261
+ - **`retired` 补丁状态当前无使用者**:v1.10.0 移除了唯一会设置它的能力。保留该状态
262
+ 是因为它是「上游吸收能力后补丁主动让位」的唯一表达。
130
263
 
131
264
  ## 开发
132
265
 
133
266
  ```sh
134
- # 链接全局 dsh 的嵌套依赖(仓库本身无 node_modules)
135
- powershell -ExecutionPolicy Bypass -File .\scripts\link-deps.ps1
267
+ # 前置:把全局 dsh 的嵌套依赖 junction 到仓库(仓库本身不含 node_modules)
268
+ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\link-deps.ps1
136
269
 
137
- # 全套 8 套件 147 断言
270
+ # 全套 13 个套件(断言总数以运行器末行输出为准,不要手写)
138
271
  npm test
139
272
  ```
140
273
 
141
- 测试分两层:`verify_compat` 对真实安装源码做特征断言与门禁实算;`e2e_real_components`
142
- 直接驱动 dsh 的真实实现类(`JsonlSessionPersistence` / `SessionProjectionRegistry` /
143
- `SessionStore`),逐点位验证「补丁装上 → 行为正确」。其余套件覆盖逻辑与边界。
274
+ 测试分三层:`verify_compat` 对真实安装的 dsh 源码做特征断言并实算版本门禁;
275
+ `e2e_real_components` 用真实实现类(原型链驱动)验证补丁装上后的行为;其余套件
276
+ 覆盖逻辑与边界。
144
277
 
145
- ## 更多文档
278
+ 这三层都**不验证真实 dsh 进程里的调用链**。那需要起一个隔离实例并驱动 HTTP RPC,
279
+ 工具在 [`tools/runtime-probe/`](tools/runtime-probe/README.md):
146
280
 
147
- | 文档 | 内容 |
148
- |---|---|
149
- | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 三类同步阻塞的定位、各补丁实现原理、加载侧分工、安全性与回退设计 |
150
- | [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | 版本矩阵、各版本内部形态、dsh 版本门禁规则、插件清单规范 |
151
- | [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
152
- | [PUBLISHING.md](PUBLISHING.md) | 发布流程与约定 |
281
+ ```sh
282
+ node tools/runtime-probe/run.mjs --home <隔离 home> --agents <agents home> \
283
+ --port 3190 --scenario all --out <输出目录>
284
+ ```
153
285
 
154
- ## License
286
+ ## 文档
155
287
 
156
- MIT
288
+ | 文档 | 读者 | 内容 |
289
+ |---|---|---|
290
+ | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 维护者 | 问题分类、各能力的探测与实现、装配契约、如何新增能力 |
291
+ | [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md) | 维护者 | 时间/空间两维度的实测数据、测量边界、已移除能力的记录 |
292
+ | [docs/RENDER-ANALYSIS.md](docs/RENDER-ANALYSIS.md) | 维护者 | 浏览器渲染链路:静态机制、真实浏览器实测、瓶颈排序与上游建议 |
293
+ | [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | 维护者 | 版本矩阵、0.2.2 的五处破坏性变更、插件清单规范 |
294
+ | [docs/HARNESS-COMPARISON.md](docs/HARNESS-COMPARISON.md) | 参考 | 其他 coding agent harness 怎么处理长会话 |
295
+ | [docs/PUBLISHING.md](docs/PUBLISHING.md) | 发布者 | 发布流程与约定 |
296
+ | [CHANGELOG.md](CHANGELOG.md) | — | 版本变更记录 |