claude2codex 0.3.3 → 0.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -3
- package/README.zh-CN.md +109 -54
- package/dist/server.js +47 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -111,6 +111,8 @@ Note that the contract prompt and the **thread-goal objective** are different st
|
|
|
111
111
|
|
|
112
112
|
Requires [Codex CLI](https://github.com/openai/codex) and Node.js 18+.
|
|
113
113
|
|
|
114
|
+
**Model & effort.** c2c uses whatever model and reasoning effort your Codex CLI is configured with (`~/.codex/config.toml`); it has no defaults of its own. Call `codex_config` to see what jobs will run with. To override, set `CODEX_MODEL` in the MCP server's `env` (all jobs) or pass `reasoning_effort` per job.
|
|
115
|
+
|
|
114
116
|
```sh
|
|
115
117
|
npx claude2codex
|
|
116
118
|
```
|
|
@@ -130,9 +132,12 @@ Add to your Claude Code MCP settings:
|
|
|
130
132
|
}
|
|
131
133
|
```
|
|
132
134
|
|
|
133
|
-
### Workflow Prompt
|
|
135
|
+
### Workflow: Instructions + Prompt
|
|
136
|
+
|
|
137
|
+
The workflow reaches Claude in two layers. Neither needs extra installation.
|
|
134
138
|
|
|
135
|
-
|
|
139
|
+
- **Server instructions (automatic).** On connect, the server sends a short instruction block (under 1,000 chars) that Claude Code adds to its system prompt. It activates only when you ask to delegate work to Codex: Claude then drafts a Goal Contract for your approval, estimates, implements, polls, and re-runs verification itself. Tasks you don't delegate are handled as usual.
|
|
140
|
+
- **`c2c-workflow` Prompt (opt-in, full rules).** Goal/Delta Contract formats and the complete review protocol, including falsifiability checks. MCP Prompts are user-invoked: type `/mcp__codex__c2c-workflow` at the start of a delegating session (the middle segment is whatever you named the server in your MCP config).
|
|
136
141
|
|
|
137
142
|
### Project Setup: CLAUDE.md and AGENTS.md
|
|
138
143
|
|
|
@@ -176,7 +181,7 @@ Python 3.12, Poetry. Run from project root.
|
|
|
176
181
|
|
|
177
182
|
**What goes where:**
|
|
178
183
|
|
|
179
|
-
| | MCP server
|
|
184
|
+
| | MCP server | CLAUDE.md | AGENTS.md |
|
|
180
185
|
|---|---|---|---|
|
|
181
186
|
| Role definition | ✓ | — | — |
|
|
182
187
|
| Workflow steps | ✓ | — | — |
|
|
@@ -230,6 +235,30 @@ Codex then enters its goal-continuation loop: after each turn, it checks "did I
|
|
|
230
235
|
| `C2C_MAX_CONCURRENT` | `2` | Max simultaneously active Codex jobs; overflow queues FIFO |
|
|
231
236
|
| `C2C_STALL_WARN_MS` | `120000` | Stall watchdog threshold; emits stalled/resumed events; `0` disables |
|
|
232
237
|
|
|
238
|
+
## No Codex? Use c2c-lite
|
|
239
|
+
|
|
240
|
+
If Codex is unavailable (subscription expired, API down, rate limited), **[c2c-lite](https://github.com/PrestoOverture/c2c-lite)** gives you the same contract workflow with zero dependencies — Claude delegates to a Claude subagent instead of Codex, using the built-in `Agent` tool. Same Goal/Delta Contract format, same review discipline, no MCP server needed. Just one Skill file.
|
|
241
|
+
|
|
242
|
+
## Relationship to codex-plugin-cc
|
|
243
|
+
|
|
244
|
+
OpenAI maintains an official [Codex plugin for Claude Code](https://github.com/openai/codex-plugin-cc) (`codex-plugin-cc`). The two projects are **complementary, not competing** — they serve different workflows and can coexist in the same environment.
|
|
245
|
+
|
|
246
|
+
| | claude2codex | codex-plugin-cc |
|
|
247
|
+
|---|---|---|
|
|
248
|
+
| **Integration** | MCP server | Claude Code plugin |
|
|
249
|
+
| **Delegation model** | Structured Goal/Delta Contracts with mandatory handoff format | Free-form prompts forwarded to Codex as-is |
|
|
250
|
+
| **Review cycle** | Claude reviews Codex's output against success conditions; failures trigger scoped Delta Contracts | No structured review loop; results returned verbatim |
|
|
251
|
+
| **Code review** | Not included | Codex reviews Claude's code (native + adversarial) |
|
|
252
|
+
| **Concurrency** | Parallel jobs with FIFO queue and dependency chaining | Single task at a time |
|
|
253
|
+
| **Observability** | Token tracking, cost estimation, stall watchdog | Basic job status |
|
|
254
|
+
|
|
255
|
+
**When to use which:**
|
|
256
|
+
|
|
257
|
+
- **claude2codex** — when you want contract discipline: clearly defined goals, machine-checkable success conditions, structured handoffs, and a rework loop that converges on failures. Best for substantial implementation tasks where getting the specification right matters more than getting started fast.
|
|
258
|
+
- **codex-plugin-cc** — when you want quick Codex access: ad-hoc code reviews, fast rescue runs, session transfers between Claude and Codex. Best for lightweight delegation and review workflows.
|
|
259
|
+
|
|
260
|
+
Both use `codex app-server` under the hood. Installing one does not interfere with the other.
|
|
261
|
+
|
|
233
262
|
## Development
|
|
234
263
|
|
|
235
264
|
```sh
|
package/README.zh-CN.md
CHANGED
|
@@ -1,24 +1,24 @@
|
|
|
1
1
|
# claude2codex
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
一个让 Claude Code 通过结构化契约将实现工作委派给 OpenAI Codex 的 MCP 服务器。
|
|
4
4
|
|
|
5
5
|
*[English](./README.md)*
|
|
6
6
|
|
|
7
7
|
## 演示
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
完整的workflow实践过程：Claude 起草 Goal Contract，`codex_estimate` 预估成本，Codex 在 goal loop 下自主实现（`codex_status` 实时流式进度），最后 Claude 独立复核 handoff。
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
|
|
13
|
-
*Codex 运行（13k tokens，50
|
|
13
|
+
*Codex 运行（13k tokens，50 秒），等待时间已压缩。终端回放：*`asciinema play demo/demo.cast`
|
|
14
14
|
|
|
15
15
|
## 为什么做这个项目
|
|
16
16
|
|
|
17
17
|
2025 年，AI 辅助编程的主流方式是写详细的 prompt 告诉模型*怎么*实现——改哪些文件、用什么模式、有时候几乎是伪代码。工程师是导演，AI 是需要不断指导的执行者。
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
2026 年，模型的[实现能力已经足够强](https://www.anthropic.com/institute/recursive-self-improvement)，事无巨细地指挥"怎么写"不再是工程师最好的时间投入方式。瓶颈转移了：当实现变得廉价，真正昂贵的错误是**定义了错误的问题**和**没有验收出坏的结果**。把实现步骤写对，远不如把目标定义对重要。
|
|
20
20
|
|
|
21
|
-
这就是为什么 Goal Contract 被设计成这样。它不解释怎么写代码——它定义**代码必须做到什么**（Goal
|
|
21
|
+
这就是为什么 Goal Contract 被设计成这样。它不解释怎么写代码——它定义**代码必须做到什么**（Goal），**要避免什么**（Constraints）和**怎么证明做对了**（Success Conditions）。工程师的角色变成了问题定义、上下文补充和验收——和一个好的工程管理者委派任务时做的事情一样。
|
|
22
22
|
|
|
23
23
|
这个项目建立在这个前提上：把规划和审查（人的判断力仍然占主导）与实现（模型已经足够强）分开，用一种契约格式把它们连接起来，迫使工程师在最重要的部分(问题定义和验收标准)上做到清晰。
|
|
24
24
|
|
|
@@ -31,20 +31,26 @@ flowchart LR
|
|
|
31
31
|
Claude -.->|Delta Contract 修正| Codex
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
- **你** — 定义问题，决定做什么，给最终批准。
|
|
37
|
+
- **Claude Code** — 架构师和审查者。辅助架构设计，撰写契约，验证结果。
|
|
36
38
|
- **OpenAI Codex** — 实现者。接收契约，编写代码，运行测试，报告结果。
|
|
37
39
|
|
|
40
|
+
|
|
41
|
+
|
|
38
42
|
## 什么是 Goal Contract（目标契约）？
|
|
39
43
|
|
|
40
44
|
Goal Contract 是一份结构化规格说明，精确告诉 Codex **要做什么**。它由三部分组成：
|
|
41
45
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
| **
|
|
46
|
+
|
|
47
|
+
| 部分 | 作用 |
|
|
48
|
+
| ---------------------------- | -------------------------------- |
|
|
49
|
+
| **Goal（目标）** | 任务完成后代码应该达到的状态。 |
|
|
50
|
+
| **Constraints（约束）** | 边界条件：该动哪些文件、遵循什么模式、哪些东西*不能*改。 |
|
|
46
51
|
| **Success Conditions（成功条件）** | 可验证的标准，证明目标已达成。至少一条必须是可运行的测试或命令。 |
|
|
47
52
|
|
|
53
|
+
|
|
48
54
|
示例：
|
|
49
55
|
|
|
50
56
|
```markdown
|
|
@@ -70,11 +76,13 @@ Goal Contract 是一份结构化规格说明，精确告诉 Codex **要做什么
|
|
|
70
76
|
|
|
71
77
|
当 Claude 审查 Codex 的产出并发现问题时，不会从头来过 — 而是发送一份 **Delta Contract**（返工指令），只针对*失败的部分*：
|
|
72
78
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
|
79
|
+
|
|
80
|
+
| 部分 | 作用 |
|
|
81
|
+
| --------------------------- | ------------------------------- |
|
|
82
|
+
| **Findings（发现）** | 什么地方有问题，附文件/行号引用。 |
|
|
76
83
|
| **Failed Conditions（失败条件）** | 原始契约中哪些 Success Conditions 没通过。 |
|
|
77
84
|
|
|
85
|
+
|
|
78
86
|
Codex 恢复同一个线程（保留第一次尝试的全部上下文），只修复被指出的问题。
|
|
79
87
|
|
|
80
88
|
## 完整工作流
|
|
@@ -93,14 +101,16 @@ flowchart TD
|
|
|
93
101
|
G --> I[完成 - 更新文档]
|
|
94
102
|
```
|
|
95
103
|
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
|
|
96
108
|
## 三层 Prompt 架构
|
|
97
109
|
|
|
98
110
|
Codex 最终工作时的 prompt 由三层组成，但只有两层来自 claude2codex：
|
|
99
111
|
|
|
100
112
|
1. **协议层**（内嵌在 MCP 服务器中）— 通用规则：如何自我验证、如何格式化交接报告、如何处理返工。无论什么项目都一样。
|
|
101
|
-
|
|
102
113
|
2. **项目层**（`AGENTS.md`）— 项目特定的编码规范、工具链说明、架构约束。**由 Codex 自己加载，不是本服务器注入的。** Codex 会在工作目录所属的仓库树中查找 `AGENTS.md`（以及 `AGENTS.override.md`），放进它自己的 instructions 层，并受其 `project_doc_max_bytes` 预算约束。claude2codex 过去会重复注入一遍，现已移除。
|
|
103
|
-
|
|
104
114
|
3. **任务层**（Goal/Delta Contract 本身）— 这次要做的具体工作。
|
|
105
115
|
|
|
106
116
|
这种分离意味着：MCP 服务器开箱即用（第 1 层始终存在），直接继承 Codex 已经加载的项目上下文（第 2 层），每次任务都有独特的规格说明（第 3 层）。
|
|
@@ -111,10 +121,14 @@ Codex 最终工作时的 prompt 由三层组成，但只有两层来自 claude2c
|
|
|
111
121
|
|
|
112
122
|
需要 [Codex CLI](https://github.com/openai/codex) 和 Node.js 18+。
|
|
113
123
|
|
|
124
|
+
**模型与推理强度。** c2c 直接沿用 Codex CLI 的配置（`~/.codex/config.toml`），自身不设任何默认值。调用 `codex_config` 可查看任务实际将使用的模型和强度。如需覆盖：在 MCP server 的 `env` 中设置 `CODEX_MODEL`（作用于所有任务），或在单个任务中传入 `reasoning_effort`。
|
|
125
|
+
|
|
114
126
|
```sh
|
|
115
127
|
npx claude2codex
|
|
116
128
|
```
|
|
117
129
|
|
|
130
|
+
|
|
131
|
+
|
|
118
132
|
### MCP 配置
|
|
119
133
|
|
|
120
134
|
添加到你的 Claude Code MCP 设置中：
|
|
@@ -130,15 +144,20 @@ npx claude2codex
|
|
|
130
144
|
}
|
|
131
145
|
```
|
|
132
146
|
|
|
133
|
-
### 工作流 Prompt（自动）
|
|
134
147
|
|
|
135
|
-
服务器注册了一个 MCP Prompt（`c2c-workflow`），教 Claude 完整的契约工作流——角色分配、Goal/Delta Contract 格式、审查协议。**连接 MCP 服务器后自动加载。** 无需额外安装。
|
|
136
148
|
|
|
137
|
-
###
|
|
149
|
+
### 工作流：Instructions + Prompt
|
|
150
|
+
|
|
151
|
+
工作流分两层送达 Claude，都无需额外安装。
|
|
152
|
+
|
|
153
|
+
- **服务器 instructions（自动）。** 连接时服务器会发送一段简短说明（不超过 1000 字符），Claude Code 会把它加入系统提示。它只在你要求把工作交给 Codex 时生效：Claude 会起草 Goal Contract 供你批准，然后估算、提交、轮询，并亲自重跑验证命令。不委派的任务照常处理。
|
|
154
|
+
- **`c2c-workflow` Prompt（按需调用，完整规则）。** Goal/Delta Contract 格式和完整审查协议（含可证伪性检查）。MCP Prompt 需要用户手动调用：在要委派的 session 开头输入 `/mcp__codex__c2c-workflow`（中间一段是你在 MCP 配置里给服务器起的名字）。
|
|
155
|
+
|
|
156
|
+
### 项目配置：CLAUDE.md 和 [AGENTS.md](http://AGENTS.md)
|
|
138
157
|
|
|
139
158
|
MCP 服务器负责工作流协议。你的项目文件只需要放**项目特有的上下文**——不要重复服务器已经提供的内容。
|
|
140
159
|
|
|
141
|
-
|
|
160
|
+
`CLAUDE.md`（给 Claude——架构师/审查者）：
|
|
142
161
|
|
|
143
162
|
```markdown
|
|
144
163
|
# Claude Code Guidelines
|
|
@@ -156,7 +175,7 @@ MCP 服务器负责工作流协议。你的项目文件只需要放**项目特
|
|
|
156
175
|
- 未经明确批准不得修改 migrations。
|
|
157
176
|
```
|
|
158
177
|
|
|
159
|
-
|
|
178
|
+
`AGENTS.md`（给 Codex——实现者）：
|
|
160
179
|
|
|
161
180
|
```markdown
|
|
162
181
|
# Codex Guidelines
|
|
@@ -176,27 +195,33 @@ Python 3.12，Poetry。从项目根目录运行。
|
|
|
176
195
|
|
|
177
196
|
**什么放哪里：**
|
|
178
197
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
198
|
+
|
|
199
|
+
| | MCP 服务器 | CLAUDE.md | AGENTS.md |
|
|
200
|
+
| --------- | ----------- | --------- | --------- |
|
|
201
|
+
| 角色定义 | ✓ | — | — |
|
|
202
|
+
| 工作流步骤 | ✓ | — | — |
|
|
203
|
+
| 契约格式 | ✓ | — | — |
|
|
204
|
+
| 审查协议 | ✓ | — | — |
|
|
205
|
+
| 会话启动 | — | ✓ | ✓ |
|
|
206
|
+
| 项目特有的审查规则 | — | ✓ | — |
|
|
207
|
+
| 工具链与构建命令 | — | — | ✓ |
|
|
208
|
+
| 文件/依赖边界 | — | — | ✓ |
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
|
|
189
212
|
|
|
190
213
|
## 提供的工具
|
|
191
214
|
|
|
192
|
-
|
|
193
|
-
|
|
215
|
+
|
|
216
|
+
| 工具 | 说明 |
|
|
217
|
+
| ----------------- | ----------------------------------------------------------------------------------------------------- |
|
|
194
218
|
| `codex_implement` | 从 Goal Contract 启动一个 Codex 任务。支持 `context_files`（先读参考文件，校验存在性）和 `depends_on`（前序任务成功后才启动）。立即返回 job ID。 |
|
|
195
|
-
| `codex_status`
|
|
196
|
-
| `codex_result`
|
|
197
|
-
| `codex_rework`
|
|
198
|
-
| `codex_estimate`
|
|
199
|
-
| `codex_config`
|
|
219
|
+
| `codex_status` | 查看任务进度：状态、队列位置、依赖、轮次、目标状态、token 用量、距上次活动的时间、活动记录。 |
|
|
220
|
+
| `codex_result` | 获取已完成任务的结构化交接报告。 |
|
|
221
|
+
| `codex_rework` | 用 Delta Contract 恢复 Codex 线程进行返工（同样支持 `context_files`）。 |
|
|
222
|
+
| `codex_estimate` | 只读的任务前成本预估：渲染后的 prompt 规模、thread-goal objective 相对 `GOAL_OBJECTIVE_MAX` 的规模，以及本机已完成任务的 token 统计。 |
|
|
223
|
+
| `codex_config` | 只读查看 Codex 当前模型、版本和配置。 |
|
|
224
|
+
|
|
200
225
|
|
|
201
226
|
任务会持久化（`C2C_STATE_DIR`），因此状态查询、结果获取和返工在 server 重启后依然可用。超出并发上限的任务按 FIFO 排队；停滞看门狗会在运行中的任务失去进展时主动上报。关于如何写出"一次过审"的合同，参见实战指南 [PATTERNS.zh-CN.md](./PATTERNS.zh-CN.md)。
|
|
202
227
|
|
|
@@ -213,22 +238,50 @@ Python 3.12，Poetry。从项目根目录运行。
|
|
|
213
238
|
|
|
214
239
|
## 环境变量
|
|
215
240
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
241
|
+
|
|
242
|
+
| 变量 | 默认值 | 说明 |
|
|
243
|
+
| ----------------------- | ---------------------- | --------------------------------------------------------- |
|
|
244
|
+
| `CODEX_BIN` | `codex` | Codex 可执行文件 |
|
|
245
|
+
| `CODEX_ARGS` | `app-server` | Codex 启动参数（空格分隔） |
|
|
246
|
+
| `CODEX_CWD` | 当前目录 | 任务默认工作目录 |
|
|
247
|
+
| `CODEX_MODEL` | Codex 默认 | 模型覆盖 |
|
|
248
|
+
| `CODEX_APPROVAL_POLICY` | `never` | 审批策略（默认自主执行） |
|
|
249
|
+
| `CODEX_PERMISSIONS` | 未设置 | 权限配置透传 |
|
|
250
|
+
| `CODEX_JOB_TIMEOUT_MS` | `1800000` | 单任务最大时长（30 分钟） |
|
|
251
|
+
| `CODEX_QUIET_MS` | `30000` | 判定活跃目标已完成前的静默等待时间 |
|
|
252
|
+
| `GOAL_OBJECTIVE_MAX` | `2000` | 渲染后 goal-objective 的最大长度；超限的合同会被 `codex_implement` 在提交时拒绝 |
|
|
253
|
+
| `C2C_STATE_DIR` | `~/.claude2codex/jobs` | 持久化任务注册表（每任务一个原子写入的 JSON 文件） |
|
|
254
|
+
| `C2C_LOG_LEVEL` | `info` | stderr 上的结构化 JSON 日志：`silent`、`error`、`info`、`debug` |
|
|
255
|
+
| `C2C_RETRIES` | `1` | 首个 turn 开始前的进程故障自动重试次数 |
|
|
256
|
+
| `C2C_MAX_CONCURRENT` | `2` | 同时活跃的 Codex 任务上限；超出按 FIFO 排队 |
|
|
257
|
+
| `C2C_STALL_WARN_MS` | `120000` | 停滞看门狗阈值；发出 stalled/resumed 事件；`0` 禁用 |
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
## 没有 Codex？用 c2c-lite
|
|
263
|
+
|
|
264
|
+
Codex 不可用（欠费、API 故障、限流）的时候，**[c2c-lite](https://github.com/PrestoOverture/c2c-lite)** 提供同样的合同工作流，零依赖——Claude 把活儿派给另一个 Claude 子代理 (建议Sonnet)，用的是 Claude Code 内置的 `Agent` 工具。同样的 Goal/Delta Contract 格式，同样的审查流程，不需要 MCP 服务器，只要一个 Skill 文件。
|
|
265
|
+
|
|
266
|
+
## 与 codex-plugin-cc 的关系
|
|
267
|
+
|
|
268
|
+
OpenAI 维护了一个官方的 [Codex plugin for Claude Code](https://github.com/openai/codex-plugin-cc)（`codex-plugin-cc`）。两个项目**互补而非竞争**——它们服务于不同的工作流，可以在同一环境中共存。
|
|
269
|
+
|
|
270
|
+
| | claude2codex | codex-plugin-cc |
|
|
271
|
+
|---|---|---|
|
|
272
|
+
| **集成方式** | MCP 服务器 | Claude Code 插件 |
|
|
273
|
+
| **委派模型** | 结构化 Goal/Delta Contract，强制交接格式 | 自由文本 prompt 原样转发给 Codex |
|
|
274
|
+
| **审查循环** | Claude 按 success conditions 审查 Codex 产出；失败触发限定范围的 Delta Contract | 无结构化审查循环；结果原样返回 |
|
|
275
|
+
| **代码审查** | 不包含 | Codex 审查 Claude 的代码（原生 + 对抗式） |
|
|
276
|
+
| **并发** | 并行任务 + FIFO 队列 + 依赖链 | 单任务 |
|
|
277
|
+
| **可观测性** | Token 追踪、成本预估、停滞看门狗 | 基本任务状态 |
|
|
278
|
+
|
|
279
|
+
**何时用哪个：**
|
|
280
|
+
|
|
281
|
+
- **claude2codex** — 需要契约纪律时：清晰的目标定义、可机器验证的成功条件、结构化交接报告、以及针对失败项收敛的返工循环。适合需要把规格说明想清楚的实质性实现任务。
|
|
282
|
+
- **codex-plugin-cc** — 需要快速调用 Codex 时：即时代码审查、快速 rescue 任务、Claude 与 Codex 之间的会话转移。适合轻量级委派和审查场景。
|
|
283
|
+
|
|
284
|
+
两者底层都使用 `codex app-server`。安装其中一个不会影响另一个。
|
|
232
285
|
|
|
233
286
|
## 开发
|
|
234
287
|
|
|
@@ -239,6 +292,8 @@ bun test # 端到端测试（使用 mock，无需真实 API 调用）
|
|
|
239
292
|
npm run build # 生成 dist/server.js
|
|
240
293
|
```
|
|
241
294
|
|
|
295
|
+
|
|
296
|
+
|
|
242
297
|
## 协议
|
|
243
298
|
|
|
244
299
|
MIT
|
package/dist/server.js
CHANGED
|
@@ -262,7 +262,7 @@ var CodexAppServer = class {
|
|
|
262
262
|
*/
|
|
263
263
|
async initialize() {
|
|
264
264
|
const result = await this.request("initialize", {
|
|
265
|
-
clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.
|
|
265
|
+
clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.4" },
|
|
266
266
|
capabilities: { experimentalApi: true }
|
|
267
267
|
});
|
|
268
268
|
this.notify("initialized", {});
|
|
@@ -593,6 +593,19 @@ function updateGoal(job, params) {
|
|
|
593
593
|
store.save(job);
|
|
594
594
|
}
|
|
595
595
|
var TERMINAL_GOAL_STATUSES = /* @__PURE__ */ new Set(["complete", "budget_limited", "budgetLimited"]);
|
|
596
|
+
function codexErrorMessage(err) {
|
|
597
|
+
const raw = typeof err === "string" ? err : err?.message;
|
|
598
|
+
if (typeof raw !== "string" || !raw.trim()) return void 0;
|
|
599
|
+
try {
|
|
600
|
+
const parsed = JSON.parse(raw);
|
|
601
|
+
const inner = parsed?.error?.message;
|
|
602
|
+
if (typeof inner === "string" && inner) {
|
|
603
|
+
return typeof parsed.status === "number" ? `${inner} (HTTP ${parsed.status})` : inner;
|
|
604
|
+
}
|
|
605
|
+
} catch {
|
|
606
|
+
}
|
|
607
|
+
return raw;
|
|
608
|
+
}
|
|
596
609
|
async function runJob(job, opts) {
|
|
597
610
|
const deadline = Date.now() + opts.config.jobTimeoutMs;
|
|
598
611
|
const maxAttempts = (opts.config.retries ?? 1) + 1;
|
|
@@ -625,6 +638,7 @@ async function runAttempt(job, opts, timeoutMs) {
|
|
|
625
638
|
let activeTurn = false;
|
|
626
639
|
let stalled = false;
|
|
627
640
|
let processError;
|
|
641
|
+
let lastCodexError;
|
|
628
642
|
let quietTimer;
|
|
629
643
|
let stallTimer;
|
|
630
644
|
let settle;
|
|
@@ -769,9 +783,26 @@ async function runAttempt(job, opts, timeoutMs) {
|
|
|
769
783
|
log(job, "turn", `turn ended (${status})`);
|
|
770
784
|
writeLog("info", "turn_ended", { job_id: job.id, turn: job.turns, status });
|
|
771
785
|
progress("turn_ended", `turn ended (${status})`);
|
|
786
|
+
if (status === "failed") {
|
|
787
|
+
const reason = codexErrorMessage(p.turn?.error) ?? lastCodexError ?? "no error message from Codex";
|
|
788
|
+
finalize("error", `Codex turn failed: ${reason}`);
|
|
789
|
+
settle();
|
|
790
|
+
break;
|
|
791
|
+
}
|
|
772
792
|
void onTurnEnded();
|
|
773
793
|
break;
|
|
774
794
|
}
|
|
795
|
+
case "error": {
|
|
796
|
+
const message = codexErrorMessage(p.error);
|
|
797
|
+
if (!message) break;
|
|
798
|
+
const willRetry = p.willRetry === true;
|
|
799
|
+
if (!willRetry) lastCodexError = message;
|
|
800
|
+
const detail = willRetry ? `${message} (Codex will retry)` : message;
|
|
801
|
+
log(job, "error", detail);
|
|
802
|
+
writeLog(willRetry ? "info" : "error", "codex_error", { job_id: job.id, message, will_retry: willRetry });
|
|
803
|
+
progress("codex_error", detail.slice(0, 200));
|
|
804
|
+
break;
|
|
805
|
+
}
|
|
775
806
|
default:
|
|
776
807
|
break;
|
|
777
808
|
}
|
|
@@ -930,7 +961,16 @@ function textResult(obj, isError = false) {
|
|
|
930
961
|
isError
|
|
931
962
|
};
|
|
932
963
|
}
|
|
933
|
-
var
|
|
964
|
+
var SERVER_INSTRUCTIONS = `When the user asks to delegate work to Codex (or to use c2c), act as architect and reviewer, not implementer:
|
|
965
|
+
1. Draft a Goal Contract and get the user's approval (show the user the contract) before calling codex_implement.
|
|
966
|
+
2. codex_estimate, then codex_implement; poll codex_status and report progress.
|
|
967
|
+
3. Review via codex_result: re-run every verification command yourself; never trust the handoff alone. On failure, send a Delta Contract via codex_rework.
|
|
968
|
+
If a Codex job itself fails (error, 0 tokens, no handoff), report it and wait; don't implement the task yourself unless the user explicitly asks.
|
|
969
|
+
Full formats: the c2c-workflow prompt.`;
|
|
970
|
+
var server = new McpServer(
|
|
971
|
+
{ name: "c2c-codex", version: "0.3.4" },
|
|
972
|
+
{ instructions: SERVER_INSTRUCTIONS }
|
|
973
|
+
);
|
|
934
974
|
var reasoningEffort = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
|
|
935
975
|
var contextFiles = z.array(z.object({
|
|
936
976
|
path: z.string().min(1),
|
|
@@ -1216,6 +1256,7 @@ Only what Codex would get wrong without being told. One line of
|
|
|
1216
1256
|
|
|
1217
1257
|
### Success Conditions
|
|
1218
1258
|
- [ ] Assertions, not paragraphs. At least one is a command whose exit code decides.
|
|
1259
|
+
- [ ] Command-based conditions must be falsifiable: describe how they fail when the defect exists. Subjective criteria should be marked as needing reviewer judgment.
|
|
1219
1260
|
- [ ] Handoff includes: Changed Files, Validation, Success Conditions, Risks & Deviations.
|
|
1220
1261
|
\`\`\`
|
|
1221
1262
|
|
|
@@ -1238,9 +1279,10 @@ Only what Codex would get wrong without being told. One line of
|
|
|
1238
1279
|
|
|
1239
1280
|
1. Handoff must be complete (all four sections). Missing handoff = review failure.
|
|
1240
1281
|
2. Re-run every verification command yourself \u2014 do not trust the handoff's claims.
|
|
1241
|
-
3.
|
|
1242
|
-
4.
|
|
1243
|
-
5.
|
|
1282
|
+
3. Verify falsifiability: each command-based success condition must fail when the defect is present. A check that passes regardless is a review failure.
|
|
1283
|
+
4. Run the project's own typecheck/build/test/lint.
|
|
1284
|
+
5. Flag security issues and constraint violations.
|
|
1285
|
+
6. Report findings to the user. Fix small issues (typos, imports, test gaps found by your own falsifiability check) directly; do not rewrite the implementation.
|
|
1244
1286
|
` }
|
|
1245
1287
|
}]
|
|
1246
1288
|
}));
|
package/package.json
CHANGED