dsh-compat-adapter

这是什么

DSH（DeepSeek Harness）是新的 agent 运行时。而你已经在 Claude Code、Codex、WorkBuddy、OpenCode、GitHub Copilot 里积累了成套的 hooks 与 rules —— 那些"写文件前先拦一下""工具调用后补一段上下文""会话结束时跑个脚本"的东西。

把它们搬到 DSH 最省事的做法，是照着名字硬接一遍。那会静默地坏掉：

Claude 的 updatedInput 被解析了但不生效； Codex 的 permissionDecision: "ask" 没有审批路径，退化成放行； Copilot 把 deny 写在顶层，而 DSH 的 hook 解析器只读 hookSpecificOutput —— 直接复用的话，每一个 deny 都会被当成"没有决定"而放行； OpenCode 的插件是 TypeScript 回调，"名字"能对上，"回调体"根本过不来。

这个插件存在的意义，是让每一次适配的"损失"都变成可读的输出，而不是一个看起来能跑的假象。

它只做三件事：

两个不做

• 不重造官方桥。 能映射的事件直接交给 @deepseek-ai/dsh-hooks-claude-code / -codex，本插件只负责"把声明变成桥的配置"和"没有桥的事件怎么办"。
• 不执行外部代码。 JS 函数 handler、OpenCode 的 TS 回调、Claude 的 http / mcp_tool / prompt / agent handler —— 一律 UNSUPPORTED。别家插件运行时不嵌进 DSH Host。

核心设计：分级，而不是布尔

每个注册都返回一个冻结的能力结果。没有 supported: true 这种把风险抹平的字段。

为什么一个 DIRECT 都没有

两个官方桥本身就是"尽力而为"的方言适配。宣称逐字节忠实，就是虚假能力。

所以本插件任何一行都不标 DIRECT —— 全部 112 行都是 ADAPTED，每一行都必须写出自己的损失。这不是悲观，这是诚实：test/matrix-readme.test.js 会断言 DIRECT.length === 0，并断言每一行 ADAPTED 都至少带一条 degradations。

全覆盖不等于等价。 112 个事件全部可执行（0 拒绝），但这是"每行都写明损失"的全覆盖，不是"全都一模一样"。其中 10 个事件在自己的 degradations 里明确写着 Approximate（Claude MessageDisplay、StopFailure；Codex Interrupt；WorkBuddy Elicitation、ElicitationResult；OpenCode installation.updated、server.connected、session.deleted、session.updated、tui.toast.show），其余 102 个为真实/精确映射。test/doc-counts.test.js 会把这组数字与代码逐项比对，文档不能比代码多宣称一分能力。

四条硬性不变量（测试强制，不是文档承诺）

那么在全部可执行的今天，UNSUPPORTED 还剩哪些真实触发路径？

• JS 函数 handler —— 不把外部代码执行进 Host。
• 缺 ctx.shell —— 组合里没有 shell executor，命令 hook 跑不了；rules 仍然可用（只读文件、只注入）。
• 缺官方桥包 —— dsh-hooks-* 从 profile 解析不到时拒绝，不退回自研实现。
• 非 command handler —— http / mcp_tool / prompt / agent 抛 INVALID_HANDLER。

支持的 vendor

五家互相独立。每家是一个纯数据模块（src/vendors/<vendor>.js）：无 I/O、不 import DSH，所以整张矩阵脱离 Harness 也能单测。

"近似"列统计 degradations[] 中自述 Approximate 的事件数。它与其他列并列展示、而不是藏进正文：它不为零，就不许写成零。

三个容易被误读的点：

• workbuddy：WorkBuddy 桌面端没有公开 hook API。本插件按 CodeBuddy 引擎（腾讯文档为 Claude-Code 兼容）处理，并把"桌面端无 API""CODEBUDDY_PROJECT_DIR 不导出""modifiedInput 不被读取"写进每一条 degradations，由测试断言。
• opencode：29 个回调名全部映射到 DSH seam，但 TS 回调"体"不携带 —— 必须改写为命令。这是 out of scope，不是"忘做了"。
• copilot：DSH 没有官方 Copilot 桥，所以其 14 个事件里 10 个走本插件自建桥（builtin-bridge），4 个走原生翻译。deny 真拦工具、block 真续跑、子 agent 真注入、approval 真决定 —— 详见 Copilot 的特殊路径。

工作流程

flowchart TB
    P["预置插件<br/>preset-class plugin"] -->|"显式声明 vendor + event"| S["ctx.compatAdapter<br/>registerHook / registerRules"]
    S --> G{"能力分级"}
    G -->|"official-bridge · 17"| B["官方桥<br/>dsh-hooks-claude-code / -codex"]
    G -->|"native-translate · 80"| T["原生翻译层<br/>src/translate.js"]
    G -->|"native-seam · 5"| O["只观察路由<br/>src/observe.js"]
    G -->|"builtin-bridge · 10"| BB["自建桥<br/>src/bridges/copilot.js"]
    G -->|"CARRY · rules"| R["原文逐字节携带"]
    G -->|"UNSUPPORTED"| X["拒绝 + reason<br/>永不挂载"]
    B --> SEAM["DSH seam<br/>tools/pre-execute · approval/request<br/>agent/turn-stopping · session/event …"]
    T --> SEAM
    O --> SEAM
    BB --> SEAM
    R --> CTX["agent/created<br/>注入模型可见上下文"]
    SEAM --> RUN["真实拦截<br/>deny 阻断 · block 续跑 · ask 走审批"]

四种路由的差别，就是**"决定能不能到达 DSH"**：

安装

标准 DSH Cordis bundle（package.json 的 dsh.bundle.patch + cordis.patch.yml）。

# 方式 A：plugin_manager 工具（受管理路径，推荐）
#   action: install_bundle, target: <本仓库绝对路径>

# 方式 B：CLI
dsh plugin --profile <profile> add <本仓库绝对路径>

装好后插件只做一件事：提供 ctx.compatAdapter 服务。它自己不做任何适配 —— 适配由预置插件声明触发。

# ✅ 正确
- insert:
    - id: compat-adapter
      name: 'dsh-compat-adapter'

预置类插件怎么用

在预置的 plugins 列表里插入本插件（装载顺序由 inject 保证），然后在你自己的 apply() 里调用服务：

- insert:
    - id: preset-my-preset
      name: '@deepseek-ai/dsh-agent-preset'
      config:
        id: my-preset
        name: My Preset
        plugins:
          - id: compat-adapter
            name: 'dsh-compat-adapter'
          - id: my-vendor-assets
            name: './my-vendor-assets/index.js'

// my-vendor-assets/index.js
export const name = 'my-vendor-assets'
export const inject = ['compatAdapter']

// apply 可以是 async：Cordis 会等待它，且注册必须在插件 setup 阶段完成。
export async function apply(ctx) {
  // ── hooks ──────────────────────────────────────────────────────────────
  const r = await ctx.compatAdapter.registerHook({
    vendor: 'claude',                        // 显式声明，不靠检测
    event: 'PreToolUse',
    matcher: 'Write',                        // 厂商 matcher 语义，原样交给官方桥
    handler: 'node ./hooks/no-write.mjs',    // 命令字符串 = command hook
  })
  // r.capability === 'ADAPTED'
  // r.seams      === ['tools/pre-execute']
  // r.degradations === [... 逐条损失 ...]

  // ── rules ──────────────────────────────────────────────────────────────
  const rules = await ctx.compatAdapter.registerRules({
    vendor: 'codex',
    source: 'rules/*.rules',            // 绝对路径 / 相对 baseDir / file:// / glob
    baseDir: '/abs/path/to/package',    // 相对路径的基准；必须绝对
  })
  // rules.capability === 'CARRY'，会话开始时作为上下文注入
}

公共 API

registerHook(declaration)

返回 Promise<CapabilityResult>（冻结）。可移植性不足不抛错 —— 只有"声明本身无法处理"才抛错。

registerRules(declaration)

返回 Promise<CapabilityResult>，capability === 'CARRY'，seams === ['agent/created']。

规则语义：注册时读盘并逐字节携带（附 sha256 与 bytes），在 agent/created（fresh / resume / clear / compact 全覆盖）时通过 agent.inject(createUserMessage(...)) 作为模型可见上下文入队。注入消息的 source.kind 是 compat-adapter-rules，与 DSH 自带的 agent-instructions 区分，日志里可追溯。

规则永远不是安全边界。 全部 CARRY。尤其 Codex 的 Starlark 规则是命令策略 DSL，DSH 没有对应规则引擎 —— 本插件只把它作为"原工具策略的说明文本"注入，不翻译、不强制执行。任何"规则会阻止某事"的预期都是错的；要强制，请写原生 DSH 插件挂到 tools/pre-execute。

其他方法

配置项（cordis.patch.yml 的 row config）

阻断契约

参考工具文档里"exit code 2 = 阻断"的行为，在本 DSH 版本的两个官方桥里不可靠（可能被记录为 decision: 'pass' 而放行）。因此本插件统一契约：

stdout 输出 hookSpecificOutput.permissionDecision（deny / ask）+ 退出码 0。

#!/usr/bin/env bash
# 例：拒绝写入 —— deny + exit 0
printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"no writes in this preset"}}'
exit 0

本插件生成的任何示例、测试与文档都用这一种；从不生成依赖 exit 2 的 handler。src/vendors/shared.js 的 permissionDecisionOutput() 是唯一生成入口，测试直接断言生成物含 permissionDecision、且不含遗留的顶层 decision 字段。

ask 映射成 DSH 的 {kind:'ask'}，deny 映射成 {kind:'deny'}（经官方桥，不经过本插件）。exit 2 仍会被桥解析（用户手写的老 hook 不会被吞掉），但这不是本插件承诺的契约路径。

Copilot 的特殊路径

GitHub Copilot 是唯一没有官方 DSH 桥的 vendor（Claude / Codex / WorkBuddy 都能复用官方桥），所以它的适配路径不同：本插件真的实现翻译层，不是旁观。

为什么不能直接复用 hook protocol

DSH 的 @deepseek-ai/dsh-hook-protocol 只认 Claude/Codex 方言：

// DSH 解析器只读这一层
{ "hookSpecificOutput": { "permissionDecision": "deny", "permissionDecisionReason": "…" } }

而 Copilot 把决定写在顶层：

{ "permissionDecision": "deny", "permissionDecisionReason": "…" }

若直接复用，每一个 Copilot deny 都会被静默当成"没有决定"而放行。所以 src/translate.js 里有一层 parseCopilotStdout() / normalizeCopilotOutput()：先按 Copilot 原生格式解析，再归一化成内部形状。

这条路径有专门的测试（test/smoke-copilot.test.js，21 个用例）并纳入 npm run verify:live 的真实启动验证。

事件映射

三处必须注意的方言差异

1. matcher 是锚定正则。 Copilot 编译为 ^(?:PATTERN)$ 且必须全匹配 —— bas 不会匹配 bash；无效正则会让该 hook 整体跳过（不是 match-all）。本插件按此实现。
2. allow 不预批准。 Copilot 的 allow 是"不弹权限提示"，不是"强制放行"，所以翻译成 next() 而非 allow 短路。
3. 阻断契约仍统一为 stdout + exit 0。 Copilot 本身还接受 exit 2 表示 deny，但本插件不让 hook 依赖它 —— 同一个 hook 脚本在各 vendor 下行为一致。

支持矩阵

本节由代码生成：npm run matrix:write 从 src/matrix.js 重新生成，test/matrix-readme.test.js 在漂移时报错。不要手改。

读矩阵需要注意的三件事：

1. ADAPTED 的损失是逐条列出的，不是修辞。例如 Claude PreToolUse 的 updatedInput 只被解析、不被采纳；Codex PreToolUse 的 ask 没有审批路径；Claude SubagentStart 的 agent_type 恒为 general-purpose（针对具体 agent type 的 matcher 永不命中）。
2. native-seam 的事件是"只观察"：PreCompact 映射到 session/event 的 compaction/start，SessionEnd 映射到 agent/disposed。DSH 的压缩是服务调用、不是可取消 waterfall，所以不能否决压缩；尝试阻断只会被记入审计日志并忽略。
3. WorkBuddy 的每一行都必须说明"桌面端无公开 hook API" —— 这是最容易误读的地方，所以它被写进每条 degradations 并由测试断言。

已知限制

诚实清单。每一条都在矩阵或测试里有对应证据。

验证

npm run check-surface     # 逐项断言已安装 DSH 的 seam / 导出 / 事件 / 服务
npm test                  # 141 个用例：单测 + 真实 Harness 冒烟
npm run verify            # 两者一起
npm run verify:live       # 真实 profile 启动的端到端验证
npm run verify:installed  # 确认"已装好的"插件真的生效

npm test 全部通过（141/141），无第三方测试依赖（node:test）。

测试结构

test/helpers/register-dsh-resolver.js 用 node:module 的 registerHooks 把 @deepseek-ai/* 解析到已安装的 DSH（$DSH_INSTALL_DIR → PATH 上的 dsh → 已知全局安装位），找不到就报错退出而不是跳过测试。

真实 profile 的端到端验证

npm test 里的冒烟测试启动的是真实 Cordis 上下文，但没有走产品启动器。npm run verify:live 补上这一段：在隔离的 $DSH_HOME 里用 sdk-minimal 初始化 profile → 以 link: 方式装进 profile → 通过官方 runProfile 真正启动 → 逐项断言。

实测输出：

verify-live: DSH install   /opt/node/lib/node_modules/@deepseek-ai/dsh
verify-live: profile       adapter-verify
  ok   ctx.compatAdapter is provided by the installed bundle
  ok   ctx.shell resolves in the live composition
  ok   the matrix covers every vendor, none claiming DIRECT
  ok   registerHook(copilot) returns ADAPTED on the native translation seam
  ok   a Copilot preToolUse deny reaches DSH (top-level permissionDecision is decoded)
  ok   the Copilot matcher is anchored: `bash` does not match `edit`
  ok   registerHook returns ADAPTED with a seam and degradations
  ok   a declared PreToolUse hook blocks Write at the live tools/pre-execute seam
  ok   the hook command really ran (side-effect trace + stdin payload)
  ok   the declared matcher is real: a non-matching tool stays allowed
  ok   registerRules returns CARRY on agent/created
  ok   carried rules are injected as sourced context on agent/created
  ok   a Copilot event with no faithful mapping is refused with a reason
  ok   an UNSUPPORTED declaration never becomes executable
  ok   status() reports the carried rules with hashes

verify-live matrix:
  claude     hooks=33 supported /  0 refused   rules=CARRY
  codex      hooks=12 supported /  0 refused   rules=CARRY
  workbuddy  hooks=24 supported /  0 refused   rules=CARRY
  opencode   hooks=29 supported /  0 refused   rules=CARRY
  copilot    hooks=14 supported /  0 refused   rules=CARRY

verify-live: PASS

为什么 verify:live 要自己 spawn 一个持有 stdin 管道的子进程： sdk-minimal 模板挂载的 dsh-sdk-app 注册了 exitOnStdinEnd，stdin 一到 EOF 就 exit(0) 卸载整个组合。从 shell 继承来的 stdin 经常已经是 EOF（重定向自 /dev/null、管道上游已退出、CI 的封闭 stdin），因此脚本把子进程的 stdin 管道一直握在手里。这不是被测插件的缺陷，是 SDK profile 的正常产品行为。

确认"装好的插件真的生效"

配置里出现一行不等于运行时服务可用。npm run verify:installed 用真实启动器 boot 一个已经装好的 profile：

export DSH_HOME=/tmp/dsh-adapter-home
node scripts/verify-installed.mjs --profile smoke

{
  "profile": "smoke",
  "service": { "compatAdapter": true, "shell": true },
  "deny": { "capability": "ADAPTED",
            "decision": { "kind": "deny", "reason": "installed-plugin-denial" },
            "nonMatch": { "kind": "allow" } },
  "rules": { "capability": "CARRY", "injected": 1, "sourceKind": "compat-adapter-rules" },
  "status": { "hooks": 1, "executableHooks": 1, "unsupportedHooks": 0, "rules": 1, "carriedFiles": 1 }
}

项目结构

dsh-compat-adapter/
├── index.js                 # Cordis 插件入口：provide ctx.compatAdapter
├── cordis.patch.yml         # bundle patch（name 必须是 bare specifier）
├── package.json             # dsh.bundle.patch + 精确钉住的 peerDependencies
├── src/
│   ├── service.js           # CompatAdapter：registerHook / registerRules / status / matrix / dispose
│   ├── capability.js        # 四级词表 + capabilityResult() 校验与冻结
│   ├── surface.js           # DSH 版本与所消费的 seam / 导出 / 事件，单点固定
│   ├── bridge-host.js       # 官方桥宿主：生成配置、挂载、事务化重挂、回滚、剪枝
│   ├── translate.js         # 原生翻译层：vendor 决定 → DSH 裁决类型
│   ├── observe.js           # 只观察路由：跑 hook、记审计、忽略阻断
│   ├── rules.js             # 读盘携带、sha256、渲染注入文本
│   ├── matrix.js            # 支持矩阵（README 与测试共用同一渲染）
│   ├── peer.js              # 惰性 peer 解析（保证插件总能挂载）
│   ├── hook-runner.js       # runHook 的唯一薄封装
│   ├── classify.js          # 裁决分类
│   ├── errors.js            # 稳定错误码
│   └── vendors/             # 纯数据模块：无 I/O、不 import DSH
│       ├── index.js         # vendor 注册表与别名
│       ├── shared.js        # bridged / nativeSeam / nativeTranslate / unsupported 构造器
│       ├── claude.js        # 33 事件
│       ├── codex.js         # 12 事件
│       ├── workbuddy.js     # 24 事件
│       ├── opencode.js      # 29 事件
│       └── copilot.js       # 14 事件
├── test/                    # node:test，15 个文件，141 个用例
├── scripts/
│   ├── check-surface.js     # 逐项断言 DSH 表面
│   ├── write-matrix.js      # 从代码重写 README 矩阵块
│   ├── verify-live.mjs      # 真实 profile 启动验证
│   └── verify-installed.mjs # 已装 profile 的生效验证
└── locale/                  # en / zh 插件元数据

给下一位维护者：实现中踩到的 DSH 坑

这些都是在本插件在 0.2.0-rc.2 上实测踩到并已修复的，不是猜测。

新增一个 vendor

1. 建 src/vendors/<id>.js，导出 VENDOR / HOOKS / RULES / KNOWN_EVENTS（可选 BRIDGE_PACKAGE）。用 shared.js 的 bridged / nativeSeam / nativeTranslate / unsupported 构造每条映射。
2. 加进 src/vendors/index.js 的 VENDOR_MODULES（含别名）与 VENDORS。
3. 在 test/vendors.test.js 补 fixture 行。
4. 跑 npm run matrix:write 重生成 README 矩阵块，再跑 npm test。

未知 vendor 传进服务是作者错误（UNKNOWN_VENDOR），永远不会静默 fallback。

贡献

npm install          # 无运行时依赖；peer 由 DSH 安装提供
npm run check-surface
npm test
npm run verify:live

提交前请确保 npm run verify 全绿。改动 src/vendors/** 或 src/matrix.js 后必须重跑 npm run matrix:write，否则 test/matrix-readme.test.js 会失败 —— 这是设计如此：文档不允许比代码声称更多。

许可

MIT © dsh-compat-adapter contributors