Codex 对话套件 DamonBao/dsh-codex-suite

DSH Codex Suite

为 DeepSeek Harness（DSH）打造的插件套件：把 ChatGPT / OpenAI Codex 模型和 Codex 风格的对话体验带进 DSH Web UI。基于 DSH 0.2.1-rc.2 构建（peer 范围 >=0.2.0-rc.2 <0.3.0-0）。

本仓库是 pnpm monorepo，包含两个相互独立的运行时插件和一个纯组合包：

| 包 | 类型 | 功能 |
| @jcy2387/dsh-codex-provider | 运行时插件 | 注册 openai-codex Provider：ChatGPT OAuth 登录、主动令牌刷新、用量面板、代理感知网络和原生设置页。 |
| @jcy2387/dsh-conversation-ui | 运行时插件 | 增强助手揭示、思考自动展开和产物展示，保留 DSH 原生对话布局与控制。 |
| @jcy2387/dsh-suite | 纯组合包 | 不含运行时代码，仅通过一个 profile patch 一次装齐两个插件。 |

两个插件完全解耦：Conversation UI 可服务任意模型，Codex Provider 也可搭配原生对话界面使用。

为什么需要这套件

Codex Provider —— 无需 API Key 的可靠 ChatGPT 接入

- 双流程 ChatGPT OAuth。 浏览器登录 + 设备码兜底。登录失败会被归类为无敏感信息的本地化原因（区域受限、回调端口冲突、令牌交换错误、网络问题……），而不是裸报错堆栈。
- IPv6 回环回调桥。 pi-ai 的 OAuth 监听只绑 IPv4；在 IPv6 优先的主机上，套件会透明转发回环回调，登录依然可用。
- 主动令牌刷新。 访问令牌在过期前约 5 分钟轮换，失败按退避重试；刷新令牌失效会被精确识别并提示「需要重新连接」，而不是在流式中途崩掉。
- 用量面板。 从 ChatGPT 账号级接口获取套餐（以 Plus / Pro 5x / Pro 20x 等对外名称显示）、Credits、主/次限额窗口的用量百分比条和重置时间。
- 重置次数（额度银行）。 查看账号可用的 banked reset 次数与最早到期时间，并在确认弹窗中一键兑换，恢复 5 小时与每周限额窗口。
- 代理感知网络。 自动探测环境变量与系统代理（macOS / Windows / Linux），仅让 OpenAI 流量走代理、回环保持直连，并提供显式代理模式（auto / environment / off）。
- 可靠性优先的默认值。 默认 SSE 传输（避免 WebSocket 后期失败导致部分输出重复）、5 分钟流空闲超时、可配置重试策略。
- 原生设置页 位于 插件 → DSH Codex Suite → codex-provider，中英文界面、实时状态，RPC 仅限 loopback 权限——凭据绝不离开 Host。

Conversation UI —— 在 DSH 原生对话中增强

- 原生呈现。 工具分组、工作步骤展示模式、过程折叠、运行状态和视口恢复由 DSH 管理。
- 两种揭示模式。 typewriter（默认）按字素揭示，可选三种预设和速度；teleprompter 直接显示最新快照。回合结束后剩余队列以更快的收尾速率排空，再切换到完整快照；停止、失败和减少动态效果同样保证不丢内容。
- 思考偏好。 持久化的自动展开设置作用于原生流式思考，用户仍可手动折叠。
- 原生助手功能。 Markdown、图片、文件引用、停止标记和最终答复操作保留 DSH 行为。
- 产物卡片。 完成回合展示文件编辑和网站，附真实增删行数；原生 changed-files 卡启用时文件交给原生卡（含 diff 预览与审阅），插件只补网站，避免同一回合两张文件卡。相对/绝对路径会归一化合并，同一文件只计一次。

插件显示元数据通过包导出的 locale/en.json 与 locale/zh.json 提供，使用 meta.title、meta.description；插件列表、详情及组件名称跟随 DSH 界面语言。package.json 的普通描述保留英文供 npm 使用。

自定义图标由 package.json 的 icon: "./icon.svg" 声明，随 npm 包一起发布。套件和两个子组件统一使用青绿代码图标。

安装

前置条件：DeepSeek Harness（dsh）>=0.2.0-rc.2 <0.3.0-0（装有 web profile）、Node.js ^22.19 || >=24、pnpm 11。

安装整套 Suite（推荐）：

dsh plugin --profile web add @jcy2387/dsh-suite@0.2.1-rc.2
dsh web

或单独安装插件：

dsh plugin --profile web add @jcy2387/dsh-codex-provider@0.2.1-rc.2
dsh plugin --profile web add @jcy2387/dsh-conversation-ui@0.2.1-rc.2
dsh web

本地开发 —— 用工作区内的包替代发布版：

dsh plugin --profile web add link:$PWD/packages/codex-provider
dsh plugin --profile web add link:$PWD/packages/conversation-ui
dsh web

在同一个 profile 里，整套 Suite 和单独插件二选一安装。Suite 直接注册 codex-provider 和 conversation-ui；再安装同一插件的独立 bundle 会产生重复 loader entry id，导致无法启动。变更 bundle 列表后请重启 dsh。

从旧分组套件升级时，移除针对 suite-plugins 的 overlay，直接配置 codex-provider 和 conversation-ui。插件 id、已保存的偏好、凭据和会话数据不变。

快速开始

1. 安装套件（见上）并打开 Web UI（dsh web）。
2. 进入 插件 → DSH Codex Suite → codex-provider，点击连接，选择浏览器登录（无头/远程机器可用设备码登录），完成 ChatGPT 授权。
3. 回到对话，在模型选择器中挑选 openai-codex 模型即可开聊。
4. 可选：在同一设置页查看用量面板，并在 插件 → DSH Codex Suite（或 Conversation UI） 中调节对话流参数。

配置

两个插件都通过 profile 的 cordis.patch.yml overlay 配置部署默认值；Conversation UI 的 mode、preset、revealCharsPerSec 和「自动展开思考」同时可在插件设置卡中实时修改并跨重启持久化。

Codex Provider（profile patch ID：codex-provider）

| 选项 | 取值 | 默认 | 说明 |
| transport | sse \| websocket \| websocket-cached \| auto | sse | SSE 可避免流后期失败时部分输出被重复。 |
| streamIdleTimeoutMs | 正整数 | 300000 | 读取单个响应流的最大空闲间隔。 |
| timeoutMs / websocketConnectTimeoutMs | 正整数 | — | 可选的请求级超时。 |
| retryPolicy | 重试策略对象 | 内置 | 请求重试行为。 |
| credentialRef | 凭据引用 | OPENAI_CODEX_OAUTH | 保存 OAuth 状态的 Harness 凭据槽。 |
| ipv6CallbackBridge | 布尔 | true | 为 IPv6 主机转发 OAuth 回环回调。 |
| proactiveRefresh | 布尔 | true | 在过期前主动刷新令牌。 |
| proxyMode | auto \| environment \| off | auto | 重启后生效；也可在设置页修改。 |

Conversation UI（profile patch ID：conversation-ui）

| 选项 | 取值 | 默认 | 说明 |
| mode | typewriter \| teleprompter | typewriter | 部署默认揭示风格；也可在设置卡中实时修改。 |
| preset | realtime \| balanced \| silky | balanced | 部署默认平滑节奏；也可在设置卡中实时修改。 |
| revealCharsPerSec | 5–200 | 80 | 打字机揭示速度；也可在设置卡中实时修改。 |
| scrollSpeedPxPerSec | 1–200 | 48 | 已弃用的兼容字段；滚动由 DSH 管理。 |
| maxScrollSpeedPxPerSec | 1–2000 | 1000 | 已弃用的兼容字段；滚动由 DSH 管理。 |

若想临时禁用 Conversation UI 而不卸载，应用包内自带的 conversation-ui-off.yml overlay：

- id: conversation-ui
disabled: true

设置入口

| 位置 | 可控内容 |
| 插件 → DSH Codex Suite → codex-provider | 连接/断开账号、登录方式、用量面板、重置次数查看与兑换、代理模式。 |
| 插件 → DSH Codex Suite（或 Conversation UI） | 揭示模式、平滑预设、揭示速度、自动展开思考（均实时生效）、插件版本、npm 安装一键更新。 |

架构

每个运行时插件都由两半组成：

- Host 半（Node）—— Cordis 插件：Provider 注册、OAuth 生命周期、网络与设置持久化，从包根加载。
- Web 半（浏览器）—— 通过 dsh.client manifest 发现的 React 视图。Codex Provider 提供设置分区；Conversation UI 替换助手节点视图并包装工具行。

两半之间只通过两条窄通道通信：注入到 HTML 的启动配置全局变量（window.__DSH_CONVERSATION_UI_CONFIG__）把校验后的插件配置带给浏览器；经鉴权的 Connection RPC 把设置读写带回 Host。机密信息（令牌、代理地址）绝不跨越 RPC 边界。

各包详细文档：codex-provider · conversation-ui · suite

DSH 0.2.1-rc.2 兼容

Provider 使用与 DSH 适配器一致的 pi-ai 1.3.0。Conversation UI 将运行状态和滚动交给 DSH 0.2，已结束的 Turn 使用其本地化时长单位，并正确显示停止和失败状态。Provider、Conversation UI、Suite 已与 Models、Logistics 插件一起在隔离的 DSH 0.2.1-rc.2 Web profile 中启动，三个插件设置页均可呈现，浏览器控制台无错误。替换旧版插件后重启 DSH。

DSH 0.1.7-rc.2 启动兼容

使用 DSH 0.1.7-rc.2 时，将 Suite 升级到 0.1.7-rc.2。Suite 0.1.7-rc.1 会在宿主旁安装旧版 dsh-settings；新版宿主会禁用这个不兼容的副本，导致 Codex Provider 一直等待设置服务。新版 Suite 改用宿主提供的设置服务。更新插件后重启 DSH。

升级到 DSH 0.1.7-rc.1

首次启动每个 profile 时，插件会从 $DSH_HOME/settings.yaml（不存在时读取 settings.yaml.imported）导入旧的 openai-codex.proxyMode 和 conversation-ui.thinkAutoExpand，保存到当前 profile 的 cordis.patch.yml。插件兼容导入只补齐 profile 中缺失的值；成功后写入 .plugin-settings-migrations/ 标记，避免重启后恢复已重置的值。导入失败保留源文件，并在下次启动重试。DSH 自带导入会把旧文件改名为 .imported，升级前请备份整个 DSH_HOME。

Codex 账号继续读取原凭据存储的 OPENAI_CODEX_OAUTH，不重新登录、不搬动或删除凭据。会话和附件由 DSH 管理，本插件不重写。保持原 DSH_HOME 即可保留这些数据。账号与代理设置位于插件的 codex-provider 组件页；对话偏好位于 Suite 或独立 Conversation UI 的插件配置页。

开发

要求：Node.js ^22.19.0 || >=24.0.0，pnpm 11.7。

pnpm install
pnpm run check # typecheck + test + build + pack dry-run，与 CI 一致

单包命令：

pnpm --filter @jcy2387/dsh-codex-provider check # typecheck + test + build + publint
pnpm --filter @jcy2387/dsh-conversation-ui typecheck
pnpm --filter @jcy2387/dsh-conversation-ui test
pnpm --filter @jcy2387/dsh-conversation-ui build
pnpm --dir packages/all pack --dry-run

测试基于 vitest，共 17 个套件，覆盖 OAuth 状态机、令牌刷新、网络/代理探测、用量与重置次数解析、设置控制器和流式客户端视图。客户端测试直接解析已安装的 DSH 发布包（用一个小型 module-table 替身实例化其浏览器 factory bundle）。CI 会校验发布 tag 与三个包版本一致、审计发布 tarball 的内容，并跑一个消费方冒烟测试：把打包出的 tarball 装进一个全新工程（用真实 registry 解析已发布的 peer 依赖区间），再导入全部 Node 侧入口。

发布

发布由 Release 工作流（.github/workflows/release.yml）自动完成：只要发布一个 GitHub Release 就会触发。它要求 release tag 与三个包的共同版本一致（允许可选的 v 前缀），重跑全部质量门禁，打包三个 tarball，校验 suite 组合包不再携带 workspace: 区间，然后按依赖顺序（provider → conversation-ui → suite）发布到 npm，自带 provenance 溯源，采用 OIDC Trusted Publishing 认证 —— 不需要任何长期有效的 NPM_TOKEN secret。

一次性配置：在 npmjs.com 上为 @jcy2387/dsh-codex-provider、@jcy2387/dsh-conversation-ui、@jcy2387/dsh-suite 分别配置 Trusted Publishing，授权仓库 DamonBao/dsh-codex-suite、工作流 release.yml（environment 留空）。

dist-tag 跟随 GitHub Release 的 pre-release 勾选：正式 Release（不勾 pre-release）一律发 latest（包括 rc 版本）；勾了 pre-release 则按版本通道打 tag（0.1.2-alpha.4 → alpha，0.1.2-rc.1 → rc）。工作流具备幂等性 —— 某个包的版本若已存在于 npm 则跳过，因此部分失败后重跑只会补发缺失的包。

一次典型的发布：

先在三个 packages/*/package.json 里统一升版本号，然后：
pnpm run check
VERSION="$(node -p "require('./packages/codex-provider/package.json').version")"
git commit -am "release: $VERSION"
git tag "$VERSION"
git push origin main --tags

随后为该 tag 创建并发布一个 GitHub Release 即可。Dependabot 每周检查 GitHub Actions 依赖。刻意未启用 Dependabot 的 npm 依赖更新：它重新生成 pnpm-lock.yaml 时不带 workspace overrides，PR 无法通过 pnpm install --frozen-lockfile —— 依赖升级请用 pnpm update 手动处理。

仓库结构

.
├─ packages/
│ ├─ codex-provider/ # @jcy2387/dsh-codex-provider
│ │ ├─ src/ # Host 半：OAuth、刷新、网络、用量、重置次数、LLM 适配器 │ │ ├─ src/client/ # Web 半：设置分区 UI │ │ ├─ tests/ # 12 个 vitest 套件 │ │ └─ cordis.patch.yml │ ├─ conversation-ui/ # @jcy2387/dsh-conversation-ui │ │ ├─ src/ # Host 半：配置桥、设置 RPC │ │ ├─ src/client/ # Web 半：流式视图、卡片、原生滚动桥接 │ │ ├─ tests/ # 3 个 vitest 套件 │ │ └─ cordis.patch.yml │ └─ all/ # @jcy2387/dsh-suite（纯组合包，无运行时代码） ├─ .github/workflows/ci.yml # 校验 + tarball 审计 + 消费方冒烟 ├─ .github/workflows/release.yml # GitHub Release 触发 npm 发布 ├─ pnpm-workspace.yaml └─ README.md / README.zh.md

故障排查

- 浏览器登录迟迟不完成 —— 回调桥监听 127.0.0.1:1455；请确认端口空闲且浏览器可达回环地址。设置页会给出具体失败类别（端口冲突、超时、state 不匹配……）。
- 区域不受支持 —— OpenAI 拒绝受限区域登录；设置页会以独立原因提示。可通过代理模式（proxyMode）改变出口线路（需重启生效）。
- 一段时间后提示「需要重新连接」 —— 刷新令牌已过期或被吊销（如改密）。在设置页重新连接一次即可。

许可证

MIT © jcy2387