# 验证状态与验收对照

> 面向开发者/维护者的技术文档。测试、E2E 与跨代兼容的完整记录。

## 验证状态

### UI 面：跨代次截图矩阵（`npm run verify:ui`）

`verify:kernels` 证明"装配起来、到点发得出去"，`--steps type` 证明"能对着那一代的类型编译"；
**UI 面**是第三件事："画出来、点得动"，只能看。所以这里给的是**结构性判据 + 截图**：

| 每代三张 | 判据 |
|---|---|
| 作曲行 + 定时按钮 | `[class*=ss-sched-btn]` 存在（client bundle 在该代次加载成功） |
| 待发送 dock 行 | 发 `/later +30m …`（真实命令通道，不烧模型）后 `[class*=ss-dock-row]` 出现 |
| 面板展开 | 点按钮后 `[class*=ss-panel]` 出现 |

产物 `.verify/ui-matrix/{matrix.json,matrix.html,*.png}`（gitignore）。不设像素阈值 —— 跨代次的
字体渲染差异不该被当回归；截图是给人复核的。

**方法与历次结论**记在 [`notes/ui-matrix.md`](notes/ui-matrix.md)（含"每代拍什么/判什么"、
三处跨代次差异、以及 append-only 的结论表）；**进仓证据**在
[`media/ui-matrix/`](media/ui-matrix/)：一页拼图 `matrix.png` + 每代 `-dock.png` 缩略图 + `manifest.json`
（把"哪次运行、什么结论、哪个文件、文件 sha256"钉在一起）。

实例引导自包含在 `scripts/ui-matrix/instance.mjs`，处理了三处实测出来的跨代次差异：
`.bin/dsh` 可能是软链（npm 树）或 shell 脚本（pnpm 树，混用会 `SyntaxError`）；
模块回退层要的 `<dsh 包>/node_modules/package.json` 占位；`cordis.patch.yml` 里 **hmr 必须开启**
（0.1.2 的 `watchUserPatches()` 缺 hmr 服务会直接抛错）。隔离靠 `DSH_HOME`，**没有** unshare/容器 ——
插件若往 `DSH_HOME` 之外写，这里挡不住（dsh-later 已实测只写 DSH_HOME）。


### 跨代回归脚本的四个面（2026-10-26，issue #97 补齐后两个）

`npm run verify:kernels`（`scripts/verify-across-kernels.mjs`）是"某代次到底支不支持"的判决者，
所以它的口径本身要可复核。现在它分四个面，`--steps` 可选（默认 `mount,function`）：

| step | 面 | 判据 |
|---|---|---|
| `mount` | 装配 | 真内核冷启动、插件 `activated`、AgentRegistry 可用 |
| `function` | 功能 | `at` 五种文法经真实命令派发 + 到点投递的事件形状 |
| `type` | 类型 | 依赖线换成该代次后跑**两个** tsconfig（复用 `typecheck-all.mjs`，不短路） |
| `gate` | 门禁 | 该代次自己的 `evaluatePluginCompatibility` 判一遍 + 最新语义判一遍，两值进产物 |

三点口径（都是这轮实测出来的）：

1. **代次按 rc 粒度判**：`dsh@0.1.5-rc.1` 的内部依赖 `^0.1.5-rc.1` 会装出 `rc.3` 的兄弟包。
   脚本现在逐包 pin + 记录 `requested`/`resolved`，不一致即判「未判定（组合漂移）」。
2. **"跑现成 `lib/` 产物能挂上"不算支持**：类型面才是能拦住"旧内核没有该能力/符号改名"的那一面
   （`0.1.5` 19 条、`0.1.2` 宿主 2 条 + client 21 条）。
3. **越界自检覆盖 `sessions`/`storages`/`plugin-state` 与根级文件**：只扫 `sessions/` 会漏掉
   `plugin-state/` 的残留。


> ⚠️ **支持面调整（2026-10-26，issue #95 / PR #98 + #101）：内核下界为 `>=0.1.2-rc.1`。**
> 本文档下面记录的「0.1.1 / 0.1.2 / 0.1.5 已通过」是**当时的实测**，它们只证明了装配与功能面，
> 没证明**类型面**。把整条 `@deepseek-ai/dsh*` 依赖线换成目标代次后跑本仓 tsc，当时的结论是：
> `0.1.5-rc.1` 19 条红（图标改名 + props 形状）、`0.1.2-rc.1` 2 条红且 client 项目被 `&&` 短路没跑、
> `0.1.1-rc.2` 依赖在 registry 未发布**无法自证**。
>
> 据此先把下界收到 `0.1.7-rc.1`（PR #98），随后按同一份测量把能兼容的补回来（PR #101）：
> **`0.1.2-rc.1` 与 `0.1.5` 线（按 rc.3 验证）现在两个 tsconfig 都是 0 条错误**，且装配与到点投递在真内核上跑绿，已回到代次表；
> `0.1.1-rc.2` 仍不入表（依赖装不出，任何工具都给不出结论）。
> 补法见 `src/client/primitives-compat.ts`（图标/Tooltip/FileTypeIcon/fileSizeText）、
> `src/client/workspace-path-compat.ts`（fileMediaUrl）、`src/upstream-shims.ts`（宿主侧类型缺口），
> 以及 0.1.2 运行期把文件附件降级成文本的说明。
>
> 新的**入表标准 = 装配/功能 + 跨代类型编译两面都过**；表里**当时**六代
> （`0.1.2-rc.1` / `0.1.5-rc.3` / `0.1.7-rc.1` / `0.1.7-rc.2` / `0.2.0-rc.2` / `0.2.1-rc.2`）两面都已通过。
> （这句是 1.8.0 前后的记录，数量保留不改；**现状是 9 条**，逐代结论见下文「跨内核代次」各节与
> §0.2.2-alpha.2。）
> `0.1.5` 列 rc.3 而非 rc.1：rc.1 的默认安装会 caret 混装 rc.3 组件、装配即失败（与本插件无关），
> 用户实际拿到的就是统一 rc.3。


- **单元/集成测试（2026-11-02 复核，基线 `main@33c76b3`，取代此前的 183 与 620）**：
  **747 条 / 747 passed / 0 failed / 0 skipped**（`npm test`，71 个文件），
  `node scripts/typecheck-all.mjs` 两个 tsconfig 都通过，`npm run build` 幂等（重跑后 `lib/` 零脏改）。
  ⚠️ **同一份代码在隔离 worktree 里报的是 743 passed / 4 skipped**，这不是回归：那 4 条是
  `tests/peer-facet-integration.test.mjs` 的**真对端**用例，skip 条件是「逐级向上找不到
  `dsh-group-status` 仓」。主仓 `dsh-plugins/dsh-later` 旁边就放着那个仓 → 真跑；
  建在 `~/dsh-worktrees/<x>` 的 worktree 找不到 → skip。
  **报测试数请连带说明在哪棵树上跑的**（issue #103 的落点就是这句没写清楚）。
- **历史数量（保留原文，别当现状读）**：2026-09-28 复核 **183 个全绿**；2026-10-27 复核
  **620 条 / 613 passed / 0 failed / 7 skipped**（基线 `main@4ef6af5`，含 `SKILL.md` provider 那 30 条；
  那 7 条 skip 全在构建端到端用例，条件 `skip: !existsSync('<repo>/node_modules/esbuild')`，
  在没装依赖的 worktree 里跑会跳，CI 装齐依赖时会跑）。
  更早「typecheck 有预存依赖类型噪音」的记录已随 `0.1.7` 适配一并消除 —— 噪音的真实后果见下文
  「一个隐蔽的构建耦合」：**任何类型错误都会让 `build.mjs` 从 tsc 回退到 esbuild bundle**，
  而 bundle 会内联本地模块、产生双副本，进而改变运行时语义。故 typecheck 干净
  不只是代码整洁问题，**它是构建产物形态的前置条件**。
- **独立实例线上 E2E（Playwright 无头真点 UI）**（**2026-09-08 的记录，不是现状态口径**；
  「≈计划 75s，实测 72s」是那一轮的单次观测，别当 SLA 读）：按钮渲染→开面板→自定义时间→确认→
  芯片出现→任务列表可见→到期真触发→对话出现 `user/message`。
  ⚠️ 那句里的 `source=plugin:later` **已随 issue #75 过时**：`kind:'plugin'` 从 `0.1.7-rc.1` 起被
  v4 准入拒绝，注入消息一律用 `kind:'schedule'`，更早的代次才是 `plugin` —— 判定在
  `src/schedule-compat.ts`，逐代结论见下文「已解决（2026-10-23，issue #75）」。
  要拿当前的端到端证据，跑 `npm run verify:kernels`（装配 + 真投递事件形状）与
  `npm run verify:ui`（真 GUI），这两条命令的产物才是活的。
- **内核代次兼容（2026-09-07 实测）**：`0.1.1-rc.2` 与 `0.1.2-rc.1` 两代均通过 host 入口链接（运行时符号 17/17 存在）、headless 真实启动（停在 `MISSING_CREDENTIAL`，在插件加载之后）与 web 真实启动（`lib/client.js` HTTP 200）。跨代做法有三处：
  1. **peer 枚举完整覆盖**：除了 `dsh-schedule / dsh-session / dsh-session-projection`，把宿主直接 import 的 `@deepseek-ai/{cordis,dsh-agent,dsh-commands,dsh-llm,dsh-settings,dsh-tools,schemastery}` 全部列入 peer + dev——`0.1.1-rc.2` 经 `dsh-schedule` 传递提升到顶层 `node_modules/@deepseek-ai/` 时这些包是可达的；`0.1.2-rc.1` 的 hoisting 策略变化把它们留在 `.pnpm/`，**未声明 peer 的会运行时报 `ERR_MODULE_NOT_FOUND`**（已实测 `lib/runtime.js` import `@deepseek-ai/dsh-llm` 在 0.1.2 直接崩）。
  2. **设置命名空间**写作 `'dsh-later' as SettingsNamespace`（`settingsNamespace()` helper 在 `0.1.2` 已删除，运行时导入会让整个模块链接失败）。
  3. **设置卡片所需的 `SettingsScope`** 在 `src/client/components/SchedulerSettingsCard.tsx` 内本地声明，不从 `@deepseek-ai/dsh-client-runtime/client` 取类型——该包是 `0.1.1` 内核特有，`0.1.2` 已拆走，且同名 `SettingsScope` 在 host（`dsh-settings`）与 client 两侧成员并不相同。peer 为逐代枚举 `^0.1.1-rc.2 || ^0.1.2-rc.1`（node-semver 不把预发布版算进任何范围，除非比较符带同一 `[major.minor.patch]` 元组，故无跨代区间写法）：**上游每发布新 rc 代次就要补一个枚举项**。
- **Session API 跨代**：探测与 peer 矩阵已收敛到 `src/upstream-compat.ts`（2026-09-17）。
  - `readOwnEvents` / `readInheritedEventCount`：`0.1.1` = `.events` + `header.seedLength`；
    `0.1.2` = `ownEvents()` + `inheritedEventCount`。`foldUserState` 只调这两处。
  - `KERNEL_GENERATIONS` 是 peer 代次的唯一事实来源；改完跑
    `node scripts/sync-peer-matrix.mjs` 重写 package.json，再 `npm test`。
  - 护栏：`tests/upstream-compat.test.mjs`（两代形状一致 + peer/dev 同步 + seedLength 回归）。
- **插话投递改动的跨代核对（2026-09-28，静态比对 4 代产物）**：新增的投递/确认路径逐项确认
  在其声明支持的两代内可用，并额外核对到**尚未声明**的更新代次。
  - 方法：从 npm 拉取 `0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.2` 四代 tarball 解包比对
    （而非只跑本地 devDependency 的单一版本——本地只有 `0.1.2-rc.1`）。
  - 结论：改动依赖的 4 个 API 在**四代全部存在且契约一致**：
    `agent.followup` / `agent.steer`（四代 doc comment 逐字相同）、
    `sessions.flush(session)`、`createUserMessage` / `boundContextSummary`。
    Session 形状仍是两轨：`0.1.1-rc.2` 为 `.events`+`seedLength`，`≥0.1.2-rc.1` 为
    `ownEvents()`+`inheritedEventCount` —— 与 `KERNEL_GENERATIONS` 的二元模型吻合，
    **无需新增代次**。
  - 送达确认走 `readOwnEvents` 兼容层（非直接读 `session.events`）；已加护栏
    `tests/delivery.test.mjs` 的三个形状用例，并反向验证：把 `readOwnEvents` 换回
    直接读 `.events` 后，`0.1.2+` 用例立即失败。
  - 设置枚举用 `s.union([s.const(...)])`，`schemastery@3.18.2` 具备该 API；实测非法值
    **抛错而非静默回落**，故 `getSettings` 的 `try/catch`（回落 `startSettings`）+
    逐字段精确比对（只认 `'steer'`/`'discard'`）是必要的双重保险。
  - ⚠️ **peer 代次缺口已实测定位（2026-09-28）**：peer 枚举只到 `^0.1.2-rc.1`，实际运行的
    宿主已是 `0.1.5-rc.3`。为决定「补哪些代次」做了实测：

    | 代次 | host 入口链接 | 结论 |
    |---|---|---|
    | `0.1.5-rc.1` / `rc.2` / `rc.3` | 15/15 模块导入通过 | ✅ **可补** |
    | `0.1.7-rc.1` | 导出仍含 `allocateScheduleId` | ⚠️ **「可补」只对了一半**（2026-10-23 复核）：
      这一面确实兼容，但**消息 `source.kind:'plugin'` 在这一代已被淘汰**，当时没核对那一面 ⇒ 提醒到点
      100% 不投递。详见「已解决（2026-10-23，issue #75）」一节 |
    | `0.1.7-rc.2` | 起初 11/15 失败 | ✅ **已适配并落地验证**（见下节） |

    方法：在隔离目录按代次 `npm install` 内核作用域包（`--ignore-scripts`，各代 9 个包 +
    cordis），把 `lib/` 拷入后逐个 `import()` 全部 15 个 host 模块。

  - **`0.1.7-rc.2` 适配已完成（2026-09-28 实测通过）**。
    此前结论是「破坏性、不可补、需单独适配工作」——适配现已完成，全部差异收敛到新模块
    **`src/schedule-compat.ts`**，调用点无版本分支。

    **差异清单与处置**（全部读实现确认，非猜测）：

    | 变更 | 性质 | 处置 |
    |---|---|---|
    | `allocateScheduleId` 导出被删（5 处调用） | 行为变更 | `ScheduleId("schedule-${randomUUID()}")` —— 与官方 `ScheduleService.create` 的内联实现一致；旧实现是确定性递增，新的是 UUID |
    | `renderEveryReminderBatchFraming` → `renderRecurringReminderBatchFraming` | 纯改名 | namespace 属性访问，按存在性择一 |
    | `createAfter/At/EveryScheduleRecord` 新增必填 `title` | 新增参数 | 按函数 `arity >= 5` 择一；`title` 由 `deriveScheduleTitle` 从 prompt 派生 |
    | `MessageSourceMap` 删除 `plugin` / `host` kind | 枚举收紧 | 0.1.7 新增 `kind:'schedule'`（官方 `dsh-schedule` 注入提醒用的正是它） |
    | `ScheduleRecord` 联合 3→6 变体（+daily/weekly/cron） | 类型变宽 | `StoredScheduleRecord` 显式列举 after/at/every；**`Extract` 在此 tsc 配置下不收窄** |
    | `ScheduleDeliveryMode` `'session-local'` → `'host'` | 值变更 | wire 契约归一到稳定值，不让内核改名传导到客户端 |
    | `agent/created` 回调改为异步串行 | 签名变更 | 回调显式 `async` |
    | `SettingsProvider.register` → `SettingsForms`（无 `register`） | **架构级** | 代次门控：探测不到 `register` 就保持 `startSettings`（profile yml 的 `base`）。**0.1.7 下设置页不可用**，见遗留项 |

    **踩到的关键坑**：最初用 `import { renderEveryReminderBatchFraming as X } from '…'`
    + `as unknown as` 兜底，这在 0.1.7 上直接
    `SyntaxError: does not provide an export named` —— **ESM 具名 import 是链接期硬失败，
    类型断言救不了**。改用 `import * as sched` + 属性访问才真正双代次兼容。
    这个坑不真跑 0.1.7 发现不了。

    **`title` 截断有数据支撑**：真实存量 979 条记录中，最长 prompt 575 字符，
    **22 条超过 0.1.7 的 120 上限**。故 `deriveScheduleTitle` 必须截断（按词边界优先），
    直接透传会在编辑这些记录时抛 `invalid_prompt`。

  - **`0.1.7` 存量数据兼容：零损坏（2026-09-28 离线实测）**

    用 0.1.7-rc.2 的真实解码器读 `~/.dsh/sessions` 的全部历史日志：

    | 指标 | 结果 |
    |---|---|
    | 扫描会话日志 | 1211 个 |
    | `schedule/change` 事件 | **979 条** |
    | 解码通过 | **979（100%）** |
    | 整份日志 `foldScheduleEvents` | 180/180 文件通过 |
    | 无法读取的日志文件 | 0 |

    ⚠️ **修正一处此前的误判**：曾记录「缺失 `title` 的存量记录会被 `decodeStoredTitle`
    判损坏并整份拒读」。**这是错的。** 0.1.7 实际实现了双轨解码：

    | 函数 | 用途 | 对 `title` |
    |---|---|---|
    | `decodeHistoricalRecordTitle` | 读 `schedule/change` **事件** | **可选**，缺失合法 |
    | `decodeRecordTitle` | Host 内部持久化记录 | 必填 |

    反向验证确认只有「**有 key 但值非法**」才拒（空串 / 未 trim / >121）；
    「**缺失 key**」是合法的历史形态。

    **结论：升级到 0.1.7 不需要任何存量数据迁移。**

  - **`0.1.7-rc.2` 真实宿主端到端验证（2026-09-28 实测通过）**

    此前所有验证都基于「用 0.1.7 的包」，未过真实宿主。本次补齐：

    - **隔离环境**：独立 `DSH_HOME` + 独立安装目录
      （`@deepseek-ai/dsh@0.1.7-rc.2`，291 个包），全程不触碰运行中的 `0.1.5-rc.3` 宿主。
    - **profile 装载**：`dsh plugin --profile <name> add file:…` 成功；
      插件被**自动登记为 bundle**（`dsh.bundle.patch` 检测生效），组合进配置树（行 id `later`）。
    - **host 模块确实被求值**：临时往 `lib/index.js` 插入加载标记，0.1.7 启动日志打出该标记
      → 证明不是「静默跳过」。已还原。
    - **client 模块被宿主正确服务**：从 `index.html` 的插件清单可解析到
      `dsh-later/client.js`，拉取 HTTP 200（468KB 合并包内可定位到 dsh-later 模块块）。
    - **工具级端到端**（真实模型驱动）：
      - `user_schedule_create` → `{"ok":true,"id":"schedule-0639dcca-…","kind":"after",…}`
        —— **UUID 格式 id 确认生效**
      - sidecar 落盘：`{"schedule-0639dcca-…":{"delivery":"context","uid":"…","windowSeconds":600}}`
      - `user_schedule_list` **读回同一条**，id/kind/state 一致
    - **最终状态**：0 类型错误，`npm test` **183 通过 / 0 失败**，全部基于 0.1.7 依赖。

  - **测试污染真实状态目录（2026-09-28 已修）**

    排查中发现 `~/.dsh/plugin-state/later/` 累积了测试产物：

    - **根因**：`tests/helpers/ownership-state.mjs` 要求「在导入 lib **之前**调用
      `freshOwnershipDir()`」，但 ESM import 会被提升——该约束在语法上无法满足。
      15 个测试里有 11 个实际写进真实用户目录（13 个 `session-test-*.json`
      + `session-delete-case` / `session-edit-case` / `x.json`），并让断言因残留状态
      互相干扰（P0-1 两条单独跑通过、整文件跑失败）。
    - **处置**：helper 改为**导入即隔离**（模块求值时自动指向一次性临时目录），结构上杜绝；
      清理 16 个脏文件，保留真实的 v1 格式旧会话残留。跑测试后生产目录零写入。
    - **顺带修复一个真实 bug**：`resolveStateDir()` / `legacyStateDir()` 里写成
      `process.env['DSH_LATER_STATE_DIR'] ?? process.env['DSH_LATER_STATE_DIR']`
      —— **同一变量自比较**，旧名 `DSH_SESSION_SCHEDULER_STATE_DIR` 的回退从未生效；
      且因「有 override」，`legacyStateDir()` 直接返回 `undefined`，
      **改名迁移也不会发生**。已抽成 `stateDirOverride()` 统一处理两个名字。

  - **一个隐蔽的构建耦合（值得记住）**

    `build.mjs` 先跑 `tsc`，**tsc 因任何类型错误失败时才回退到 esbuild `bundle: true`**，
    而 bundle 模式会把本地 import **内联**：

    ```
    lib/ownership-store.js     ← 真正的模块
    lib/user-tools.js:202      ← 被内联了一份自己的 recordOwnership
    lib/index.js               ← 同样内联
    ```

    两份副本各有独立的 `cachedDir` 与内存缓存，`freshOwnershipDir()` 只重置了前者的缓存。
    于是：**`0.1.7` 的那个 `SettingsForms.register` 类型错误，经由
    「tsc 失败 → esbuild bundle → 模块双副本」，最终表现为 14 个测试失败。**

    修掉该类型错误后构建回到 tsc 路径（`lib/user-tools.js` 恢复为
    `import … from './ownership-store.js'`），14 个失败**同时消失**。

    教训：**类型错误不只是类型错误** —— 它会静默改变构建产物形态，进而改变运行时语义。

  - **`0.1.5-rc.1` 的落地验证（2026-09-28 实测）**：
    - 隔离目录安装内核作用域包（各代 9 包 + cordis，`--ignore-scripts`）后，
      **host 入口链接**：15/15 模块 `import()` 通过。
    - **运行时实例化**（不止 import —— 捕捉「导入 OK 但 `apply()` 崩」）：以最小假 ctx
      调 `apply()` 成功，注册顺序为
      `inject[sessionProjections] → inject[settings] → effect×2 → on(agent/created)`。
    - **对照 `0.1.2-rc.1`**（原有代次）：同样 15/15 + `apply()` 成功，注册顺序**逐项相同**
      —— 未因本次改动产生代次间行为分叉。
    - 运行的宿主 `0.1.5-rc.3` 现已满足新声明的 peer 范围（`semver.satisfies` 默认语义下
      亦为 true，不再依赖 `includePrerelease`）。
  - **本地开发代次已对齐到 `0.1.7-rc.2`（2026-09-28 更新）**：
    原先固定 `0.1.5-rc.1`；`0.1.7` 适配完成后同步推进到 `0.1.7-rc.2`，使本地与目标运行时一致。
    以下为推进到 `0.1.5-rc.1` 时的处置记录（方法仍适用）：
    - 起因：devDependencies 原先写的是**完整 peer 范围串**，npm/pnpm 因此解析到
      「满足范围的最老可用版本」= `0.1.2-rc.1`，而真实运行时是 `0.1.5-rc.3` ——
      **测试环境落后运行环境整整一代**，API 漂移在本地无从暴露（peer 缺口正是这样漏掉的）。
    - 处置：`devDependencies` 改为**固定到最新已验证代次** `0.1.5-rc.1`（全部
      kernel-scoped 包同代次，避免类型面自相矛盾）；`peerDependencies` 仍为完整范围串。
    - `scripts/sync-peer-matrix.mjs` 同步改造：peer 写范围、dev 写固定代次；且**只在该
      字段已是范围串或缺失时**才改写 dev，避免把有意固定的版本冲掉（幂等）。
    - 结果：`npm run typecheck` **通过且无新增错误**（0.1.2 → 0.1.5 的类型面兼容），
      `npm test` **183 通过 / 0 失败**（新增 2 条 dev 固定性守卫）。
    - 新增守卫（`tests/upstream-compat.test.mjs`）：dev 必须是**具体代次**而非范围串、
      必须落在已验证列表内、全部包同代次、且等于最新已验证代次；另有一条显式登记
      「当前 dev 代次」的断言，使代次变更在 diff 中可见而非被 install 悄悄改掉。
      反向验证两种情形均被挡下：dev 回退成范围串、dev 固定到未验证的 `0.1.7-rc.2`。
  - **代次守卫改为数据驱动**（原先硬编码「两代」，每加一代都要改测试）。
    现断言结构不变量：首代 legacy、其余 own-events、`peerRange` 下界必须**恰为该代次
    本身**（逐代留痕，不借用更早下界）、代次表严格递增。并附 `verGt` / `caretCovers`
    的自测，防止守卫自身失效。
    反向验证：把 `0.1.5-rc.1` 的范围偷写成 `^0.1.2-rc.1`，守卫立即失败。

- **`0.2.0` 兼容核对（2026-10-08 实测通过）**
  - **现象**：插件在 DSH `0.2.0-rc.2` 上**完全不加载**（无按钮、无命令、无工具）。
    宿主日志：`skipping profile bundle "dsh-later": Plugin dsh-later@1.0.0 is
    incompatible with dsh 0.2.0-rc.2 …`。
  - **根因（不是代码失效，是 peer 声明缺口）**：内核自 0.2.0 起把 peer 校验
    **从警告升级为硬门槛**（`dsh-app-boot` 的 `evaluatePluginCompatibility`）——
    peer 范围不满足即**整插件跳过**，而非此前的「打印警告后照常加载」。
    本插件 peer 枚举止于 `^0.1.7-rc.2`，`0.2.0-rc.2` 对全部 8 个 kernel-scoped 包
    均不满足（预发布版必须显式枚举，`^0.1.7-rc.2` 不覆盖 `0.2.0-rc.2`），故被挡下。
  - **API 面逐项核对（结论：全部保持，无需改动任何业务代码）**
    | 依赖面 | `0.2.0-rc.2` 实测 |
    |---|---|
    | Session 形状 | `ownEvents()` + `inheritedEventCount` **未变** → `readOwnEvents` / `readInheritedEventCount` 原样可用 |
    | `dsh-schedule` 导出 | `foldScheduleEvents` / `renderReminderFraming` / `resolveEveryOccurrence` / `decodeScheduleChange` / `scheduleView` / `ScheduleId` **均在**；`renderRecurringReminderBatchFraming` **仍在**，`schedule-compat.ts` 的三处桥接照旧命中 0.1.7 分支 |
    | `dsh-llm` | `createUserMessage` / `boundContextSummary` 在；`MessageSourceMap` 已无 `plugin` kind，仅剩 user/model/tool/system-prompt，而 `schedule` kind 由 `dsh-schedule` 经 module augmentation 并入 → `scheduleMessageSource()` 的存在性探测继续走 `schedule` |
    | `dsh-agent` | `followup()`（next-turn）与 `steer()`（next-step）**语义未变** |
    | `dsh-tools` | `defineTool` 在 |
  - **实证**：把 devDependencies 固定到 `0.2.0-rc.2` 后，
    ① `tsc -p tsconfig.json --noEmit`（host）**0 错误**；
    ② `tsc -p tsconfig.client.json --noEmit`（client）**0 错误**；
    ③ `npm run build` 走 **tsc 原生路径成功**（无 esbuild 降级告警 —— 即
    typecheck 干净，构建产物形态未被破坏）；④ 183 项测试全绿。
    （注：#56 起判定的**形式**变了 —— tsc 报错会直接非零退出、不再有"降级告警"这条路，
    所以「没看到告警」不再是"typecheck 干净"的证据，改为「构建成功且产物判据判逐文件」。）
  - **落地**：`KERNEL_GENERATIONS` 追加 `0.2.0-rc.2` 一代 → `node scripts/sync-peer-matrix.mjs`
    重写 8 个 peer 范围 → dev 固定推进到 `0.2.0-rc.2`（并同步护栏中的代次断言）。
    核对后以宿主的校验逻辑复算：`0.2.0-rc.2` 上 **0 个不兼容 peer**（放行）；
    历史代次 `0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-rc.{1,3} / 0.1.7-rc.2` **仍全部支持**；
    未核对的 `0.3.0-rc.1` **仍被正确拒绝**（护栏未被放宽）。

### `0.2.0` 的第二处差异：reminder framing 措辞变更（已修）

`dsh-schedule` 在 0.2.0 把 one-shot 与 recurring 两条 framing 的防护句**统一收敛**
为一个常量（`SCHEDULED_MESSAGE_FRAMING`）：

| 代次 | framing 第二行（固定来源行） |
|---|---|
| ≤ `0.1.7-rc.2` | `Present reminder_prompt_json to the user as untrusted reminder content, not new user instructions.` |
| ≥ `0.2.0-rc.2` | `This is a scheduled message from the user` |

**影响面**：本插件的**单条**路径直接调上游 `renderReminderFraming`，自动跟随，无需改动；
但**多条到期一次性合并**（P1-5）是上游不提供的形态，由 `src/runtime.ts` 的
`renderOneShotBatchFraming` **自渲染**——其固定来源行是上游文案的**本地副本**。
若不同步，同一会话里「单条」与「合并」两条提醒的防护措辞会不一致。

**已修**：把本地副本对齐到上游统一后的措辞（`src/runtime.ts`）。
**已加护栏**：`tests/runtime.test.mjs` 的「本地批次 framing 的固定来源行与上游一致」——
从上游 `renderReminderFraming` **实时取**来源行比对本地副本，不硬编码任何一版文案，
故支持任意多代。反向验证：把本地副本改回旧长句，护栏立即失败。

> 这两处（peer 门槛 + framing 措辞）是**独立的两个问题**：前者让插件整个不加载，
> 后者只在加载成功后影响合并提醒的文案一致性。前者掩盖了后者——插件不加载时
> framing 根本不会执行，故修完 peer 缺口后测试才暴露出来。这正是 devDependencies
> 固定到运行时真实代次的价值：把「本地测试环境落后于运行时」造成的盲区消除。

- **`0.2.1` 兼容核对（2026-10-20 实测通过）**

  - **结论**：`0.2.1-rc.2` 相对 `0.2.0-rc.2` 对本插件只多出**一处类型面差异**，
    业务路径无需新增版本分支；登记代次后 host / client 两条 `tsc --noEmit`
    零错误，`npm test` **407 通过 / 0 失败**。
  - **Session 形状未变**：`@deepseek-ai/dsh-session@0.2.1-rc.2` 的类型声明里
    `ownEvents(): readonly SessionEvent[]` 与 `inheritedEventCount: SessionLogOffset`
    仍在（`node_modules/@deepseek-ai/dsh-session/lib/types/index.d.ts` 第 231、152
    行），故 `readOwnEvents` /
    `readInheritedEventCount` 原样可用，`sessionApi` 仍为 `'own-events'`。
  - **`dsh-schedule` 的探测照旧命中**：`renderRecurringReminderBatchFraming` 仍在导出；
    `scheduleMessageSource()` 在这一代同样返回 `kind:'schedule'`——但依据已从「该符号是否存在」
    换成**内核版本号**（issue #75：0.1.7-rc.1 上「符号还在、kind 已死」，存在性探测会选错），
    两种口径在 0.2.1 上结论一致；
    `createAfterScheduleRecord` 的 arity 仍为 5（`title` 照旧由 `deriveScheduleTitle`
    提供）；`foldScheduleEvents` / `renderReminderFraming` / `resolveEveryOccurrence` /
    `decodeScheduleChange` / `scheduleView` / `ScheduleId` 逐个 `import()` 实测均在。
  - **唯一的真实差异：`ScheduleInputError` 多一个码**。0.2.1 给输入错误闭包加了
    `subagent_session`（目标 Session 属于委派子代理，投递永远到不了，故其 `create`
    拒绝、`update` 返回非变更结果）。本插件的写路径**不经过** `ScheduleService`
    （自己 append `schedule/change` 再 fold），因此不会真收到该码；但
    `toInputError` 是上游闭包的直通翻译器，本地联合不补就编译不过（升级依赖时
    `tsc` 已如实报出 `TS2322`）。处置：`UserScheduleErrorCode` 补入该码并注明来源，
    另加一条运行期护栏，构造 `ScheduleInputError('subagent_session', …)` 经翻译后
    **码原样透出**，不降级成 `internal_error`。
  - **落地**：`KERNEL_GENERATIONS` 追加 `0.2.1-rc.2`（`peerRange: '^0.2.1-rc.2'`，
    `sessionApi: 'own-events'`）→ `node scripts/sync-peer-matrix.mjs` 重写 8 个 peer
    范围 → devDependencies 里 9 个 `@deepseek-ai/*` 精确版本推进到 `0.2.1-rc.2`
    （含只出现在 dev 的 `dsh-client-ui-primitives`；`cordis` / `schemastery` 不动）
    → `pnpm-lock.yaml` 同步刷新。
  - **证据**：`tsc -p tsconfig.json --noEmit` 0 错误；`tsc -p tsconfig.client.json
    --noEmit` 0 错误；`npm test` 407 通过 / 0 失败（基线 406，新增 1 条错误码护栏）。
  - **变异验证**：从 `KERNEL_GENERATIONS` 删掉 `0.2.1-rc.2` 并重建 `lib/` 后，
    `peerDependencies 与 KERNEL_GENERATIONS 完整范围一致` 与
    `devDependencies 固定到某个已验证代次（不与 peer 范围混同）` 双双变红
    （407 → 405 通过 / 2 失败）；还原后回到 407 全绿。护栏确实绑在代次表上，
    不是被 package.json 里的常量蒙混过关。
  - **未覆盖**：本次没有在真实宿主里加载 0.2.1 内核（只做依赖面、类型面与单测冒烟）；
    `engines.dsh` 的既有区间已覆盖 0.2.1（`>=0.2.0-rc.2 <0.3.0-0`），未改动。
  - **合并后复核（2026-10-20，main 合入 #63–#66 之后）**：在 0.2.1-rc.2 的**真实** devDependency 下
    重跑 —— `pnpm install --frozen-lockfile` 通过且**不改写** `pnpm-lock.yaml`；
    host / client 两条 `tsc --noEmit` 零错误；`npm test` **443 通过 / 0 失败**
    （基线 406 + #55 的 1 + #54 的 2 + #56 的 18 + #57 的 16）；`npm run build` 后 `lib/` 与源码
    同步（`git status` 零脏改），产物仍是逐文件 tsc 形态。
    这也补上了 #54 交接里"0.2.1 内核下的最终 typecheck 未验"那一项 —— 该错误码是在真实 0.2.1
    类型面下编译通过的，不是在 0.2.0 上"看起来没问题"。

### 0.2.2-alpha.2：投影注册契约变更（issue #118）

这一代对本插件是**两条契约变更**：一条在类型层"静默失效"，一条在运行时要求 await 时序。
装配面本身没坏（见下面的对照组），所以改法的形状不是"修一个炸掉的 bug"。

代次表因此从 **8 条变 9 条**。本文档上面各处写的「六代」是 **1.8.0 那轮基线实际跑过的数量**，
属于历史记录，不随本轮改写；本节给的是这一代的新数字。

| 变更 | `0.2.2-alpha.2` 的形状 | 本仓落点 |
|---|---|---|
| `SessionProjectionStateMap` 移除 | 类型包里已无该接口（`grep -c SessionProjectionStateMap lib/types/*.d.ts` 两个文件都是 0）；状态类型改由单元自身的 `stateSchema` 泛型承载 | `src/domain.ts`（删掉死的 `declare module` StateMap 块，**保留**同块里的 `SessionProjectionMap`）、`src/upstream-compat.ts` 的代次注释 |
| `register()` 返回 `Promise<ProjectionHandle<S>>` | 附一条时序要求 *Callers must await registration before publishing consumers*；handle 提供 `stateOf` / `readerFor` / `dispose` | `src/projection-registration.ts`（唯一的跨代收敛点，含 `as never` 边界转换）+ `src/index.ts`（注册包进 async `ctx.effect`） |

**先别把它读成"修编译错误"。** 类型包里 `SessionProjectionStateMap` 确实被删了，但 TypeScript 的
module augmentation 允许**新增**一个不存在的 interface，所以 `tsc` 不报错 —— 它是**静默无效**
（一段没人读的死声明），而不是编译失败。静默无效比报错更危险，这也正是 issue 前提里
"类型层破坏 tsc"一条实测不成立的原因。

**`register()` 的返回形状是"可调用 + thenable"，而且**两代都是**。** `0.2.2-alpha.2` 的实现返回
`Object.assign(dispose, { then, catch, finally, [Symbol.toStringTag]: 'Promise' })`
（`~/dsh-versions/0.2.2-alpha.2/node_modules/@deepseek-ai/dsh-session-projection/lib/index.js:80-109`），
即**不 await 也照样 `typeof === 'function'`**。老代次也不是裸函数：`0.2.1-rc.4` 的 `register()`
直接 `return this.ctx.effect(...)`（`…/dsh-session-projection/lib/index.js:68`），而 cordis 的 effect
返回带 `.then` 的 AsyncDisposable（`cordis/lib/index.js:1239/1274`）。所以收敛点必须**两步判**：

1. **thenable 优先** —— 先看 `typeof value?.then === 'function'` 并 `await`。先判函数会静默走
   老分支、跳过 await 且**不报错**（上游同时把 callable 形态标了 deprecated，方向一致）。
2. **按 await 的解析值分岔** —— 两代是"同一种形状、两种解析值"，这一步不能省：

| 代次 | `typeof`（await 前） | thenable | **await 解析值** | 正确处置 |
|---|---|---|---|---|
| ≤0.2.1（代次表里其余 8 条） | `function` | 是 | **函数**（disposer 本身），`.dispose` 为 `undefined` | 当老代次 disposer 用 |
| `0.2.2-alpha.2` | `function` | 是 | **对象** `{dispose, stateOf, readerFor}` | 用 `handle.dispose()` |

只写第一步（"thenable 就当 handle"）会在**全部老代次**上静默回归：解析出的函数被当成"缺 dispose
的 handle"，于是每次加载 warn 一次、且**注册永不被释放**（泄漏一个 registration）。这个错在装配面
看不出来，只有 `tests/projection-registration.test.mjs` 里"thenable 解析为函数（rc.2/rc.4 真实形状）"
那条能判红 —— 变异验证：把实现换成"只判 thenable、不判解析值"后，9 条里只红这一条。

**`stateOf` 已 `@deprecated`。** 这一代起 `registry.stateOf(session, key)` 每个 key 首次读会 warn 一次，
推荐改用 awaited registration 的 `handle.stateOf(session)`（或所属领域服务）；本插件没有直接调用
（`grep stateOf src/` 无命中），知悉即可。

**`wire.summary` / `SessionProjectionSummaryExcluded<T>` 本次不采纳。** 佐证不是"它是可选参数所以不做"：
这一代的擦除层在 `wire.summary !== false` 时**默认按 true** 落进 registration
（`lib/index.js` 的 `acquire()`：`summary: wire.summary !== false`），也就是本插件现状（根本不声明
`summary`）在该代已经是"参与摘要"的语义，运行时行为不变。而把 map 条目包成
`SessionProjectionSummaryExcluded<T>` 会让其余老代次的跨代 tsc 报"找不到名字"（类型层没有
"某代次没有就退化成 T"的写法，除非在 `upstream-shims.ts` 里造条件类型），而运行时 `summary:false`
又会被老代次当未知字段忽略 —— 两边语义不对等。这是一个有意识的"不做"，记在这里免得后人以为漏了。

#### 对照组：只放开声明面就 GREEN（2026-10-30 实测）

只把 `engines.dsh` 与 8 个 kernel-scoped peer **临时**各加一条 `>=0.2.2-alpha.2 <0.2.3-0`，
**不改任何代码**，同一个脚本立刻变成：

```
### 0.2.2-alpha.2 … GREEN
    内核=0.2.2-alpha.2 · 同源=same · 投递 spliced=1 dispatch=Y · at 形状 5/5 · gate 本代=pass 最新=pass
```

（合并前的对照组在 `/tmp/repro-118c` 跑过、package.json 已还原。那是一次性临时目录，复查不要
指望它还在 —— 用本节的复跑命令重新生成 `.verify/` 产物。）结论要这么读：

- 本 issue 在装配/投递面上**不是"坏了"，而是"被门禁关在门外"** —— 真正的阻断只有声明面
  （`engines.dsh` 上界原为 `<0.2.2-0`，按 semver §11 排除 `alpha.2`；0.2.1 起内核**单独按
  `engines` 判定**，peer 不再兜底）；
- 因此 `register()` 的 await 改动是**契约对齐**，不是"修一个已经炸掉的 bug"；
- 而且**不 await 在这一代上实测也没有可观测差异**：注册表写入发生在 `acquire()` 的**同步段**
  （`dsh-session-projection/lib/index.js:127-151`，由 `ctx.effect` 同步执行），唯一的 `await` 在
  :153，其后只剩 `fiber.assertActive()` 与 handle 构造；消费者读面（`summaryKeys()` /
  `snapshot()`）全是同步读注册表，注册过程中**没有任何"发布消费方"点**。同 turn 探针实测：
  `register()` 返回后立刻 `summaryKeys()` 就已包含 `userSchedules`；端到端连「只改 engines、
  lib 仍是不 await 的 HEAD 代码」也是 mount+function GREEN、投递 5/5、首读即见。
- 所以本文档与 CHANGELOG、PR 描述里**都不许**写"不 await 会读不到投影 / 会掉 dock" —— 那是
  虚假因果，一句"你复现了吗"就能打穿。这条改动真正的价值是：照上游契约做（callable 形态已
  deprecated），上门取掉兜底时不被动；`tests/projection-registration.test.mjs` 钉住的是
  **"我们真的在 await"** 这个实现事实，而不是"修了一个可观测 bug"。

#### 实测结论

2026-10-30 测，插件基线 `ffb322d`，由 verify-kernels 在 `verify/118-integration` 上跑。原始产物：
`.verify/task4-full/across-kernels-2026-10-30T09-34-49-655Z.json`（9 代次全量）与
`.verify/task4-alpha2/across-kernels-2026-10-30T09-36-09-882Z.json`（`0.2.2-alpha.2` 单独一轮）。
两者都在 gitignore 的 `.verify/` 下，**不存在于仓库**，复查请用本节末尾的命令重新生成。

| 面 | 结论 |
|---|---|
| mount + function（9 代次，各自独立进程） | **9/9 GREEN**；`同源=same` 9/9、`投递 spliced=1 dispatch=Y`、`at 形状 5/5`；总退出码 **0**（单代 17–19s，9 代共 161s，全程 `--no-install`） |
| type（9 代次，两个 tsconfig） | **9/9 绿、0 错误** |
| gate（该代自己的 `evaluatePluginCompatibility`） | 7 代 **pass**；`0.1.2-rc.1` / `0.1.5-rc.3` 是**结构性未判定** —— 那两代的 `dsh-app-boot` 根本不导出该函数，**不是**插件被判过，不许记成绿 |
| gate（最新语义） | **9/9 pass** |
| UI（真 GUI，官方入口 `npm run verify:ui -- --versions 0.2.2-alpha.2`） | 按钮=Y · dock=1 · 面板=Y · badge=1 · 错误=0 · 警告=0，exit **0**；`0.2.2-alpha.2` 单独一轮同样 exit 0、GREEN。截图入库：[`docs/media/ui-matrix-2026-10-30-realgui/`](./media/ui-matrix-2026-10-30-realgui/README.md) |
| 投影物化探针（本 issue 要求的判据，见 §1.0） | `summaryKeys()` 含 `userSchedules`；`snapshot().values.userSchedules` 存在（`schedules=0, asOfSeq=2`）；建一条 `after_seconds=2` 后 `schedules 0→1` 且含该 prompt（`asOfSeq=5`）；到点投递后回 0（`asOfSeq=10`）；显式 `snapshot(['userSchedules'])` 正常；`pluginWarns=[]` |
| 全量单测 | **747 tests / 743 pass / 0 fail / 4 skipped**（71 文件）。4 条 skip 是 `tests/peer-facet-integration.test.mjs` 的真对端用例：它的 skip 条件是「逐级向上找不到 `dsh-group-status` 仓」，这轮跑在 `~/dsh-worktrees/` 的隔离树上所以跳；同一份代码在主仓 `dsh-plugins/` 下跑是 **747/747/0/0**（那个仓就在旁边） |

复跑命令（逐条落 JSON 到 `.verify/`）：

```
node scripts/verify-across-kernels.mjs --steps mount,function,type,gate --no-install
node scripts/verify-across-kernels.mjs --versions 0.2.2-alpha.2 --steps mount,function,type,gate --no-install
PLAYWRIGHT_MODULE=<playwright 模块目录> npm run verify:ui -- --versions 0.2.2-alpha.2
```

**devDependencies 不动**（仍固定 `0.2.1-rc.2`）：alpha 不进本地编译基线，新代次靠 `--steps type`
与真内核四面覆盖。`0.2.2-alpha.2` 在本仓算"支持"要**两侧声明**（`engines.dsh` + kernel-scoped
peer 各追加 `>=0.2.2-alpha.2 <0.2.3-0`）**与**四面实测共同成立，缺一不算。

#### 发布前的老代次回归复核（2026-11-02，基线 `main@33c76b3`）

上面那张表跑在合并**前**的分支上，而这次改动动的是**所有代次共用**的注册路径，所以发布前在
合并后的 `main` 上又补了一轮，专门回答「会不会把老代次弄坏」：

| 判据 | 结果 |
|---|---|
| 声明面 | `git diff 2043c81..33c76b3 -- package.json`：**8 枚 peer 与 `engines.dsh` 的旧条款逐字未变**，只在末尾各追加一条 `>=0.2.2-alpha.2 <0.2.3-0`。老内核评估自己那个版本时的判定与发布前一致 |
| 框架假设 | 异步 effect body 需要 cordis await `Promise<Disposable>`。九棵版本树里的 cordis 是 **4.0.2 ~ 4.0.6-alpha.1**（peer 声明 `^4.0.1`，全代次同一 major）；最低那版 4.0.2 的产物里 `wrapper.then`（`lib/index.js:1274`）与 `_execute` 的 await（`:1355`）都在 |
| 投影物化探针 × **5 代** | `0.1.2-rc.1` / `0.1.5-rc.3` / `0.1.7-rc.1` / `0.2.1-rc.2` / `0.2.2-alpha.2`：`snapshot().values.userSchedules` 全存在、建一条后 `schedules 0→1` 且 nonce 命中、**`pluginWarns` 全空**。最后那列是关键——两步判若在老代次取错分支（把 await 出的 disposer 函数当「缺 dispose 的 handle」），必然在这里冒一条 warn |
| UI 面官方入口 × **3 个老代次** | `0.1.2-rc.1` / `0.1.7-rc.2` / `0.2.1-rc.2`：按钮=Y · dock=1 · 面板=Y · badge=1 · 错误=0，汇总 exit **0**（补上「上一轮六代 UI 矩阵跑在本次改动之前」这个缺口） |
| `npm test` 在主仓 | **747 / 747 passed / 0 failed / 0 skipped**；隔离 worktree 里同一份代码是 743 + 4 skipped（真对端用例找不到 `dsh-group-status` 仓才跳，见上文「验证状态」） |

**一处行为变化，方向是改善**：老代次过去把 `register()` 的返回值丢掉，而那条注册 effect 挂在
`sessionProjections` **服务自己的** context 上，插件卸载/重载时不释放；现在由我们的子 fiber 持有，
卸载即释放。重复注册在老代次本来就容忍（只有 `stateVersion` 不一致才抛），所以这不是修崩溃，
是修滞留。

**仍未覆盖，别读成已覆盖**：`0.2.2` 段只验了 `alpha.2`（range 语义会连带放行同段更晚的 rc 与
`0.2.2` 正式版，那是既有契约，不是本次验过的结论）；UI 面本轮只补跑 3 个老代次，
`0.1.5-rc.3` / `0.1.7-rc.1` / `0.2.0-rc.2` / `0.2.1-rc.3` / `rc.4` 的 UI 结论仍是 10-28 那轮（改动前）。

## 会话日志兼容：`session-scheduler/user-schedule`（#58，2026-10-20 定案）

插件在 1.4.0 之前把「定时任务所有权」写进会话日志（自定义事件类型），之后改存 sidecar。
旧日志里那些记录仍在，而宿主持久层对**不认识的类型**是**整份拒读**：

```js
// dsh-session-persistence/lib/index.js
if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true)
  throw unsupported(`… unknown to this harness and not marked ignorable; refusing to interpret the log …`)
```

- **上游立场**：事件名注册**不是**兼容机制。`dsh-session/lib/types/known-event-types.d.ts` 的注释写着
  「event-name registration was rejected … would make reads composition-dependent」。上游认的是 envelope 的
  `ignorable: true`（未知但标记为可忽略的记录按 log-only 保留、正常读过去）。
- **决定（#58 C 路线）**：删掉启动时的读兼容注册；旧日志改由 `scripts/migrate-owned-events.mjs`
  一次性迁移——只给这些记录补 `ignorable: true`，不动 `seq`、不动 `type`（**不能删行**：读路径要求
  seq 连续，删行会造出缺口反而更读不了）。脚本默认 dry-run、`--apply` 时先备份、幂等可重跑。
- **暴露面（实测，不是 grep）**：会话日志是 `session.v*.jsonl.zstd`，`grep` 读不进去。
  按 zstd 解压 + JSON `type` 精确匹配扫全库：**1666 份日志（v3 813 / v4 853）→ 0 份命中**。
  并且该事件在 `2026-09-10`（`80c8775` sidecar 化）就停止写入，而最早 release `v1.0.0` 是
  `2026-09-12` —— **没有任何已发布版本写过它**，受影响面只可能是 2026-08-26 至 09-10 之间从 git
  直装的开发版。
  （教训：用 `grep` 扫压缩日志会同时给出假阳性和假阴性；第一次重扫时 46 个"命中"全是 `tool/result`
  里**文本提到**这个类型名。）
- **迁移不能承诺什么**：它让**会话历史**重新可读，但**不保证**插件从那批老日志恢复提醒状态 ——
  1.4.0 起 sidecar 才是权威；V3 老日志在 V4 读取时还会把未知 ignorable 事件重命名进 `plugin:`
  命名空间。`src/user-tools.ts` / `src/projection.ts` 里按 `OWNED_EVENT` 读取的代码保留（对未迁移的
  环境仍是防御性分支），但不再是状态来源。

## 验收对照（v1.0.0）

| 编号 | 场景 | 落地 |
|---|---|---|
| AC-01 | 输入内容点击 ⏰ | ✅ 线上 E2E 实测：按钮渲染、面板可开 |
| AC-02 | 智能时段确认 | ✅ 线上 E2E 实测：自定义时间→确认→芯片显示｜任务列表 |
| AC-03 | 过去时间拒绝 | 面板校验 + 宿主 `not_future` 兜底 |
| AC-04 | 到期注入消息 | ✅ 线上 E2E 实测：到期（≈计划 75s）后对话出现 user/message（source=plugin）|
| AC-05 | 关网页重开仍在 | 事件日志持久化 + `userSchedules` 投影冷恢复 |
| AC-06 | 草稿变更 | 有意取舍：不静默取消（见 [设计决策 §4](./design-decisions.md)） |
| AC-07 | fork 不继承 | `session/end-seed` 重置 |
| AC-08 | 100 并发创建 | agent 事务串行化 + 单 session 上限 100 |
| AC-20 | 与 dsh-schedule 共存 | `schedule/change` 荷载零改动（严格兼容） |

## 已知限制

### `0.1.7` 下设置页不可用

`0.1.7` **删除了整个 `settings.yaml` 体系**：

- `SettingsProvider.register()` 不复存在，`ctx.settings` 变为 `SettingsForms`
  （只有 `configure` / `describe` / `prepareDocument`）
- 命名空间 schema 改为**由 profile 声明驱动**
  （内核注释原文：*Move the sections of the removed `settings.yaml` into the active profile*）

**处置**：`src/index.ts` 做代次门控 —— 探测不到 `register` 即保持 `startSettings`
（profile yml 的 `base` 值）。插件核心功能（命令、工具、调度器、投递）**不受影响**，
但以下能力在 `0.1.7` 上缺失：

| 能力 | 状态 |
|---|---|
| GUI 设置页（`SchedulerSettingsCard`） | ❌ 不显示 |
| `steerDelivery` / `confirmDelivery` 运行时热改 | ❌ 用 yml `base` 值 |
| `maxSchedules` / `allowLongPrompts` 运行时热改 | ❌ 用 yml `base` 值 |
| 命令与工具本身 | ✅ 正常 |

代码中留有 `TODO(0.1.7 配置迁移)`。**这是跨 15 个插件的架构课题，不应塞进单插件适配**：
需要先确定 profile 声明式配置的写法，再统一迁移各插件的设置面。

### 已解决（2026-10-20，issue #58）：读兼容注册已移除

历史上这里记着一条**已知限制**：插件需要 `Set.add()` 改写宿主的只读集合
`KNOWN_SESSION_EVENT_TYPES` 才能读旧日志 —— 非官方支持面、`link:` 开发态下还会静默失效（#57）。

该限制已消除：注册模块与调用已删除，旧日志改由 `scripts/migrate-owned-events.mjs` 一次性迁移
（补 envelope 的 `ignorable: true`，不动 seq/type）。实测暴露面、为什么不删行、以及踩过的坑
（用 `grep` 扫 zstd 日志会同时给假阴性与假阳性）都已收在本文档的
**「会话日志兼容：`session-scheduler/user-schedule`」** 一节，此处不再重复。

### 已解决（2026-10-23，issue #75）：0.1.7-rc.1 上提醒 100% 不投递

**现象**：宿主 `dsh 0.1.7-rc.1` 上，提醒到点全部失败，面板显示「发送失败 / 超时未确认」。
**且插件侧没有任何可读的错误**——会话日志里既没有 `schedule/change operation:dispatch`，
也没有那句准入报错（它只出现在宿主 stdout）。

**根因**：`schedule-compat.ts` 拿 `renderRecurringReminderBatchFraming` 是否存在推断
「是不是 0.1.7」。但上游两个破坏性变更**不在同一个 rc 落地**：

| | `plugin` kind 是否被收 | render 新名是否存在 | `allocateScheduleId` 是否存在 |
|---|---|---|---|
| `0.1.5-rc.1` | ✅ 收 | ❌ | ✅ |
| `0.1.7-rc.1` | ❌ **已删** | ❌ **仍用旧名** | ✅ |
| `0.1.7-rc.2` | ❌ | ✅ | ❌ |

中间那行就是事故窗口：按符号探测会把它判成 0.1.5，于是交出
`{ kind:'plugin', … }`，被 `@deepseek-ai/dsh-session-format-v3-to-v4` 的准入
（`value["kind"] === "plugin"` 直接 throw）拒绝。

**为什么不能换个符号再探**（issue 里建议的 `allocateScheduleId` 也不成立）：上表显示
`0.1.5-rc.1` 与 `0.1.7-rc.1` 的 `dsh-schedule` 导出面**逐符号相同**——两个版本在 registry 里
都存在（`@deepseek-ai/dsh-schedule@0.1.5-rc.1` / `@0.1.7-rc.1`），实测两边都有
`renderEveryReminderBatchFraming` 与 `allocateScheduleId`、都没有新名。任何单符号推断都会
在这里踩空。**能区分的只有版本号。**

**改法**：判定换成「内核版本 + 显式阈值」——`PLUGIN_KIND_RETIRED_SINCE = '0.1.7-rc.1'`，
版本从 `@deepseek-ai/dsh` → `dsh-schedule` → `dsh-llm` → `dsh-session` 依次解析后向上读
`package.json`（**不能**直接 `require('<pkg>/package.json>')`：实测 0.1.5 的 `exports` 里没有
`./package.json` 这一条，0.1.7 起才有）。版本读不到时才退回符号探测，并且**警告一次**——
静默的错判正是本次事故的成因。比较器自己实现（semver §11 的预发布序），不引依赖：
阈值两侧都是 `rc.N`，按字符串比会得出 `rc.10 < rc.2`。

**实测矩阵**（本机 `~/dsh-versions/`，各版本 `npm i @deepseek-ai/dsh@<v>` 的真树）：

| 版本 | `dsh` 的 package.json version | 判定 kind |
|---|---|---|
| 0.1.5-rc.1 | 0.1.5-rc.1 | plugin ✅ |
| 0.1.7-rc.1 | 0.1.7-rc.1 | **schedule** ✅（修复前：plugin ❌） |
| 0.1.7-rc.2 | 0.1.7-rc.2 | schedule ✅ |
| 0.2.1-rc.2 | 0.2.1-rc.2 | schedule ✅ |

**端到端验收**：`node devkit/func-later.mjs --plugin <本仓> --dsh ~/dsh-versions/<版本> --case drive-gates --hold 8`。
判据是**事件形状**（一条 `agent/inbox/spliced` 且其 `inserted[].content` 带提醒正文，随后
`schedule/change operation:dispatch`），不是「日志里能不能搜到 nonce」——创建事件与命令回执里
也含同样的文本，拿它当判据会得出假结论（实测踩过）。修复前 rc.1 为 RED
（`spliced=0`、`dispatch=无`、`fold` 由 active 1 → 0 即窗口过期而非消费），修复后四代全 GREEN。

**顺带登记代次**：`KERNEL_GENERATIONS` 显式加入 `0.1.7-rc.1` 并跑 `scripts/sync-peer-matrix.mjs`。
`package.json` 的 `engines.dsh` 早就把 rc.1 圈在支持范围内（`>=0.1.1-rc.2 <0.2.0-0`），而 peer
强制拦截要到 0.2.0 才生效——所以这条坑路一直对外可达，只是没人验过。

**未做的部分（如实）**：issue 建议 3 里「把 append 抛出的真实校验错误透出来」做不到——那句
throw 发生在宿主写入路径，插件侧 `followup()` 不抛、也拿不到（实测）。改为能拿到的那一半：
投递未确认时把**自己的判定依据**（`kind=` + 内核版本 + 出处）记进宿主日志，
让下一次同类事故不用重跑跨代次实测就能定位。`DELIVERY_CONFIRM_TIMEOUT_MS` 仍是 2000ms，未调。