dsh-session-rollover 0.0.0-stage → 1.2.0

package/compatibility/policy.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "package": "@deepseek-ai/dsh",
+  "baseline": "0.2.1-rc.5",
+  "verifiedRuntimeVersions": ["0.2.1-rc.5", "0.2.2-rc.1"],
+  "registry": "https://registry.npmjs.org/",
+  "contracts": [
+    {"package": "@deepseek-ai/dsh-session", "methods": ["get", "list", "snapshotEvents"], "tokens": ["session/event"]},
+    {"package": "@deepseek-ai/dsh-session-title", "methods": ["get", "rename"]},
+    {"package": "@deepseek-ai/dsh-api-session-controller", "methods": ["create", "prompt", "selectModel"]},
+    {"package": "@deepseek-ai/dsh-session-projection", "methods": ["stateOf"]},
+    {"package": "@deepseek-ai/dsh-working-directory", "methods": ["get"]},
+    {"package": "@deepseek-ai/dsh-workspace", "methods": ["list"], "tokens": ["sessionIds"]},
+    {"package": "@deepseek-ai/dsh-agent", "methods": ["get", "current"], "tokens": ["agent/pre-step", "reject"],
+      "versionOverrides": {"0.2.1-rc.5": {"methods": ["get"]}}},
+    {"package": "@deepseek-ai/dsh-client-connection", "methods": ["admit"]},
+    {"package": "@deepseek-ai/dsh-client-ui-conversation", "methods": ["storeFor", "set"], "tokens": ["conversation.session.header.actions", "conversation.input.dock", "blocks"]},
+    {"package": "@deepseek-ai/dsh-client-ui-workspace", "methods": ["openSession"], "alternatives": [["sidebar.session.row.trailing", "sidebar.session.row.leading"]]},
+    {"package": "@deepseek-ai/dsh-client-ui-slots", "methods": ["register"]}
+  ]
+}

package/compatibility/runtime-0.2.2-rc.1.json

@@ -0,0 +1,32 @@
+{
+  "passed": true,
+  "runtimeVerified": true,
+  "checkedAt": "2026-11-11T07:26:36.784Z",
+  "dsh": "0.2.2-rc.1",
+  "plugin": "1.2.0",
+  "platform": "Windows",
+  "environment": "installed DSH CLI with isolated home and profile",
+  "model": "localhost fixture only; no provider credentials or real model quality assessment",
+  "checks": {
+    "tenHumanMessagesOneRollover": true,
+    "workspaceAndDirectoryInherited": true,
+    "modelInherited": true,
+    "frozenTodosAndActiveStep": true,
+    "continuationTodoProgress": true,
+    "archivedReadonly": true,
+    "restoredWritePersistsAcrossRefresh": true,
+    "restoredVolumeDoesNotRolloverAgain": true,
+    "realHostRestartPreservesIndexAndSnapshot": true,
+    "anonymousHTTPStatus": 401,
+    "sourceNavigationAndCopyJSON": true,
+    "inlineSlotLifecycleFixedAndRechecked": true
+  },
+  "browser": "manual automation through computer-use; no plugin warnings after fix and real restart",
+  "limitation": "Host reconnect logged a native released-session-reference error; plugin UI recovered after page reload. No full Bot or production provider acceptance.",
+  "sourceDigests": {
+    "client.js": "25a484847caf9a2ec71b11817d3c147c83fd546f2f80582826df124d742c2b69",
+    "src/server/plugin.mjs": "6afd4b8d5e6c03082240ca2f7304bff9fd3ec0e28bfa32e1fe369458f4a48ae5",
+    "src/server/host-adapter.mjs": "d145284cfa392d64b00d45f40ab308b320d768dc23606bbdbb048c0db6b25dd6",
+    "src/server/compatibility.mjs": "5572940c2bb6fc16dd0393f369417bd9acc025ab65fd7df5f370ededf454ce38"
+  }
+}

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-session-rollover · 宿主挂载补丁（insert 一条 server 插件；不 disabled 任何宿主组件，不改宿主代码）
+# 配置说明：rollover.mode = auto|manual|off；threshold = 轮次阈值（默认 10）；
+# dataDir 留空 → 自动落到 <DSH_HOME>/plugin-data/dsh-session-rollover（代码与数据分离，升级不重置）。
+- insert:
+    - id: session-rollover
+      name: 'dsh-session-rollover'
+      config:
+        mode: auto
+        threshold: 10

package/docs/COMPATIBILITY.md

@@ -0,0 +1,70 @@
+# DSH 升级适配与验收
+
+插件按“公开接口适配、运行前探测、逐版检查、真实宿主验收”维护。不能提前保证尚未发布的 DSH 一定兼容，也不根据版本号猜测新接口。
+
+## 当前范围
+
+- 历史真实宿主验收基线：`0.2.1-rc.5`；`1.2.0` 已在本机安装的 `0.2.2-rc.1` 独立 home / profile 中完成实机验收。
+- `compatibility/policy.json` 的 `verifiedRuntimeVersions` 决定允许安装的 DSH 版本；`engines.dsh` 必须与其逐项一致，发布检查禁止悄悄放宽范围。
+- npm 声明扫描、夹具回归和真实宿主验收分别记录。扫描通过不自动修改版本约束，不自动发布 npm 包，也不自动改用户 profile。
+- `1.2.0` 增加新版宿主支持；已安装 `1.1.1` 的用户需更新插件，npm 同一版本不会被覆盖更新。发布核验记录见 [投稿材料](../marketplace/SUBMISSION.md)。
+
+## 本次验证（2026-11-11）
+
+| 检查 | 结果与范围 |
+| --- | --- |
+| 本地回归 | Windows、Node.js 24.22.1，100 项全部通过（含旧宿主有 agents、无 model.current 时的投影回退） |
+| 公开声明 | `0.2.1-rc.5`、`0.2.2-alpha.3`、`0.2.2-rc.1` 的十一个组件包均通过 |
+| 发布包 | `1.2.0` 实际 tgz 隔离安装、服务端导出、预构建客户端和展示资源通过 |
+| 新版真实宿主 | `0.2.2-rc.1` 验收通过，保留旧基线并增加该确切版本；不放行其他未验收版本 |
+| 远程 CI | 已编写工作流；本地提交不代表远程已启用，需推送默认分支后运行 |
+
+声明报告和安装包校验报告分别保存在 `out/dsh-compatibility.json`、`out/package-verification.json`；它们不是实际宿主验收报告。其他平台及 Node 版本由远程矩阵执行，本轮未在本机验证。
+
+真实宿主记录见 [runtime-0.2.2-rc.1.json](../compatibility/runtime-0.2.2-rc.1.json)：十条用户消息仅分卷一次，继承工作区、目录及模型，待办快照保持不变，新卷实时待办可继续推进，来源跳转、复制 JSON、双向归档开关和宿主重启恢复正常，匿名 HTTP 请求返回 401。本轮使用本地模型夹具，不代表真实服务商模型或 Bot 端完整验收。
+
+重启复验发现并修复 `uiConversation` 子作用域卸载后交接卡 keyed slot 未释放的问题；插槽现在随该子作用域清理，重复注入回归与实机重启复验通过。宿主热重连期间仍观察到原生会话引用已释放的日志，刷新后恢复；这与插件重复插槽问题分开记录，不宣称宿主全局无错误。
+
+## 运行保护
+
+服务端集中在 `src/server/compatibility.mjs` 检查会话存储、标题、创建/提示/模型选择、投影、工作区接口，以及同步读取的返回结构。关键能力不满足时，自动与手动分卷在创建会话、改名、保存重试之前停止；HTTP 建卷操作返回 `503 host-incompatible`，面板显示更新提示。
+
+已有的交接快照与只读状态仍可读取；已注册的服务端归档写入拦截不因分卷暂停而关闭。方法存在不证明事件语义仍相同；如果升级导致插件本身无法加载，这些插件内保护也无法运行，所以仍需遵守宿主版本约束。
+
+新版宿主优先通过 `workingDirectory.get(session)` 和活动 Agent 的 `model.current()` 读取领域状态。缺少这些可选服务时，回退到已验证的 `sessionProjections.stateOf`。后者在较新源码中已弃用，仍纳入声明检查；将来移除时明确失败，由维护者适配，而不是静默换成空目录或默认模型。
+
+基线 `0.2.1-rc.5` 的 Agent 声明尚无 `current()`，检查策略对此确切版本保留显式例外，运行时使用投影回退；后续版本继续检查领域服务接口。未知模型结构会暂停分卷，合法的空选择保持可用。
+
+浏览器针对插槽、导航与输入阻塞服务做能力检查。缺少可选界面能力时记录带插件名的警告，并在可用的面板中提示；不让缺失服务直接导致 React 渲染错误。服务端诊断可通过 `ctx.sessionRollover.compatibility()` 获取；每个会话状态的 `compatibility` 还包含返回结构检查。
+
+## 自动检查
+
+仓库工作流 `.github/workflows/compatibility.yml` 包含：
+
+1. Windows / Linux、Node.js 22 / 24 上运行完整回归、发布格式检查和 tgz 隔离安装校验。
+2. 从官方 npm 注册表枚举基线发布时刻之后的每个 DSH 版本，包含 alpha、rc 与后续补丁；不只检查 `latest`，避免遗漏中间版本。
+3. 下载各版本的十一个公开组件包，核对 SHA512 后只读扫描类型声明，检查插件使用的方法、事件名及界面插槽，并保存报告。不会执行上游安装脚本。
+
+工作流在代码推送、PR、手动触发和每六小时的定时任务中运行；需要提交到 GitHub 默认分支并启用 Actions 才会生效。本地创建文件不等于已启用远程任务。注册表请求或归档校验失败均使任务失败，不视为兼容通过。版本数超过 200 时要求维护基线，不静默截断。
+
+```powershell
+npm test
+npm run check:release
+npm run check:package
+npm run check:dsh -- all
+npm run check:dsh -- 0.2.2-rc.1
+node scripts/check-dsh-compatibility.mjs --list
+```
+
+需要网络与系统 `tar`；Windows 自带的 tar 可用。报告默认写入忽略提交的 `out/dsh-compatibility.json`，也可用 `DSH_COMPATIBILITY_REPORT` 指定位置。`level: public-declaration-smoke`、`runtimeVerified: false` 明确说明证据边界。声明扫描不会证明方法签名、授权、事件顺序或视觉渲染完全兼容。
+
+`check:package` 在自有临时目录安装实际 tgz，复核导出、预构建客户端和全部发布资源，结束后清理隔离目录；包与报告保存在 `out/`。此检查也不代表真实 DSH 宿主验收。
+
+## 每次 DSH 发布后的维护步骤
+
+1. 查看每个新版本的声明扫描和回归结果；发现方法、事件或插槽变化时更新集中适配层，保留旧宿主路径的测试。
+2. 用该版本的真实 DSH，在隔离 home / profile 和本地模型夹具中验证：插件装载、十条真实用户消息只分一次、模型与工作区继承、待办交接、来源导航、重启恢复、归档只读及恢复写入、HTTP owner 授权。不得使用生产会话验收。
+3. 记录 DSH 与插件版本、平台、结果及证据位置。通过后才向 `verifiedRuntimeVersions` 添加确切版本，并同步 `engines.dsh` 的 `||` 列表。旧基线仍用于回归，不能只因新版本号更大便放行。
+4. 更新插件版本、构建预生成客户端、完成打包与隔离安装验证，再发布新 npm 版本。用户通过正常插件升级获得适配；不得覆盖同一 npm 版本。
+
+宿主升级后遇到兼容提示时，应保留数据目录，使用已验收版本组合或更新插件；不要删除快照、绕过宿主版本检查或同时加载两份插件。

package/docs/DETAIL.md

@@ -0,0 +1,44 @@
+# Session Rollover
+
+Split long DeepSeek Harness conversations into volumes and continue with a snapshot of the current work. Supports DSH Web and desktop.
+
+## Features
+
+- Counts actual user messages and creates the next volume after the current turn finishes safely. Default threshold: 10 messages. System context and handoff messages do not count.
+- Adds a first-message handoff card with todos, all active steps, constraints, file references and unfinished job states. Expand the summary, inspect or copy the full JSON, and navigate to the source volume.
+- Displays message count, threshold, volume number and archive state. Each series supports up to 9 volumes; start an independent series with a snapshot to continue beyond that limit.
+- Archives previous volumes as read-only. The input-area switch can allow writing again or restore read-only mode, and persists across reloads and restarts.
+- Provides **Roll over now**, **New independent conversation** and **Usage guide** in the conversation header's `⋯` menu. Current action labels and the built-in guide are in Chinese.
+
+![Handoff card and task progress](./screenshots/host-rollover.png)
+
+## Getting started
+
+Install and enable `dsh-session-rollover` through the DSH plugin manager or marketplace. Desktop users must select the actual desktop profile and restart the host through the desktop app. Open a main conversation and continue working; rollover waits for a safe point after the threshold is reached. Use the source link to inspect the previous volume.
+
+The optional `dsh-todo-progress` plugin shows live task progress. The handoff card remains a historical snapshot. R3 does not require R2 to split conversations.
+
+## Configuration
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `auto` | `auto`: automatic rollover; `manual`: threshold notice only; `off`: no automatic evaluation |
+| `threshold` | `10` | Number of actual user messages |
+| `forceAuto` | `false` | Prevent external part markers from switching auto to manual; safety checks still apply |
+| `dataDir` | Automatic | Custom local data directory |
+
+Explicit manual actions bypass the mode and count threshold, but still require a safe session state. Subsessions do not roll over automatically. Restoring write access to an archived volume does not restart automatic rollover for that volume.
+
+## Data and limits
+
+Default storage: `<DSH_HOME>/plugin-data/dsh-session-rollover`, or `~/.dsh/plugin-data/dsh-session-rollover` without DSH_HOME. Uninstalling preserves data. Renaming the public package does not change storage or service interfaces. Snapshots may contain conversation constraints and local paths; review them before sharing.
+
+Summaries use deterministic extraction, without another model call or API key. Conversation continuation uses the model configured in DSH. Background jobs are recorded as handles and states; processes are not moved, resumed or restarted. Summary text is limited to 1500 characters and the full handoff message to 16 KiB; oversized handoffs fail with a notice. Automatic failures get at most two further retries, triggered by subsequent user messages.
+
+Version `1.2.0` supports DSH `0.2.1-rc.5` and `0.2.2-rc.1`. The latter was tested in an isolated host with a local model fixture for ten-message rollover, model and workspace inheritance, todo continuation, archive controls and restart recovery. Version `1.1.1` excludes DSH `0.2.2-rc.1`; upgrade the plugin while retaining its data directory. This is not full acceptance for production models, Bot group channels or future host versions. Older hosts may omit this long description; the conversation `⋯` menu includes a built-in usage guide.
+
+Replace the old `@deepseek-ai/dsh-session-rollover` dependency and bundle rather than loading both versions. Back up profile configuration and plugin data before upgrading. See the Chinese [publishing and migration guide](./PUBLISHING.md).
+
+[Source](https://github.com/Oak-liuhj/dsh-session-rollover) · [Issues](https://github.com/Oak-liuhj/dsh-session-rollover/issues)
+
+Maintained by Oak-liuhj. Distributed with Apache-2.0 and MIT notices. This is a community plugin, not an official DeepSeek product.

package/docs/DETAIL.zh-CN.md

@@ -0,0 +1,49 @@
+# 会话分卷与续接
+
+让长会话在合适的时机切换到新卷，并携带待办、当前步骤和约束继续工作。适用于 DeepSeek Harness Web 与桌面客户端。
+
+## 可以做什么
+
+- **自动分卷**：默认累计 10 条真实用户消息后，在本轮执行结束、工具调用完成且未压缩时创建下一卷。系统上下文与交接消息不计数。
+- **交接快照**：新卷首条消息包含摘要与完整 JSON，记录待办、全部进行中步骤、约束、文件线索和未完成后台任务状态。
+- **来源回溯**：标题栏显示轮数、阈值及卷序，接续卡可跳转上一卷。每个系列最多 9 卷，之后可新建独立会话继续。
+- **归档保护**：旧卷默认只读，支持“允许再次写入 / 恢复只读”；设置在刷新和重启后保留。
+- **手动控制**：会话标题栏 `⋯` 可提前换会话、携带快照新建独立会话、查看使用说明。
+
+![分卷后的接续卡与待办](./screenshots/host-rollover.png)
+
+## 快速使用
+
+1. 在 DSH 插件管理器或市场安装并启用 `dsh-session-rollover`；桌面用户确认选择实际的 desktop profile，并通过桌面客户端重启宿主。
+2. 打开一个主会话，标题栏会显示本卷轮数。正常对话，达到阈值后等待当前执行结束。
+3. 新卷首条接续卡可以展开摘要、查看或复制原始快照 JSON，并通过来源链接回看旧卷。
+4. 如需继续在旧卷对话，在归档提示中点击“允许再次写入”。恢复写入不会让该旧卷再次自动分卷。
+
+若安装了可选的 `dsh-todo-progress`，右侧面板显示实时待办进度；交接卡保留切卷时的历史快照。R3 不另建任务状态，也不要求安装 R2 才能分卷。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+| --- | --- | --- |
+| `mode` | `auto` | `auto` 自动分卷，`manual` 达阈值只提示，`off` 关闭自动判定 |
+| `threshold` | `10` | 真实用户消息阈值 |
+| `forceAuto` | `false` | 不因外部换段标记而降为 manual；仍执行安全检查 |
+| `dataDir` | 自动 | 自定义本地持久化目录 |
+
+显式手动操作不受 mode 和轮数限制，但仍需要当前会话处于安全状态；子会话不自动分卷。相同系列达到 9 卷时，使用 `⋯ → 新建独立会话` 另开系列，保留快照出处。
+
+## 数据与边界
+
+数据保存在本机，默认目录为 `<DSH_HOME>/plugin-data/dsh-session-rollover`（未配置 DSH_HOME 时为 `~/.dsh/plugin-data/dsh-session-rollover`）。卸载保留历史数据，公开包名更换也不改变该目录。交接快照与 JSON 可能包含会话约束和文件路径，分享前请检查内容。
+
+摘要是确定性摘录，不调用额外模型；继续对话仍使用 DSH 已配置的模型，无需额外 API Key。后台任务只继承句柄和状态，不迁移、恢复或重新启动进程。正文摘要上限 1500 字符、完整交接消息上限 16 KiB，超预算会拒绝交接并提示。自动失败最多再试两次，由后续用户轮次触发。
+
+`1.2.0` 支持 DSH `0.2.1-rc.5` 与 `0.2.2-rc.1`；后者已在独立环境验证十轮分卷、模型和工作区继承、待办续接、归档开关及重启恢复。旧版 `1.1.1` 的版本约束不支持 `0.2.2-rc.1`，需升级插件并保留数据目录。不代表所有模型、Bot 群端或后续宿主版本均已验收。旧宿主可能不显示本长说明，可从会话 `⋯ → 使用说明` 查看内置指南。
+
+## 升级与支持
+
+旧 `@deepseek-ai/dsh-session-rollover` 用户须替换依赖和 bundle，避免同时加载新旧包；升级前备份配置与插件数据。详见 [发布与升级指南](./PUBLISHING.md)。
+
+[源码](https://github.com/Oak-liuhj/dsh-session-rollover) · [反馈问题](https://github.com/Oak-liuhj/dsh-session-rollover/issues)
+
+维护者 Oak-liuhj。本项目分发包含 Apache-2.0 与 MIT 两份许可证。社区插件，与 DeepSeek 官方无隶属关系。

package/docs/DEVELOPMENT.md

@@ -0,0 +1,104 @@
+# 开发与集成
+
+面向插件维护者和集成方。用户安装、配置与操作入口见 [README](../README.md)。
+
+## 服务和 HTTP 接口
+
+```js
+const result = await ctx.sessionRollover.rollover(sessionId);
+// status: rolled-over | skipped | failed
+// 成功时 newSessionId；其他情况查看 reason。
+
+const info = ctx.sessionRollover.info(sessionId);
+// source, handoff, readonly, sealed, turnCount, threshold,
+// volume, cap, capped, summaryRetry, retryLimitReached,
+// previousTurnCount, nextSessionId, degraded 等。
+
+ctx.sessionRollover.setReadonly(sessionId, false); // 仅允许已归档卷
+```
+
+R2 面板可继续调用原有 rollover/info 服务；无实时 `todo/write` 时继承交接快照，出现实时事件后以日志为准，包括显式清空待办。
+
+浏览器控制接口要求宿主 owner 身份；POST 校验同源、JSON、请求体大小及会话 ID，不接收客户端提供的交接正文。
+
+| 方法与路径 | 用途 |
+| --- | --- |
+| `GET /api-dsh-session-rollover/session?session=<id>` | 会话状态与快照 |
+| `POST /api-dsh-session-rollover/session` | `{sessionId, action: 'readonly', readonly: false}`；或 `action: 'rollover' / 'new'` |
+| `GET /api-dsh-session-rollover/pending?session=<id>` | 已认证浏览器取走一次性提示；取件即删除，不是展示确认协议 |
+
+`connection` 为显式必需注入；`jobs`、`agentDefaultModel` 通过独立可选注入获取，避免 Cordis 未声明服务访问报错。
+
+`workingDirectory`、`agents` 同样通过可选注入获取，用于新版领域状态读取。`sessionRollover.compatibility()` 返回关键方法的能力报告；会话 `info().compatibility` 还检查读取结果形状。逐版检查、CI 与真实宿主验收流程见 [升级适配指南](./COMPATIBILITY.md)。
+
+## 项目结构
+
+```text
+index.js                         稳定服务端入口
+client.js                        生成的宿主 ModuleLoader 浏览器入口
+cordis.patch.yml                 挂载补丁
+src/
+  domain/                        计数、切点、模式、命名、待办、摘要与载荷纯规则
+  application/                   T0–T8 分卷编排与交接消息排版
+  storage/                       索引、快照、只读、重试、提示队列
+  server/                        生命周期、公开宿主适配器、HTTP 路由
+  client/
+    rollover-ui.js              React 状态订阅、摘要卡和归档输入保护
+    toast-client.js             原提示实现与 ModuleLoader 构建模板
+  *.mjs                          旧路径兼容转导出
+scripts/build-client.mjs         无第三方构建依赖，嵌入 UI factory
+test/                          按 domain/application/storage/server/client/package 分类
+docs/architecture.md           分层、失败边界及维护规则
+docs/r3-validation.md           本轮修复、验证和边界
+docs/r3-demo.html               固定数据交互原型
+```
+
+根入口默认/具名导出和旧 `src/*.mjs` 子路径保持兼容；新代码引用分类目录。修改 `src/client/` 后运行构建，不直接编辑生成的 `client.js`。
+
+## 数据目录
+
+优先级为配置 `dataDir` → `DSH_ROLLOVER_DATA_DIR` → `<DSH_HOME>/plugin-data/dsh-session-rollover` → `~/.dsh/plugin-data/dsh-session-rollover`。环境变量空白视为未设置。
+
+| 文件 | 内容 |
+| --- | --- |
+| `cluster-index.json` | 七字段簇记录及 `turn_counts`，同文件原子替换 |
+| `handoff-<id>.json` | 完整历史交接快照 |
+| `readonly-<id>.json` | 双向只读设置；优先于索引默认值，兼容旧聚合标记 |
+| `retry-<id>.json` | 摘要尝试次数 |
+| `pending-cleanup.json` | 废弃新卷；仅登记，不自动删除宿主会话 |
+| `storage-health.json` | 建卷前存储预检 |
+| `notices.json` / `plugin.log.jsonl` | 提示队列/去重与诊断日志 |
+
+每个文件采用临时文件加 rename，不能保证宿主会话与多个文件之间的跨系统原子提交。提交后提示/重试状态写盘失败仍保留成功结果并标记降级，避免重复创建新卷。索引恢复依赖宿主中仍保存的交接消息；历史消息也已删除时无法凭空恢复。
+
+## 开发与验证
+
+开发验证使用 Node.js 24.22.1、npm 11.19.1，无需安装第三方依赖。
+
+```powershell
+npm test
+npm run check:release
+npm run check:package
+npm pack --dry-run
+npm pack --pack-destination <输出目录>
+```
+
+`npm test` 构建后运行 `test/**/*.test.mjs`，不把 support 夹具当测试。发布前检查实际压缩包解压导入、静态入口与兼容导出，而不只看 dry-run 清单。
+
+既有验证已在**已安装 DSH 的隔离 Web profile** 中接入本地模型夹具，验证真实宿主事件、浏览器加载、十条真实用户消息分卷、`todo_write` 接续、摘要/JSON/剪贴板一致、来源导航和双向只读开关；这不是生产模型质量或 Bot 群端验收。详细记录见 [验证文档](./r3-validation.md)。
+
+## 兼容与边界
+
+`dsh.verifiedDsh: 0.2.1-rc.5`、`dsBot.min/verified: 0.2.6` 是保留的历史适配元数据，不代表新增了群端版本验收。宿主升级后需复验公开注入、插槽、用户消息来源与改名行为。
+
+- 摘要是确定性摘录，不调用语言模型；文件路径仅为线索，不证明文件已修改。当前未迁移或恢复后台进程。
+- 自动重试由后续用户轮次触发，没有后台定时无限重试。已封卷恢复写入只允许继续对话，不重新分卷。
+- 正式界面的输入保护依赖公开 `conversation.blocks`；侧栏徽标仅显示在宿主开放的列表装饰槽上，宿主运行状态图标可能暂时占用该位置。
+- 提示定位沿用原实现，依据第一个富文本输入框；多编辑器页面需另行复验。
+- 自动化测试、交互原型、真实宿主加模型夹具分别提供不同证据，不替代真实服务商模型和 Bot 端完整业务验收。
+
+## 发布与维护
+
+发布步骤、scoped 旧包迁移和市场展示资源见 [发布指南](./PUBLISHING.md)。分层、事务失败边界和前端插槽说明见 [架构文档](./architecture.md)。
+
+浏览器入口须随源码一同提交。GitHub 安装使用预构建入口，不依赖安装时构建。更改包名、导出、展示资源或挂载补丁后，运行 npm run check:release，并核对实际 tgz 中的文件。

package/docs/PUBLISHING.md

@@ -0,0 +1,80 @@
+# 发布与升级指南
+
+公开包名为 `dsh-session-rollover`，当前版本 1.2.0，维护者 Oak-liuhj。仓库：[Oak-liuhj/dsh-session-rollover](https://github.com/Oak-liuhj/dsh-session-rollover)。支持在宿主中直接填写 npm 包名安装；市场收录不代替 npm 发布。实际公开版本以 npm 官方源和 GitHub Release 为准，发布核验记录见 [投稿材料](../marketplace/SUBMISSION.md)。
+
+## 构建与打包
+
+```powershell
+npm test
+npm run check:release
+npm run check:package
+npm pack --pack-destination D:/release
+```
+
+`prepack` 构建并核对清单、挂载补丁、ModuleLoader 包名、双语说明、图标和截图。GitHub 源安装依赖已提交的 `client.js`，不运行 prepare 或安装时构建。包无第三方运行时依赖。除静态检查外，还应解压实际 tgz 并验证入口、兼容导出及资源是否齐全。
+
+## 发布到 npm
+
+1. 使用有权维护此包的 npm 账号登录。浏览器登录与双重验证由账号持有人完成，不将密码、验证码或令牌写入仓库。
+2. 完成上述测试、发布校验和打包，审核 tgz 文件清单；首次发布前确认包名可用。
+3. 发布审核通过的同一个 tgz，避免检查后重新打包产生不同内容：
+
+```powershell
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm publish "D:/release/dsh-session-rollover-1.2.0.tgz" --access public --registry=https://registry.npmjs.org/
+npm view dsh-session-rollover@1.2.0 version dist.integrity --registry=https://registry.npmjs.org/
+```
+
+4. 在隔离目录从 npm 安装并核对包名、版本、挂载补丁、预构建客户端与模块导入；只有 npm 返回该版本且下载验证通过，才确认包名安装可用。
+5. 国内 npm 镜像同步可能晚于官方源。若官方源可安装而镜像返回 404，应等待镜像同步或使用 GitHub 安装源。
+
+`publishConfig.registry` 固定为 npm 官方源；公开包名为 `dsh-session-rollover`。npm 已发布的同一版本不能覆盖，后续发布需先提升版本号。认证和双重验证失败时保留待发布包，完成认证后继续发布，不绕过验证。
+
+### 已进入暂存区时
+
+使用支持 `npm stage` 的 CLI，先查询已有暂存记录，再确认同一个包：
+
+```powershell
+npm stage list dsh-session-rollover --json --registry=https://registry.npmjs.org/
+npm stage view <stage-id> --json --registry=https://registry.npmjs.org/
+npm stage approve <stage-id> --registry=https://registry.npmjs.org/
+```
+
+核对版本、`latest` 标签和 shasum 与已审核 tgz 一致。`staged` 仅表示待审批，同一暂存版本不能再次普通发布；保留原 tgz 和 stage id，完成审批后再执行下载与隔离安装验证。首次暂存可能产生 `0.0.0-stage` 占位版本，不能以包名可查询作为正式版本发布成功的依据。
+
+CLI 登录授权、注册安全密钥和本次发布的本人认证是不同步骤。账号已启用 2FA 但审批仍要求配置时，先核对账号状态并尝试全新登录，不反复注册密钥；认证 URL 失效也不代表 tgz 丢失。若全新登录后问题仍存在，保存不含凭据的错误、时间和 stage id，向 [npm 支持](https://www.npmjs.com/support)反馈。不要通过关闭 2FA 或创建绕过认证的令牌处理审批异常。
+
+认证请求有有效期，应在本人准备好设备验证后再启动命令，并让 npm 直接打开系统浏览器。不要先生成地址再等待聊天确认；手工打开时核对完整地址，避免回调参数混入中文标点或正文。有效期已过时重新运行原审批命令，不复用旧地址。
+
+## 从 scoped 旧包迁移
+
+1. 记录真实运行的 profile，桌面通常是 `~/.dsh/profiles/desktop`。备份该 profile 的 package.json、锁文件、Cordis 配置和旧插件目录，并备份 `<DSH_HOME>/plugin-data/dsh-session-rollover`；自定义 dataDir 也需备份。
+2. 通过桌面插件管理器/宿主支持的依赖管理渠道，将 `@deepseek-ai/dsh-session-rollover` 替换为新包。CLI 可使用 `dsh plugin --profile desktop remove @deepseek-ai/dsh-session-rollover`，然后 `dsh plugin --profile desktop add <本地tgz或GitHub源>`。分步操作时先停止宿主，避免短暂缺包。
+3. profile 的 `dsh.profile.bundles` 只保留新包一次；显式 Cordis 节点的 `name` 改为新包名，原 `id: session-rollover`、用户配置值和相邻插件保留。不可同时加载两个包来注册同一个服务。不能只覆盖 node_modules 而保留过期依赖来源。
+4. 从桌面客户端重启实际宿主；不要用普通 Web profile 的重启操作接管桌面生命周期。
+5. 核实已加载目标版本、面板图标/简介、会话 `⋯ → 使用说明`、旧卷快照和只读状态。不要为了安装验证向生产会话发送测试消息。
+
+本次更名不迁移数据；数据目录、`sessionRollover`、HTTP 路由、Cordis id 和旧 `src/*` 导出保持兼容。卸载也不删除数据。回滚时停止宿主，恢复备份的 profile 配置、锁文件和依赖，再重启；不要覆盖更新后已产生的用户数据。
+
+## 市场展示
+
+| 资源 | 作用 |
+| --- | --- |
+| package.json | 包名、版本、作者、仓库、兼容声明和 PNG 图标 |
+| locale/zh.json、locale/en.json | 插件面板的标题、简介及 meta.detail 路径 |
+| docs/DETAIL.zh-CN.md、docs/DETAIL.md | 中英文功能、入口、配置、数据和限制说明 |
+| assets/icon.png | 方形市场卡图；SVG 仅作可维护源文件 |
+| screenshots.json | 1–8 张仓库内图片；宿主截图来自隔离夹具，未使用用户生产会话 |
+| marketplace/*.yml | 待提交市场目录的唯一条目 |
+
+旧宿主可能只显示标题/简介/图标，不支持 meta.detail；会话菜单内置指南补足入口。截图中的右侧实时任务面板由独立的可选 R2 插件提供。截图是本地模型夹具演示，不证明生产模型效果。
+
+## 外部发布顺序
+
+1. 审核本地改动、验证记录与实际包；确认没有凭据、会话数据或机器配置进入包。
+2. 将代码及预构建 client.js 推送至公开仓库；如使用 tag / Release，确保引用同一版本的完整资源。需要支持 npm 包名安装时，再按上文完成 npm 发布与下载验证。
+3. 等仓库创建满一天并确保 topic 为 `dsh-plugin`。按 [投稿材料](../marketplace/SUBMISSION.md) 向官方插件目录发起 PR。
+4. 确认市场抓取后的简介、图标、截图及安装源正确；外部收录前不要宣称已上架。
+
+`engines.dsh` 由 `compatibility/policy.json` 中实际完成宿主验收的确切版本组成，不推测扩大兼容区间；声明扫描通过后仍需执行 [升级验收](./COMPATIBILITY.md)。许可证声明为 `(Apache-2.0 AND MIT)`，必须同时分发 LICENSE、LICENSE.upstream 和 NOTICE。

package/docs/architecture.md

@@ -0,0 +1,71 @@
+# 架构与维护说明
+
+项目使用 JavaScript ESM，服务端无需编译；浏览器 UI 通过无依赖脚本生成单文件 ModuleLoader 入口。
+
+## 模块边界
+
+| 层 | 职责 | 依赖 |
+| --- | --- | --- |
+| `domain/` | 用户轮次/切点、模式、命名、摘要、载荷和内存簇索引 | 不访问宿主、磁盘、网络或 DOM |
+| `application/` | T0–T8 顺序、预算、失败补偿与消息排版 | domain；以参数传入 host、state、index、persistence |
+| `storage/` | 索引、只读、快照、重试和提示持久化 | 可依赖 domain，不依赖插件类 |
+| `server/` | 生命周期、事件、安全闸、公开服务适配和 HTTP | 组装各层 |
+| `client/` | 共享状态订阅、交接卡、归档输入保护和 toast | 宿主 React、slots、uiWorkspace、uiConversation、conversation |
+
+唯一插件类位于 `src/server/plugin.mjs`。根 `index.js` 保留默认/具名导出，旧 `src/*.mjs` 仅转导出，兼容包 `./src/*` 使用者。
+
+`npm run build` 将 `src/client/rollover-ui.js` 的 factory 嵌入 `toast-client.js` 模板，生成根 `client.js`；`build:check` 防止源码与产物不一致。测试与打包前自动构建，无额外 npm 运行时依赖。
+
+## 入口与切点
+
+自动入口为 `session/event` 的 `turn/end`、`compaction/end`、`part/end`、`tool/result`，同时保留 `agent/pre-step` 兼容检查。`countTurns` 统计真正的用户消息，`hasOpenTurn` 检查执行是否结束，两者互不代替。宿主内部时间、技能目录、运行时上下文及交接注入不占用户轮数。
+
+同一会话的自动/手动入口共用 `rollover:<id>` 锁；`lastCheckedTurn` 防同轮重复检查。不安全工具/换段切点释放本轮检查标记，等结束事件再次判定。`forceAuto` 不绕过切点检查。
+
+服务端在后续回合首步拦截归档只读。手动 `ctx.sessionRollover.rollover` 绕过 mode/threshold，但仍检查执行状态、封卷、只读、子会话、工具与预算。`setReadonly` 只允许已归档卷，写入单卷设置后再同步索引；单卷设置为查询优先来源，保持重启一致。
+
+必需服务由 static inject 声明，包括 HTTP owner 准入使用的 `connection`。可选 `jobs` / `agentDefaultModel` 分别使用 `ctx.inject`，服务撤销时清理引用，禁止跨 Cordis 注入范围直接取值。
+
+## 事务阶段
+
+| 阶段 | 工作 | 失败边界 |
+| --- | --- | --- |
+| T0 | 读取快照、检查执行中回合/换段、统计用户轮数 | 不建卷 |
+| T1 | mode 和有来源信息的外部 marker 检测 | 不建卷；manual 可提示 |
+| T2 | 子会话/工具安全闸、命名预演、一次捕获 todos/jobs | 不建卷 |
+| T3 | 四段正文与完整载荷、1500 字符/16 KiB 闸、存储预检 | 不建卷、不裁剪关键内容 |
+| T4 | 按来源 workspace/cwd 创建空会话 | 原会话不变 |
+| T5 | 保存快照、继承模型、注入首条消息 | 原会话不变；废弃卷登记 pending |
+| T6 | 必要时原会话改名 | 失败登记 pending |
+| T7 | 新卷改名 | 失败尝试恢复原标题，回滚失败独立告警 |
+| T8 | 索引/计数提交、旧卷只读、清理 pending | 分文件原子替换；异常显式 degraded |
+
+这不是跨宿主与多个 JSON 的原子数据库事务。建卷前的存储预检发现常见目录不可写问题；提交后辅助状态/提示失败不能将已成功建卷重新报告成失败并再次创建。清理登记本身失败也记录降级，避免二次异常覆盖主结果。
+
+真实 `vol_no` 独立于命名后缀；冲突使后缀超过 9 时使用索引确认后缀，避免名称嵌套，也避免把普通 `Q3-26` 猜成卷号。第九卷显式接续可创建新簇，父链为 null，JSON 来源 ID 只提供历史出处；此路径不封存或改名来源。
+
+## 一致性与恢复
+
+一次适配器捕获源事件与 live job 列表；一次事务取 todos/jobs 后，同时用于人读和机器快照。保留全部 active 步骤、约束和文件；正文四段映射为 UI 六块内容及卷标识/健康两组。用户原文和路径不能用静默截断满足预算。
+
+待办取最后一个合法 `todo/write`。完全没有实时事件时继承快照，明确空数组表示清空。后台任务合并 workflow、`job/registered` / `job/settled` 和可选 live registry，按 owner 过滤，记录 running/stopping 等状态而不迁移进程。
+
+摘要失败尝试次数写 `retry-<id>.json`，初次加两次重试后停止，重启不重置；后续用户轮次提供重试机会，手动操作可开始新尝试。
+
+启动读取合法索引，然后扫描宿主中已注入的 `rollover: v1` 交接消息，补齐缺项或重建丢失/坏索引；使用快照 true volume，旧快照可沿父链推导。pending 废弃卷不参与恢复，不凭任意标题后缀归簇。显式 readonly false 不被重建覆盖。旧 `rebuildFromTitles` / `createSummaryRetry` 导出继续兼容，但运行时使用上述更严格恢复与持久化尝试流程。
+
+## 浏览器与控制面
+
+每会话共用轮询缓存，多 UI 订阅复用请求；最后订阅卸载后清理轮询。切换会话当帧不借用旧卷状态。
+
+正式接口 `GET/POST /api-dsh-session-rollover/session` 通过宿主 `connection.admit` 检查 owner；POST 校验 Origin、JSON、体积与 ID。摘要由服务器生成，不接受浏览器传入快照。旧 pending GET 继续用于一次性 toast，取走即删，不确认展示。
+
+归档输入使用公开 `conversation.blocks`，释放时撤销自己的原因并恢复其他插件最新状态。不要覆盖 `conversation.composer.bar`：其子槽拥有独占声明和 renderSlot 授权，简单包装会崩溃，重复声明也会被拒绝。
+
+首条 userText 渲染卡固定显示历史快照；后续 R2 进度消费实时待办。缺少 userText 扩展时在 dock 回退展示。列表优先 trailing，旧宿主回退 leading；宿主状态图标可能临时占据 leading。来源导航与自动跳转区分：只有当前浏览器观察到活动→封卷时跳新卷，回看旧卷不跳回。
+
+## 验证约定
+
+规则改动在 domain 测试；副作用/补偿用 application 夹具；重启/存储/权限/注入用 server 与 storage 测试；UI 资源释放和提示用 client 测试；兼容导出用 package 测试。运行 `npm test`、`npm run build:check`，并实际解包导入 npm pack 产物。
+
+宿主接口与前端加载变更需要真实宿主浏览器验证。已安装宿主加本地模型夹具、交互原型和纯测试分别记录证据；不能将其等同于生产服务商模型或 Bot 群端验收。详见 [R3 修复与验证记录](./r3-validation.md)。

package/docs/live-host-validation.json

@@ -0,0 +1,37 @@
+{
+  "passed": true,
+  "host": "Installed DSH web profile (isolated home)",
+  "model": "local OpenAI-compatible fixture, not a real model",
+  "oldId": "session-3787ec68-6c4f-4b19-9b36-ded3ed0eeb45",
+  "newId": "session-5d41f38d-2759-465c-b2d9-f26292fb2b8d",
+  "rounds": {
+    "verifiedPersistedHumanMessages": 10,
+    "verification": "resumed final UI checks on existing completed rollover"
+  },
+  "old": {
+    "turns": 10,
+    "readonly": true,
+    "volume": 1
+  },
+  "next": {
+    "turns": 0,
+    "volume": 2,
+    "todoCount": 8,
+    "currentStep": 4
+  },
+  "checks": [
+    "10 actual human messages -> one rollover",
+    "native context excluded",
+    "inline first-message card",
+    "exact snapshot and clipboard",
+    "model tool continuation step4 -> step5",
+    "source navigation remains in old volume",
+    "composer blocked",
+    "switch on/off persists across refresh",
+    "sidebar badges on legacy host leading slot",
+    "real host dark theme",
+    "no browser errors"
+  ],
+  "errors": [],
+  "requests": []
+}

package/docs/marketplace-validation.md

@@ -0,0 +1,22 @@
+# 1.1.1 发布准备验证
+
+验证日期：2026-11-07。公开包名 `dsh-session-rollover`；保留既有服务、HTTP 接口、Cordis id 与数据目录。
+
+## 已验证
+
+- 原有 86 项 domain / application / storage / server / client / package 回归全部通过。
+- 已安装的 DSH 在独立 `r3-market` profile 中实际加载新 ModuleLoader 包名；本轮没有发送模型请求。
+- 插件管理页面实际显示中文标题“会话分卷与续接”及新简介。
+- 会话 `⋯ → 使用说明` 可打开、收起、关闭；重新打开操作菜单时重置说明状态，Escape 可关闭。
+- 浅色、深色说明弹窗已截图检查；390×720 视口下无水平溢出，底部按钮可滚动触达。
+- 修复窄窗口下菜单按钮与旧宿主右侧工具区重叠，使用正常指针点击复验通过。
+- 浏览器检查无 pageerror。验证通过 Playwright 驱动宿主 Web 页面；未使用 Windows 桌面 UI 自动化工具。
+- 实际 tgz 解压后通过同一发布校验，28 个模块可导入；说明、图标、截图及双许可证齐全，未打包 profile、浏览器认证状态或运行日志。
+- 正式 desktop profile 已通过本机 CLI 从旧 scoped 1.0.0 迁移至新包 1.1.1，并重启桌面宿主。市场运行态接口确认新包为 live，只存在一条新包 bundle，旧依赖已移除。
+- 原 profile 配置、旧插件和分卷数据已备份；安装前后全部 9 个原数据文件一致。启动后 8 个状态文件哈希仍一致，仅诊断日志追加启动记录。其他声明依赖和相邻 R2 1.2.1 保持原值。没有向生产会话发送测试消息。
+
+## 证据范围
+
+`docs/screenshots/host-*.png` 是 1.1.0 功能修复阶段在隔离 profile、本地模型夹具中取得的真实宿主图；本轮保留作为分卷行为演示。`help-*.png` 是 1.1.1 在实际宿主内生成的说明弹窗。均未使用生产会话截图。
+
+完整分卷逻辑的前一轮验证范围见 [R3 验证记录](./r3-validation.md)。本轮不扩大 Bot 群端、生产模型或后续 DSH 版本的验收声明。市场格式检查与本地安装成功也不代表插件市场已收录。

package/docs/prototype-validation.json

@@ -0,0 +1,10 @@
+{
+  "passed": true,
+  "geometry": {
+    "height": 484,
+    "scrollHeight": 950,
+    "scrollTop": 342
+  },
+  "errors": [],
+  "checks": 14
+}