SuperAPI AI 工具集

protected-commit

编程与开发

查看项目

更新于 10-15 22:12

技能介绍

用途:当提交因“Protected state edit detected”被拒,或在编辑 AGENTS.md、CLAUDE.md、锁文件、.forge/config.yaml、.github/workflows 等受保护文件前,使用本技能了解门禁机制与正确做法。

主要能力:说明门禁由 scripts/protected-state-check.js 在每次 pre-commit 运行(lefthook 作业 protected-state,无 glob),对每个暂存文件调用 assertProtectedWriteAllowed;匹配受保护表面的文件需要一次性、内容绑定的 Kernel 能力,绑定到确切的 actor、worktree、surface、path、bytes 和 source HEAD。可用命令查询某路径所属表面:node -e "console.log(require('./lib/protected-state-surfaces').assertProtectedWriteAllowed('AGENTS.md'))"。

常见误解:FORGE_PROTECTED_STATE_ALLOWED_SURFACES 不授权任何操作,运行时无代码读取它;.forge/protected-paths.yaml 的 categories 块不是实际执行依据,运行时使用 lib/protected-state-surfaces.js 中硬编码的 PROTECTED_SURFACES 列表;--no-verify 不是答案,绕过钩子被禁止。

被阻止时的流程:读取被阻止输出中的 path、requiredSurface、reason、repairHint;通过拥有该文件的命令重新生成(锁文件用包管理器,.forge/config.yaml 用 Forge config/setup,harness 镜像用 forge setup,.beads/** 用 forge migrate --from beads 再执行 Forge issue 命令);只暂存该命令产生的字节,后续任何改动都会使授权失效。若没有命令能产生所需变更,应停止并提交 kernel issue,说明路径、表面和缺失的写入器,不得发明豁免或削弱检查。

已知不可达路径(2026-08-13):AGENTS.md 归类为 generated_harness,唯一能签发受保护状态授权的命令是 forge release generate-npm-workflow,因此目前无法提交 AGENTS.md 编辑,包括产品建议用户写入的 USER:START/USER:END 块内的编辑。应视为已记录的产品缺陷,而非绕过对象。

完成标准:提交因拥有命令产生字节而通过门禁,或已提交 issue 并如实报告阻塞,未发布绕过方案。