kiro-spec-engine 1.3.0 → 1.4.1

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

@@ -0,0 +1,448 @@
+# 在 VS Code + Copilot 中使用 kse
+
+> 将 kse 与 VS Code 和 GitHub Copilot 集成进行 AI 辅助开发的完整指南
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23  
+**工具**: VS Code + GitHub Copilot  
+**集成模式**: 手动导出 + 内联注释  
+**预计设置时间**: 5 分钟
+
+---
+
+## 概述
+
+**VS Code** 是最流行的代码编辑器，**GitHub Copilot** 提供 AI 驱动的代码补全。
+
+**kse 与 VS Code + Copilot 的集成**使用**手动导出**和**内联注释**，让 Copilot 理解你的 Spec 并生成匹配你设计的代码。
+
+### 为什么在 VS Code + Copilot 中使用 kse？
+
+- ✅ **熟悉的环境** - 使用你已知的编辑器
+- ✅ **智能补全** - Copilot 遵循你的 Spec
+- ✅ **内联建议** - 在你输入时获得上下文感知的代码
+- ✅ **灵活集成** - 多种使用 kse 的方式
+
+---
+
+## 集成模式
+
+**模式：** 手动导出 + 内联注释
+
+**工作原理：**
+1. 你在 kse 中创建 Spec（需求、设计、任务）
+2. 你在代码中添加引用 Spec 的注释
+3. Copilot 读取注释和 Spec 文件
+4. Copilot 生成匹配你设计的代码
+5. 你在 tasks.md 中更新任务状态
+
+---
+
+## 设置
+
+### 前置条件
+
+- 已安装 **VS Code**（[下载](https://code.visualstudio.com/)）
+- 已安装 **GitHub Copilot** 扩展
+- 已全局安装 **kse**（`npm install -g kiro-spec-engine`）
+- 项目已被 kse **采用**（`kse adopt`）
+
+### 步骤 1：安装推荐的扩展
+
+在 VS Code 中安装这些扩展：
+
+1. **GitHub Copilot** - AI 代码补全
+2. **GitHub Copilot Chat** - 与 Copilot 聊天
+3. **Markdown All in One** - 更好的 Spec 编辑
+4. **Mermaid Preview** - 可视化设计图
+
+### 步骤 2：配置 VS Code 设置
+
+创建 `.vscode/settings.json`：
+
+```json
+{
+  "files.associations": {
+    "*.md": "markdown"
+  },
+  "markdown.preview.breaks": true,
+  "github.copilot.enable": {
+    "*": true,
+    "markdown": true
+  },
+  "github.copilot.advanced": {
+    "inlineSuggestCount": 3
+  }
+}
+```
+
+### 步骤 3：创建 Workspace 片段（可选但推荐）
+
+创建 `.vscode/kse.code-snippets`：
+
+```json
+{
+  "kse Spec Reference": {
+    "prefix": "kse-ref",
+    "body": [
+      "// Task ${1:1.1}: ${2:Task description}",
+      "// Spec: .kiro/specs/${3:spec-name}/",
+      "// Design: See ${4:ComponentName} in design.md",
+      "// Requirements: ${5:FR-1, FR-2}",
+      "//"
+    ],
+    "description": "Add kse Spec reference comment"
+  },
+  "kse Task Header": {
+    "prefix": "kse-task",
+    "body": [
+      "/**",
+      " * Task ${1:1.1}: ${2:Task description}",
+      " * ",
+      " * Spec: .kiro/specs/${3:spec-name}/",
+      " * Requirements: ${4:FR-1}",
+      " * Design: ${5:ComponentName} in design.md",
+      " * ",
+      " * Implementation notes:",
+      " * - ${6:Note 1}",
+      " */"
+    ],
+    "description": "Add kse task header comment"
+  }
+}
+```
+
+---
+
+## 使用方法
+
+### 方法 1：内联 Spec 引用（推荐）
+
+**最佳用于：** 实现新功能和组件
+
+**步骤：**
+
+1. **创建新文件**（例如 `src/auth/AuthController.js`）
+
+2. **添加 Spec 引用注释：**
+   ```javascript
+   /**
+    * Task 1.1: 设置项目依赖
+    * 
+    * Spec: .kiro/specs/01-00-user-login/
+    * Requirements: FR-1, FR-2, NFR-1
+    * Design: AuthController in design.md
+    * 
+    * 实现说明：
+    * - 使用 Express 进行路由
+    * - 使用 bcrypt 进行密码哈希
+    * - 使用 JWT 进行令牌
+    * - 实现速率限制
+    */
+   ```
+
+3. **开始输入** - Copilot 将：
+   - 读取你的注释
+   - 读取引用的 Spec 文件
+   - 建议匹配你设计的代码
+
+4. **按 Tab** 接受建议
+
+### 方法 2：使用 Copilot Chat
+
+**最佳用于：** 复杂实现和讨论
+
+**步骤：**
+
+1. **打开 Copilot Chat**
+   - 按 `Cmd+Shift+I`（macOS）或 `Ctrl+Shift+I`（Windows/Linux）
+   - 或点击侧边栏中的 Copilot 图标
+
+2. **引用你的 Spec：**
+   ```
+   我正在实现 .kiro/specs/01-00-user-login/ 中的用户登录功能。
+   
+   请阅读：
+   - requirements.md
+   - design.md
+   - tasks.md
+   
+   然后帮我实现任务 1.1："设置项目依赖"
+   ```
+
+3. **Copilot 将：**
+   - 读取你的 Spec 文件
+   - 提供代码建议
+   - 解释实现决策
+
+4. **插入代码** 到你的文件中
+
+### 方法 3：使用 Workspace 片段
+
+**最佳用于：** 快速添加 Spec 引用
+
+**步骤：**
+
+1. **在文件中输入：**
+   ```
+   kse-ref
+   ```
+
+2. **按 Tab** - 片段展开为：
+   ```javascript
+   // Task 1.1: Task description
+   // Spec: .kiro/specs/spec-name/
+   // Design: See ComponentName in design.md
+   // Requirements: FR-1, FR-2
+   //
+   ```
+
+3. **填写详细信息** 并开始编码
+
+4. **Copilot 使用此上下文** 进行建议
+
+---
+
+## 工作流示例
+
+### 完整功能实现工作流
+
+```bash
+# 1. 创建 Spec
+kse create-spec 01-00-user-login
+
+# 2. 在 VS Code 中编写 Spec
+# - 打开 requirements.md
+# - 打开 design.md
+# - 打开 tasks.md
+
+# 3. 创建实现文件
+# src/auth/AuthController.js
+
+# 4. 添加 Spec 引用（使用 kse-ref 片段）
+kse-ref [Tab]
+
+# 5. 开始编码 - Copilot 建议代码
+
+# 6. 接受建议（Tab）
+
+# 7. 在 tasks.md 中标记任务为完成
+- [x] 1.1 设置项目依赖
+
+# 8. 对下一个任务重复
+```
+
+---
+
+## 最佳实践
+
+### 1. 始终添加 Spec 引用
+
+在每个文件顶部添加 Spec 引用：
+```javascript
+// Spec: .kiro/specs/01-00-user-login/
+// Task: 1.1 - 设置项目依赖
+```
+
+### 2. 使用描述性注释
+
+Copilot 读取注释。要具体：
+```javascript
+// 实现 AuthController.login() 方法
+// 要求：
+// - 验证邮箱和密码
+// - 检查速率限制
+// - 返回 JWT 令牌
+```
+
+### 3. 在注释中引用设计
+
+```javascript
+// 参见 design.md 中的 AuthController 设计
+// 使用 design.md 中指定的确切方法名称
+```
+
+### 4. 分解复杂任务
+
+对于复杂任务，添加分步注释：
+```javascript
+// 步骤 1：验证输入
+// 步骤 2：检查速率限制
+// 步骤 3：验证凭据
+// 步骤 4：生成令牌
+// 步骤 5：返回响应
+```
+
+### 5. 使用 Copilot Chat 进行复杂逻辑
+
+对于复杂实现，使用 Copilot Chat：
+- 讨论方法
+- 获取代码示例
+- 要求解释
+
+---
+
+## 示例代码模式
+
+### 模式 1：组件实现
+
+```javascript
+/**
+ * AuthController - 处理认证请求
+ * 
+ * Spec: .kiro/specs/01-00-user-login/
+ * Task: 3.1 - 实现 AuthController
+ * Design: 参见 design.md 中的 AuthController
+ * Requirements: FR-1, FR-2, NFR-1
+ * 
+ * 此控制器实现：
+ * - POST /api/auth/login - 用户登录
+ * - 输入验证
+ * - 速率限制
+ * - JWT 令牌生成
+ */
+
+class AuthController {
+  // Copilot 将基于上述上下文建议实现
+}
+```
+
+### 模式 2：方法实现
+
+```javascript
+/**
+ * 验证用户凭据
+ * 
+ * Task: 2.2 - 实现 AuthService.authenticate()
+ * Design: 参见 design.md 中的 AuthService
+ * 
+ * @param {string} email - 用户邮箱
+ * @param {string} password - 用户密码
+ * @returns {Promise<User|null>} 如果有效则返回用户，否则返回 null
+ * 
+ * 实现：
+ * 1. 通过邮箱查找用户
+ * 2. 使用 bcrypt 比较密码
+ * 3. 如果匹配则返回用户
+ */
+async authenticate(email, password) {
+  // Copilot 将建议实现
+}
+```
+
+### 模式 3：测试实现
+
+```javascript
+/**
+ * AuthService 测试
+ * 
+ * Spec: .kiro/specs/01-00-user-login/
+ * Task: 4.1 - 编写全面的测试
+ * 
+ * 测试场景：
+ * - 有效凭据 → 返回用户
+ * - 无效凭据 → 返回 null
+ * - 缺少邮箱 → 抛出错误
+ * - 无效邮箱格式 → 抛出错误
+ */
+
+describe('AuthService', () => {
+  // Copilot 将建议测试用例
+});
+```
+
+---
+
+## 故障排除
+
+### 问题：Copilot 不遵循我的 Spec
+
+**解决方案：**
+1. 使你的注释更详细
+2. 在注释中引用特定的设计部分
+3. 在 design.md 中添加代码示例
+4. 使用 Copilot Chat 进行复杂实现
+
+### 问题：Copilot 建议不相关的代码
+
+**解决方案：**
+1. 添加更多上下文到注释
+2. 引用 Spec 文件：`// Spec: .kiro/specs/...`
+3. 要具体："实现 design.md 中的确切 AuthController"
+
+### 问题：Copilot 看不到我的 Spec 文件
+
+**解决方案：**
+1. 确保 Spec 文件在工作区中
+2. 在 VS Code 中打开 Spec 文件
+3. 在注释中使用相对路径
+4. 检查 `.gitignore` 是否排除了 `.kiro/`
+
+---
+
+## 高级技巧
+
+### 1. 使用多文件上下文
+
+在多个文件中打开 Spec：
+- requirements.md
+- design.md
+- 你的实现文件
+
+Copilot 使用所有打开文件的上下文。
+
+### 2. 使用 Copilot Labs
+
+如果你有 Copilot Labs：
+- 使用"解释"功能理解 Spec
+- 使用"翻译"功能转换设计为代码
+- 使用"测试"功能生成测试
+
+### 3. 创建模板文件
+
+为常见模式创建模板：
+```javascript
+// templates/controller-template.js
+/**
+ * [ComponentName] - [Description]
+ * 
+ * Spec: .kiro/specs/[spec-name]/
+ * Task: [task-id] - [task-description]
+ * Design: See [ComponentName] in design.md
+ * Requirements: [requirements]
+ */
+```
+
+### 4. 使用任务注释
+
+在 tasks.md 中添加实现注释：
+```markdown
+- [ ] 1.1 设置项目依赖
+  <!-- 实现：src/package.json -->
+  <!-- 参考：design.md 中的技术栈部分 -->
+```
+
+---
+
+## 相关文档
+
+- 📖 [快速入门指南](../quick-start.md) - 开始使用 kse
+- 🔌 [集成模式](../integration-modes.md) - 理解手动导出模式
+- 📋 [Spec 工作流](../spec-workflow.md) - 创建有效的 Spec
+- 🔧 [故障排除](../troubleshooting.md) - 常见问题
+
+---
+
+## 下一步
+
+- 设置 VS Code 片段以快速引用 Spec
+- 尝试使用 Copilot Chat 进行复杂实现
+- 探索 [Cursor 指南](cursor-guide.md) 获取更集成的体验
+- 查看 [API 示例](../examples/add-rest-api/) 获取完整的 Spec 示例
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23