@vrs-soft/wecom-aibot-mcp 2.4.21 → 2.4.23

package/README.md

@@ -94,13 +94,31 @@ npx @vrs-soft/wecom-aibot-mcp --http-only --start
 | `--add / --delete` | Add/delete bot |
 | `--set-token [token]` | Set Auth Token (for remote deployment) |
 | `--set-token --clear` | Clear Auth Token |
-| `--debug` | Start in foreground with debug output |
-| `--http-only` | Start HTTP MCP Server only (server-side use) |
+| `--debug` | Start in foreground with debug-level logging (writes to `server.log` + stdout) |
+| `--http-only` | Deprecated; identical to `--start` |
 | `--channel-only` | Configure Channel MCP only (requires `MCP_URL`) |
 | `--clean-cache` | Clear CC registry cache |
 | `--upgrade` | Force upgrade global configs |
 | `--uninstall` | Complete uninstall |
 
+## Logs
+
+All logs are written to `~/.wecom-aibot-mcp/` as JSON Lines (one JSON object per line):
+
+| File | Producer | Levels | Rotation |
+|------|----------|--------|----------|
+| `server.log` | `--start` / `--debug` daemon | `info` always, `debug` when `--debug` | 10MB × 5 |
+| `channel.log` | `--channel` MCP proxy (per agent) | `info` always, `debug` when debug marker exists | 10MB × 5 |
+| `connection.log` | WebSocket layer (connect/disconnect/auth) | n/a | append-only |
+| `debug` (marker file) | `--debug` creates it; channel-server reads it | — | — |
+
+Quick inspection:
+
+```bash
+tail -f ~/.wecom-aibot-mcp/server.log | jq .
+grep -h '"level":"error"' ~/.wecom-aibot-mcp/server.log*
+```
+
 ## Run Modes
 
 | | Channel Mode | HTTP Mode |

package/dist/bin.js

@@ -42,11 +42,11 @@ function showHelp() {
   --setup --server --channel  本地完整安装（HTTP + Channel）
   --upgrade       强制升级全局配置（覆盖 MCP 配置、权限、skill）
   --reinstall     重新安装全局配置（删除后重新写入，保留机器人配置）
-  --start         启动 MCP Server（后台服务模式）
+  --start         启动 HTTP MCP Server（后台守护进程，日志写 server.log）
   --stop          停止 MCP Server
-  --debug         前台启动 MCP Server（日志直接输出到终端，用于调试）
-  --channel       启动 Channel MCP Proxy（stdio 代理 + SSE 唤醒）
-  --http-only     仅启动 HTTP Server（远程部署场景，不安装 Channel MCP 配置）
+  --debug         前台启动 + debug 级日志（日志同时落 server.log，stdout 实时打印）
+  --channel       启动 Channel MCP Proxy（stdio 代理 + SSE 唤醒，日志写 channel.log）
+  --http-only     仅写 HTTP-only 配置（已废弃；--start 默认就是 daemon-only 行为）
   --channel-only  仅配置 Channel MCP（本地连接远程 HTTP Server）
   --status        显示服务状态和机器人配置
   --config        重新配置默认机器人（修改 Bot ID / Secret / 目标用户）
@@ -70,8 +70,8 @@ function showHelp() {
 拆分部署（远程 HTTP + 本地 Channel）:
 
   远程服务器:
-    npx @vrs-soft/wecom-aibot-mcp --http-only --start
-    # 只启动 HTTP Server，不写入本地 MCP 配置
+    npx @vrs-soft/wecom-aibot-mcp --start
+    # 启动 HTTP Server（daemon 不会写本地 client MCP 配置）
 
   本地机器:
     MCP_URL=http://远程IP:18963 npx @vrs-soft/wecom-aibot-mcp --channel-only
@@ -96,6 +96,24 @@ MCP 配置（默认安装同时配置两种模式）:
   启动 Channel 模式（研究预览）：
     claude --dangerously-load-development-channels server:wecom-aibot-channel
 
+日志:
+
+  Daemon (HTTP MCP):
+    ~/.wecom-aibot-mcp/server.log         info 级（永久）+ debug 级（仅 --debug 时写）
+    ~/.wecom-aibot-mcp/server.log.1..5    自动滚动备份（每份 ≤10MB，共保留 5 份）
+
+  Channel MCP:
+    ~/.wecom-aibot-mcp/channel.log        info 级（永久）+ debug 级（仅 debug 模式时写）
+    ~/.wecom-aibot-mcp/channel.log.1..5   自动滚动备份
+
+  WebSocket 连接事件:
+    ~/.wecom-aibot-mcp/connection.log     专用文件（connect/disconnect/auth 事件）
+
+  Debug 标记:
+    ~/.wecom-aibot-mcp/debug              存在则启用 debug 级输出（--debug 时自动创建）
+
+  日志格式: JSON Lines，每行一个 {ts, level, msg, data?}，方便 jq/grep 检索
+
 更多信息: https://github.com/eric2877/wecom-aibot-mcp
 `);
 }
@@ -271,6 +289,10 @@ async function startMcpServerForeground(isDebug = false) {
         fs.writeFileSync(debugFile, 'true');
         console.log('[mcp] Debug 标记文件已创建');
     }
+    // 配置统一日志输出到文件（JSON Lines + 自动滚动）
+    logger.setLogFile(path.join(os.homedir(), '.wecom-aibot-mcp', 'server.log'));
+    if (isDebug)
+        logger.setDebug(true);
     // 确保 hook 已安装
     ensureHookInstalled();
     // 加载统计并清理旧日志
@@ -299,9 +321,12 @@ async function startMcpServerForeground(isDebug = false) {
     logger.log(`[mcp] 健康检查: http://127.0.0.1:${HTTP_PORT}/health`);
     logger.log(`[mcp] 微信模式：enter_headless_mode 时建立连接`);
     logger.log(`[mcp] PID: ${process.pid}`);
+    // 写入启动事件到 server.log（永久记录）
+    logger.info('daemon started', { version: VERSION, port: HTTP_PORT, protocol, pid: process.pid, debug: isDebug });
     // 退出处理
     const gracefulShutdown = () => {
         console.log('[mcp] 正在关闭...');
+        logger.info('daemon shutdown', { pid: process.pid });
         stopKeepaliveMonitor();
         stopHttpServer();
         if (fs.existsSync(PID_FILE)) {
@@ -605,7 +630,7 @@ async function main() {
                 console.log(`[setup] 如需启用 HTTPS，配置证书后重新运行 --setup --server`);
             }
             console.log('\n[setup] Server 配置完成！');
-            console.log('  启动: npx @vrs-soft/wecom-aibot-mcp --http-only --start');
+            console.log('  启动: npx @vrs-soft/wecom-aibot-mcp --start');
             console.log('\n[setup] ─── 步骤 2/2：配置企业微信机器人 ───\n');
             await addMcpConfig();
         }
@@ -675,6 +700,10 @@ async function main() {
                 fs.writeFileSync(debugFile, 'true');
             }
         }
+        // 配置统一日志输出到文件（每个 channel-server 进程都写同一份 channel.log，多进程并发追加）
+        logger.setLogFile(path.join(os.homedir(), '.wecom-aibot-mcp', 'channel.log'));
+        if (isDebug)
+            logger.setDebug(true);
         console.log('[channel] Starting Channel MCP Proxy...');
         const { startChannelServer } = await import('./channel-server.js');
         await startChannelServer();
@@ -691,7 +720,7 @@ async function main() {
     if (args.includes('--http-only') && !args.includes('--start')) {
         console.log('[mcp] HTTP-only 模式：仅启动 HTTP Server');
         console.log('[mcp] 不写入 MCP 配置（远程部署场景）');
-        console.log('[mcp] 使用 --http-only --start 启动服务');
+        console.log('[mcp] 使用 --start 启动服务');
         process.exit(0);
     }
     // --channel-only：仅配置 Channel MCP（本地连接远程 HTTP Server）

package/dist/channel-server.js

@@ -12,11 +12,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
 import { VERSION, installSkill } from './config-wizard.js';
 import { addPermissionHook, registerActiveProject, unregisterActiveProject, updateWechatModeConfig } from './project-config.js';
+import { logger } from './logger.js';
 const MCP_URL = process.env.MCP_URL || 'http://127.0.0.1:18963';
 const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN;
 // 构建带 auth 的 fetch headers
@@ -28,22 +26,14 @@ function getAuthHeaders() {
     return headers;
 }
 // Channel 日志文件
-const CHANNEL_LOG_FILE = path.join(os.homedir(), '.wecom-aibot-mcp', 'channel.log');
 /**
  * 写入 Channel 日志
+ *
+ * 默认走 logger.debug（仅 --debug 时落盘）。关键事件请直接调用 logger.info()，
+ * 它们会永久落盘到 ~/.wecom-aibot-mcp/channel.log（自动滚动）。
  */
 function logChannel(message, data) {
-    const timestamp = new Date().toISOString();
-    const logLine = `[${timestamp}] ${message}${data ? ` | ${JSON.stringify(data)}` : ''}\n`;
-    // 写入日志文件
-    try {
-        fs.appendFileSync(CHANNEL_LOG_FILE, logLine);
-    }
-    catch (err) {
-        console.error(`[channel] 日志写入失败: ${err}`);
-    }
-    // 同时输出到 stderr
-    console.error(`[channel] ${message}${data ? ` | ${JSON.stringify(data).slice(0, 200)}` : ''}`);
+    logger.debug(message, data);
 }
 // SSE 连接状态
 let sseConnected = false;
@@ -192,7 +182,7 @@ function connectSSE(ccId) {
     sseCurrentCcId = ccId;
     // SSE URL 添加 ccId 查询参数用于授权验证
     const sseUrl = ccId ? `${MCP_URL}/sse/${ccId}?ccId=${ccId}` : `${MCP_URL}/sse`;
-    logChannel('Connecting to SSE', { url: sseUrl, ccId, mcpServerReady: mcpServer ? 'yes' : 'no' });
+    logger.info('Connecting to SSE', { url: sseUrl, ccId, mcpServerReady: mcpServer ? 'yes' : 'no' });
     sseAbortController = new AbortController();
     // SSE fetch 配置：添加 keep-alive headers 确保连接稳定
     fetch(sseUrl, {
@@ -228,7 +218,7 @@ function connectSSE(ccId) {
             }
             return;
         }
-        logChannel('SSE connected, waiting for messages', { status: res.status });
+        logger.info('SSE connected', { ccId, status: res.status });
         const reader = res.body?.getReader();
         if (!reader) {
             logChannel('No response body');
@@ -250,7 +240,7 @@ function connectSSE(ccId) {
                 sseConnected = false;
                 // 非主动断开时自动重连
                 if (!sseAbortController?.signal.aborted) {
-                    logChannel('SSE 断线，3 秒后重连', { ccId });
+                    logger.info('SSE 断线，3 秒后重连', { ccId });
                     setTimeout(() => { httpSessionId = null; connectSSE(ccId); }, 3000);
                 }
                 break;
@@ -321,11 +311,11 @@ function connectSSE(ccId) {
         }
         clearInterval(heartbeatInterval);
     }).catch((err) => {
-        logChannel('SSE error', { error: String(err) });
+        logger.error('SSE error', { error: String(err) });
         sseConnected = false;
         // 非主动断开时自动重连
         if (!sseAbortController?.signal.aborted) {
-            logChannel('SSE 出错，3 秒后重连', { ccId });
+            logger.info('SSE 出错，3 秒后重连', { ccId });
             setTimeout(() => { httpSessionId = null; connectSSE(ccId); }, 3000);
         }
     });
@@ -438,7 +428,7 @@ function registerChannelTools(server) {
                 try {
                     const parsed = JSON.parse(content[0].text);
                     if (parsed.ccId) {
-                        logChannel('Got ccId, connecting SSE', { ccId: parsed.ccId, mode });
+                        logger.info('Got ccId, connecting SSE', { ccId: parsed.ccId, mode });
                         // 保存连接参数供重连复用
                         sseRobotId = robot_id || parsed.robotName;
                         sseProjectDir = project_dir || process.cwd();
@@ -446,10 +436,10 @@ function registerChannelTools(server) {
                         // Channel 模式：在本地项目写入 PermissionRequest hook
                         const localProjectDir = project_dir || process.cwd();
                         const hookResult = addPermissionHook(localProjectDir);
-                        logChannel('本地 PermissionRequest hook 已写入', { path: hookResult.path, success: hookResult.success });
+                        logger.info('本地 PermissionRequest hook 已写入', { path: hookResult.path, success: hookResult.success });
                         // 注册本地 PID → projectDir（供本地 permission-hook.sh 通过进程树匹配项目）
                         registerActiveProject(process.ppid ?? process.pid, localProjectDir);
-                        logChannel('本地 active-projects 已注册', { pid: process.ppid ?? process.pid, projectDir: localProjectDir });
+                        logger.info('本地 active-projects 已注册', { pid: process.ppid ?? process.pid, projectDir: localProjectDir });
                         // 写入本地 wecom-aibot.json（远程 HTTP MCP 写在远端 fs，agent 本地需要自己落地）
                         updateWechatModeConfig(localProjectDir, {
                             wechatMode: true,
@@ -458,10 +448,10 @@ function registerChannelTools(server) {
                             mode: parsed.mode || mode,
                             autoApproveTimeout: auto_approve_timeout,
                         });
-                        logChannel('本地 wecom-aibot.json 已写入', { projectDir: localProjectDir, robotName: parsed.robotName, ccId: parsed.ccId });
+                        logger.info('本地 wecom-aibot.json 已写入', { projectDir: localProjectDir, robotName: parsed.robotName, ccId: parsed.ccId });
                         // 安装 skill 到本地（同上）
                         const skillResult = installSkill(localProjectDir);
-                        logChannel('本地 skill 安装', { success: skillResult.success, skillUrl: skillResult.skillUrl });
+                        logger.info('本地 skill 安装', { success: skillResult.success, skillUrl: skillResult.skillUrl });
                         // Channel 模式：过滤 heartbeat 信息，简化消息
                         if (mode === 'channel' || parsed.mode === 'channel') {
                             delete parsed.heartbeat; // Channel 模式不需要 heartbeat loop
@@ -492,7 +482,7 @@ function registerChannelTools(server) {
             sseAbortController = null;
             sseConnected = false;
             sseCurrentCcId = undefined;
-            logChannel('SSE disconnected', { cc_id });
+            logger.info('SSE disconnected', { cc_id });
         }
         // 注销本地 active-projects 记录
         unregisterActiveProject(localProjectDir);

package/dist/config-wizard.js

@@ -1111,7 +1111,8 @@ export function ensureGlobalConfigs(mode = 'full', remoteOptions) {
         fs.writeFileSync(VERSION_FILE, JSON.stringify({ version: VERSION, installedAt: Date.now() }, null, 2));
         return { upgraded, previousVersion };
     }
-    // remote-channel 模式：写入远程 HTTP MCP（带 token）+ Channel MCP
+    // remote-channel 模式：远程部署的 Channel 客户端——只写 Channel MCP，不写 HTTP MCP
+    // （HTTP MCP daemon 在远端，本地不需要 HTTP transport client config）
     if (mode === 'remote-channel') {
         if (!remoteOptions?.url) {
             console.log('[config] ❌ 远程模式需要提供 URL');
@@ -1123,13 +1124,7 @@ export function ensureGlobalConfigs(mode = 'full', remoteOptions) {
         }
         if (!claudeConfig.mcpServers)
             claudeConfig.mcpServers = {};
-        // HTTP MCP 配置（带 token，可选）
-        const mcpEndpointUrl = remoteOptions.url.replace(/\/+$/, '') + '/mcp';
-        const httpMcpConfig = { type: 'http', url: mcpEndpointUrl };
-        if (remoteOptions.token)
-            httpMcpConfig.headers = { Authorization: `Bearer ${remoteOptions.token}` };
-        claudeConfig.mcpServers['wecom-aibot'] = httpMcpConfig;
-        // Channel MCP 配置（带 MCP_URL + MCP_AUTH_TOKEN）
+        // 只写 Channel MCP 配置（带 MCP_URL + MCP_AUTH_TOKEN），HTTP MCP 由远端 daemon 提供，本地无需 client 配置
         const channelEnvRemote = { MCP_URL: remoteOptions.url.replace(/\/+$/, '') };
         if (remoteOptions.token)
             channelEnvRemote.MCP_AUTH_TOKEN = remoteOptions.token;
@@ -1138,8 +1133,13 @@ export function ensureGlobalConfigs(mode = 'full', remoteOptions) {
             args: ['-y', '@vrs-soft/wecom-aibot-mcp', '--channel'],
             env: channelEnvRemote,
         };
+        // 移除可能残留的 HTTP MCP client 配置（远程模式 HTTP/Channel 完全分离）
+        if (claudeConfig.mcpServers['wecom-aibot']) {
+            delete claudeConfig.mcpServers['wecom-aibot'];
+            console.log('[config] 已移除残留的 HTTP MCP client 配置（远程模式只用 Channel）');
+        }
         fs.writeFileSync(CLAUDE_CONFIG_FILE, JSON.stringify(claudeConfig, null, 2));
-        console.log('[config] remote-channel 模式：已写入 HTTP MCP + Channel MCP 配置（带 Token）');
+        console.log('[config] remote-channel 模式：仅写入 Channel MCP 配置');
         // Channel 模式需要权限配置
         writeMcpPermissions();
         console.log('[config] 已写入权限配置到 ~/.claude/settings.local.json');
@@ -1235,19 +1235,20 @@ export async function runRemoteInstallWizard() {
             // Server 不写入 ~/.claude.json，只提示启动命令
             console.log('\n─────────────────────────────────────');
             console.log('Server 安装完成！');
-            console.log('  启动命令: npx @anthropic/wecom-aibot-mcp --http-only --start');
+            console.log('  启动命令: npx @vrs-soft/wecom-aibot-mcp --start');
             console.log('  或者:     npm run start:http');
             console.log('─────────────────────────────────────\n');
             console.log('[config] Client 端请在其他机器运行安装程序连接本服务器\n');
             return 'server';
         }
         // Client 安装模式：本机有 ~/.claude.json，作为客户端
+        // 远程模式 = HTTP/Channel 完全分离：本地只装 Client 配置，daemon 在远端
         console.log('\n检测到本机有 ~/.claude.json → Client 安装模式\n');
         console.log('  请选择连接远程服务器的方式：\n');
-        console.log('  1. 仅 HTTP MCP（轮询模式）');
-        console.log('  2. HTTP MCP + Channel MCP（推荐，消息自动唤醒）\n');
+        console.log('  1. Channel MCP（推荐：SSE 自动推送，消息到达立即唤醒 agent）');
+        console.log('  2. HTTP MCP（轮询模式，兼容不支持 Channel 的 Claude Code）\n');
         const choice = await question(rl, '请选择 (1/2): ');
-        const mode = choice === '2' ? 'remote-channel' : 'remote';
+        const mode = choice === '2' ? 'remote' : 'remote-channel';
         let serverUrl = await question(rl, '远程服务器地址（如 https://your-server:18963）: ');
         while (!serverUrl) {
             console.log('服务器地址不能为空');
@@ -1264,12 +1265,13 @@ export async function runRemoteInstallWizard() {
         ensureGlobalConfigs(mode, { url: serverUrl, token });
         console.log('\n─────────────────────────────────────');
         console.log('Client 配置完成！');
-        console.log(`  模式:       ${mode === 'remote-channel' ? 'HTTP + Channel' : '仅 HTTP'}`);
+        console.log(`  模式:       ${mode === 'remote-channel' ? 'Channel（仅 Channel MCP）' : 'HTTP（仅 HTTP MCP）'}`);
         console.log(`  服务器:     ${serverUrl}`);
         console.log(`  Auth Token: ${token.slice(0, 8)}...${token.slice(-4)}`);
         console.log('─────────────────────────────────────\n');
         if (mode === 'remote-channel') {
-            console.log('Channel 模式优势：微信消息自动唤醒 agent，无需主动轮询');
+            console.log('Channel 模式优势：微信消息通过 SSE 自动唤醒 agent，无需主动轮询');
+            console.log('启动方式：claude --dangerously-load-development-channels server:wecom-aibot-channel');
         }
         console.log('[config] 请重启 Claude Code 以加载最新配置\n');
         return mode;

package/dist/connection-manager.js

@@ -113,7 +113,7 @@ export async function connectRobot(robotName, agentName) {
         agentName,
     };
     connectionPool.set(robot.name, state);
-    logger.log(`[connection] 已连接机器人: ${robot.name}`);
+    logger.info('robot connected', { robotName: robot.name });
     return {
         success: true,
         client,
@@ -127,7 +127,7 @@ export function disconnectRobot(robotName) {
     if (state) {
         state.client.disconnect();
         connectionPool.delete(robotName);
-        logger.log(`[connection] 已断开机器人: ${robotName}`);
+        logger.info('robot disconnected', { robotName });
     }
 }
 /**
@@ -145,7 +145,7 @@ export async function getClient(robotName) {
     // 断开了，尝试重连
     const robot = await findRobotConfig(state.robotName);
     if (robot) {
-        logger.log(`[connection] 重连机器人: ${robot.name}`);
+        logger.info('robot reconnecting', { robotName: robot.name });
         const oldClient = state.client;
         // 迁移旧 client 的未解决审批记录和待发送审批消息
         const pendingApprovals = oldClient.getUnresolvedApprovalMap();
@@ -165,11 +165,11 @@ export async function getClient(robotName) {
         state.client.connect();
         const connected = await waitForConnection(state.client, 5000);
         if (connected) {
-            logger.log(`[connection] 重连成功: ${robot.name}`);
+            logger.info('robot reconnected', { robotName: robot.name });
             return state.client;
         }
         else {
-            logger.log(`[connection] 重连失败: ${robot.name}`);
+            logger.error('robot reconnect failed', { robotName: robot.name });
             return null;
         }
     }

package/dist/http-server.js

@@ -141,7 +141,7 @@ function cleanStaleCcIds() {
     for (const [id, entry] of ccIdRegistry) {
         if (now - entry.lastOnline > CCID_STALE_TIMEOUT) {
             ccIdRegistry.delete(id);
-            logger.log(`[ccid] 清理超时条目: ${id} (离线 ${Math.round((now - entry.lastOnline) / 60000)} 分钟)`);
+            logger.info('ccId stale cleanup', { ccId: id, offlineMins: Math.round((now - entry.lastOnline) / 60000) });
         }
     }
 }
@@ -150,24 +150,24 @@ function cleanStaleCcIds() {
 export function registerCcId(ccId, robotName, agentName, mode, projectDir, isReconnect) {
     if (isReconnect || ccIdRegistry.has(ccId)) {
         // 重连：直接覆盖，更新 lastOnline
-        logger.log(`[ccid] 重连: ${ccId} → ${robotName}`);
+        logger.info('ccId reconnect', { ccId, robotName });
     }
     else {
         // 首次注册：先清理超时条目
         cleanStaleCcIds();
-        logger.log(`[ccid] 注册: ${ccId} → ${robotName} (${agentName || 'unknown'}, mode: ${mode || 'http'})`);
+        logger.info('ccId registered', { ccId, robotName, agentName: agentName || null, mode: mode || 'http' });
     }
     ccIdRegistry.set(ccId, { robotName, agentName, mode, projectDir, lastOnline: Date.now() });
     return { success: true, ccId };
 }
 export function unregisterCcId(ccId) {
     ccIdRegistry.delete(ccId);
-    logger.log(`[ccid] 注销: ${ccId}`);
+    logger.info('ccId unregistered', { ccId });
 }
 export function clearCcIdRegistry() {
     const entries = Array.from(ccIdRegistry.keys());
     ccIdRegistry.clear();
-    logger.log(`[ccid] 清空注册表: 共清理 ${entries.length} 条 (${entries.join(', ')})`);
+    logger.info('ccId registry cleared', { count: entries.length, entries });
     return { cleared: entries.length, entries };
 }
 export function getRobotByCcId(ccId) {

package/dist/logger.d.ts

@@ -1,51 +1,33 @@
 /**
  * 统一日志模块
  *
- * 通过 --debug 参数控制日志输出：
- * - debug 模式：所有日志输出到 stderr
- * - 正常模式：只输出必要信息（如错误、启动消息）
+ * 级别：error / info / debug
+ * - error：永远写文件 + stderr
+ * - info：永远写文件，--debug 时也写 stdout
+ * - debug：仅 --debug 模式写文件 + stdout
  *
- * Debug 标记文件：~/.wecom-aibot-mcp/debug
+ * Debug 标记：~/.wecom-aibot-mcp/debug 文件存在 → debug 模式
  *
- * 用法与 console 完全一致：
- * - logger.log() - debug 模式才输出
- * - logger.error() - 始终输出到 stderr
- * - logger.warn() - 始终输出到 stderr
- * - logger.info() - 始终输出到 stdout
- */
-/**
- * 检查是否处于 debug 模式
+ * 文件输出：JSON Lines 格式，自动按 10MB 滚动，保留最近 5 份
+ *   <file>      当前
+ *   <file>.1    上一份
+ *   ...
+ *   <file>.5    最旧
+ *
+ * 调用方在入口处通过 setLogFile() 指定写入文件：
+ * - daemon (`--start` / `--debug`): server.log
+ * - channel-server (`--channel`):    channel.log
  */
 export declare function isDebugMode(): boolean;
-/**
- * 设置 debug 模式
- */
 export declare function setDebugMode(enabled: boolean): void;
-/**
- * 日志输出（仅 debug 模式）
- * 与 console.log 用法完全一致
- */
-export declare function log(...args: unknown[]): void;
-/**
- * 错误日志（始终输出到 stderr）
- * 与 console.error 用法完全一致
- */
-export declare function error(...args: unknown[]): void;
-/**
- * 信息日志（始终输出到 stdout）
- * 与 console.info 用法完全一致
- */
-export declare function info(...args: unknown[]): void;
-/**
- * 警告日志（始终输出到 stderr）
- * 与 console.warn 用法完全一致
- */
-export declare function warn(...args: unknown[]): void;
+export declare function setLogFile(file: string): void;
 export declare const logger: {
-    log: typeof log;
-    error: typeof error;
-    info: typeof info;
-    warn: typeof warn;
+    info: (msg: string, data?: unknown) => void;
+    debug: (msg: string, data?: unknown) => void;
+    error: (msg: string, data?: unknown) => void;
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
     isDebug: typeof isDebugMode;
     setDebug: typeof setDebugMode;
+    setLogFile: typeof setLogFile;
 };

package/dist/logger.js

@@ -1,84 +1,114 @@
 /**
  * 统一日志模块
  *
- * 通过 --debug 参数控制日志输出：
- * - debug 模式：所有日志输出到 stderr
- * - 正常模式：只输出必要信息（如错误、启动消息）
+ * 级别：error / info / debug
+ * - error：永远写文件 + stderr
+ * - info：永远写文件，--debug 时也写 stdout
+ * - debug：仅 --debug 模式写文件 + stdout
  *
- * Debug 标记文件：~/.wecom-aibot-mcp/debug
+ * Debug 标记：~/.wecom-aibot-mcp/debug 文件存在 → debug 模式
  *
- * 用法与 console 完全一致：
- * - logger.log() - debug 模式才输出
- * - logger.error() - 始终输出到 stderr
- * - logger.warn() - 始终输出到 stderr
- * - logger.info() - 始终输出到 stdout
+ * 文件输出：JSON Lines 格式，自动按 10MB 滚动，保留最近 5 份
+ *   <file>      当前
+ *   <file>.1    上一份
+ *   ...
+ *   <file>.5    最旧
+ *
+ * 调用方在入口处通过 setLogFile() 指定写入文件：
+ * - daemon (`--start` / `--debug`): server.log
+ * - channel-server (`--channel`):    channel.log
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-const DEBUG_FILE = path.join(os.homedir(), '.wecom-aibot-mcp', 'debug');
+const CONFIG_DIR = path.join(os.homedir(), '.wecom-aibot-mcp');
+const DEBUG_FILE = path.join(CONFIG_DIR, 'debug');
+const MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+const KEEP_FILES = 5;
+let logFile = null;
 let debugMode = false;
-/**
- * 检查是否处于 debug 模式
- */
 export function isDebugMode() {
     if (debugMode)
         return true;
-    // 检查标记文件
     if (fs.existsSync(DEBUG_FILE)) {
         debugMode = true;
         return true;
     }
     return false;
 }
-/**
- * 设置 debug 模式
- */
 export function setDebugMode(enabled) {
     debugMode = enabled;
     if (enabled && !fs.existsSync(DEBUG_FILE)) {
+        if (!fs.existsSync(CONFIG_DIR))
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
         fs.writeFileSync(DEBUG_FILE, 'true');
     }
     else if (!enabled && fs.existsSync(DEBUG_FILE)) {
         fs.unlinkSync(DEBUG_FILE);
     }
 }
-/**
- * 日志输出（仅 debug 模式）
- * 与 console.log 用法完全一致
- */
-export function log(...args) {
-    if (isDebugMode()) {
-        console.log(...args);
-    }
-}
-/**
- * 错误日志（始终输出到 stderr）
- * 与 console.error 用法完全一致
- */
-export function error(...args) {
-    console.error(...args);
+export function setLogFile(file) {
+    logFile = file;
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
 }
-/**
- * 信息日志（始终输出到 stdout）
- * 与 console.info 用法完全一致
- */
-export function info(...args) {
-    console.info(...args);
+function rotate(file) {
+    try {
+        for (let i = KEEP_FILES - 1; i >= 1; i--) {
+            const src = `${file}.${i}`;
+            const dst = `${file}.${i + 1}`;
+            if (fs.existsSync(src))
+                fs.renameSync(src, dst);
+        }
+        if (fs.existsSync(file))
+            fs.renameSync(file, `${file}.1`);
+    }
+    catch {
+        // 滚动失败忽略，避免阻塞日志写入
+    }
 }
-/**
- * 警告日志（始终输出到 stderr）
- * 与 console.warn 用法完全一致
- */
-export function warn(...args) {
-    console.warn(...args);
+function write(level, msg, data) {
+    if (level === 'debug' && !isDebugMode())
+        return;
+    const entry = JSON.stringify({
+        ts: new Date().toISOString(),
+        level,
+        msg,
+        ...(data !== undefined ? { data } : {}),
+    }) + '\n';
+    // 文件
+    if (logFile) {
+        try {
+            if (fs.existsSync(logFile) && fs.statSync(logFile).size >= MAX_SIZE) {
+                rotate(logFile);
+            }
+            fs.appendFileSync(logFile, entry);
+        }
+        catch {
+            // 写文件失败不抛
+        }
+    }
+    // 控制台
+    if (level === 'error') {
+        process.stderr.write(entry);
+    }
+    else if (debugMode) {
+        process.stdout.write(entry);
+    }
 }
-// 导出 logger 对象，用法与 console 完全一致
+// 公共 API
 export const logger = {
-    log,
-    error,
-    info,
-    warn,
+    info: (msg, data) => write('info', msg, data),
+    debug: (msg, data) => write('debug', msg, data),
+    error: (msg, data) => write('error', msg, data),
+    // 兼容旧 API（散落在各处的调用）
+    log: (...args) => {
+        if (debugMode)
+            console.log(...args);
+    },
+    warn: (...args) => console.warn(...args),
     isDebug: isDebugMode,
     setDebug: setDebugMode,
+    setLogFile,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrs-soft/wecom-aibot-mcp",
-  "version": "2.4.21",
+  "version": "2.4.23",
   "description": "企业微信智能机器人 MCP 服务 - Claude Code 审批通道",
   "type": "module",
   "main": "dist/index.js",