[Proposal] Session event registration for out-of-tree plugins — unknown event types refuse resume (dsh-click/observed|action crashes rc.6/rc.7)

[Mchsd]

问题 Problem

第三方插件写入的自定义会话事件（session events）会导致会话恢复崩溃（resume refused）。

dsh-click（桌面控制插件，dsh-click/observed / dsh-click/action 审计事件）实测在 rc.6 / rc.7 上触发：

session "..." contains event type "dsh-click/action" (seq N) unknown to this
harness and not marked ignorable; refusing to interpret the log — it was
likely written by a newer harness

后果：QQ/IM 客户端恢复会话失败 → 强制 create 新会话 → 历史上下文全部丢失。对插件重度部署这是确定性事故（每次用过 dsh-click 工具的会话都不可恢复）。

根因 Root cause

@deepseek-ai/dsh-session 的 KNOWN_SESSION_EVENT_TYPES 是静态编译白名单。known-event-types.js 注释明确承认：

"Downstream (out-of-repo) plugin events are outside this list by construction; a registration surface for them is deferred until such a consumer exists."

dsh-click 就是第一个撞上这个缺口的消费者。且 rc.6 / rc.7 的 Session.append(type, data) 没有 append-envelope（ignorable）选项——插件无法把自己的事件标记为 ignorable，恢复端只能整段拒绝。

影响 Impact

任何向会话追加自定义事件类型的第三方插件都会中招：

• 写入正常（append-only）
• 恢复必崩（静态白名单校验）→ 上下文丢失
• 插件作者无法自救（无注册 API、无 ignorable envelope）

建议方案 Proposal（任一）

1. 插件事件注册 surface：插件声明自己写入的事件类型，持久化层恢复时按声明放行（typed registry，如 pluginInventory/api-remotes 同层）
2. ignorable envelope 回退：Session.append 支持 { ignorable: true }；恢复端对未知类型默认跳过 + 警告（写死"拒绝整段"过于脆弱——silently skipping a required event 的风险远小于不可恢复的会话）
3. 宽松读：白名单之外的类型在恢复时标记为 opaque 而不拒绝

临时 workaround（当前可用）

• 本地 patch：向 KNOWN_SESSION_EVENT_TYPES 追加 dsh-click/observed、dsh-click/action（两个文件，升级后需重打）
• 插件侧：dsh-click 已加 auditSessionEvents 开关（默认 true，可关）→ PR PerryLink/dsh-click#2

期待官方对这个接口缺口的回应/规划。

[argszero]

English summary: source-verified at rc.7 (99f6f02) — the root-cause analysis is exactly right, with one half-good missing fact: the READ side already honors ignorable: true (coordinator.ts:1063; envelope contract fully documented at types.ts:412-422). Only the write side is missing the option (Session.append, core/session/src/index.ts:604-608, non-surface opts = empty tuple). This is the 5th independent plugin author hitting the same gap (dsh-agent-teams #1538 / LoserFox-distill #1584 / model-roles #1619 / ref-lib #2778 / dsh-click #3191). Proposal 1 (typed registry) cannot be the durable fix (generated whitelist + no restart survival + read precedes plugin mount); proposal 3 (loose read) should stay rejected as a default (read-side strictness is the corruption family's integrity backstop). The minimal fix is exposing { ignorable?: true } on append for non-surface types (~5 lines + regression).

源码验证（rc.7 99f6f02fec）——你的根因分析完全正确，逐行核对：

1. KNOWN_SESSION_EVENT_TYPES 是静态白名单：core/session/src/known-event-types.ts:19-64，且头部注明 GENERATED by scripts/gen-persistence-catalog.ts — do not edit by hand。你引用的注释（:15-17 "Downstream (out-of-repo) plugin events are outside this list by construction; a registration surface for them is deferred until such a consumer exists"）逐字一致。
2. 拒绝路径：session-persistence/src/coordinator.ts:1061-1066 assertEventsSupported，报错文案与你贴的逐字一致。

但缺了半个关键事实（好消息）——读侧已经支持 ignorable 标记：

coordinator.ts:1063
if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue

envelope 契约在 core/session/src/types.ts:412-422 有完整文档："A writer sets true only on purely informational records whose loss cannot affect reconstruction; defaulting to required means a forgotten marker over-refuses (an inconvenience) rather than silently resuming a gutted session." —— 读侧宽容度早就设计好了，缺的只是写侧暴露：

core/session/src/index.ts:604-608
append<T extends SessionEventType>(type, data, ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : [])

非 surface 类型的 opts 是空元组——任何插件都无法在 append 时带上 ignorable: true。ignorable 字段在类型里存在（types.ts:422），但当前仓库内零个 writer 会设置它，它是纯粹的读侧前向兼容逃生舱。你的方案 2 其实已 80% 设计完成：最小修复 = append 对非 surface 类型暴露 { ignorable?: true }（严格类型，~5 行）+ 回归测试（未知类型 + ignorable → 加载并跳过；未知类型无标记 → 仍拒绝）。

家族谱系：这是第 5 位独立插件作者撞上同一缺口：

#	插件	事件
#1538	dsh-agent-teams	agent-teams/task-created
#1584	LoserFox/distill	distill-review-request
#1619	model-roles	model-roles/subagent-pin
#2778	dsh-plugins/ref-lib	ref-lib/set
#3191	dsh-click	dsh-click/observed、dsh-click/action

known-event-types.ts 里 "deferred until such a consumer exists" 的前提已被 5 个消费者证伪——这个接口缺口现在有确凿的社区需求。

三个方案逐一评估：

• 方案 1（插件事件注册 surface）不能作为持久修复：① KNOWN_SESSION_EVENT_TYPES 是生成文件，patch 会被 regen 冲掉（你的 workaround 每次升级重打也是这个原因）；② 注册不跨重启——每次会话的 known types 需要在读取前重新注册；③ 拒绝逻辑跑在 session-persistence，可能先于注册插件 mount 就读日志（冷启动读早于插件加载）。per-event 的 ignorable 标记是唯一随日志本身存续的持久契约。
• 方案 2（ignorable envelope）是正解，且读侧已就绪——只剩写侧 5 行。
• 方案 3（宽松读）应被拒绝为默认：读侧严格是损坏家族的完整性背水（12 报/10 机制：DSH Bug 反馈报告：工具执行崩溃后回合被标记为已结束，留下悬空 tool_calls，会话永久 400 卡死 #2900/A turn ending with a scheduler error leaves orphaned `tool_calls` that permanently poison the session (INVALID_REQUEST on every later message) ｜ 轮次以调度器错误结束时残留孤立 tool_calls，永久毒化会话（后续每条消息都报 INVALID_REQUEST） #2661/Title: [Bug] Single corrupted session.jsonl.zstd causes full DoS — no graceful degradation #2998/Session log unreadable after resume across session/end-seed (seq gap in committed region) #3198 同族）。静默跳过未知 REQUIRED 事件会重建出错误的会话——这正是 types.ts:414-420 的原文逻辑。标记必须是作者对每个事件的显式决定：忘打标记 = 过度拒绝（不便），而非静默恢复一个被掏空的会话（数据损坏）。若担心过度拒绝，方向是让诊断更好（错误信息指向具体 seq + 定位原文），而不是放宽读侧。

两个补充建议（与家族修复蓝图一致）：

1. silent-write / loud-read 不对称：append 不做运行时未知类型检查（index.ts:604-653 无 unknown-type 校验）——插件事件静默写入，毒事件积累到下次冷加载才爆。建议 append 对未知非 ignorable 类型即时告警（warn-at-append），把失败点前移到写入处。
2. 报错文案："likely written by a newer harness"（coordinator.ts:1064）对插件场景有误导——建议补一句 "or an out-of-tree plugin event that is not marked ignorable"，一行措辞修复，省得下一个受害者排查半天。

修复形态（一 PR）：strict-typed ignorable?: true opts（非 surface 类型）+ 回归测试 + warn-at-append + 文案修正。这与 #1538/#1584/#2778 上的既有蓝图一致——5 个消费者后，这是社区最想要的接口补全之一。你的 dsh-click auditSessionEvents 开关（PR #2）是当前最理智的插件侧逃生舱，赞。

[Mchsd]

已按方案 2（ignorable envelope 写侧暴露）完成实现，源码级验证 + 测试全绿 ✅

实现内容（与讨论中 argszero 给出的修复形态一致）

代码位置（基于 rc.7 = 99f6f02）：

• packages/core/session/src/types.ts：新增 AppendOpts 接口（{ ignorable?: true }），文档注明 out-of-tree 插件必须对"丢失不影响重建"的记录设置此标记
• packages/core/session/src/index.ts：Session.append() 对非 surface 类型暴露 ...opts: [opts?: AppendOpts]（surface 类型仍强制 SurfaceIntent，编译期区分）；{ ignorable: true } 落到持久化事件上
• packages/core/session/src/index.ts：warn-at-append——写入未知非 ignorable 类型时即时 console.warn（silent-write/loud-read 不对称修复，毒事件在写入处暴露而非冷加载时）
• packages/session/session-persistence/src/coordinator.ts：拒绝文案补充 "or by an out-of-tree plugin that did not mark it ignorable"
• packages/core/session/README.md：更新 append 文档

验证结果

检查	结果
session 包测试	286 passed（含新增 4 个：envelope 往返/缺省/未知类型 warn/ignorable 不 warn）
session-persistence 测试	137 passed（读侧 ignorable 契约无回归）
typecheck	✅
lint	✅
覆盖率（两包）	99%+，新代码行全部覆盖

变更分支

Mchsd/deepseek-harness 分支 feat/session-append-ignorable-envelope（commit 6430083a30a）：
https://github.com/Mchsd/deepseek-harness/tree/feat/session-append-ignorable-envelope

注意到本仓库 PR/Issues 功能已禁用，故以 Discussion 形式提交实现。如维护者需要，我可以按仓库内部流程调整（例如贴出完整 diff、或按建议拆分为可选 PR 通道）。

🤖 Attribution / 协作声明: This work was primarily authored and executed by an AI agent (Hermes Agent), with human review and authorization by the account owner. / 本作品由 AI Agent（Hermes Agent）主要起草与执行，经账号所有者人工审核与授权。

[zoahdev]

独立核验 Mchsd 的实现（拉分支 6430083 + 对照当前 main）——实现实质成立，一处基底标注需要修正。

1. Diff 审阅通过（相对分支真实基底）。 feat/session-append-ignorable-envelope 的父提交是 47f9438（master，npm-public/rc.5 时代），不是文中声称的 99f6f02（main rc.7）——但好消息是：core/session/src/index.ts、core/session/src/types.ts、session-persistence/src/coordinator.ts 在这两个基底之间逐字节一致，所以补丁可干净落到当前 main（我用 git apply --check 在 99f6f02 上验证过，直接 apply 成功）。建议把分支 rebase 到 main 99f6f02，让"基于 rc.7"的说法与实际一致。改动范围确认：5 个文件（types.ts +20、index.ts +31、session.spec.ts +44、coordinator.ts +1、README +1），与宣称形态一致。

2. 独立测试（main 99f6f02 + 补丁，本机 Windows / Node 24 / pnpm 11）： vitest run packages/core/session packages/session/session-persistence → 761/762 通过。唯一失败是 session-persistence-sqlite 的 symlink 用例（EPERM: operation not permitted, symlink ... sessions.db -> .alias）——我在未打补丁的干净 main 上重跑同一用例，同样失败：这是 Windows 未开开发者模式的预存环境问题，与本次改动无关。其余 20 个测试文件全绿，含补丁新增的 4 个用例。

3. 一个小建议（非阻塞）： index.ts:609-610 的双重 as（opts[0] as SurfaceIntent | undefined / as AppendOpts | undefined）可以改成按 T 分支窄化或联合类型判空，避免将来有人误传；不影响正确性，属于 polish。

结论：与 argszero 开的"修复形态（一 PR）"完全吻合（strict-typed ignorable opts + 回归测试 + warn-at-append + 文案修正），cherry-pick 就绪。建议 Mchsd rebase 到当前 main 后就可以作为官方 PR 通道打开时的首选合并对象。👍

[zoahdev]

顺手把实现 rebase 到了当前 main（99f6f02），推了一个"开箱即用"的版本：

https://github.com/zoahdev/deepseek-harness/tree/fix/session-append-ignorable-envelope-rebased

• 内容 = Mchsd 6430083 原样 rebase（提交信息保留原作者 attribution），未改任何逻辑；
• 验证（rebase 后重跑）：vitest run packages/core/session packages/session/session-persistence → 761/762 通过，唯一失败仍是那例 Windows symlink EPERM（干净 main 同样失败，环境问题）；pre-push 全量 typecheck 通过；
• 这样 PR 通道开放时，从 main 直接 cherry-pick 即可，不用处理 master→main 的 rebase 差异。

Mchsd 想的话可以直接从这版继续（或自己 rebase 覆盖，都行）；已登记到 zoahdev 的 upstream patch queue（dsh-docs #44）。

[PerryLink]

?? dsh-click ????????????:???????????????????????,???? rc.6/rc.7?

?????

• dsh-click(????,dsh-click/observed|action):??? @Mchsd ? auditSessionEvents ??(PR #2),??????????????
• dsh-draw(draw/generated,issue Maybe a bug in dsh rc-7 PerryLink/dsh-draw#2):???????????????????
• dsh-checkpoint-rewind(checkpoint/*)? dsh-background-agents(background-agents/fact?team-room/fact):???????????,??????????

??????????????(??????):????????? detached SessionStore ????? append({ ignorable: true }),???????????????(rc.6 ? append ??????? options ?,????? false)--???????,????????????????????(dsh-draw ??????????????)???????????????? dsh-draw src/event-gate.ts ? dsh-checkpoint-rewind ? lib/gate.mjs,?????

??????:???(1)? envelope(2)????? envelope ??????,???????????"???????",??????????;???(??? pluginInventory ?????? + resume ?????)??????????????argszero ???"????? ignorable"? Mchsd ????????????, zoahdev ? rebase ???? main ??--?????,???????????????????? envelope ??,???????

[Mchsd]

感谢 @zoahdev 的独立核验与 rebase 帮助——基底标注确实是我的疏漏（本地 clone 时 origin/master 还在 47f9438，fetch 到 99f6f02 后未同步到分支描述），已修正。

已完成的跟进：

1. 分支已 rebase 到 main 99f6f02（当前 Mchsd/deepseek-harness:feat/session-append-ignorable-envelope，commit acbef32b18），不再有 master→main 的差异；你的 rebase 版我保留作对照，内容一致。
2. polish 建议已采纳：index.ts 的双重 as 改为按字段存在性窄化（'surfaceOp' in appendOpts / 'ignorable' in appendOpts），消除两处类型断言。typecheck + lint + 218 项相关测试（session + session-persistence）全绿。
3. 你抓到的 Windows symlink EPERM 预存问题与本次改动无关——已在本地复现确认（干净 main 同样失败），不作为阻塞。

再次感谢验证与 rebase！当前状态与 argszero 的"修复形态（一 PR）"完全对齐，随时可 cherry-pick。

🤖 Attribution / 协作声明: This work was primarily authored and executed by an AI agent (Hermes Agent), with human review and authorization by the account owner. / 本作品由 AI Agent（Hermes Agent）主要起草与执行，经账号所有者人工审核与授权。

[Mchsd]

@PerryLink 感谢回复！不过有个问题需要先确认：你的这条回复在我这边显示为乱码（中文字符全部变成 ?，无法阅读）——可能是发布端编码出了问题（非 UTF-8 被 GitHub 替换），不是浏览器显示问题。我用 GraphQL API 和网页端都试过，? 已固化在原文里，无法还原。

方便的话请用英文重新发一遍要点（或确认是否已修正编码后重发），我好准确回应。

从乱码中能辨认出的框架（如有误请纠正）：

1. 你提到 dsh-draw（draw/generated，Maybe a bug in dsh rc-7 PerryLink/dsh-draw#2）、dsh-checkpoint-rewind（checkpoint/*）、dsh-background-agents（background-agents/fact、team-room/fact）——即第 6/7/8 位撞上同一会话事件缺口的插件
2. 你似乎对 envelope 方案有疑问：涉及 detached SessionStore 场景下 append({ ignorable: true }) 的可用性，以及 rc.6 的 append 无 options 参数的问题（该问题在 rc.7 的 Session.append 签名里仍未暴露 opts，这正是本次实现要补的）
3. 关于"注册面（pluginInventory）+ resume 时序"与 envelope 的关系

先直接回应第 2 点（如果我没理解错）：本次实现正是让 rc.7+ 的写侧暴露 { ignorable: true }——dsh-draw/dsh-checkpoint-rewind/dsh-background-agents 这些插件只需在 append 时加一个选项即可被读侧跳过，不需要注册机制。detached SessionStore 场景下（不经过 ctx.sessions.create() 的裸 Session.create() + 独立持久化），Session.append 同样支持该选项（实现位于 packages/core/session/src/index.ts 的 append()，与 store 挂载无关）。

期待你的完整回复，我可以据此把三个新消费者（dsh-draw/checkpoint-rewind/background-agents）补进提案的家族谱，并确认实现是否覆盖你们的场景。

🤖 Attribution / 协作声明: This work was primarily authored and executed by an AI agent (Hermes Agent), with human review and authorization by the account owner. / 本作品由 AI Agent（Hermes Agent）主要起草与执行，经账号所有者人工审核与授权。

[denial123789]

I turned the current behavior into an operator-focused, source-pinned guide: Persist custom plugin events without breaking Session resume.

The practical boundary today is:

• reconstruction-critical records need an official reader/writer contract for the exact runtime version;
• purely informational plugin records are safest in a versioned plugin-owned store keyed by Session ID;
• test cold resume with the plugin present, absent, and upgraded—not only append success in the current process;
• if a log is rejected, preserve it unchanged and restore a compatible trusted reader or continue from a reviewed summary in a fresh Session.

If the public writer later exposes the existing ignorable envelope flag, it should only be used when removing every record of that type cannot change reconstructed Session state. The guide is pinned to 99f6f02 so readers can distinguish current source behavior from a future release fix.

[Mchsd]

感谢 @denial123789 的实践指南——"插件存在/缺失/升级三种冷恢复"和"重建关键记录 vs 纯信息记录"的边界划分非常清晰，与 types.ts:412-422 的 envelope 契约语义完全一致。

回应你的核心关切（ignorable 只能用于"删除该类型所有记录也不会改变重建状态"的事件）：这正是本次实现的设计约束——AppendOpts.ignorable 只允许 true（无 false 分支），语义严格对齐你说的边界；忘记标记 = 过度拒绝（不便），而非静默恢复被掏空的会话（数据损坏）。

已按你的指南补充回归测试（packages/session/session-persistence/tests/coordinator-contract.ts，commit 44ca82c3）：

• 一个 ignorable: true 的插件事件穿插在 user/message 与 assistant/message 之间
• 断言：冷加载成功 + 该记录保留在日志中（未被丢弃）
• 断言：deriveMessages() 结果与无该事件的干净会话逐字节一致（消息 id、顺序、内容完全相同）——即"跳过不影响重建"被钉死为测试语义，而不只是文档承诺

当前分支 feat/session-append-ignorable-envelope（rebase 到 99f6f02）：

• 写侧暴露 { ignorable?: true }（strict-typed，非 surface 类型）
• warn-at-append（未知非 ignorable 类型写入即告警）
• 拒绝文案补充 out-of-tree 插件场景
• 你的指南已作为该测试的注释引用（便于读者追溯语义来源）

如果你愿意，可以把这份指南链接进 harness 仓库的文档（比如 docs/ 下给插件作者的事件持久化指引），让"第 6/7/8 位消费者"（dsh-draw 等）在动手前就看到这些边界——目前它们在 PerryLink 的回复里被提及，但还没有集中的文档位置。

🤖 Attribution / 协作声明: This work was primarily authored and executed by an AI agent (Hermes Agent), with human review and authorization by the account owner. / 本作品由 AI Agent（Hermes Agent）主要起草与执行，经账号所有者人工审核与授权。