stigmergy 1.0.94 → 1.0.95

package/docs/development_guidelines.md

@@ -0,0 +1,392 @@
+# Stigmergy CLI 开发规范
+
+## 1. 代码风格规范
+
+### 1.1 命名规范
+- **变量命名**：使用camelCase，如`userName`, `cliPatterns`
+- **常量命名**：使用UPPER_SNAKE_CASE，如`MAX_RETRY_COUNT`, `DEFAULT_TOOL`
+- **函数命名**：使用camelCase，如`analyzeCLI`, `getCLIPattern`
+- **类命名**：使用PascalCase，如`SmartRouter`, `MemoryManager`
+- **文件命名**：使用snake_case，如`smart_router.js`, `cli_help_analyzer.js`
+
+### 1.2 注释规范
+```javascript
+/**
+ * 智能路由类
+ * 负责根据用户输入将请求路由到合适的CLI工具
+ */
+class SmartRouter {
+    /**
+     * 初始化智能路由
+     * @returns {Promise<void>}
+     */
+    async initialize() {
+        // 实现初始化逻辑
+    }
+    
+    /**
+     * 智能路由决策
+     * @param {string} userInput - 用户输入
+     * @returns {Promise<Object>} 路由结果
+     */
+    async smartRoute(userInput) {
+        // 实现路由逻辑
+    }
+}
+```
+
+### 1.3 错误处理规范
+```javascript
+try {
+    const result = await someAsyncOperation();
+    return result;
+} catch (error) {
+    // 记录错误日志
+    console.error(`[ERROR] Operation failed: ${error.message}`, error);
+    
+    // 抛出自定义错误或返回默认值
+    throw new Error(`Operation failed: ${error.message}`);
+}
+```
+
+## 2. 模块设计规范
+
+### 2.1 模块结构
+```
+src/
+├── core/                    # 核心模块
+│   ├── smart_router.js      # 智能路由
+│   ├── cli_help_analyzer.js # CLI帮助分析器
+│   └── memory_manager.js    # 内存管理器
+├── adapters/                # 适配器模块
+│   └── [tool_name]/         # 各工具适配器
+├── utils/                   # 工具模块
+└── main_english.js          # 主入口文件
+```
+
+### 2.2 模块导出规范
+```javascript
+// smart_router.js
+class SmartRouter {
+    // 类实现
+}
+
+// 导出类和重要函数
+module.exports = SmartRouter;
+
+// 或者导出多个项
+module.exports = { 
+    SmartRouter, 
+    someUtilityFunction 
+};
+```
+
+## 3. 异步编程规范
+
+### 3.1 Promise使用
+```javascript
+// 推荐：使用async/await
+async function processData() {
+    try {
+        const result = await fetchData();
+        return await processResult(result);
+    } catch (error) {
+        throw new Error(`Processing failed: ${error.message}`);
+    }
+}
+
+// 避免：回调地狱
+// 不推荐嵌套过多的Promise链
+```
+
+### 3.2 错误边界处理
+```javascript
+async function robustOperation() {
+    const maxRetries = 3;
+    let lastError;
+    
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await riskyOperation();
+        } catch (error) {
+            lastError = error;
+            if (i < maxRetries - 1) {
+                // 重试前等待
+                await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+            }
+        }
+    }
+    
+    throw new Error(`Operation failed after ${maxRetries} retries: ${lastError.message}`);
+}
+```
+
+## 4. 文件操作规范
+
+### 4.1 异步文件操作
+```javascript
+const fs = require('fs/promises');
+
+// 推荐：使用fs/promises
+async function readFileAsync(filePath) {
+    try {
+        const data = await fs.readFile(filePath, 'utf8');
+        return data;
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        throw error;
+    }
+}
+
+// 避免：使用同步方法
+// const data = fs.readFileSync(filePath, 'utf8'); // 不推荐
+```
+
+### 4.2 路径处理
+```javascript
+const path = require('path');
+
+// 推荐：使用path模块处理路径
+const configPath = path.join(os.homedir(), '.stigmergy', 'config.json');
+
+// 避免：字符串拼接路径
+// const configPath = os.homedir() + '/.stigmergy/config.json'; // 不推荐
+```
+
+## 5. 环境变量规范
+
+### 5.1 环境变量使用
+```javascript
+// 推荐：使用解构赋值和默认值
+const { 
+    STIGMERGY_ENABLED = 'true',
+    STIGMERGY_VERSION = '1.0.0',
+    NODE_ENV = 'development'
+} = process.env;
+
+// 避免：直接访问process.env
+// if (process.env.STIGMERGY_ENABLED === 'true') // 不推荐
+```
+
+### 5.2 配置管理
+```javascript
+class ConfigManager {
+    constructor() {
+        this.config = {
+            enabled: process.env.STIGMERGY_ENABLED === 'true',
+            version: process.env.STIGMERGY_VERSION || '1.0.0',
+            debug: process.env.NODE_ENV === 'development'
+        };
+    }
+    
+    get(key) {
+        return this.config[key];
+    }
+    
+    set(key, value) {
+        this.config[key] = value;
+    }
+}
+```
+
+## 6. 日志规范
+
+### 6.1 日志级别
+```javascript
+const LOG_LEVELS = {
+    ERROR: 0,
+    WARN: 1,
+    INFO: 2,
+    DEBUG: 3
+};
+
+class Logger {
+    constructor(level = LOG_LEVELS.INFO) {
+        this.level = level;
+    }
+    
+    error(message, error) {
+        if (this.level >= LOG_LEVELS.ERROR) {
+            console.error(`[ERROR] ${message}`, error);
+        }
+    }
+    
+    warn(message) {
+        if (this.level >= LOG_LEVELS.WARN) {
+            console.warn(`[WARN] ${message}`);
+        }
+    }
+    
+    info(message) {
+        if (this.level >= LOG_LEVELS.INFO) {
+            console.log(`[INFO] ${message}`);
+        }
+    }
+    
+    debug(message) {
+        if (this.level >= LOG_LEVELS.DEBUG) {
+            console.log(`[DEBUG] ${message}`);
+        }
+    }
+}
+```
+
+### 6.2 日志格式
+```javascript
+// 统一日志格式
+[LEVEL] TIMESTAMP MESSAGE [CONTEXT]
+
+// 示例
+[INFO] 2023-12-08T10:30:00.000Z CLI tool analysis completed [claude]
+[ERROR] 2023-12-08T10:30:01.000Z Failed to execute command [qwen]
+```
+
+## 7. 测试规范
+
+### 7.1 测试文件命名
+- 单元测试：`*.test.js`
+- 集成测试：`*.integration.test.js`
+- 端到端测试：`*.e2e.test.js`
+
+### 7.2 测试结构
+```javascript
+describe('ModuleName', () => {
+    let instance;
+    
+    beforeEach(() => {
+        instance = new ModuleName();
+    });
+    
+    afterEach(() => {
+        // 清理资源
+    });
+    
+    describe('methodName', () => {
+        test('should do something when condition', async () => {
+            // 准备测试数据
+            
+            // 执行测试
+            
+            // 验证结果
+        });
+    });
+});
+```
+
+## 8. 安全规范
+
+### 8.1 输入验证
+```javascript
+function validateInput(input) {
+    if (typeof input !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    
+    if (input.length > 10000) {
+        throw new Error('Input too long');
+    }
+    
+    // 检查危险字符
+    if (/[;&|`$<>]/.test(input)) {
+        throw new Error('Invalid characters in input');
+    }
+    
+    return input.trim();
+}
+```
+
+### 8.2 命令执行安全
+```javascript
+const { spawn } = require('child_process');
+
+function safeExecuteCommand(command, args = []) {
+    // 验证命令和参数
+    if (!command || typeof command !== 'string') {
+        throw new Error('Invalid command');
+    }
+    
+    // 过滤参数中的危险字符
+    const safeArgs = args.filter(arg => 
+        typeof arg === 'string' && !/[;&|`$<>]/.test(arg)
+    );
+    
+    // 使用spawn而不是exec
+    return spawn(command, safeArgs, { 
+        stdio: 'inherit',
+        shell: false // 避免shell注入
+    });
+}
+```
+
+## 9. 性能规范
+
+### 9.1 内存管理
+```javascript
+// 及时释放大对象引用
+function processData(largeData) {
+    try {
+        // 处理数据
+        return processResult(largeData);
+    } finally {
+        // 清理大对象
+        largeData = null;
+    }
+}
+
+// 使用流处理大文件
+const fs = require('fs');
+const { pipeline } = require('stream/promises');
+
+async function processLargeFile(inputPath, outputPath) {
+    const readStream = fs.createReadStream(inputPath);
+    const writeStream = fs.createWriteStream(outputPath);
+    
+    await pipeline(
+        readStream,
+        transformStream,
+        writeStream
+    );
+}
+```
+
+### 9.2 缓存策略
+```javascript
+class CacheManager {
+    constructor() {
+        this.cache = new Map();
+        this.ttl = 24 * 60 * 60 * 1000; // 24小时
+    }
+    
+    get(key) {
+        const item = this.cache.get(key);
+        if (!item) return null;
+        
+        if (Date.now() - item.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return null;
+        }
+        
+        return item.value;
+    }
+    
+    set(key, value) {
+        this.cache.set(key, {
+            value,
+            timestamp: Date.now()
+        });
+    }
+    
+    cleanup() {
+        const now = Date.now();
+        for (const [key, item] of this.cache.entries()) {
+            if (now - item.timestamp > this.ttl) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
+```
+
+遵循这些开发规范可以确保代码质量、可维护性和团队协作效率。

package/docs/requirements_specification.md

@@ -0,0 +1,148 @@
+# Stigmergy CLI 系统需求规格说明书
+
+## 1. 引言
+
+### 1.1 目的
+本文档定义了Stigmergy CLI多智能体协作系统的功能需求和非功能需求，确保系统能够为用户提供高效的AI CLI工具协作体验。
+
+### 1.2 范围
+本系统旨在提供一个基础支撑平台，让用户能够自由决定如何使用各种AI CLI工具进行分工和协作，同时确保各工具间能够有效传递上下文信息。
+
+### 1.3 核心理念
+- 用户主导：用户决定如何分工和协同
+- CLI自主：各CLI工具自主决定调用其他工具
+- 系统支撑：项目只提供基础支撑和上下文传递机制
+
+## 2. 总体描述
+
+### 2.1 产品概述
+Stigmergy CLI是一个多智能体AI CLI工具协作系统，支持多种AI CLI工具（如Claude、Qwen、Gemini等）在同一项目环境中协同工作。
+
+### 2.2 产品功能
+- 智能路由：基于用户输入将请求路由到合适的CLI工具
+- 上下文管理：维护和传递项目上下文信息
+- 状态共享：提供全局内存管理机制
+- CLI模式分析：分析和缓存CLI工具的使用模式
+
+### 2.3 用户特征
+- AI开发者和研究人员
+- 需要使用多个AI工具协同工作的技术人员
+- 希望简化多CLI工具管理的用户
+
+### 2.4 运行环境
+- Node.js >= 16.0.0
+- 支持Windows、macOS和Linux操作系统
+- 需要安装各种AI CLI工具
+
+## 3. 功能需求
+
+### 3.1 智能路由系统 (FR-001)
+
+#### 3.1.1 基础路由功能
+**描述**：系统应能根据用户输入的关键字识别目标CLI工具并转发请求。
+**优先级**：高
+**输入**：用户输入的自然语言指令
+**处理**：
+1. 解析用户输入，识别CLI工具关键字
+2. 提取目标工具后的指令内容
+3. 将指令转发到相应CLI工具
+**输出**：CLI工具的执行结果
+
+#### 3.1.2 默认路由功能
+**描述**：当无法识别特定CLI工具时，系统应能将请求路由到默认工具。
+**优先级**：高
+**输入**：无法明确识别CLI工具的用户输入
+**处理**：
+1. 检查用户输入是否包含已知CLI工具关键字
+2. 如果未找到匹配，使用默认CLI工具
+**输出**：默认CLI工具的执行结果
+
+### 3.2 上下文管理系统 (FR-002)
+
+#### 3.2.1 环境变量传递
+**描述**：系统应在执行CLI工具时传递必要的环境变量。
+**优先级**：高
+**输入**：CLI工具名称和执行参数
+**处理**：
+1. 设置标准环境变量（项目目录、上下文文件路径等）
+2. 执行CLI工具并传递环境变量
+**输出**：带有环境变量的CLI工具执行
+
+#### 3.2.2 全局内存管理
+**描述**：系统应提供全局内存文件供各CLI工具读写共享状态。
+**优先级**：高
+**输入**：内存读写请求
+**处理**：
+1. 提供内存读取接口
+2. 提供内存更新接口
+3. 确保并发安全
+**输出**：内存数据或更新确认
+
+### 3.3 CLI模式分析系统 (FR-003)
+
+#### 3.3.1 CLI帮助信息分析
+**描述**：系统应能分析CLI工具的帮助信息并缓存模式。
+**优先级**：中
+**输入**：CLI工具名称
+**处理**：
+1. 执行CLI工具的帮助命令
+2. 解析帮助信息提取命令模式
+3. 缓存分析结果
+**输出**：CLI工具模式信息
+
+#### 3.3.2 模式缓存管理
+**描述**：系统应能管理和更新CLI模式缓存。
+**优先级**：中
+**输入**：缓存管理请求
+**处理**：
+1. 检查缓存有效性
+2. 更新过期缓存
+3. 处理缓存失效情况
+**输出**：缓存状态信息
+
+## 4. 非功能需求
+
+### 4.1 性能需求
+- CLI工具路由延迟应小于100ms
+- 内存读写操作应小于50ms
+- CLI模式分析应在5秒内完成
+
+### 4.2 可靠性需求
+- 系统应能处理CLI工具执行失败的情况
+- 系统应提供错误恢复机制
+- 系统应保证内存数据的一致性
+
+### 4.3 可用性需求
+- 系统应提供清晰的错误提示信息
+- 系统应支持命令行帮助信息
+- 系统应提供详细的日志记录
+
+### 4.4 安全性需求
+- 系统不应执行危险的系统命令
+- 系统应保护敏感的环境变量
+- 系统应防止未经授权的内存访问
+
+## 5. 外部接口需求
+
+### 5.1 用户界面
+- 命令行界面（CLI）
+- 标准输入输出流
+
+### 5.2 硬件接口
+- 标准计算机硬件
+- 网络连接（用于CLI工具通信）
+
+### 5.3 软件接口
+- Node.js运行时环境
+- 各种AI CLI工具
+- 文件系统API
+
+## 6. 其他需求
+
+### 6.1 国际化需求
+- 支持英文环境
+- 支持UTF-8编码
+
+### 6.2 可扩展性需求
+- 支持新增CLI工具
+- 支持插件化扩展