当 hooks 配置完成但没有按预期触发，或触发后行为异常、系统变慢，问题通常藏在文件模式匹配、hook 开关状态、触发事件类型或指令逻辑中。本文按三类典型故障场景梳理排查路径，适合已有一定 hooks 使用经验、遇到具体问题时快速检索。

Hooks 出现异常时，按以下分类逐步排查，通常能快速定位根因。

Hook 不触发

遇到 hook 应该触发但没有响应的情况，按顺序检查：

• 文件关联 hooks：确认文件匹配模式（file pattern）与目标文件路径一致。模式过于严格（如路径大小写不匹配）会导致静默失败。
• 确认 hook 已启用：在 Agent Hooks 面板查看 hook 旁边的状态，确保没有被禁用。
• 确认事件类型正确：例如，File Save 只在保存时触发，而不是修改时；Agent Stop 只在 agent 回复结束后触发，而非中途。

Hook 行为异常

Hook 触发了，但结果不符合预期：

• 检查指令是否清晰：指令（instructions）写得模糊时，agent 可能自行解释，导致非预期行为。尽量用具体、可验证的表述。
• 检查 hooks 之间是否冲突：多个 hook 监听同一事件且指令相互矛盾时，结果会不稳定。建议给每个 hook 划定明确的职责边界。
• 检查文件模式是否过宽：**/* 这类通配符会匹配项目内所有文件，可能触发意料之外的 hook 执行。

性能问题

Hooks 使整体响应变慢时：

• 收窄文件匹配范围：将 **/* 改为 src/**/*.ts 等更具体的模式，减少不必要的触发。
• 简化 agent prompt 类 actions 的指令：指令越复杂，agent 处理时间越长；拆分成多个细粒度 hooks 往往比单个复杂 hooks 更高效。
• 优化 shell command 类 actions：确保执行的命令能快速完成，避免在 hook 中运行耗时的构建或测试任务（除非这是设计目标）。
• 降低触发频率：评估触发事件是否过于频繁，比如将 File Save 改为 Manual Trigger 或 Agent Stop。

更多排查信息，参考 Kiro 通用故障排查指南。

常见问题

Q：文件模式语法有什么注意事项？

Kiro 使用 glob 语法，* 匹配单层目录，** 匹配任意深度。*.ts 只匹配根目录下的 TypeScript 文件，**/*.ts 才能匹配所有子目录。路径分隔符统一使用正斜杠 /。

Q：两个 hook 同时触发时，执行顺序是怎样的？

Hooks 按照在配置中的顺序依次执行，并非并发。如果顺序对结果有影响，建议在 hook 描述中明确标注执行序号，方便后续维护。

Q：怎么判断是 hook 没触发，还是触发了但 agent 没有执行正确操作？

可以在指令中加入明确的输出要求，例如"执行完成后在聊天中回复'已执行 lint'"，这样可以区分"未触发"和"触发但行为错误"两种情况。