内容
# 代码桥
代码桥是一个用于代理工作台的本地控制桥。它使用有文档记录的代码接口来启动、控制、观察和协调工作，而不将结构化的运行时控制视为屏幕自动化。
## 为什么存在
代理编排器需要一种稳定地驱动编码工作台、检查事件和保留工件的方法。UI 自动化可以帮助完成视觉任务，但它是会话控制的脆弱基础。代码桥公开了代码已经提供的结构化接口。
## 核心思想
```text
代理编排器
|
v
代码桥
|
+-- 代码应用服务器 (丰富的会话控制)
+-- 代码执行 (一次性作业)
+-- 代码:// 链接 (打开应用表面)
+-- 代码 MCP 服务器 (工具消费)
```
结构化控制优先。浏览器、桌面或操作系统自动化仅保留给真正需要查看或操作可视表面的工作。
## 代码桥管理的内容
- 代码 CLI 功能检测
- 应用服务器 JSON-RPC 初始化
- 线程和回合生命周期助手
- 账户预检和支持的登录流程
- 事件流捕获到操作员选择的本地文件
- Windows 到 WSL 连接器，带有作用域防火墙和令牌身份验证
- 生成的应用服务器协议模式
## 设计原则
- 优先使用文档化的运行时接口而不是 UI 抓取。
- 默认使用标准输入输出或仅限本地回环的传输。
- 需要身份验证才能使用非本地回环监听器。
- 将凭证和机器特定证据保留在存储库之外。
- 将生成的模式和观察到的行为视为版本化的证据。
- 通过 `PATH`、`CODEX_BIN` 或脚本选项使本地路径可配置。
## 存储库布局
```text
docs/ 架构、路线图和通用连接器指南
evals/ 小型机器可读的评估定义
prompts/ 操作员意图和安全合约与脚本配对
scripts/ 确定性主机设置助手
skills/ 项目本地代理指南
src/ CLI、桥实现和生成的协议模式
notes/ 公共安全笔记约定；本地运行日志被忽略
```
## 当前状态
存储库包含一个可执行的代码功能探测器、应用服务器烟雾路径、账户检查、线程/回合助手、Windows 主机连接器、生成的应用服务器模式快照和第一个 MCP 外观 (`src/mcp-server.mjs`)，为本地代理编排器公开探测、账户和线程/回合控制作为 MCP 工具。更广泛的注册表仍是计划中的工作。
运行语法检查：
```bash
npm run check
```
在 `codex` 位于 `PATH` 时运行功能探测：
```bash
npm run probe
```
或显式选择本地可执行文件：
```bash
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex probe
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex app-server-smoke
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-status
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-login-start
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-login-cancel <login-id>
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex thread-smoke
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex turn-smoke --events /tmp/codex-events.jsonl
```
`account-login-start` 使用代码应用服务器的支持的设备代码流。代码桥不会在代码主目录之间复制凭证文件。
## MCP 外观
`src/mcp-server.mjs` 将代码桥公开为本地代理编排器的标准输入输出 MCP 服务器（例如 Claude Code）：
```bash
npm run mcp
# 或，作为二进制文件安装后：codex-bridge-mcp
```
工具：`codex_bridge_probe`、`codex_bridge_app_server_smoke`、`codex_bridge_account_status`、`codex_bridge_account_login_start`、`codex_bridge_account_login_cancel`、`codex_bridge_start_thread`、`codex_bridge_list_threads`、`codex_bridge_resume_thread` 和 `codex_bridge_send_turn`。回合始终在只读沙盒中运行，并且 `approvalPolicy: never` — 服务器无法执行 shell 命令或写入文件，调用者无法通过工具参数扩大该策略。
默认情况下，MCP 外观启动一个本地标准输入输出应用服务器，保留现有的 Claude Code 工作流程。要附加到单独管理的应用服务器，例如身份验证的 Windows 连接器，请使用以下配置配置 MCP 进程：
```bash
CODEX_APP_SERVER_URL=ws://host:48740
CODEX_APP_SERVER_TOKEN_FILE=/local/path/to/codex-bridge-ws-token.txt
```
令牌也可以通过 `CODEX_APP_SERVER_TOKEN` 提供，但首选本地令牌文件。非本地回环 WebSocket 连接需要这两个凭证源之一。永远不要将令牌放入存储库配置中。
## Windows 主机连接器
参见 [`docs/WINDOWS_CODEX_CONNECTOR.md`](docs/WINDOWS_CODEX_CONNECTOR.md)。 PowerShell 助手启动一个身份验证的应用服务器监听器，并将其防火墙规则限定为明确提供或自动检测的 WSL 地址。
## 公共/私有模型
该存储库包含通用代码、文档、生成的模式和综合示例。私有下游存储库或本地控制平面应保留部署值、真实主机名和地址、操作运行日志、诊断记录、凭证引用和环境特定配置。
永远不要在此提交令牌、账户状态、私有事件日志或机器特定证明工件。
