WhoDB Agent Hooks 全解析：为 AI 编码助手构建自动格式化、代码生成与构建验证钩子体系-北京尧图网络

数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载本文深入剖析 WhoDB 开源仓库中的.agents/hooks钩子基础设施它如何在 Claude Code、Codex 等 AI 编码助手执行 Edit/Write/apply_patch 等工具动作后自动格式化 Go/TypeScript 代码、按需重新生成 GraphQL 类型并在每个回合结束时对改动区域做编译与类型检查兜底。读完本文你将掌握 WhoDB 钩子体系的完整触发链路、JSON 载荷解析原理、双配置文件注册方式并能够依照官方流程为仓库新增一个自己的 Agent Hook。一、Hooks 机制概述让 AI 编辑后的代码始终一致WhoDB 将 Agent Hooks 定义为在工具动作edit、write、apply_patch之后运行的一批脚本其使命是保持代码库的一致性。钩子脚本通过标准输入stdin接收一个包含工具输入的 JSON payload从中解析出本次改动的文件路径再决定执行哪些检查与修复。这套设计有一个明确的分工哲学PostToolUse 钩子静默自动修复负责gofmt、oxlint --fix、GraphQL codegen 等机械性工作它们吞掉错误输出、不打断 Agent 的回合Stop 钩子回合结束兜底verify-build.sh负责把 PostToolUse 钩子只修风格、不报编译错误的缺口补上——如果本轮改动的代码无法编译或类型检查不过就以退出码 2 阻断回合把错误原样抛回给 Agent 继续修复。官方钩子脚本总览原文档定义的钩子脚本清单如下触发与职责完全继承自 .agents/hooks/README.md脚本触发时机实际行为auto-format-go.sh.go文件被编辑依次执行gofmt -w与golangci-lint run --fixauto-lint-ts.sh.ts/.tsx文件被编辑执行oxlint --fixauto-graphql-codegen.sh.graphqls文件被编辑在core/执行go generate、在frontend/执行pnpm generateEE 子模块同理verify-build.shAgent 回合结束Stop仅对本回合改动过的区域做编译/类型检查CE/EE 的 Go 用go buildCE/EE 前端用pnpm typecheck失败则以退出码 2 阻断回合对重复出现的相同错误做去抖避免死循环session-context.sh会话开始SessionStart注入当前分支名与未提交文件数值得注意的边界翻译translation刻意不作为自动钩子。官方约定 Agent 只新增或更新en_US字符串需要翻译时手动运行dev/translate工具链参见 .agents/docs/localization.md 与 .agents/rules/localization.md。这避免了在每次编辑时都触发整个国际化流水线。二、逐钩子深度剖析从触发到落地的完整链路2.1 auto-format-go.shGo 文件的格式化与静态检查自动修复该脚本对应 auto-format-go.sh核心逻辑分两遍执行gofmt 一遍先调用python3 $hook_dir/changed-files.py从 JSON 载荷中解析出本次所有改动文件凡以.go结尾的文件通过resolve_file()把相对路径解析为仓库内绝对路径脚本内部先用git rev-parse --show-toplevel定位仓库根随后执行gofmt -w -- $resolved_path输出被静默丢弃/dev/null 21golangci-lint 一遍再次遍历改动文件若仓库根下存在core/go.mod则在core/模块目录内执行golangci-lint run --fix -- $file_path把可自动修复的 lint 问题就地修复。两个细节体现了工程化考量resolve_file同时兼容以仓库根为起点和以当前工作目录为起点两种路径形式所有命令都追加|| true确保修复失败不会阻断 Agent 回合。背景知识core/是 CECommunity EditionGo 后端模块见 go.work 中的 workspace 定义core/go.mod即该模块的 go.mod而core/lint.sh是仓库预置的 Go lint 入口golangci-lint只是钩子脚本直接调用的 CLI。2.2 auto-lint-ts.shTypeScript/TSX 的 oxlint 自动修复对应 auto-lint-ts.sh。它同样先通过changed-files.py枚举改动文件筛选出.ts/.tsx后缀然后按路径前缀分流命中$repo_root/ee/frontend/前缀 → 在ee/frontend目录执行pnpm exec oxlint --fix -- $resolved_path命中$repo_root/frontend/前缀 → 在frontend目录执行pnpm exec oxlint --fix -- $resolved_path其余情况直接跳过。之所以要cd进各自的前端目录再执行是因为oxlint需要基于该目录下的package.jsonfrontend/package.json解析 pnpm 工作区依赖与 lint 配置。这也说明 WhoDB 的 CE 前端frontend/与 EE 前端ee/frontend拥有相互独立的工具链上下文。2.3 auto-graphql-codegen.shschema 变更驱动的前后端代码生成GraphQL 是 WhoDB CE 后端对外暴露数据面的核心接口schema 定义位于 core/graph/schema.graphqls。当.graphqls文件被编辑时auto-graphql-codegen.sh 会按哪个区域被改了做精确分流改动路径形如ee/*或*/ee/*→ 标记needs_ee1随后执行(cd $repo_root/ee go generate .)EE Go 后端生成(cd $repo_root/ee/frontend pnpm run generate)EE 前端生成其余情况 → 标记needs_ce1随后执行(cd $repo_root/core go generate .)CE Go 后端生成(cd $repo_root/frontend pnpm run generate)CE 前端生成。所谓后端生成对应的是 core/generate.go 中的//go:generate go run github.com/99designs/gqlgen generate——即在core/内执行go generate .会触发 gqlgen 从schema.graphqls重新生成 resolver 骨架与模型。所谓前端生成对应 frontend/package.json 的generate: graphql-codegen --config codegen.yml脚本其配置见 frontend/codegen.yml以../core/graph/schema.graphqls为 schema、src/**/*.graphql为 documents输出src/generated/schema-types.ts与src/generated/graphql.ts两份类型文件。这套机制保证Agent 修改了 GraphQL schema 之后前后端类型代码在编辑发生的瞬间就被重新生成后续的 Go 编译与 TS typecheck 不会因为改 schema 忘重新生成而报出与业务无关的错误。2.4 verify-build.sh回合结束时的编译/类型检查看门狗这是整套钩子体系中最关键的一道防线实现在 verify-build.sh。其设计动机在脚本注释中写得很直白PostToolUse 的自动格式化/ lint 钩子会静默修复风格问题却会把编译错误与类型错误吞掉verify-build.sh负责在回合结束前把这些错误捞回来。其执行流程分四步循环保护先读取 Stop 事件载荷若其中包含stop_hook_active: true表示 Agent 正因为上一次 Stop 钩子的阻断而继续修复则直接退出避免二次阻断收集改动changed_in()函数通过git diff --name-only已跟踪未暂存、git diff --cached --name-only已暂存、git ls-files --others --exclude-standard未跟踪文件三路合并出本回合的真实改动面EE 子模块若存在ee/目录单独收集按区域分流检查用 grep 判断改动类型并置位四个标志——need_core_gocore/*.go、need_ce_tsfrontend/*.ts|tsx、need_ee_goee/*.go、need_ee_tsee/frontend/*.ts|tsx随后分别执行go build ./...Go 后端与pnpm typecheck前端对应typecheck: tsc -p tsconfig.ce.json --noEmit失败阻断与去抖任一检查失败错误信息截取最后 40 行汇总后写入 stderr 并以退出码 2结束——该退出码会让 Claude Code / Codex 认定 Stop 钩子失败从而把错误呈现给 Agent 要求修复。为防止无法修复的硬错误把 Agent 困在循环里脚本用shasum对错误集生成指纹写入.git/.whodb-verify-build-fp若与上一次指纹完全相同则删除指纹文件并放行。这套静默修风格 Stop 兜底编译的双层设计正是 WhoDB 钩子体系与其他仅做格式化钩子项目的本质区别。2.5 session-context.sh会话开始注入仓库上下文对应 session-context.sh是唯一在SessionStart事件触发的钩子。它输出一行形如Branch: main, Uncommitted files: 3的文本被注入到 Agent 的上下文里让 Agent 从一开始就知道自己工作在哪个分支、工作区有多少未提交改动。实现上支持通过WHODB_ROOT环境变量显式指定仓库根否则回退到git rev-parse --show-toplevel分支名解析失败时输出unknown保证任何环境下都不会产生空输出。三、支撑文件changed-files.py 如何解析 JSON 载荷所有 PostToolUse 钩子都依赖同一个解析器changed-files.py。它是Claude Code 风格 file hooks 与 Codex apply_patch hooks 的统一路径提取器从 stdin 读取 JSON 后按以下优先级提取文件路径tool_input.file_path/tool_input.path单文件型工具输入tool_input.files数组型逐个提取tool_input.command用正则^\*\*\* (?:Add|Update|Delete) File: (.)$与^\*\*\* Move to: (.)$匹配 Codexapply_patch的补丁头部提取被增改删或移动的文件。提取结果会做三重清洗仅接受字符串值、剔除含换行或空字符的异常路径、按出现顺序去重后逐行输出。由于它把载荷解析收敛到一个脚本后续新增任何 PostToolUse 钩子都无需重复实现解析逻辑。四、双配置文件注册Claude Code 与 Codex 的事件映射钩子脚本本身不包含任何触发配置事件绑定完全由两份配置文件决定而且两份文件必须同时更新——两种工具互不读取对方的配置Claude Code.claude/settings.json 的hooks字段注册了三类事件SessionStart→session-context.shPostToolUsematcher 为Edit|Write→auto-format-go.sh、auto-lint-ts.sh、auto-graphql-codegen.sh三个脚本依次执行Stop→verify-build.sh。Codex.codex/hooks.json 结构类似但 matcher 表达更细SessionStart的 matcher 为startup|resume并带statusMessage: Loading session context与 30 秒超时PostToolUse的 matcher 为^apply_patch$|Edit|Write正则匹配apply_patch工具名三个自动修复钩子分别配置了 60/120/300 秒超时另注册了一个 UI 检查钩子当.agents/skills/impeccable/scripts/hook.mjs存在时执行node .../hook.mjs对 UI 变更做检测与设计深度检查Design deep pass。注册命令统一采用bash $(git rev-parse --show-toplevel)/.agents/hooks/script-name即以 git 仓库根为锚点定位钩子脚本——这保证了无论 Agent 当前工作目录在仓库的哪个子目录命令都能正确解析。注意两条配置中 matcher 的差异Claude 用Edit|WriteCodex 额外匹配apply_patch正是为了让同一批脚本在两家工具上获得等价触发行为。五、平台兼容性Codex/Claude Code 格式与 Pi 扩展体系原文档明确提示了兼容性边界这些钩子采用 Codex / Claude Code 的钩子格式JSON on stdin。而 Pi一个采用扩展机制的编码助手使用的是扩展式extension-based钩子系统与前者不互通。若要在 Pi 中获得等价能力需要把这些脚本包装成 Pi 扩展wrap these scripts in a Pi extension。也就是说.agents/hooks目录天然是工具中立的但具体接线方式要随宿主工具而异——这也与 .agents/README.md 声明的共享 Agent 指南保持工具中立、工具专属说明放在 CLAUDE.md 等适配文件中的原则一致。六、新增一个 Hook 的完整指南官方流程原文档给出了四条可操作的步骤这里结合源码逐条展开第 1 步编写脚本到.agents/hooks/根目录。脚本应遵循现有约定从 stdin 读取 JSON 载荷可复用changed-files.py解析路径、用git rev-parse --show-toplevel定位仓库根、以exit 0正常结束且不被单次失败卡死参考 auto-format-go.sh 的|| true模式。第 2 步为ee/子模块添加转发 shim。因为ee/是独立的 git 仓库当 Agent 的工作目录落在ee/内部时git rev-parse --show-toplevel会解析到ee/而不是 monorepo 根导致bash $(git rev-parse --show-toplevel)/.agents/hooks/...找不到脚本。解决办法是在ee/.agents/hooks/script-name放置转发壳并严格匹配官方 shim 模式#!/usr/bin/env bash exec $(cd $(dirname $0)/../../.. pwd)/.agents/hooks/script-name $即用脚本自身位置向上回溯三级到达 monorepo 根再exec真实脚本保留$参数透传。随后需要chmod x赋予执行权限。第 3 步在.claude/settings.json与.codex/hooks.json中同时注册。使用统一命令形式bash $(git rev-parse --show-toplevel)/.agents/hooks/script-name并挂在合适的事件下SessionStart、PostToolUse、Stop等。Codex 侧还可以按需补充matcher、statusMessage、timeout等字段参照 .codex/hooks.json 中已有钩子的写法。务必两份配置都更新否则两种工具的行为会不一致。第 4 步更新 .agents/hooks/README.md 顶部的脚本表格登记新脚本的触发器与行为保证文档与实现同步。七、与 Git pre-commit 的分工配合值得区分的是.agents/hooks/下还有一份 pre-commit它属于Git 客户端钩子而非 Agent 钩子——由bash dev/setup-hooks.sh见 dev/setup-hooks.sh安装到本地 git 配置中在任何git commit提交前运行对暂存文件做 Go lint在core/内通过./lint.sh run对改动包目录执行与前端 oxlint排除frontend/src/generated/生成目录失败即中止提交如需临时跳过可设SKIP_LINT1。两者的关系是互补的两道闸门Agent 钩子在编辑发生的那一刻就把代码修好、在回合结束前验证可编译git pre-commit 则作为提交前的最后防线拦截任何绕过 Agent 钩子的改动例如人类开发者或其它工具直接改的文件。再加上 dev/check-agent-instructions.sh 对 Agent 指令文档的变更校验WhoDB 以编辑即修复 → 回合结束即验证 → 提交前再校验三层防线维持代码库的持续一致。八、小结WhoDB 的 Agent Hooks 体系可以概括为一套工具中立、事件驱动、分层兜底的工程实践工具中立脚本只依赖 stdin 的 JSON 与 git 命令通过双配置文件适配 Claude Code 与 Codex并预留了 Pi 扩展包装路径事件驱动SessionStart注入上下文、PostToolUse静默修复格式与 lint 并重生成 GraphQL 类型、Stop做编译/类型检查兜底每一类事件都有明确职责分层兜底PostToolUse 的静默修复 Stop 的exit 2阻断 git pre-commit 的提交前校验覆盖了从编辑到提交的完整生命周期可扩展changed-files.py统一了路径解析新增钩子只需遵循脚本 ee/ 转发 shim 双配置注册更新文档四步流程。对于在 WhoDB 仓库中工作的任何 AI 编码助手无论是 Claude Code、Codex 还是后续接入的工具这套体系都让写代码、修代码、验代码的闭环得以自动完成——这也是阅读本仓库时理解其 Agent 工程化程度的最佳入口。赞分享数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载相关推荐ECC PHP Hooks 实战为 PHP 代码库构建格式化、静态分析、定向测试与安全告警的 PostToolUse 钩子体系ECC PHP Hooks 实战为 PHP 代码库构建格式化、静态分析、定向测试与安全告警的 PostToolUse 钩子体系本文以 ECCThe age人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具ECC Kotlin Hooks 实践用 PostToolUse 钩子为 .kt 文件构建自动格式化、静态分析与编译验证的自动化质量护栏ECC Kotlin Hooks 实践用 PostToolUse 钩子为 .kt 文件构建自动格式化、静态分析与编译验证的自动化质量护栏本文围绕 ECC 仓人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具PowerToys File Locksmith 快速上手文件被占用删不掉一次右键定位元凶PowerToys File Locksmith 快速上手文件被占用删不掉一次右键定位元凶删文件时弹出此操作无法完成因为文件已在另一个程序中打开本桌面应用开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

WhoDB Agent Hooks 全解析：为 AI 编码助手构建自动格式化、代码生成与构建验证钩子体系

相关推荐

打卡记忆单词法：告别死记硬背，让孩子爱上英语学习

SnackBar队列机制揭秘：为何始终只显示一条消息？3个Queue设计原理解析

Flutter三方库鸿蒙化适配实践：lzma压缩库迁移全记录

更多资讯

给仓库写个 cloudinabottle.toml：Cloud in a Bottle 应用开发完整教程

Python实现FPU模拟：非线性振子链能量递归的数值复现

从理论到落地：构建企业级信息安全防线

【Web 渗透】10 款 Burp Suite 神器插件合集，直接拉满渗透测试效率

塔吉克语论文写到一半想求助？这份工具榜先按环节挑，别再只问谁第一 [特殊字符]

手写词法分析器：从状态机到回退机制的完整实验指南

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？