Kiro Agent Hooks 完全指南

一、什么是 Hooks

Hooks（钩子）是 Kiro 提供的事件驱动自动化机制。它的核心思想很简单：

当某个事件发生时，自动执行一个预设的操作。

Hook 文件存放在项目的 .kiro/hooks/ 目录中，文件扩展名为 .kiro.hook，内容为 JSON 格式。

二、Hook 文件结构

json 复制代码

{
  "enabled": true,
  "name": "Hook 名称",
  "version": "1.0.0",
  "description": "这个 Hook 做什么的描述",
  "when": {
    "type": "事件类型",
    "patterns": ["文件匹配模式（仅文件事件需要）"],
    "toolTypes": ["工具类别（仅 preToolUse/postToolUse 需要）"]
  },
  "then": {
    "type": "操作类型",
    "prompt": "提示词（askAgent 时必填）",
    "command": "shell 命令（runCommand 时必填）"
  }
}

三、触发事件类型（when.type）

事件类型	触发时机	额外参数
`fileEdited`	用户保存文件时	`patterns`：文件匹配模式
`fileCreated`	新建文件时	`patterns`：文件匹配模式
`fileDeleted`	删除文件时	`patterns`：文件匹配模式
`promptSubmit`	用户发送消息给 AI 时	无
`agentStop`	AI 执行完成时	无
`preToolUse`	AI 调用工具之前	`toolTypes`：工具类别或正则
`postToolUse`	AI 调用工具之后	`toolTypes`：工具类别或正则
`preTaskExecution`	Spec 任务开始执行前	无
`postTaskExecution`	Spec 任务执行完成后	无
`userTriggered`	用户手动点击触发	无

toolTypes 可用类别

用于 preToolUse 和 postToolUse：

read --- 读取类工具
write --- 写入类工具
shell --- 终端命令类工具
web --- 网络请求类工具
spec --- Spec 相关工具
* --- 所有工具
支持正则匹配，如 ".*sql.*" 匹配包含 sql 的 MCP 工具名

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

四、操作类型（then.type）

askAgent --- 向 AI 发送提示

让 AI 在执行过程中接收一条额外的指令或提醒，用于自检、补充逻辑等。

json 复制代码

"then": {
  "type": "askAgent",
  "prompt": "请检查代码是否有安全隐患"
}

runCommand --- 执行 shell 命令

自动运行一条终端命令，如 lint、测试、构建等。

json 复制代码

"then": {
  "type": "runCommand",
  "command": "npm run lint"
}

五、典型应用场景

场景	事件	操作
写入前代码审查	`preToolUse` + `write`	`askAgent` 检查规范
保存后自动格式化	`fileEdited`	`runCommand` 跑 prettier
任务完成后跑测试	`postTaskExecution`	`runCommand` 跑测试
提交前安全扫描	`preToolUse` + `write`	`askAgent` 检查敏感信息
新建文件时添加头部注释	`fileCreated`	`askAgent` 补充文件头

六、完整示例：前端项目保存后自动 Lint + 单测

假设你有一个 React + TypeScript 前端项目，需要：

每次编辑 .ts / .tsx 文件后自动运行 ESLint
AI 每次写入文件前检查是否遵循 React 最佳实践

示例 1：保存后自动 ESLint

文件路径：.kiro/hooks/lint-on-save.kiro.hook

json 复制代码

{
  "enabled": true,
  "name": "Lint on Save",
  "version": "1.0.0",
  "description": "当 TypeScript/TSX 文件被编辑保存后，自动运行 ESLint 检查语法和风格问题。",
  "when": {
    "type": "fileEdited",
    "patterns": ["*.ts", "*.tsx"]
  },
  "then": {
    "type": "runCommand",
    "command": "npx eslint --fix --no-error-on-unmatched-pattern ."
  }
}

示例 2：写入前 React 最佳实践检查

文件路径：.kiro/hooks/react-best-practices.kiro.hook

json 复制代码

{
  "enabled": true,
  "name": "React Best Practices Review",
  "version": "1.0.0",
  "description": "在 AI 写入代码前，自动检查是否符合 React 最佳实践，包括 Hooks 规则、组件拆分、性能优化等。",
  "when": {
    "type": "preToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "在写入代码前，请检查以下 React 最佳实践：\n1. Hooks 是否在组件顶层调用（不在条件/循环中）\n2. useEffect 的依赖数组是否完整且正确\n3. 是否避免了在 render 中创建新对象/函数（应使用 useMemo/useCallback）\n4. 组件是否过大，是否需要拆分为子组件\n5. Props 是否定义了 TypeScript 类型\n6. 事件处理函数是否使用 handleXxx 命名\n7. 是否存在内存泄漏风险（如未清理的定时器/订阅）\n如发现问题，请修正后再写入。"
  }
}

示例 3：Spec 任务完成后跑单测

文件路径：.kiro/hooks/test-after-task.kiro.hook

json 复制代码

{
  "enabled": true,
  "name": "Run Tests After Task",
  "version": "1.0.0",
  "description": "每当一个 Spec 任务完成后，自动运行 Vitest 单元测试，确保改动没有破坏现有功能。",
  "when": {
    "type": "postTaskExecution"
  },
  "then": {
    "type": "runCommand",
    "command": "npx vitest --run"
  }
}

七、注意事项

preToolUse 的访问控制语义：如果 Hook 输出明确表示"拒绝/不允许"，AI 将不会执行该工具调用。这可以用作权限守卫。
避免循环依赖：preToolUse 的 Hook 如果触发了另一个需要相同工具的操作，可能产生无限循环。Kiro 会检测并跳过嵌套的重复 Hook。
enabled 字段 ：设置为 false 可临时禁用某个 Hook，无需删除文件。
管理方式 ：
- 直接编辑 .kiro/hooks/ 目录下的 JSON 文件
- 通过 Kiro 左侧面板的 "Agent Hooks" 区域查看和管理
- 通过命令面板搜索 "Open Kiro Hook UI" 打开可视化界面

八、一句话总结

Hooks 让你为 AI 助手设定"自动行为规则"------在正确的时机自动执行检查或命令，确保代码质量，减少重复的手动提醒。