Codex 渠道兼容插件

为 DSH 的第三方 OpenAI 兼容渠道提供两种互斥方式：

• 直连加头（headers）：直接请求 HTTPS 上游，通过原生 llm-pi-ai/request-headers 钩子添加 originator、x-codex-window-id。
• 本地代理（proxy）：插件管理只监听 127.0.0.1 的代理，向上游添加上述请求头及 User-Agent。

默认使用直连加头，匹配 https://api.tu-zi.com/coding/v1。仅作用于 pi-ai 提供商；其他地址不受影响。

在页面中切换

打开 插件 → Codex 渠道兼容 → 配置，点击「直连加头」或「本地代理」。选择自动保存，运行时生效，无需重启 DSH。页面显示实际生效方式、目标提供商和失败原因。

• 切到代理：读取目标提供商现有的密钥引用，检查密钥可用、代理监听成功后，自动将其 Base URL 改为 http://127.0.0.1:3081/v1。
• 切回直连：将仍使用本插件本地地址的目标提供商恢复到上游 HTTPS 地址，然后关闭代理。
• 「关闭兼容」同样恢复上游地址，并关闭请求头注入和本地代理。
• 密钥引用、API 协议、模型列表及其他配置保持原值。代理在每次请求时重新读取当前引用和密钥，支持轮换。
• 模式请求串行执行；端口占用、密钥缺失或配置冲突会显示错误。通常保留原模式和路由；跨配置回滚也发生冲突时，页面明确提示检查模型设置，并尽可能保留服务本地路由所需的代理。
• 页面选择代表期望模式，「实际生效」代表切换结果。失败后可点「重试所选方式」。期望模式持久保存，重启会重新尝试。

切换影响之后发出的请求。切回直连或停用时，代理中的活动请求会被关闭，建议等当前回复结束后切换。

如更新后还没有配置入口，刷新当前网页以加载 Client 模块。

匹配范围与高级配置

upstreamBaseURL 是完整 HTTPS API 基址；末尾 / 被规范化，不使用域名包含或路径前缀匹配。providerIds 限制两种方式处理的提供商；空数组表示按完整基址匹配。插件也识别同一端口的本地代理地址，以便切回或重启时恢复路由。

以下为用户 profile 的 Cordis 配置覆盖示例，不应修改已安装包的默认补丁：

- id: local-codex-compat
  config:
    mode: headers
    upstreamBaseURL: https://api.tu-zi.com/coding/v1
    providerIds: []
    port: 3081
    # 兼容旧配置；自动切换采用提供商配置的 apiKeyEnv。
    credentialRef: TUZI_CODING_API_KEY
    originator: codex_cli_rs
    userAgent: codex_cli_rs/0.167.0
    windowId: ''
    idleTimeoutMs: 300000

模式为 volatile 配置，通过网页或工具切换时热生效。上游、端口、范围等普通配置修改会重新加载插件。使用代理时修改端口或上游之前，先切回直连，避免旧地址脱离新的匹配范围。

• 目标提供商需先在 DSH 模型设置中配置；上游地址必须匹配。代理模式未找到目标时不会修改其他提供商。新增提供商后重新选择方式以应用。
• 目标提供商必须明确配置 apiKeyEnv，以保证调用者与代理使用同一凭据。未指定引用，或使用不同密钥引用时，代理模式会明确拒绝切换；使用 providerIds 选择使用同一引用的提供商。不会覆盖 API key 或猜测环境凭据。
• 直连加头只覆盖 pi-ai 推理请求，不覆盖模型目录查询。DSH 会继续设置自己的 User-Agent；需要调整 UA 的渠道使用本地代理。
• 正常停用/卸载会异步尝试恢复仍归本插件管理的本地 URL，然后关闭代理。手工改到其他上游的地址不会被覆盖。强制结束进程可能留下本地 URL；再次加载插件会按期望模式重新启动代理或恢复直连。

代理行为

代理仅接受严格的本地 Host，拒绝所有浏览器 Origin，并核对入站 Bearer 与提供商当前密钥。缺失密钥返回 503，不匹配返回 401。固定 HTTPS 上游，固定路由，不跟随重定向。

本地请求	上游基址后缀
GET /v1/models	/models
POST /v1/responses	/responses
POST /v1/responses/compact	/responses/compact
POST /v1/chat/completions	/chat/completions

GET /health 仅说明监听状态，不验证上游或模型可用性。不会在启动/切换时发送推理请求。

• 请求体、工具参数、图片数据、HTTP 状态、JSON 错误及 SSE 字节原样转发；不转换 Chat Completions / Responses，不重试、不补造结束事件。
• 不会修复 Stream ended without finish_reason。 上游截断保持为截断。
• 过滤 hop-by-hop、Cookie、Origin、Referer、Forwarded、X-Forwarded-*，移除上游 Set-Cookie。
• 客户端取消会关闭上游。密钥读取、响应头等待和流空闲有超时；停用关闭监听和活动连接。凭据服务不提供取消接口，插件只取消自身等待。
• 不记录密钥、请求头、请求体或响应体，不读取固定的个人凭据文件。

兼容头用于渠道客户端兼容检查；服务端是否接受取决于其规则。默认 UA 版本来自用户上传代理配置，可以按上游要求修改；不保证真实第三方渠道的接受情况。

Agent 工具

codex_compat 提供 action: status 查看实际状态，或 action: switch 配合 mode: headers | proxy | off 切换。工具与页面使用同一 Host Settings 写入路径和串行控制器，对当前 profile 所有会话生效。返回实际模式、目标提供商和错误原因，不返回密钥。

验证和分发

npm test

测试使用本机服务和测试密钥，覆盖请求头范围、鉴权、密钥轮换、JSON/工具字段、SSE、超时、取消，以及双向模式切换、监听先于切流、配置冲突、重试、串行执行、跨配置回滚、陈旧本地路由恢复和端口释放。不会连接第三方推理渠道。

本版面向 DSH Web profile，需要已启动且可通过回环地址访问的 Web 服务。插件用一次带随机鉴权值的本机请求建立独立任务上下文，随后立即移除临时路由，以避免热更新事务嵌套；这次请求不携带模型凭据或配置内容。

发布包包含带版本号的单文件 Host 入口，避免运行中升级后沿用旧的内部模块。npm test 和 npm pack 会先运行本地 build.mjs；安装已打包的归档无需运行构建脚本。运行时使用 Node 标准库及 DSH Schemastery，Client 由 DSH 加载 React。中英文显示资源及原创 SVG 图标随包分发。源自用户提供的代理 ZIP，已移除其固定个人路径和凭据文件读取逻辑。