Compat Layer for DeepSeek Harness

DSH 插件兼容层：版本差异归一化接缝。它只做两件事，不含任何业务功能：

会话事件词表注册 —— 取代 DSH 在 0.2.0-rc.2 中移除的 registerSessionEventType()。插件在这里声明自有事件类型，而不是直接改 Harness 内部；每次注册必须携带明确的 omission 分类（事件缺失是否影响会话重建）。
事件名别名归一化 —— 同一逻辑事件的历史拼写（如格式迁移产生的 plugin:<type> 前缀）归一到规范名，插件的 fold 只需认规范名。

适配版本：DSH 0.2.0-rc.2 起（不兼容更早格式链）。

其他插件如何使用

// 宿主半侧
import { Service } from '@deepseek-ai/cordis'

export const inject = ['compat', /* 其余依赖 */]

export function apply(ctx, config) {
  ctx.effect(
    () => ctx.compat.registerSessionEventType('your-plugin/your-event', {
      omission: 'safe',            // 'safe'：信息性记录，缺失不影响重建
                                   // 'required'：缺失可能影响重建
      data: { enabled: 'boolean' } // 可选：载荷形状说明（仅文档用）
    }),
    'your-plugin.sessionEventType',
  )
}

fold 时用 ctx.compat.normalizeEventType(event.type) 归一化历史拼写。
ctx.compat.describeSessionEvents() 返回当前全部声明（诊断/外部插件查询用）。
服务名是 compat（inject: ['compat']）。兼容层未安装时，声明了该依赖的插件会得到明确的启动失败，而不是静默错乱。

诊断界面（1.1.0 新增）

诊断页（只读）：插件页 → 本插件行（plugins.row.config）展示 ①已注册事件类型与其 omission 分类 ②事件别名表 ③能力注册表（name/version/methods/owner）④本 build 词表是否可写。数据来自宿主写入的 volatile 字段 snapshotJson（ctx.compat.describeDiagnostics() 的序列化形式），页面不能修改任何东西。
可发现入口：settings.general.item 摘要行（id compat-layer），打开「设置 → 通用」即可见：兼容层：事件类型 N · 别名 M · 能力 K。
宿主在启动、以及每次事件类型/别名/能力变更后（microtask 合并）重新发布快照。

维护工具（离线，非运行期）

tools/normalize-session-log.mjs：把已存 v4 日志中指定插件类型的事件补上 ignorable: true，让日志在未装插件的裸 Harness 上也能读。默认 dry-run， --write 才落盘，写前自动备份，任何解析失败都会整体拒绝。

node tools\normalize-session-log.mjs <session.v4.jsonl.zstd> --types subagent-pro/toggle           # 预览
node tools\normalize-session-log.mjs <session.v4.jsonl.zstd> --types subagent-pro/toggle --write   # 应用

明确不做的事

不 patch Harness 内部（Session.prototype / sessionFormatCatalog 均不动；实测证明这类补丁要么被冻结挡下、要么影响不到落盘路径）。
不在运行期改写已存日志（append-only 原则）；改写只发生在上述离线工具里。
不含任何业务功能（子代理/记忆/重试/多模态各归各的插件）。

English

Host Cordis service (ctx.compat) providing session-event vocabulary registration (replacement for the removed registerSessionEventType(), with a mandatory omission-safety classification) and event-name alias normalization across historical format-migration spellings. Now also publishes a read-only diagnostics snapshot for a browser diagnostics page (registered event types / alias table / capability registry / vocabulary writability) plus a Settings -> General summary row. Ships an offline log-normalization maintenance tool. No business features, no runtime patching of harness internals. Targets DSH 0.2.0-rc.2+.

License: MIT. Author: jd962.

dsh-compat-layer

Install

Source

Readme