# Codex Capability Bridge

**简体中文** | [English](./README.en.md)

[![CI](https://github.com/AEcru/codex-capability-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/AEcru/codex-capability-bridge/actions/workflows/ci.yml)
[![License: Apache--2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![Zero Dependencies](https://img.shields.io/badge/runtime%20deps-0-success)](./package.json)

让 Claude Code 或 Claude Desktop 自动发现并选择本机 Codex 的 Skills、已启用插件能力，并通过 Codex MCP 完成任务。

## 让 Claude 自己安装

在 Claude Desktop Cowork 中挂载本项目目录，然后直接发送：

```text
请读取本项目 README.md 和 docs/AI_INSTALL_PROMPT.md，按照“AI 自主安装提示词”的流程自主完成 Claude Desktop 接入。允许 Codex 操作的目录是本仓库父目录。不要只给建议，直接执行、验证并汇报；不要运行会产生模型用量的真实 ImageGen 验收。
```

完整提示词、权限规则和故障处理见 [AI 自主安装提示词](./docs/AI_INSTALL_PROMPT.md)。

安装完成后，可以直接在 Claude Code 中说：

```text
使用 codex 的 imagegen 插件生成一张猫咪的图片
```

或者不指定能力：

```text
使用 codex 的插件生成一张猫咪的图片
```

Claude Code 会搜索 Codex 能力目录、选择 `imagegen`、检查运行时状态，再把完整任务委派给 Codex。

## 一条命令安装

前置条件：Node.js 20+、Claude Code、Codex CLI 或 Codex Desktop。

Claude Desktop：

```bash
npm run setup:desktop -- --project-dir "<允许 Codex 操作的项目目录>"
```

Claude Code：

```bash
npm run setup
```

如果安装器提示 Claude Code 尚未认证，请在真实验收前执行 `claude auth login`。插件安装和离线校验不要求 Claude API 登录，但 Claude 自己处理自然语言任务时必须已认证。

安装完成后重启 Claude Code。默认安装到 Claude Code 的 `user` 作用域；团队项目可使用：

```bash
npm run setup -- --scope project
```

Windows 也可以执行：

```powershell
.\setup.ps1
```

macOS/Linux 也可以执行：

```bash
sh ./setup.sh
```

## 它解决什么问题

Codex 的 Skills、插件和宿主工具不属于同一层能力：

- 独立 Skills 位于 `$CODEX_HOME/skills` 或 `~/.agents/skills`。
- 已安装插件有启用状态，不能把缓存目录中的所有内容都当作可用插件。
- `imagegen` 等系统 Skill 可以被发现，但其默认 `image_gen` 工具由 Codex 宿主管理。
- `codex mcp-server` 对外提供 `codex` 与 `codex-reply`，可以启动和继续 Codex 任务。

本项目把这些差异封装在一个 Claude Code 插件中，不要求 Claude 自己理解 Codex 的目录结构。

## 架构

![架构总览](./docs/images/architecture.svg)

> 本文档中的架构图与流程图均由 [lhr-fireworks-tech-graph](https://github.com/AEcru/lhr-fireworks-tech-graph) 技能生成——一个面向 Claude Code 的企业级 SVG 技术图生成器。想为自己的项目生成同风格插图，推荐使用它。

用户的自然语言任务经 Claude Code 的 Skill 路由进入桥接层;桥接层一边从四个来源合并能力目录并甄别启用状态,一边通过 `codex mcp-server` 把任务真实委派给 Codex Agent;产物落盘后经存在性与文件签名双重校验,绝对路径回传 Claude。

插件向 Claude Code 暴露 5 个稳定工具：

- `search_codex_capabilities`：按用户任务搜索和排序能力。
- `describe_codex_capability`：检查来源、启用状态和执行模式。
- `run_codex_capability`：启动 Codex 任务。
- `continue_codex_task`：使用 `threadId` 继续任务。
- `codex_bridge_doctor`：诊断 CLI、MCP 与 ImageGen 委派链路。

## 委派全流程

一次「用 codex 的插件生成图片」从进入到返回,完整经过搜索排序、可执行性检查、安全闸、真实执行与产物校验五道关:

![任务委派全流程](./docs/images/delegation-flow.svg)

任何一道关失败都不会被掩盖:不可执行走 doctor 诊断并如实报告,产物未通过校验不会声称成功。

## AI 自我修复(Actionable Errors)

桥接器的所有失败路径都内嵌**可执行的恢复步骤**——错误文本直接告诉调用方模型"先用哪个工具确认什么、然后怎么重试",并按 MCP 规范以 `isError: true` 结果返回(而非 JSON-RPC 协议错),保证模型能完整读到指引并自我纠正:

![AI 自我修复回路](./docs/images/self-repair-loop.svg)

覆盖的失败模式与恢复动作(完整决策表见 [SKILL.md](./plugins/codex-capability-bridge/skills/lhr-use-codex-capabilities/SKILL.md)):

| 失败 | 错误内嵌的恢复指引 |
| --- | --- |
| 能力 id 不存在 | 附 `Did you mean: <相近候选>`,或引导调用 search 列出真实 id |
| 能力名歧义 | 列出全部同名完整 id 供选择 |
| 可发现但不可执行 | 区分「插件未启用」与「后端缺失」,分别给出动作 |
| Codex CLI 未找到 / 工具缺失 | 引导 doctor 查探测报告,提示 `CODEX_CLI_PATH` 修复 |
| 工作目录越界 | 列出允许的根目录,提示改用项目内路径或 `CODEX_BRIDGE_ALLOWED_ROOTS` |
| 委派任务超时 | 建议缩小任务或调高 `CODEX_BRIDGE_TIMEOUT_MS` |

自修复最多两轮,之后如实向用户报告已尝试与仍缺失的内容——防止无限重试。

## 能力发现顺序

桥接器按以下来源构建目录：

1. `$CODEX_HOME/skills`，包含隐藏的 `.system` Skills。
2. `~/.agents/skills`。
3. `$CODEX_HOME/plugins/cache` 中的插件 Skills。
4. `codex plugin list --json` 返回的启用状态。

缓存中存在不代表已启用。桥接器会保留来源和状态，Claude 应优先选择可执行结果。

## ImageGen 的准确边界

`imagegen` 是 Codex 系统 Skill，不是普通的可移植插件。它默认要求 Codex 宿主提供内置 `image_gen` 工具。桥接器会：

1. 自动发现 `imagegen` Skill。
2. 通过 Codex MCP 启动一个真实 Codex 任务。
3. 明确要求 Codex 使用内置 `image_gen`。
4. 要求产物写入当前工作目录并返回绝对路径。
5. 如果宿主没有提供图像工具，返回真实边界，不会偷偷切换到其他图片供应商。

因此 `npm run doctor` 能确认“目录与委派链路已就绪”，最终图像工具可用性在真实任务调用时由 Codex 宿主确认。

## 验收

### 1. 离线协议验收

```bash
npm test
npm run smoke
```

覆盖能力发现、中文意图排序、MCP 协议、Codex 线程续聊、图像内容落盘和安装幂等性。

### 2. 环境诊断

```bash
npm run doctor
```

健康输出应包含：

```text
Codex CLI: OK
Codex MCP: OK (codex, codex-reply)
ImageGen: DISCOVERED; delegation backend=true; host verification=unknown
```

`unknown` 是有意设计：doctor 不会把“Codex MCP 能启动”冒充“宿主一定注入了 image_gen”。真实任务返回后，桥接器会对工作区内图片做文件存在性和 PNG/JPEG/WebP/GIF 文件签名校验。

### 3. 一键真实 ImageGen 验收

```bash
npm run acceptance:imagegen
```

该命令会让 Codex 真实调用内置 ImageGen，并要求生成 `output/codex-bridge-cat.png`。只有目标文件存在、位于工作区内且图片签名有效时才成功。此步骤可能产生模型用量。

### 4. Claude Code 真实验收

重启 Claude Code，在任意可写测试项目中发送：

```text
使用 codex 的 imagegen 插件生成一张猫咪的图片，并保存到当前项目的 output/cat.png
```

然后发送不指定能力的版本：

```text
使用 codex 的插件生成一张猫咪的图片，并保存到当前项目的 output/cat-auto.png
```

预期行为：Claude 调用搜索工具，选择 `imagegen`，调用运行工具，最后报告 Codex 返回的文件路径。不得只回复一段图片描述。

开发时无需正式安装，可以运行：

```bash
claude --plugin-dir ./plugins/codex-capability-bridge
```

## 配置

通常不需要配置。可选环境变量：

| 变量 | 用途 |
| --- | --- |
| `CODEX_HOME` | 覆盖 Codex 主目录，默认 `~/.codex` |
| `CODEX_CLI_PATH` | 指定可执行的 Codex CLI |
| `CODEX_BRIDGE_CODEX_COMMAND` | 最高优先级指定 Codex 命令 |
| `CODEX_BRIDGE_CODEX_ARGS_JSON` | 自定义 Codex 命令的 JSON 字符串数组前置参数 |
| `CODEX_BRIDGE_PROJECT_DIR` | 覆盖默认工作目录 |
| `CODEX_BRIDGE_ALLOWED_ROOTS` | 额外允许的工作目录根路径，多个路径使用系统 PATH 分隔符 |
| `CODEX_BRIDGE_TIMEOUT_MS` | Codex 任务超时，默认 300000 毫秒 |
| `CODEX_BRIDGE_ALLOW_UNSAFE` | 仅显式设为 `1` 时允许 `never` 或 `danger-full-access` |
| `CODEX_BRIDGE_DISABLE_NPX` | 设为 `1` 时禁用官方 npm Codex CLI 后备解析 |

Windows 下桥接器会验证候选 CLI 是否真的可以执行，并避开可能返回 `Access denied` 的 WindowsApps 路径。

## 安全策略

- 默认使用 `on-request` 审批和 `workspace-write` 沙箱。
- 默认只允许当前 Claude 项目目录及其子目录。
- 不自动安装 Codex 插件，不自动登录，不修改 Codex 配置。
- 不自动使用 `danger-full-access` 或跳过权限检查。
- 不把 API Key 写入配置、命令参数或日志。
- 只把嵌套返回的图像内容写入工作目录下的 `.codex-bridge-output`。
- ImageGen 内置工具不可用时，不静默降级到需要 `OPENAI_API_KEY` 的 CLI 模式。

## 卸载

Claude Desktop：

```bash
npm run uninstall:desktop
```

Claude Code：

```bash
npm run uninstall
```

指定安装作用域：

```bash
npm run uninstall -- --scope project
```

卸载脚本只卸载本插件及其 marketplace 声明，不删除用户凭据、Codex 配置或其他插件。

## 开发与发布

```bash
npm test
npm run check
```

项目运行时仅使用 Node.js 内置模块，没有生产依赖。Claude marketplace 会把插件目录复制到本地缓存，因此服务器、Skill 和配置全部位于 `plugins/codex-capability-bridge` 内，不依赖仓库外部文件。

发布新版本时同时更新：

- `package.json`
- `.claude-plugin/marketplace.json`
- `plugins/codex-capability-bridge/.claude-plugin/plugin.json`
- `plugins/codex-capability-bridge/server/index.mjs` 中的服务器版本
- `CHANGELOG.md`

## 故障排查

先运行：

```bash
npm run doctor
```

如果提示找不到 Codex CLI，设置 `CODEX_CLI_PATH` 指向可执行文件。桥接器也可以使用官方 npm 包 `@openai/codex` 作为最后后备；可通过 `CODEX_BRIDGE_DISABLE_NPX=1` 禁止该网络后备。Windows Codex Desktop 常见可执行候选包括用户目录下的 Codex app-server CLI；不要硬编码包含版本哈希的路径。

如果 Claude 看不到工具：

1. 运行 `claude plugin list --json` 确认插件已启用。
2. 重启 Claude Code，或在开发会话执行 `/reload-plugins`。
3. 运行 `claude plugin validate --strict .`。
4. 查看 Claude Code 的 `/mcp` 状态。

如果 ImageGen 被发现但真实任务失败，说明当前 Codex 委派会话没有获得内置图像工具。桥接器会保留错误原文；不要把目录发现成功误判为图像生成成功。

## 许可证

Apache-2.0。你可以使用、修改、商用及再发布本项目；分发原项目或衍生作品时，必须保留 [LICENSE](./LICENSE) 与 [NOTICE](./NOTICE) 中的原始版权和署名声明，并在修改过的文件中说明修改。参见 [LICENSE](./LICENSE)。