Claude Code插件开发入门从codex-plugin-cc学命令、Agent与Hook设计【免费下载链接】codex-plugin-ccUse Codex from Claude Code to review code or delegate tasks.项目地址: https://gitcode.com/GitHub_Trending/co/codex-plugin-cc一句话认识这个项目codex-plugin-cc 是什么codex-plugin-cc是 OpenAI 官方出品的Claude Code 插件让你直接在 Claude Code 里调用 Codex既能跑代码评审/codex:review又能把调试、修复类任务委派给 Codex 后台执行/codex:rescue。它同时提供了斜杠命令Commands、子代理Agent、生命周期钩子Hooks和内部技能Skills四类插件组件堪称学习 Claude Code 插件开发的一份活教材。本文带你拆解这个插件的完整架构一个plugins/codex/目录里命令、Agent 与 Hook 是怎么分工协作的。 插件目录结构一个组件齐全的参考实现打开仓库核心代码全部在plugins/codex/下结构非常清晰plugins/codex/ ├── commands/ # 8 个斜杠命令.md 文件 ├── agents/ # 1 个子代理 codex-rescue.md 文件 ├── hooks/ # hooks.jsonHook 注册表 ├── prompts/ # 提示词模板如 stop-review-gate ├── schemas/ # JSON Schema评审输出契约 ├── scripts/ # Node.js 运行时脚本真正的执行层 └── skills/ # 2 个内部技能SKILL.md它提供的命令包括/codex:review—— 只读代码评审/codex:adversarial-review—— 可指定关注点的对抗式评审/codex:rescue—— 把任务委派给 Codex 子代理/codex:transfer—— 把当前会话上下文迁移到 Codex/codex:status、/codex:result、/codex:cancel—— 后台任务管理三件套/codex:setup—— 环境检查与评审门禁开关整体思路可以概括为一句话Markdown 文件负责声明Node 脚本负责执行。下面逐个拆解。一、命令Commands设计YAML 头 行为剧本Claude Code 的斜杠命令本质是一个 Markdown 文件由YAML frontmatter声明区 正文行为剧本两部分组成。以 review.md 为例--- description: Run a Codex code review against local git state argument-hint: [--wait|--background] [--base ref] disable-model-invocation: true allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion ---这里藏着 4 个关键设计点allowed-tools最小授权只开放Bash(node:*)和Bash(git:*)把命令的手脚限制在最小范围——这是插件安全设计的第一原则。disable-model-invocation: true声明该命令只能由用户显式输入触发模型不会自己调用避免意外行为。$ARGUMENTS变量正文里用$ARGUMENTS原样接收用户参数并在剧本中要求不得改写用户意图。行为剧本用自然语言写死规则比如 review.md 中明确规定先估算 diff 规模 → 小规模推荐前台等待、大规模推荐后台运行 → 只用AskUserQuestion问一次且推荐项必须标注 (Recommended)。再对比 status.md它只用了一行!前缀命令直接执行脚本并渲染结果表格——简单命令不需要复杂剧本。命令复杂度与行为剧本长度成正比这是很实用的分寸感。二、Agent 设计codex-rescue的薄转发器模式子代理定义在 codex-rescue.mdfrontmatter 声明了它的身份--- name: codex-rescue model: sonnet tools: Bash skills: - codex-cli-runtime - gpt-5-4-prompting ---真正值得学习的是正文里的职责收窄设计Your only job is to forward the users rescue request to the Codex companion script. Do not do anything else.这个 Agent 被刻意做成一个薄转发器thin forwarding wrapper✅ 允许恰好一次Bash调用把请求转发给 codex-companion.mjs可用gpt-5-4-prompting技能把用户口语润色成更紧凑的 Codex 提示词❌ 禁止读文件、grep、轮询状态、拉取结果、总结输出等一切自作主张 输出把脚本 stdout原样返回不加任何评论为什么这样设计因为 Agent 一旦聪明起来就会绕过插件的运行时逻辑自己发挥导致状态管理失控。把 Agent 收窄成纯粹的协议转换层智能被推到两个地方上游的命令剧本rescue.md 负责--resume/--fresh路由判断下游的 Codex 本体真正干活。中间层越薄系统越可控——这是本插件最值得抄的设计。三、Hook 设计Stop钩子实现评审门禁插件的 Hook 注册在 hooks.json 中一共三类Hook触发时机作用SessionStart会话启动提供当前 transcript 路径供/codex:transfer使用SessionEnd会话结束清理会话生命周期状态StopClaude 准备停止时触发评审门禁让 Codex 复查上一轮的代码改动Stop钩子是亮点。执行脚本 stop-review-gate-hook.mjs 的工作流程是从 stdin 读取 Claude Code 传入的 JSON 上下文上一轮 assistant 消息、会话 ID、工作目录若未开启门禁stopReviewGate配置或 Codex 未就绪直接放行并打印提示否则加载提示词模板 stop-review-gate.md注入上一轮回复调起一次 Codex 评审解析结果第一行以ALLOW:开头则放行以BLOCK:开头则输出{decision:block}阻断 Claude 的停止让它先把问题修完这套设计的精髓在于输出契约化提示词里明确规定首行必须且只能是ALLOW: 原因或BLOCK: 原因Hook 脚本就能用简单的字符串前缀判断做机器决策而不需要再去理解一段自然语言。⚠️ 官方也提醒评审门禁可能形成 Claude/Codex 长循环、快速消耗用量只建议在有人盯守的会话中开启/codex:setup --enable-review-gate开、--disable-review-gate关。四、Skill 与运行时智能的收纳柜剩下的智能被收纳进了两个内部技能user-invocable: false用户不可直接调用codex-cli-runtime/SKILL.md规定 rescue Agent 调用task命令的完整契约——如何剥离路由标志位、--resume如何映射为--resume-last、spark如何映射为gpt-5.3-codex-spark等gpt-5-4-prompting/SKILL.md一套像操作员一样给 Codex 写提示词的方法论用 XML 标签task、grounding_rules等组装结构化提示词并配有 references/prompt-blocks.md 等参考文档真正的执行层是 scripts/ 目录下的 Node 脚本核心是codex-companion.mjs及其 lib/ 下的模块状态管理state.mjs、工作区解析workspace.mjs、进程管理process.mjs等它封装了 Codex app server 通信与作业生命周期。评审输出还有 JSON Schema 约束review-output.schema.json。五、5 条可直接抄走的设计要点声明与执行分离.md文件只做声明与编排重活全部交给scripts/里的脚本便于测试与维护最小工具授权每个命令/Agent 的allowed-tools/tools字段按需开放能只给Bash就不给全套Agent 保持薄把子代理做成协议转发器智能放在命令剧本和远端模型两端Hook 决策必须契约化要求下游模型输出机器可解析的固定格式如ALLOW:/BLOCK:首行而非自由文本内部知识用 Skill 沉淀不可用户调用的内部技能user-invocable: false是存放运行时契约和提示词工程规范的好位置 自己动手安装体验这个插件要求Node.js ≥ 18.18以及 ChatGPT 订阅含免费或 OpenAI API key。在 Claude Code 中依次执行/plugin marketplace add openai/codex-plugin-cc /plugin install codexopenai-codex /reload-plugins /codex:setup/codex:setup会检查 Codex 是否就绪缺失时还会引导安装。一个推荐的首次运行组合拳/codex:review --background /codex:status /codex:result后台发起评审 → 查看进度 → 取回结果完整走一遍命令 后台任务 状态管理的闭环。想深入阅读建议按这个顺序逛源码先读 README.md 了解全貌再依次精读commands/review.md、agents/codex-rescue.md、hooks/hooks.json三个文件——它们分别展示了命令、Agent、Hook 三种组件的标准写法读完你已具备开发自己的 Claude Code 插件的基础。【免费下载链接】codex-plugin-ccUse Codex from Claude Code to review code or delegate tasks.项目地址: https://gitcode.com/GitHub_Trending/co/codex-plugin-cc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考