Codex-Reasonix Bridge MCP Runtime

桌面化 MCP Runtime，连接 Codex Desktop → Reasonix。 双击启动，STDIO 模式，不需要网络权限。

快速开始（非技术用户）

1. 双击 start_bridge.cmd（或 python run.py）
2. 看到提示 "MCP Runtime started (transport=stdio)"
3. 打开 Codex Desktop → Settings → MCP
4. 添加自定义 MCP Server（或使用 GUI "自动配置 Codex"）：
   名称：codex-reasonix-bridge
   类型：STDIO
   命令：python
   参数：E:\codex-reasonix-bridge\mcp-runtime\run.py
   工作目录：E:\codex-reasonix-bridge\mcp-runtime
5. 保存并重启 Codex Desktop
6. 在 Codex 中输入任务 -> Bridge 自动调用 Reasonix -> 返回结果

或使用 桌面 GUI 启动器（推荐）：

双击 start_bridge.cmd → 自动打开图形界面
  → 点击"启动向导"完成首次配置
  → 点击"自动配置 Codex"一键连接
  → 点击"启动服务"运行 Bridge

GUI 启动器功能

按钮	功能
启动服务	启动 HTTP MCP Server
停止服务	停止 HTTP MCP Server
刷新状态	刷新 Codex/Reasonix 检测状态
自动配置 Codex	备份原配置 → 写入 Bridge MCP 配置 → 支持撤销
启动向导	5 步引导：依赖检查 → Codex → Reasonix → Prompt → 启动
打开日志	打开 state/ 日志目录

状态面板显示：

• Bridge：运行中 / 已停止 / 错误
• MCP 地址
• Codex：已安装 / 未检测到 / MCP 已配置
• Reasonix：可用 / 不可用（含路径和版本）

安装

# Python >= 3.11
pip install fastapi uvicorn    # HTTP 模式需要

启动方式

# HTTP 模式（默认，桌面化使用）
python run.py

# 桌面 GUI 启动器
python run.py --gui

# 双击快捷方式
start_bridge.cmd

# 指定端口
python run.py --port 8765

# stdio 模式（高级）
python run.py --stdio

# 运行示例
python run.py --example

MCP 传输: STDIO (stdin/stdout，默认) 调试模式: python run.py --http --port 8765（HTTP）

真实工作流

Codex Desktop
  → generate_spec / plan_task
  → 返回 Specification
  → Bridge 校验 Schema 并保存
  → execute_task
  → Bridge 调用 Reasonix
  → Reasonix 修改仓库并验证
  → Bridge 校验 ExecutionResult 并保存
  → 返回 Codex Desktop

注意：plan_task 和 run_once 保留用于 Mock 测试；真实 Codex Desktop 主链路使用 execute_task。

真实 Codex Desktop 接入步骤（图形化）

1. 打开 Codex Desktop
2. 打开 Settings → MCP
3. 点击 "Add Custom MCP Server"
4. 名称填写 codex-reasonix-bridge
5. 地址填写 http://127.0.0.1:8765/mcp
6. 保存
7. 确认可以看到 plan_task、execute_task、run_once、get_state 等工具

如果 Codex Desktop 当前版本要求通过配置文件添加，请使用 GUI 的"自动配置 Codex"按钮。

Reasonix 接入方式

Bridge 自动检测本机 Reasonix。检测优先级：

1. Reasonix CLI（reasonix.cmd，npm 全局安装）
2. 自定义路径（%LOCALAPPDATA%\reasonix\ 等）
3. npm 全局包目录

检测结果在 GUI 状态面板中显示。

配置 config/agents.json：

• "adapter": "mock" — 默认，无需 Reasonix，用于测试
• "adapter": "cli" — 使用真实 Reasonix CLI

{
  "reasonix": {
    "adapter": "cli",
    "command": "reasonix.cmd",
    "timeout_seconds": 1800
  }
}

Prompt 文件

文件	用途
prompts/codex_planner.txt	Mock 模式或独立 Planner Adapter 使用
prompts/reasonix_executor.txt	每次 Reasonix 执行时加载
AGENTS.md	Codex Desktop 项目级职责描述
CLAUDE.md	不参与运行时调用

配置文件

config/agents.json:

{
  "codex": { "adapter": "mock", "command": "codex.cmd", ... },
  "reasonix": { "adapter": "mock", "command": "reasonix.cmd", ... },
  "bridge": { "http_host": "127.0.0.1", "http_port": 8765, "log_level": "INFO" }
}

敏感配置通过环境变量设置，不会明文显示。

安全说明

• 默认只监听 127.0.0.1，不暴露到局域网
• 端口占用时显示明确错误
• 危险命令（rm -rf, git push 等）被拦截
• 所有子进程设置超时
• 运行前后记录 git status / git diff
• 不自动 commit / push / 删除文件
• Scope 越界修改标记为 partial 或 failed
• 日志中 API Key、Token、Secret 已脱敏

项目结构

codex-reasonix-bridge/
├── start_bridge.cmd          # 双击启动
├── run.py                    # 入口（默认 HTTP 8765）
├── config/agents.json        # 配置
├── prompts/                  # Prompt 文件
├── state/                    # 状态存储（自动创建）
├── src/
│   ├── desktop_launcher.py   # GUI 桌面启动器
│   ├── server.py             # MCP Server（HTTP + stdio）
│   ├── bridge.py             # 桥接协调器
│   ├── config_manager.py     # 配置管理
│   ├── reasonix_detector.py  # Reasonix 自动检测
│   ├── codex_integration.py  # Codex MCP 自动配置
│   ├── dispatcher.py         # MCP 请求分发
│   ├── safety.py             # 安全控制
│   ├── schema_validator.py   # Schema 校验
│   ├── state_store.py        # 状态存储
│   └── adapters/             # Adapter 层
└── tests/                    # 105 个测试

测试

# 运行全部 105 个测试
python tests/test_models.py
python tests/test_routes.py
python tests/test_tools.py
python tests/test_integration.py
python tests/test_bridge.py
python tests/test_safety.py
python tests/test_state_store.py
python tests/test_adapters.py
python tests/test_acceptance.py
python tests/test_desktop.py

当前仍需要用户手动完成的操作

1. 安装依赖：首次使用需 pip install fastapi uvicorn
2. 配置 Codex Desktop MCP：可手动或使用 GUI 一键完成
3. 切换真实 Reasonix：将 config/agents.json 中 adapter 从 "mock" 改为 "cli"
4. 重启 Codex Desktop：MCP 配置生效需要重启