kiro-spec-engine 1.3.0 → 1.4.0

package/docs/zh/tools/kiro-guide.md

@@ -0,0 +1,342 @@
+# 在 Kiro 中使用 kse
+
+> kse 与 Kiro IDE 的原生集成 - 最无缝的体验
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23  
+**工具**: Kiro IDE  
+**集成模式**: 原生集成  
+**预计设置时间**: 0 分钟（开箱即用）
+
+---
+
+## 概述
+
+**Kiro IDE** 是专为 Spec 驱动开发设计的 AI 驱动 IDE。kse (Kiro Spec Engine) 是 Kiro 的核心组件。
+
+**kse 与 Kiro 的集成**是**完全原生的** - 无需设置、无需手动导出、无需配置。一切都开箱即用！
+
+### 为什么在 Kiro 中使用 kse？
+
+- ✅ **零配置** - 开箱即用
+- ✅ **原生集成** - kse 是 Kiro 的一部分
+- ✅ **自动上下文** - Kiro 始终知道你的 Spec
+- ✅ **可视化工具** - Spec 浏览器、任务跟踪器等
+- ✅ **最佳体验** - 专为 Spec 驱动开发设计
+
+---
+
+## 集成模式
+
+**模式：** 原生集成
+
+**工作原理：**
+1. Kiro 自动检测 `.kiro/` 目录
+2. Kiro 的 AI 始终可以访问你的 Spec
+3. 无需手动导出或粘贴
+4. Kiro 自动更新任务状态
+5. 可视化工具显示进度
+
+---
+
+## 设置
+
+### 无需设置！
+
+如果你使用 Kiro IDE，kse 已经集成。只需：
+
+1. **打开你的项目** 在 Kiro 中
+2. **运行 `kse adopt`**（如果尚未采用）
+3. **开始创建 Spec！**
+
+就是这样！Kiro 会处理其余的事情。
+
+---
+
+## 使用方法
+
+### 方法 1：使用 Spec 浏览器（推荐）
+
+Kiro 提供了一个可视化的 Spec 浏览器。
+
+**步骤：**
+
+1. **打开 Spec 浏览器**
+   - 点击侧边栏中的"Specs"图标
+   - 或按 `Cmd+Shift+S`（macOS）/ `Ctrl+Shift+S`（Windows/Linux）
+
+2. **查看你的 Spec**
+   - 查看所有 Spec 的列表
+   - 点击查看需求、设计和任务
+   - 查看进度条和完成状态
+
+3. **实现任务**
+   - 点击任务旁边的"实现"按钮
+   - Kiro 的 AI 自动：
+     - 读取 Spec 上下文
+     - 生成代码
+     - 更新任务状态
+
+### 方法 2：使用 AI 聊天
+
+**步骤：**
+
+1. **打开 AI 聊天**
+   - 点击侧边栏中的"AI"图标
+   - 或按 `Cmd+K`（macOS）/ `Ctrl+K`（Windows/Linux）
+
+2. **告诉 AI：**
+   ```
+   请实现 01-00-user-login 的任务 1.1
+   ```
+
+3. **Kiro 的 AI 自动：**
+   - 读取 Spec（无需手动导出！）
+   - 理解需求和设计
+   - 生成代码
+   - 更新任务状态
+   - 在 Spec 浏览器中显示进度
+
+### 方法 3：使用命令面板
+
+**步骤：**
+
+1. **打开命令面板**
+   - 按 `Cmd+Shift+P`（macOS）/ `Ctrl+Shift+P`（Windows/Linux）
+
+2. **输入：**
+   ```
+   kse: Implement Task
+   ```
+
+3. **选择：**
+   - 选择 Spec（例如 01-00-user-login）
+   - 选择任务（例如 1.1）
+
+4. **Kiro 自动实现任务**
+
+---
+
+## Kiro 独有功能
+
+### 1. Spec 浏览器
+
+可视化浏览器显示：
+- 所有 Spec 的列表
+- 每个 Spec 的进度
+- 任务状态（未开始、进行中、已完成）
+- 快速操作按钮
+
+### 2. 任务跟踪器
+
+实时任务跟踪：
+- 查看所有任务及其状态
+- 按 Spec 或状态过滤
+- 一键实现任务
+- 自动进度更新
+
+### 3. 需求验证
+
+Kiro 验证你的 Spec：
+- 检查需求完整性
+- 验证设计追溯
+- 建议改进
+- 突出显示缺失的部分
+
+### 4. 设计可视化
+
+可视化你的设计：
+- 渲染 Mermaid 图
+- 显示组件关系
+- 突出显示依赖关系
+- 交互式架构视图
+
+### 5. 自动上下文管理
+
+Kiro 自动管理上下文：
+- 无需手动导出
+- 始终最新
+- 智能上下文选择
+- 优化的 AI 提示
+
+---
+
+## 工作流示例
+
+### 完整功能实现工作流
+
+```
+1. 在 Kiro 中创建 Spec
+   - 命令面板 → "kse: Create Spec"
+   - 输入名称：01-00-user-login
+
+2. 编写 Spec
+   - Kiro 打开 requirements.md
+   - 编写需求
+   - Kiro 打开 design.md
+   - 编写设计
+   - Kiro 打开 tasks.md
+   - 编写任务
+
+3. 在 Spec 浏览器中查看 Spec
+   - 查看进度：0/15 任务完成
+   - 查看需求和设计
+
+4. 实现任务
+   - 点击任务 1.1 旁边的"实现"
+   - Kiro 的 AI 生成代码
+   - 审查并接受
+   - 任务自动标记为完成
+
+5. 继续下一个任务
+   - 点击任务 1.2 旁边的"实现"
+   - 重复
+
+6. 跟踪进度
+   - Spec 浏览器显示：3/15 任务完成（20%）
+   - 任务跟踪器显示详细状态
+```
+
+---
+
+## 最佳实践
+
+### 1. 使用 Spec 浏览器
+
+Spec 浏览器是在 Kiro 中使用 kse 的最佳方式：
+- 可视化进度
+- 快速访问 Spec
+- 一键任务实现
+
+### 2. 让 Kiro 管理任务状态
+
+不要手动编辑 tasks.md 中的复选框。让 Kiro 的 AI 更新它们：
+- 更准确
+- 自动同步
+- 在 Spec 浏览器中反映
+
+### 3. 使用需求验证
+
+在实现前验证你的 Spec：
+- 命令面板 → "kse: Validate Spec"
+- 修复任何问题
+- 然后开始实现
+
+### 4. 利用设计可视化
+
+使用 Mermaid 图进行设计：
+- Kiro 渲染它们
+- 交互式视图
+- 更容易理解架构
+
+### 5. 使用 Kiro 的 AI 聊天
+
+Kiro 的 AI 始终知道你的 Spec：
+- 无需粘贴上下文
+- 只需询问："实现任务 1.1"
+- AI 自动读取 Spec
+
+---
+
+## 键盘快捷键
+
+### Spec 导航
+
+- `Cmd/Ctrl + Shift + S` - 打开 Spec 浏览器
+- `Cmd/Ctrl + Shift + T` - 打开任务跟踪器
+- `Cmd/Ctrl + Shift + R` - 打开需求视图
+- `Cmd/Ctrl + Shift + D` - 打开设计视图
+
+### Spec 操作
+
+- `Cmd/Ctrl + Shift + N` - 创建新 Spec
+- `Cmd/Ctrl + Shift + E` - 导出上下文（如果需要）
+- `Cmd/Ctrl + Shift + V` - 验证 Spec
+
+### AI 交互
+
+- `Cmd/Ctrl + K` - 打开 AI 聊天
+- `Cmd/Ctrl + I` - 实现当前任务
+- `Cmd/Ctrl + Shift + I` - 实现所有任务
+
+---
+
+## 与其他工具的比较
+
+### Kiro vs Cursor
+
+| 功能 | Kiro | Cursor |
+|------|------|--------|
+| kse 集成 | 原生 | 手动导出 |
+| Spec 浏览器 | ✅ | ❌ |
+| 任务跟踪器 | ✅ | ❌ |
+| 自动上下文 | ✅ | ❌ |
+| 设置时间 | 0 分钟 | 5 分钟 |
+
+### Kiro vs Windsurf
+
+| 功能 | Kiro | Windsurf |
+|------|------|----------|
+| kse 集成 | 原生 | 命令执行 |
+| Spec 浏览器 | ✅ | ❌ |
+| 可视化工具 | ✅ | ❌ |
+| Watch 模式 | 内置 | 需要设置 |
+
+### Kiro vs Claude
+
+| 功能 | Kiro | Claude |
+|------|------|--------|
+| kse 集成 | 原生 | 手动粘贴 |
+| IDE 功能 | ✅ | ❌ |
+| 自动上下文 | ✅ | ❌ |
+| 任务管理 | ✅ | ❌ |
+
+---
+
+## 故障排除
+
+### 问题：Spec 浏览器为空
+
+**解决方案：**
+1. 确保你已运行 `kse adopt`
+2. 检查 `.kiro/specs/` 目录是否存在
+3. 刷新 Spec 浏览器（右键 → 刷新）
+
+### 问题：AI 不读取我的 Spec
+
+**解决方案：**
+1. 这不应该发生在 Kiro 中！
+2. 如果发生，重启 Kiro
+3. 验证 Spec 文件格式正确
+
+### 问题：任务状态未更新
+
+**解决方案：**
+1. 让 Kiro 的 AI 更新任务，不要手动编辑
+2. 如果手动编辑，刷新 Spec 浏览器
+3. 检查 tasks.md 格式是否正确
+
+---
+
+## 相关文档
+
+- 📖 [快速入门指南](../quick-start.md) - 开始使用 kse
+- 🔌 [集成模式](../integration-modes.md) - 理解原生集成
+- 📋 [Spec 工作流](../spec-workflow.md) - 创建有效的 Spec
+- 🔧 [故障排除](../troubleshooting.md) - 常见问题
+
+---
+
+## 下一步
+
+- 探索 Spec 浏览器和任务跟踪器
+- 尝试需求验证功能
+- 使用设计可视化
+- 查看 [API 示例](../examples/add-rest-api/) 获取完整的 Spec 示例
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23