hooks

Hooks 提供事件驱动的自动化能力，当特定事件发生时自动执行操作。

设计理念

问题

开发中有很多重复性任务：

• 保存文件后运行 linter

• 提交前运行测试

• 文件创建后添加模板

手动执行效率低。

解决方案

事件驱动的自动化：

事件发生 → 触发 Hook → 执行操作

Hook 结构

基本格式

{
  "name": "Lint on Save",
  "version": "1.0.0",
  "description": "Run linter when TypeScript files are saved",
  "when": {
    "type": "fileEdited",
    "patterns": ["*.ts", "*.tsx"]
  },
  "then": {
    "type": "runCommand",
    "command": "npm run lint"
  }
}

Hook Schema

interface Hook {
  name: string;
  version: string;
  description?: string;
  
  when: HookTrigger;
  then: HookAction;
}

type HookTrigger =
  | { type: 'fileEdited'; patterns: string[] }
  | { type: 'fileCreated'; patterns: string[] }
  | { type: 'fileDeleted'; patterns: string[] }
  | { type: 'promptSubmit' }
  | { type: 'agentStop' }
  | { type: 'preToolUse'; toolTypes: string[] }
  | { type: 'postToolUse'; toolTypes: string[] }
  | { type: 'userTriggered' };

type HookAction =
  | { type: 'askAgent'; prompt: string }
  | { type: 'runCommand'; command: string; timeout?: number };

事件类型

文件事件

fileEdited - 文件保存时触发

{
  "when": {
    "type": "fileEdited",
    "patterns": ["*.ts", "*.tsx"]
  },
  "then": {
    "type": "runCommand",
    "command": "npm run lint"
  }
}

fileCreated - 文件创建时触发

{
  "when": {
    "type": "fileCreated",
    "patterns": ["*.test.ts"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Add test template to the new file"
  }
}

fileDeleted - 文件删除时触发

{
  "when": {
    "type": "fileDeleted",
    "patterns": ["*.ts"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Check if any imports need to be updated"
  }
}

Agent 事件

promptSubmit - 用户发送消息时触发

{
  "when": {
    "type": "promptSubmit"
  },
  "then": {
    "type": "runCommand",
    "command": "git status"
  }
}

agentStop - Agent 执行完成时触发

{
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "npm run test"
  }
}

工具事件

preToolUse - 工具执行前触发

{
  "when": {
    "type": "preToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Verify this write operation is safe"
  }
}

postToolUse - 工具执行后触发

{
  "when": {
    "type": "postToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "runCommand",
    "command": "git add -A"
  }
}

Hook 操作

askAgent

让 AI 执行某个操作：

{
  "type": "askAgent",
  "prompt": "Review the changes and suggest improvements"
}

runCommand

执行 Shell 命令：

{
  "type": "runCommand",
  "command": "npm run lint",
  "timeout": 30000
}

创建 Hook

使用 createHook 工具

await createHook({
  id: 'format-on-save',
  name: 'Format on Save',
  description: 'Auto-format code when files are saved',
  eventType: 'fileEdited',
  filePatterns: '*.ts,*.tsx',
  hookAction: 'runCommand',
  command: 'npm run format',
  why: 'Ensure consistent code formatting',
});

手动创建

// .kiro/hooks/my-hook.json
{
  "name": "My Hook",
  "version": "1.0.0",
  "when": {
    "type": "fileEdited",
    "patterns": ["*.ts"]
  },
  "then": {
    "type": "runCommand",
    "command": "npm run lint"
  }
}

Hook 管理

列出 Hooks

# 在 Kiro 中查看
Explorer → Agent Hooks

# 或使用命令
claude-code hooks list

启用/禁用

{
  "name": "My Hook",
  "enabled": false,  // 禁用 Hook
  "when": { ... },
  "then": { ... }
}

实用示例

1

自动测试

{
  "name": "Test on Save",
  "when": {
    "type": "fileEdited",
    "patterns": ["src/**/*.ts"]
  },
  "then": {
    "type": "runCommand",
    "command": "npm run test -- --related"
  }
}

2

代码审查

{
  "name": "Review Changes",
  "when": {
    "type": "postToolUse",
    "toolTypes": ["write"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Review the changes for potential issues"
  }
}

3

自动提交

{
  "name": "Auto Commit",
  "when": {
    "type": "agentStop"
  },
  "then": {
    "type": "runCommand",
    "command": "git add -A && git commit -m 'Auto commit'"
  }
}

下一步

• 查看 Skills 系统 的上下文注入

• 了解 Plugins 系统 的开发

• 探索 工具系统 的完整能力