alemonjs 2.1.0 → 2.1.1

package/README_CONFIG.md

@@ -1,62 +1,245 @@
-# 环境变量
+## 配置相关
 
-`platform`:`string` 平台
+### 基础配置
 
-`login`:`string` 登录
-
-`LOG_PATH`:`string` log 地址
-
-`PKG_PATH`:`string` package.json 地址
+```yaml
+# === 服务器配置 ===
+port: 17117 # CBP服务器端口，快捷参数 --port
+serverPort: 18110 # 应用服务器端口（可选，仅在需要Web服务时设置）
 
-`NODE_ENV`:`development | production` 环境判断
+# === 应用配置 ===
+input: 'lib/index.js' # 应用入口文件路径，快捷参数 --input
+login: 'discord' # 登录平台标识，快捷参数 --login
+url: 'ws://127.0.0.1:17117' # CBP服务器连接地址，快捷参数 --url
+is_full_receive: false # 是否全量接收消息（用于分流处理）
 
-`CFG_PATH`: `string`
+# === CBP（Chat Bot Protocol）配置 ===
+loadBalanceStrategy: 'least-connections' # 负载均衡策略，快捷参数 --loadBalanceStrategy
+```
 
-# 配置
+### 权限管理
 
 ```yaml
-# 常规配置
-port: 17117 # 端口，快捷参数 --port
-input: 'lib/index.js' # 入口地址，快捷参数 --input
-login: 'discord' # 选择登录的平台，快捷参数 --login
-url: 'ws://127.0.0.1:17117' # 连接阿柠檬服务URL，快捷参数 --url
-is_full_receive: false # 不全量接收消息（用于分流处理）
-# 禁用设置
-disabled_text_regular: '/闭关' # 设置正则，若匹配则禁用
-disabled_selects: # 禁用事件。若匹配则禁用
-  'private.message.create': true # 禁用私聊
-disabled_user_id:
-  '1715713638': true # 若匹配则禁用
-disabled_user_key:
-  '123456': true # 多匹配则禁用
-# 重定向：把指定的文本，转为指定的内容 （禁用规则比重定向优先）
-redirect_text_regular: '^#' # 识别前缀 #
-redirect_text_target: '/' # 替换为 /
-# 映射规则
-mapping_text:
-  - regular: '/开始游戏'
-    target: '/踏入仙途'
-# ismaster 设置
+# === 主人权限设置 ===
 master_id:
-  '1715713638': true
+  '1715713638': true # 通过用户ID设置主人权限
 master_key:
-  '123456': true
-# bot 设置
+  '123456': true # 通过用户Key设置主人权限
+
+# === 机器人标识设置 ===
 bot_id:
-  '1715713638': true # 把指定 id 视为 isBot
+  '1715713638': true # 将指定用户ID标识为机器人
 bot_key:
-  '123456': true # 把指定bot kye 视为 isBot
-# 处理器
+  '123456': true # 将指定用户Key标识为机器人
+```
+
+### 消息过滤与控制
+
+```yaml
+# === 禁用控制 ===
+disabled_text_regular: '/闭关' # 文本正则匹配，若匹配则禁用所有功能
+disabled_selects: # 禁用特定事件类型
+  'private.message.create': true # 禁用私聊消息
+  'message.create': true # 禁用群组消息
+  'interaction.create': true # 禁用交互事件
+disabled_user_id: # 禁用特定用户ID
+  '1715713638': true
+disabled_user_key: # 禁用特定用户Key
+  '123456': true
+
+# === 文本重定向 ===
+redirect_text_regular: '^#' # 文本前缀匹配正则
+redirect_text_target: '/' # 将匹配的前缀替换为指定内容
+
+# === 文本映射规则 ===
+mapping_text:
+  - regular: '/开始游戏' # 匹配的文本
+    target: '/踏入仙途' # 替换成的文本
+  - regular: '/帮助'
+    target: '/help'
+```
+
+### 消息处理器配置
+
+```yaml
 processor:
-  repeated_event_time: 60000 # 过滤掉 1分钟内出现相同 MessageId 的 event
-  repeated_user_time: 1000 # 过滤掉 1秒内出现相同UserId 的 event
-# 加载子模块 (支持 array 写法)
+  repeated_event_time: 60000 # 过滤重复MessageId的时间窗口（毫秒）
+  repeated_user_time: 1000 # 过滤同一用户连续消息的时间窗口（毫秒）
+```
+
+### 模块管理
+
+```yaml
+# === 子模块配置 ===
 apps:
-  'alemonjs-openai': true
-# 模块配置, 约定。
-# 模块对应的配置名，应是模块名。
+  'alemonjs-openai': true # 启用OpenAI模块
+  'alemonjs-xianyu': true # 启用咸鱼模块
+  # 也支持数组格式
+  # - 'alemonjs-openai'
+  # - 'alemonjs-xianyu'
+
+# === 模块特定配置 ===
+# 模块配置的键名应与模块名一致
 alemonjs-openai:
   baseURL: 'https://api.deepseek.com'
-  apiKey: ''
+  apiKey: 'your-api-key-here'
   model: 'deepseek-chat'
 ```
+
+## 快捷参数
+
+启动时可使用的快捷参数：
+
+```bash
+# === 基础参数 ===
+# 指定CBP服务器端口
+node index.js --port 8080
+
+# 指定应用服务器端口
+node index.js --serverPort 3000
+
+# 指定入口文件
+node index.js --input ./lib/index.js
+
+# 指定登录平台
+node index.js --login discord
+
+# 指定CBP服务器连接地址
+node index.js --url ws://localhost:8080
+
+# === CBP相关参数 ===
+# 指定负载均衡策略
+node index.js --loadBalanceStrategy least-connections
+
+# 启用全量接收模式
+node index.js --is_full_receive true
+
+# === 组合使用示例 ===
+# 启动Discord平台，使用轮询策略，端口8080
+node index.js --login discord --loadBalanceStrategy round-robin --port 8080
+```
+
+## 配置管理工具
+
+使用 `alemonc` 命令行工具来管理配置：
+
+```bash
+# 查看帮助
+npx alemonc -h
+
+# 添加模块
+alemonc add apps alemonjs-openai alemonjs-xianyu
+
+# 移除模块
+alemonc remove apps alemonjs-openai
+
+# 设置配置项
+alemonc set login qq
+alemonc set discord.token your-token
+alemonc set loadBalanceStrategy least-connections
+
+# 删除配置项
+alemonc del discord
+
+# 获取配置项
+alemonc get login
+```
+
+## 基础环境变量
+
+`platform`:`string` - 平台标识，支持的平台类型包括：
+- `discord` - Discord平台
+- `qq` - QQ平台  
+- `telegram` - Telegram平台
+- 或其他自定义平台包名（如：`@alemonjs/xxx`）
+
+`login`:`string` - 登录标识，通常与平台名称相同或为平台的特定实例名
+
+`url`:`string` - CBP服务器连接地址，默认为 `ws://127.0.0.1:17117`
+
+`port`:`string | number` - CBP服务器端口，默认为 `17117`
+
+`serverPort`:`string | number` - 应用服务器端口（可选，仅在需要启动Web服务时设置）
+
+`is_full_receive`:`string` - 是否全量接收消息，可选值：`'true'` | `'1'` | `'false'` | `'0'`
+
+## 文件路径相关
+
+`LOG_PATH`:`string` - 日志文件存储路径
+
+`PKG_PATH`:`string` - package.json 文件路径，默认为当前工作目录下的 `package.json`
+
+`CFG_PATH`:`string` - 配置文件路径，默认为当前工作目录下的 `alemon.config.yaml`
+
+## 运行环境
+
+`NODE_ENV`:`development | production` - 环境判断，用于区分开发环境和生产环境
+
+## CBP
+
+ChatBot Protocol
+
+ALemonJS的核心通信协议，负责客户端与平台之间的消息传输和负载均衡。
+
+### 负载均衡策略
+
+```yaml
+# 负载均衡策略配置
+loadBalanceStrategy: 'least-connections' # 默认策略
+
+# 支持的策略类型：
+# - 'round-robin': 轮询算法
+# - 'least-connections': 最少连接算法（推荐）
+# - 'random': 随机算法  
+# - 'first-available': 首个可用算法
+
+# 支持的策略类型：
+# - 'round-robin': 轮询算法
+# - 'least-connections': 最少连接算法（推荐）
+# - 'random': 随机算法  
+# - 'first-available': 首个可用算法
+
+#1. **轮询算法 (round-robin)**
+#   - 按固定顺序依次分配请求
+#   - 适用于客户端处理能力相近的场景
+#   - 请求分布均匀
+
+#2. **最少连接算法 (least-connections)**
+#   - 优选当前连接数最少的客户端
+#   - 适用于客户端处理能力不同的场景
+#   - 提供最优的负载分配
+
+#3. **随机算法 (random)**
+#   - 随机选择可用客户端
+#   - 简单的概率性分布
+#   - 适用于临时测试场景
+
+#4. **首个可用算法 (first-available)**
+#   - 总是选择第一个健康的客户端
+#   - 类似主备模式
+#   - 适用于有优先级需求的场景
+```
+
+### CBP连接配置
+
+```yaml
+# CBP服务器配置
+cbp:
+  # 连接超时时间（毫秒）
+  timeout: 180000 # 3分钟
+  
+  # 重连间隔（毫秒）
+  reconnectInterval: 6000 # 6秒
+  
+  # 心跳间隔（毫秒）
+  heartbeatInterval: 18000 # 18秒
+  
+  # 健康检查间隔（毫秒）
+  healthCheckInterval: 30000 # 30秒
+  
+  # 连接认证头配置
+  headers:
+    user-agent: 'platform' # 平台标识
+    x-device-id: 'auto-generated' # 设备ID（自动生成）
+    x-full-receive: '0' # 是否全量接收：'1' 开启，'0' 关闭
+```

package/lib/cbp/connects/client.js

@@ -18,8 +18,11 @@ import { createResult } from '../../core/utils.js';
 import '../../app/hook-use-api.js';
 import '../../app/message-api.js';
 import '../../app/message-format.js';
-import { deviceId, FULL_RECEIVE_HEADER, DEVICE_ID_HEADER, USER_AGENT_HEADER, apiResolves, apiTimeouts, actionResolves, actionTimeouts, reconnectInterval } from '../processor/config.js';
+import { deviceId, reconnectInterval } from '../processor/config.js';
+import { handleApiResponse } from '../processor/api.js';
+import { handleActionResponse } from '../processor/actions.js';
 import { useHeartbeat } from './connect.js';
+import { FULL_RECEIVE_HEADER, DEVICE_ID_HEADER, USER_AGENT_HEADER } from '../core/constants.js';
 
 const cbpClient = (url, options = {}) => {
     if (global.chatbotClient) {
@@ -72,45 +75,23 @@ const cbpClient = (url, options = {}) => {
                 if (parsedMessage?.activeId) {
                     if (parsedMessage.active === 'sync') {
                         const configs = parsedMessage.payload;
-                        const env = configs.env || {};
+                        const env = configs?.env ?? {};
                         for (const key in env) {
                             process.env[key] = env[key];
                         }
                     }
                 }
                 else if (parsedMessage?.apiId) {
-                    const resolve = apiResolves.get(parsedMessage.apiId);
-                    if (resolve) {
-                        apiResolves.delete(parsedMessage.apiId);
-                        const timeout = apiTimeouts.get(parsedMessage.apiId);
-                        if (timeout) {
-                            apiTimeouts.delete(parsedMessage.apiId);
-                            clearTimeout(timeout);
-                        }
-                        if (Array.isArray(parsedMessage.payload)) {
-                            resolve(parsedMessage.payload);
-                        }
-                        else {
-                            resolve([createResult(ResultCode.Fail, '接口处理错误', null)]);
-                        }
-                    }
+                    const results = Array.isArray(parsedMessage.payload)
+                        ? parsedMessage.payload
+                        : [createResult(ResultCode.Fail, '接口处理错误', null)];
+                    handleApiResponse(parsedMessage.apiId, results);
                 }
                 else if (parsedMessage?.actionId) {
-                    const resolve = actionResolves.get(parsedMessage.actionId);
-                    if (resolve) {
-                        actionResolves.delete(parsedMessage.actionId);
-                        const timeout = actionTimeouts.get(parsedMessage.actionId);
-                        if (timeout) {
-                            actionTimeouts.delete(parsedMessage.actionId);
-                            clearTimeout(timeout);
-                        }
-                        if (Array.isArray(parsedMessage.payload)) {
-                            resolve(parsedMessage.payload);
-                        }
-                        else {
-                            resolve([createResult(ResultCode.Fail, '消费处理错误', null)]);
-                        }
-                    }
+                    const results = Array.isArray(parsedMessage.payload)
+                        ? parsedMessage.payload
+                        : [createResult(ResultCode.Fail, '消费处理错误', null)];
+                    handleActionResponse(parsedMessage.actionId, results);
                 }
                 else if (parsedMessage.name) {
                     onProcessor(parsedMessage.name, parsedMessage, parsedMessage.value);

package/lib/cbp/connects/connect.js

@@ -3,7 +3,7 @@ import 'fs';
 import 'path';
 import 'yaml';
 import '../../core/utils.js';
-import { HEARTBEAT_INTERVAL } from '../processor/config.js';
+import { TIME_CONFIG } from '../core/constants.js';
 
 const useHeartbeat = ({ ping, isConnected, terminate }) => {
     let heartbeatTimer = null;
@@ -17,7 +17,7 @@ const useHeartbeat = ({ ping, isConnected, terminate }) => {
     const callback = () => {
         if (isConnected()) {
             const diff = Date.now() - lastPong;
-            const max = HEARTBEAT_INTERVAL * 2;
+            const max = TIME_CONFIG.HEARTBEAT_INTERVAL * 2;
             if (diff > max) {
                 logger.debug({
                     code: ResultCode.Fail,
@@ -33,7 +33,7 @@ const useHeartbeat = ({ ping, isConnected, terminate }) => {
                 message: '发送 ping',
                 data: null
             });
-            heartbeatTimer = setTimeout(callback, HEARTBEAT_INTERVAL);
+            heartbeatTimer = setTimeout(callback, TIME_CONFIG.HEARTBEAT_INTERVAL);
         }
         else {
             stopHeartbeat();

package/lib/cbp/connects/platform.js

@@ -1,12 +1,13 @@
 import * as flattedJSON from 'flatted';
 import { WebSocket } from 'ws';
-import { deviceId, DEVICE_ID_HEADER, USER_AGENT_HEADER, reconnectInterval } from '../processor/config.js';
+import { deviceId, reconnectInterval } from '../processor/config.js';
 import { ResultCode } from '../../core/variable.js';
 import 'fs';
 import 'path';
 import 'yaml';
 import '../../core/utils.js';
 import { useHeartbeat } from './connect.js';
+import { DEVICE_ID_HEADER, USER_AGENT_HEADER } from '../core/constants.js';
 
 const cbpPlatform = (url, options = {
     open: () => { }

package/lib/cbp/core/connection-manager.d.ts

@@ -0,0 +1,18 @@
+import { WebSocket } from 'ws';
+export interface ConnectionState {
+    connections: Map<string, WebSocket>;
+    lastActivity: Map<string, number>;
+    metadata: Map<string, any>;
+}
+export declare const createConnectionState: () => ConnectionState;
+export declare const addConnection: (state: ConnectionState, id: string, ws: WebSocket, metadata?: any) => ConnectionState;
+export declare const removeConnection: (state: ConnectionState, id: string) => ConnectionState;
+export declare const getConnection: (state: ConnectionState, id: string) => WebSocket | undefined;
+export declare const getHealthyConnectionIds: (state: ConnectionState) => string[];
+export declare const getConnectionStats: (state: ConnectionState) => {
+    total: number;
+    healthy: number;
+    unhealthy: number;
+    lastUpdate: number;
+};
+export declare const clearAllConnections: (state: ConnectionState) => ConnectionState;

package/lib/cbp/core/connection-manager.js

@@ -0,0 +1,67 @@
+import { WebSocket } from 'ws';
+
+const createConnectionState = () => ({
+    connections: new Map(),
+    lastActivity: new Map(),
+    metadata: new Map()
+});
+const addConnection = (state, id, ws, metadata) => {
+    const newState = {
+        connections: new Map(state.connections),
+        lastActivity: new Map(state.lastActivity),
+        metadata: new Map(state.metadata)
+    };
+    newState.connections.set(id, ws);
+    newState.lastActivity.set(id, Date.now());
+    if (metadata) {
+        newState.metadata.set(id, metadata);
+    }
+    return newState;
+};
+const removeConnection = (state, id) => {
+    const newState = {
+        connections: new Map(state.connections),
+        lastActivity: new Map(state.lastActivity),
+        metadata: new Map(state.metadata)
+    };
+    const ws = newState.connections.get(id);
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.close();
+    }
+    newState.connections.delete(id);
+    newState.lastActivity.delete(id);
+    newState.metadata.delete(id);
+    return newState;
+};
+const getConnection = (state, id) => {
+    return state.connections.get(id);
+};
+const getHealthyConnectionIds = (state) => {
+    const healthyIds = [];
+    for (const [id, ws] of state.connections.entries()) {
+        if (ws.readyState === WebSocket.OPEN) {
+            healthyIds.push(id);
+        }
+    }
+    return healthyIds;
+};
+const getConnectionStats = (state) => {
+    const total = state.connections.size;
+    const healthy = getHealthyConnectionIds(state).length;
+    return {
+        total,
+        healthy,
+        unhealthy: total - healthy,
+        lastUpdate: Date.now()
+    };
+};
+const clearAllConnections = (state) => {
+    for (const ws of state.connections.values()) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.close();
+        }
+    }
+    return createConnectionState();
+};
+
+export { addConnection, clearAllConnections, createConnectionState, getConnection, getConnectionStats, getHealthyConnectionIds, removeConnection };

package/lib/cbp/core/constants.d.ts

@@ -0,0 +1,19 @@
+export declare const USER_AGENT_HEADER = "user-agent";
+export declare const DEVICE_ID_HEADER = "x-device-id";
+export declare const FULL_RECEIVE_HEADER = "x-full-receive";
+export declare const USER_AGENT_HEADER_VALUE_MAP: {
+    readonly platform: "platform";
+    readonly client: "client";
+    readonly testone: "testone";
+};
+export declare const TIME_CONFIG: {
+    readonly TIMEOUT: number;
+    readonly RECONNECT_INTERVAL: number;
+    readonly HEARTBEAT_INTERVAL: number;
+};
+export declare const HEALTH_CHECK_CONFIG: {
+    readonly INTERVAL: 30000;
+    readonly MAX_CONSECUTIVE_FAILURES: 3;
+    readonly PING_TIMEOUT: 5000;
+};
+export declare const generateUniqueId: () => string;

package/lib/cbp/core/constants.js

@@ -0,0 +1,23 @@
+const USER_AGENT_HEADER = 'user-agent';
+const DEVICE_ID_HEADER = 'x-device-id';
+const FULL_RECEIVE_HEADER = 'x-full-receive';
+const USER_AGENT_HEADER_VALUE_MAP = {
+    platform: 'platform',
+    client: 'client',
+    testone: 'testone'
+};
+const TIME_CONFIG = {
+    TIMEOUT: 1000 * 60 * 3,
+    RECONNECT_INTERVAL: 1000 * 6,
+    HEARTBEAT_INTERVAL: 1000 * 18
+};
+const HEALTH_CHECK_CONFIG = {
+    INTERVAL: 30000,
+    MAX_CONSECUTIVE_FAILURES: 3,
+    PING_TIMEOUT: 5000
+};
+const generateUniqueId = () => {
+    return Date.now().toString(36) + Math.random().toString(36).substring(2);
+};
+
+export { DEVICE_ID_HEADER, FULL_RECEIVE_HEADER, HEALTH_CHECK_CONFIG, TIME_CONFIG, USER_AGENT_HEADER, USER_AGENT_HEADER_VALUE_MAP, generateUniqueId };

package/lib/cbp/core/load-balancer.d.ts

@@ -0,0 +1,37 @@
+import { ConnectionState } from './connection-manager';
+export type LoadBalanceStrategy = 'round-robin' | 'least-connections' | 'random' | 'first-available';
+export declare const LoadBalanceStrategyEnum: {
+    readonly ROUND_ROBIN: "round-robin";
+    readonly LEAST_CONNECTIONS: "least-connections";
+    readonly RANDOM: "random";
+    readonly FIRST_AVAILABLE: "first-available";
+};
+export interface LoadBalancerState {
+    strategy: LoadBalanceStrategy;
+    roundRobinIndex: number;
+    bindingCounts: Map<string, number>;
+}
+export declare const createLoadBalancerState: (strategy?: LoadBalanceStrategy) => LoadBalancerState;
+export declare const selectByRoundRobin: (availableIds: string[], currentIndex: number) => {
+    selectedId: string | null;
+    nextIndex: number;
+};
+export declare const selectByLeastConnections: (availableIds: string[], bindingCounts: Map<string, number>) => string | null;
+export declare const selectByRandom: (availableIds: string[]) => string | null;
+export declare const selectFirstAvailable: (availableIds: string[]) => string | null;
+export declare const selectConnection: (connectionState: ConnectionState, balancerState: LoadBalancerState) => {
+    selectedId: string | null;
+    newBalancerState: LoadBalancerState;
+};
+export declare const incrementBindingCount: (balancerState: LoadBalancerState, connectionId: string) => LoadBalancerState;
+export declare const decrementBindingCount: (balancerState: LoadBalancerState, connectionId: string) => LoadBalancerState;
+export declare const getLoadBalancerStats: (balancerState: LoadBalancerState) => {
+    strategy: LoadBalanceStrategy;
+    roundRobinIndex: number;
+    totalConnections: number;
+    totalBindings: number;
+    bindingCounts: {
+        [k: string]: number;
+    };
+    lastUpdate: number;
+};