Kiro AI 助手完整使用指南

Kiro AI 助手完整使用指南

目录

核心概念

Kiro 是一个 AI 驱动的 IDE 助手，专注于帮助开发者高效完成编码任务。它不仅能理解你的代码，还能主动执行操作、自动化工作流程。

核心能力

• 📝 读写代码文件
• 🔍 智能代码分析
• 🛠️ 执行 Shell 命令
• 🌐 联网搜索最新信息
• 🤖 自动化工作流程
• 📊 代码变更追踪

工作模式

1. Autopilot 模式（自动驾驶）

• Kiro 可以自主修改工作区内的文件
• 适合：快速迭代、批量修改、自动化任务
• 使用场景：重构代码、批量更新、自动修复

2. Supervised 模式（监督模式）

• 每次修改后，你可以选择接受或撤销
• 适合：关键代码修改、学习 Kiro 的工作方式
• 使用场景：核心业务逻辑、安全敏感代码

切换方式: 在 Kiro 设置中选择工作模式

Specs – 规范驱动开发

Specs 是一种结构化的功能开发方法，将复杂功能分解为：需求 → 设计 → 任务。

什么是 Spec？

Spec 是一个正式化的开发流程，包含三个核心文档：

• requirements.md – 需求文档
• design.md – 设计文档
• tasks.md – 任务清单

Spec 类型

1. Feature Spec（功能规范）

用于构建新功能或能力

适用场景:

• 添加新功能或增强
• 实现新的用户界面
• 创建新的系统能力
• 构建集成或新模块

触发词: “add”, “new”, “create”, “implement”, “build”, “develop”

示例:

"我想添加用户认证功能"
"创建一个新的仪表板"
"实现支付处理"

2. Bugfix Spec（修复规范）

用于修复已损坏或不正确的功能

适用场景:

• 某些功能崩溃或报错
• 现有行为不正确
• 引入了回归问题
• 需要修复错误处理

触发词: “fix”, “bug”, “crash”, “error”, “broken”, “issue”, “problem”

示例:

"修复数量为零时的崩溃"
"登录在移动端报错"
"用户无法提交表单"

Spec 工作流程

Feature Spec 有两种工作流：

1. Requirements-First（需求优先）

需求文档 → 设计文档 → 任务清单

• 适合：业务需求明确，但技术方案待定
• 示例：“我需要一个帮助客户追踪订单的系统”

2. Design-First（设计优先）

设计文档 → 需求文档 → 任务清单

• 适合：技术方案清晰，需要形式化需求
• 示例：“我想用微服务架构实现事件溯源”

Bugfix Spec 工作流：

Bug 条件探索 → 设计修复方案 → 任务清单

• 使用 Bug Condition 方法论
• 通过属性测试验证修复

如何创建 Spec

方式 1: 直接对话

"创建一个用户认证的 spec"
"我想为购物车功能写一个规范"

方式 2: 使用命令面板

• 打开命令面板（Ctrl/Cmd + Shift + P）
• 搜索 “Kiro: Create Spec”

Spec 文件结构

.kiro/specs/
└── user-authentication/ # 功能名称（kebab-case）
├── .config.kiro # 配置文件
├── requirements.md # 需求文档
├── design.md # 设计文档
└── tasks.md # 任务清单

执行 Spec 任务

执行单个任务:

"执行任务 2"
"开始任务 1.3"

执行所有任务:

"运行所有任务"
"执行完整的 spec"

Spec 文件引用

在 Spec 文档中，你可以引用其他文件：

#[[file:openapi.yaml]]
#[[file:schema.graphql]]

这样 Kiro 在处理 Spec 时会自动读取这些文件的内容。

Hooks – 自动化触发器

Hooks 允许你在特定事件发生时自动触发 AI 操作。

Hook 事件类型

文件事件

• fileEdited – 文件被编辑并保存
• fileCreated – 创建新文件
• fileDeleted – 删除文件

对话事件

• promptSubmit – 发送消息给 AI
• agentStop – AI 执行完成

工具事件

• preToolUse – 工具执行前（可用于权限检查）
• postToolUse – 工具执行后（可用于验证）

任务事件

• preTaskExecution – Spec 任务开始前
• postTaskExecution – Spec 任务完成后

手动触发

• userTriggered – 用户手动点击触发

Hook 动作类型

1. askAgent（询问 AI）

• 向 AI 发送提示
• 适合：代码审查、提醒、建议

2. runCommand（运行命令）

• 执行 Shell 命令
• 适合：运行测试、代码检查、构建

Hook 配置示例

示例 1: 保存时自动 Lint

{
"name": "Lint on Save",
"version": "1.0.0",
"when": {
"type": "fileEdited",
"patterns": ["*.ts", "*.tsx"]
},
"then": {
"type": "runCommand",
"command": "npm run lint"
}
}

示例 2: 写操作前审查

{
"name": "Review Write Operations",
"version": "1.0.0",
"when": {
"type": "preToolUse",
"toolTypes": ["write"]
},
"then": {
"type": "askAgent",
"prompt": "验证此写操作是否符合编码标准"
}
}

示例 3: 任务完成后运行测试

{
"name": "Run Tests After Task",
"version": "1.0.0",
"when": {
"type": "postTaskExecution"
},
"then": {
"type": "runCommand",
"command": "npm run test"
}
}

管理 Hooks

方式 1: 使用 UI

• 打开命令面板
• 搜索 “Open Kiro Hook UI”
• 可视化创建和管理 Hooks

方式 2: 直接编辑

• Hooks 存储在 .kiro/hooks/ 目录
• 每个 Hook 是一个 JSON 文件

方式 3: 对话创建

"创建一个 Hook，在保存 TypeScript 文件时运行 lint"
"添加一个 Hook，在任务完成后运行测试"

Hook 文件位置

.kiro/hooks/
├── lint-on-save.json
├── review-writes.json
└── test-after-task.json

Steering – 行为定制规则

Steering 规则允许你定制 Kiro 的行为和工作方式。

什么是 Steering？

Steering 是 Markdown 文件，包含额外的上下文和指令，影响 Kiro 的所有或部分交互。

Steering 类型

1. Always Included（始终包含）

—
inclusion: always
—

# 我的编码标准

– 使用 TypeScript 严格模式
– 所有函数必须有 JSDoc 注释
– 使用 4 空格缩进

2. File Match（文件匹配）

—
inclusion: fileMatch
fileMatchPattern: '**/*.test.ts'
—

# 测试文件规则

– 使用 Jest 框架
– 每个测试必须有描述性名称
– 使用 AAA 模式（Arrange-Act-Assert）

3. Manual（手动引用）

—
inclusion: manual
—

# API 设计指南

– RESTful 风格
– 使用语义化的 HTTP 状态码
– 统一的错误响应格式

在聊天中使用 # 引用：

"按照 #API设计指南 创建用户 API"

Steering 文件位置

工作区级别（优先级更高）:

.kiro/steering/
├── coding-standards.md
├── test-rules.md
└── api-guidelines.md

用户级别（全局）:

~/.kiro/steering/
├── personal-preferences.md
└── common-patterns.md

文件引用

Steering 文件中可以引用其他文件：

# API 规范

参考我们的 OpenAPI 定义：
#[[file:api/openapi.yaml]]

创建 Steering 规则

方式 1: 对话创建

"创建一个 Steering 规则，要求所有组件使用函数式写法"
"添加编码标准到 Steering"

方式 2: 直接编辑

• 在 .kiro/steering/ 创建 .md 文件
• 添加 front-matter 配置
• 编写规则内容

实际应用示例

代码变更追踪规则

—
inclusion: always
—

# 代码变更自动记录规则

当完成文件变更后，自动调用记录工具追踪变更。

触发条件：
– 创建新文件
– 修改现有文件
– 删除文件内容
– 重构代码

这就是你当前激活的 Steering 规则！

MCP – 模型上下文协议

MCP 允许 Kiro 连接外部工具和服务，扩展其能力。

什么是 MCP？

Model Context Protocol（模型上下文协议）是一个标准，允许 AI 模型与外部系统交互。

MCP 配置文件

用户级别（全局）:

~/.kiro/settings/mcp.json

工作区级别:

.kiro/settings/mcp.json

MCP 配置示例

{
"mcpServers": {
"aws-docs": {
"command": "uvx",
"args": ["awslabs.aws-documentation-mcp-server@latest"],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
},
"database": {
"command": "uvx",
"args": ["mcp-server-postgres"],
"env": {
"DATABASE_URL": "postgresql://localhost/mydb"
},
"disabled": false,
"autoApprove": ["query_read"]
}
}
}

配置字段说明

• command: 启动 MCP 服务器的命令（通常是 uvx）
• args: 命令参数（包名和版本）
• env: 环境变量
• disabled: 是否禁用此服务器
• autoApprove: 自动批准的工具列表

安装 MCP 依赖

大多数 MCP 服务器使用 uvx 运行，需要先安装 uv：

使用 pip:

pip install uv

使用 Homebrew (macOS):

brew install uv

使用 Cargo (Rust):

cargo install uv

管理 MCP 服务器

方式 1: 命令面板

• 打开命令面板
• 搜索 “MCP”
• 查看可用的 MCP 命令

方式 2: MCP Server 视图

• 在 Kiro 功能面板中找到 “MCP Server” 视图
• 查看、启用、禁用服务器
• 配置更改后自动重连

方式 3: 对话配置

"配置 MCP 连接到我的 PostgreSQL 数据库"
"添加 AWS 文档 MCP 服务器"

常用 MCP 服务器

• aws-documentation-mcp-server – AWS 文档查询
• mcp-server-postgres – PostgreSQL 数据库操作
• mcp-server-git – Git 仓库操作
• mcp-server-filesystem – 文件系统访问

测试 MCP 工具

"测试 AWS 文档 MCP 工具"
"使用数据库 MCP 查询用户表"

聊天上下文

Kiro 可以访问多种上下文信息，帮助它更好地理解你的需求。

使用 # 引用上下文

#File – 引用文件

"查看 #src/App.tsx 的实现"
"重构 #utils/helper.ts 中的函数"

#Folder – 引用文件夹

"分析 #src/components 目录结构"
"重构 #services 文件夹中的代码"

#Problems – 当前文件的问题

"修复 #Problems"
"解决这些诊断问题 #Problems"

#Terminal – 终端输出

"分析 #Terminal 中的错误"
"根据 #Terminal 输出调试问题"

#Git Diff – Git 变更

"审查 #Git Diff"
"解释这些变更 #Git Diff"

拖拽图片

你可以直接拖拽图片到聊天框，Kiro 可以分析图片内容：

• UI 设计稿 → 生成代码
• 错误截图 → 诊断问题
• 架构图 → 理解系统设计

实战示例

示例 1: 创建新功能（使用 Spec）

你: "创建一个用户认证功能的 spec"

Kiro: 这是新功能还是修复 bug？
[选项: 新功能 / 修复 Bug]

你: "新功能"

Kiro: 你想从哪里开始？
[选项: 需求文档 / 技术设计]

你: "需求文档"

Kiro: [创建 requirements.md]
需求文档已创建，包含：
– 用户故事
– 验收标准
– 正确性属性

你: "看起来不错，继续"

Kiro: [创建 design.md]
设计文档已创建，包含：
– 系统架构
– 数据模型
– API 设计

你: "继续"

Kiro: [创建 tasks.md]
任务清单已创建，共 8 个任务

你: "执行所有任务"

Kiro: [依次执行任务 1-8]
✓ 任务 1: 创建用户模型
✓ 任务 2: 实现注册 API
…
✓ 任务 8: 编写集成测试

所有任务已完成！

示例 2: 快速修改（不使用 Spec）

你: "在 #src/App.tsx 中添加一个加载状态"

Kiro: [修改文件]
已添加 loading 状态和 Spinner 组件

[自动记录变更]
– 文件修改: src/App.tsx
– 新增: 15 行
– 删除: 3 行

示例 3: 使用 Hook 自动化

你: "创建一个 Hook，每次保存 TypeScript 文件时运行 ESLint"

Kiro: [创建 Hook 文件]
Hook 已创建: .kiro/hooks/lint-on-save.json

现在每次保存 .ts 或 .tsx 文件时，会自动运行 ESLint

示例 4: 使用 Steering 定制行为

你: "创建一个 Steering 规则，要求所有 API 响应使用统一格式"

Kiro: [创建 Steering 文件]
Steering 规则已创建: .kiro/steering/api-response-format.md

现在我会确保所有 API 响应遵循这个格式：
{
"success": boolean,
"data": any,
"error": string | null
}

示例 5: 联网搜索最新信息

你: "React 19 有哪些新特性？"

Kiro: [搜索网络]
根据最新文档，React 19 的主要新特性包括：
1. Server Components 正式发布
2. Actions 简化表单处理
3. 新的 use() Hook
…

[来源: react.dev]

示例 6: 修复 Bug（使用 Bugfix Spec）

你: "创建一个 spec 修复数量为零时的崩溃"

Kiro: 这是新功能还是修复 bug？
[选项: 新功能 / 修复 Bug]

你: "修复 Bug"

Kiro: [创建 bugfix.md]
Bug 条件文档已创建：
– Bug 描述
– 重现步骤
– Bug 条件 C(X)

你: "继续"

Kiro: [创建 design.md]
修复设计已创建：
– 根因分析
– 修复方案
– 验证策略

你: "执行所有任务"

Kiro: [执行任务]
✓ 任务 1: 编写 Bug 探索测试（测试失败 ✓ – 确认 Bug 存在）
✓ 任务 2: 实现修复
✓ 任务 3: 验证修复（测试通过 ✓）

Bug 已修复并验证！

最佳实践

1. 选择合适的工作方式

使用 Spec 当:

• 功能复杂，需要规划
• 团队协作，需要文档
• 需要追踪进度
• 想要结构化开发

直接对话当:

• 快速修改
• 简单任务
• 探索性编程
• 学习和实验

2. 善用上下文引用

# 好的做法
"重构 #src/utils/helper.ts 中的日期处理函数"

# 不够好的做法
"重构 helper.ts"（Kiro 可能找不到文件）

3. 利用 Hooks 自动化重复任务

常见的自动化场景：

• 保存时 Lint
• 提交前运行测试
• 文件创建时添加模板
• 任务完成后运行验证

4. 用 Steering 建立团队标准

—
inclusion: always
—

# 团队编码标准

## TypeScript
– 启用严格模式
– 使用接口而非类型别名（公共 API）
– 所有导出函数必须有 JSDoc

## React
– 使用函数组件
– Props 使用接口定义
– 使用 React.FC 类型

5. 渐进式采用

快速参考

常用命令

# 创建 Spec
"创建一个 [功能名] 的 spec"

# 执行任务
"执行任务 [编号]"
"运行所有任务"

# 文件操作
"创建 [文件名]"
"修改 #[文件路径]"
"重构 #[文件夹]"

# 上下文引用
"查看 #File"
"分析 #Folder"
"修复 #Problems"
"解释 #Terminal"
"审查 #Git Diff"

# Hook 管理
"创建一个 Hook [描述]"
"打开 Hook UI"

# Steering 管理
"创建 Steering 规则 [描述]"
"添加编码标准"

# MCP 管理
"配置 MCP [服务名]"
"测试 MCP 工具"

文件结构

项目根目录/
├── .kiro/
│ ├── hooks/ # Hook 配置文件
│ │ └── *.json
│ ├── steering/ # Steering 规则文件
│ │ └── *.md
│ ├── settings/ # 设置文件
│ │ └── mcp.json # MCP 配置
│ └── specs/ # Spec 文件
│ └── feature-name/
│ ├── .config.kiro
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── .ai-activity/ # AI 活动日志
└── ai-code-tracker.log

获取帮助

在对话中询问

"如何创建 Hook？"
"Spec 和直接对话有什么区别？"
"如何配置 MCP 服务器？"

查看文档

• Kiro 官方文档
• 命令面板中的帮助命令
• 本指南文件

实验和探索

Kiro 很智能，你可以用自然语言描述你想做的事情，它会理解并执行。不要害怕尝试！

总结

Kiro 是一个强大而灵活的 AI 编程助手：

• 直接对话 – 快速完成简单任务
• Specs – 结构化开发复杂功能
• Hooks – 自动化重复工作
• Steering – 定制行为和标准
• MCP – 扩展能力连接外部服务

选择适合你的工作方式，逐步探索更高级的功能。祝编码愉快！🚀