@shuind/dsh-codex

English | 中文

面向不适配 DSH 原生接口的 GPT 模型，提供一个极简的 Codex harness。它保留 DSH 的运行时、profile、服务和插件生态，只把模型看到的提示词与核心工具切换为紧凑的 Codex 协议；现有 DSH 插件仍可继续使用，本包只替换模型面向的这一层。

DSH 兼容性

本包是模型面向的兼容层，不是另一套运行时。会话、服务、profile 组合、provider 和插件生命周期仍由 DSH 管理。把它安装到现有 DSH profile 后，其他 DSH 插件仍可按原方式组合使用。

安装、启用和选择

这三件事是分开的：

1. 把插件安装到 Web 使用的 profile：

   dsh plugin --profile web add @shuind/dsh-codex

   本包仍是标准 DSH bundle，因此会显示在插件列表中；它的 DSH 依赖是 optional peer，不会因为本包产生 peer warning。

2. 启用插件：启动或重启该 profile。bundle 会在 $DSH_HOME/.agent-presets/codex 不存在时，把随包提供的 codex preset 安装到这里；已经存在的用户 preset 不会被覆盖。

3. 新建对话，在模式菜单中选择 Codex 模式。插件列表和 Agent preset 列表不是同一个界面。DSH 0.1.0-rc.6 会从 $DSH_HOME/.agent-presets 发现用户 preset；更新版 DSH 也可能自己提供 system codex preset。

如果之前手动创建的 $DSH_HOME/.agent-presets/codex 缺少有效的 agent.cordis.yml，请修复或删除该目录后重启 profile。安装器有意保留已有目录，不会强行覆盖。

preset 在会话创建时确定。选择 Codex 只影响新建对话，不会改写已有会话的提示词和工具目录。

功能

随包提供的 codex preset 会挂载本包，以及 dsh 的 Skill 文件系统和 Skill 工具。本包拥有 Codex 提示词区段，以及以下精确的模型工具名称和描述：

• exec_command：在 PTY 中运行命令，返回输出或用于后续交互的 session id。
• write_stdin：向已有的统一 exec 会话写入字符并返回最近输出。
• apply_patch：通过唯一必填的 input 字符串接收完整的自由格式 patch 文本。
• update_plan：接收可选 explanation，以及由 step／status 项组成的必填 plan。

完整 schema 以导出的工具注册为准。前两个工具返回 Codex 兼容的执行字段（chunk_id、wall_time_seconds、exit_code、session_id、original_token_count 和 output），并使用相同的 Chunk ID／Wall time／Output 响应信封。apply_patch 返回变更文件列表，并渲染熟悉的 Success. Updated the following files: 摘要。update_plan 写入持久化的 todo/write 事件，并返回 Plan updated。

dsh 组合

exec_command 使用 dsh Shell 服务执行管道命令，并使用 dsh Terminal 服务执行可选的 PTY 会话。Codex 的 shell、login、yield_time_ms 和 max_output_tokens 参数仍然面向模型，并在服务接口处完成转换。write_stdin 通过每个 agent 的统一会话注册表寻址。

apply_patch 解析 Codex patch 语言，通过 dsh fs 解析目标，执行带版本检查的写入／删除，记录文件系统结果，并通过 sandboxPolicy 处理沙箱决策。它不引入第二套文件系统实现。新增、更新、删除和移动都使用 dsh 的标准文件系统错误和持久化观测事件。

update_plan 只追加会话中的 todo/write 事件，不依赖额外的运行时投影 helper，也不维护第二个 plan 存储；投影和回放仍由 DSH 负责。因此它同时兼容旧版和新版 dsh-tool-todo。Codex 包不会挂载 todo_write。

配置

本包接受 defaultYieldTimeMs、pollYieldTimeMs、writeYieldTimeMs 和 maxOutputBytes。它们控制执行时序和保留的输出大小；协议名称、参数名称、描述和结果字段是固定的。使用沙箱文件系统时，必须同时提供对应的 dsh sandboxPolicy 服务。

在 DSH 0.1.0-rc.6 中，apply_patch 使用普通 dsh 工具定义；它的 input 仍然接收完整的 Codex freeform patch，具体 provider 的工具序列化由 DSH 路由负责。

Bundle 与 preset 组合

本包声明了 dsh.bundle patch，但这个 patch 只负责安装 preset 模板，不会把 @shuind/dsh-codex 全局挂载，也不会把 Codex 工具加入 standard、code、minimal 或其他 preset。随包的 presets/codex/agent.cordis.yml 只包含一个 codex-tools 行，因此 Codex 会话只挂载一次提示词和四个核心工具。

如果你自己编写 Codex preset，请把 @shuind/dsh-codex 放在该 preset 的 agent.cordis.yml 中，不要放到 profile 顶层 patch。这样也不会和新版 DSH 自带的 system Codex preset 重复。

preset 仍把 Skills、文件系统策略、shell provider、terminal provider 和 Web 展示留给 dsh 扩展点；可以通过其他 preset 或对应的 dsh 行扩展，而不改变 Codex 工具协议。

模型体验

提示词和工具目录

模型看到的内容

请求包含 Codex 基础提示词、四个 Codex 核心工具，以及显式挂载的 dsh 扩展（例如 skill）。工具名称、描述、参数名称和结果封装与 Codex harness 协议一致；dsh 的实现服务隐藏在工具之后。

Token 影响

该 preset 的每次请求都承担 Codex 提示词和核心 schema 的固定前缀成本。Skill 内容和工具结果取决于实际数据。

KV Cache 影响

会话挂载组合不变时，固定提示词和工具前缀可以复用。Skill 发现结果和其他显式挂载的扩展会从 Codex 前缀之后改变请求后缀。

工具调用和结果

模型看到的内容

命令调用返回 Codex 执行封装，patch 调用返回变更文件封装和摘要文本，plan 调用返回持久化的计划确认。文件系统事件和会话事件会在回放时重建模型可见的效果。

Token 影响

工具结果取决于数据：命令输出和变更文件摘要会保留在会话中，而计划确认的大小固定且很小。

KV Cache 影响

工具结果追加到会话上下文。文件变更或计划更新通过标准 dsh 会话日志和投影影响后续上下文，而不是依赖隐藏的可变状态。

已知限制与暂缓事项

• preset 对一个会话固定不变。选择 codex 会影响新会话；在 Web 中改变选中的 preset 不会重写已有会话的提示词或工具。
• PTY 行为取决于挂载的 dsh Terminal provider。出厂的 Windows 组合禁用可选的 bash terminal 行；管道执行仍可通过选中的 shell 服务使用。
• 管道会话不接受非空的 write_stdin 输入；交互式输入需要 PTY 会话。
• provider 专用的 custom tool 或 grammar 序列化不属于本包；Codex patch 协议通过普通 dsh 工具定义即可使用。
• 本包实现 Codex 核心协议，并刻意通过 dsh 插件保留 Skills、文件系统策略、shell provider、terminal provider 和 Web 展示的可扩展性。