Kiro 特色功能#

# 实际示例：Kiro 自动生成的需求定义

## 用户故事
As a: 用户
I want to: 使用邮箱地址和密码登录
So that: 能使用服务的个性化功能

## 接受标准（EARS 语法）
When: 用户访问登录页面时
The system shall: 显示登录表单
With:
  - 邮箱地址输入框
  - 密码输入框（以掩码形式显示）
  - "登录"按钮
  - "忘记密码"链接

When: 用户输入正确的认证信息并点击登录按钮时
The system shall: 将用户重定向到仪表板页面
And: 生成 JWT 令牌并启动会话

When: 用户输入了错误的认证信息时
The system shall: 显示错误信息
But: 出于安全考虑，不显示具体错误原因

// Kiro 自动生成的技术设计文档示例

## 架构设计

### 前端结构

```ts
interface LoginSystem {
  // UI 组件
  components: {
    LoginForm: {
      path: "components/auth/LoginForm.tsx";
      props: {
        onSubmit: (credentials: LoginCredentials) => Promise<void>;
        onForgotPassword: () => void;
      };
    };

    PasswordResetModal: {
      path: "components/auth/PasswordResetModal.tsx";
      props: {
        isOpen: boolean;
        onClose: () => void;
      };
    };
  };

  // 状态管理
  stores: {
    AuthStore: {
      state: {
        user: User | null;
        isAuthenticated: boolean;
        isLoading: boolean;
      };
      actions: {
        login: (credentials: LoginCredentials) => Promise<void>;
        logout: () => void;
        resetPassword: (email: string) => Promise<void>;
      };
    };
  };

  // API 通信
  services: {
    AuthService: {
      endpoints: {
        login: "POST /api/auth/login";
        logout: "POST /api/auth/logout";
        resetPassword: "POST /api/auth/reset-password";
      };
    };
  };
}
```

### 后端结构

- 使用 Node.js + Express
- JWT 认证
- 使用 bcrypt 进行密码哈希
- 通过 PostgreSQL 管理用户信息

## 实现任务清单

### 前端
- [ ] 创建 LoginForm 组件
  - [ ] 实现表单校验
  - [ ] 错误处理
  - [ ] 管理加载状态
- [ ] 实现 AuthStore
  - [ ] 登录操作
  - [ ] 令牌管理
  - [ ] 自动登出功能
- [ ] 实现路由守卫
  - [ ] 未认证用户的重定向处理
  - [ ] 已认证用户的访问控制

### 后端
- [ ] 实现认证接口
  - [ ] /api/auth/login
  - [ ] /api/auth/logout
  - [ ] /api/auth/refresh
- [ ] 编写中间件
  - [ ] JWT 验证中间件
  - [ ] 请求速率限制
- [ ] 数据库设计
  - [ ] users 表
  - [ ] sessions 表

### 测试
- [ ] 单元测试
- [ ] 集成测试
- [ ] 端到端（E2E）测试

# 方法一：从 Kiro 面板操作

1. 点击左侧边栏的 Kiro 图标
2. 在 Specs 区域点击「+」按钮
3. 用自然语言输入你的需求

# 方法二：通过聊天窗口生成

1. 使用 Cmd/Ctrl + L 打开聊天面板
2. 点击「Spec」按钮
3. 输入你的需求内容

# 实际输入示例

"我想实现一个电商网站的购物车功能，
需要包含以下几点：

- 添加/删除商品
- 修改商品数量
- 检查库存
- 自动计算总金额
- 支持优惠券
- 运费计算"

# Kiro 自动生成的内容结构如下

.kiro/specs/shopping-cart/
├── requirements.md # 详细的需求定义
├── design.md # 技术设计文档
└── tasks.md # 实现任务清单

# 名称：auto-format-on-save
# 说明：在保存文件时自动格式化代码并整理 import 语句

Trigger: File Save
Target: "**/*.{js,ts,jsx,tsx}"
Instructions: |
  每当保存文件时，依次执行以下操作：

  1. 使用 ESLint 检查问题  
     - 能自动修复的部分直接修复  
     - 无法自动修复的问题列出清单  

  2. 使用 Prettier 格式化代码  
     - 优先使用项目中的 .prettierrc 配置  
     - 如果没有则使用默认配置  

  3. 整理 import 语句  
     - 删除未使用的 import  
     - 调整 import 顺序（外部 → 内部 → 相对路径）  
     - 合并重复的 import  

  4. 检查 console.log  
     - 如果在正式代码中检测到 console.log，发出警告  
     - 如果是调试用途，建议加上 `/* debug */` 注释说明

# 名称：react-component-scaffold
# 说明：在创建新的 React 组件时，自动生成所需的相关文件

Trigger: File Create
Target: "src/components/**/*.tsx"
Instructions: |
  当你新建一个 React 组件时，将自动执行以下操作：

  1. 生成组件的基础结构代码
     ```typescript
     import React from 'react'
     import styles from './ComponentName.module.css'
     
     interface ComponentNameProps {
       // TODO: 定义组件的 props
     }
     
     export const ComponentName: React.FC<ComponentNameProps> = (props) => {
       return (
         <div className={styles.container}>
           {/* TODO: 组件实现 */}
         </div>
       )
     }
     ```

  2. 创建对应的测试文件  
     - 在同一目录下生成 ComponentName.test.tsx  
     - 包含基础的渲染测试用例

  3. 创建 Storybook 的 story 文件  
     - 生成 ComponentName.stories.tsx  
     - 包含基础的组件展示 story

  4. 创建 CSS 模块样式文件  
     - 生成 ComponentName.module.css  
     - 包含基础样式定义

  5. 自动向 index.ts 添加导出语句

# 名称：security-scanner
# 说明：检查代码中是否包含 API 密钥或其他敏感信息

Trigger: File Save
Target: "**/*"
Instructions: |
  扫描文件内容，检测以下类型的敏感信息：

  1. 硬编码的认证信息  
     - API 密钥（如 AWS、Google、OpenAI 等）  
     - 密码  
     - 私钥  
     - 数据库连接字符串  

  2. 如果发现敏感信息，执行以下处理：  
     - 高亮显示包含问题的代码行  
     - 建议将敏感信息移至环境变量  
     - 给出添加到 .env 文件的示例  
     - 检查 .gitignore 中是否已包含 .env 文件  

  3. 私有 URL 检查  
     - 内部 API 端点  
     - 开发环境用的 URL  
     - 同样建议将其环境变量化  

  4. 提交前最终检查  
     - 通过 git diff 检查是否有敏感信息将被提交  
     - 如有问题，发出警告并建议中止提交操作

# 如何创建 Hook

1. 打开 Kiro 面板 → Agent Hooks → 点击「+」按钮
2. 用自然语言输入你想要实现的功能描述
3. Kiro 会自动生成配置 → 你确认后保存即可 🎉

# 设计高效 Hook 的小技巧

- 一个 Hook 只做一件事（遵循单一职责原则）
- 文件匹配规则要尽量具体（避免使用 "*/*" 这种全局匹配）
- 注意执行频率（每次保存触发可能会带来性能压力）
- 在指令中加入错误处理逻辑，增强稳定性

# 启用 / 禁用 Hook 的方法

- 点击 👁️ 图标即可切换 ON / OFF 状态
- 想临时停用某个 Hook 的时候非常方便

# 此文件会生成在 .kiro/steering/product.md

# 产品概览

## 产品名称

MyAwesomeEC 购物平台

## 使命

为中小型在线商家提供一个简单易用、功能强大的电商建站平台

## 目标用户

- 个体经营者
- 中小企业的电商负责人
- 有意通过副业经营网店的个人用户

## 核心功能

1. 商品管理

   - 库存管理
   - 商品分类
   - 支持上传多张商品图片

2. 订单管理

   - 订单状态跟踪
   - 配送进度查询
   - 退换货流程支持

3. 客户管理

   - 用户注册与登录
   - 购买历史记录查看
   - 商品收藏与愿望清单功能

4. 支付功能
   - 支持信用卡支付（集成 Stripe）
   - 便利店付款
   - 货到付款

## 业务目标

- 月交易额突破 1 亿元
- 实现 1,000 家以上活跃商户上线运营
- 将平均订单金额稳定在 5,000 元左右

# 此文件将生成在 .kiro/steering/tech.md

# 技术栈说明

## 前端

- **框架**：Next.js 14.2.5（使用 App Router）
- **语言**：TypeScript 5.5.4
- **样式处理**：
  - Tailwind CSS 3.4.1
  - CSS Modules（组件级样式）
- **状态管理**：Zustand 4.5.4
- **表单处理**：React Hook Form 7.52.1
- **数据验证**：Zod 3.23.8

## 后端

- **运行时环境**：Node.js 20.x
- **框架**：Express 4.19.2
- **ORM 工具**：Prisma 5.17.0
- **认证机制**：NextAuth.js 4.24.7

## 数据库

- **生产环境**：PostgreSQL 15（托管于 AWS RDS）
- **开发环境**：PostgreSQL 15（通过 Docker 本地运行）
- **缓存服务**：Redis 7.2

## 基础设施 & 部署

- **前端托管**：Vercel
- **API 部署**：AWS Lambda + API Gateway
- **图片分发**：Cloudinary
- **监控系统**：Datadog

## 开发工具

- **包管理器**：pnpm 8.15.6
- **代码规范检查**：ESLint 8.57.0
- **代码格式化工具**：Prettier 3.3.3
- **测试框架**：
  - Jest 29.7.0
  - React Testing Library
  - Playwright（端到端测试）

## 注意事项

- Node.js 版本通过 `.nvmrc` 进行管理
- 必须使用 pnpm（禁止使用 npm 或 yarn）
- 已通过 Husky 设置 pre-commit 钩子

# 此文件将生成在 .kiro/steering/structure.md

# 项目结构说明

## 目录结构

project-root/
├── .kiro/ # Kiro 配置目录
│ ├── steering/ # 项目信息（AI 使用的上下文）
│ └── settings/ # Kiro 的运行设置
├── src/
│ ├── app/ # Next.js 的 App Router 页面目录
│ │ ├── (auth)/ # 需要身份验证的页面
│ │ ├── (public)/ # 公共访问页面
│ │ ├── api/ # API 路由
│ │ └── layout.tsx # 根级布局组件
│ ├── components/ # UI 组件目录
│ │ ├── common/ # 通用组件（例如按钮、卡片等）
│ │ ├── features/ # 按功能模块分类的组件
│ │ └── ui/ # 基础 UI 元件（输入框、标签等）
│ ├── hooks/ # 自定义 React Hooks
│ ├── lib/ # 工具方法与模块集合
│ │ ├── api/ # 封装的 API 客户端
│ │ ├── utils/ # 通用工具函数
│ │ └── constants/ # 常量定义
│ ├── stores/ # Zustand 状态管理逻辑
│ └── types/ # TypeScript 类型定义

├── prisma/
│ ├── schema.prisma # 数据库结构定义（Prisma Schema）
│ └── migrations/ # 数据库迁移记录

├── public/ # 静态资源文件（图片、图标等）
├── tests/ # 测试文件目录（单元测试、集成测试）
└── docs/ # 项目文档与说明文件

### **命名规范**

#### **文件命名：**

- **组件（Component）**：使用 PascalCase 命名，文件扩展名为 .tsx
  示例：ProductCard.tsx
- **自定义 Hook**：使用 camelCase 命名，扩展名为 .ts
  示例：useAuth.ts
- **工具函数（Utility）**：使用 camelCase 命名，扩展名为 .ts
  示例：formatPrice.ts
- **类型定义**：统一命名为 types.ts 或 models.ts
- **常量定义**：文件命名为 constants.ts，文件内常量使用全大写 SNAKE_CASE 命名
  示例：MAX_ITEM_COUNT, DEFAULT_CURRENCY

#### **代码中的命名规则：**

- **变量 / 函数**：使用 camelCase 命名
  示例：userName, getProductList
- **常量**：使用全大写 SNAKE_CASE 命名（UPPER_SNAKE_CASE）
  示例：DEFAULT_TIMEOUT, MAX_RETRY_COUNT
- **类型 / 接口（Type & Interface）**：使用 PascalCase 命名
  示例：UserProfile, OrderItem
- **枚举（Enum）**：枚举名使用 PascalCase，枚举值使用全大写 SNAKE_CASE

### 导入顺序（Import 顺序）建议如下：

1. React 相关模块（例如 react, react-dom, next 等）
2. 外部库（如 lodash, axios, zustand 等）
3. 内部路径别名（如 @/components, @/lib 等）
4. 相对路径（例如 ../utils, ./Button）
5. 样式文件（如 .css, .scss, .module.css）
   例：

```JavaScript
// 1. React 相关
import React, { useState } from 'react'

// 2. 外部库
import { useRouter } from 'next/navigation'
import axios from 'axios'

// 3. 内部路径别名
import { Button } from '@/components/ui'
import { formatPrice } from '@/lib/utils'

// 4. 相对路径
import { ProductType } from './types'

// 5. 样式文件
import styles from './Product.module.css'

```

# .kiro/steering/api-standards.md

---

inclusion: fileMatch
fileMatchPattern: "app/api/*"

---

# API 设计标准

## 接口设计

### URL 设计原则

- 采用 RESTful 设计
- 资源名称使用复数形式（例如 /users, /products）
- 路径层级最多为三层
- 使用 kebab-case（例如 /user-profiles）

### HTTP 方法使用规范

- GET：获取资源（幂等）
- POST：创建资源
- PUT：整体更新资源
- PATCH：部分更新资源
- DELETE：删除资源

## 响应格式

### 成功响应示例

```json
{
  "success": true,
  "data": {
    // 实际数据内容
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "version": "1.0",
    "requestId": "uuid-here"
  }
}
```

### **错误响应（Error Responses）**

```JSON
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入值不合法",
    "details": [
      {
        "field": "email",
        "message": "请输入有效的邮箱地址"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "requestId": "uuid-here"
  }
}
```

---
inclusion: always
---

---
inclusion: fileMatch
fileMatchPattern: 'components/**/*.tsx'
---

---
inclusion: manual
---

# 一个完整的项目开发流程

1. 📋 使用 Spec 模式定义需求
   "创建一个用户管理系统"

2. 🎨 连接 Figma Power 获取设计
   "从 Figma 中获取用户列表页面的设计规范"

3. 🗄️ 使用 Supabase Power 设置数据库
   "在 Supabase 中创建 users 表，包含邮箱、姓名和创建时间字段"

4. 💻 开发功能（Kiro IDE + Agent）
   "基于设计稿和数据库结构实现用户管理界面"

5. 🧪 使用 Postman Power 测试 API
   "创建用户管理 API 的测试集合"

6. 🚀 使用 Netlify Power 部署
   "将应用部署到 Netlify 生产环境"

7. 🔍 使用 Datadog Power 监控
   "查看应用的性能指标和错误日志"

# 生产环境问题快速定位

1. 🚨 发现问题
   "用户反馈登录功能异常"

2. 🔍 Datadog Power 查询日志
   "查询过去1小时内登录相关的错误日志"

3. 📊 分析性能数据
   "获取登录 API 的响应时间和错误率趋势"

4. 🗄️ Supabase Power 检查数据
   "检查用户表中的数据完整性"

5. 🔧 修复并测试
   "修复问题后使用 Postman Power 验证功能"

6. 🚀 重新部署
   "通过 Netlify Power 部署修复版本"

# 方法一：通过 Kiro Powers 市场（推荐）
1. 访问 https://kiro.dev/powers/
2. 浏览可用的 Powers
3. 点击 "Add to Kiro" 按钮一键安装

# 方法二：通过 Kiro IDE
1. 打开 Kiro IDE
2. 在 Powers 面板中浏览和安装
3. Kiro 自动处理配置和设置

# 方法三：手动配置（高级用户）
1. 编辑 .kiro/settings/mcp.json 文件
2. 添加 Power 的配置信息
3. 重启 Kiro 或重新连接 MCP 服务器

# Powers 会根据对话上下文自动激活

"帮我设计一个登录页面" → 自动激活 Figma Power

"创建一个新的数据表" → 自动激活 Supabase Power

"查询生产环境的错误日志" → 自动激活 Datadog Power

"部署当前项目" → 自动激活 Netlify Power