【Codex with ChatGPT 源码学习②】694 行 SKILL.md：Markdown 怎么指挥 Codex 干活？

【Codex with ChatGPT 源码学习②】694 行 SKILL.mdMarkdown 怎么指挥 Codex 干活系列说明本文是对社区开源项目 XiaoDuoYa/codex-with-chatgpt 的技术解读非 OpenAI 官方教程、非该项目维护者发布的文档。研究基于 2026-10-22 可访问的main分支分支内容会变化建议阅读时核对具体 commit。证据标记[源码]表示能从对应源文件确认[文档]是项目约定[推断]为技术分析[建议]为改进方案不能误当作已经实现的能力。文中命令和请求示例若未专门注明均为教学示例并非实际执行结果。推荐 CSDN 标签CodexAgent SkillMarkdownAI Agent工作流源码精读Agent 编排状态机Codex 执行机制摘要解读 Skill 元数据、触发、Golden Rules、CLI、浏览器规则和恢复步骤解释“模型解释规程”与“程序强制规则”的区别。本章以仓库main分支当前公开的skill/SKILL.md为依据结合docs/protocol.md和docs/architecture.md分析。本章最重要的问题一个 Markdown 文件为什么能让 Codex 操作浏览器、启动服务、维护任务状态、调用 ChatGPT 并反复修改代码答案是SKILL.md并不直接执行这些操作它是交给 Codex Agent 解释的一套操作规程。真正的操作由 Codex 已经具备的工具、C2C CLI 和 Node.js Bridge 完成。一、先建立 Skill 的完整心智模型这有点类似传统软件中的Agent 系统传统软件中的类比SKILL.md操作规程 工作流定义Codex 模型解释规程并做决策的控制器Codex Harness工具运行时c2cCLI服务管理及状态操作接口MCP Bridge数据访问服务docs/protocol.md通信协议规范Session / Checkpoint持久化状态但这个类比有一个重要边界Codex 并不是确定性的脚本解释器。它通过模型理解和执行指令可能出现理解偏差、工具失败或者执行步骤遗漏。因此Skill 的约束属于 Agent 行为约束而文件系统沙箱、OAuth、权限检查等才属于软件层面的强制边界。二、SKILL.md的实际结构源码仓库的main分支版本约有 694 行。为了便于研究可以按职责分成以下部分。源码区域内容主要解决的问题1–8YAML 元数据如何发现 Skill9–96定位与 Golden RulesCodex 应遵循哪些规则97–167In-app Browser如何使用内置浏览器168–211Locations / Update如何定位程序及更新212–343Connection / Setup如何初始化 MCP 连接344–468Conversation Management如何管理 ChatGPT 会话469–591Coding Task如何完成开发闭环592–609Media Workflow如何处理图片、视频产物610–末尾Disconnect / Recovery如何断开和恢复连接其中有五部分尤其值得深入Skill 触发、浏览器调用、CLI、状态机、任务执行。三、第一部分Skill 是如何触发的3.1 YAML Frontmatter文件开头的真实定义是--- name: codex-with-chatgpt description: Use ChatGPT (web) as the planning and review brain for Codex coding sessions, while Codex keeps full execution ownership. Use when the user says 使用 Codex with ChatGPT ... / Set up Codex with ChatGPT / 用 ChatGPT 规划, when they ask to connect ChatGPT to the current workspace, disconnect it, or run a task through the ChatGPT planning loop. ---这是整个 Skill 的入口。name是 Skill 标识description是帮助 Agent 判断何时应该使用该 Skill 的文字描述。这里有一个重点它不是传统意义上的关键词触发器。例如传统软件可能采用if 使用 Codex with ChatGPT in user_message: run_c2c()但 Skill 的工作方式不是这么简单。Codex 会根据当前可用 Skill 的描述、用户任务和上下文判断是否采用这个 Skill。用户也可以显式指定使用它。3.2 三种常见触发方式用户输入预期行为“使用 Codex with ChatGPT 完成登录模块”匹配 Skill 并启动协作工作流“帮我连接 ChatGPT 到当前工程”进入连接配置工作流“用 ChatGPT 规划当前开发任务”可能根据描述匹配该 Skill注意这里说的是 Skill 作者定义的预期行为不是对每个 Codex 版本都能成功触发的保证。3.3 Skill 安装的位置源码给出了两项关键路径codex-home/ └── skills/ └── codex-with-chatgpt/ └── SKILL.mdCodex Home 的解析规则为如果设置了 CODEX_HOME 使用 CODEX_HOME 否则 Linux/macOS: ~/.codex Windows: %USERPROFILE%\.codex项目安装时还会把源码中的ACTUAL_CHECKOUT_PATH替换成实际的仓库路径。因此必须区分Skill 安装目录供 Codex 发现和读取。C2C 源码目录保存 TypeScript、CLI 和 Bridge 实现。用户 WorkspaceCodex 真正要开发的工程。这三个目录可以完全不同。四、第二部分Golden Rules 是什么源码第 19–96 行定义了几条核心规则。它们不是业务逻辑本身而是整个协作系统的行为约束。其中最重要的是以下几类。4.1 Codex 保留执行权源码明确规定 Codex 负责编辑代码Shell 命令Git 操作测试错误恢复ChatGPT 负责高层规划、代码理解、审查和调试策略。这意味着 ChatGPT 返回的是计划Codex 再将计划转化为实际工具调用。4.2 不通过聊天消息传输源码Skill 要求不把文件正文、Diff 和日志粘贴进 ChatGPT 对话而是让 ChatGPT 通过 MCP 自主查询。目的有三个控制消息更短。避免重复传输大量相同内容。ChatGPT 能按需读取最新版本的文件而不是只依赖某一次聊天里的旧副本。需要强调文件内容仍然会经由 MCP 发送给 ChatGPT并不是始终留在本地。4.3 浏览器认证限制规则要求不能直接操作 OAuth Token、Cookie 或 Session Storage浏览器中自动输入的凭证只限于项目定义的配对码。这是一种降低凭据暴露风险的设计但不是绝对的安全保证。4.4 浏览器类型限制这是仓库比较特殊的地方。它明确指定control-in-app-browser要求使用 Codex 的iab浏览器能力不允许把普通外部 Chrome、Edge 或 Safari 当成默认执行环境也要求避免截图坐标点击式 Computer Use。所以不能简单地说这个项目就是用 Playwright 操作 Chrome。更准确地说它使用 Codex 内置浏览器的控制 API底层某些操作可能使用 Playwright 风格的 DOM 能力。4.5 Doctor Gate启动正式协作前需要确保本地 Bridge、MCP、隧道及连接状态满足条件。逻辑上类似检查环境 │ ├── 正常 → 允许 ChatGPT 协作 │ └── 异常 → 修复或中止这是一个非常值得借鉴的设计把运行环境是否就绪变成执行任务的前置条件。但源码中的“静默修复”和自动更新也意味着存在自动修改本地配置的行为。对正式工程建议增加人工确认及版本固定机制。五、第三部分Codex 如何真正操作 ChatGPT 浏览器这是整个 Skill 中最容易被误解、也最有技术研究价值的部分。5.1 不是 Skill 自己打开浏览器源码第 97–105 行规定Codex 应调用内置浏览器能力。核心 API 形态是// 以下是从 SKILL.md 摘出的关键调用 setupBrowserRuntime(); const iab await agent.browsers.get(iab);iab是 in-app browser 的标识。从软件架构角度可以理解为SKILL.md │ ▼ 指导 Codex Codex Agent │ ▼ 调用浏览器工具 Browser Runtime │ ▼ 浏览器交互 ChatGPT Web UISkill 只告诉 Codex 应调用什么接口实际浏览器能力由运行环境提供。需要注意SKILL.md的这些 API 不能单独复制到普通 Node.js 程序中运行。它们依赖相应的 Codex 浏览器运行时。5.2 浏览器 Tab 的生命周期Skill 规定了一个很有意思的设计整个 Codex Session 尽量复用同一个 ChatGPT 标签页。关键操作包括// 概念性片段仅保留核心 APIconsttabawaitiab.tabs.new();awaittab.goto(https://chatgpt.com/);awaittab.markHandoff();awaittab.markDeliverable();其中方法在项目中的用途tabs.new()首次建立 ChatGPT 标签页tab.goto()导航到指定页面markHandoff()标记交互任务需要保持浏览器状态markDeliverable()标记应该保留的工作页面visibility.set(true)使内置浏览器对用户可见最后两种标记不是标准浏览器 Web API而是特定浏览器运行环境的能力。5.3 Codex 如何发送和接收消息SKILL.md没有定义一个普通的 HTTP ChatGPT API 调用而是要求 Codex 使用浏览器页面的交互能力。概念上发送消息可分为四步1. 找到 ChatGPT 输入区域 2. 输入 C2C 协议消息 3. 提交消息 4. 检查页面是否出现相应回复源码还要求尽量使用 DOM 检查而不是持续截图。每次发送后保持同一浏览器标签页。如果页面仍在生成回复不要重复发送。浏览器超时不等于 ChatGPT 没有收到消息。识别STATE: PLAN、STATE: DONE或STATE: BLOCKED后再继续。这些约束的目标是避免重复执行任务。不过它们仍然属于基于网页 UI 的交互机制不能获得官方模型 API 那样明确的请求 ID、响应结构和交付语义。这也是该项目的一项主要架构弱点。六、第四部分c2cCLI 在系统中承担什么理解了 Skill 和浏览器之后就要研究另一半传统软件程序。源码指定的命令入口为nodecheckout/bin/c2c.jscommand或者安装了全局命令后c2ccommandSKILL.md并不自己创建 MCP 服务器而是让 Codex 执行 CLI 命令进而调用项目的 TypeScript/Node.js 实现。6.1 主要 CLI 分工CLI用途c2c setup初始化 Workspace Bridgec2c doctor检查并修复连接环境c2c prefs保存机器级配置偏好c2c tunnel status检查公网隧道状态c2c pair生成连接配对码c2c session读取当前会话状态c2c session set更新会话状态和 Checkpointc2c record记录任务执行结果c2c unpair撤销连接授权例如假设 Codex 正在开发的项目位于E:\Projects\demo它可以执行c2c doctor-w E:\Projects\demo--json c2c session-w E:\Projects\demo--json其中-w指的是被开发的 Workspace而不是 C2C 工具自己的仓库目录。-json的作用是让 Codex 更容易读取机器可解析的状态。6.2 第一次连接如何建立根据SKILL.md的 Setup 工作流过程大致如下检查 Node.js、cloudflared和 C2C 构建产物初始化本地 Bridge 和对应 Workspace配置公网隧道得到 MCP Server URL在 ChatGPT 创建对应的 MCP 连接通过 OAuth 和临时配对码完成授权在 ChatGPT 中调用workspace_info验证正确的 Workspace保存连接和会话记录进入 Ready 状态这里必须区分两种授权ChatGPT 网页登录用户用自己的 ChatGPT 账户登录以使用 ChatGPT 服务。MCP OAuth 授权ChatGPT 作为客户端获得访问本地 C2C Bridge 的权限。两者不是同一套认证机制也不应共享密码或 Token。源码还规定首次配置可以选择自动或手动引导并且一个 Workspace 只绑定一个特定的连接。七、第五部分真正的核心——任务状态机前面的组件负责“能不能连接”状态机负责“连接后怎么工作”。源码的 Coding Task 工作流位于第 469–591 行是整个 Skill 最值得仔细学习的部分。7.1 状态机不是一个一直运行的 JavaScript 循环例如项目并没有简单地定义while(true){constplanawaitaskChatGPT();awaitexecute(plan);}相反状态转换由 Codex Agent 按 Skill 执行配合浏览器消息和本地 Session Checkpoint 记录。状态流是再看每个状态由谁产生状态产生者含义INITCodex发起任务PLANChatGPT返回可执行计划EXECUTINGCodex正在执行EXECUTEDCodex当前迭代执行完成REVIEWChatGPT正在通过 MCP 审查通常是隐含阶段DONEChatGPT建议结束任务BLOCKEDChatGPT存在阻塞需要处理ERROR任意一方协议或基础设施故障HANDOFFCodex将任务交接给新 ChatGPT 会话这里的DONE是 ChatGPT 根据检查结果给出的协议结论并非数学意义上的代码正确性证明。7.2 状态机还分两个层次这个设计比看上去复杂一点。第一层跨 Agent 通信状态通过 ChatGPT 对话中的[C2C]消息传递。第二层Codex 本地 Checkpoint记录当前已经执行到哪一步例如PLAN_RECEIVEDEXECUTINGEXECUTED_LOCALEXECUTED_SENT为什么要这么做假设 Codex 已经执行了数据库迁移但在准备向 ChatGPT 发送EXECUTED时崩溃了。重新启动后系统不能直接重新执行数据库迁移否则可能造成重复操作。如果 Checkpoint 显示EXECUTED_LOCAL则应继续发送执行结果而不是重新执行刚才的任务。这类似分布式任务系统中的持久化检查点机制但其实际可靠性仍取决于状态写入的时机、原子性和外部操作的幂等性。八、第六部分用一个真实开发任务完整模拟我们用 Python 工程的“增加 CSV 导出功能”来模拟一次完整任务。假设当前目录demo-project/ ├── src/ │ ├── report.py │ └── data.py ├── tests/ │ └── test_report.py ├── README.md └── pyproject.toml以下是教学模拟消息不是已经实际运行的记录。第一步Codex 发起 INIT用户输入使用 Codex with ChatGPT为当前项目增加 CSV 导出功能。Codex 通过 Skill 匹配 Coding Task 工作流先检查 Bridge再在 ChatGPT 浏览器中发送[C2C] STATE: INIT TASK_ID: c2c_a123 ITERATION: 0 GOAL: 为报表模块增加 CSV 导出功能。 INSTRUCTION: 通过 MCP 分析当前工程 生成下一轮可执行开发计划。注意消息中没有源码。第二步ChatGPT 读取项目ChatGPT 收到请求后理论上可以按需调用这些 MCP 工具workspace_info ↓ list_directory(src) ↓ read_file(src/report.py) ↓ read_file(tests/test_report.py) ↓ git_status这些调用由 ChatGPT 工具系统发往 MCP Bridge而不是由 Codex 复制文件内容。第三步ChatGPT 返回 PLAN[C2C] STATE: PLAN TASK_ID: c2c_a123 ITERATION: 1 GOAL: 实现 CSV 报表导出。 RATIONALE: 当前模块已有数据查询能力 可以在现有报表接口上扩展。 ACTIONS: 1. 在 report.py 增加 CSV 导出函数。 2. 使用标准 csv 模块进行编码。 3. 添加空数据、特殊字符测试。 FILES_LIKELY_INVOLVED: src/report.py tests/test_report.py TESTS: pytest tests/test_report.py SUCCESS_CRITERIA: CSV 内容正确原功能不回归。收到 PLAN 后Codex 更新本地 Checkpointc2c session set -w E:\Projects\demo-project --protocol-state PLAN_RECEIVED --waiting-for none --next-step execute PLAN这一步的意义是即使 Codex 进程随后重启也知道当前已经取得计划。第四步Codex 执行计划Codex 进入EXECUTING使用自己的编辑和终端工具修改文件。例如生成importcsvimportiodefexport_csv(rows):outputio.StringIO()writercsv.writer(output)writer.writerows(rows)returnoutput.getvalue()接着运行python-m pytest tests/test_report.py-q假设测试结果为8 passed注意 ChatGPT 并没有直接执行这些动作。第五步Codex 记录结果源码要求通过c2c record写入执行记录c2c record-w E:\Projects\demo-project --task c2c_a123 --iteration 1 --changed-filessrc/report.py,tests/test_report.py--tests8 passed--exit-statusok若同时保存测试输出还可以指定--command、--output-file和--exit-code。Bridge 将执行记录提供给 ChatGPT但会按照本地安全规则限制日志内容。随后 Codex 更新状态为EXECUTED_LOCAL并通过浏览器向 ChatGPT 发送简短消息[C2C] STATE: EXECUTED TASK_ID: c2c_a123 ITERATION: 1 RESULT: Execution finished. CHANGED_FILES: 2 TESTS: 8 passed Please review the current git diff and execution records through MCP.第六步ChatGPT 独立审查ChatGPT 使用 MCP 读取git_diff test_status execution_summary execution_output假设审查发现 CSV 导出没有正确处理 UTF-8 BOM而用户的需求明确要求兼容某些 Excel 导入场景。ChatGPT 不应该直接返回DONE而应给出下一轮PLAN说明为什么需要修改、修改哪里以及如何验证。Codex 随后执行第二轮。最终审查通过ChatGPT 返回[C2C] STATE: DONE TASK_ID: c2c_a123 ITERATION: 2 SUMMARY: CSV 导出功能已实现 相关测试和审查已完成。Codex 清理当前任务 Checkpoint并向用户汇报。九、第七部分断线恢复是如何实现的这部分体现了项目作者对长时间 Agent 工作流的考虑。假设 Codex 在任务执行过程中退出再次启动时c2c session-w E:\Projects\demo-project--json可能读取到类似这样的概念性状态{taskId:c2c_a123,iteration:2,protocolState:EXECUTED_SENT,waitingFor:GPT_REVIEW}这里展示的是便于理解的字段示例并非声称完整 CLI 响应恰好具有这一 JSON 结构。Codex 根据状态做不同处理Checkpoint恢复策略INIT等待已经发送的 PLANPLAN_RECEIVED继续执行已收到的计划EXECUTING检查并继续当前执行阶段EXECUTED_LOCAL不重复执行只发送结果EXECUTED_SENT不重复发送等待 ChatGPT 审查DONE汇报结果并清理 CheckpointBLOCKED保留阻塞信息等待处理还有一个专门的HANDOFF协议。当原来的 ChatGPT 会话丢失或需要切换时Codex 可以创建新会话并发送简短的任务交接说明。新的 ChatGPT 会话再通过 MCP 查询当前代码不需要将整个旧对话复制过来。但是这里还缺少一个严格保证考虑一个更极端的问题Codex 已经在 ChatGPT 网页按下发送按钮但还未来得及写入EXECUTED_SENT程序就崩溃了。重新启动时Checkpoint 和网页的真实状态可能不一致。这就是经典的分布式系统难题消息交付和状态持久化之间存在失败窗口。要达到强可靠性通常还需要唯一消息 ID 和幂等处理明确的消息接收确认状态持久化与外部副作用的恢复策略防止重复执行非幂等命令。C2C 的 Task ID、Iteration 和 Checkpoint 提供了部分基础但不应将其理解为已经实现严格的 exactly-once 执行语义。十、第八部分从软件架构角度重新理解 Skill现在可以回答一个更深入的问题为什么作者选择写一个 694 行左右的 Skill而不是全部使用 TypeScript 编写一个工作流程序因为作者希望利用 Codex 已经具备的 Agent 能力。传统程序需要明确规定每一步的控制逻辑planrequest_plan()filesparse_files(plan)modify_files(files)resultrun_tests()reviewrequest_review(result)而使用 Skill可以让 Codex 理解高层指令自主选择如何修改文件、调用哪些测试命令以及如何处理普通工程错误。两种架构各有优劣维度Skill 驱动确定性工作流引擎开发灵活性高取决于设计适配未知工程较容易通常需要适配状态可预测性较弱较强错误恢复依赖模型和持久化机制可以严格实现自动化测试Agent 行为不容易完全复现相对容易安全边界不能只依靠提示词可由程序强制长期维护指令与工具均可能变化接口契约更明确因此可以把这个项目看作一种Agent 驱动编排 传统服务支撑的混合架构。对于普通开发任务这种模式很灵活对于需要严格冻结、可重复验证和审计追踪的工程则需要把关键状态转换、验证门禁和权限判定尽可能落实到程序代码。十一、三个值得特别关注的源码设计第一自动更新机制。SKILL.md要求在工作流入口检查更新发现新版本后执行git pull、安装依赖、构建并重新安装 Skill。这很方便但对要求版本固定的工程来说存在供应链及可重复性风险。第二ChatGPT Project 与 Workspace 映射。 新工程默认采用一个 Workspace 对应一个 ChatGPT Project 和一个 MCP 连接而新的 Codex 对话可以在同一个 Project 内创建新的 ChatGPT 会话。这有助于任务隔离和上下文管理却仍需要严格校验连接是否指向正确的 Workspace。第三不向用户展示内部技术细节。 Golden Rules 要求 Codex 尽量不向最终用户展示 MCP、OAuth、端口等内部信息。这有利于简化普通用户体验但不适合直接照搬到开发、调试和安全审计模式。工程人员应能查看连接目标、权限变更、执行日志和失败原因。这些都属于 Skill 作者设计的行为规则而不是 Codex 平台本身的强制规定。十三、Markdown 怎么指挥 Codex 干活13.1. 先看文件定位[源码]skill/SKILL.md在核对时约 694 行开头采用 YAML frontmatter---name:codex-with-chatgptdescription:Use ChatGPT (web) as the planning and review brain for Codex coding sessions...---这里name提供技能标识description帮助 Codex 根据任务判断是否使用。它不是简单的if 关键词 in 用户输入脚本用户也可以明确指定 Skill。13.2. Skill 的作用和局限用户目标Codex Agent 发现并选择 Skill模型解释 SKILL.md 指令调用 Codex Harness 工具C2C CLI内置浏览器文件编辑 / Shell / Git本地 Bridge 与会话状态ChatGPT WebSkill 是操作规程而不是独立 HTTP 进程、插件二进制或模型权重。它可规定“执行c2c doctor”但执行命令依赖 Codex 的 Shell 权限规定“不要泄露秘密”也不能替代真实的文件权限控制。13.3. Golden Rules 的工程含义[文档] Skill 要求源码和日志通过 MCP 按需读不复制进浏览器消息Codex 保留编辑、Shell、Git、测试权ChatGPT 负责规划审查通过内置浏览器iab操作页面异常先检查本地服务必要时进入人工配置不同 Workspace 使用独立连接。这些规则体现出模型决策层与软件执行层的分工。它们是对 Codex 的行为要求并不构成 OS 级强制沙箱。13.4. CLI 为什么重要[文档] 常用命令包括c2c doctor--json c2c session-w E:\demo--json c2c record-w E:\demo--task c2c_f81a--iteration 1 --changed-filessrc/report.py--tests8 passed--exit-statusokc2c doctor用于检查连接和环境c2c session查询本地会话c2c record将执行结果写入可由 MCP 读取的记录。具体命令选项以当前版本 CLI 帮助为准上面路径只是示例。13.5. 为什么 Skill 要区分会话与任务同一个 Browser Tab、ChatGPT Conversation、Workspace 和 Codex Task 不是同一对象。[文档] Skill 定义long-chat与project两种会话复用模式每个工作区应有明确的 ChatGPT 连接。Task ID 用于标识一次任务Iteration 标识其中某轮Checkpoint 则用于断点恢复。这些内容在第六篇深入拆解。13.6. 自动修复与自动更新的两面性遇到故障时Skill 希望 Codex 执行检查和修复部分入口还涉及版本更新。它可以降低新手配置成本但[建议]正式环境锁定源码 commit、依赖版本和 Skill 版本升级经过审查后再执行。13.7. 最小思考练习问SKILL.md中写着“必须读取 Git Diff 才能给出 DONE”能否保证执行答不能单靠文本保证。需要独立 Verifier 检查是否真的读取并审查了目标 Diff且测试与交付规则真正满足要求。十四. 小结Skill 的核心价值是将复杂 Agent 协作规程封装成可加载的文本。下一篇将拆解它依赖的iab浏览器控制运行时。源码阅读SKILL.md版权与引用本文为独立整理与分析引用项目名称、接口名称和少量必要代码片段以解释技术原理原项目的代码许可证为 MIT。本文不代表原作者或 OpenAI 的立场。转载请保留原项目地址及本文出处。系列导航参见同一系列的「导读」及其他章节。ChatGPT 负责思考Codex 负责干活从源码读懂 Codex with ChatGPT系列导读【Codex with ChatGPT 源码学习①】整体架构为什么要分离控制平面与数据平面【Codex with ChatGPT 源码学习②】694 行 SKILL.mdMarkdown 怎么指挥 Codex 干活【Codex with ChatGPT 源码学习③】iab、DOM、PlaywrightCodex 如何操作 ChatGPT 网页