SuperAPI AI 工具集

guard

部署与运维

查看项目

更新于 10-26 18:53

技能介绍

guard 是 bro 工具链中的声明式提示机制,用于在 hook 事件触发时向会话注入一行上下文提醒。它本身不包含执行逻辑:收集、匹配、探针求值、触发集合预算与 judge 否决均由 @broject/guard 及 hooks 层实现,本技能只负责策略声明。使用前提是 bro 已在 PATH 中,或可通过 npx -y @broject/bro@0 调用。

用途与能力:guard 是单行提示,由 mega-hook 在 session-start、prompt-submit、post-tool、stop 等事件点求值。当 when 子句成立时触发,并把 say 行加入 hook 输出。when 子句可包含事件名、匹配键、状态探针与可选的 judge 否决。guard 永不阻断、永不授权,其输出只是上下文,不是门禁;需要真正阻止工作应使用 stop-gate 贡献而非 guard。

声明来源:guard 声明来自两处——bro.config.json 中的 guard.defs(优先,项目自有),以及各连接器的 guards() 贡献(按注册顺序,同名先到者胜;配置定义可通过复用名称覆盖内置项)。guard.enabled: false 可整体关闭该机制;guard.maxPerEvent 限制单次事件输出的行数。

命令:bro self guard list [--json] 列出所有已收集的 guard,包括名称、来源(config/connector/skipped)、事件、预算与校验状态。bro self guard test <name> [--event <e>] 针对实时状态求值单个 guard,打印 FIRE/SKIP 及逐子句判定行(匹配、状态探针、judge、预算),不写入任何内容,触发集合不受影响。

when.state 支持的键:diff.changed/diff.without 基于 git status(porcelain -z -uall,重命名计两个路径)的 glob;branch glob;已武装的 session-gate 方面;exists 仓库相对路径;probes 引擎注册的具名探针(如 spec-drift)及其自有参数。when.judge 调用 judge 门面:否决会抑制触发;弃权(无 judge、低置信度、decide 错误)不会抑制。

策略要点:guard 只提示,永不门禁;say 是一行注入会话记录的上下文。默认预算为 1:会话见过一次提示后,触发集合(位于 <git-common>/bro/hooks/fired/<session>,即 learn 的锁)会抑制重复;仅当重复本身是目的时才提高 when.budget,否则 guard 刷屏会成为故障。探针必须廉价:状态探针在 hook 内运行且有宿主超时限制,只允许 argv-git 与文件 stat;需要网络或长时间扫描的探针应读取缓存状态或不予发布。when.judge 是否决器而非驱动器:judge 只能抑制,不能使确定性子句失败的 guard 触发;弃权视为 ok:true,因为不可验证的条件也不应静默抑制提示。发布前先测试:bro self guard test <name> 展示每个子句对真实状态的判定;永远无法成立的子句是带维护成本的死重。重名是显式而非静默的:两个定义同名会在收集时告警且先到者胜;连接器内置项改名以覆盖是有意为之,拼写错误的名称会表现为 guard test 中可见的未知探针子句失败。

限制:资料未提供具体收费、价格、平台支持范围、性能数据或完整使用步骤,上述内容暂未提供;guard 不阻断执行,不能替代 stop-gate;探针受 hook 超时限制;judge 仅能否决。