kiro-spec-engine 1.3.0 → 1.4.1

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

@@ -0,0 +1,498 @@
+# 在任何 AI 工具中使用 kse
+
+> 将 kse 与任何 AI 编码助手集成的通用指南
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23  
+**工具**: 任何 AI 编码助手  
+**集成模式**: 所有模式  
+**预计设置时间**: 5-10 分钟
+
+---
+
+## 概述
+
+**kse 适用于任何 AI 编码工具。** 本指南展示了如何将 kse 与任何 AI 助手集成，无论是 IDE、聊天机器人还是命令行工具。
+
+### 为什么在任何 AI 工具中使用 kse？
+
+- ✅ **工具无关** - 适用于任何 AI 助手
+- ✅ **灵活集成** - 选择最适合你的模式
+- ✅ **一致的工作流** - 跨工具的相同 Spec 结构
+- ✅ **未来证明** - 在工具之间轻松切换
+
+---
+
+## 三种集成模式
+
+kse 支持三种集成模式。选择最适合你的 AI 工具的一种：
+
+### 模式 1：原生集成
+
+**最佳用于：** 可以执行 shell 命令的 AI 工具
+
+**工具示例：** Windsurf、Cline、Kiro、Aider
+
+**工作原理：**
+1. AI 工具直接运行 kse 命令
+2. AI 读取导出的上下文
+3. AI 生成代码
+4. AI 可以更新任务状态
+
+**设置：**
+```bash
+# 确保 kse 已安装并在 PATH 中
+kse --version
+
+# 采用项目
+kse adopt
+
+# 创建 Spec
+kse create-spec 01-00-my-feature
+```
+
+**使用：**
+```
+告诉 AI："使用 kse 检查 01-00-my-feature 的 spec 并实现任务 1.1"
+```
+
+### 模式 2：手动导出
+
+**最佳用于：** 基于聊天的 AI 工具
+
+**工具示例：** Claude、ChatGPT、Cursor、Copilot
+
+**工作原理：**
+1. 你使用 kse 导出上下文
+2. 你将上下文复制到 AI 工具
+3. AI 生成代码
+4. 你手动更新任务状态
+
+**设置：**
+```bash
+# 安装 kse
+npm install -g kiro-spec-engine
+
+# 采用项目
+kse adopt
+
+# 创建 Spec
+kse create-spec 01-00-my-feature
+```
+
+**使用：**
+```bash
+# 导出上下文
+kse context export 01-00-my-feature
+
+# 复制到剪贴板
+cat .kiro/specs/01-00-my-feature/context-export.md | pbcopy
+
+# 粘贴到 AI 工具并请求实现
+```
+
+### 模式 3：Watch 模式
+
+**最佳用于：** 活跃开发期间的自动更新
+
+**工具示例：** 所有工具（作为补充）
+
+**工作原理：**
+1. Watch 模式监视 Spec 文件的更改
+2. 文件更改时自动重新导出上下文
+3. AI 工具始终拥有最新的上下文
+
+**设置：**
+```bash
+# 启动 Watch 模式
+kse watch start
+
+# 配置自动导出
+kse watch add --pattern ".kiro/specs/*/requirements.md" --action "kse context export {spec}"
+kse watch add --pattern ".kiro/specs/*/design.md" --action "kse context export {spec}"
+```
+
+**使用：**
+```
+编辑 Spec 文件 → Watch 模式自动重新导出 → AI 使用更新的上下文
+```
+
+---
+
+## 通用工作流
+
+无论你使用哪个 AI 工具，工作流都是相同的：
+
+### 步骤 1：创建 Spec
+
+```bash
+kse create-spec 01-00-my-feature
+```
+
+### 步骤 2：编写 Spec
+
+编辑三个文件：
+- `requirements.md` - 你要构建什么
+- `design.md` - 你将如何构建
+- `tasks.md` - 分步计划
+
+### 步骤 3：为 AI 准备上下文
+
+**选项 A：原生模式**
+```
+告诉 AI："使用 kse 检查 spec 并实现任务 1.1"
+```
+
+**选项 B：手动导出**
+```bash
+kse context export 01-00-my-feature
+# 将 context-export.md 复制到 AI 工具
+```
+
+**选项 C：任务特定提示**
+```bash
+kse prompt generate 01-00-my-feature 1.1
+# 将生成的提示复制到 AI 工具
+```
+
+### 步骤 4：AI 生成代码
+
+AI 工具：
+- 读取你的 Spec
+- 理解需求和设计
+- 生成匹配你架构的代码
+
+### 步骤 5：更新任务状态
+
+**选项 A：让 AI 更新**（如果支持）
+```
+"请在 tasks.md 中将任务 1.1 标记为完成"
+```
+
+**选项 B：手动更新**
+```markdown
+- [x] 1.1 设置项目依赖  ← 从 [ ] 改为 [x]
+```
+
+### 步骤 6：重复
+
+对每个任务重复步骤 3-5。
+
+---
+
+## 工具特定提示
+
+### 对于聊天机器人（Claude、ChatGPT）
+
+**提示模板：**
+```
+我已提供 [功能名称] 的完整 Spec。
+
+Spec 包括：
+- requirements.md - 需求和验收标准
+- design.md - 架构和组件设计
+- tasks.md - 实现任务
+
+请实现任务 [task-id]："[task-description]"
+
+要求：
+1. 严格遵循 design.md 中的架构
+2. 使用 design.md 中指定的确切组件名称
+3. 满足 requirements.md 中的所有验收标准
+4. 包含错误处理和验证
+5. 添加适当的注释
+
+请提供：
+- 完整的代码实现
+- 使用说明
+- 任何必要的配置
+```
+
+### 对于 IDE（Cursor、VS Code）
+
+**在代码中添加注释：**
+```javascript
+/**
+ * Task 1.1: 设置项目依赖
+ * 
+ * Spec: .kiro/specs/01-00-my-feature/
+ * Requirements: FR-1, FR-2, NFR-1
+ * Design: 参见 design.md 中的 ComponentName
+ * 
+ * 实现说明：
+ * - [具体说明]
+ */
+```
+
+### 对于命令行工具（Aider、Cline）
+
+**命令模板：**
+```bash
+# 使用 Aider
+aider --message "使用 .kiro/specs/01-00-my-feature/ 中的 spec 实现任务 1.1"
+
+# 使用 Cline
+cline "检查 .kiro/specs/01-00-my-feature/ 并实现任务 1.1"
+```
+
+---
+
+## 最佳实践
+
+### 1. 使你的 Spec 详细
+
+AI 工具需要清晰的指令：
+- ✅ 详细的需求
+- ✅ 具体的设计决策
+- ✅ 明确的任务描述
+- ✅ 代码示例（如果可能）
+
+### 2. 使用任务特定提示
+
+对于大型 Spec，使用任务特定提示：
+```bash
+kse prompt generate 01-00-my-feature 1.1
+```
+
+这会创建一个更小、更集中的上下文。
+
+### 3. 在提示中明确
+
+告诉 AI 确切地做什么：
+- ✅ "严格遵循 design.md"
+- ✅ "使用 design.md 中的确切组件名称"
+- ✅ "实现 requirements.md 中的所有验收标准"
+
+### 4. 迭代改进
+
+不要犹豫要求更改：
+```
+"代码看起来不错，但请：
+1. 添加更多错误处理
+2. 添加 JSDoc 注释
+3. 使用 async/await 而不是 promises"
+```
+
+### 5. 跟踪进度
+
+始终更新 tasks.md：
+```markdown
+- [x] 1.1 设置项目依赖
+- [-] 1.2 创建 User 模型  ← 进行中
+- [ ] 1.3 实现 AuthService
+```
+
+---
+
+## 示例集成
+
+### 示例 1：使用 Claude
+
+```bash
+# 1. 创建并编写 Spec
+kse create-spec 01-00-user-login
+# 编辑 requirements.md、design.md、tasks.md
+
+# 2. 导出上下文
+kse context export 01-00-user-login
+
+# 3. 复制到剪贴板
+cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
+
+# 4. 在 Claude 中：
+# - 粘贴上下文
+# - 说："请实现任务 1.1"
+
+# 5. 从 Claude 复制代码到项目
+
+# 6. 更新 tasks.md
+- [x] 1.1 设置项目依赖
+```
+
+### 示例 2：使用 Cursor
+
+```bash
+# 1. 创建并编写 Spec
+kse create-spec 01-00-user-login
+
+# 2. 生成任务特定提示
+kse prompt generate 01-00-user-login 1.1
+
+# 3. 在 Cursor Composer 中（Cmd+K）：
+# - 粘贴生成的提示
+
+# 4. Cursor 生成代码
+
+# 5. 审查并接受
+
+# 6. 更新 tasks.md
+```
+
+### 示例 3：使用 Windsurf
+
+```bash
+# 1. 创建并编写 Spec
+kse create-spec 01-00-user-login
+
+# 2. 在 Windsurf 中告诉 AI：
+"使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1"
+
+# 3. Windsurf 自动：
+# - 运行 kse context export
+# - 读取 Spec
+# - 生成代码
+# - 更新 tasks.md
+
+# 4. 审查更改
+```
+
+### 示例 4：使用 VS Code + Copilot
+
+```bash
+# 1. 创建并编写 Spec
+kse create-spec 01-00-user-login
+
+# 2. 创建实现文件
+# src/auth/AuthController.js
+
+# 3. 添加 Spec 引用注释
+/**
+ * Task 1.1: 设置项目依赖
+ * Spec: .kiro/specs/01-00-user-login/
+ * Design: 参见 design.md 中的 AuthController
+ */
+
+# 4. 开始输入 - Copilot 建议代码
+
+# 5. 按 Tab 接受
+
+# 6. 更新 tasks.md
+```
+
+---
+
+## 故障排除
+
+### 问题：AI 不遵循我的设计
+
+**解决方案：**
+1. 使你的 design.md 更详细
+2. 在 design.md 中添加代码示例
+3. 在提示中明确："严格遵循 design.md"
+4. 将设计分解为更小的部分
+
+### 问题：上下文太大
+
+**解决方案：**
+1. 使用任务特定提示：
+   ```bash
+   kse prompt generate 01-00-my-feature 1.1
+   ```
+2. 将大型 Spec 分解为更小的 Spec
+3. 仅包含相关部分
+
+### 问题：AI 忘记了上下文
+
+**解决方案：**
+1. 在同一对话中保持相关任务
+2. 对于新任务，重新提供上下文
+3. 引用之前的响应："如你在任务 1.1 中实现的..."
+
+### 问题：不确定使用哪种模式
+
+**解决方案：**
+- **你的 AI 可以运行命令吗？** → 使用原生模式
+- **你的 AI 是聊天机器人吗？** → 使用手动导出
+- **你经常更新 Spec 吗？** → 添加 Watch 模式
+
+---
+
+## 高级技巧
+
+### 1. 组合模式
+
+同时使用多种模式：
+- 手动导出用于初始实现
+- Watch 模式用于活跃开发
+- 原生模式用于自动化任务
+
+### 2. 创建自定义脚本
+
+为你的工作流创建脚本：
+```bash
+#!/bin/bash
+# quick-implement.sh
+
+SPEC=$1
+TASK=$2
+
+# 导出上下文
+kse context export $SPEC
+
+# 生成提示
+kse prompt generate $SPEC $TASK
+
+# 复制到剪贴板
+cat .kiro/specs/$SPEC/context-export.md | pbcopy
+
+echo "✅ 上下文已复制到剪贴板"
+echo "现在粘贴到你的 AI 工具并请求实现"
+```
+
+### 3. 使用 Steering 规则
+
+为 AI 行为添加项目特定规则：
+```bash
+# 编辑 .kiro/steering/CORE_PRINCIPLES.md
+# 添加你的编码标准、约定等
+
+# 使用 steering 导出
+kse context export 01-00-my-feature --steering
+```
+
+### 4. 模板化你的 Spec
+
+为常见模式创建 Spec 模板：
+```bash
+# 创建模板目录
+mkdir .kiro/templates
+
+# 创建模板 Spec
+cp -r .kiro/specs/01-00-user-login .kiro/templates/api-feature-template
+
+# 对于新功能，从模板复制
+cp -r .kiro/templates/api-feature-template .kiro/specs/02-00-new-feature
+```
+
+---
+
+## 相关文档
+
+- 📖 [快速入门指南](../quick-start.md) - 开始使用 kse
+- 🔌 [集成模式](../integration-modes.md) - 深入了解三种模式
+- 📋 [Spec 工作流](../spec-workflow.md) - 创建有效的 Spec
+- 🔧 [故障排除](../troubleshooting.md) - 常见问题
+
+### 工具特定指南
+
+- [Cursor 指南](cursor-guide.md) - Cursor IDE 集成
+- [Claude 指南](claude-guide.md) - Claude Code 集成
+- [Windsurf 指南](windsurf-guide.md) - Windsurf IDE 集成
+- [Kiro 指南](kiro-guide.md) - Kiro IDE 原生集成
+- [VS Code 指南](vscode-guide.md) - VS Code + Copilot 集成
+
+---
+
+## 下一步
+
+- 选择最适合你的 AI 工具的集成模式
+- 尝试使用你的 AI 工具实现你的第一个任务
+- 探索 Watch 模式进行自动化
+- 查看 [API 示例](../examples/add-rest-api/) 获取完整的 Spec 示例
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23