前言¶

DSH（DeepSeek Harness）是面向 agent 的运行时。很多团队已经在 Claude Code、Codex、WorkBuddy、OpenCode、GitHub Copilot 里沉淀了 hooks 与 rules：写文件前拦截、工具调用后补上下文、会话结束跑脚本等。若只按事件名硬接到 DSH，常见问题包括：Claude 的 updatedInput 被解析却不生效；Codex 的 permissionDecision: "ask" 没有审批路径而退化为放行；Copilot 把 deny 写在顶层而 DSH 解析器只读 hookSpecificOutput，导致 deny 被当成「无决定」而放行；OpenCode 的 TypeScript 回调体无法随名称一并迁移。

下面介绍社区插件 dsh-compat-adapter（维护者 denceee）：作为 DSH 前置/基座适配层，通过显式声明 vendor 与 event、能力分级、路由到真实 seam，让每次适配的损失可读，而不是表面能跑、实则静默失败。插件归类为工作流，可在 SkillHub 目录页 查看条目；源码与文档在 GitHub。

这是什么¶

dsh-compat-adapter 是 DSH Cordis bundle 插件，安装后只提供 ctx.compatAdapter 服务；它本身不自动迁移任何资产，由预置类插件在 apply() 里调用 registerHook / registerRules 触发适配。

设计原则可概括为三件事：

两个明确边界：

1. 不重造官方桥。能映射的事件交给 @deepseek-ai/dsh-hooks-claude-code / @deepseek-ai/dsh-hooks-codex，本插件负责把声明写成桥配置，并处理无官方桥的事件。
2. 不执行外部代码。JS 函数 handler、OpenCode TS 回调、Claude 的 http / mcp_tool / prompt / agent handler 一律 UNSUPPORTED，不把别家插件运行时嵌进 DSH Host。

当前 package.json 版本为 0.5.0，面向 DSH 0.2.0-rc.2，Node 要求 ^22.19.0 或 >=24.0.0，许可证 MIT。README 标注 141 项测试通过。

能力分级：不是「支持 / 不支持」二选一¶

每个注册返回冻结结果，没有抹平风险的 supported: true 字段。

112 个事件在文档与 test/doc-counts.test.js 中与代码对齐：102 个为真实/精确映射，10 个在各自 degradations 中自述 Approximate（Claude MessageDisplay、StopFailure；Codex Interrupt；WorkBuddy Elicitation、ElicitationResult；OpenCode installation.updated、server.connected、session.deleted、session.updated、tui.toast.show）。README 还提到 29 个原生翻译点，以及自建 Copilot 桥、真实文件监听、真实 git worktree 检测、官方 LSP 接入等实现方向；凡未在矩阵中声明的能力均不应假定存在。

测试强制的不变量包括：ADAPTED 必须至少一条 degradations；未知 vendor/event 抛 UNKNOWN_VENDOR / UNKNOWN_EVENT；UNSUPPORTED 资产永不写入配置、不挂桥。常见 UNSUPPORTED 路径：JS 函数 handler；组合里缺 ctx.shell 时命令 hook 无法执行（rules 仍可读文件并注入）；profile 解析不到 dsh-hooks-* 时拒绝、不退回自研实现；非 command 的 handler 类型抛 INVALID_HANDLER。

支持的 vendor 与路由¶

五家 vendor 互相独立，数据在 src/vendors/<vendor>.js，矩阵可脱离 Harness 单测。

路由含义简述：

• official-bridge（17）：claude / codex / workbuddy 有官方包时由桥映射到 DSH seam。
• native-translate（80）：本插件 src/translate.js 直接产出 DSH 裁决类型。
• native-seam / 只观察（5）：src/observe.js，记录阻断尝试但不取消生命周期。
• builtin-bridge（10）：仅 Copilot，DSH 无官方桥时使用 src/bridges/copilot.js（deny 拦工具、block 续跑、子 agent 注入、approval 等，细节见仓库 README Copilot 小节）。
• CARRY：五家 rules 注入模型可见上下文，不执行为策略。

阅读矩阵时注意：workbuddy 按 CodeBuddy 引擎（Claude-Code 兼容）处理，桌面端无公开 hook API 等限制写在每条 degradations；opencode 回调名可映射，TS 回调体不携带，须改写为命令；copilot 顶层 deny 等语义由自建桥与原生翻译共同覆盖，仍属 ADAPTED 并带损失说明。

安装与启用¶

插件以标准 DSH Cordis bundle 分发（package.json 的 dsh.bundle.patch + cordis.patch.yml）。安装命令以 README 为准，需使用本仓库在磁盘上的绝对路径，不要凭插件名拼接远程 URL。

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

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

装好后仅在 Cordis 中注册 compatAdapter 服务；实际迁移逻辑在你的预置插件里完成。

cordis.patch.yml 注意点：bundle patch 的 baseUrl 是 profile 根目录，insert 行的 name 必须是 bare specifier（例如 'dsh-compat-adapter'），不要写成相对路径或 node_modules/... 前缀，否则解析不到包。

在 agent preset 中先插入本插件，再挂载你的资产插件，并声明 inject: ['compatAdapter']：

- 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'

典型用法：注册 command hook¶

预置插件 apply() 在 setup 阶段完成注册（可为 async，Cordis 会等待）。示例来自 README：显式 vendor + event，handler 为命令字符串。

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

export async function apply(ctx) {
  const r = await ctx.compatAdapter.registerHook({
    vendor: 'claude',
    event: 'PreToolUse',
    matcher: 'Write',
    handler: 'node ./hooks/no-write.mjs',
  })
  // r.capability === 'ADAPTED'
  // r.seam、r.degradations 等字段应被预置逻辑记录或展示给用户
}

消费者如何组合多个 hook、如何注册 rules，见仓库 INTEGRATION.md。

本地校验可选用：

npm test
# 或完整校验链
npm run verify

适用场景与注意¶

适合谁：正在把 DSH 作为 agent 基座，且需要可审计地承接 Claude Code / Codex / WorkBuddy / OpenCode / GitHub Copilot 既有 hooks（command 形态）与 rules 的团队；愿意接受「全覆盖但逐条标明损失」，而不是假设行为与原厂逐字节一致。

务必知晓：

1. 插件与 DSH 进程同权限运行；安装前请阅读源码与 MIT 许可证，确认 handler 命令与 rules 内容可信。
2. 不存在「全部 DIRECT」的捷径；集成 UI 或文档应展示 degradations，避免对用户隐瞒 Approximate 事件。
3. peer 依赖包含 @deepseek-ai/dsh、dsh-hook-protocol、dsh-hooks-claude-code、dsh-hooks-codex 等 0.2.0-rc.2 对齐版本；版本不匹配时行为以实际解析结果为准，官方桥缺失会 fail-closed。
4. SkillHub（skillhub.cn）为社区插件目录，与 DeepSeek / 幻方无官方从属关系；星标与分类以目录登记为准（当前 GitHub 1 star，分类 工作流）。

结尾¶

dsh-compat-adapter 的价值在于：五家 vendor、112 个 hook 事件与 rules 的迁移路径被写成可测试矩阵，路由到真实 DSH seam，拒绝虚假等价与静默放行。若你要在 DSH 上复用既有编码助手资产，可从目录页了解条目，在 GitHub 阅读矩阵与 INTEGRATION，再用 profile 本地路径安装 bundle，由预置插件显式注册每一项适配。

• 目录页：https://www.skillhub.cn/plugins/denceee/dsh-compat-adapter
• 仓库：https://github.com/denceee/dsh-compat-adapter