ECC Web 前端 Hook 实战指南用 PreToolUse / PostToolUse / Stop 钩子守护前端代码质量【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文是 ECCEverything Claude Code仓库中 Web 前端规则体系的一部分围绕 docs/ja-JP/rules/web/hooks.md 展开为前端项目Next.js、Vue、React 等提供一套可直接复制的 Agent Hook 配置方案。读完本文你将掌握如何用 PostToolUse 钩子在每次编辑后自动格式化、Lint、增量类型检查与样式检查如何用 PreToolUse 钩子拦截超限写入如何用 Stop 钩子在会话结束时做生产构建验证以及这些钩子背后的源码级实现原理。一、ECC 的 Hook 体系事件驱动的自动化守门员Hooks 是 ECC 中基于事件触发的自动化机制在 Claude Code 工具执行前后触发用于强制执行代码质量、尽早发现错误并自动化重复检查。仓库 hooks/README.md 给出了核心执行链路User request → Claude picks a tool → PreToolUse hook runs → Tool executes → PostToolUse hook runs按 rules/common/hooks.md 的定义Hook 主要有三大类型这也是本文全部配置的组织骨架Hook 类型触发时机能力边界PreToolUse工具执行前可以校验、修改参数可通过退出码 2阻断工具调用PostToolUse工具执行后分析输出、执行格式化/检查不能阻断Stop每次会话响应结束做最终验证如构建检查此外还有SessionStart/SessionEnd会话生命周期边界、PreCompact上下文压缩前保存状态等生命周期钩子。Web 前端场景的推荐实践集中在PostToolUse质量守护与PreToolUse风险拦截上。二、PostToolUse 钩子编辑后的自动质量流水线Web 规则的核心原则是优先使用项目本地工具绝不把钩子挂到远程一次性包执行上。这样能保证使用仓库自身锁定的依赖版本也避免网络解析开销。2.1 保存时自动格式化Format on Save每次Write/Edit之后调用项目现有的格式化器入口对文件执行 Prettier 格式化{ hooks: { PostToolUse: [ { matcher: Write|Edit, command: pnpm prettier --write \$FILE_PATH\, description: Format edited frontend files } ] } }yarn prettier或npm exec prettier --等等价本地命令只要使用仓库自己拥有的依赖同样没问题。源码印证ECC 仓库自带的开箱即用实现 scripts/hooks/post-edit-format.js 走得更远——它只对.ts|tsx|js|jsx文件生效通过 scripts/lib/resolve-formatter.js 从项目根向上查找配置文件自动检测 Biome 还是 Prettier检测到 Biome 时执行biome check --write格式化 Lint 一次完成避免与 quality-gate 重复调用检测到 Prettier 时执行prettier --write仅格式化优先使用本地node_modules/.bin二进制而非npx单次调用节省约 200-500ms 的包解析开销失败静默降级非阻断并在 Windows 上对.cmd包装器做 shell 元字符注入防护。2.2 Lint 检查ESLint编辑后直接对目标文件运行 ESLint 自动修复{ hooks: { PostToolUse: [ { matcher: Write|Edit, command: pnpm eslint --fix \$FILE_PATH\, description: Run ESLint on edited frontend files } ] } }2.3 类型检查Type Checkincremental timeout 双保险类型检查是全项目最昂贵的检查原文档给出了经过实战调优的配置{ hooks: { PostToolUse: [ { matcher: Write|Edit, command: timeout 60 pnpm tsc --noEmit --pretty false --incremental --tsBuildInfoFile node_modules/.cache/tsc-hook.tsbuildinfo, description: Type-check after frontend edits (incremental timeout-capped) } ] } }为什么两个标志都至关重要没有--incremental每次编辑都会从零重新检查整个程序。在真实的 Next.js 项目中这会快速叠加每 5-10 秒一次的编辑 每次 30-60 秒的 tsc 运行 N 个并发 tsc 进程同时存在没有timeout挂起的 tsc例如传递依赖发生变化、类型检查器卡在递归类型上永远不会退出父 shell 结束后变成孤儿进程必须指定--tsBuildInfoFile因为--noEmit通常会抑制 buildinfo 写入显式指定路径才能让增量机制继续生效。--incremental生效后未变更代码的复检从 30-60 秒降到 1-3 秒。Windows 适配如果没有 GNU coreutils把timeout 60换成 PowerShell 包装器或者依赖 Stop/SessionEnd 钩子清扫残留的 tsc 进程。源码印证scripts/hooks/post-edit-typecheck.js 展示了另一种实现策略——它从被编辑文件目录向上最多 20 层查找最近的tsconfig.json然后在该目录下执行npx tsc --noEmit --pretty false30 秒超时tsc 非零退出时它只过滤出与本次编辑文件相关的错误行相对路径/绝对路径/原始路径三候选匹配避免同名文件误报最多报 10 行避免把整个项目的存量错误一次性倾倒给 Agent。2.4 CSS 样式检查Stylelint{ hooks: { PostToolUse: [ { matcher: Write|Edit, command: pnpm stylelint --fix \$FILE_PATH\, description: Lint edited stylesheets } ] } }该规则的应用范围见 rules/web/hooks.md 的 front-matter作用于*.css、*.scss、*.sass、*.less、*.html、*.tsx、*.jsx、*.vue、*.svelte等 Web 前端文件。三、PreToolUse 钩子拦截超限写入与 PostToolUse 只做事后修复不同PreToolUse 可以在写入发生前阻断。Web 规则提供了一个 800 行的文件大小保护钩子关键设计是从工具输入内容tool_input判断而不是从磁盘上可能还不存在的文件判断——因为Write目标文件在写入前可能根本不存在读不到内容必须直接解析本次写入的载荷{ hooks: { PreToolUse: [ { matcher: Write, command: node -e \let d;process.stdin.on(data,cdc);process.stdin.on(end,(){const iJSON.parse(d);const ci.tool_input?.content||;const linesc.split(\\n).length;if(lines800){console.error([Hook] BLOCKED: File exceeds 800 lines (lines lines));console.error([Hook] Split into smaller modules);process.exit(2)}console.log(d)})\, description: Block writes that exceed 800 lines } ] } }这段 Node 一行脚本完整演示了 Hook 的 stdin/stdout 协议从 stdin 读取 JSON解析出tool_input.content按行计数超过 800 行时向 stderr 输出提示并以退出码2阻断写入否则原样回显数据到 stdout。这一实现与 hooks/README.md 中 Block large file creation 配方一脉相承且 ECC 仓库自身在 hooks/hooks.json 中通过pre:config-protection阻断修改 lint/formatter 配置文件引导 Agent 修代码而非放宽配置等钩子实践了同样的 PreToolUse 阻断思想。四、Stop 钩子会话结束时的生产构建验证{ hooks: { Stop: [ { command: pnpm build, description: Verify the production build at session end } ] } }在会话/响应结束时执行生产构建确保所有编辑累积后项目仍可构建把能通过类型检查但构建失败的问题挡在会话内解决。ECC 仓库在 hooks/README.md 中同样为 Stop 事件配置了 console.log 审计、会话摘要持久化、模式提取持续学习、成本遥测、桌面通知等多类钩子可见 Stop 是收尾兜底的黄金时机。五、推荐的钩子执行顺序1. format 格式化 2. lint Lint 3. type check 类型检查 4. build 构建验证先格式化再 Lint 可以避免格式问题污染 Lint 输出类型检查在最重的构建之前先行拦截构建验证作为最终关卡。ECC 仓库自身的实践也遵循这一分层PostToolUse中 post-edit-format → quality-gateLint 等价物→ post-edit-typecheck最后 Stop 时兜底构建验证。六、进阶理解 Hook 协议与源码级配置结构6.1 Hook 的输入输出协议Hook 本质是 shell 命令stdin 接收工具输入 JSONstdout 必须输出原数据。以 hooks/README.md 中的结构为准访问input.tool_name如 Edit、Bash、Write、input.tool_input工具专属参数Bash有commandEdit/Write/Read有file_pathEdit还有old_string/new_stringWrite有content、PostToolUse 阶段还有input.tool_output退出码语义0成功继续2阻断工具调用仅 PreToolUse其他非零为错误记录但不阻断需要后台执行时可用async: true与timeout字段见 schemas/hooks.schema.json 中commandHookItem的定义。6.2 官方 Schema 支持的事件schemas/hooks.schema.json 定义了 ECC 认可的全部 Hook 事件SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Notification、SubagentStart、Stop、SubagentStop、PreCompact、InstructionsLoaded、TeammateIdle、TaskCompleted、ConfigChange、WorktreeCreate、WorktreeRemove、SessionEnd并支持command、http、prompt三种 action 类型。6.3 运行时开关与环境变量无需改配置文件即可控制 Hook 行为hooks/README.mdexport ECC_HOOKS_ENABLEDtrue # 主开关 export ECC_HOOK_PROFILEstandard # minimal | standard | strict export ECC_DISABLED_HOOKSpre:bash:tmux-reminder,post:edit:typecheckminimal只保留生命周期与安全钩子standard为默认平衡档strict追加更多提醒与更严护栏。ECC 仓库自身的 hooks/hooks.json 正是这种结构的实例每个 matcher 下挂载带id的钩子如pre:bash:dispatcher、pre:write:doc-file-warning通过run-with-flags.js按 profile 门控启用。七、安装与落地建议手动粘贴配置将上述 JSON 片段合并进你的~/.claude/settings.json的hooks节点对应你的项目级.claude/settings.json亦同或按 schemas/hooks.schema.json 校验格式使用 ECC 安装器仓库 hooks 面向插件/安装器加载不要直接把 hooks/hooks.json 复制进个人配置应运行bash ./install.sh --target claude --modules hooks-runtime --enable-hooksWindows 用pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks安装器会把命令重写到你的实际 Claude 根目录Windows 为%USERPROFILE%\.claude按项目裁剪前端项目优先保留 format → lint → type check 三件套与 800 行写入保护CI 已有 lint/typecheck 的团队可把 Stop 构建验证替换为轻量冒烟命令避免重复全量构建。前端工程质量不在于 Agent 多聪明而在于把不可变的检查固化为事件驱动的自动化。按本文顺序装配这五类钩子你的 Web 项目就能在每次编辑时自动完成格式化、Lint、增量类型检查与构建验证——这正是 rules/web/hooks.md 与 ECC 开源仓库共同沉淀的最佳实践。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考