Kiro Hooks 完整文档指南
概念介绍与核心理念
Kiro Hooks 是强大的自动化工具，通过在 IDE 中发生特定事件时自动执行预定义的 agent 操作来简化您的开发工作流程。使用 hooks，您无需手动请求例行任务，并确保代码库的一致性。
什么是 Agent Hooks？
Agent Hooks 是自动化触发器，当 IDE 中发生特定事件时执行预定义的 agent 操作。与其手动请求执行例行任务，hooks 为以下事件设置自动响应：
- 保存文件
- 创建新文件
- 删除文件
Agent Hooks 的优势
Agent Hooks 通过智能自动化改变您的开发工作流程。通过为常见任务设置 hooks，您可以：
- 维护一致的代码质量
- 防止安全漏洞
- 减少手动开销
- 标准化团队流程
- 创建更快的开发周期
Agent Hooks 工作原理
flowchart LR
A[事件检测] --> B[Prompt 执行]
B --> C[自动化操作]
A1[文件保存/创建/删除] --> A
B1[预定义 Prompt] --> B
C1[Agent 处理] --> CAgent Hook 系统遵循简单的三步流程：
- 事件检测：系统监控 IDE 中的特定事件
- Prompt 执行：当事件发生时，预定义的 prompt 被发送给 agent
- 自动化操作：agent 处理 prompt 并执行请求的操作
Hook 类型与触发器
Agent Hooks 支持各种触发器类型，每种都为特定的自动化场景而设计：
1. 文件创建时触发（On File Create）
触发条件：当工作区中创建匹配特定模式的新文件时。
使用场景：
- 为新组件生成样板代码
- 向新文件添加许可证头
- 创建实现文件时设置测试文件
2. 文件保存时触发（On File Save）
触发条件：当匹配特定模式的文件被保存时。
使用场景：
- 运行代码检查和格式化
- 更新相关文件
- 生成文档
- 为更改的文件运行测试
3. 文件删除时触发（On File Delete）
触发条件：当匹配特定模式的文件被删除时。
使用场景：
- 清理相关文件
- 更新其他文件中的导入引用
- 维护项目完整性
4. 手动触发（Manual Trigger）
触发条件：手动执行 hook。
使用场景：
- 按需代码审查
- 文档生成
- 安全扫描
- 性能优化
Hook 管理与配置
设置 Agent Hooks
创建和管理 hooks 非常简单：
使用资源管理器视图
- 导航到 Kiro 面板中的 Agent Hooks 部分
- 点击 + 按钮创建新的 hook
- 在输入字段中使用自然语言定义 hook 工作流程
- 按 Enter 或点击 Submit 继续
- 配置 hook 设置并保存
使用命令面板
- 使用
Cmd + Shift + P（Mac）或Ctrl + Shift + P（Windows/Linux）打开命令面板 - 输入
Kiro: Open Kiro Hook UI - 按照屏幕指示创建您的 hook
管理您的 Hooks
通过 Kiro 面板中的 Agent Hooks 部分访问所有 hooks。
启用/禁用 Hooks
在不删除的情况下开启或关闭 hooks：
- 快速切换：点击 Agent Hooks 面板中任何 hook 旁边的
眼睛图标 - 从 hook 视图：选择一个 hook 并使用右上角的
Hook Enabled开关
编辑现有 Hooks
Hooks 随着您的工作流程而演进。通过在 Agent Hooks 面板中选择您的 hook 并修改触发器、文件模式、指令或描述等设置，随时更新它们。更新立即生效。
删除 Hooks
在 Agent Hooks 面板中选择 hook，点击底部视图中的 Delete Hook，然后点击 delete。此操作无法撤销。
运行手动触发 Hooks
您可以使用以下方式执行手动触发 hook：
- 快速运行：点击 Agent Hooks 面板中 hook 名称旁边的
播放按钮（▷） - 从 hook 视图：选择 hook 并点击右上角的
Start Hook
最佳实践与指导原则
遵循这些最佳实践将帮助您创建可靠、高效且可维护的 hooks，从而增强您的开发工作流程。
Hook 设计
具体且清晰
- 编写详细、明确的指令
- 每个 hook 专注于一个特定任务
- 对复杂操作使用编号步骤
充分测试
- 在部署前在示例文件上测试 hooks
- 验证 hooks 在边缘情况下的工作情况
- 在扩展前从有限的文件模式开始
监控性能
- 确保 hooks 不会减慢您的工作流程
- 考虑触发事件的频率
- 优化 prompts 以提高效率
安全考虑
验证输入
- 确保 hooks 优雅地处理意外的文件内容
- 考虑文件格式中的潜在边缘情况
- 使用格式错误或意外输入进行测试
限制范围
- 尽可能针对特定文件类型或目录
- 使用精确的文件模式避免不必要的执行
- 考虑 hooks 对整个代码库的影响
定期审查
- 随着项目发展更新 hook 逻辑
- 删除不再需要的 hooks
- 根据实际结果优化 prompts
团队协作
文档化 Hooks
- 维护 hook 用途的清晰文档
- 包含预期行为的示例
- 记录任何限制或边缘情况
标准化工作流程
- 在团队成员之间使用一致的 hooks
- 在版本控制中存储 hook 配置
- 为常见团队工作流程创建标准 hooks
版本控制集成
- 考虑与版本控制系统集成的 hooks
- 为代码审查工作流程创建 hooks
- 使用 hooks 强制执行团队标准
实际使用案例与示例
这些示例展示了您可以为自己的项目调整的真实 hook 实现。
1. 安全预提交扫描器
触发类型：File Save
目标：**/*
此 hook 通过在提交前扫描文件来帮助防止安全泄露。
Hook 指令：
扫描此文件的潜在安全问题，包括：
- API 密钥、密码或机密信息
- 硬编码凭据
- 潜在的 SQL 注入漏洞
- XSS 漏洞
- 不安全的配置
如果发现任何问题，请提供具体的修复建议。2. 国际化助手
触发类型：File Save
目标：src/locales/en/*.json
此 hook 确保当您更新主要语言文件中的文本时，翻译保持同步。
Hook 指令：
检查此英语语言环境文件是否有其他语言文件中不存在的新键。
对于任何缺失的键，将它们添加到相应文件中，并使用占位符文本
表示需要翻译。3. 文档生成器
触发类型：Manual Trigger
此 hook 在代码更改时自动更新文档。
Hook 指令：
为当前项目生成全面的文档，包括：
- 所有公共函数的 API 文档
- 使用示例
- 安装说明
- 配置选项
使用最新信息更新 README.md 文件。4. 测试覆盖率维护器
触发类型：File Save
目标：src/**/*.{js,ts,jsx,tsx}
此 hook 确保随着代码的发展，测试覆盖率保持较高水平。
Hook 指令：
分析此文件并检查是否存在相应的测试文件。
如果测试缺失或不完整：
- 创建或更新测试文件
- 确保所有公共函数都经过测试
- 在适当的地方添加边缘情况测试与 MCP 集成
Agent Hooks 可以通过 Model Context Protocol (MCP) 功能增强以扩展其功能：
- 访问外部工具：Hooks 可以利用 MCP 服务器访问专门的工具和 API
- 增强上下文：MCP 为更智能的 hook 操作提供额外的上下文
- 领域特定知识：专门的 MCP 服务器可以提供领域专业知识
示例：验证 Figma 设计
触发类型：File Save Hook
目标：*.css *.html
Hook 指令：
使用 Figma MCP，验证此文件中的 HTML 和 CSS 更改
是否遵循设计系统规范。检查：
- 颜色与设计令牌的一致性
- 排版与样式指南的对齐
- 间距和布局对网格系统的遵循
对任何偏差提供具体反馈。故障排除与常见问题
虽然提供的信息中故障排除页面内容不完整，但这里是 Kiro Hooks 的常见故障排除方法：
常见问题
Hook 未触发
- 验证文件模式是否匹配您的目标文件
- 检查 hook 是否在 Agent Hooks 面板中启用
- 确保触发事件按预期发生
性能问题
- 审查 hook 频率和范围
- 优化 prompt 复杂性
- 考虑限制文件模式以减少不必要的执行
意外结果
- 审查并优化 hook 指令的清晰度
- 在部署到生产环境前使用示例文件测试
- 检查文件模式中的边缘情况
调试步骤
- 检查 Hook 状态：验证 hook 已启用且配置正确
- 测试文件模式：确保您的目标模式匹配预期文件
- 查看日志：检查任何错误消息或警告
- 简化指令：从基本指令开始，逐渐增加复杂性
- 增量测试：在广泛应用前在小文件集上测试 hooks
故障排除最佳实践
- 保持 hook 配置的详细文档
- 尽可能在版本控制中使用 hook 设置
- 在生产环境前在开发环境中测试 hooks
- 监控 hook 性能并根据需要调整
- 随着项目发展定期审查和更新 hook 逻辑