本文提供五个可直接参考的 hook 实现案例，覆盖从安全防护到国际化管理的真实开发场景：Agent Stop 触发的安全预提交扫描、Prompt Submit 触发的用户操作集中日志、File Save 触发的国际化文件同步和测试覆盖率检查，以及 Manual Trigger 触发的按需文档生成。此外还介绍了如何将 MCP 能力融入 hooks，以 Figma 设计稿一致性校验为例，展示 hooks 与外部工具协作的扩展玩法。

Hooks 实战示例

以下示例展示了可用于真实项目的 hook 实现，每个示例都包含触发类型、目标文件和完整配置。

安全预提交扫描

防止敏感信息意外提交到代码库。

触发类型：Agent Stop

Agent Prompt：

Review changed files for potential security issues:
1. Look for API keys, tokens, or credentials in source code
2. Check for private keys or sensitive credentials
3. Scan for encryption keys or certificates
4. Identify authentication tokens or session IDs
5. Flag passwords or secrets in configuration files
6. Detect IP addresses containing sensitive data
7. Find hardcoded internal URLs
8. Spot database connection credentials

For each issue found:
1. Highlight the specific security risk
2. Suggest a secure alternative approach
3. Recommend security best practices

用户 Prompt 集中日志

将所有用户 prompt 记录到集中式日志系统，用于审计或分析。

触发类型：Prompt Submit

Shell Command：

# 将用户 prompt 推送到 Grafana Loki
curl -H "Content-Type: application/json" -XPOST \
     "http://loghost/loki/api/v1/push" --data-raw \
     "{'streams': [{
        'stream': { 'app': 'kiro', 'user': \"${USER}\"  },
        'values': [ [\"$(date +%s%N)\", \"${USER_PROMPT}\"] ]
      }]}"

国际化文件同步

当主语言文件更新时，自动同步其他语言文件的待翻译标记。

触发类型：File Save
目标文件：src/locales/en/*.json

Agent Prompt：

When an English locale file is updated:
1. Identify which string keys were added or modified
2. Check all other language files for these keys
3. For missing keys, add them with a "NEEDS_TRANSLATION" marker
4. For modified keys, mark them as "NEEDS_REVIEW"
5. Generate a summary of changes needed across all languages

测试覆盖率守护

代码修改时自动检查并补充测试覆盖。

触发类型：File Save
目标文件：src/**/*.{js,ts,jsx,tsx}

Agent Prompt：

When a source file is modified:
1. Identify new or modified functions and methods
2. Check if corresponding tests exist and cover the changes
3. If coverage is missing, generate test cases for the new code
4. Run the tests to verify they pass
5. Update coverage reports

按需文档生成

手动触发，为当前文件生成完整文档。

触发类型：Manual Trigger

Agent Prompt：

Generate comprehensive documentation for the current file:
1. Extract function and class signatures
2. Document parameters and return types
3. Provide usage examples based on existing code
4. Update the README.md with any new exports
5. Ensure documentation follows project standards

与 MCP 集成

Agent hooks 可以结合 MCP（Model Context Protocol）进一步扩展能力：

1. 接入外部工具：hooks 可以利用 MCP 服务器调用专用工具和 API
2. 丰富上下文：MCP 为 hook 的 Agent 动作提供额外的参考信息
3. 领域专业知识：专用 MCP 服务器可为 hooks 注入特定领域的判断能力

使用 MCP 与 hooks 配合的步骤：

1. 配置 MCP 服务器
2. 在 hook 的 Agent Prompt 中引用 MCP 工具
3. 为高频调用的工具配置合适的自动审批（autoApprove）设置

典型使用场景：

• 确保代码遵循 Figma 设计系统规范
• 任务完成后自动更新 Ticket 状态
• 从项目内的示例文件同步数据库

示例：Figma 设计一致性校验

这个 hook 监听 HTML 和 CSS 文件的保存，并通过 Figma MCP 验证设计规范遵从性。

触发类型：File Save
目标文件：*.css *.html

Agent Prompt：

Use the Figma MCP to analyze the updated html or css files and check that they follow
established design patterns in the figma design. Verify elements like hero sections,
feature highlights, navigation elements, colors, and button placements align.

常见问题

Q：这些示例中的文件路径 pattern 是否需要根据项目结构调整？

A：是的，必须调整。示例中的路径（如 src/locales/en/*.json、src/**/*.{js,ts,jsx,tsx}）基于常见项目结构。使用前请对照你的实际目录结构修改，否则 hook 可能永远不会触发或触发范围过宽。

Q：安全扫描 hook 能替代专业的 secret 扫描工具吗？

A：不建议完全依赖。这个 hook 是一道额外的保护层，适合捕获明显的遗漏。对于正式项目，建议同时使用 git-secrets、truffleHog 或 gitleaks 等专业工具作为 CI/CD 中的强制检查，而不是仅靠 Agent 判断。

Q：国际化同步 hook 如果翻译键非常多，会不会超出上下文限制？

A：当语言文件很大时，建议在 prompt 中限制扫描范围，比如只检查最近修改的键，而不是全量扫描所有语言文件。也可以将任务拆分：先由 Shell Command hook 提取变更的键列表并写入临时文件，再由 Agent Prompt hook 读取这份列表进行翻译处理。