dsh-large-proj-perf 1.3.0 → 1.3.3

package/CHANGELOG.md

@@ -9,6 +9,78 @@
 
 ## [Unreleased]
 
+## [1.3.3] — 2026-10-24
+
+面向 **dsh 0.2.1-rc.3** 的兼容版本。rc.3 是**纯版本刷新**：17 个关键包
+（`dsh-session`、`dsh-session-persistence(-jsonl)`、`dsh-session-projection(-cache)`、
+`dsh-app-boot`、`dsh-web-app`、`dsh-plugin-manager`、`dsh-agent-loop`、`dsh-base`、
+`dsh-host-webserver`、`dsh-home-paths`、`dsh-session-checkpoint-policy`、
+`dsh-session-query`、`dsh-session-format-catalog`、`dsh-session-format-v3-to-v4`、
+`dsh-working-directory`、`dsh-agent-preset-registry`）rc.2→rc.3 逐字节相同；
+顶层依赖集 86 项无增删；305 个已装包全部对齐 rc.3。四个补丁点与投影缓存零影响。
+
+### Changed
+
+- 已知版本列表加入 `0.2.1-rc.3`；支持范围上限更新为 `0.2.1-rc.3`。
+
+## [1.3.2] — 2026-10-17
+
+面向 **dsh 0.2.1-rc.2** 的兼容版本。rc.2 是**纯版本刷新**：13 个关键包
+（`dsh-session`、`dsh-session-persistence(-jsonl)`、`dsh-session-projection(-cache)`、
+`dsh-app-boot`、`dsh-agent-loop`、`dsh-web-app`、`dsh-plugin-manager`、
+`dsh-host-webserver`、`dsh-home-paths` 等）rc.1→rc.2 逐字节相同，四个补丁点零影响。
+
+### Added
+
+- **插件清单展示元数据**（按官方 bundle 规范）：`icon.svg`、
+  `locale/en.json`、`locale/zh.json`（双语标题与描述），并在 `exports` 中暴露
+  `./locale/*.json` 与 `./cordis.patch.yml`、在 `files` 中纳入这些资源。
+  此前插件在插件管理器中只显示裸包名、无图标。
+- `verify_compat` 新增 4 条断言：bundle 声明完整（`dsh.bundle.patch`）、双语
+  `locale` 可解析、`exports` 暴露子路径、展示元数据可被宿主 `readPluginMeta` 解析。
+
+### Changed
+
+- 已知版本列表加入 `0.2.1-rc.2`；支持范围上限更新为 `0.2.1-rc.2`。
+- **README 重整**：从 315 行精简到 156 行，只保留使用者需要的内容（能力与效果、
+  安装、配置、验证、已知限制）。维护者向内容拆到 `docs/`：
+  - `docs/ARCHITECTURE.md` —— 三类同步阻塞、各补丁实现原理、加载侧分工、
+    identity 契约、安全性与回退、代码结构；
+  - `docs/COMPATIBILITY.md` —— 版本矩阵、0.1.3 破坏面、版本门禁规则、
+    插件清单规范、升级检查清单。
+- `files` 白名单纳入 `docs/`，随 npm 包发布。
+
+## [1.3.1] — 2026-10-17
+
+面向 **dsh 0.2.1-rc.1** 的兼容与修复版本。
+
+### Added
+
+- **`engines.dsh` 声明**（`>=0.1.0-rc.6 <0.3.0-0`）。0.2.1 起门禁优先读
+  `engines.dsh` 且**独占生效**——声明后 `peerDependencies` 的 dsh 项被完全忽略。
+  两处声明保持一致，同时满足 0.2.0（只认 peer）与 0.2.1+（只认 engines）两代门禁。
+- `verify_compat` 改为直接 `import` 宿主真实的 `evaluatePluginCompatibility` 实算
+  门禁（拿不到时回退 semver 离线复算），并把 `engines.dsh` 纳入断言。
+- e2e 新增 2 组回归断言，锁定本次修复的两个预热缺陷。
+
+### Fixed
+
+- **预热用 `def.init()` 无参调用**（严重）：上游投影契约是
+  `init(header, inheritedEventCount)`，`agentPreset` / `workingDirectory` /
+  `agentTeam` 等真实投影从 header 取值，无参调用抛 `TypeError` 导致该 unit
+  预热静默失败。现按上游 `restore()` 语义传 `(session.header, session.inheritedEventCount)`。
+- **预热写入的 cell 缺 `views` 字段**（严重）：上游 `buildCell()` 产出
+  `{state, observedSeq, views: [undefined, undefined]}`，`drive()` / `advanceCell()`
+  会读写 `views[0]/[1]`。缺该字段时，预热后的会话在**下一条事件到达**时抛
+  `TypeError: Cannot read properties of undefined (reading '1')`。现按 `buildCell` 同形写入。
+
+### Changed
+
+- **测试适配 0.2.1 的 jsonl 后端形态**：该包不再导出 `default` 类，只导出
+  cordis 插件（`name`/`apply`/`Config`）。e2e 改为经真实 `Context.plugin` 装载后
+  从 `ctx.sessionPersistence` 取实例（同时保留 0.2.0 及之前的原型直取路径）。
+- 已知版本列表加入 `0.2.1-rc.1`。
+
 ## [1.3.0] — 2026-10-11
 
 面向 **dsh 0.2.0** 的发布准备版本。

package/README.md

@@ -1,218 +1,114 @@
 # dsh-large-proj-perf
 
-[![Version](https://img.shields.io/badge/version-1.3.0-blue)]()
-[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6..0.2.0--rc.2-green)]()
+[![Version](https://img.shields.io/badge/version-1.3.3-blue)]()
+[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6..0.2.1--rc.3-green)]()
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-DSH（DeepSeek Harness）大会话性能插件：零拷贝 fork、分片投影预热、fork 缓存回填、
-分片 materialize、冷会话内存治理——一次装齐，消除 fork / 历史加载 / 落盘对超大会话
-（数十万事件）的事件循环阻塞与 OOM。
+DSH（DeepSeek Harness）大会话性能插件。消除 fork、历史会话加载、超大会话落盘对
+事件循环的阻塞，并治理冷会话内存——面向数十万事件的会话。
 
-所有优化带**源码特征校验 + 协议探测 + 三层回退**（能力探测 / try-catch / 配置开关），
-不匹配自动跳过、绝不盲补；上游吸收了某项能力后对应补丁**自动从 `active` 转
-`retired`**——插件按项逐项退役，最终全部 `retired` 之日即整体退役之时。
+所有优化都带**源码特征校验 + 协议探测 + 三层回退**（能力探测 / try-catch / 配置
+开关）：dsh 内部结构变化时补丁自动跳过并告警，绝不盲补。上游原生实现了某项能力后，
+对应补丁自动从 `active` 转为 `retired`。
 
-## 特性一览
+## 能力与效果
 
-| 能力 | 解决什么 | 0.1.3-alpha.2 实测 | 状态 |
+| 能力 | 症状 | 效果 | 当前状态 |
 |---|---|---|---|
-| 零拷贝 fork | fork 时逐事件 `snapshotJsonValue` 深拷贝阻塞 | 49ms → 5.9ms（0.1.7 真实环境） | 活跃（0.1.7 走 `create(eventState:'shared-frozen')` + `buildForkSeed` 通道） |
-| 分片投影预热 | 打开历史会话的同步冷折叠冻结事件循环 | 74 万事件 20min → ~200ms | 活跃 |
-| fork 缓存回填 | fork 子会话无投影缓存行，重开走全量读 | 分钟级 → 秒级 | 活跃（0.1.3 直读 `session.vN.jsonl.zstd` 多帧） |
-| 分片 materialize | fork 落盘单巨字符串：60 万事件 501MB、74 万直接 RangeError | 多帧 zstd，字节兼容 | 活跃（0.1.3 三参签名已适配） |
-| 冷会话 LRU 裁剪 | 冷会话事件树 ~700MB/个 ×5 叠加 OOM | 省 ~2.8GB | 0.1.3 上游系统修复（`coldLogMemo=2`），补丁自动跳空 |
-| fast initFor | persistence 的 `structuredClone(seed)` 深拷贝 | 135ms → ~0ms | 已退役（rc.8 起上游原生；0.1.3 coordinator 移除） |
-| heap 检测 | V8 heap 上限过低告警 | 运维辅助 | 活跃 |
+| 零拷贝 fork | fork 逐事件 `snapshotJsonValue` 深拷贝 | 49ms → 5.9ms | 活跃 |
+| 分片投影预热 | 打开历史会话时同步冷折叠冻结事件循环 | 74 万事件 20 分钟 → ~200ms | 活跃 |
+| fork 缓存回填 | 子会话无投影缓存行，重开走全量读 | 分钟级 → 秒级 | 活跃 |
+| 分片 materialize | 落盘单巨字符串：60 万事件 501MB、74 万 RangeError | 多帧 zstd，字节兼容 | 活跃 |
+| 冷会话 LRU 裁剪 | 冷会话事件树 ~700MB/个 × 5 叠加 OOM | 省 ~2.8GB | 上游已代偿 |
+| fast initFor | persistence 的 `structuredClone(seed)` | 135ms → ~0ms | 已退役 |
+| heap 检测 | V8 heap 上限过低无提示 | 启动告警并给出参数建议 | 活跃 |
 
-运行时各补丁的实际状态经 `stats.get` 的 `patches` 字段暴露：
-`active`（已安装生效）/ `retired`（上游已原生实现）/ `inactive`（环境缺失或特征
-漂移）/ `off`（配置关闭）。
-
-## 工作原理
-
-dsh 0.1.x 在大会话上有三类同步阻塞（源码级定位 + 实测）：
-
-| 问题 | 环节 | 实测 |
-|---|---|---|
-| A. fork 深拷贝 | `Session` 构造器逐事件 `snapshotJsonValue` + 旧 persistence `initFor` 的 `structuredClone(seed)` | 18.2MB / 20k 事件合计 ~480ms |
-| B. projection 冷折叠 | `cellFor()` 冷时同步 `buildCell` 全量折叠 | 74 万事件阻塞 20+ 分钟（100% 单核） |
-| C. fork 全量序列化 | `encodeMaterialization` 一次性序列化整个 seed | 60 万事件 501MB 单串；74 万 RangeError |
-
-对应方案（全部独立开关、失败自动回退官方实现）：
-
-1. **零拷贝 fork**：fork 的 seed 是 live 会话的 `snapshotEvents()`（事件在 append 时
-   已 deepFreeze）。改走 fromRestore 通道原地冻结复用引用（三协议自动探测）：
-   - **0.1.7+**：复用原生 `_resolveForkSource` + `_forkBoundary` + 模块级
-     `buildForkSeed`（slice + 注入 `session/end-seed {inherited:true}` marker +
-     `openTurnClosers` 补 turn 闭合），只把 `create` 的写入通道换成
-     `eventState:'shared-frozen'`；`buildForkSeed` 新建的事件未冻结，送入前
-     原地深冻结（满足「已冻结或独立拥有」前提）；
-   - **0.1.3–0.1.5**：复用 `_forkSeed`，补丁补 `version/id/createdAt` 到 meta
-     并在 seed 尾部注入 inherited marker（磁盘校验要求 `cut == marker.seq`，
-     原生快照通道自动追加、restore 通道不追加）；
-   - **alpha.5 / rc.1**：`prepare({seedSource:'persistence'})` 旧通道。
-2. **分片投影预热**：会话进入且事件数超阈值时，抢在首次冷折叠前分片重放 cells
-   （每片间 `setImmediate`/`setTimeout` 让出），直写 `registration.cells`；有投影
-   缓存行时取基线跳过已折叠前缀；fork 子会话预热后回填缓存行。
-3. **分片 materialize**：每 `materializeChunkEvents` 事件一个 zstd frame（多帧是
-   解码端 `scanZstdFrames` 的原生格式，字节兼容），消除单巨字符串。0.1.3 头帧
-   直接复用上游 `encodeCurrentHeader` 编码器（`original(meta, inheritedEventCount,
-   [])` 只产 header 帧），不重写格式层。
-4. **冷会话 LRU 裁剪**：运行时把 `SessionPreparations.capacity` 降到
-   `preparedCacheSize`（默认 1）并淘汰最旧 ready 条目；`config.set` 即时生效，
-   dispose 恢复原容量。0.1.3 起上游以 `COLD_LOG_MEMO_MAX_ENTRIES = 2` + handle
-   模型懒 materialize 系统代偿，该补丁在上游 0.1.3 自动跳空（老版本仍活跃）。
-5. **fast initFor**：`structuredClone(seed)` → 冻结引用复用；rc.8 起上游原生实现，
-   补丁自动退役（0.1.3 连 `PersistenceCoordinator` 本体也已移除）。
-6. **heap 检测**：heap 上限低于阈值（默认 6GB）时告警并提示
-   `--max-old-space-size`。
-
-安全性：共享冻结引用与深拷贝语义等价（事件进入源会话时已完整校验并深冻结）；
-三层回退保证任何不匹配都不破坏上游行为。
-
-### 加载侧：上游已优化的部分与插件的作用点
-
-长对话「打开」的成本分三段，0.1.3–0.1.7 期间上游已优化前两段：
-
-| 阶段 | 上游现状（0.1.7） | 插件是否介入 |
-|---|---|---|
-| 磁盘解码 | 逐帧 zstd 解码 + 增量 `SessionLogScanner`（不拼整串），每 500ms `scheduler.yield()` 让出事件循环 | 否（上游已良好） |
-| 老格式迁移 | 格式 < v4 的会话经 v0→v1→v2→v3→v4 链，**在 Worker Thread 内完成**并发布新世代文件（`session.vN.jsonl`） | 否（上游已良好） |
-| 投影折叠 | `cellFor` 冷时**同步全量** `buildCell`（仍在主线程） | **是**：分片预热 + 缓存行基线（见下） |
-| 落盘编码 | `encodeMaterialization` 单 body 帧（fork 子会话首次落盘可能 501MB 单串） | **是**：分片 zstd 多帧 |
-
-插件写/读投影缓存行时必须使用与上游 `identityOf` 一致的键：`createdAt`/`cwd`/
-`isSeeded`/`inheritedEventCount` 以及 **0.1.3 起新增的 `formatVersion`**
-（= `header.version`）。上传 identity 缺 `formatVersion` 时，上游只把它当作
-title 前驱提示，**不能作折叠短路**——补行与基线复用会静默失效（此坑已于 1.2.0
-修复并有回归断言守护）。
-
-## 支持版本
-
-| 版本线 | 形态 |
-|---|---|
-| 0.1.0-rc.6 / rc.7 / rc.8 | fork `prepare(seedSource)` 通道；initFor `structuredClone` 形态 |
-| 0.1.1-rc.1 / rc.2 | 同 alpha.5 形态；rc.2 为 `(meta, events)` 裸 meta 签名 |
-| 0.1.2-alpha.5 / 0.1.2-rc.1 | `snapshotEvents()`；fork meta `isSeeded`+`inheritedEventCount`；`(storage, events)` 签名 |
-| 0.1.3-alpha.2 | persistence 子系统重写（见下）；投影缓存 identity 新增 `formatVersion`（插件已跟进） |
-| 0.1.5-alpha.1 | 会话格式 **v3**（`SESSION_FORMAT_VERSION=3`）；cut/header 语义与 v2 一致，文件名 `session.v3.jsonl`；补丁点零行级变更 |
-| 0.1.5-rc.1 | 仅新增已知事件类型（`deliverables/presented`、`subagent/catalog`）；补丁点零变化 |
-| 0.1.5-rc.2 | 相对 rc.1 四个关键包源码零差异（仅版本号），无新增变更 |
-| 0.1.7-rc.2 | 新增 `toolHistory()` 增量折叠（游标只消费新事件）；persistence/format/projection-cache 零差异，补丁点无变化 |
-| 0.2.0-rc.2 | 主版本升级。**插件管理引入严格 peer 门禁**（见下）；`dsh-session` 重构 tail-repair 并新增 `ToolCallRecovery`（`buildForkSeed`/`SESSION_FORMAT_VERSION` 等导出不变）；`llm-deepseek` 拆分为 `-api-key`/`-account`；四个补丁点与 projection-cache 零破坏 |
-| 0.1.7-rc.1 | fork 内部重构：`_forkSeed` → `_forkBoundary` + 模块级 `buildForkSeed`；**open-turn 边界从「拒绝」改为「注入 turn 闭合事件」**；会话格式升 **v4**（cut/文件名语义同 v2/v3）；事件词汇收紧（`tool/result` role=`tool`、新增 `system/message`）。插件已适配（三协议探测） |
-
-### 0.1.3-alpha.2 关键变化（已全部适配）
-
-- `dsh-session-persistence` 变为 contract 层（`SessionPersistence` 基类 + 错误 +
-  校验），`PersistenceCoordinator`/`initFor`/`SessionPreparations` 移除；JSONL
-  实现移入 `dsh-session-persistence-jsonl`。
-- 格式 v0→v1→v2 迁移链（`dsh-session-format` 系列）；物理 header 移除
-  `seedLength`，seed cut 由事件流尾 `session/end-seed {inherited:true}` marker
-  表达（`cut == marker.seq`）；文件名变 `session.vN.jsonl[.zstd]`。
-- `encodeMaterialization(meta, events)` → `(meta, inheritedEventCount, events)`；
-  事件词汇收紧（`assistant/message` 需 `data.stream`、消息 `id/source/role` 校验）。
-
-升级 dsh 后：启动日志显示 `dsh version: x.y.z (verified)`（版本探针）或列表外
-版本告警；跑 `node tests/verify_compat.mjs`（对真实安装源码做结构断言 + peer 门禁
-离线复算，当前 30 项）；确认无 `signature mismatch` 告警。
+运行时状态经 `stats.get` 的 `patches` 字段暴露：`active`（已安装生效）、
+`retired`（上游已原生实现）、`inactive`（环境缺失或特征漂移）、`off`（配置关闭）。
 
 ## 安装
 
-要求：Node **≥ 22.15.0**（`node:zlib` zstd 接口）；dsh `0.1.0-rc.6` ~ `0.2.0-rc.2`
-（`package.json` 已声明 `engines`）。
+要求 Node **≥ 22.15.0**（`node:zlib` 的 zstd 接口），dsh `0.1.0-rc.6` ~ `0.2.1-rc.3`。
 
 ```sh
 # 从 GitHub 安装（推荐）
 dsh plugin --profile web add github:orangeofcarl0-sys/dsh-large-proj-perf
 
+# 从 npm 安装
+dsh plugin --profile web add dsh-large-proj-perf
+
 # 本地开发
 dsh plugin --profile web add file:<本仓库路径>
 ```
 
-> 修改仓库代码后需把 `lib/`、`cordis.patch.yml`、`package.json` 同步到
-> `<DSH_HOME>/profiles/web/node_modules/dsh-large-proj-perf/`（`file:` 安装
-> 不自动跟随），或重新 `dsh plugin add`。重启 `dsh web` 生效，日志出现
-> `[dsh-perf] installed (...)` 即成功。
-
-### 插件管理：0.2.0 的 peer 门禁（重要）
-
-dsh 0.2.0 起，profile bundle 加载前会校验插件 `package.json` 的
-`peerDependencies` 中**所有 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` 项**：
-运行时版本不满足 range 即**跳过整个插件**（启动日志打
-`skipping profile bundle "<name>": ... incompatible with dsh <ver>`），可用
-`dsh plugin allow-version <pkg>@<ver> --profile web` 做精确版本豁免。
-
-本插件的声明（0.2.0 契约的显式兼容声明）：
+重启 `dsh web` 后，启动日志出现 `[dsh-perf] installed (...)` 即装载成功。
 
-```json
-"peerDependencies": {
-  "@deepseek-ai/cordis": "^4.0.1",
-  "@deepseek-ai/dsh": ">=0.1.0-rc.6 <0.3.0-0",
-  "@deepseek-ai/dsh-session": ">=0.1.0-rc.6 <0.3.0-0"
-}
-```
-
-- 只声明我们**真实依赖**的东西：`dsh-session`（`snapshotEvents`/`buildForkSeed`/
-  `SessionLogOffset`）与 `dsh`（版本探针）；
-- 上界 `<0.3.0-0` 覆盖整个 0.1.x–0.2.x 线：既让门禁能替我们守住兼容边界，
-  又不会在小版本推进时误杀自己。**升级 dsh 大版本（0.3+）前需先更新此范围**；
-- `verify_compat.mjs` 会用 dsh 自带的 semver **离线复算**同一条门禁规则
-  （`plugin contract: declared dsh peers satisfy runtime version`）——离线报警
-  = 重启后必被跳过。
+> `file:` 安装不跟随源码改动。改完代码需把 `lib/`、`cordis.patch.yml`、
+> `package.json`、`icon.svg`、`locale/` 同步到
+> `<DSH_HOME>/profiles/web/node_modules/dsh-large-proj-perf/`，或重新 `dsh plugin add`。
 
-### 大会话内存（推荐启动方式）
+### 建议同时调高 V8 heap 上限
 
-多个超大会话的 live 事件树每个 ~700MB，默认 V8 heap 上限 ~4GB 会 OOM。插件已自动
-做冷会话治理，但 heap 上限是**启动期参数**，进程内改不了——推荐用仓库脚本启动（内置
-`--max-old-space-size=8192`）：
+多个大会话并存时，每个 live 事件树约 700MB，默认 ~4GB 上限容易 OOM。heap 上限是
+**启动期参数**，进程内改不了。用仓库脚本启动（内置 `--max-old-space-size=8192`）：
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dsh.ps1
 ```
 
-### 避免超长对话（主动规避）
-
-本插件是「被动优化」，无法削减**正在使用的** live 事件树（每会话几百 MB 是它的
-物理成本）。推荐配合 [dsh-fresh-start](https://github.com/orangeofcarl0-sys/dsh-fresh-start)：
-`/fresh` 一键「总结 → 开新会话 → 归档老会话」，主动控制会话规模。本插件兜底
-性能，fresh-start 控制规模。
+插件会在上限低于 6GB 时打告警，但不代为修改。
 
 ## 配置
 
-全部配置可经 Settings 卡片、`config.set` API 或 settings 持久化修改；数值项带下限
-钳制（非法值被拒绝或收敛到下限：`materializeChunkEvents ≥ 1000`、`chunkSize ≥ 1`、
-`preparedCacheSize ≥ 1` 等），NaN/Infinity 直接拒绝。
+可经 Settings 卡片、`config.set` API 或 settings 持久化修改。数值项带下限钳制
+（如 `materializeChunkEvents ≥ 1000`、`chunkSize ≥ 1`），NaN/Infinity 直接拒绝。
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `zeroCopyFork` | `true` | 零拷贝 fork（三协议自动探测：0.1.7 fork-seed / 0.1.3 event-state / alpha.5 seed-source） |
-| `fastInitFor` | `true` | fast initFor（rc.8+ 自动退役；0.1.3 无此形态） |
+| `zeroCopyFork` | `true` | 零拷贝 fork |
+| `fastInitFor` | `true` | fast initFor（新版 dsh 自动退役） |
 | `slowForkWarnMs` | `100` | fork 耗时告警阈值（ms） |
-| `warmupEnabled` | `true` | 大会话投影分片预热总开关 |
-| `minEvents` | `20000` | 低于此事件数不预热（同步冷折叠足够快） |
-| `chunkSize` | `5000` | 每片折叠事件数（下限 1；片间让出事件循环） |
-| `chunkYieldMs` | `0` | 让出方式：0=setImmediate；>0=setTimeout(ms) |
-| `warmOnCreated` | `true` | session/created（含 resume 的大会话）即预热 |
+| `warmupEnabled` | `true` | 投影分片预热总开关 |
+| `minEvents` | `20000` | 低于此事件数不预热 |
+| `chunkSize` | `5000` | 每片折叠事件数（片间让出事件循环） |
+| `chunkYieldMs` | `0` | 让出方式：0 = `setImmediate`，>0 = `setTimeout(ms)` |
+| `warmOnCreated` | `true` | `session/created`（含 resume）即预热 |
 | `backfillOnBoot` | `false` | 磁盘冷会话补投影缓存行（大文件解码同步，默认关） |
 | `backfillMaxSessions` | `8` | 补行扫描会话数上限 |
 | `backfillMinBytes` / `backfillMaxBytes` | `1MB` / `32MB` | 补行文件大小范围 |
-| `chunkedMaterialize` | `true` | 分片落盘（0.1.3 头帧复用上游编码器） |
+| `chunkedMaterialize` | `true` | 分片落盘 |
 | `materializeChunkEvents` | `50000` | 每帧事件数（下限 1000） |
-| `preparedCacheTrim` | `true` | 冷会话 LRU 裁剪总开关（false 恢复官方容量） |
-| `preparedCacheSize` | `1` | 裁剪目标容量（官方默认 5 → 1，省 ~2.8GB） |
-| `keepRecent` | `50` | 内存保留的最近记录数（fork/预热统计） |
+| `preparedCacheTrim` | `true` | 冷会话 LRU 裁剪总开关 |
+| `preparedCacheSize` | `1` | 裁剪目标容量（官方默认 5） |
+| `keepRecent` | `50` | 内存保留的最近统计记录数 |
 | `heapWarnBytes` | `6GB` | heap 上限告警阈值 |
 
-## API
+## 验证是否生效
+
+启动日志会打印探测到的 dsh 版本与各补丁安装结果：
 
-`POST http://127.0.0.1:3080/dsh-large-proj-perf/api/<method>`（回环 + 同源校验）：
+```
+[dsh-perf] dsh version: 0.2.1-rc.3 (verified)
+[dsh-perf] zero-copy fork installed (SessionStore.prototype.fork patched, protocol: 0.1.7 forkSeed)
+[dsh-perf] chunked materialize installed (chunk=50000 events/frame, protocol: 0.1.3)
+```
+
+出现 `signature mismatch` 说明 dsh 内部结构已变，对应补丁跳过（功能回退到官方实现，
+不会出错）。此时升级插件或运行兼容性检查：
+
+```sh
+node tests/verify_compat.mjs
+```
+
+### HTTP API
+
+`POST http://127.0.0.1:3080/dsh-large-proj-perf/api/<method>`（仅回环 + 同源）：
 
 | 端点 | 说明 |
 |---|---|
-| `stats.get` | `dshVersion` 版本探针、`patches` 各补丁状态（active/retired/inactive/off）、fork/预热/补行计数与最近记录 |
-| `stats.reset` | 清零计数与历史（保留版本探针与补丁状态） |
-| `config.get` / `config.set` | 运行时开关；`config.set` 同时写 settings 持久化（`backfillOnBoot` 等生效即补跑） |
+| `stats.get` | 版本探针、各补丁状态、fork/预热/补行计数与最近记录 |
+| `stats.reset` | 清零计数（保留版本探针与补丁状态） |
+| `config.get` / `config.set` | 运行时开关，`set` 同时写 settings 持久化 |
 
 ```sh
 curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/stats.get
@@ -220,48 +116,40 @@ curl -X POST http://127.0.0.1:3080/dsh-large-proj-perf/api/config.set \
   -H 'Content-Type: application/json' -d '{"key":"backfillOnBoot","value":true}'
 ```
 
-## 开发与测试
+## 已知限制
+
+- **这是被动优化**，削减不了正在使用的 live 事件树（每会话几百 MB 是物理成本）。
+  建议配合 [dsh-fresh-start](https://github.com/orangeofcarl0-sys/dsh-fresh-start)
+  主动控制会话规模：`/fresh` 一键「总结 → 开新会话 → 归档老会话」。
+- `backfillOnBoot` 的解码在插件层同步执行（虽按 `chunkSize` 分片让出），超大文件
+  仍可能短暂冻结事件循环，故默认关闭。
+- `preparedCacheTrim` 在新版 dsh 上自动跳空为 `inactive`（上游已系统代偿）；仅在
+  老版本 dsh 上真正生效。
+- 与其他插件不冲突，但若某个行管理类插件禁用了 `session-projection-cache`，
+  本插件的缓存与预热能力会被削弱。
+
+## 开发
 
 ```sh
-# 一次到位：junction 链接全局 dsh 的嵌套依赖（仓库无 node_modules）
+# 链接全局 dsh 的嵌套依赖（仓库本身无 node_modules）
 powershell -ExecutionPolicy Bypass -File .\scripts\link-deps.ps1
 
-# 全套 8 套件 138 断言
-#  - verify_compat：对真实安装源码做特征断言 + peer 门禁离线复算
-#  - e2e_real_components：直接驱动 dsh 真实实现类（真实 JsonlSessionPersistence
-#    / SessionProjectionRegistry / SessionStore），逐点位验证补丁安装与行为
+# 全套 8 套件 147 断言
 npm test
 ```
 
-仓库布局：
-
-```
-lib/index.js            编排层（apply：配置/统计/日志/版本探针/补丁安装/定时器）
-lib/runtime.js          日志、safeGet、sessionEventsOf、sessionLogOffset、版本探针
-lib/config.js           默认值/下限钳制/settings schema 注册
-lib/stats.js            统计与补丁生命周期状态（active/retired/inactive/off）
-lib/api.js              stats/config HTTP 端点
-lib/warmup.js           分片投影预热 + fork 缓存回填
-lib/backfill.js         磁盘冷会话补行（readRaw / 0.1.3 直读双通道）
-lib/patches/*.js        零拷贝 fork / fast initFor / 冷会话 LRU / 分片 materialize
-tests/                  verify_compat（真实源码特征 + 门禁复算）/ e2e_real_components
-                        （真实实现类端到端）/ smoke_*、test_*（mock 逻辑与边界）
-```
-
-补丁安装原则：**特征校验先行**（`String(原型方法)` 含特征字面量，不匹配打
-`signature mismatch` 后跳过）；**协议探测**（如 fork 的 `eventState` vs
-`seedSource` 双分支）；**try-catch 兜底**（零拷贝失败自动回退官方实现并计入
-`fallbacks`）。所有补丁 dispose 时按原形状还原（原型方法 delete 回落 / 自有属性
-原样写回）。
+测试分两层：`verify_compat` 对真实安装源码做特征断言与门禁实算；`e2e_real_components`
+直接驱动 dsh 的真实实现类（`JsonlSessionPersistence` / `SessionProjectionRegistry` /
+`SessionStore`），逐点位验证「补丁装上 → 行为正确」。其余套件覆盖逻辑与边界。
 
-## 已知限制
+## 更多文档
 
-- `backfillOnBoot` 的解码在插件层同步执行（虽按 chunkSize 分片让出），超大文件
-  仍可能短暂冻结事件循环，故默认关闭，需要时手动开启。
-- 0.1.3 上 `preparedCacheTrim` 自动跳空为 `inactive`（上游已系统代偿）；若你仍
-  运行老版本 dsh，该补丁才真正生效。
-- 插件不与 `dsh-perf`（配置订阅类）或 `dsh-pref-kit` 冲突，但行管理类插件禁用
-  `session-projection-cache` 会削弱本插件的缓存/预热功能。
+| 文档 | 内容 |
+|---|---|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 三类同步阻塞的定位、各补丁实现原理、加载侧分工、安全性与回退设计 |
+| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | 版本矩阵、各版本内部形态、dsh 版本门禁规则、插件清单规范 |
+| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
+| [PUBLISHING.md](PUBLISHING.md) | 发布流程与约定 |
 
 ## License
 

package/docs/ARCHITECTURE.md

@@ -0,0 +1,124 @@
+# 架构与实现
+
+本文面向维护者，说明每项优化针对的具体阻塞点、实现方式，以及安全性与回退设计。
+
+## 三类同步阻塞
+
+dsh 0.1.x 在大会话上有三类同步阻塞，均为主线程事件循环占用：
+
+| 问题 | 环节 | 实测 |
+|---|---|---|
+| A. fork 深拷贝 | `Session` 构造器逐事件 `snapshotJsonValue`，旧 persistence `initFor` 的 `structuredClone(seed)` | 18.2MB / 20k 事件合计 ~480ms |
+| B. projection 冷折叠 | `cellFor()` 冷时同步 `buildCell` 全量折叠 | 74 万事件阻塞 20+ 分钟（100% 单核） |
+| C. fork 全量序列化 | `encodeMaterialization` 一次性序列化整个 seed | 60 万事件 501MB 单串；74 万 RangeError |
+
+## 各补丁的实现
+
+所有补丁独立开关、失败自动回退官方实现。
+
+### 1. 零拷贝 fork（问题 A）
+
+fork 的 seed 是 live 会话的 `snapshotEvents()`，这些事件在 append 时已被
+`deepFreeze`。补丁改走 fromRestore 通道，原地冻结复用引用而非深拷贝。
+
+fork 协议经历三代，补丁按能力探测自动选择：
+
+| 协议 | 版本 | 实现 |
+|---|---|---|
+| fork-seed | 0.1.7+ | 复用原生 `_resolveForkSource` + `_forkBoundary` + 模块级 `buildForkSeed`（slice + 注入 `session/end-seed {inherited:true}` marker + `openTurnClosers` 补 turn 闭合），只把 `create` 的写入通道换成 `eventState:'shared-frozen'`。`buildForkSeed` 新建的事件未冻结，送入前原地深冻结 |
+| event-state | 0.1.3–0.1.5 | 复用 `_forkSeed`，补丁补 `version/id/createdAt` 到 meta，并在 seed 尾部注入 inherited marker（磁盘校验要求 `cut == marker.seq`；原生快照通道自动追加，restore 通道不追加） |
+| seed-source | alpha.5 / rc.1 | `prepare({seedSource:'persistence'})` 旧通道 |
+
+探测依据是方法存在性与源码字面量，任一不满足即整体跳过，绝不安装会破坏 fork 的补丁。
+
+已知取舍：open-turn 边界 fork 时，fromRestore 模式会补一条非 inherited 的 live
+end-seed 标记（原生快照通道不补）。该标记不参与 seed cut、不影响 v4 校验，代价是
+子会话事件流比原生多一条标记。
+
+### 2. 分片投影预热（问题 B）
+
+会话进入且事件数超过 `minEvents` 时，抢在首次同步冷折叠前分片重放 cells：每片
+`chunkSize` 个事件，片间用 `setImmediate`/`setTimeout` 让出事件循环，折叠完成后直写
+`registration.cells`（WeakMap）。此后 `snapshot()` / `drive()` 全部命中热 cell。
+
+有投影缓存行时取基线跳过已折叠前缀；fork 子会话预热后回填缓存行，否则被放弃时
+永远没有缓存行，下次打开会走 `readFrom(0)` 全量读。
+
+写入的 cell 必须与上游 `buildCell()` 同形——`{ state, observedSeq, views: [undefined, undefined] }`，
+且初始化必须按上游签名 `init(header, inheritedEventCount)` 调用。缺 `views` 会在下一条
+事件经 `drive()` 时抛 `TypeError`；无参 `init()` 会让所有从 header 取值的投影
+（`agentPreset`、`workingDirectory`、`agentTeam`）抛错。两者均有回归断言守护。
+
+### 3. 分片 materialize（问题 C）
+
+每 `materializeChunkEvents` 个事件一个 zstd frame。多帧是解码端 `scanZstdFrames`
+的原生格式，字节兼容。
+
+头帧不复刻上游编码器，而是直接调用原方法 `original(meta, inheritedEventCount, [])`
+——`events.length === 0` 时只产 header 帧，编码逻辑始终归上游所有。
+
+### 4. 冷会话 LRU 裁剪
+
+运行时把 `SessionPreparations.capacity` 降到 `preparedCacheSize`（默认 1）并淘汰最旧
+ready 条目；`config.set` 即时生效，dispose 恢复原容量。
+
+新版 dsh 已用 `COLD_LOG_MEMO_MAX_ENTRIES = 2` + handle 模型懒 materialize 系统代偿，
+该补丁自动跳空为 `inactive`（老版本仍活跃）。
+
+### 5. fast initFor
+
+`structuredClone(seed)` 换成冻结引用复用。rc.8 起上游原生实现，补丁自动退役；
+0.1.3 连 `PersistenceCoordinator` 本体也已移除。
+
+### 6. heap 检测
+
+heap 上限低于 `heapWarnBytes`（默认 6GB）时告警并提示 `--max-old-space-size`。
+
+## 加载侧：上游已优化的部分与插件的作用点
+
+长对话「打开」的成本分四段，其中前两段上游已自行优化：
+
+| 阶段 | 上游现状 | 插件是否介入 |
+|---|---|---|
+| 磁盘解码 | 逐帧 zstd 解码 + 增量 `SessionLogScanner`（不拼整串），每 500ms `scheduler.yield()` | 否 |
+| 老格式迁移 | 格式 < v4 的会话经 v0→v1→v2→v3→v4 链，**在 Worker Thread 内完成**并发布新世代文件 | 否 |
+| 投影折叠 | `cellFor` 冷时**同步全量** `buildCell`（仍在主线程） | **是**：分片预热 + 缓存行基线 |
+| 落盘编码 | `encodeMaterialization` 单 body 帧 | **是**：分片 zstd 多帧 |
+
+### 投影缓存行的 identity 契约
+
+插件写/读缓存行时必须使用与上游 `identityOf` 一致的键：`createdAt`、`cwd`、
+`isSeeded`、`inheritedEventCount`，以及 **0.1.3 起新增的 `formatVersion`**
+（= `header.version`）。
+
+缺 `formatVersion` 时上游只把它当作 title 前驱提示，**不能作折叠短路**——补行与
+基线复用会静默失效。该问题已于 1.2.0 修复，并有回归断言守护。
+
+## 安全性与回退
+
+共享冻结引用与深拷贝语义等价：事件进入源会话时已完整校验并深冻结，fork 的 seed
+只是复用这些不可变对象。
+
+三层回退保证任何不匹配都不破坏上游行为：
+
+1. **能力探测**——依赖的方法/导出不存在时直接跳过；
+2. **源码特征校验**——`String(原型方法)` 不含特征字面量时打 `signature mismatch` 并跳过；
+3. **try-catch 兜底**——零拷贝 fork 失败时自动回退官方实现，并计入 `fallbacks` 计数。
+
+所有补丁在 dispose 时按原形状还原：原型方法用 `delete` 回落，自有属性原样写回，
+不留 bind 副本遮蔽。
+
+## 代码结构
+
+```
+lib/index.js            编排层（apply：配置/统计/日志/版本探针/补丁安装/定时器）
+lib/runtime.js          日志、safeGet、sessionEventsOf、sessionLogOffset、版本探针
+lib/config.js           默认值/下限钳制/settings schema 注册
+lib/stats.js            统计与补丁生命周期状态
+lib/api.js              stats/config HTTP 端点
+lib/warmup.js           分片投影预热 + fork 缓存回填
+lib/backfill.js         磁盘冷会话补行（0.1.3 前 readRaw / 之后直读双通道）
+lib/patches/*.js        零拷贝 fork / fast initFor / 冷会话 LRU / 分片 materialize
+tests/run.mjs           测试运行器：每套件独立子进程（隔离内存，避免累积崩溃）
+tools/                  开发者专用脚本（不随 npm 包发布）
+```

package/docs/COMPATIBILITY.md

@@ -0,0 +1,115 @@
+# 兼容性与插件规范
+
+本文面向维护者：记录各 dsh 版本的内部形态差异、版本门禁规则，以及插件清单规范。
+
+## 版本矩阵
+
+按时间顺序。每一行说明该版本对插件作用点的影响。
+
+| dsh 版本 | 内部形态与影响 |
+|---|---|
+| 0.1.0-rc.6 / rc.7 / rc.8 | fork 走 `prepare(seedSource)` 通道；initFor 为 `structuredClone` 形态。rc.8 起 initFor 上游原生零拷贝，fast initFor 补丁退役 |
+| 0.1.1-rc.1 / rc.2 | 同 alpha.5 形态；rc.2 的 `encodeMaterialization` 是 `(meta, events)` 裸 meta 签名 |
+| 0.1.2-alpha.5 / 0.1.2-rc.1 | 新增 `snapshotEvents()`；fork meta 带 `isSeeded` + `inheritedEventCount`；签名变 `(storage, events)` |
+| 0.1.3-alpha.2 | **persistence 子系统重写**（见下）；投影缓存 identity 新增 `formatVersion` |
+| 0.1.5-alpha.1 | 会话格式 **v3**（`SESSION_FORMAT_VERSION=3`）；cut/header 语义同 v2，文件名 `session.v3.jsonl` |
+| 0.1.5-rc.1 | 仅新增已知事件类型（`deliverables/presented`、`subagent/catalog`） |
+| 0.1.5-rc.2 | 相对 rc.1 四个关键包源码零差异（仅版本号） |
+| 0.1.7-rc.1 | fork 内部重构：`_forkSeed` → `_forkBoundary` + 模块级 `buildForkSeed`；**open-turn 边界从「拒绝」改为「注入 turn 闭合事件」**；会话格式升 **v4**；事件词汇收紧（`tool/result` role=`tool`、新增 `system/message`） |
+| 0.1.7-rc.2 | 新增 `toolHistory()` 增量折叠；persistence/format/projection-cache 零差异 |
+| 0.2.0-rc.2 | 主版本升级。**插件管理引入严格 peer 门禁**；`dsh-session` 重构 tail-repair 并新增 `ToolCallRecovery`（`buildForkSeed`/`SESSION_FORMAT_VERSION` 等导出不变）；`llm-deepseek` 拆分为 `-api-key` / `-account` |
+| 0.2.1-rc.1 | **门禁新增 `engines.dsh` 且独占生效**；jsonl 后端改为 cordis 插件形态（只导出 `name`/`apply`/`Config`）；persistence 改为 `ctx.effect` 资源生命周期 + `listConcurrency` 限流；`dsh-session` 新增 `appendPluginRecord`/`pluginRecordOf`；投影 `register()` 直接返回 effect。**fork 通道与四个补丁点源码零变化** |
+| 0.2.1-rc.2 | **纯版本刷新**：13 个关键包 rc.1→rc.2 逐字节相同。唯一实质变更在 `dsh-web-app/cordis.patch.yml`（新增 `ui-deepseek-model-label-1017` 条目），不触及任何作用点 |
+| 0.2.1-rc.3 | **纯版本刷新**：17 个关键包 rc.2→rc.3 逐字节相同（含 `dsh-session`、三个 persistence/projection 包、`dsh-app-boot`、`dsh-web-app`、`dsh-plugin-manager`、`dsh-session-format-*`、`dsh-working-directory`、`dsh-agent-preset-registry` 等）；依赖集 86 项无增删；305 个已装包全部对齐 rc.3。插件侧仅需登记版本 |
+
+## 0.1.3-alpha.2 的关键变化
+
+这次是破坏面最大的一次，四个作用点全部需要重新适配：
+
+- `dsh-session-persistence` 变为 contract 层（`SessionPersistence` 基类 + 错误 + 校验），
+  `PersistenceCoordinator` / `initFor` / `SessionPreparations` 移除；JSONL 实现移入
+  `dsh-session-persistence-jsonl`。
+- 格式 v0→v1→v2 迁移链（`dsh-session-format` 系列）；物理 header 移除 `seedLength`，
+  seed cut 改由事件流尾 `session/end-seed {inherited:true}` marker 表达（`cut == marker.seq`）；
+  文件名变 `session.vN.jsonl[.zstd]`。
+- `encodeMaterialization(meta, events)` → `(meta, inheritedEventCount, events)`。
+- 事件词汇收紧：`assistant/message` 需 `data.stream`，消息需 `id/source/role` 校验。
+
+## dsh 版本门禁
+
+dsh 0.2.0 起，profile bundle 加载前会校验插件 `package.json` 的 `peerDependencies`
+中**所有 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` 项**：运行时版本不满足 range 即
+**跳过整个插件**（启动日志打 `skipping profile bundle "<name>": ... incompatible`），
+可用 `dsh plugin allow-version <pkg>@<ver> --profile web` 做精确版本豁免。
+
+**0.2.1 新增 `engines.dsh`，且它独占生效**：只要插件声明了 `engines.dsh`，门禁就
+**只**看它，`peerDependencies` 里的 dsh 项被完全忽略（`unmetRequirements()` 的
+`if (Object.hasOwn(engines, "dsh"))` 分支直接返回）。
+
+本插件的声明：
+
+```json
+"engines": {
+  "node": ">=22.15.0",
+  "dsh": ">=0.1.0-rc.6 <0.3.0-0"
+},
+"peerDependencies": {
+  "@deepseek-ai/cordis": "^4.0.1",
+  "@deepseek-ai/dsh": ">=0.1.0-rc.6 <0.3.0-0",
+  "@deepseek-ai/dsh-session": ">=0.1.0-rc.6 <0.3.0-0"
+}
+```
+
+- 只声明真实依赖：`dsh-session`（`snapshotEvents` / `buildForkSeed` / `SessionLogOffset`）
+  与 `dsh`（版本探针）。
+- 上界 `<0.3.0-0` 覆盖整个 0.1.x–0.2.x 线：既让门禁守住兼容边界，又不会在小版本推进时
+  误杀自己。**升级 dsh 大版本（0.3+）前必须先更新此范围。**
+- 保留 `peerDependencies` 是为旧版本兜底：0.2.0 及之前不认 `engines.dsh`，只读 peer
+  范围。两处保持一致即可同时满足两代门禁。
+- `verify_compat.mjs` 直接 `import` 宿主真实的 `evaluatePluginCompatibility` 实算一遍，
+  拿不到该导出时回退 semver 离线复算。报警 = 重启后必被跳过。
+
+## 插件清单规范
+
+dsh 从插件 `package.json` 读取两类信息，缺一不可：
+
+| 用途 | 字段 | 说明 |
+|---|---|---|
+| **加载** | `dsh.bundle.patch` | bundle patch 文件路径（或路径数组），profile 加载时按序应用；缺它插件不会被当作 bundle |
+| **展示** | `icon` + `./locale/*.json` | 插件管理器与设置页的标题、描述、图标；缺了会退化为裸包名 |
+
+本插件的完整声明：
+
+```json
+"icon": "./icon.svg",
+"exports": {
+  ".": { "default": "./lib/index.js" },
+  "./locale/*.json": "./locale/*.json",
+  "./package.json": "./package.json",
+  "./cordis.patch.yml": "./cordis.patch.yml"
+},
+"files": ["lib", "scripts", "locale/*.json", "icon.svg", "cordis.patch.yml", "README.md", "CHANGELOG.md", "LICENSE"],
+"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+```
+
+`locale/en.json` / `locale/zh.json` 结构与官方 bundle 一致：
+
+```json
+{ "meta": { "title": "…", "description": "…" } }
+```
+
+注意 `exports` 必须显式暴露 `./locale/*.json` 与 `./cordis.patch.yml`——宿主通过
+`optionalResourcePath("<pkg>/locale/en.json")` 走 Node 解析读取，未导出的子路径读不到。
+
+图标走 `icon` 字段（相对路径，须在包目录内，≤256 KiB，支持 SVG/PNG/JPEG/WebP），
+也可改用 `exports` 暴露的 `./icon` 资源。
+
+## 升级 dsh 后的检查清单
+
+1. 启动日志确认 `dsh version: x.y.z (verified)`，且无 `signature mismatch` 与
+   `skipping profile bundle`。
+2. `node tests/verify_compat.mjs` 全通过。
+3. `npm test` 全通过（含真实组件 e2e）。
+4. 若新版本不在 `KNOWN_DSH_VERSIONS`，按需登记（`lib/runtime.js` 与
+   `tests/verify_compat.mjs` 各一份）。
+5. 实机启动 web profile，`stats.get` 确认各点位为预期的 `active` / `inactive`。

package/icon.svg

@@ -0,0 +1,14 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(1.5 1.5) scale(0.9166666667)">
+    <rect x="4" y="8" width="28" height="5" rx="2.5" fill="url(#a)" fill-opacity="0.9" />
+    <rect x="4" y="15.5" width="21" height="5" rx="2.5" fill="url(#a)" fill-opacity="0.65" />
+    <rect x="4" y="23" width="14" height="5" rx="2.5" fill="url(#a)" fill-opacity="0.4" />
+    <path d="M27 21.5L31 25.5L27 29.5" stroke="#FFFFFF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+  </g>
+  <defs>
+    <linearGradient id="a" x1="4" y1="8" x2="4" y2="30" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#5EEAD4" />
+      <stop offset="1" stop-color="#2B7FFF" />
+    </linearGradient>
+  </defs>
+</svg>

package/lib/runtime.js

@@ -10,7 +10,7 @@ export const TAG = '[dsh-perf]'
 
 // 插件开发/验证过的 dsh 版本。运行时探针检测到列表外版本时打告警，并提示跑
 // tests/verify_compat.mjs 确认补丁特征是否仍匹配（特征校验会自动跳过，但会静默失效）。
-export const KNOWN_DSH_VERSIONS = ['0.1.0-rc.6', '0.1.0-rc.7', '0.1.0-rc.8', '0.1.1-rc.1', '0.1.1-rc.2', '0.1.2-alpha.5', '0.1.2-rc.1', '0.1.3-alpha.2', '0.1.5-alpha.1', '0.1.5-rc.1', '0.1.5-rc.2', '0.1.7-rc.1', '0.1.7-rc.2', '0.2.0-rc.2']
+export const KNOWN_DSH_VERSIONS = ['0.1.0-rc.6', '0.1.0-rc.7', '0.1.0-rc.8', '0.1.1-rc.1', '0.1.1-rc.2', '0.1.2-alpha.5', '0.1.2-rc.1', '0.1.3-alpha.2', '0.1.5-alpha.1', '0.1.5-rc.1', '0.1.5-rc.2', '0.1.7-rc.1', '0.1.7-rc.2', '0.2.0-rc.2', '0.2.1-rc.1', '0.2.1-rc.2', '0.2.1-rc.3']
 
 // cordis 环境下对缺失服务调用 ctx.get 可能抛错——统一安全取服务
 export const safeGet = (ctx, name) => {

package/lib/warmup.js

@@ -57,7 +57,10 @@ export function createWarmup(pc) {
     const row = checkpointRows[key]
     const usable = row !== void 0 && row.ver === def.stateVersion
     const unitBaseSeq = usable ? row.seq : -1
-    let state = usable ? row.val : def.init()
+    // init 的上游签名是 init(header, inheritedEventCount)：多个真实投影
+    // （agentPreset / workingDirectory / agentTeam）从 header 取值，无参调用
+    // 会直接抛 TypeError。缓存行可用时按上游 restore() 语义直接用 row.val。
+    let state = usable ? row.val : def.init(session.header, session.inheritedEventCount)
 
     let i = 0
     if (usable) {
@@ -79,7 +82,10 @@ export function createWarmup(pc) {
     const liveReg = registry.registrations.get(key)
     if (liveReg !== registration || liveReg.cells.get(session) !== void 0) return { status: 'skip', baseSeq: unitBaseSeq }
     const observedSeq = events.at(-1)?.seq ?? -1
-    liveReg.cells.set(session, { state, observedSeq })
+    // cell 必须与上游 buildCell 同形：drive()/advanceCell() 会读写 views[0]/[1]，
+    // 缺该字段会在下一条事件到达时抛 TypeError（Cannot read properties of
+    // undefined (reading '1')）。
+    liveReg.cells.set(session, { state, observedSeq, views: [void 0, void 0] })
     return { status: 'folded', baseSeq: unitBaseSeq }
   }
 

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Large Project Performance",
+    "description": "Keeps fork, cold-session loading, and persistence of very large sessions off the event loop: zero-copy fork, chunked projection warmup, fork cache backfill, chunked materialize, and cold-session memory governance."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "大会话性能优化",
+    "description": "让 fork、冷会话加载与超大会话落盘不再阻塞事件循环：零拷贝 fork、投影分片预热、fork 缓存回填、分片 materialize 与冷会话内存治理。"
+  }
+}

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "dsh-large-proj-perf",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "DSH 大会话性能插件：零拷贝 fork + 投影分片预热 + fork 缓存回填 + 分片 materialize + 冷会话内存治理 + heap 检测（DeepSeek Harness / DSH）",
   "type": "module",
   "main": "lib/index.js",
+  "icon": "./icon.svg",
   "engines": {
-    "node": ">=22.15.0"
+    "node": ">=22.15.0",
+    "dsh": ">=0.1.0-rc.6 <0.3.0-0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "test": "node tests/verify_compat.mjs && node tests/smoke_fork.mjs && node tests/test_fast_initfor.mjs && node tests/test_cache_trim.mjs && node tests/smoke_warmup.mjs && node tests/test_chunked_materialize.mjs && node tests/test_backfill.mjs && node tests/e2e_real_components.mjs",
+    "test": "node tests/run.mjs",
     "prepublishOnly": "npm test",
     "pack:check": "npm pack --dry-run"
   },
@@ -19,15 +21,20 @@
     ".": {
       "default": "./lib/index.js"
     },
-    "./package.json": "./package.json"
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
   },
   "files": [
     "lib",
     "scripts",
+    "locale/*.json",
+    "icon.svg",
     "cordis.patch.yml",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "license": "MIT",
   "repository": {

package/scripts/set-npm-token.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-# 安全写入 npm 发布用 token 到 ~/.npmrc（token 不回显、不进 shell 历史）。
-#
-# 用法：
-#   bash scripts/set-npm-token.sh
-# 然后按提示粘贴 token（输入不可见），回车确认。
-#
-# 前置：在 https://www.npmjs.com/settings/<用户名>/tokens 生成
-#       **Granular Access Token** 并勾选 "Bypass 2FA"（或选 Automation 类型），
-#       权限至少包含 dsh-large-proj-perf 的 Read and write。
-set -euo pipefail
-
-NPMRC="${HOME}/.npmrc"
-REGISTRY_LINE='//registry.npmjs.org/:_authToken='
-
-printf '粘贴 npm token（输入不可见，回车确认）: '
-IFS= read -rs TOKEN
-printf '\n'
-
-if [ -z "${TOKEN}" ]; then
-  echo "错误：token 为空，未做任何修改。" >&2
-  exit 1
-fi
-case "${TOKEN}" in
-  npm_*|*[![:space:]]*) : ;;
-  *) echo "错误：token 含空白字符，疑似误粘贴。" >&2; exit 1 ;;
-esac
-
-# 备份现有 npmrc（若存在）
-if [ -f "${NPMRC}" ]; then
-  cp "${NPMRC}" "${NPMRC}.bak-$(date +%Y%m%d-%H%M%S)"
-  # 移除旧的 registry.npmjs.org token 行（保留其他 registry 配置）
-  grep -v '^//registry.npmjs.org/:_authToken=' "${NPMRC}" > "${NPMRC}.tmp" || true
-  mv "${NPMRC}.tmp" "${NPMRC}"
-fi
-
-printf '%s%s\n' "${REGISTRY_LINE}" "${TOKEN}" >> "${NPMRC}"
-chmod 600 "${NPMRC}" 2>/dev/null || true
-
-echo "已写入 ${NPMRC}（权限 600）。"
-echo "校验身份："
-npm whoami --registry=https://registry.npmjs.org || {
-  echo "身份校验失败——token 可能无效或权限不足。" >&2
-  exit 1
-}
-echo "完成。现在可以执行：npm publish --registry=https://registry.npmjs.org"