# 在任何 AI 工具中使用 kse

> 将 kse 与任何 AI 编码助手集成的通用指南

---

**版本**: 1.42.0  
**最后更新**: 2026-02-11  
**工具**: 任何 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 spec bootstrap --name 01-00-my-feature --non-interactive
```

**使用：**
```
告诉 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 spec bootstrap --name 01-00-my-feature --non-interactive
```

**使用：**
```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 spec bootstrap --name 01-00-my-feature --non-interactive
```

### 步骤 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 spec bootstrap --name 01-00-user-login --non-interactive
# 编辑 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 spec bootstrap --name 01-00-user-login --non-interactive

# 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 spec bootstrap --name 01-00-user-login --non-interactive

# 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 spec bootstrap --name 01-00-user-login --non-interactive

# 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.42.0  
**最后更新**: 2026-02-11