@opentritium/dsh-codex-shim

English README

本插件在选定的模型路由上模拟 Codex 风格的 prompt、tool vocabulary、工具结果和 WebUI 展示，帮助 GPT 系列及其他适配 Codex 的模型更可靠地调用工具。

本包是 shim，不是 Codex runtime。它不启动 Codex app-server，不处理 Codex OAuth，不提供模型、凭据、命令执行器或网页搜索后端。插件只通过 DSH 的公开 Service Definition、Consumer 和 UI slot 使用现有能力；模型不匹配或移除 bundle 后，DSH 会照常使用它原本的工具和行为。

在 profile 中安装

以下示例将 bundle 安装到 WebUI web profile。由 dsh plugin 维护 profile manifest 和依赖列表。

使用 gh 下载 Release tarball

gh release download --repo OpenTritium/dsh-codex-shim --pattern 'opentritium-dsh-codex-shim-*.tgz'
pnpm dsh plugin --profile web add ./opentritium-dsh-codex-shim-*.tgz
pnpm dsh --profile web --dump-config

没有 GitHub CLI 时，可用 curl 与 jq 下载同一个最新 Release 资产：

curl -fsSL https://api.github.com/repos/OpenTritium/dsh-codex-shim/releases/latest \
  | jq -r '.assets[] | select(.name | endswith(".tgz")) | .browser_download_url' \
  | xargs -r curl -fLO
pnpm dsh plugin --profile web add ./opentritium-dsh-codex-shim-*.tgz
pnpm dsh --profile web --dump-config

如果内置的 gpt-5.6-* 规则已经够用，无需阅读下面两个关于配置的小节。

通过配置文件配置

通过 profile 的 settings provider 配置本插件。默认的文件 provider 使用 $DSH_HOME/settings.yaml（通常是 ~/.dsh/settings.yaml）；在其中创建或编辑 codex-shim: 分节即可。在显式设置 modelPatterns 前，bundle 内置的 gpt-5.6-* 自动规则仍然生效。

codex-shim:
  enabled: true
  modelPatterns:
    - gpt-5.6-*
    - deepseek-v4-*
  modelOverrides:
    - provider: openai
      model: gpt-5.6-luna
      enabled: true
    - provider: example-provider
      model: experimental-model
      enabled: false

enabled: false 会关闭全局 shim。modelPatterns 会替换自动启用规则列表；填 modelPatterns: [] 可以关闭自动匹配。每条 modelOverrides 是精确的 provider/model 决策，优先于自动规则；未添加的模型仍遵循自动规则。provider 和 model 必须与 DSH 解析出的路由完全一致。

文件 settings provider 会监听合法的配置修改，因此路由策略会热更新。如果 profile 使用其他 settings provider，应通过该 provider 配置同一个 namespace。

补丁 WebUI 以提供可视化配置（可选）

DSH 47f943859bef60e4160492346772ded9b24f765a 尚不能让外部 bundle 将 settings namespace 暴露给 WebUI。不需要设置卡时，只安装 tarball 并按上面的 settings.yaml 配置即可。若希望获得更好的 GUI 设置体验，对应 Release 会附带 deepseek-harness-settings-client-exposure-47f9438.patch：这是一个不包含 OpenTritium 或 Codex 行为的通用 WebUI settings 白名单扩展。

只在该精确、干净的 DSH commit 上应用 patch，重建 DSH 后再安装 Release tarball：

gh release download --repo OpenTritium/dsh-codex-shim --pattern 'opentritium-dsh-codex-shim-*.tgz' --pattern 'deepseek-harness-settings-client-exposure-47f9438.patch'
git clone https://github.com/deepseek-ai/deepseek-harness.git deepseek-harness
cd deepseek-harness
git checkout 47f943859bef60e4160492346772ded9b24f765a
git apply --check ../deepseek-harness-settings-client-exposure-47f9438.patch
git apply ../deepseek-harness-settings-client-exposure-47f9438.patch
pnpm install && pnpm run build
pnpm dsh plugin --profile web add ../opentritium-dsh-codex-shim-*.tgz
pnpm dsh --profile web --dump-config

该 patch 为 settings owner 增加显式的 expose: 'client' 选项；不会加载本 bundle、添加 OpenTritium row 或改变模型/工具行为。不要对 dirty checkout 或其他 commit 应用它；应等待上游提供等价能力。

卸载

移除 bundle 不需要 DSH patch，并会恢复纯上游的 profile 组合：

pnpm dsh plugin --profile web remove @opentritium/dsh-codex-shim
pnpm dsh --profile web --dump-config

若之前应用过可选的 WebUI patch，请先移除 bundle。只有确认没有其他本地外部 bundle 使用 expose: 'client' 时，才反向应用 patch：

pnpm dsh plugin --profile web remove @opentritium/dsh-codex-shim
git apply --reverse --check ../deepseek-harness-settings-client-exposure-47f9438.patch
git apply --reverse ../deepseek-harness-settings-client-exposure-47f9438.patch
pnpm run build
pnpm dsh --profile web --dump-config

dsh plugin remove 会删除 profile 依赖和 bundle layer。若也要清理已保存的 shim 偏好，删除 $DSH_HOME/settings.yaml 中完整的 codex-shim: 分节即可；文件 settings provider 会热更新合法修改。

路由和配置

bundle 会全局挂载 gate，但只有同时满足以下条件时才应用 Codex surface：

• 全局开关已启用；
• 当前模型匹配自动规则，或显式的 provider/model override 启用它；
• 当前 scope 中至少存在一个 shim tool。

默认自动规则是 gpt-5.6-*。用户可以改成 deepseek-v4-* 等规则，填入空列表关闭自动匹配，或使用显式 provider/model override。WebUI 设置页通过 DSH settings slot 提供相同配置。

Shim 工具

下列工具由 bundle 注册，并只在激活的 Codex 路由中向模型展示。“降级”表示底层 DSH capability 尚未覆盖完整 Codex 操作。

工具	状态	DSH capability	说明
exec_command	可用	ctx.shell、sandbox policy、approval	执行命令、限制输出，并保留 session 供后续轮询。
write_stdin	降级可用	ShellProcess 读取	可以轮询已有 session。当前 DSH shell 定义没有 stdin 写入操作，非空 stdin 会明确拒绝。
apply_patch	可用	ctx.fs、ctx.shell	支持 Codex patch marker、添加/删除/更新/移动文件和模糊匹配。删除二进制文件时不显示文本 diff。apply-patch、applypatch 仅作为兼容别名，不在 surface 中展示。
view_image	条件可用	ctx.fs、attachment service	profile 提供 filesystem 和图片 attachment capability 时读取 PNG、JPEG、WebP、GIF。
update_plan	可用	持久化 todo/write session event	保存 pending、in_progress、completed 步骤，最多一个进行中步骤。
web_run	仅搜索	ctx.web.search()	接收多个 search_query 并返回 provider 来源；不实现 open、click、find、截图或任意 fetch。

被 Mask 的工具

当替代工具存在时，gate 会从当前 prompt advertisement 中隐藏重叠的上游工具。它不会注销这些工具，因此路由切换或移除 shim 后，上游 surface 会恢复。

已存在的 shim 工具	隐藏的上游工具
exec_command	bash、pwsh、read、glob、grep
exec_command + write_stdin	terminal_close、terminal_list、terminal_open、terminal_read、terminal_send、terminal_signal
apply_patch	edit、str_replace_editor、write
view_image	read_image
update_plan	todo_write
web_run	web_search

Mask 具有 scope 感知能力。如果前置工具无法在当前 composition 中解析，对应 mask 不会生效。

局限性

• write_stdin 只是轮询适配器，不是完整交互终端。要支持 stdin 写入、信号和终端控制，需要通用的 DSH shell 定义者和提供者。
• web_run 有意保持搜索-only。未来的网页引用或抓取 provider 应通过独立 DSH seam 提供这些能力；本包不携带 OpenAI hosted provider。
• 补丁拦截覆盖直接的 Codex patch 调用。隐藏在更大 shell script 中的 patch 会交给 shell，不会被猜测拦截。
• 工具可用性取决于 profile composition。缺少 shell、filesystem 或 attachment capability 时会明确失败，不模拟成功。

shim 只消费 capability 定义，不实现或选择 provider。实际 provider 由 DSH profile 负责选择。

TODO / 路线图

以下是后续工作，不代表当前已经提供这些能力：

• OpenAI Responses 网页抓取： 新增独立的 DSH web 定义者/提供者，使用当前命中路由的 Responses 端点；只有 provider 真正支持时，才暴露网页引用、导航和抓取操作。不支持时继续保持 web_run 仅搜索。本 shim 不硬编码端点，也不加入 OpenAI hosted search provider。
• 交互式终端： 扩展通用 DSH shell 定义者和提供者，支持 stdin 写入、信号、session 列出/打开/关闭、PTY 行为和跨平台一致性；再升级 write_stdin 与 session 管理，不宣称尚未支持的操作。
• Windows 兼容性： 在宣称支持 Windows 前，补充 Windows CI，覆盖 bundle 安装、profile 组合、已支持工具的行为和 WebUI 启动。
• Codex 行为对齐： 对照参照版本检查工具 schema、参数校验、错误、生命周期、权限请求、transcript event 和 WebUI 展示；每项能力先补 composition 和 acceptance 测试，再扩大 surface。

目标是在 DSH capability 之上尽可能接近 Codex 体验。Runtime、OAuth 和 Responses wire protocol 兼容仍不属于本包范围。

兼容性

组件	支持基线
DeepSeek Harness	tarball 安装固定为 commit 47f943859bef60e4160492346772ded9b24f765a（0.1.0-rc.5）。对应的 settings-client-exposure patch 是可选项，仅用于显示 WebUI 设置卡；不假定附近 commit 兼容。
DSH peers	@deepseek-ai/dsh-* peer 目标为 ^0.1.0-rc.5；Cordis 目标为 ^4.0.1，避免安装第二个 Cordis runtime。
Node.js	^22.19.0 或 >=24.0.0。
React/WebUI	React 18；浏览器代码使用 DSH 的 locale、settings、connection、runtime 和 slot API。
Codex 参照	@openai/codex / codex-cli 0.147.0，用于工具名、patch 行为和 app-server 产品参照。本包不声明完整 Codex runtime 或 wire protocol 兼容。

每个 shim 版本都会针对表中的基线进行组合验证。升级 DSH 或 Codex 后，应重新检查工具 schema、prompt section、approval/sandbox 字段和 WebUI slot contract。

Windows： Windows 上的行为和兼容性尚未测试。当前开发和测试以 Unix 风格的 shell 与 filesystem 语义为目标；若在 Windows 上运行遇到问题，请反馈。

开发

pnpm install
pnpm run check
pnpm run bench

发布包包含 lib/、cordis.patch.yml、两份 README 和许可证。persona 与 locale 源文件会在 tsdown 构建时打包。

推送与 package.json 版本严格对应的 vX.Y.Z tag 会触发 GitHub Actions 发布流程。它会验证可选的源码集成、运行 pnpm run check，将打出的 tarball 和可选 GUI patch 附加到 GitHub Release，不会发布到 npm。

许可证

MIT，详见 LICENSE。