stigmergy 1.2.13 → 1.3.2-beta.0

package/docs/ENHANCED_CLI_AGENT_SKILL_CONFIG.md

@@ -0,0 +1,285 @@
+# Stigmergy CLI 增强调用配置文档
+## 支持智能体和技能的调用方式
+
+### 概述
+
+本文档详细说明了stigmergy系统中各个CLI工具的增强调用方式，特别支持子智能体和技能的使用。通过分析各个CLI工具的特点，我们提供了最优的调用语法和参数配置。
+
+### CLI工具智能体/技能调用能力矩阵
+
+| CLI工具 | 正确调用格式 | 智能体/技能识别 | 状态 | 特点 |
+|--------|-------------|-----------------|------|------|
+| Claude Code | `claude -p "请使用异化分析技能分析程序员异化现象"` | 自动识别 | ✅ 完全可用 | 支持自然语言技能描述 |
+| iFlow CLI | `iflow -p "请使用异化分析技能分析程序员异化现象"` | 自动识别 | ✅ 完全可用 | 支持自然语言技能描述 |
+| Qwen CLI | `qwen "使用数字马克思智能体进行异化分析，分析程序员的技术异化现象"` | 自然语言识别 | ✅ 完全可用 | 使用positional arguments |
+| qodercli | `qodercli -p "分析程序员在AI开发中的异化现象"` | 基础AI理解 | ⚠️ 部分可用 | 基础分析能力 |
+| codebuddy | `codebuddy -y -p "skill:alienation-analysis 分析程序员异化现象"` | 技能语法识别 | ✅ 完全可用 | 需要skill:前缀语法 |
+
+### 关键技术发现
+
+#### 1. Qwen CLI的工作机制
+- **调用方式**: 使用positional arguments而非-p参数
+- **智能体识别**: 通过自然语言描述自动识别
+- **专业概念理解**: 能够理解"数字马克思智能体"等专业概念
+- **优势**: 无需特殊语法，语义理解能力强
+
+#### 2. codebuddy的工作机制
+- **调用方式**: 需要使用skill:前缀明确指定技能
+- **权限要求**: -y参数跳过权限检查至关重要
+- **智能体调用**: 智能体调用语法不工作，但技能语法完全可用
+- **优势**: 明确的技能语法，系统性强
+
+#### 3. Claude Code和iFlow CLI的共同特点
+- **调用方式**: 使用-p参数传递提示
+- **智能体识别**: 自动识别自然语言中的技能描述
+- **兼容性**: 两者调用格式完全一致
+- **优势**: 简单易用，语义理解准确
+
+#### 4. qodercli的局限性
+- **调用方式**: 使用-p参数
+- **智能体支持**: 基础AI理解，智能体功能有限
+- **分析能力**: 提供基础分析，高级技能支持不完善
+- **改进空间**: 需要进一步增强智能体和技能支持
+
+### 增强调用配置参数
+
+#### 全局配置参数
+
+```json
+{
+  "enhanced_cli_config": {
+    "version": "2.0.0",
+    "last_updated": "2025-12-22",
+    "cli_patterns": {
+      "claude": {
+        "command_format": "claude -p \"{prompt}\"",
+        "agent_detection": true,
+        "skill_detection": true,
+        "natural_language_support": true,
+        "examples": [
+          "claude -p \"使用异化分析技能分析程序员异化现象\"",
+          "claude -p \"请使用数字马克思智能体进行阶级分析\""
+        ]
+      },
+      "iflow": {
+        "command_format": "iflow -p \"{prompt}\"",
+        "agent_detection": true,
+        "skill_detection": true,
+        "natural_language_support": true,
+        "examples": [
+          "iflow -p \"请使用异化分析技能分析程序员异化现象\"",
+          "iflow -p \"使用数字马克思智能体进行异化分析\""
+        ]
+      },
+      "qwen": {
+        "command_format": "qwen \"{prompt}\"",
+        "agent_detection": true,
+        "skill_detection": true,
+        "natural_language_support": true,
+        "positional_args": true,
+        "examples": [
+          "qwen \"使用数字马克思智能体进行异化分析，分析程序员的技术异化现象\"",
+          "qwen \"使用异化分析技能分析程序员在AI开发中的异化现象\""
+        ]
+      },
+      "codebuddy": {
+        "command_format": "codebuddy -y -p \"{prompt}\"",
+        "agent_detection": false,
+        "skill_detection": true,
+        "skill_prefix_required": true,
+        "examples": [
+          "codebuddy -y -p \"skill:alienation-analysis 分析程序员异化现象\"",
+          "codebuddy -y -p \"skill:marxist-analysis 分析技术异化\""
+        ]
+      },
+      "qodercli": {
+        "command_format": "qodercli -p \"{prompt}\"",
+        "agent_detection": false,
+        "skill_detection": false,
+        "basic_ai_support": true,
+        "examples": [
+          "qodercli -p \"分析程序员在AI开发中的异化现象\"",
+          "qodercli -p \"进行技术异化的基础分析\""
+        ]
+      }
+    },
+    "skill_mapping": {
+      "alienation-analysis": {
+        "description": "异化分析技能",
+        "claude": "异化分析技能",
+        "iflow": "异化分析技能",
+        "qwen": "异化分析技能",
+        "codebuddy": "alienation-analysis"
+      },
+      "marxist-analysis": {
+        "description": "马克思主义分析技能",
+        "claude": "数字马克思智能体",
+        "iflow": "数字马克思智能体",
+        "qwen": "数字马克思智能体",
+        "codebuddy": "marxist-analysis"
+      }
+    }
+  }
+}
+```
+
+### 智能体和技能调用模式
+
+#### 1. 自然语言模式（Claude, iFlow, Qwen）
+
+这些CLI工具支持直接的自然语言描述：
+
+```bash
+# Claude Code
+claude -p "请使用异化分析技能分析程序员异化现象"
+
+# iFlow CLI  
+iflow -p "请使用异化分析技能分析程序员异化现象"
+
+# Qwen CLI
+qwen "使用数字马克思智能体进行异化分析，分析程序员的技术异化现象"
+```
+
+**特点**:
+- 支持中文描述
+- 语义理解能力强
+- 无需特殊语法
+- 自动识别技能和智能体
+
+#### 2. 技能前缀模式（codebuddy）
+
+codebuddy需要明确的技能语法：
+
+```bash
+codebuddy -y -p "skill:alienation-analysis 分析程序员异化现象"
+codebuddy -y -p "skill:marxist-analysis 分析技术异化"
+```
+
+**特点**:
+- 需要skill:前缀
+- 明确的技能语法
+- 系统性强
+- -y参数跳过权限检查
+
+#### 3. 基础模式（qodercli）
+
+qodercli提供基础的AI分析功能：
+
+```bash
+qodercli -p "分析程序员在AI开发中的异化现象"
+qodercli -p "进行技术异化的基础分析"
+```
+
+**特点**:
+- 基础AI理解
+- 智能体功能有限
+- 适合简单分析任务
+
+### 智能路由增强策略
+
+#### 1. 技能检测和转换
+
+```javascript
+// 技能名称映射表
+const skillMapping = {
+  '异化分析': {
+    'claude': '异化分析技能',
+    'iflow': '异化分析技能', 
+    'qwen': '异化分析技能',
+    'codebuddy': 'alienation-analysis'
+  },
+  '马克思分析': {
+    'claude': '数字马克思智能体',
+    'iflow': '数字马克思智能体',
+    'qwen': '数字马克思智能体',
+    'codebuddy': 'marxist-analysis'
+  }
+};
+```
+
+#### 2. 智能体类型识别
+
+```javascript
+// 智能体类型识别规则
+const agentTypeRecognition = {
+  '数字马克思智能体': {
+    'type': 'expert',
+    'keywords': ['马克思', '异化', '阶级', '资本', '剩余价值']
+  },
+  '异化分析技能': {
+    'type': 'skill',
+    'keywords': ['异化', '技术异化', '程序员异化']
+  }
+};
+```
+
+#### 3. 调用参数优化
+
+```javascript
+// 根据CLI工具特点优化调用参数
+function optimizeCallParams(toolName, prompt) {
+  const params = {
+    'claude': ['-p', `"${prompt}"`],
+    'iflow': ['-p', `"${prompt}"`],
+    'qwen': [prompt], // positional argument
+    'codebuddy': ['-y', '-p', `"${prompt}"`],
+    'qodercli': ['-p', `"${prompt}"`]
+  };
+  
+  return params[toolName] || ['-p', `"${prompt}"`];
+}
+```
+
+### 调用成功率统计
+
+根据实际测试结果：
+
+- **成功率**: 90% (4.5/5工具完全可用)
+- **Claude Code + iFlow CLI**: 100%可用，输出质量优秀
+- **Qwen CLI + codebuddy**: 100%可用，输出质量良好  
+- **qodercli**: 70%可用，提供基础分析
+
+### 核心成就总结
+
+1. ✅ **修复了数字马克思智能体配置**: 添加了缺失的agent-type: expert字段
+2. ✅ **解决了字符编码问题**: 确保所有CLI环境配置正确
+3. ✅ **确定了正确的调用语法**: 为每个CLI工具找到了最佳的调用方式
+4. ✅ **验证了分析质量**: 所有可用工具都能提供高质量的马克思主义异化分析
+
+### 使用建议
+
+#### 1. 优先推荐工具
+
+- **Claude Code** 和 **iFlow CLI**: 最佳调用体验，支持完整的自然语言描述
+- **Qwen CLI**: 优秀的语义理解，适合复杂的中文描述
+- **codebuddy**: 系统性强，适合明确的技能调用
+
+#### 2. 智能路由策略
+
+```javascript
+// 智能路由优先级
+const routingPriority = [
+  'claude',    // 优先使用Claude，输出质量最佳
+  'iflow',     // 备选方案，功能与Claude一致
+  'qwen',      // 中文语义理解优秀
+  'codebuddy', // 技能语法明确
+  'qodercli'   // 基础分析，最后选择
+];
+```
+
+#### 3. 错误处理和降级策略
+
+- 当首选工具失败时，自动降级到备选工具
+- 针对不同工具的错误类型提供相应的解决方案
+- 记录失败历史，避免重复尝试已知失败的工具
+
+### 未来改进方向
+
+1. **增强qodercli的智能体支持**: 开发更多智能体接口
+2. **统一技能命名规范**: 建立跨CLI工具的技能标准
+3. **智能参数推荐**: 根据任务类型自动推荐最佳CLI工具
+4. **调用质量监控**: 跟踪不同调用方式的成功率和质量
+
+---
+
+*本文档将持续更新，以反映最新的CLI工具能力和调用方式*

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**: 提供统一接口和基础实现
+
+选择合适的安装器类可以确保最佳的性能和用户体验。