企业官网建设流程全解析

GitAgent Hooks钩子详解：拦截、修改和控制AI代理每个生命周期事件

【免费下载链接】opengapA framework-agnostic, git-native standard for defining AI agents项目地址: https://gitcode.com/gh_mirrors/git/opengap

GitAgent Hooks（钩子）是 GitAgent 框架中一套强大的生命周期拦截机制。GitAgent 是一个 git 原生的 AI 代理标准框架——你的代理身份、规则、记忆和工具都以版本化文件的形式保存在 git 仓库中，而 Hooks 让你用简单的脚本或代码，在代理运行的每个关键节点上拦截、修改和控制其行为：阻止危险命令、审计日志、限流、告警，全部尽在掌握。

🎯 GitAgent Hooks 是什么？

简单来说，Hooks 就像给 AI 代理装上的"安全栏杆"：

• 拦截（block）——代理准备执行危险操作时，直接叫停；
• 修改（modify）——在工具真正执行前，悄悄替换它的参数；
• 放行（allow）——检查通过，一切照常。

与传统框架不同的是，GitAgent 的钩子定义就存放在仓库的hooks/hooks.yaml文件中（见 README.md），随仓库一起提交、分叉、审查——你可以git log追踪每一条钩子的变更历史，这正是 "agents as repos" 理念的体现。

⏱️ 7 个生命周期事件全解析

GitAgent 在代理运行的 7 个关键时刻提供钩子挂载点，完整定义见 src/hooks.ts：

💡 规律很好记："事前"事件（pre_）可以拦截和改写，"事后"事件（post_、on_*）用于日志、告警和审计。

📝 三步配置你的第一个钩子

第 1 步：在hooks/hooks.yaml中声明

hooks: pre_tool_use: - script: validate-command.sh description: "拦截危险 CLI 命令" on_error: - script: incident-report.sh

框架启动时会通过loadHooksConfig自动加载该文件（src/hooks.ts#L32-L42）。

第 2 步：编写钩子脚本（JSON 进、JSON 出）

钩子脚本通过stdin 接收 JSON 上下文，通过stdout 返回 JSON 决策，任何语言都能写：

// stdin 输入 {"event": "pre_tool_use", "session_id": "uuid", "tool": "cli", "args": {"command": "rm -rf /"}} // stdout 输出 {"action": "block", "reason": "Destructive command blocked"}

第 3 步：理解三种动作

HookResult定义见 src/hooks.ts#L26-L30：

• allow：放行，继续执行（脚本不返回 JSON 时默认放行）；
• block：立即中止，reason会反馈给代理；
• modify：用返回的args字段替换原始参数后继续执行。

执行引擎（src/hooks.ts#L44-L117）有三个值得了解的安全设计：

1. 10 秒超时——钩子卡死不会拖垮代理，自动SIGTERM终止；
2. 路径穿越防护——脚本路径被锁定在基础目录内，无法逃逸；
3. 故障不阻塞——钩子自身报错只记录日志，不阻断主流程（fail-safe）。

🧩pre_tool_use：最强钩子，拦截 + 改参数

这是唯一能同时拦截和修改参数的事件。框架通过wrapToolWithHooks给每个工具的execute方法包上一层钩子逻辑：执行前先跑钩子，遇到block直接抛错，遇到modify则换用新参数（src/hooks.ts#L150-L188）。

典型用法：

• 黑名单拦截rm -rf、DROP TABLE等破坏性命令；
• 自动把代理要写入的路径重定向到沙箱目录；
• 记录每一次工具调用，形成完整审计轨迹。

多个钩子按声明顺序依次执行，一旦某个返回block或modify立即短路生效（src/hooks.ts#L129-L144）。

💻 编程式 Hooks：用 TypeScript 写钩子

不想写 shell 脚本？GitAgent SDK 提供进程内回调式钩子，在 src/sdk-types.ts 中定义了GCHooks接口，覆盖onSessionStart、preToolUse、preQuery、postToolFailure、postResponse、fileChanged、onError全部事件。核心包装逻辑见 src/sdk-hooks.ts：

const result = query({ hooks: { preToolUse: async (ctx) => { if (ctx.toolName === "cli" && ctx.args.command.includes("rm")) { return { action: "block", reason: "Blocked rm command" }; } return { action: "allow" }; }, }, });

一行判断即可拦截危险操作，类型提示完整，适合嵌入 Node.js 应用。

🔌 插件也能注册钩子

插件通过api.registerHook(event, handler)即可为四个核心事件（on_session_start、pre_tool_use、post_response、on_error）注册程序化钩子（src/plugin-sdk.ts#L68-L71），加载时自动与仓库级钩子合并（src/plugins.ts）。这意味着"安全护栏"可以像 npm 包一样被打包、复用、分发。

🛡️ 最佳实践速查

记住两条原则：

1. 拦截用事前事件，审计用事后事件——事后钩子没有拦截权，别指望它们能阻止操作；
2. 钩子要快——10 秒超时的限制意味着钩子里别做重活，日志和告警应异步落盘。

总结

GitAgent Hooks 用极简的"JSON 进、JSON 出"协议，为 AI 代理提供了完整的生命周期控制能力：7 个挂载点覆盖从会话开始到错误处理的全过程，block/modify/allow三种动作既能当安全护栏，也能做审计引擎，而 git 原生的配置文件让每条规则都可追溯、可回滚。配合框架内置的 审计模块 与 合规检查，你可以轻松构建一个受控、可观测的 AI 代理系统。更多细节请参考 Documentation.md 中的 Hooks 章节。

【免费下载链接】opengapA framework-agnostic, git-native standard for defining AI agents项目地址: https://gitcode.com/gh_mirrors/git/opengap