stigmergy 1.3.2-beta.0 → 1.3.2-beta.10

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 开发团队
+
+**记住这些教训，避免重复犯错！**

package/docs/development_guidelines.md

@@ -389,4 +389,280 @@ class CacheManager {
 }
 ```
 
+## 10. 代码生成规范
+
+### 10.1 模板字符串中的正则表达式 ⚠️ 极其重要！
+
+#### 🔴 致命陷阱：正则表达式字面量 vs RegExp 构造函数
+
+**问题场景**：在模板字符串中生成包含正则表达式的代码
+
+```javascript
+// ❌ 错误示例
+const code = `
+  const cleanInput = input.replace(/^\\\\/?${commandName}\\s*/i, '').trim();
+`;
+
+// 当 commandName = "/stigmergy-resume" 时
+// 生成：/^\\/?\/stigmergy-resume\s*/i
+//                        ↑ 正则被 "/stigmergy-resume" 中的 / 提前关闭！
+```
+
+**错误原因分析**：
+
+1. **正则字面量语法冲突**：`/pattern/` 首尾的 `/` 是定界符
+2. **命令名中的 `/` 破坏语法**：`/^\\/?\/stigmergy-resume` 中第一个 `/` 关闭了正则
+3. **模板字符串插值错误**：使用 `\${variable}` 会阻止插值！
+
+#### ✅ 正确做法：使用 RegExp 构造函数
+
+```javascript
+// ✅ 正确示例
+const code = `
+  const cleanInput = input.replace(
+    new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+    ''
+  ).trim();
+`;
+```
+
+**转义计算公式**：
+
+```
+源文件中的反斜杠数 = 目标反斜杠数 × 2^(嵌套层数)
+```
+
+| 目标 | 在模板字符串中写 | 生成后 | 说明 |
+|------|------------------|--------|------|
+| `\s` | `\\s` | `\s` | 模板转义一次 |
+| `\\s` | `\\\\s` | `\\s` | 模板转义一次 |
+| `\\\s` | `\\\\\\s` | `\\s` | 字符串中为 `\\s` |
+
+#### 📋 必须遵守的规则
+
+1. **动态模式 → 用 RegExp 构造函数**
+   ```javascript
+   new RegExp(pattern + variable + pattern, flags)
+   ```
+
+2. **静态模式 → 可以用正则字面量**
+   ```javascript
+   const staticRegex = /\s+/;  // 简单清晰
+   ```
+
+3. **永远不要阻止插值**
+   ```javascript
+   // ❌ 错误：阻止插值
+   \${commandName}  // 生成字面量 "${commandName}"
+
+   // ✅ 正确：允许插值
+   ${commandName}   // 生成实际值 "/stigmergy-resume"
+   ```
+
+4. **不要在字符串中转义 `/`**
+   ```javascript
+   // ❌ 不必要
+   '\/path'  // 在字符串中不需要转义 /
+
+   // ✅ 正确
+   '/path'   // 字符串中的 / 不需要转义
+   ```
+
+#### 🛠️ 调试工具
+
+```javascript
+/**
+ * 验证生成的代码是否有语法错误
+ */
+function validateGeneratedCode(code) {
+  try {
+    new Function(code);
+    return true;
+  } catch (e) {
+    console.error('语法错误:', e.message);
+    return false;
+  }
+}
+
+/**
+ * 计算需要的反斜杠数量
+ */
+function calculateBackslashes(targetCount, nestingDepth = 1) {
+  return '\\'.repeat(targetCount * Math.pow(2, nestingDepth));
+}
+```
+
+#### 📝 代码审查检查清单
+
+涉及 **模板字符串 + 正则表达式** 的代码必须检查：
+
+- [ ] 所有 `${variable}` 是否真的需要插值（不是 `\${variable}`）
+- [ ] 如果模式包含动态的 `/`，是否使用了 RegExp 构造函数
+- [ ] 反斜杠数量是否经过计算（而非猜测）
+- [ ] 是否有语法验证测试
+- [ ] 是否注释说明了转义的计算过程
+
+#### 💡 永远记住
+
+> **在模板字符串中生成包含正则的代码时，使用 RegExp 构造函数 + 字符串拼接，永远比尝试计算正确的正则字面量转义更安全！**
+
+```javascript
+// ✅ 安全、清晰、可维护
+new RegExp('pattern' + variable + 'pattern', 'flags')
+
+// ❌ 危险、复杂、易出错
+/pattern${variable}pattern/flags
+```
+
+### 10.2 代码生成最佳实践
+
+#### 10.2.1 生成器模式
+
+```javascript
+class CodeGenerator {
+  /**
+   * 生成CLI集成代码
+   * @param {string} cliName - CLI工具名称
+   * @returns {string} 生成的代码
+   */
+  generateForCLI(cliName) {
+    const commandName = this.getCommandName(cliName);
+
+    return `
+// Auto-generated by Stigmergy - DO NOT EDIT
+const handler = {
+  commandName: '${commandName}',
+
+  async handle(input) {
+    const cleanInput = input.replace(
+      new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+      ''
+    ).trim();
+
+    // 处理逻辑...
+    return { response: 'OK' };
+  }
+};
+
+module.exports = handler;
+`;
+  }
+
+  /**
+   * 获取命令名称
+   */
+  getCommandName(cliName) {
+    const needsSlash = ['claude', 'codebuddy'].includes(cliName.toLowerCase());
+    return needsSlash ? `/stigmergy-resume` : 'stigmergy-resume';
+  }
+}
+```
+
+#### 10.2.2 测试生成代码
+
+```javascript
+const { CodeGenerator } = require('./generators');
+
+describe('CodeGenerator', () => {
+  test('should generate valid JavaScript syntax', () => {
+    const generator = new CodeGenerator();
+    const code = generator.generateForCLI('claude');
+
+    // 验证语法
+    expect(() => new Function(code)).not.toThrow();
+
+    // 验证包含关键部分
+    expect(code).toContain('new RegExp');
+    expect(code).toContain('/stigmergy-resume');
+  });
+
+  test('should escape regex correctly', () => {
+    const generator = new CodeGenerator();
+    const code = generator.generateForCLI('claude');
+
+    // 提取并验证正则表达式
+    const regexMatch = code.match(/new RegExp\('([^']+)',\s*'i'\)/);
+    expect(regexMatch).toBeTruthy();
+
+    // 测试生成的正则是否工作
+    const pattern = regexMatch[1];
+    const regex = new RegExp(pattern, 'i');
+    expect(regex.test('/stigmergy-resume')).toBe(true);
+    expect(regex.test('\\/stigmergy-resume')).toBe(true);
+  });
+});
+```
+
+### 10.3 常见错误案例
+
+#### 案例1：阻止插值
+
+```javascript
+// ❌ 错误
+const commandName = '/stigmergy-resume';
+const code = `input.replace(/^\\\\/?\${commandName}\\s*/i, '')`;
+// 生成：input.replace(/^\\\\/?${commandName}\s*/i, '')
+//                                ↑ 未插值！
+```
+
+```javascript
+// ✅ 正确
+const commandName = '/stigmergy-resume';
+const code = `input.replace(new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'), '')`;
+// 生成：input.replace(new RegExp('^\\\\/?' + '/stigmergy-resume' + '\s*', 'i'), '')
+```
+
+#### 案例2：正则字面量中的 `/` 冲突
+
+```javascript
+// ❌ 错误
+const commandName = '/stigmergy-resume';
+const code = `input.replace(/\\/?${commandName}\\s*/i, '')`;
+// 生成：input.replace(/\/?\/stigmergy-resume\s*/i, '')
+//                        ↑ 第一个 / 关闭了正则
+```
+
+```javascript
+// ✅ 正确
+const commandName = '/stigmergy-resume';
+const code = `input.replace(new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'), '')`;
+```
+
+### 10.4 历史教训记录
+
+#### 2025-12-25: ResumeSessionGenerator 正则转义错误
+
+**问题描述**：
+生成的 `resumesession-history.js` 文件包含语法错误，导致无法加载。
+
+**错误代码**（Line 537, 627）：
+```javascript
+const cleanInput = input.replace(/^\\\\/?\${commandName}\\s*/i, '').trim();
+```
+
+**错误原因**：
+1. `\${commandName}` 阻止了模板插值
+2. 正则字面量中的 `/` 与命令名中的 `/` 冲突
+3. 反斜杠转义计算错误
+
+**修复方案**：
+```javascript
+const cleanInput = input.replace(
+  new RegExp('^\\\\\\\\/?' + '${commandName}' + '\\\\\s*', 'i'),
+  ''
+).trim();
+```
+
+**影响范围**：
+- 影响：所有CLI工具的ResumeSession集成
+- 修复版本：v1.3.2-beta.3
+- 调试时间：约2小时
+- 失败尝试：3次
+
+**经验总结**：
+- 永远使用 RegExp 构造函数处理动态正则
+- 永远不要在模板字符串中用 `\${` 阻止插值（除非真的需要字面量）
+- 反斜杠数量必须通过公式计算，不能猜测
+- 必须添加语法验证测试
+
 遵循这些开发规范可以确保代码质量、可维护性和团队协作效率。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stigmergy",
-  "version": "1.3.2-beta.0",
+  "version": "1.3.2-beta.10",
   "description": "Stigmergy CLI - Multi-Agents Cross-AI CLI Tools Collaboration System",
   "main": "src/index.js",
   "bin": {
@@ -48,6 +48,8 @@
     "path-fixer": "node path-fixer.js",
     "emergency-clean": "node emergency-cleanup.js",
     "test:conflict-prevention": "node test/conflict-prevention-test.js",
+    "test:comprehensive": "node scripts/run-comprehensive-tests.js",
+    "test:quick": "node scripts/run-quick-tests.js",
     "post-deployment-config": "node scripts/post-deployment-config.js",
     "preinstall": "node scripts/preinstall-check.js",
     "postinstall": "node src/index.js auto-install",