SuperAPI AI 工具集

hook-development

编程与开发

查看项目

更新于 11-10 16:22

技能介绍

用途:为 Google Antigravity 插件编写事件驱动的自动化钩子(hooks),在开发流程的关键节点执行校验、策略约束、上下文注入与外部工具集成。

主要能力:

  1. 钩子事件:PreToolUse(工具执行前,可允许、拒绝或修改调用)、PostToolUse(工具完成后反馈、记录)、Stop 与 SubagentStop(校验完成度)、UserPromptSubmit(处理用户提示,添加上下文或拦截)、SessionStart(加载项目上下文)、SessionEnd(清理与记录)、PreCompact(压缩前保留关键信息)、Notification(响应通知)。
  2. 钩子类型:基于提示词的钩子由大模型推理做上下文感知判断,支持 Stop、SubagentStop、UserPromptSubmit、PreToolUse,文档称其为推荐方式;命令钩子执行 bash 命令做确定性检查,适合快速校验、文件操作、外部工具集成与性能敏感检查。
  3. 配置格式:插件中在 hooks/hooks.json 使用带 description(可选)与 hooks 包装层的格式;用户设置在 .agents/settings.json 使用事件直接位于顶层的直接格式。插件钩子会与用户钩子合并并并行运行。
  4. 匹配器:支持精确工具名、以竖线分隔的多个工具、通配符 * 以及正则(如 mcp__.__delete.),且区分大小写。
  5. 输入与输出:所有钩子通过 stdin 接收 JSON,含 session_id、transcript_path、cwd、permission_mode、hook_event_name 等公共字段及各事件专属字段;可在提示词中用 $TOOL_INPUT、$TOOL_RESULT、$USER_PROMPT 等引用。标准输出支持 continue、suppressOutput、systemMessage;PreToolUse 可返回 permissionDecision 与 updatedInput;Stop 可返回 decision(approve|block)与 reason。退出码 0 表示成功并将 stdout 展示在记录中,2 表示阻断性错误并将 stderr 反馈给 Antigravity,其余为非阻断性错误。
  6. 环境变量:命令钩子可使用 $CLAUDE_PROJECT_DIR、$ANTIGRAVITY_PLUGIN_ROOT(推荐用于可移植路径)、$CLAUDE_ENV_FILE(仅 SessionStart,用于持久化环境变量)、$CLAUDE_CODE_REMOTE。
  7. 性能与并行:所有匹配的钩子并行执行,彼此看不到对方输出,顺序不确定,因此需按相互独立来设计;建议对高频路径减少 I/O,并用命令钩子做快速确定性检查。
  8. 临时启用机制:可通过标志文件或配置文件让钩子按条件激活,用于临时严格校验、调试或项目级行为。

使用方式:先确定需要挂载的事件,再选择提示词钩子或命令钩子;在 hooks/hooks.json 写入配置,命令钩子需编写脚本,文件引用使用 ${ANTIGRAVITY_PLUGIN_ROOT};用 scripts/validate-hook-schema.sh 校验配置、用 scripts/test-hook.sh 预测试,再以 claude --debug 在 Antigravity 中调试,并在插件 README 中说明。

适用场景:文件写入安全校验、命令执行审查、MCP 工具管控、任务完成度检查、会话开始时加载项目上下文、按提示词内容附加安全提示等插件开发场景。

限制与注意事项:钩子在会话启动时加载,修改配置或脚本需重启 Google Antigravity 才能生效,不支持热替换;hooks.json 中 JSON 无效会导致加载失败,缺少脚本会在调试模式中告警,可用 /hooks 查看已加载钩子。命令钩子应校验输入、检查路径穿越与敏感文件、为变量加引号并设置合适超时(命令钩子默认 60 秒、提示词钩子默认 30 秒),且不应记录敏感信息。文档另提供 references/ 下的模式、迁移与进阶文档,examples/ 下的 validate-write.sh、validate-bash.sh、load-context.sh 示例,以及 scripts/ 下的校验、测试与检查脚本。具体收费、价格与平台支持信息暂未提供。