Codex IO Bridge

Codex IO Bridge 为 VS Code 扩展提供一套共享的 Codex 会话接口：读取会话与本地历史、发送输入、接收事件，以及管理桥接状态。它是供其他扩展使用的本机基础层；安装后不会自动连接飞书，也不会自动发送消息。

Codex IO Bridge provides a shared Codex session API for VS Code extensions: read conversations and local history, send input, receive events, and manage bridge health. It is a local integration layer for other extensions. Installing it does not connect to Feishu or send messages automatically.

What it connects / 它连接什么

Bridge 在当前 VS Code 窗口中运行，通过经用户明确安装的桥接文件与官方 OpenAI Codex 扩展通信。Remote 等扩展调用公开 API；Bridge 复用官方 Codex 的连接，不创建自己的模型服务或飞书连接。

Bridge runs in the current VS Code window and communicates with the official OpenAI Codex extension through bridge files installed at the user's request. Extensions such as Remote call its public API. Bridge reuses Codex's connection; it does not run a separate model service or connect to Feishu.

Consumer extensions                 IO Bridge (local API v1)                  Official Codex
-------------------                 ------------------------                  --------------
Codex Remote ---------+----------> Control panel + compatibility --------> Codex host
Codex Voice  ----------+            Session API + request protection        Renderer + app-server
Other consumers -------+            Events + JSONL history observer  <----> Local CODEX_HOME
                                   Patch install / update / restore         Session state + JSONL

左侧是接入方，中间是 Bridge 的控制、健康检查、请求防重、事件及历史模块，右侧是官方 Codex 与本地会话数据。补丁只由 Bridge 管理，依赖扩展不应分别修改官方文件。

The left side shows consumers; the center shows Bridge's controls, health checks, replay protection, events, and history modules; the right side shows official Codex and local session data. Bridge alone manages the patch. Consumer extensions should not modify Codex files independently.

Message relay / 消息中转链路

使用 Codex Remote 接入飞书时，飞书机器人和群聊由 Remote 配置及维护。Remote 将群消息映射到 Codex 会话，经 Bridge 提交给官方 Codex；回复、状态和历史再经 Bridge 返回 Remote，由 Remote 负责转发到飞书。Voice 等其他接入方使用同一 Bridge API，但各自负责自己的输入输出体验。

When Codex Remote connects Feishu, Remote owns the bot configuration and chats. Remote maps a chat message to a Codex conversation and submits it through Bridge to official Codex. Replies, state, and history return through Bridge, while Remote delivers them to Feishu. Other consumers, including Voice, use the same Bridge API and own their respective user experiences.

Input / 输入
[Feishu chat] -> [Remote: bot + chat routing] -> [Bridge: API + replay guard]
                                                   -> [Official Codex: native turn] -> [Model]

Result / 回复
[Model] -> [Official Codex: events + local JSONL] -> [Bridge: event + history]
        -> [Remote: deduplicate + deliver] -> [Feishu chat]

实时事件与本地 JSONL 历史共同支持状态更新和缺失消息补齐；sendMessage 的接受回执只表示 Codex 已接受输入，不表示模型已经回复。飞书网络、机器人权限和转发策略均不属于 Bridge 的配置。

Live events and local JSONL history support status updates and recovery of missed messages. An accepted sendMessage receipt means Codex accepted the input; it does not mean the model has replied. Feishu networking, bot permissions, and forwarding policy are configured outside Bridge.

Install and use / 安装与使用

本扩展需要 VS Code 1.96.2 或更新版本、受信任的本机桌面工作区，以及已经安装并登录的官方 openai.chatgpt Codex 扩展。Bridge 复用该扩展的 app-server 连接；自身不需要填写令牌或服务地址。Codex CLI 和 ChatGPT Desktop 采用独立的接入产品，不由本扩展适配。

This extension requires VS Code 1.96.2 or later, a trusted local desktop workspace, and the installed, signed-in official openai.chatgpt Codex extension. Bridge reuses that extension's app-server connection and requires no token or server address of its own. Codex CLI and ChatGPT Desktop use separate connectors.

安装官方 Codex 和 Codex IO Bridge，打开活动栏中的 Codex IO Bridge。

Install official Codex and Codex IO Bridge, then open Codex IO Bridge in the Activity Bar.
查看“代码兼容”“补丁文件”“当前窗口”三项状态，点击 安装会话桥接。

Inspect code compatibility, patch files, and current-window status, then select 安装会话桥接 (Install session bridge).
安装或更新补丁后，等正在运行的 Codex 任务结束再重载相关窗口。

After installing or updating the patch, wait for running Codex tasks to finish before reloading the relevant windows.
面板显示 会话桥接已就绪 后，再在 Remote 或适配版 Voice 中设置相应功能。

Once the panel shows 会话桥接已就绪 (Session bridge ready), configure Remote or a compatible Voice extension for its own features.

安装扩展不会自动修改官方 Codex 文件；只有明确点击安装或更新时才会备份并修改所需文件。更新官方 Codex 后，返回本面板检查兼容性、补丁状态和重载提示。检查基于实际代码结构；已验证构建列表不是版本允许名单。Remote SSH、Dev Container、浏览器版 VS Code 和自定义 Codex CLI 不在当前支持范围内。

Installing the extension does not change official Codex files automatically. Bridge backs up and modifies the required files only after an explicit install or update action. After updating official Codex, return to the panel to inspect compatibility, patch status, and reload guidance. Compatibility is checked against actual code structure; the verified-build list is not a version allowlist. Remote SSH, Dev Containers, browser-based VS Code, and custom Codex CLI installations are outside the current support scope.

Bridge 0.12.4（补丁 1.17.3）增加对 Codex 26.928.40906 的适配。旧版已验证适配继续保留；后续版本仍按实际入口与依赖结构检查兼容性。

Bridge 0.12.4 (patch 1.17.3) adds an adapter for Codex 26.928.40906. Previously verified adapters remain available; future versions are still checked against their actual integration points and dependencies.

Complete capability list / 完整能力清单

下表覆盖当前公开的全部 24 个能力标识。接入方应读取 getHealth().capabilities，按能力启用功能，而不要从扩展版本号推断功能可用。

The table covers all 24 public capability identifiers. Consumers should inspect getHealth().capabilities and enable features by capability, instead of inferring availability from an extension version.

模块 / Module	能力标识 / Capability IDs	功能 / Function
状态与可靠性 / Health and reliability	`health`, `request-replay-protection`	只读就绪状态、结构化错误、持久请求防重 / Read-only readiness, structured errors, durable replay protection
会话管理 / Conversations	`thread-list`, `thread-summary`, `thread-create`, `thread-runtime`, `thread-models`, `thread-name`	列表与按 ID 查询、创建、运行状态、模型与名称 / List and look up by ID, create, inspect runtime, set model and name
历史与资源 / History and files	`thread-history`, `history-images`, `history-files`	本地可见历史、图片及受限文件读取 / Local visible history, images, and scoped file reads
输入与控制 / Input and controls	`background-input`, `input-images`, `native-queue`, `turn-steering`, `interrupt`	后台输入、图片、VS Code 原生排队、调整方向、中断 / Background input, images, native VS Code queue, steering, interrupt
用户交互 / User interaction	`interactions`, `async-question-replies`, `pending-questions`	审批、异步问题回答及待答状态 / Approvals, asynchronous answers, live pending-question state
事件与观察 / Events and observation	`thread-events`, `owned-thread-observation`	多播事件、可释放的独立会话观察 / Multicast events and independently disposable observations
输入框与语音适配 / Composer and voice integration	`draft-input`, `continuous-input`, `recording-controls`	草稿插入、提交与录音控件协议 / Draft insertion, submission, and recording-control protocol

Public API / 公开接口

公开 API 为 v1，完整类型见随扩展提供的 api/index.d.ts。每个 VS Code 扩展宿主有自己的 API 实例；backendId + threadId 标识后端会话，hostEpoch 等运行时身份在窗口重载后应重新取得。

The public API is v1; see the bundled api/index.d.ts for complete types. Each VS Code extension host has its own API instance. backendId + threadId identifies a backend conversation, while runtime identities such as hostEpoch must be reacquired after a window reload.

API	用途 / Purpose
`getHealth`, `getStatus`	读取桥接就绪、兼容及运行状态；`getStatus` 为兼容接口 / Read readiness, compatibility, and runtime; `getStatus` is retained for compatibility
`listThreads`, `getThreadSummary`	分页列出会话、按 ID 读取会话及分支摘要 / Page through conversations or read one conversation/fork by ID
`getThreadRuntime`	读取当前窗口的加载、忙碌和活动回合状态 / Read this window's loaded, busy, and active-turn state
`listModels`, `setThreadModel`	查看可用模型与推理强度、设置后续回合模型 / List available models and reasoning efforts; set a model for later turns
`renameThread`	经 Codex 原生接口修改会话名称 / Rename a conversation through Codex's native interface
`createThread`, `openThread`	创建会话、在官方侧栏打开会话 / Create a conversation or open it in the official sidebar
`subscribeThread`, `observeThread`	观察事件及 JSONL 补偿；后者返回可释放句柄 / Observe events and JSONL recovery; the latter returns a disposable handle
`getHistory`	读取可见用户与助手消息、时间及来源 / Read visible user and assistant messages, timestamps, and sources
`readHistoryImage`, `readHistoryFile`	按历史中的资源 ID 读取图片或可见本地文件 / Read an image or visible local file by its history resource ID
`sendMessage`, `queueMessage`, `steerMessage`	立即提交、显式加入 Codex 可见的原生队列、向指定活动回合调整方向 / Submit immediately, queue in Codex’s visible native queue, or steer an identified active turn
`getPendingQuestions`, `answerQuestion`	只读原生待答状态、回答仍有效的结构化问题 / Read live pending state and answer a still-valid structured question
`interrupt`, `respond`	中断指定回合、响应仍有效的审批或阻塞式问题 / Interrupt a turn or respond to a live approval or blocking question
`getTargets`, `composer`	获取可见输入框、插入或提交草稿并同步录音 UI 状态 / Get visible composers, edit or submit drafts, and sync recording UI state
`onEvent`	订阅可多播的原生通知、完成事件与就绪变化 / Subscribe to multicast native notifications, completion events, and readiness changes

接入扩展通过 VS Code 的 extensions.getExtension('koupualen.codex-io-bridge').activate() 获取 API，并在调用前检查 apiVersion === 1、getHealth().ready 及所需能力。推荐在自己的 package.json 中声明 extensionDependencies: ["koupualen.codex-io-bridge"] 和 extensionKind: ["ui"]。示例的 ./types/codex-io-bridge 是接入方复制 api/index.d.ts 后的本地路径，仅供类型检查；不要通过 Node require() 启动第二份 Bridge。

A consumer obtains the API through VS Code's extensions.getExtension('koupualen.codex-io-bridge').activate(), then checks apiVersion === 1, getHealth().ready, and required capabilities. Declare extensionDependencies: ["koupualen.codex-io-bridge"] and extensionKind: ["ui"] in the consumer's package.json. The example's ./types/codex-io-bridge is a consumer-owned copy of api/index.d.ts for type checking only; do not use Node require() to create a second Bridge instance.

import * as vscode from 'vscode';
import type { CodexIoBridgeApi } from './types/codex-io-bridge';

export async function sendToCodex(threadId: string, text: string, requestId: string) {
  const extension = vscode.extensions.getExtension<CodexIoBridgeApi>('koupualen.codex-io-bridge');
  if (!extension) throw new Error('Codex IO Bridge is not installed');
  const io = await extension.activate();
  if (io.apiVersion !== 1) throw new Error('Incompatible Bridge API');
  const health = await io.getHealth();
  if (!health.ready || !health.capabilities.includes('background-input')) {
    throw new Error(health.error?.message || 'Codex IO Bridge is not ready');
  }
  // Generate and retain requestId for the user action before calling this function.
  const receipt = await io.sendMessage({ threadId, backendId: health.backendId, text, requestId });
  // receipt.state === 'accepted' does not mean the turn has completed.
  return receipt;
}

写入操作须使用稳定的 requestId。RESULT_UNKNOWN 表示操作可能已经执行，应先在原 Codex 会话核对，不能换 ID 自动重发；THREAD_BUSY 等明确未投递错误才可依原请求规则重试。原生排队返回 queued 只表示入队，图片文件应保留到 Codex 实际消费。

Mutations need a stable requestId. RESULT_UNKNOWN means the operation may already have happened: inspect the original Codex conversation before retrying, and do not automatically submit under a new ID. Explicit non-delivery errors such as THREAD_BUSY can be retried according to the request contract. A native queued receipt means enqueued, not executed; retain local image files until Codex consumes them.

Data and safety / 数据与安全

Bridge 在本机读取 Codex 可见会话历史，并可按该会话历史中的 ID 读取图片或普通本地文件；它不提供任意路径读取接口。补丁原文件备份默认位于 ~/.codex-io-bridge/backups/，请求防重记录位于 ~/.codex-io-bridge/request-receipts/，防重记录不保存提示词正文。诊断可能包含本机路径，分享前请自行检查。

Bridge reads locally visible Codex history and can read images or ordinary local files by IDs found in that conversation's history; it does not expose arbitrary-path reads. Original-file backups default to ~/.codex-io-bridge/backups/, and replay-protection records to ~/.codex-io-bridge/request-receipts/; the latter do not store prompt bodies. Diagnostics may contain local paths, so review them before sharing.

维护与诊断 提供查看日志、检查待核对的队列消息，以及二次确认后的 恢复官方 Codex 文件。恢复仅处理 Bridge 能验证归属及哈希的文件；若发现文件冲突会停止覆盖。恢复后需重载相关窗口，依赖 Bridge 的扩展会暂时无法收发，历史不会被删除。

维护与诊断 (Maintenance and diagnostics) offers logs, queue messages requiring review, and 恢复官方 Codex 文件 (Restore official Codex files) behind a confirmation step. Restore only touches files whose ownership and hashes Bridge can verify, and stops on conflicts. Reload affected windows afterward; dependent extensions cannot send or receive until the bridge is reinstalled, but conversation history is retained.

旧版 Voice 若自行管理同一份官方补丁，需先在旧 Voice 中恢复其补丁、停用旧版并重载，再由 IO Bridge 安装共享补丁。legacy-conflict、unsupported、conflict、partial 等状态会在面板中说明下一步；这些状态下接入方应暂停新输入并保留用户内容。

If an older Voice extension manages its own patch of the same official files, restore that patch from the older Voice extension, disable it, and reload before installing the shared IO Bridge patch. The panel explains next steps for legacy-conflict, unsupported, conflict, and partial states. Consumers should pause new input and preserve user content in those states.

Support scope / 支持范围

公开 API 保持 v1。官方 Codex 版本变化后是否可用由代码兼容检查决定；关键结构不匹配时，Bridge 会停止安装并展示失败项。Bridge 是本机 VS Code 扩展间接口，不是独立 HTTP 服务或飞书机器人。

The public API remains v1. After an official Codex update, code compatibility checks determine whether the bridge can be used. Bridge refuses installation and reports failed checks when required structures no longer match. It is a local interface among VS Code extensions, not a standalone HTTP service or Feishu bot.

需要排查时，先打开桥接控制面板查看代码兼容、补丁文件和当前窗口，再使用 维护与诊断 → 查看诊断 / 查看日志。接入扩展的飞书连接、群聊路由和语音设置应在各自扩展中排查。

For troubleshooting, start with code compatibility, patch files, and current-window state in the Bridge control panel, then use Maintenance and diagnostics → Diagnostics / Logs. Investigate Feishu connections, chat routing, and voice settings in the respective consumer extensions.

Installation packages / 安装包

仓库中的各版本 VSIX 安装包统一保存在 release/，由 Git 管理。开发者执行 npm run package 时，脚本先通过 VSCE 的发布前步骤编译，再根据 package.json 中的名称与版本生成 release/codex-io-bridge-<version>.vsix。同版本安装包已存在时会拒绝覆盖，请升级版本号后再打包。release/ 不会被嵌套进安装包。

All versioned VSIX installation packages are kept in release/ and tracked in Git. npm run package compiles through VSCE's prepublish step and writes release/codex-io-bridge-<version>.vsix using the name and version in package.json. Packaging refuses to overwrite an existing version; increase the version before packaging again. The release/ directory is excluded from the VSIX contents.