kiro-spec-engine 1.3.0 → 1.4.0

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

@@ -0,0 +1,377 @@
+# 在 Windsurf 中使用 kse
+
+> 将 kse 与 Windsurf IDE 集成进行 AI 辅助开发的完整指南
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23  
+**工具**: Windsurf IDE  
+**集成模式**: 原生 + Watch 模式  
+**预计设置时间**: 2 分钟
+
+---
+
+## 概述
+
+**Windsurf** 是一个 AI 驱动的 IDE，具有强大的命令执行能力。它可以直接运行 shell 命令，使其成为 kse 的理想选择。
+
+**kse 与 Windsurf 的集成**支持**原生模式**和**Watch 模式**，实现最无缝的体验。
+
+### 为什么在 Windsurf 中使用 kse？
+
+- ✅ **原生命令执行** - Windsurf 可以直接运行 kse 命令
+- ✅ **自动化工作流** - 无需手动导出/粘贴
+- ✅ **Watch 模式支持** - 自动上下文更新
+- ✅ **完全集成** - 最无缝的 kse 体验
+
+---
+
+## 集成模式
+
+**模式：** 原生 + Watch 模式
+
+**工作原理：**
+1. 你在 kse 中创建 Spec（需求、设计、任务）
+2. 你告诉 Windsurf："使用 kse 检查 spec 并实现任务 1.1"
+3. Windsurf 自动运行 `kse context export`
+4. Windsurf 读取导出的上下文
+5. Windsurf 生成代码
+6. Windsurf 可以更新 tasks.md 中的任务状态
+
+---
+
+## 设置
+
+### 前置条件
+
+- 已安装 **Windsurf IDE**（[下载](https://windsurf.ai/)）
+- 已全局安装 **kse**（`npm install -g kiro-spec-engine`）
+- 项目已被 kse **采用**（`kse adopt`）
+
+### 步骤 1：验证 kse 可访问
+
+在 Windsurf 终端中：
+```bash
+kse --version
+```
+
+应显示版本号（例如 1.3.0）。
+
+### 步骤 2：启用 Watch 模式（可选但推荐）
+
+Watch 模式在文件更改时自动更新上下文：
+
+```bash
+kse watch start
+```
+
+这会在后台启动文件监视器。
+
+---
+
+## 使用方法
+
+### 方法 1：直接命令（推荐）
+
+**最简单的方法** - 只需告诉 Windsurf 使用 kse！
+
+**步骤：**
+
+1. **在 Windsurf 中打开聊天**
+
+2. **告诉 Windsurf：**
+   ```
+   使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1
+   ```
+
+3. **Windsurf 将：**
+   - 运行 `kse context export 01-00-user-login`
+   - 读取导出的上下文
+   - 理解需求和设计
+   - 生成代码
+   - 创建或修改文件
+   - 可选：更新 tasks.md
+
+### 方法 2：分步命令
+
+**更多控制** - 明确告诉 Windsurf 每一步做什么。
+
+**步骤：**
+
+1. **导出上下文：**
+   ```
+   请运行：kse context export 01-00-user-login
+   ```
+
+2. **读取上下文：**
+   ```
+   请读取 .kiro/specs/01-00-user-login/context-export.md
+   ```
+
+3. **实现任务：**
+   ```
+   现在请实现任务 1.1："设置项目依赖"
+   严格遵循 design.md 中的架构。
+   ```
+
+4. **更新任务状态：**
+   ```
+   请在 .kiro/specs/01-00-user-login/tasks.md 中将任务 1.1 标记为完成
+   ```
+
+### 方法 3：Watch 模式 + 自动更新
+
+**最自动化** - 文件更改时自动更新上下文。
+
+**步骤：**
+
+1. **启动 Watch 模式：**
+   ```bash
+   kse watch start
+   ```
+
+2. **配置 Watch 模式以在更改时导出：**
+   ```bash
+   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}"
+   ```
+
+3. **现在，当你更新 Spec 文件时：**
+   - Watch 模式自动重新导出上下文
+   - Windsurf 始终拥有最新的上下文
+   - 无需手动重新导出！
+
+---
+
+## 工作流示例
+
+### 完整功能实现工作流
+
+```bash
+# 1. 创建 Spec
+kse create-spec 01-00-user-login
+
+# 2. 编写 requirements.md、design.md、tasks.md
+
+# 3. 在 Windsurf 中告诉 AI：
+"使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1"
+
+# 4. Windsurf 自动：
+# - 导出上下文
+# - 读取 Spec
+# - 生成代码
+# - 更新任务状态
+
+# 5. 审查更改
+
+# 6. 对下一个任务重复
+"现在请实现任务 1.2"
+```
+
+### 使用 Watch 模式的迭代开发
+
+```bash
+# 1. 启动 Watch 模式
+kse watch start
+
+# 2. 在 Windsurf 中实现任务
+"使用 kse 实现 01-00-user-login 的任务 1.1"
+
+# 3. 如果需要，更新 design.md
+# Watch 模式自动重新导出上下文
+
+# 4. 继续下一个任务
+"现在请实现任务 1.2"
+# Windsurf 使用更新的上下文
+```
+
+---
+
+## 最佳实践
+
+### 1. 使用自然语言
+
+Windsurf 理解自然语言。只需说：
+```
+"使用 kse 检查 user-login spec 并实现下一个任务"
+```
+
+### 2. 让 Windsurf 管理任务
+
+Windsurf 可以更新任务状态：
+```
+"实现任务 1.1 并在 tasks.md 中标记为完成"
+```
+
+### 3. 使用 Watch 模式进行活跃开发
+
+在活跃开发期间启动 Watch 模式：
+```bash
+kse watch start
+```
+
+完成后停止：
+```bash
+kse watch stop
+```
+
+### 4. 批量实现任务
+
+Windsurf 可以实现多个任务：
+```
+"使用 kse 实现 01-00-user-login 的任务 1.1、1.2 和 1.3"
+```
+
+### 5. 要求验证
+
+让 Windsurf 验证实现：
+```
+"实现任务 1.1 并运行测试以验证它是否有效"
+```
+
+---
+
+## 示例提示
+
+### 实现新功能
+
+```
+使用 kse 检查 .kiro/specs/01-00-user-login/ 中的 spec 并实现任务 1.1："设置项目依赖"。
+
+严格遵循 design.md 中的架构。
+完成后在 tasks.md 中标记任务为完成。
+```
+
+### 实现多个任务
+
+```
+使用 kse 检查 01-00-user-login spec 并实现阶段 1 的所有任务（1.1 和 1.2）。
+
+对于每个任务：
+1. 实现代码
+2. 编写测试
+3. 在 tasks.md 中标记为完成
+```
+
+### 调试问题
+
+```
+我正在实现 01-00-user-login spec。
+
+任务 2.1 已完成，但测试失败。请：
+1. 使用 kse 检查 spec
+2. 审查我的代码
+3. 识别问题
+4. 修复它
+5. 运行测试以验证
+```
+
+---
+
+## Watch 模式配置
+
+### 基本 Watch 配置
+
+在 Spec 更改时自动导出上下文：
+
+```bash
+# 监视 requirements.md 更改
+kse watch add --pattern ".kiro/specs/*/requirements.md" --action "kse context export {spec}"
+
+# 监视 design.md 更改
+kse watch add --pattern ".kiro/specs/*/design.md" --action "kse context export {spec}"
+
+# 监视 tasks.md 更改
+kse watch add --pattern ".kiro/specs/*/tasks.md" --action "kse context export {spec}"
+```
+
+### 高级 Watch 配置
+
+在 Spec 更改时运行测试：
+
+```bash
+# 在任务更新时运行测试
+kse watch add --pattern ".kiro/specs/*/tasks.md" --action "npm test"
+
+# 在设计更改时运行 linter
+kse watch add --pattern ".kiro/specs/*/design.md" --action "npm run lint"
+```
+
+### 检查 Watch 状态
+
+```bash
+# 查看 Watch 模式是否正在运行
+kse watch status
+
+# 列出所有 watch 规则
+kse watch list
+
+# 停止 Watch 模式
+kse watch stop
+```
+
+---
+
+## 故障排除
+
+### 问题：Windsurf 找不到 kse 命令
+
+**解决方案：**
+1. 验证 kse 已全局安装：
+   ```bash
+   npm list -g kiro-spec-engine
+   ```
+2. 重启 Windsurf
+3. 检查 PATH 是否包含 npm 全局 bin
+
+### 问题：Watch 模式未触发
+
+**解决方案：**
+1. 检查 Watch 模式是否正在运行：
+   ```bash
+   kse watch status
+   ```
+2. 验证文件模式是否正确：
+   ```bash
+   kse watch list
+   ```
+3. 重启 Watch 模式：
+   ```bash
+   kse watch stop
+   kse watch start
+   ```
+
+### 问题：Windsurf 不遵循设计
+
+**解决方案：**
+1. 使你的 design.md 更详细
+2. 在提示中明确："严格遵循 design.md"
+3. 要求 Windsurf 先读取设计：
+   ```
+   首先读取 .kiro/specs/01-00-user-login/design.md
+   然后实现任务 1.1
+   ```
+
+---
+
+## 相关文档
+
+- 📖 [快速入门指南](../quick-start.md) - 开始使用 kse
+- 🔌 [集成模式](../integration-modes.md) - 理解原生和 Watch 模式
+- 📋 [Spec 工作流](../spec-workflow.md) - 创建有效的 Spec
+- 🔧 [故障排除](../troubleshooting.md) - 常见问题
+
+---
+
+## 下一步
+
+- 尝试使用 Windsurf 的原生命令实现你的第一个任务
+- 设置 Watch 模式进行自动上下文更新
+- 探索批量任务实现
+- 查看 [API 示例](../examples/add-rest-api/) 获取完整的 Spec 示例
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-01-23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
   "main": "index.js",
   "bin": {