从 Codex / Claude Code 迁移
三条迁移路径：模型层兼容（Responses API）、复用现有 hooks.json（hook 桥接）、原生 Cordis 插件
如果你正在使用 OpenAI Codex 或 Anthropic Claude Code，DeepSeek Harness 提供了三条渐进式的迁移路径。本页基于上游仓库的 hooks 子系统文档与 DeepSeek API 官方公告整理。
先想清楚：要不要迁移
Harness 仍处于开发者预览阶段，而 Codex 与 Claude Code 是成熟产品。如果当前工具已经满足需求，不必因为 DeepSeek 官方基准使用 Harness 就立即迁移——基准成绩是「模型 + Harness + 配置 + 工具环境」的系统成绩，见评测口径。
三条路径可以按需组合，互不冲突：
| 路径 | 做法 | 适合 |
|---|---|---|
| 1. 模型层兼容 | 继续用 Codex，把模型指向 DeepSeek API | 想先用上 DeepSeek V4，不想换工具 |
| 2. Hook 桥接 | 迁移到 dsh，复用现有 hooks.json | 团队已沉淀 hooks 工作流，想平缓切换 |
| 3. 原生插件 | 用 Cordis 插件在扩展点上重写定制逻辑 | 长期投入、需要类型化返回与更强能力 |
路径一：模型层兼容
DeepSeek API 已原生支持 OpenAI Responses API 格式，并针对性适配 Codex；官方文档提供一键配置脚本完成 Codex 的接入（见 DeepSeek API 官方公告）。模型接入细节见配置模型。
这一步几乎零成本
不改工作流、不换编辑器，只换模型端点，即可对比 DeepSeek 模型在你的任务上的表现。这也是评估「模型 vs 工具」贡献的最快方法。
路径二：Hook 桥接
Harness 的 hooks 子系统允许把现有的 Claude Code / Codex hook 配置直接指给桥接插件，让这些外部 shell hook 在 Harness 的类型化拦截点上继续运行。两个桥接均为 Cordis 插件：
Claude Code 桥接（dsh-hooks-claude-code）
读取 Claude Code 的 hooks.json（或 settings 文件的 hooks key），映射的 hook 点：
| Claude Code hook | 行为 |
|---|---|
SessionStart | additionalContext 注入新会话（不可阻塞） |
UserPromptSubmit | deny → 拒绝该步；additionalContext → 追加上下文 |
PreToolUse | deny → 拒绝工具调用；ask → 转为审批请求 |
PostToolUse | deny → 带反馈阻断；additionalContext → 前置上下文 |
Stop | 阻塞 Stop 并把原因送回，强制 agent（智能体）再执行一步 |
SubagentStart / SubagentStop | 注入上下文 / 仅观测 |
在 cordis.yml 中启用：
- dsh-hooks-claude-code:
configPath: ./.claude/hooks.json
pluginRoot: ./.claude/plugins/my-plugin
projectDir: .configPath：必填；进程级配置，启动时解析一次。pluginRoot：替换命令里的${CLAUDE_PLUGIN_ROOT}。projectDir：替换${CLAUDE_PROJECT_DIR}并设置 hook 环境变量，缺省为会话 cwd。- 只运行
type: 'command'的 hook；http/mcp_tool/prompt/agent会被解析并跳过（记录警告）。 - hook 进程在会话工作区目录运行；多个 hook 按配置顺序串行执行，决策按最严格方式折叠（
deny > ask > allow）。
Codex 桥接（dsh-hooks-codex）
读取 Codex 的 hook 配置，实现其 10 个 hook 点中的 5 个：PreToolUse、PostToolUse、SessionStart、UserPromptSubmit、Stop。
- dsh-hooks-codex:
configPath: ./.codex/hooks.json
model: deepseek-v4- matcher 一律按正则解释；stdin payload 为 snake_case，额外携带
turn_id与model。 - 不注入 Codex 插件环境变量，也不做配置期占位符替换。
- 没有工具预审批或改写路径：hook 可以阻塞，但不会预批准或替换工具输入。
- 只运行同步
type: 'command'hook；async: true会被跳过（记录警告）。
桥接的边界
桥接是兼容路径，不是完整能力
两个桥接都只覆盖各自协议的一个子集。解析失败会被隔离（记录警告、不注册任何内容），不会拖垮启动；但原生 Cordis 插件能做桥接能做的一切，且具有类型化返回、无序列化边界。所有深度定制都应迁移到原生插件（见开发者指南）。
路径三：原生 Cordis 插件
hook 桥接底层是 Harness 的类型化拦截点（agent/pre-step、tools/pre-execute、tools/post-execute 等，见 Host 服务与事件）。一个「原生 hook」就是挂在同一批扩展点上的普通 Cordis 插件——把外部 shell hook 协议翻译到这些点上，就是桥接做的事；你自己写插件时直接消费这些点即可。
常见概念对照
| Codex / Claude Code | DeepSeek Harness |
|---|---|
hooks.json（shell hook） | cordis.yml 插件（或 hook 桥接兼容层） |
PreToolUse deny / ask | tools/pre-execute waterfall 决策（deny / ask） |
${CLAUDE_PLUGIN_ROOT} | 桥接的 pluginRoot 配置 |
| 产品自带审批 | 内置 permission preset（权限预设）与审批策略 |
| 终端 CLI | Web GUI / headless / CLI 三形态 |
建议路线
- 先跑通模型层兼容（路径一），用你自己的任务集做 A/B；
- 需要沿用 hooks 工作流时接入桥接（路径二），并逐步把高频 hook 改写为原生插件（路径三）；
- 迁移期间保留旧工具作为回退，双轨运行一段时间再切换。