[开源] 我做了一个 Codex 插件：不再靠 Prompt 约束 Agent，而是让 Hook 强制执行工作流

作者：#grapefruit0205 板块：#开发调优 本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容： 我的帖子已经打上 开源推广 标签： 是 我的开源项目完整开源，无未开源部分： 是 我的开源项目已链接认可 LINUX DO 社区： 是 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是 以上选择我承诺是永久有效的，接受社区和佬友监督： 是 以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出 最近用 Codex 这类 Coding Agent 时，我一直在想一个问题： 我们经常会在 Prompt 里告诉 Agent： 不要反复规划 不要重复扫描整个仓库 不要超出修改范围 已经成功的检查不要再跑一遍 只做真正需要的验证 但这些规则本质上都只是： “希望模型记得并且愿意遵守。” 上下文一长、任务一复杂，Agent 还是可能重新规划、重新扫描 Repository，或者把已经验证过的东西再验证一遍。 所以我换了一个思路： 既然 Prompt 只能建议行为，为什么不让 Hook 直接约束行为？ 于是我做了这个开源项目： Click GitHub： github.com GitHub - grapefruit0205/click: Codex plugin for coding agents that turns software... Codex plugin for coding agents that turns software requests into approved implementation contracts, then keeps implementation and verification inside the agreed boundary. 核心想法很简单 Prompts can suggest behavior. Hooks can enforce the workflow. Click 不只是给 Codex 塞一个更长的 Prompt。 它会先把软件修改请求整理成一个很小的执行契约： Request ↓ Compact Contract ↓ User Approval ↓ Implementation ↓ Current-revision Evidence ↓ Done 契约主要只有这些内容： outcome boundary must_hold build verification plain_language 也就是先确定： 最终要实现什么 哪些内容属于本次修改范围 哪些条件必须保持不变 大概怎么实现 什么证据足以证明任务已经完成 用户确认一次之后，再开始真正修改代码。 但我觉得 Click 最重要的部分不是“Contract”。 而是： Hook 会把这个 Contract 变成一个持久化的工作流状态机。 不是“请不要重新规划” 而是： update_plan ↓ BLOCKED 当 Click workflow 已经进入执行阶段后，如果 Agent 又触发匹配到的 update_plan，Hook 会直接拒绝。 同样，Repository 扫描也是这样。 第一次为了建立上下文，可以允许一次比较宽的 inventory。 之后如果 Agent 又想重新扫整个仓库： First broad inventory ↓ allowed Second broad inventory ↓ blocked Narrow inspection ↓ allowed 也就是说： 第一次理解代码库，之后逐步缩小范围。 而不是每隔几分钟重新 rg --files 一遍。 Approval 也由状态机控制 第一次用户提出需求，并不代表用户已经批准了一个还没看到的方案。 Click 会先 stage contract，并生成一个 contract_id： Request ↓ Stage Contract ↓ contract_id ↓ STOP ↓ Later user turn ↓ Approve ↓ Implementation unlocked 同一个 user turn 里不能直接： stage → pass Hook 会阻止这种情况。 只有后续 user turn 明确批准对应的 contract_id，实现阶段才会解锁。 Verification 也不是无限增长 Coding Agent 还有一个我经常遇到的问题： 为了“更确定”，测试越来越多。 于是 Click 把 Verification 也放进 Contract。 目前有三种预算： quick → 1 focused → 4 full → 10 每个验证来源都有自己的 evidence_id。 例如： { "version": 2, "checks": [ { "evidence_id": "E1", "argv": [ "python3", "-m", "pytest", "tests/test_cancel.py" ], "class": "targeted" } ] } 如果同一个验证在当前 code revision 已经成功： 不会再重复执行。 如果代码发生 mutation： revision N ↓ evidence success code changed ↓ revision N+1 ↓ old evidence = stale 这样 Hook 知道： 哪个 Revision 已经被什么 Evidence 验证过。 而不是只在 Prompt 里写一句： “不要重复跑测试。” 我还把命令执行做成了结构化 Capability Click 会区分： click-gate inspect click-gate mutate click-gate service click-gate verify 例如： click-gate inspect 明确表示这是读取操作。 click-gate mutate 明确表示这是可能修改工作区的操作。 click-gate verify 明确表示这是最终验证。 支持的 argv 会使用： shell=False 执行。 这里的目标不是做一个 OS Sandbox。 而是让 Hook 能够更明确地知道： Agent 现在到底是在读取、修改、启动服务，还是验证。 Click 不是在控制模型的“思考” 这个边界我觉得很重要，所以 README 里也明确写出来了。 Click 无法： 读取 hidden reasoning 知道模型是不是在自然语言里偷偷重新规划 观察所有外部 Connector / Hosted Tool 自动证明架构设计在语义上一定正确 替代真正的 OS Sandbox 替代人工 Code Review 它控制的是： observable tool path 所以我现在最喜欢用这句话解释 Click： The model decides how to implement. The Hook decides whether the workflow is allowed to move forward. 模型依然决定： “怎么写代码。” Hook 决定： “现在能不能进入下一步。” 为什么我觉得这个方向值得尝试 现在很多 Coding Agent Workflow 的优化思路还是： 写更好的 Prompt ↓ 再写更详细的 Prompt ↓ 增加更多规则 但随着 Agent 能力越来越强，我越来越觉得： 某些规则可能根本不应该继续放在 Prompt 里。 例如： Approval 是否发生 是否重复扫描 Repository 是否反复调用 Plan Tool Verification 是否重复 Evidence 是否已经过期 当前 Workflow 处于什么状态 这些其实更像： State Machine / Runtime Policy 而不是 Prompt Engineering。 所以 Click 想尝试的是： Prompt ↓ Intent Contract ↓ Boundary Hook ↓ State + Enforcement 当前状态 目前版本是 v0.24.5。 主要支持 Codex，同时也有实验性的 Google Antigravity Adapter。 CI 会在： Linux macOS Windows 上运行 deterministic Hook/runtime/policy tests，同时还有独立的 Plugin Security Scan。 项目还很新，我现在更想知道真实 Codi