
关于
事实强制门控,在允许操作前阻止 Edit/Write/Bash 并要求具体调查(导入器、数据 Schema、用户指令)。相比无门控代理可衡量地提升输出质量 +2.25 分。
name: gateguard description: 事实强制门控,阻止Edit/Write/Bash(包括MultiEdit)操作,要求在允许操作前进行具体调查(导入者、数据模式、用户指令)。与无门控Agent相比,可测量地提升输出质量+2.25分。 origin: community
GateGuard — 事实强制预操作门控
一个PreToolUse钩子,强制Claude在编辑前进行调查。它不是自我评估("你确定吗?"),而是要求具体事实。调查行为本身创造了自我评估永远无法产生的意识。
何时激活
- 在文件编辑影响多个模块的任何代码库中工作时
- 具有特定模式或日期格式的数据文件的项目
- AI生成的代码必须匹配现有模式的团队
- Claude倾向于猜测而非调查的任何工作流
核心概念
LLM自我评估不起作用。问"你是否违反了任何策略?"答案永远是"没有"。这已通过实验验证。
但问"列出所有导入此模块的文件"会强制LLM运行Grep和Read。调查本身创造了改变输出的上下文。
三阶段门控:
1. DENY — block the first Edit/Write/Bash attempt
2. FORCE — tell the model exactly which facts to gather
3. ALLOW — permit retry after facts are presented
没有竞品能做到全部三个。大多数止步于deny。
证据
两次独立A/B测试,相同Agent,相同任务:
| 任务 | 有门控 | 无门控 | 差距 | | --- | --- | --- | --- | | 分析模块 | 8.0/10 | 6.5/10 | +1.5 | | Webhook验证器 | 10.0/10 | 7.0/10 | +3.0 | | 平均 | 9.0 | 6.75 | +2.25 |
两个Agent都能产生可运行并通过测试的代码。区别在于设计深度。
门控类型
Edit / MultiEdit门控(每个文件首次编辑)
MultiEdit的处理方式相同——批次中的每个文件都单独门控。
Before editing {file_path}, present these facts:
1. List ALL files that import/require this file (use Grep)
2. List the public functions/classes affected by this change
3. If this file reads/writes data files, show field names, structure,
and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim
Write门控(首次创建新文件)
Before creating {file_path}, present these facts:
1. Name the file(s) and line(s) that will call this new file
2. Confirm no existing file serves the same purpose (use Glob)
3. If this file reads/writes data files, show field names, structure,
and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim
破坏性Bash门控(每次破坏性命令)
触发条件:rm -rf、git reset --hard、git push --force、drop table等。
1. List all files/data this command will modify or delete
2. Write a one-line rollback procedure
3. Quote the user's current instruction verbatim
常规Bash门控(每个会话一次)
1. The current user request in one sentence
2. What this specific command verifies or produces
快速开始
选项A:使用ECC钩子(零安装)
scripts/hooks/gateguard-fact-force.js中的钩子已包含在此插件中。通过hooks.json启用。
如果GateGuard阻止了设置或修复工作,使用ECC_GATEGUARD=off启动会话。对于钩子级别的控制,继续使用ECC_DISABLED_HOOKS配合GateGuard钩子ID。
选项B:带配置的完整包
pip install gateguard-ai
gateguard init
这会添加.gateguard.yml用于项目级配置(自定义消息、忽略路径、门控开关)。
反模式
- 不要使用自我评估替代。 "你确定吗?"永远得到"是的"。这已通过实验验证。
- 不要跳过数据模式检查。 两个A/B测试Agent都假设ISO-8601日期,而真实数据使用
%Y/%m/%d %H:%M。检查数据结构(使用脱敏值)可以防止这整类bug。 - 不要对每个Bash命令都门控。 常规bash每个会话门控一次。破坏性bash每次都门控。这种平衡避免了减速同时捕获真正的风险。
最佳实践
- 让门控自然触发。不要试图预先回答门控问题——调查本身才是提升质量的关键。
- 为你的领域自定义门控消息。如果你的项目有特定约定,将它们添加到门控提示中。
- 使用
.gateguard.yml忽略.venv/、node_modules/、.git/等路径。
相关技能
safety-guard— 运行时安全检查(互补,不重叠)code-reviewer— 编辑后审查(GateGuard是编辑前调查)
