stigmergy 1.2.13 → 1.3.1

package/docs/INSTALLER_ARCHITECTURE.md

@@ -0,0 +1,257 @@
+# Stigmergy CLI 安装器架构文档
+
+## 📋 概述
+
+本文档定义了 Stigmergy CLI 中各个安装器类的职责边界和使用场景，帮助开发者理解何时使用哪个安装器类。
+
+## 🏗️ 安装器架构概览
+
+```
+Stigmergy CLI 安装器体系
+├── StigmergyInstaller (完整安装器)
+│   ├── 继承 EnhancedCLIInstaller 的所有功能
+│   ├── 扫描和检测功能
+│   ├── 基础安装功能
+│   ├── 项目管理功能
+│   └── Cross-CLI Hooks 生成
+├── EnhancedCLIInstaller (增强安装器)
+│   ├── 权限处理
+│   ├── 批量安装
+│   ├── 升级功能
+│   └── 错误重试
+├── BaseInstaller (抽象基类)
+│   └── 定义标准接口
+└── EnhancedInstaller (已弃用)
+    └── 功能已整合到 EnhancedCLIInstaller
+```
+
+## 📊 详细职责对比
+
+| 功能/类 | StigmergyInstaller | EnhancedCLIInstaller | BaseInstaller | EnhancedInstaller |
+|---------|-------------------|---------------------|---------------|-------------------|
+| **继承关系** | 继承 EnhancedCLIInstaller | 独立实现 | 抽象基类 | 继承 BaseInstaller |
+| **扫描 CLI 工具** | ✅ `scanCLI()` | ❌ | ✅ 抽象方法 | ❌ |
+| **检测 CLI 工具** | ✅ `checkCLI()` | ❌ | ✅ 抽象方法 | ❌ |
+| **基础安装** | ✅ 调用父类 `installTools()` | ✅ `installTools()` | ✅ 抽象方法 | ❌ |
+| **权限处理** | ✅ 继承自父类 | ✅ `setupPermissions()` | ❌ | ❌ |
+| **批量安装** | ✅ 继承自父类 | ✅ `installTools()` | ❌ | ❌ |
+| **升级功能** | ✅ 继承自父类 | ✅ `upgradeTools()` | ❌ | ❌ |
+| **重试机制** | ✅ 继承自父类 | ✅ 自动重试 | ❌ | ❌ |
+| **部署 hooks** | ✅ `deployHooks()` | ❌ | ✅ 抽象方法 | ❌ |
+| **项目文件创建** | ✅ `createProjectFiles()` | ❌ | ❌ | ❌ |
+| **Cross-CLI Hooks** | ✅ `generateToolHook()` | ❌ | ❌ | ❌ |
+| **工具集成配置** | ✅ `installToolIntegration()` | ❌ | ❌ | ❌ |
+| **错误处理** | 高级 (继承权限感知) | 高级 (权限感知) | 抽象 | 基础 |
+| **推荐使用场景** | 完整功能和向后兼容 | 高级功能和权限处理 | 接口定义 | 不推荐使用 |
+
+## 🎯 职责详细说明
+
+### 1. StigmergyInstaller (完整安装器)
+
+**文件位置：** `src/core/installer.js`
+
+**继承关系：** 继承自 `EnhancedCLIInstaller`
+
+**主要职责：**
+- **继承自 EnhancedCLIInstaller**：所有高级功能（权限处理、批量安装、升级、重试）
+- **CLI 工具扫描和检测**：`scanCLI()` 和 `checkCLI()`
+- **Cross-CLI Hooks 生成**：`generateToolHook()` 和 `createToolHooks()`
+- **项目管理和配置**：`createProjectFiles()` 和 `deployHooks()`
+- **工具集成配置**：`installToolIntegration()` 和各种工具特定配置方法
+- **向后兼容性**：保持所有原有功能不变
+
+**推荐使用场景：**
+- 需要完整功能的 CLI 工具管理
+- 需要保持向后兼容的项目
+- 需要项目管理、配置和 Hooks 部署的复杂场景
+- 工具集成配置
+
+**使用场景：**
+- 扫描已安装的 CLI 工具
+- 创建项目文件
+- 部署集成 hooks
+- 基础安装需求
+
+**核心方法：**
+```javascript
+- scanCLI()           // 扫描所有 CLI 工具
+- checkCLI(toolName)  // 检查单个 CLI 工具
+- installTools()      // 基础安装 (无权限处理)
+- deployHooks()       // 部署 hooks
+- createProjectFiles() // 创建项目文件
+- installToolIntegration() // 工具集成配置
+```
+
+### 2. EnhancedCLIInstaller (增强安装器)
+
+**文件位置：** `src/core/enhanced_cli_installer.js`
+
+**主要职责：**
+- 高级权限处理
+- 批量安装优化
+- 工具升级功能
+- 自动重试机制
+- 跨平台权限提升
+
+**使用场景：**
+- 需要权限处理的安装
+- 批量安装多个工具
+- 升级现有工具
+- 权限受限环境下的安装
+
+**核心方法：**
+```javascript
+- setupPermissions()              // 权限设置和检测
+- installTools()                  // 批量安装 (有权限处理)
+- upgradeTools()                  // 批量升级
+- installTool()                   // 单工具安装
+- executeElevatedInstallation()   // 权限提升安装
+- isPermissionError()             // 权限错误检测
+```
+
+### 3. BaseInstaller (抽象基类)
+
+**文件位置：** `src/core/base_installer.js`
+
+**主要职责：**
+- 定义安装器标准接口
+- 提供基础实现
+- 确保继承类实现必需方法
+
+**使用场景：**
+- 作为其他安装器的基础
+- 定义统一接口
+- 代码复用
+
+## 🚀 使用指南
+
+### 何时使用 StigmergyInstaller？
+
+```javascript
+// 场景 1: 扫描和检测
+const installer = new StigmergyInstaller();
+const { available, missing } = await installer.scanCLI();
+
+// 场景 2: 部署 hooks
+await installer.deployHooks(availableTools);
+
+// 场景 3: 创建项目文件
+await installer.createProjectFiles();
+```
+
+### 何时使用 EnhancedCLIInstaller？
+
+```javascript
+// 场景 1: 需要权限处理的安装
+const enhancedInstaller = new EnhancedCLIInstaller({
+  verbose: true,
+  autoRetry: true,
+  maxRetries: 2
+});
+
+// 场景 2: 批量安装
+const result = await enhancedInstaller.installTools(toolNames, toolInfos);
+
+// 场景 3: 升级工具
+const upgradeResult = await enhancedInstaller.upgradeTools(toolNames, toolInfos);
+```
+
+## 🔄 集成模式
+
+### 模式 1: 分离式使用
+```javascript
+// 扫描使用基础安装器
+const baseInstaller = new StigmergyInstaller();
+const scanResult = await baseInstaller.scanCLI();
+
+// 安装使用增强安装器
+const enhancedInstaller = new EnhancedCLIInstaller();
+await enhancedInstaller.installTools(missingTools);
+```
+
+### 模式 2: 根据需求选择
+```javascript
+function createInstaller(options) {
+  if (options.needPermissions) {
+    return new EnhancedCLIInstaller(options);
+  } else {
+    return new StigmergyInstaller();
+  }
+}
+```
+
+## ⚠️ 注意事项
+
+### 避免的陷阱
+
+1. **不要混淆 installTools 方法**
+   - `StigmergyInstaller.installTools()`: 基础安装
+   - `EnhancedCLIInstaller.installTools()`: 权限感知的安装
+
+2. **不要在权限受限环境使用 StigmergyInstaller**
+   - 在系统目录中使用可能失败
+   - 应该使用 EnhancedCLIInstaller
+
+3. **不要混合使用安装器方法**
+   - 每个安装器都有完整的功能
+   - 不需要从一个调用另一个的方法
+
+### 性能考虑
+
+- **扫描操作**: 使用 StigmergyInstaller (更轻量)
+- **安装操作**: 使用 EnhancedCLIInstaller (功能更完整)
+- **批量操作**: 优先使用 EnhancedCLIInstaller
+
+## 🔧 配置建议
+
+### 开发环境
+```javascript
+const installer = new StigmergyInstaller({
+  verbose: true  // 开发时需要详细日志
+});
+```
+
+### 生产环境
+```javascript
+const installer = new EnhancedCLIInstaller({
+  verbose: false,
+  autoRetry: true,
+  maxRetries: 2
+});
+```
+
+### 权限受限环境
+```javascript
+const installer = new EnhancedCLIInstaller({
+  autoRetry: true,
+  maxRetries: 3,
+  timeout: 600000  // 增加超时时间
+});
+```
+
+## 📈 未来改进计划
+
+### 短期 (1-2 个月)
+- [ ] 统一 installTools 接口
+- [ ] 消除功能重复
+- [ ] 添加安装器工厂模式
+
+### 中期 (3-6 个月)
+- [ ] 插件化安装器系统
+- [ ] 配置文件驱动的安装器选择
+- [ ] 安装器性能监控
+
+### 长期 (6+ 个月)
+- [ ] 动态安装器加载
+- [ ] 云端安装器配置
+- [ ] 智能安装器选择算法
+
+## 📝 总结
+
+Stigmergy CLI 的安装器架构设计遵循单一职责原则：
+
+- **StigmergyInstaller**: 负责扫描、检测、基础安装、项目管理
+- **EnhancedCLIInstaller**: 负责权限处理、批量操作、升级、重试
+- **BaseInstaller**: 提供统一接口和基础实现
+
+选择合适的安装器类可以确保最佳的性能和用户体验。

package/docs/LESSONS_LEARNED.md

@@ -0,0 +1,252 @@
+# 错误教训记录 (LESSONS LEARNED)
+
+本文档记录 Stigmergy 项目开发过程中遇到的重大错误和经验教训，**必须仔细阅读并避免重复犯错**。
+
+---
+
+## 🔴 致命错误 #1: 模板字符串中的正则表达式转义
+
+**日期**: 2025-12-25
+**影响**: 生产环境语法错误，所有 CLI 工具的 ResumeSession 集成失效
+**修复版本**: v1.3.2-beta.3
+**调试时间**: 约 2 小时
+**失败尝试**: 3 次
+
+### 问题描述
+
+生成的 `resumesession-history.js` 文件包含语法错误：
+
+```javascript
+SyntaxError: Invalid or unexpected token
+  at resumesession-history.js:515
+  const cleanInput = input.replace(/^\\/?stigmergy-resume\s*/i, '').trim();
+                                                            ^^^^^^^
+```
+
+### 错误代码
+
+**文件**: `src/core/coordination/nodejs/generators/ResumeSessionGenerator.js`
+**位置**: Line 537, 627
+
+```javascript
+// ❌ 错误写法
+const cleanInput = input.replace(/^\\\\/?\${commandName}\\s*/i, '').trim();
+const parts = cleanInput.split(/\\\\s+/).filter(p => p.length > 0);
+```
+
+### 根本原因分析
+
+#### 错误 #1: 阻止了模板插值
+
+```javascript
+\${commandName}  // ❌ 这会生成字面量 "${commandName}"，而不是插值后的值！
+${commandName}   // ✅ 这才会插值生成 "/stigmergy-resume"
+```
+
+**错误后果**：生成的代码中包含 `${commandName}` 字面量，导致语法错误。
+
+#### 错误 #2: 正则字面量中的 `/` 冲突
+
+```javascript
+// 当 commandName = "/stigmergy-resume" 时
+// 生成的代码：
+const cleanInput = input.replace(/^\\/?\/stigmergy-resume\s*/i, '').trim();
+//                              ↑ 第一个 / 关闭了正则字面量
+//                                stigmergy-resume\s*/i  ← 这部分变成了无关代码
+```
+
+**错误后果**：正则表达式被提前关闭，后续代码变成语法错误。
+
+#### 错误 #3: 反斜杠转义计算错误
+
+```
+模板字符串转义层级：
+源文件 → 模板字符串 → 生成代码 → 正则表达式
+
+错误的计算：
+源文件写：/^\\\\/?\${commandName}\\s*/i
+期望生成：/^\\/?stigmergy-resume\s*/i
+实际生成：/^\\/?${commandName}\s*/i  ← 未插值 + 正则破坏
+```
+
+### 正确的解决方案
+
+```javascript
+// ✅ 正确写法
+const cleanInput = input.replace(
+  new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+  ''
+).trim();
+const parts = cleanInput.split(/\\\s+/).filter(p => p.length > 0);
+```
+
+### 转义计算公式
+
+```
+源文件中的反斜杠数 = 目标反斜杠数 × 2^(嵌套层数)
+```
+
+**实际应用**：
+
+| 目标 | 在模板字符串中写 | 生成后 | 解释 |
+|------|------------------|--------|------|
+| `\s` | `\\s` | `\s` | 模板转义 1 次 |
+| `\\s` | `\\\\s` | `\\s` | 模板转义 1 次 |
+| `\\\s` | `\\\\\\s` | `\\s` | 字符串内容为 `\\s` |
+
+### 为什么使用 RegExp 构造函数？
+
+```javascript
+// ❌ 危险：正则字面量
+/^\\\\/?\/stigmergy-resume\s*/i
+//        ↑ 与命令名中的 / 冲突
+
+// ✅ 安全：RegExp 构造函数
+new RegExp('^\\\\\\\\/?' + '/stigmergy-resume' + '\\\\\s*', 'i')
+//           ↑ 通过字符串拼接避免 / 冲突
+```
+
+### 经验教训
+
+#### 1. 永远记住的规则
+
+> **在模板字符串中生成包含正则的代码时，使用 RegExp 构造函数 + 字符串拼接，永远比尝试计算正确的正则字面量转义更安全！**
+
+```javascript
+// ✅ 安全、清晰、可维护
+new RegExp('pattern' + variable + 'pattern', 'flags')
+
+// ❌ 危险、复杂、易出错
+/pattern${variable}pattern/flags
+```
+
+#### 2. 必须遵守的规则
+
+- [ ] **永远不要阻止插值**：使用 `${variable}`，而不是 `\${variable}`
+- [ ] **动态模式 → RegExp 构造函数**：避免正则字面量中的 `/` 冲突
+- [ ] **反斜杠数量必须计算**：使用公式，不能猜测
+- [ ] **必须添加语法验证**：生成代码后立即测试语法
+- [ ] **必须注释说明转义**：让其他人理解你的计算
+
+#### 3. 代码审查检查清单
+
+涉及 **模板字符串 + 正则表达式** 的代码必须检查：
+
+```javascript
+// ✅ 检查项
+- [ ] 所有 ${variable} 是否真的需要插值（不是 \${variable}）
+- [ ] 如果模式包含动态的 /，是否使用了 RegExp 构造函数
+- [ ] 反斜杠数量是否经过计算（而非猜测）
+- [ ] 是否有语法验证测试
+- [ ] 是否注释说明了转义的计算过程
+```
+
+### 验证工具
+
+```javascript
+/**
+ * 验证生成的代码是否有语法错误
+ */
+function validateGeneratedCode(code) {
+  try {
+    new Function(code);
+    return true;
+  } catch (e) {
+    console.error('❌ 语法错误:', e.message);
+    console.error('代码:', code);
+    return false;
+  }
+}
+
+/**
+ * 计算需要的反斜杠数量
+ */
+function calculateBackslashes(targetCount, nestingDepth = 1) {
+  return '\\'.repeat(targetCount * Math.pow(2, nestingDepth));
+}
+
+// 使用示例
+const generatedCode = generator.generateForCLI('claude');
+if (!validateGeneratedCode(generatedCode)) {
+  throw new Error('生成的代码有语法错误！');
+}
+```
+
+### 相关文档
+
+- [开发规范 - 代码生成规范](./development_guidelines.md#10-代码生成规范)
+- [ResumeSessionGenerator 源代码](../src/core/coordination/nodejs/generators/ResumeSessionGenerator.js)
+- [修复提交](https://github.com/your-repo/commit/6a2ee2c6)
+
+---
+
+## 📋 错误教训快速参考
+
+### 正则表达式生成
+
+| 场景 | ✅ 正确 | ❌ 错误 |
+|------|--------|--------|
+| 动态模式 | `new RegExp(pattern + var)` | `/pattern${var}/` |
+| 模板插值 | `${variable}` | `\${variable}` |
+| 反斜杠转义 | 通过公式计算 | 猜测数量 |
+| 语法验证 | 必须添加 | 跳过测试 |
+
+### 转义速查表
+
+| 生成目标 | 模板字符串中写 | 说明 |
+|----------|----------------|------|
+| `\s` | `\\s` | 匹配空白字符 |
+| `\\s` | `\\\\s` | 字符串 `"\s"` |
+| `\\\s` | `\\\\\\s` | 字符串 `"\\s"` |
+| `/stigmergy-resume` | `${commandName}` | 插值命令名 |
+| `RegExp('/stigmergy-resume')` | `new RegExp('${commandName}')` | 动态正则 |
+
+---
+
+## 🔄 如何添加新的错误教训
+
+当遇到重大错误时，请按照以下格式记录：
+
+```markdown
+## 🔴 致命错误 #N: [错误标题]
+
+**日期**: YYYY-MM-DD
+**影响**: [影响范围]
+**修复版本**: vX.X.X
+**调试时间**: 约 X 小时
+**失败尝试**: X 次
+
+### 问题描述
+[描述问题的现象和错误信息]
+
+### 错误代码
+**文件**: [文件路径]
+**位置**: Line XXX
+
+```javascript
+// ❌ 错误写法
+[错误代码]
+```
+
+### 根本原因分析
+[分析为什么会出现这个错误]
+
+### 正确的解决方案
+```javascript
+// ✅ 正确写法
+[正确代码]
+```
+
+### 经验教训
+[总结规则和检查清单]
+
+### 验证工具
+[提供验证和测试方法]
+```
+
+---
+
+**最后更新**: 2025-12-25
+**维护者**: Stigmergy 开发团队
+
+**记住这些教训，避免重复犯错！**