Codex 使用场景
调查故障并测试修复方案
根据故障资料复现缺陷,编写针对性补丁,并整理可供评审的交接材料。
向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。
最适合
- 正在调查已受控故障的小型工程团队。
- 已有脱敏证据和安全复现输入的应用缺陷。
- 在可用的隔离测试环境中评审针对性修复的团队。
目录
调查故障并测试修复方案
根据故障资料复现缺陷,编写针对性补丁,并整理可供评审的交接材料。
向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。
向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。
相关链接
最适合
- 正在调查已受控故障的小型工程团队。
- 已有脱敏证据和安全复现输入的应用缺陷。
- 在可用的隔离测试环境中评审针对性修复的团队。
起始提示词
在准备好的云端环境中,让 Codex 调查一起范围明确的故障。目标是交付可供工程师审查的结果,包括有证据支持的故障解释、修复前无法通过的回归测试、针对该缺陷的补丁,以及实际运行测试所得的证据。
这种做法适用于故障已得到控制、接下来需要查明并修复应用缺陷的情况。如果现有证据不足以确定原因,请清楚记录调查过程,并指出下一步如何诊断。
准备环境和故障资料包
-
在网页应用或桌面应用中,选择工作位置 > 云端,然后选择已发布的环境。
-
如需创建环境,请选择创建环境,选好 GitHub 代码仓库,然后让 Codex 准备运行时、依赖项和隔离的测试服务。
-
查看环境配置报告,解决导致检查失败的问题,并在开始新任务前发布环境。
如果依赖项或服务配置发生变化,请编辑可复用环境,测试后重新发布,然后在新任务中验证更新后的环境。
刷新代码仓库不会重新运行安装或启动命令,已有任务也会保留各自的状态。
请分别配置需要访问的网络目标和测试凭据。允许连接某个目标并不会授予服务访问权限。
在新任务中,确认受影响版本的检出代码、依赖项、各项检查和可丢弃的测试数据库均可正常使用。记录起始提交和测试基线。
请备齐初步调查所需的资料。将脱敏后的资料包放入代码仓库,或通过其他方式让任务能够访问其中的文件。开始前,应由工程师整理并核对以下资料:
| 输入 | 应包含的内容 |
|---|---|
| 故障摘要 | 故障 ID、UTC 时间范围、预期行为和实际观察到的行为、已知影响及当前状态。区分已确认的数量和估算值。 |
| 发布版本信息 | 已部署的提交 SHA、部署时间、不含机密信息的相关配置值,以及最后一个已知正常的发布版本(如有)。 |
| 关联证据 | 带有时间戳、事件 ID、请求 ID、追踪 ID 和文件引用的日志及追踪片段。脱敏时,同一标识符的替换值应保持一致。 |
| 安全复现 | 测试请求体、相关测试夹具,以及如何在不调用线上服务的情况下执行可疑代码路径。 |
| 代码仓库说明 | 相关路径、数据库引擎、测试命令、允许的改动,以及负责审查结果的工程师。 |
请勿在资料包中包含访问令牌、客户载荷或个人数据。
监控集成是可选的。如果您使用监控集成,请仅授予相关项目和时间范围内的只读访问权限。基于文件的工作流无需监控集成。代码仓库说明应要求将测试凭据与生产配置分开。
运行起始提示词
使用本页的起始提示词,并将占位符替换为您的故障 ID、代码仓库和资料包路径。首轮结果应说明证据与受影响代码之间的联系、哪些行为可以复现,以及还缺少哪些信息。
只有当证据表明代码存在缺陷时,才让 Codex 继续实施修复。否则,请审查调查结果并补充缺少的输入。看似合理的解释、最近的代码改动或在另一发布版本上通过的测试,都不足以确定故障原因。
示例:重试 webhook 时生成了重复订单
使用可运行的故障示例练习调查。示例包含准备好的故障资料包、存在可复现缺陷的处理程序、修正后的处理程序,以及 PostgreSQL 测试。
服务收到 order.created webhook 后,会写入订单并记录该事件已处理。故障期间,一次重试似乎生成了第二笔订单。团队已让服务恢复稳定,现在需要一个可供审查的补丁。
示例使用 TypeScript、Node.js 测试运行器和 PostgreSQL。其可丢弃的测试夹具包含 event_receipts 表。该表的标识列不允许为空,且 (provider, account_id, event_id) 上有不可延迟检查的唯一键。
该数据库模式允许在订单创建前先写入回执以取得事件处理权,并保留规范化载荷的指纹,以检测同一事件键是否被重复用于相互冲突的载荷。
如果您的应用要求在取得处理权时就提供订单外键,或缺少判断此类冲突所需的证据,请先暂停,单独决定如何处理数据库模式或设计。
在证据记录中注明确切的运行时、依赖锁定信息、PostgreSQL 版本、事务隔离级别和回执表模式。可下载的夹具固定使用 Node.js 24.19.0、PostgreSQL 17.6 和 pg 8.23.1。
对于示例提供的 Compose 配置,请准备一个 Docker 守护进程可正常运行的环境,并在发布前验证 docker info 能成功执行。其数据库仅接受公开的测试凭据,且仅绑定到本地回环接口。调整测试以适配您的应用时,请使用应用实际采用的数据库引擎和相关设置。
本示例假设 PostgreSQL 使用 READ COMMITTED 隔离级别,提供方的事件 ID 保持稳定,且回执保留期覆盖提供方的重试和重放窗口。
修正后的处理程序在同一个数据库事务中写入回执和订单。测试夹具创建可丢弃的数据库及 delivery_holds 表,以模拟现有队列的隔离流程。该表仅用于测试基础设施,无需为应用添加相应的迁移。
应用修复不会新增队列、数据库服务、模式迁移或监控集成。如果上述假设不成立,请暂停并重新确定修复范围。
运行示例
解压 ZIP 文件,进入解压后的目录,然后使用 Docker 和 Compose 运行以下命令:
docker compose -p codex-incident-rehearsal up -d --wait postgres
docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts baseline
docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts regression
docker compose -p codex-incident-rehearsal run --rm runner
docker compose -p codex-incident-rehearsal down --volumes
基线命令必须以退出码 1 结束。重试断言预期有一笔订单和一条回执,实际却有两笔订单和一条回执。回归命令对修正后的处理程序运行相同的断言,必须以退出码 0 结束。
最后一条测试命令覆盖完整的测试矩阵,包括独立连接、数据库锁争用,以及对历史遗留的无回执订单所对应的投递进行隔离。
如果您的安装提供的是 docker-compose,请用它替换 docker compose。按顺序执行这些命令。测试套件仅重置其标记的测试数据库模式。
如果使用 Ruby,请使用完整的 Ruby 示例项目,并使用 Ruby 3.3 安装项目依赖。使用 ZIP 压缩包中的 Compose 配置启动 PostgreSQL。在 Ruby 项目目录中运行 bundle exec ruby codex-cloud/incident-to-tested-fix/main.rb baseline,然后分别将最后一个参数替换为 regression 和 fixed,各运行一次。这些命令使用同一个可丢弃的测试数据库,并产生预期的失败和通过结果。请用这些命令替代 Node 测试运行器的命令。
查看事务处理程序
TypeScript 代码片段来自 ZIP 压缩包中的 main.ts。
Ruby 示例来自上方链接中的 Ruby 示例项目。
使用随附的数据库夹具,运行所选语言的完整示例文件。
在同一事务中取得事件处理权并写入订单
import type { Client } from "pg";
type IncidentEvent = {
provider: string;
accountId: string;
eventId: string;
payload: { type: string; orderId: string; amountCents: number };
};
async function fixed(
client: Client,
input: IncidentEvent,
hook = async (_boundary: string) => {}
) {
await assertNotHeld(client, input);
await hook("beforeClaim");
await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");
let committed = false;
try {
const claimed = await client.query(
`INSERT INTO event_receipts(provider, account_id, event_id, payload_fingerprint)
VALUES ($1,$2,$3,$4)
ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING event_id`,
[...key(input), fingerprint(input)]
);
trace("receipt-claim-result", client, input, {
inserted: claimed.rowCount === 1,
});
if (claimed.rowCount === 1) {
await hook("afterClaim");
await writeOrder(client, input);
await hook("afterOrder");
} else {
// A new READ COMMITTED statement sees the winner after its commit.
await checkReceipt(client, input);
}
await client.query("COMMIT");
committed = true;
trace("transaction-committed", client, input);
await hook("afterCommit");
trace("acknowledged", client, input, acknowledgment);
return acknowledgment;
} catch (error) {
if (!committed) {
await client.query("ROLLBACK");
trace("transaction-rolled-back-no-ack", client, input);
} else {
trace("committed-response-lost-no-ack", client, input);
}
throw error;
}
}1. 提供精简的故障资料包
可按以下文件组织资料包:
incidents/INC-DEMO-014/incident.md
incidents/INC-DEMO-014/logs.ndjson
incidents/INC-DEMO-014/release.json
incidents/INC-DEMO-014/order-created.sanitized.json
在此场景中,release.json 记录的示例发布版本 SHA 为 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413,部署时间为 2026-09-22T11:58:00Z。故障发生在同一天的 12:03:00Z–12:05:00Z。资料包显示,两笔内部订单关联到提供方的同一事件。准备自己的资料包时,请列出已确认的受影响数量,并标明哪些数字是估算值。
脱敏日志中包含以下可相互关联的观测记录:
| UTC 时间 | 关联信息 | 观测结果 |
|---|---|---|
| 12:03:04.110 | 事件 evt_demo_042,账户 acct_demo_01,请求 req_demo_a,追踪 trace_demo_a |
首次投递进入 webhook 处理程序。 |
| 12:03:04.145 | 同一事件,首次投递的追踪 | 订单 ord_demo_101 已提交。 |
| 12:03:04.150 | 同一工作进程 | 工作进程退出,此前未记录回执写入成功或响应。仅凭这段日志无法证明回执不存在。 |
| 12:03:14.203 | 同一提供方、账户和事件,请求 req_demo_b,追踪 trace_demo_b |
重试请求进入处理程序。处理程序在日志中记录未找到匹配的回执。 |
| 12:03:14.241 | 同一事件,第二次投递的追踪 | 订单 ord_demo_102 已提交,并已记录一条回执。 |
同一事件的各次投递应使用稳定的事件 ID,而每次投递应使用不同的请求 ID 和追踪 ID。如果仅按请求标识事件,就无法看出重试与原始事件的关系。
2. 追查证据并检验假设
故障报告推测重复订单由重试风暴引起。Codex 应将其视为有待检验的假设。观察到两次投递不足以证明发生了重试风暴,而且 webhook 处理程序本就必须能够处理正常的重试。
检查示例中存在缺陷的源代码可以看到,处理程序先查询回执,再提交订单,最后在另一个事务中写入回执。两次提交之间的间隙更能解释故障。如果工作进程在这段时间内发生故障,已提交的订单可能没有回执,重试就可能再创建一笔订单。如果检查和写入分开执行,两次并发投递也可能在任何一方写入回执之前都通过检查。
让 Codex 追查实际运行的处理程序及其事务边界,并引用相关代码行。它应确认资料包中的发布版本与被测代码一致。如果测试使用其他提交,则应说明这会如何限制结论的适用范围。
3. 修改处理程序前先复现故障
使用示例 webhook 和隔离的 PostgreSQL 数据库添加回归测试。在原处理程序中,紧接订单写入操作、尚未写入回执时,设置一个仅用于测试的故障注入钩子。
根据实际事务边界确认,此时原订单已经提交。使用相同的提供方、账户和事件重试,并断言恰好存在一笔订单和一条匹配的回执。示例中预置缺陷的实现应因出现两笔订单而未通过测试。
修复后,在订单写入语句执行完毕、共享事务提交之前触发相应的钩子。失败的尝试必须既不留下订单,也不留下回执。
重试并断言恰好有一笔订单和一条回执。各版本使用相同的业务断言,并记录每个版本中钩子的位置。
先在原实现上运行新测试。对于本示例预置的缺陷,预期测试会因出现两笔订单而失败。保存命令、起始提交、退出码和断言输出。如果未出现预期的失败,请先调查差异,再修改处理程序。
注入异常可以检验应用的事务行为。请在记录中注明,此方法无法复现所有可能的主机、网络或数据库故障。
4. 实施证据支持的最小修复
针对这一缺陷,请在同一个数据库连接的同一个事务中,先通过插入事件回执取得处理权,再写入订单。利用现有唯一键执行 INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ...。
只有成功插入回执的投递才能写入订单,并且只能在提交后返回成功确认。事务失败时,两次写入都会回滚。请勿捕获唯一性约束错误后继续使用已中止的事务。
并发到达的另一次投递可能需要等待第一个事务。如果第一个事务提交,第二次投递尝试取得处理权时不会插入任何行。此时应在 READ COMMITTED 隔离级别下重新执行 SELECT,按既定策略核验已存储的事件标识和载荷,然后直接返回既有的重复投递确认响应。
如果第一个事务回滚,竞争方就可以取得处理权并处理事件。如果跳过插入后找不到回执、事件标识冲突,或数据库出现暂时性错误,必须按文档规定的重试或错误处理流程操作,不得返回虚假的成功响应。
在更严格的隔离级别下,如果出现序列化失败,必须按代码仓库规定的策略重试整个事务,并遵守重试限制。请参阅 PostgreSQL 的 INSERT 冲突处理行为和事务隔离文档。
无论使用内存集合,还是分开执行“先检查再插入”,都无法防止并发工作进程或重启导致的重复处理。请根据提供方对事件标识的约定确定键的作用域。如果看似同一事件的标识或载荷信息相互冲突,应明确报告不一致,不能将其默认为有效的重复投递。
本示例的业务数据变更完全发生在同一个数据库中。如果实际处理程序还会发送邮件、从银行卡扣款或调用其他服务,仅靠该事务无法保证这些外部操作的幂等性。在扩大修复范围前,请明确这一边界,并查明系统现有的投递或幂等机制。
5. 验证修复后的行为
请让 Codex 同时提供原实现的失败结果和修复后的结果。在明确标出的事务边界使用仅用于测试的钩子,并从单独的连接检查已提交的状态。示例通过了 11 项本地 PostgreSQL 测试。下载包中的 test-evidence.md 记录了这些结果,以及在云端运行和部署时仍需完成的检查。请在已发布的环境中运行测试套件,并在依赖该恢复流程之前测试提交期间连接实际断开的情形。
| 检查项或故障注入点 | 必须满足的行为 |
|---|---|
| 首次投递,以及首次提交后的重复投递 | 首次投递创建一笔订单和一条回执。重复投递返回约定的确认响应,记录数量保持不变。记录确切的状态码和响应体。 |
| 取得事件处理权之前 | 发生故障时不创建订单或回执,也不返回成功确认。重试后创建一笔订单和一条回执。 |
| 取得处理权之后、写入订单之前 | 发生故障时回执回滚,订单不存在。重试可以正常取得处理权并处理事件。 |
| 写入订单之后、提交之前 | 发生故障时两条记录均回滚。该检查对应原代码中订单已提交但缺少回执的缺陷。修复后重试,最终有一笔订单和一条回执。 |
| 提交之后、返回确认之前 | 模拟响应丢失。两条记录均保持已提交状态。重试返回重复投递确认,不会再创建订单。 |
| 提交结果未知 | 将提交前后连接断开的情况与普通异常分开模拟。没有依据时不得返回成功确认。无论第一个事务提交还是回滚,使用同一个稳定的事件键重试都必须安全。如果未测试这种传输故障,请标记为未运行。 |
| 并发重复投递:第一个事务提交 | 让两个独立的连接或工作进程争用同一事件键。让先取得处理权的一方暂停,并在放行之前启动竞争方。验证确实发生争用,再放行先取得处理权的一方。双方都按预期流程返回确认,最终恰好有一笔订单和一条回执。 |
| 并发重复投递:第一个事务回滚 | 重复上述受控的并发过程,但让先取得处理权的一方在提交前失败。回滚后,竞争方取得处理权,创建一笔订单和一条回执。检查双方的响应和最终状态。 |
| 事件标识和载荷冲突 | 不同事件应互不影响。不同账户或提供方使用相同事件 ID 时也应互不影响。对于同一作用域内 ID 相同但规范化载荷冲突的事件,应按约定流程处理冲突。不得创建第二笔订单,也不得将不同的业务操作默认为已成功处理。 |
| 历史订单缺少回执且仍有待重试的投递 | 预置一笔已提交但没有回执的历史订单。恢复重试前,识别其事件键并暂停该键的投递。被暂停的重试既不返回成功确认,也不创建记录。依据可信证据完成核对补录后,系统可返回重复投递确认,此时有一笔原有订单和一条回执。如果证据缺失或冲突,则继续暂停该键的投递。 |
| 更广泛的服务检查 | 运行相关集成测试、代码规范检查和类型检查。分别列出新增失败、原有失败和无法运行的检查。 |
使用屏障或闭锁等同步机制协调并发,并设置有限的超时时间。不要靠休眠或仅靠两个 Promise 来协调执行时序。测试清理时要释放被阻塞的工作进程,并使用可丢弃的测试夹具。仅测试异常不足以证明进程突然终止、传输中断或生产环境并发时的实际行为。
示例在版本固定的运行器中使用 node --experimental-strip-types main.ts baseline、node --experimental-strip-types main.ts regression 和 node --experimental-strip-types main.ts。结构化输出会记录事务边界、已提交的行数、确认响应的状态码和响应体,以及实际观察到的造成阻塞的数据库后端进程 ID。
调整此工作流时,请使用您的代码仓库实际定义的命令,并报告真实结果。交接材料中应注明跳过的检查或不可用的依赖项,并说明这些情况对结论可信度的影响。
审查交接材料
共用证据记录
针对每项验收标准,使用故障处理工作流的证据格式。根据实际观察到的输出填写以下模板。如果基线版本中还没有某项新测试,请将“尚未添加”与已有检查失败区分开来。
Criterion / test: [specific behavior and test location]
Environment: [published setup reference; runtime, database and dependency versions]
Before: [revision + test-only diff ID; command; exit code; observed assertion; log path]
After: [final revision or base + diff ID; command; exit code; observed assertion; log path]
Status: [pass / fail / blocked / not run]
Limits / reviewer action: [untested behavior, blocker, or decision required]
将失败和通过的每次运行分别关联到实际测试的代码状态,包括在原版本上仅为测试添加的改动。交接时一并保留日志、响应夹具和最终代码差异。如果最终版本有变动,就需要更新证据。未运行或受阻的检查不能计为通过。
让 Codex 将代码差异和以下审查材料保存在代码仓库中:
incident-investigation.md:时间线、证据引用、已检验的假设、有证据支持的原因,以及仍不确定的事项。test-evidence.md:基线提交、回归测试失败时的输出、修复提交或代码差异、已通过的针对性检查、更广泛的检查及局限性。pr-draft.md:简要说明缺陷、行为变化、测试证据和剩余风险。deployment-handoff.md:已验证的数据库模式、隔离级别和回执保留期假设,明确指定的发布负责人,部署前检查,重复订单、确认响应及错误指标,以及下文所述的发布和回滚条件。
接受补丁前,请确认原代码无法通过新测试、修复后能够通过,且代码改动确实解决了已证实的缺陷。在 webhook 示例中,请检查事件键的作用域、事务边界、并发测试覆盖情况,以及事务以外的影响。已有的重复订单应单独审查。防止新增重复订单并不能修复历史记录。
规划部署和回滚
代码补丁只能保护运行修正后处理程序的工作进程。旧工作进程仍可能先写入订单,再尝试插入回执取得处理权,因此混合版本的金丝雀发布不能证明缺陷已消除。
部署负责人必须选择经过测试的混合版本策略,或遵循已有操作手册,暂停接收事件,等待旧工作进程处理完在途任务,更新所有消费者,然后恢复投递已保留的事件,确保不丢失任何投递。
选择后一种方案前,请确认提供方和队列的重试及保留行为。不要假设暂停处理一定不会造成丢失。
恢复投递已保留的事件前,找出已经提交但没有匹配回执的历史订单。暂停接收并等待旧消费者处理完在途任务,可以阻止旧逻辑继续写入,但无法修复已有订单。使用现有队列或隔离流程,暂停每个受影响事件键的投递。如果历史记录不足以确定完整的事件标识,应继续暂停受影响的投递或受影响时间范围内的投递,交由负责人审查,不能宣布扫描已经完成。
只有当可信且不可变的提供方、账户和事件标识,加上规范化载荷证据和已提交的业务记录,足以确定此前实际执行了哪些操作时,才可对已暂停的事件键进行核对补录。
按照获批的核对补录流程,记录匹配的回执,不重复执行业务变更,然后解除对该键的暂停措施。
如果证据缺失、载荷冲突或存在多条业务记录,应继续隔离受影响的键,交由负责人审查。重建原始事件的指纹时,不能用重试载荷代替原始事件的可信证据。
只有当每个受影响的键都已完成核对补录,或其暂停措施仍对所有消费者有效时,才满足恢复投递的条件。
在预发布环境中预置一笔历史订单及其待处理的重试。验证暂停措施能阻止创建另一笔订单,并阻止返回任何成功确认。依据可信证据完成核对补录后,重试可以收到重复投递确认,订单数量仍为一笔。还要演练无法完成核对的情况,确保该键继续处于暂停状态,且不会凭空生成回执。将这一恢复条件连同暂停和排空、消费者版本、保留期及回滚检查一并写入部署交接材料。
发布前,请验证现有唯一约束存在且有效,所有消费者的回执键和载荷处理策略一致,清理回执不会使仍可能被重放的事件失去去重保护,并确认外部操作仍在此补丁的范围之外。
在预发布环境中演练所选流程,以及工作进程发生故障后的重试。记录负责人设定的观察窗口,以及重复订单、webhook 错误、确认响应延迟、锁等待和重试积压达到何种阈值时应停止发布。不要自行编造生产环境阈值。
回退到旧处理程序可能再次引发重复订单。回滚交接材料必须明确遏制故障的措施(例如获批的暂停和排空流程)、可安全使用的版本,以及决定何时恢复处理的负责人。保留回执,不要为了让重试继续而删除回执。历史重复订单的补救方案需要单独审查。
部署决策和生产环境的补救工作由工程师负责。隔离测试通过可作为审查证据,但不足以证明生产环境运行正常。请创建 Pull Request,执行常规 CI 和审查流程,并在审查草稿后按照团队既定的管控流程部署。
在同一任务中继续
使用有针对性的后续提示词来澄清疑点或完善交接材料:
请针对两种情况审查补丁:同一事件的两次投递并发到达,以及工作进程发生故障后重试。说明测试已验证哪些行为,还有哪些行为未经测试。只修改这个处理程序及其回归测试,并在交接材料中补充仍然存在的风险。
如果首次运行未能复现故障:
请停止实施修复。列出现有证据已排除的假设,并指出剩余假设中最有依据的一个。说明要将它与其他假设区分开来,最少还需要哪些脱敏资料,或需要做哪个最小规模的隔离实验。根因仍应标记为未确认。 相关使用场景
迁移验证模块
向 Codex 提供范围明确的迁移说明、契约测试夹具和已配置好的云端环境。让 Codex 升级一个验证模块,并交付本次迁移的代码改动、对外行为一致性的验证材料、尚存的差异和回滚步骤。
创建 Codex 能用的 CLI
请 Codex 创建一个可组合使用的 CLI。Codex 可以在任意文件夹中运行它,将它与代码仓库中的脚本配合使用,用它下载文件,并通过配套技能记住它的用法。
开发网页游戏
让 Codex 根据游戏设计概要制定清晰的开发计划,再按计划做出可玩的网页游戏。使用 imagegen 生成美术素材,让 Codex 在真实浏览器中试玩,逐步改进游戏操控和界面。