stigmergy 1.0.94 → 1.0.95

package/bin/stigmergy

@@ -1,12 +1,26 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-exec node "$basedir/../src/main_english.js" "$@"
+#!/usr/bin/env node
+
+// Cross-platform launcher for Stigmergy CLI
+// This replaces the problematic shell script to ensure Windows compatibility
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+// Get the path to the main script
+const mainScript = path.join(__dirname, '..', 'src', 'main_english.js');
+
+// Spawn the Node.js process with the main script and all arguments
+const child = spawn(process.execPath, [mainScript, ...process.argv.slice(2)], {
+  stdio: 'inherit'
+});
+
+// Forward exit code
+child.on('close', (code) => {
+  process.exit(code);
+});
+
+// Handle errors
+child.on('error', (error) => {
+  console.error('[ERROR] Failed to start Stigmergy CLI:', error.message);
+  process.exit(1);
+});

package/docs/HASH_TABLE.md

@@ -0,0 +1,83 @@
+# Hash Table Data Structure
+
+## Overview
+
+This project includes a HashTable implementation with collision handling using chaining. The implementation is part of the utility functions in `src/utils.js`.
+
+## Features
+
+- **Hash Function**: Uses a prime-based hashing algorithm for better distribution
+- **Collision Handling**: Implements chaining to handle hash collisions
+- **Key Operations**: 
+  - `set(key, value)`: Insert a key-value pair
+  - `get(key)`: Retrieve a value by key
+  - `keys()`: Get all keys in the hash table
+  - `values()`: Get all values in the hash table
+
+## Implementation Details
+
+### Hash Function
+
+The hash function uses a prime number (31) to reduce collisions:
+
+```javascript
+_hash(key) {
+  let total = 0;
+  const WEIRD_PRIME = 31;
+  for (let i = 0; i < Math.min(key.length, 100); i++) {
+    const char = key[i];
+    const value = char.charCodeAt(0) - 96;
+    total = (total * WEIRD_PRIME + value) % this.keyMap.length;
+  }
+  return total;
+}
+```
+
+### Collision Handling
+
+Collisions are handled using chaining - when two keys hash to the same index, they are stored in an array at that index:
+
+```javascript
+set(key, value) {
+  const index = this._hash(key);
+  if (!this.keyMap[index]) {
+    this.keyMap[index] = [];
+  }
+  this.keyMap[index].push([key, value]);
+  return this;
+}
+```
+
+## Usage
+
+```javascript
+const { HashTable } = require('./src/utils');
+
+// Create a new hash table
+const ht = new HashTable(17);
+
+// Set key-value pairs
+ht.set("maroon", "#800000");
+ht.set("yellow", "#FFFF00");
+
+// Get values
+console.log(ht.get("maroon")); // #800000
+
+// Get all keys/values
+console.log(ht.keys());
+console.log(ht.values());
+```
+
+## Time Complexity
+
+- **Insertion**: O(1) average case, O(n) worst case
+- **Lookup**: O(1) average case, O(n) worst case
+- **Deletion**: O(1) average case, O(n) worst case
+
+The worst case occurs when all elements hash to the same index, creating a single long chain.
+
+## Test Files
+
+- `test/hash-table-test.js`: Basic functionality tests
+- `test/collision-test.js`: Collision handling demonstration
+- `test/hash-table-demo.js`: Comprehensive usage example

package/docs/WEATHER_PROCESSOR_API.md

@@ -0,0 +1,230 @@
+# Weather Data Processing API
+
+## Overview
+
+This module provides functions for processing weather data from various sources and converting it into standardized formats for analysis and display. It handles data from different weather APIs and sensors, normalizing the output for consistent consumption.
+
+## Installation
+
+The weather processor is part of the Stigmergy CLI utility functions. No additional installation is required.
+
+## Usage
+
+```javascript
+const { processWeatherData } = require('./src/weatherProcessor');
+
+// Process raw weather data
+const processedData = processWeatherData(rawWeatherData, {
+  unit: 'celsius',
+  includeForecasts: true,
+  forecastDays: 5
+});
+```
+
+## API Reference
+
+### `processWeatherData(rawData, options)`
+
+Processes raw weather data and generates standardized output.
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `rawData` | Object | Raw weather data from API or sensor |
+| `options` | Object | Processing options |
+
+##### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `unit` | string | `'celsius'` | Temperature unit (`'celsius'`, `'fahrenheit'`, `'kelvin'`) |
+| `includeForecasts` | boolean | `false` | Whether to include forecast data |
+| `forecastDays` | number | `5` | Number of forecast days to include (1-7) |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| Object | Processed weather data with standardized format |
+
+#### Throws
+
+- `Error`: If input data is invalid or missing required fields
+- `Error`: If unit option is invalid
+- `Error`: If forecastDays is outside the valid range (1-7)
+
+#### Example
+
+```javascript
+const rawData = {
+  location: {
+    name: "London",
+    country: "UK",
+    lat: 51.5074,
+    lon: -0.1278
+  },
+  current: {
+    temp: 285.15,
+    feels_like: 283.15,
+    humidity: 72,
+    pressure: 1013,
+    wind_speed: 3.5,
+    wind_deg: 180,
+    visibility: 10000,
+    clouds: 40,
+    weather: [{
+      description: "scattered clouds",
+      icon: "03d"
+    }]
+  },
+  forecast: [
+    {
+      dt: 1640995200,
+      temp: { min: 282.15, max: 286.15 },
+      humidity: 65,
+      pressure: 1015,
+      wind_speed: 2.8,
+      wind_deg: 160,
+      pop: 0.2,
+      weather: [{ description: "light rain" }]
+    }
+  ]
+};
+
+const processedData = processWeatherData(rawData, {
+  unit: 'celsius',
+  includeForecasts: true,
+  forecastDays: 3
+});
+
+// Returns:
+// {
+//   timestamp: "2025-12-08T10:30:00.000Z",
+//   location: {
+//     name: "London",
+//     country: "UK",
+//     coordinates: { lat: 51.5074, lon: -0.1278 }
+//   },
+//   current: {
+//     temperature: { value: 12, unit: "celsius", feelsLike: 10 },
+//     humidity: 72,
+//     pressure: 1013,
+//     wind: { speed: 3.5, direction: 180 },
+//     visibility: 10000,
+//     cloudiness: 40,
+//     description: "scattered clouds",
+//     icon: "03d"
+//   },
+//   forecasts: [
+//     {
+//       date: "2022-01-01",
+//       temperature: { min: 9, max: 13, unit: "celsius" },
+//       humidity: 65,
+//       pressure: 1015,
+//       wind: { speed: 2.8, direction: 160 },
+//       precipitation: { probability: 0.2, amount: 0 },
+//       description: "light rain"
+//     }
+//   ]
+// }
+```
+
+## Data Structures
+
+### Processed Weather Data
+
+The returned object has the following structure:
+
+```javascript
+{
+  timestamp: string,        // ISO timestamp of processing
+  location: {
+    name: string,           // Location name
+    country: string,        // Country code
+    coordinates: {
+      lat: number,          // Latitude
+      lon: number           // Longitude
+    }
+  },
+  current: {
+    temperature: {
+      value: number,        // Temperature value
+      unit: string,         // Temperature unit
+      feelsLike: number     // "Feels like" temperature
+    },
+    humidity: number,       // Humidity percentage (0-100)
+    pressure: number,       // Atmospheric pressure in hPa
+    wind: {
+      speed: number,        // Wind speed
+      direction: number     // Wind direction in degrees
+    },
+    visibility: number,     // Visibility in meters
+    cloudiness: number,     // Cloud cover percentage (0-100)
+    description: string,    // Weather description
+    icon: string            // Weather icon code
+  },
+  forecasts: [              // Array of forecast objects (if enabled)
+    {
+      date: string,         // Forecast date (YYYY-MM-DD)
+      temperature: {
+        min: number,        // Minimum temperature
+        max: number,        // Maximum temperature
+        unit: string        // Temperature unit
+      },
+      humidity: number,     // Humidity percentage
+      pressure: number,     // Atmospheric pressure in hPa
+      wind: {
+        speed: number,      // Wind speed
+        direction: number   // Wind direction in degrees
+      },
+      precipitation: {
+        probability: number, // Precipitation probability (0-1)
+        amount: number       // Precipitation amount
+      },
+      description: string   // Weather description
+    }
+  ]
+}
+```
+
+## Supported Data Sources
+
+The processor can handle data from various weather services including:
+- OpenWeatherMap
+- WeatherAPI
+- AccuWeather
+- National Weather Service
+- Custom sensor data
+
+## Error Handling
+
+The function validates input data and throws descriptive errors for:
+- Invalid input data types
+- Missing required fields
+- Invalid configuration options
+
+Always wrap calls in try-catch blocks for production code:
+
+```javascript
+try {
+  const weatherData = processWeatherData(rawData, options);
+  // Process weather data
+} catch (error) {
+  console.error('Failed to process weather data:', error.message);
+  // Handle error appropriately
+}
+```
+
+## Testing
+
+Unit tests are available in `test/weather-processor.test.js` and can be run with:
+
+```bash
+npm test -- test/weather-processor.test.js
+```
+
+## Related Modules
+
+- `src/utils.js`: Contains utility functions used by the weather processor
+- `src/adapters/`: Contains API-specific adapters for different weather services

package/docs/best_practices.md

@@ -0,0 +1,135 @@
+# Stigmergy CLI 最佳实践规范
+
+## 项目核心理念
+
+### 核心原则
+1. **用户主导**：用户决定如何分工和协同
+2. **CLI自主**：各CLI工具自主决定调用其他工具
+3. **系统支撑**：项目只提供基础支撑和上下文传递机制
+
+## 智能路由系统规范
+
+### 基础路由功能
+智能路由系统只负责最基本的关键字识别和CLI转发，不做深度语义分析。
+
+```javascript
+// 智能路由只做最基本的关键字识别和CLI转发
+async smartRoute(userInput) {
+    const input = userInput.trim();
+    
+    // 简单的关键字匹配，不深度解析语义
+    for (const [toolName, toolInfo] of Object.entries(this.tools)) {
+        // 只检查工具名称关键字
+        if (input.toLowerCase().includes(toolName.toLowerCase())) {
+            // 提取工具后的完整指令
+            const prompt = input.replace(new RegExp(`.*${toolName}\\s*`, 'gi'), '').trim();
+            return { tool: toolName, prompt: prompt || input };
+        }
+    }
+    
+    // 默认路由到首选工具
+    return { tool: this.defaultTool, prompt: input };
+}
+```
+
+### 上下文传递机制
+系统提供标准化的上下文传递机制，确保各CLI工具能够访问共享状态。
+
+```javascript
+// 在执行CLI时传递项目上下文
+async executeCLI(toolName, prompt) {
+    // 准备环境变量传递上下文
+    const env = {
+        ...process.env,
+        STIGMERGY_CONTEXT: JSON.stringify(this.getCurrentContext()),
+        STIGMERGY_PROJECT_DIR: process.cwd(),
+        STIGMERGY_MEMORY_FILE: this.memory.globalMemoryFile
+    };
+    
+    // 执行CLI命令
+    const child = spawn(toolName, [prompt], { 
+        stdio: 'inherit', 
+        shell: true,
+        env: env
+    });
+    
+    return child;
+}
+```
+
+### 内存和状态共享
+提供全局内存管理机制，供各CLI工具读写共享状态。
+
+```javascript
+class MemoryManager {
+    // 提供全局内存文件供各CLI读写
+    async getGlobalMemory() {
+        try {
+            const data = await fs.readFile(this.globalMemoryFile, 'utf8');
+            return JSON.parse(data);
+        } catch {
+            return { interactions: [], collaborations: [] };
+        }
+    }
+    
+    async updateGlobalMemory(updateFn) {
+        const memory = await this.getGlobalMemory();
+        const updatedMemory = updateFn(memory);
+        await fs.writeFile(this.globalMemoryFile, JSON.stringify(updatedMemory, null, 2));
+        return updatedMemory;
+    }
+}
+```
+
+## 系统架构
+
+```
+用户输入 → 智能路由 → CLI工具A → (用户决定) → CLI工具B → (用户决定) → CLI工具C
+              ↓           ↓            ↓            ↓            ↓
+           上下文传递   环境变量    用户控制    环境变量    用户控制
+```
+
+## 系统提供的核心支撑
+
+### 标准化接口
+提供给各CLI的标准接口：
+
+```javascript
+// 提供给各CLI的标准接口
+const StigmergyAPI = {
+    // 获取当前上下文
+    getContext: () => this.memory.getGlobalMemory(),
+    
+    // 更新上下文
+    updateContext: (updateFn) => this.memory.updateGlobalMemory(updateFn),
+    
+    // 调用其他CLI的标准方法
+    callCLI: (toolName, prompt) => this.executeCLI(toolName, prompt),
+    
+    // 获取CLI模式信息
+    getCLIPattern: (toolName) => this.analyzer.getCLIPattern(toolName)
+};
+```
+
+### 环境变量标准化
+系统自动设置的标准环境变量：
+
+```javascript
+// 系统自动设置的标准环境变量
+const standardEnv = {
+    STIGMERGY_ENABLED: 'true',
+    STIGMERGY_VERSION: packageVersion,
+    STIGMERGY_PROJECT_DIR: process.cwd(),
+    STIGMERGY_CONTEXT_FILE: globalMemoryFile,
+    STIGMERGY_CLI_PATTERNS: cliPatternsFile,
+    STIGMERGY_TEMP_DIR: tempDir
+};
+```
+
+## 最佳实践总结
+
+1. **保持简单**：智能路由只做最基本的工具识别和转发
+2. **用户至上**：完全由用户和各CLI决定协作流程
+3. **标准支撑**：提供统一的上下文传递和状态管理机制
+4. **透明机制**：各CLI都能访问相同的上下文和历史信息
+5. **灵活扩展**：CLI可以自由决定是否调用其他工具