scaffold-codex-hooks

scaffold-codex-hooks

先审查目标项目，然后围绕当前官方钩子模型，以确定性的托管布局搭建 Codex 钩子。

决策树

用户想做什么？

• 在尚未配置钩子的仓库中创建项目本地 Codex 钩子： 验证最新官方文档和架构，审查仓库，检查实际生效的功能标志，必要时启用，然后搭建钩子。
• 已存在 .codex/hooks.json、.codex/config.toml 或 .codex/hooks/ 文件： 先审查现有内容，选择 additive 或 overhaul，然后仅刷新托管的钩子层。
• 磁盘上存在钩子，但似乎从未影响 Codex： 先检查实际生效的 hooks 功能。如果仍处于关闭状态，则主动启用。如果已启用，请记住，项目本地的 .codex/config.toml 仅在受信任的项目中加载，然后调试 hooks.json。
• 只需解释，不需要实施： 阅读 references/hook-events.md、references/feature-flag.md 和 references/scaffold-layout.md，然后直接回答，不要搭建钩子。

快速参考

任务	操作
验证当前官方 Codex 钩子模型	阅读 https://developers.openai.com/codex/hooks、https://developers.openai.com/codex/config-basic、assets/hook-events.json 中列出的生成架构，以及该清单中的运行时源码链接
审查目标仓库	运行 scripts/audit_project.sh /path/to/project
检查实际生效的 hooks 功能	运行 python3 scripts/check_hooks_feature.py --project /path/to/project --json
审查/信任生成的钩子定义	搭建钩子或更改 .codex/hooks.json 后，在 Codex 中打开 /hooks
在项目配置中启用钩子	运行 python3 scripts/check_hooks_feature.py --project /path/to/project --enable --scope project
在用户配置中启用钩子	运行 python3 scripts/check_hooks_feature.py --project /path/to/project --enable --scope user
了解当前事件目录	阅读 references/hook-events.md
设计可复用的仓库自有脚本	阅读 references/reusable-scripts.md
决定采用增量添加还是全面改造	阅读 references/merge-strategy.md
生成或刷新托管的钩子脚手架	运行 `scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
将生成的处理程序合并到 .codex/hooks.json	让 scripts/scaffold_hooks.sh 调用 scripts/merge_hooks_json.sh，或直接运行合并脚本
在目标项目中重新生成钩子 README	运行 scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json

不可妥协的工作流程

1. 在规划任何脚手架前，先核实 Codex 官方钩子文档的最新内容。
2. 对照最新文档、当前架构和 assets/hook-events.json，确认事件集或输出契约是否发生变化。
3. 详细审查目标项目，再决定启用哪些事件或运行哪些命令。
4. 检查目标项目中的有效 hooks 功能状态，不要直接假定仓库本地的 hooks.json 已生效。
5. 如果该功能处于关闭状态，请在正确的范围内有意启用：
   • 共享仓库脚手架默认使用项目范围
   • 个人或全局钩子，或仓库不应提交 .codex/config.toml 时，使用用户范围
6. 在选择合并模式前，检查已有的 .codex/config.toml、.codex/hooks.json、.codex/hooks/、AGENTS.md、README* 和其他自动化文件。
7. 生成或更新具体的钩子计划 JSON。将项目特定的判断放入计划，而不是脚手架脚本，以保持脚手架的确定性。
8. 对于可能迁移到 Claude Code、OpenCode、Git 钩子、GitHub Actions 或本地 shell 使用的行为，优先采用仓库自有的共享脚本。生成的 Codex 钩子文件应作为这些脚本的轻量适配层。
9. 将所有当前官方事件都生成为托管钩子根目录下带注释的 bash 存根，即使 hooks.json 中仍禁用该事件。
10. 只将已启用的事件接入 .codex/hooks.json，让未启用的存根保持轻量。
11. 重新生成 .codex/hooks/README.md，确保目标项目始终有一份易读的事件说明。
12. 如果实际完成脚手架后钩子仍未激活，请重新检查有效功能状态，确认项目层已受信任，并在 /hooks 中检查并信任钩子定义。

优先检查功能的启发式规则

出现以下任一情况时，请尽早检查 hooks：

• 用户要求在仓库中搭建 Codex 钩子脚手架
• .codex/hooks.json 已存在，但似乎没有任何效果
• 用户不确定功能标志是否已开启
• 仓库本地存在 .codex/config.toml，但有效功能状态仍显示为关闭
• 现有配置使用旧版 codex_hooks 别名

按以下流程操作：

1. 首先规范化目标项目路径。
2. 运行 python3 scripts/check_hooks_feature.py --project /path/to/project --json。
3. 如果有效状态为关闭，请使用规范的 [features].hooks = true 有意启用该功能：
   • 共享的仓库本地设置使用 --scope project
   • 个人或全局设置使用 --scope user
4. 启用后重新运行检查。
5. 搭建脚手架或更改钩子定义后，使用 /hooks 检查并信任非托管命令钩子。
6. 只有完成以上步骤后，才开始排查 hooks.json、匹配器选择或钩子脚本逻辑。

优先查阅实时文档

Codex 官方文档是权威信息来源：

• https://developers.openai.com/codex/hooks
• https://developers.openai.com/codex/config-basic
• https://developers.openai.com/codex/config-reference

要确认准确的线级格式和当前解析器行为，还应查阅：

• https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/features/src/lib.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/features/src/legacy.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/lib.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/config/src/hook_config.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/engine/discovery.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/common.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/compact.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/permission_request.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/tools/hook_names.rs

如果文档与运行时源代码不一致，对于脚手架输入，应以有源代码依据的当前 CLI 行为为准，并记录文档偏差。根据当前清单，规范的功能键是 hooks；codex_hooks 是旧版别名。

https://reading.sh/codex-hooks-just-gave-you-back-complete-control-over-your-code-57d044bcae1b 上的文章可作为实用模式的辅助资料，但不能作为权威信息来源。早期关于 hook 的文章会随着功能演进而过时。

逐步维护偏差检查

更新此技能本身时，应将检查文档偏差作为维护的第一步：

1. 在编辑当天实时获取 Codex 官方 hook 文档、配置文档、生成的 schema 和运行时源代码，然后将事件名称、匹配规则、输入/输出约定、信任行为及功能标志与 assets/hook-events.json 进行比较。
2. 在可用时检查本地版本信息，例如 codex --version，并记录用于说明此次更新的 Codex 源代码提交或 schema URL。
3. 如果存在偏差，应一并更新整套脚手架内容：assets/hook-events.json、references/hook-events.md、功能标志和注意事项参考资料、脚手架生成器、模板、计划示例、验证器、测试、评估及轻量封装。
4. 如果没有偏差，也要说明已检查实时文档、schema 和源代码。不要凭记忆更新此技能，也不要照搬对 Claude Code 或 OpenCode 的假设。

项目分析规则

选择任何 hook 结构之前，请先检查：

• 仓库根目录和工作区结构
• 项目是否已有 .codex/config.toml、.codex/hooks.json 或 .codex/hooks/
• 编程语言和包管理器
• 构建、测试、lint、格式化和验证的入口
• 现有的仓库自有命令入口，例如任务运行器、包脚本、仓库中记录的框架命令、CI 作业、Make/Just/Taskfile 目标和本地脚本
• 可复用的 Agent 或自动化脚本，例如 <project>/scripts/agent-session-context.sh、<project>/scripts/agent-stop-checks.sh、适配器脚本、Husky hook 和 GitHub Actions 作业；这些应共享逻辑
• Turborepo、Nx、pnpm 工作区、Bun 工作区、Cargo 工作区或自定义任务运行器等 monorepo 工具
• 现有的 AI 指令，例如 AGENTS.md、项目规则或仓库自动化文档
• 现有的 Git hook、Husky、Lefthook 或 CI 门禁
• .env、密钥、锁文件、生成代码、迁移文件和基础设施目录等敏感路径
• hook 配置是否应放在仓库配置中以便共享，还是仅保留在用户本地

先运行 scripts/audit_project.sh，需要完整检查清单时再阅读 references/project-analysis.md。

确定性与项目特定工作

以下部分应保持确定性：

• 托管钩子根路径
• 事件存根文件名
• 生成的 hooks.generated.json 结构
• 先前托管钩子的合并行为
• 钩子 README 的生成
• 覆盖当前每个官方 Codex 钩子事件的事件清单
• 功能标志的检查和报告

以下部分允许因项目而异：

• 启用哪些事件
• 受支持事件的匹配器正则表达式
• 超时和状态消息
• 事件在运行自定义钩子逻辑前应运行的已配置仓库命令
• 事件在运行自定义钩子逻辑前应委托执行的可复用仓库脚本
• 功能启用配置应放在项目配置还是用户配置中
• 已启用事件脚本中的实际逻辑
• 刷新模式是 additive 还是 overhaul

重复运行规则

再次针对项目调用此技能时：

• 重新核验实时文档和架构定义，再判断事件集是否未发生变化。
• 重新审计项目，再判断当前钩子计划是否仍然适用。
• 重新检查有效功能状态，再判断仓库本地钩子是否处于启用状态。
• 默认保留非托管钩子。
• 在 overhaul 模式下，将托管根目录下先前生成的钩子视为可替换内容。
• 在 additive 模式下，将先前生成的钩子视为仅追加内容，除非托管层或 README 已过时。
• 如果官方事件集或解析器规则发生变化，先更新脚手架输入。

脚手架规则

• 为托管运行时钩子存根生成 bash 脚本，而非 Python 脚本。
• 在生成的 bash 存根中注释说明该事件特定的输入和输出约定。
• 将生成的事件脚本组织为 main() 加上一个 handle_event() 编辑入口，方便人和 Agent 快速了解控制流。
• 支持钩子计划中的语言无关 scripts 条目，用于可复用的仓库自有脚本；同时支持 commands 条目，用于现有仓库命令。不要在生成的脚本中硬编码包管理器、框架或示例工具链。
• 将共享行为放在与路径无关的仓库脚本中，通常位于 scripts/ 下；当输出协议不同时，传入 codex 之类的运行框架参数。生成的事件存根应保持精简。
• 默认将 .codex/hooks/generated 设为托管根目录。
• 默认将 .codex/hooks.json 设为钩子文件目标。
• 对于共享仓库脚手架，默认在 .codex/config.toml 中启用 hooks。
• 只有在钩子设置应保持个人专用或仅限本机时，才使用 ~/.codex/config.toml。
• 为每个官方事件保留一个托管脚本，使事件映射一目了然。
• 保持合并后的 hooks.json 具有确定性：只移除先前托管的处理器，绝不移除无关的自定义钩子。
• 绝不要假设 async、prompt 或 agent 钩子目前可用。当前运行时会跳过它们。
• 将 PreToolUse、PermissionRequest 和 PostToolUse 视为特定工具路径的钩子。当前支持 Bash、带有 Edit/Write 匹配器别名的 apply_patch，以及在这些路径提供钩子负载时的 MCP 工具名称；但仍不支持 WebSearch 或所有可能的 shell 路径。
• 将 SubagentStart 和 SubagentStop 视为特定 Agent 类型的钩子。对于 SubagentStop，decision: "block" 会让子 Agent 继续执行，而非让父轮次继续。
• 将 PreCompact 和 PostCompact 视为由压缩触发的钩子。它们的匹配器值为 manual 和 auto。
• 谨慎处理 Stop。对于该事件，decision: "block" 表示“使用这条新提示词继续 Codex”，而非“拒绝该轮次”。

阅读指南

需求	阅读
完整的审计清单和规划问题	references/project-analysis.md
如何安全地检查和启用 hooks	references/feature-flag.md
当前有源码依据的事件列表、匹配器支持情况和输出语义	references/hook-events.md
托管文件夹布局和计划文件结构	references/scaffold-layout.md
Codex、Claude Code、OpenCode、Git 钩子和 CI 中的可复用脚本放置位置	references/reusable-scripts.md
增量式与全面改造的行为	references/merge-strategy.md
运行时限制、文档过时问题和失效开放陷阱	references/gotchas.md

运维脚本

• scripts/audit_project.sh 根据仓库的实际信号构建项目概况。
• scripts/check_hooks_feature.py 检查或启用用户配置或项目配置中的 hooks。
• scripts/scaffold_hooks.sh 生成托管钩子树、清单、片段、README 和功能设置。
• scripts/merge_hooks_json.sh 保留非托管处理程序，同时替换之前托管的处理程序。
• scripts/render_hooks_readme.sh 根据清单和当前计划重新生成 .codex/hooks/README.md。
• scripts/validate.py 检查结构、frontmatter、清单完整性和交叉引用。
• scripts/test_skill.py 运行轻量级验证以及临时项目集成检查。

注意事项

1. 功能键是 hooks；codex_hooks 只是旧版别名。编辑配置时请使用规范键。除非配置或策略将钩子关闭，否则目前默认启用钩子。
2. UserPromptSubmit 和 Stop 会忽略 matcher。不要设计依赖这些匹配器的逻辑。
3. async、prompt 和 agent 可以解析为配置形式，但当前运行时会跳过它们并发出警告。
4. 同一事件下多个匹配的命令钩子会并发运行。一个钩子无法阻止另一个匹配的钩子启动。
5. PostToolUse 无法撤销命令产生的副作用。它最多只能替换 Codex 接下来看到的反馈。
6. Stop 中的 decision: "block" 会让 Codex 带着新提示词继续运行，而不是拒绝此轮对话。
7. SubagentStop 中的 decision: "block" 会让子 Agent 带着新提示词继续运行。请遵循 stop_hook_active，以避免循环。
8. 仅当项目受信任时才会加载仓库本地的 .codex/config.toml。如果你在项目范围启用了此功能，但项目不受信任，那么该功能的实际状态仍可能显示为关闭。
9. 非托管命令钩子必须先在 /hooks 中审核并信任，才能运行。
10. 生成的架构目前列出了十种钩子事件，包括 SubagentStart 和 SubagentStop。早期文档和文章描述的事件集较小，因此每次实际生成脚手架时，都要重新检查官方文档、架构和运行时源码。
11. 不要将可复用的验证或上下文逻辑埋在生成的 .codex/hooks/generated/events/*.sh 文件中。应将其放在仓库自有的脚本中，再让 Codex 钩子将这些脚本用作适配器。