kiro-spec-engine 1.2.3 → 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/lib/adoption/detection-engine.js

@@ -11,6 +11,7 @@ const {
   listFiles,
   readJSON
 } = require('../utils/fs-utils');
+const SteeringManager = require('../steering/steering-manager');
 
 class DetectionEngine {
   constructor() {
@@ -19,6 +20,7 @@ class DetectionEngine {
     this.specsDir = 'specs';
     this.steeringDir = 'steering';
     this.toolsDir = 'tools';
+    this.steeringManager = new SteeringManager();
   }
 
   /**
@@ -37,6 +39,7 @@ class DetectionEngine {
       let hasSteering = false;
       let hasTools = false;
       let existingVersion = null;
+      let steeringDetection = null;
       
       if (hasKiroDir) {
         // Check for version.json
@@ -57,9 +60,9 @@ class DetectionEngine {
         const specsPath = path.join(kiroPath, this.specsDir);
         hasSpecs = await pathExists(specsPath);
         
-        // Check for steering/
-        const steeringPath = path.join(kiroPath, this.steeringDir);
-        hasSteering = await pathExists(steeringPath);
+        // Check for steering/ using SteeringManager
+        steeringDetection = await this.steeringManager.detectSteering(projectPath);
+        hasSteering = steeringDetection.hasExistingSteering;
         
         // Check for tools/
         const toolsPath = path.join(kiroPath, this.toolsDir);
@@ -80,7 +83,8 @@ class DetectionEngine {
         hasTools,
         projectType,
         existingVersion,
-        conflicts
+        conflicts,
+        steeringDetection // Add steering detection details
       };
     } catch (error) {
       throw new Error(`Failed to analyze project: ${error.message}`);
@@ -225,6 +229,12 @@ class DetectionEngine {
       }
       lines.push(`  specs/: ${result.hasSpecs ? 'Yes' : 'No'}`);
       lines.push(`  steering/: ${result.hasSteering ? 'Yes' : 'No'}`);
+      
+      // Show steering details if available
+      if (result.steeringDetection && result.steeringDetection.hasExistingSteering) {
+        lines.push(`    Files: ${result.steeringDetection.count} file(s)`);
+      }
+      
       lines.push(`  tools/: ${result.hasTools ? 'Yes' : 'No'}`);
       
       if (result.conflicts.length > 0) {

package/lib/commands/adopt.js

@@ -12,6 +12,9 @@ const DetectionEngine = require('../adoption/detection-engine');
 const { getAdoptionStrategy } = require('../adoption/adoption-strategy');
 const BackupSystem = require('../backup/backup-system');
 const VersionManager = require('../version/version-manager');
+const SteeringManager = require('../steering/steering-manager');
+const AdoptionConfig = require('../steering/adoption-config');
+const { detectTool, generateAutoConfig } = require('../utils/tool-detector');
 
 /**
  * Executes the adopt command
@@ -134,7 +137,54 @@ async function adoptCommand(options = {}) {
     
     console.log();
     
-    // 7. Create backup if needed
+    // 7. Handle steering strategy if conflicts detected
+    let steeringStrategy = null;
+    let steeringBackupId = null;
+    
+    if (detection.steeringDetection && detection.steeringDetection.hasExistingSteering) {
+      console.log(chalk.blue('🎯 Handling steering files...'));
+      const steeringManager = new SteeringManager();
+      
+      // Prompt for strategy
+      steeringStrategy = await steeringManager.promptStrategy(detection.steeringDetection);
+      
+      if (steeringStrategy === 'use-kse') {
+        // Backup existing steering files
+        console.log(chalk.blue('📦 Backing up existing steering files...'));
+        const backupResult = await steeringManager.backupSteering(projectPath);
+        
+        if (backupResult.success) {
+          steeringBackupId = backupResult.backupId;
+          console.log(chalk.green(`✅ Steering backup created: ${steeringBackupId}`));
+          
+          // Install kse steering files
+          console.log(chalk.blue('📝 Installing kse steering files...'));
+          const installResult = await steeringManager.installKseSteering(projectPath);
+          
+          if (installResult.success) {
+            console.log(chalk.green(`✅ Installed ${installResult.filesInstalled} kse steering file(s)`));
+          } else {
+            console.log(chalk.red(`❌ Failed to install kse steering: ${installResult.error}`));
+            console.log(chalk.yellow('Aborting adoption'));
+            return;
+          }
+        } else {
+          console.log(chalk.red(`❌ Failed to backup steering: ${backupResult.error}`));
+          console.log(chalk.yellow('Aborting adoption for safety'));
+          return;
+        }
+      } else if (steeringStrategy === 'use-project') {
+        console.log(chalk.blue('✅ Keeping existing steering files'));
+      }
+      
+      // Save steering strategy to adoption config
+      const adoptionConfig = new AdoptionConfig(projectPath);
+      await adoptionConfig.updateSteeringStrategy(steeringStrategy, steeringBackupId);
+      
+      console.log();
+    }
+    
+    // 8. Create backup if needed
     let backupId = null;
     if (detection.hasKiroDir && (strategy === 'partial' || strategy === 'full')) {
       console.log(chalk.blue('📦 Creating backup...'));
@@ -153,7 +203,7 @@ async function adoptCommand(options = {}) {
     
     console.log();
     
-    // 8. Execute adoption
+    // 9. Execute adoption
     console.log(chalk.blue('🚀 Executing adoption...'));
     const adoptionStrategy = getAdoptionStrategy(strategy);
     const packageJson = require('../../package.json');
@@ -166,11 +216,19 @@ async function adoptCommand(options = {}) {
     
     console.log();
     
-    // 9. Report results
+    // 10. Report results
     if (result.success) {
       console.log(chalk.green('✅ Adoption completed successfully!'));
       console.log();
       
+      if (steeringStrategy) {
+        console.log(chalk.blue('Steering Strategy:'), steeringStrategy);
+        if (steeringBackupId) {
+          console.log(chalk.gray('  Backup:'), steeringBackupId);
+        }
+        console.log();
+      }
+      
       if (result.filesCreated.length > 0) {
         console.log(chalk.blue('Files created:'));
         result.filesCreated.forEach(file => console.log(`  + ${file}`));
@@ -198,6 +256,62 @@ async function adoptCommand(options = {}) {
         console.log(chalk.gray('  Run'), chalk.cyan('kse rollback'), chalk.gray('if you need to undo changes'));
       }
       
+      console.log();
+      
+      // 11. Detect tool and offer automation setup
+      console.log(chalk.blue('🔍 Detecting your development environment...'));
+      try {
+        const toolDetection = await detectTool(projectPath);
+        const autoConfig = await generateAutoConfig(toolDetection, projectPath);
+        
+        console.log();
+        console.log(chalk.blue('Tool Detected:'), chalk.cyan(toolDetection.primaryTool));
+        console.log(chalk.blue('Confidence:'), autoConfig.confidence);
+        
+        if (autoConfig.notes.length > 0) {
+          console.log();
+          autoConfig.notes.forEach(note => console.log(chalk.gray(`  ℹ️  ${note}`)));
+        }
+        
+        // Offer automation setup (unless --auto)
+        if (!auto && autoConfig.suggestedPresets.length > 0) {
+          console.log();
+          const { setupAutomation } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'setupAutomation',
+              message: 'Would you like to set up automation for this tool?',
+              default: true
+            }
+          ]);
+          
+          if (setupAutomation) {
+            console.log();
+            console.log(chalk.blue('📋 Recommended automation setup:'));
+            console.log();
+            console.log(chalk.gray('Suggested presets:'));
+            autoConfig.suggestedPresets.forEach(preset => {
+              console.log(`  - ${preset}`);
+            });
+            console.log();
+            console.log(chalk.gray('Run these commands to set up:'));
+            autoConfig.suggestedCommands.forEach(cmd => {
+              console.log(chalk.cyan(`  ${cmd}`));
+            });
+          }
+        } else if (autoConfig.suggestedCommands.length > 0) {
+          console.log();
+          console.log(chalk.blue('💡 Automation setup:'));
+          autoConfig.suggestedCommands.forEach(cmd => {
+            console.log(chalk.gray(`  ${cmd}`));
+          });
+        }
+      } catch (toolError) {
+        // Tool detection is optional, don't fail adoption if it errors
+        console.log(chalk.yellow('⚠️  Could not detect development tool'));
+        console.log(chalk.gray('  You can manually set up automation later'));
+      }
+      
       console.log();
       console.log(chalk.blue('💡 Next steps:'));
       console.log('  1. Review the .kiro/ directory structure');

package/lib/commands/context.js

@@ -0,0 +1,99 @@
+/**
+ * Context Command
+ * 
+ * Exports spec context for cross-tool usage
+ */
+
+const chalk = require('chalk');
+const ContextExporter = require('../context/context-exporter');
+
+/**
+ * Export spec context
+ * 
+ * @param {string} specName - Spec name
+ * @param {Object} options - Command options
+ * @param {boolean} options.requirements - Include requirements (default: true)
+ * @param {boolean} options.design - Include design (default: true)
+ * @param {boolean} options.tasks - Include tasks (default: true)
+ * @param {boolean} options.steering - Include steering rules
+ * @param {string} options.steeringFiles - Comma-separated list of steering files
+ * @returns {Promise<void>}
+ */
+async function exportContext(specName, options = {}) {
+  const projectPath = process.cwd();
+  const exporter = new ContextExporter();
+  
+  console.log(chalk.red('🔥') + ' Exporting Context');
+  console.log();
+  
+  try {
+    console.log(`Spec: ${chalk.cyan(specName)}`);
+    console.log();
+    
+    // Parse options
+    const exportOptions = {
+      includeRequirements: options.requirements !== false,
+      includeDesign: options.design !== false,
+      includeTasks: options.tasks !== false,
+      includeSteering: options.steering === true,
+      steeringFiles: options.steeringFiles 
+        ? options.steeringFiles.split(',').map(f => f.trim())
+        : []
+    };
+    
+    console.log('Export options:');
+    console.log(`  Requirements: ${exportOptions.includeRequirements ? chalk.green('✓') : chalk.gray('✗')}`);
+    console.log(`  Design: ${exportOptions.includeDesign ? chalk.green('✓') : chalk.gray('✗')}`);
+    console.log(`  Tasks: ${exportOptions.includeTasks ? chalk.green('✓') : chalk.gray('✗')}`);
+    console.log(`  Steering: ${exportOptions.includeSteering ? chalk.green('✓') : chalk.gray('✗')}`);
+    
+    if (exportOptions.includeSteering && exportOptions.steeringFiles.length > 0) {
+      console.log(`  Steering files: ${chalk.gray(exportOptions.steeringFiles.join(', '))}`);
+    }
+    
+    console.log();
+    console.log('Exporting...');
+    console.log();
+    
+    const result = await exporter.exportContext(
+      projectPath,
+      specName,
+      exportOptions
+    );
+    
+    if (result.success) {
+      console.log(chalk.green('✅ Context exported successfully'));
+      console.log();
+      console.log(`Export file: ${chalk.cyan(result.exportPath)}`);
+      console.log(`Sections: ${chalk.gray(result.sections)}`);
+      console.log(`Size: ${chalk.gray(formatBytes(result.size))}`);
+      console.log();
+      console.log('Usage:');
+      console.log('  1. Copy the exported file to your AI coding assistant');
+      console.log('  2. Reference specific sections when working on tasks');
+      console.log('  3. Update task status in the original tasks.md after completion');
+    } else {
+      console.log(chalk.red('❌ Export failed'));
+      console.log();
+      console.log(`Error: ${result.error}`);
+    }
+  } catch (error) {
+    console.log(chalk.red('❌ Error:'), error.message);
+  }
+}
+
+/**
+ * Format bytes to human-readable string
+ * 
+ * @param {number} bytes - Bytes
+ * @returns {string} Formatted string
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+module.exports = {
+  exportContext
+};