evolclaw 3.1.10 → 3.1.11

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v3.1.11 (2026-06-04)
+
+### Improvements
+
+- **统一入站图片识别** — 新增 `bufferToInboundImage()`，AUN/飞书/微信共用 magic-bytes → 元数据 → 后缀判定链，消除各通道重复实现的 `detectImageMime`
+- **AUN 附件处理重构** — 抽出 `processAttachments()`，私聊/群聊统一处理；图片注入视觉通道不再追加冗余 `[文件: …]` 文本行
+- **入站去抖** — bridge 默认 inbound debounce 2s → 0（消息即处理）
+- **Windows npm 安装** — `npmInstallGlobal` 改用 `cmd /c`，消除 Node 22 的 `shell:true` 弃用警告
+
+### Bug Fixes
+
+- **截断图片缓冲** — `validateImage` 捕获 image-type 的 EndOfStreamError，避免短/截断 buffer 抛异常
+- **evolclaw-web 退出容错** — `evolclaw web` 容忍前台进程信号终止（SIGINT/SIGKILL）/非零退出，不再向用户打印堆栈
+
 ## v3.1.10 (2026-06-04)
 
 ### Bug Fixes

package/README.md

@@ -13,7 +13,6 @@ EvolClaw 是一个轻量级 AI Agent 网关系统。它为 Claude Code / Codex
 - 👥 **双模式会话**：多用户私聊会话隔离，群聊会话共享，满足不同协作场景
 - 🌐 **多渠道接入**：Channel Adapter 模式，飞书 + 微信 + 钉钉 + QQ频道 + 企业微信 + AUN 网络
 - 🤖 **Agent 间互联**：通过 AUN 网络，你的 Agent 可被其他 Agent 发现和调用
-- 🖥️ **终端 TUI 客户端**：`evolclaw tui` 直接在终端与远程 Agent 对话，无需 IM
 - 🔐 **分层权限**：三级权限体系（user/admin/owner），多用户安全隔离
 - 🛠️ **Agent 自管理**：Agent 可通过 CLI 命令自主管理运行时（查看状态、切换模型、调整配置等）
 - 📦 **项目搬家**：`evolclaw mv` 一键迁移项目目录，保留 Claude/Codex/EvolClaw 全部会话历史
@@ -29,7 +28,6 @@ EvolClaw 是一个轻量级 AI Agent 网关系统。它为 Claude Code / Codex
 
 - **通勤路上**：手机打开飞书，继续昨晚的代码 review，到公司无缝切回终端
 - **会议间隙**：微信快速问一句「这个接口的返回格式是什么」，Agent 直接查代码回复
-- **终端直连**：`evolclaw tui` 在任意终端直接与远程 Agent 对话，无需打开 IM
 - **Agent 协作**：通过 AUN 网络，让你的 Agent 被其他 Agent 调用，组成分布式协作
 - **外出离开工位**：不带电脑也能通过 IM 给 Agent 下达任务，回来看结果
 - **团队协作**：拉个飞书群，成员共享同一个 Agent 会话，一起讨论和调试
@@ -170,7 +168,6 @@ evolclaw stop       # 停止服务
 evolclaw restart    # 重启服务
 evolclaw status     # 查看状态
 evolclaw logs       # 查看日志（tail -f）
-evolclaw tui        # 启动 AUN TUI 终端客户端
 evolclaw agent      # 管理 EvolAgent（list / show / new / reload）
 evolclaw mv <old> <new>  # 项目搬家（保留全部会话）
 evolclaw diagnose   # 诊断启动环境
@@ -281,7 +278,6 @@ evolclaw/
 ## TODO
 
 - [x] AUN Mesh 网络通道接入
-- [x] TUI 终端客户端（`evolclaw tui`）
 - [x] 项目搬家工具（`evolclaw mv`）
 - [x] 手动授权支持（文本回复 + 飞书卡片）
 - [x] 自动授权可配置（自动放行/自动拒绝）

package/dist/channels/aun.js

@@ -7,7 +7,7 @@ import { logger, localTimestamp } from '../utils/logger.js';
 import { LogWriter } from '../utils/log-writer.js';
 import { normalizeChannelInstances, getChannelShowActivities } from '../utils/channel-helpers.js';
 import { resolvePaths, getPackageRoot, agentMdPath as agentMdPathFn, agentDir as agentDirPath, resolveRoot } from '../paths.js';
-import { saveToUploads, sanitizeFileName } from '../utils/media-cache.js';
+import { saveToUploads, sanitizeFileName, bufferToInboundImage } from '../utils/media-cache.js';
 import { appendAidEvent } from '../utils/instance-registry.js';
 import { appendMessageLog, buildOutboundEntry } from '../core/message/message-log.js';
 import { chatDirPath } from '../core/session/session-fs-store.js';
@@ -848,43 +848,55 @@ EvolClaw AI Agent 网关，支持多项目会话管理和多 AI 后端切换。
     }
     // ── Event handlers ──────────────────────────────────────────
     /**
-     * 判断附件是否为图片，返回 MIME 类型（非图片返回空）。
-     * 多重检测：附件元数据字段 → 文件名后缀 → 文件 magic bytes。
+     * 统一处理入站附件：下载 → 图片识别+base64 注入 → 拼接文本。
+     *
+     * - 图片：base64 注入视觉通道（不再追加 [文件: …] 文本行，避免冗余）
+     * - 非图片：拼 [文件: name → path]，并提示用 Read 工具读取
+     *
+     * @param baseText 已解析的正文（私聊 text / 群聊 strippedText）
+     * @param channelId 下载归属（私聊 fromAid / 群聊 groupId）
+     * @param preCollected 已收集的附件（群聊路径会提前 collect，避免重复）
      */
-    detectImageMime(att, filePath) {
-        const extToMime = {
-            '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-            '.gif': 'image/gif', '.webp': 'image/webp',
-        };
-        // 1. 附件元数据字段（content_type / mime_type / mimeType）
-        const metaCt = (att?.content_type || att?.mime_type || att?.mimeType || '');
-        if (typeof metaCt === 'string' && metaCt.startsWith('image/'))
-            return metaCt;
-        // 2. 文件名后缀
-        const name = (att?.filename || att?.object_key || filePath || '').toLowerCase();
-        for (const [ext, mime] of Object.entries(extToMime)) {
-            if (name.endsWith(ext))
-                return mime;
-        }
-        // 3. magic bytes
-        try {
-            const { openSync, readSync, closeSync } = require('node:fs');
-            const fd = openSync(filePath, 'r');
-            const head = Buffer.alloc(12);
-            readSync(fd, head, 0, 12, 0);
-            closeSync(fd);
-            if (head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47)
-                return 'image/png';
-            if (head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)
-                return 'image/jpeg';
-            if (head[0] === 0x47 && head[1] === 0x49 && head[2] === 0x46)
-                return 'image/gif';
-            if (head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46 &&
-                head[8] === 0x57 && head[9] === 0x45 && head[10] === 0x42 && head[11] === 0x50)
-                return 'image/webp';
-        }
-        catch { /* not readable, skip */ }
-        return '';
+    async processAttachments(payload, baseText, channelId, preCollected) {
+        const rawAttachments = preCollected ?? this.collectAllAttachments(payload);
+        const images = [];
+        let finalText = baseText;
+        if (rawAttachments.length === 0 || !this.client) {
+            return { finalText, images };
+        }
+        const fileParts = [];
+        for (const att of rawAttachments) {
+            const filePath = await this.downloadAttachment(att, channelId);
+            if (!filePath)
+                continue;
+            const name = sanitizeFileName(att.filename || att.object_key?.split('/').pop() || 'file');
+            let img = null;
+            try {
+                const { readFileSync } = await import('node:fs');
+                img = await bufferToInboundImage(readFileSync(filePath), {
+                    contentType: att.content_type, mimeType: att.mime_type, filename: name,
+                });
+            }
+            catch { /* read failed, treat as non-image file */ }
+            if (img) {
+                images.push(img);
+                // 图片已注入视觉通道，不追加 [文件: …] 文本行
+            }
+            else {
+                fileParts.push(`[文件: ${name} → ${filePath}]`);
+            }
+        }
+        const parts = [];
+        if (baseText)
+            parts.push(baseText);
+        if (fileParts.length > 0) {
+            parts.push(...fileParts);
+            parts.push('请使用 Read 工具读取文件内容。');
+        }
+        if (parts.length > 0)
+            finalText = parts.join('\n\n');
+        logger.info(`${this.logPrefix()} [attachments] count=${rawAttachments.length} images=${images.length} files=${fileParts.length}`);
+        return { finalText, images };
     }
     async downloadAttachment(att, channelId) {
         const ownerAid = att.owner_aid || this._aid || '';
@@ -974,37 +986,7 @@ EvolClaw AI Agent 网关，支持多项目会话管理和多 AI 后端切换。
             mentions.push(this._aid);
         }
         // Process attachments (顶层 + 嵌套在 merge.items / quote.quote 中的)
-        const rawAttachments = this.collectAllAttachments(payload);
-        let finalText = text;
-        const inboundImages = [];
-        if (rawAttachments.length > 0 && this.client) {
-            const fileParts = [];
-            for (const att of rawAttachments) {
-                const filePath = await this.downloadAttachment(att, fromAid);
-                if (filePath) {
-                    const name = sanitizeFileName(att.filename || att.object_key?.split('/').pop() || 'file');
-                    const mime = this.detectImageMime(att, filePath);
-                    if (mime) {
-                        try {
-                            const { readFileSync } = await import('node:fs');
-                            inboundImages.push({ data: readFileSync(filePath).toString('base64'), mimeType: mime });
-                        }
-                        catch { /* fallback to file path */ }
-                    }
-                    fileParts.push(`[文件: ${name} → ${filePath}]`);
-                }
-            }
-            if (fileParts.length > 0) {
-                const parts = [];
-                if (text)
-                    parts.push(text);
-                parts.push(...fileParts);
-                if (inboundImages.length === 0)
-                    parts.push('请使用 Read 工具读取文件内容。');
-                finalText = parts.join('\n\n');
-            }
-            logger.info(`${this.logPrefix()} [img-debug] private attachments=${rawAttachments.length} images=${inboundImages.length}`);
-        }
+        const { finalText, images: inboundImages } = await this.processAttachments(payload, text, fromAid);
         // 私聊 channelId = 对端 AID（不再读 payload.chat_id 含 device 三段式）
         // device_id 仅 SDK 内部多实例去重用，evolclaw session 层面跨端共享会话
         const chatId = fromAid;
@@ -1210,35 +1192,7 @@ EvolClaw AI Agent 网关，支持多项目会话管理和多 AI 后端切换。
             ? ['all']
             : mentionedSelf && this._aid ? [this._aid] : [];
         // Process attachments
-        let finalText = strippedText;
-        const inboundImages = [];
-        if (hasAttachments && this.client) {
-            const fileParts = [];
-            for (const att of rawAttachments) {
-                const filePath = await this.downloadAttachment(att, groupId);
-                if (filePath) {
-                    const name = sanitizeFileName(att.filename || att.object_key?.split('/').pop() || 'file');
-                    const mime = this.detectImageMime(att, filePath);
-                    if (mime) {
-                        try {
-                            const { readFileSync } = await import('node:fs');
-                            inboundImages.push({ data: readFileSync(filePath).toString('base64'), mimeType: mime });
-                        }
-                        catch { /* fallback to file path */ }
-                    }
-                    fileParts.push(`[文件: ${name} → ${filePath}]`);
-                }
-            }
-            if (fileParts.length > 0) {
-                const parts = [];
-                if (strippedText)
-                    parts.push(strippedText);
-                parts.push(...fileParts);
-                if (inboundImages.length === 0)
-                    parts.push('请使用 Read 工具读取文件内容。');
-                finalText = parts.join('\n\n');
-            }
-        }
+        const { finalText, images: inboundImages } = await this.processAttachments(payload, strippedText, groupId, rawAttachments);
         const selfAgentDir = path.join(resolvePaths().agentsDir, this.config.aid);
         const peerIdentity = await PeerIdentityCache.resolve('aun', senderAid, selfAgentDir, this.store, false);
         const shortAid = this.getShortAid(senderAid);

package/dist/channels/feishu.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import imageType from 'image-type';
-import { sanitizeFileName, saveToUploads, validateImage } from '../utils/media-cache.js';
+import { sanitizeFileName, saveToUploads, bufferToInboundImage } from '../utils/media-cache.js';
 import { logger } from '../utils/logger.js';
 import { hasRichContent, renderAllRichContent, checkDependencies } from '../utils/rich-content-renderer.js';
 import { formatItemsAsText } from '../core/message/items-formatter.js';
@@ -789,18 +789,14 @@ export class FeishuChannel {
                     logger.warn('[Feishu] Empty response from image download');
                     return null;
                 }
-                // 统一图片验证（类型白名单 + 大小限制）
-                const result = await validateImage(buffer);
-                if (result.mime === null) {
-                    logger.warn(`[Feishu] Image validation failed: ${result.reason}`);
+                // 统一图片识别 + base64 注入（magic bytes → 元数据 → 后缀）
+                const img = await bufferToInboundImage(buffer);
+                if (!img) {
+                    logger.warn('[Feishu] Image validation failed (not a supported image)');
                     return null;
                 }
-                const base64Data = buffer.toString('base64');
-                logger.debug('[Feishu] Image downloaded successfully, type:', result.mime, 'size:', base64Data.length);
-                return {
-                    data: base64Data,
-                    mimeType: result.mime
-                };
+                logger.debug('[Feishu] Image downloaded successfully, type:', img.mimeType, 'size:', img.data.length);
+                return img;
             }
             logger.error('[Feishu] Image download failed: no valid method');
             return null;

package/dist/channels/wechat.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolvePaths } from '../paths.js';
 import { logger } from '../utils/logger.js';
-import { sanitizeFileName, saveToUploads, safeFetch } from '../utils/media-cache.js';
+import { sanitizeFileName, saveToUploads, safeFetch, bufferToInboundImage } from '../utils/media-cache.js';
 import { markdownToPlainText } from '../utils/rich-content-renderer.js';
 import { formatItemsAsText } from '../core/message/items-formatter.js';
 const CHANNEL_VERSION = '1.0.0';
@@ -527,7 +527,13 @@ export class WechatChannel {
             try {
                 if (item.type === MSG_ITEM_IMAGE && item.image_item?.media) {
                     const buf = await downloadMedia(item.image_item.media, item.image_item.aeskey);
-                    images.push({ data: buf.toString('base64'), mimeType: 'image/jpeg' });
+                    // 统一图片识别：magic bytes 优先正确区分 jpeg/png/gif/webp；
+                    // 检测失败时回退到 image/jpeg（微信入站图片实际均为 jpeg，保留历史行为）。
+                    const img = await bufferToInboundImage(buf, { contentType: 'image/jpeg' });
+                    if (img)
+                        images.push(img);
+                    else
+                        logger.warn('[WeChat] Image validation failed (not a supported image)');
                 }
                 else if (item.type === MSG_ITEM_FILE && item.file_item?.media) {
                     const buf = await downloadMedia(item.file_item.media);

package/dist/cli/index.js

@@ -2127,13 +2127,27 @@ async function cmdWatchWeb() {
     }
     // Node 18.20+/20+/22 起，execFile 拒绝直接 spawn .cmd/.bat（CVE-2024-27980），必须 shell:true。
     // shell 模式下含空格的路径/参数需加引号。
+    // evolclaw-web 是前台长驻服务：用户 Ctrl-C、被新实例的单实例保护 SIGKILL、或正常退出，
+    // execFileSync 都会抛错（signal 终止时 status=null）。这些都是正常生命周期，
+    // 不应让父进程 evolclaw 带堆栈崩溃。只有真正的非信号失败才提示。
     const isBatch = /\.(cmd|bat)$/i.test(exe);
-    if (isBatch) {
-        const q = (s) => `"${s}"`;
-        execFileSync(q(exe), ['--home', q(home)], { stdio: 'inherit', shell: true });
+    try {
+        if (isBatch) {
+            const q = (s) => `"${s}"`;
+            execFileSync(q(exe), ['--home', q(home)], { stdio: 'inherit', shell: true });
+        }
+        else {
+            execFileSync(exe, ['--home', home], { stdio: 'inherit' });
+        }
     }
-    else {
-        execFileSync(exe, ['--home', home], { stdio: 'inherit' });
+    catch (e) {
+        // 信号终止（SIGINT/SIGTERM/SIGKILL）= 用户主动退出或被新实例顶替，静默返回
+        if (e?.signal)
+            return;
+        // 退出码非 0 但非信号：可能是启动失败，提示但不崩溃
+        if (typeof e?.status === 'number' && e.status !== 0) {
+            process.stderr.write(`⚠ evolclaw-web 退出（code ${e.status}）\n`);
+        }
     }
 }
 async function cmdRestartMonitor() {

package/dist/utils/media-cache.js

@@ -85,7 +85,14 @@ export async function validateImage(buffer, opts) {
     }
     // 动态导入 image-type（ESM only）
     const { default: imageType } = await import('image-type');
-    const type = await imageType(buffer);
+    // image-type 对极短/截断的 buffer 会抛 EndOfStreamError，捕获后按「无法识别」处理。
+    let type;
+    try {
+        type = await imageType(buffer);
+    }
+    catch (e) {
+        return { mime: null, reason: `Image type detection error: ${e.message}` };
+    }
     if (!type) {
         return { mime: null, reason: 'Unable to detect image type' };
     }
@@ -94,6 +101,38 @@ export async function validateImage(buffer, opts) {
     }
     return { mime: type.mime };
 }
+/**
+ * 把已下载的附件 Buffer 转成入站图片条目（供 baseagent 视觉通道）。
+ *
+ * 适用于所有「需要先下载再注入」的通道（AUN ticket 下载、未来其它 CDN 下载等）。
+ * 飞书/微信已有各自的 SDK 下载路径，可按需复用本函数统一 MIME 判定。
+ *
+ * 判定优先级：
+ *   1. magic bytes（image-type 库，最可靠，同时做大小/白名单校验）
+ *   2. 元数据 MIME 字段（att.content_type / mime_type / mimeType）
+ *   3. 文件名后缀
+ *
+ * @returns 是图片返回 InboundImage；非图片或校验失败返回 null。
+ */
+export async function bufferToInboundImage(buffer, hints) {
+    // 1. magic bytes（含大小 + 白名单校验；validateImage 已吞掉 image-type 的异常）
+    const validated = await validateImage(buffer);
+    if (validated.mime) {
+        return { data: buffer.toString('base64'), mimeType: validated.mime };
+    }
+    // 2/3. magic bytes 未识别时，回退到元数据字段 / 文件名后缀
+    //      （仍受 image 白名单约束，避免把任意文件当图片注入）
+    const metaCt = hints?.contentType || hints?.mimeType || '';
+    const byMeta = typeof metaCt === 'string' && ALLOWED_IMAGE_MIMES.has(metaCt) ? metaCt : '';
+    const byExt = hints?.filename
+        ? (ALLOWED_IMAGE_MIMES.has(guessMime(hints.filename)) ? guessMime(hints.filename) : '')
+        : '';
+    const fallback = byMeta || byExt;
+    if (fallback && buffer.length > 0 && buffer.length <= DEFAULT_MAX_IMAGE_SIZE) {
+        return { data: buffer.toString('base64'), mimeType: fallback };
+    }
+    return null;
+}
 /**
  * 保存 Buffer 到 uploads 目录
  * - 自动创建目录

package/dist/utils/npm-ops.js

@@ -15,10 +15,20 @@ import { isWindows } from './cross-platform.js';
 const execFileAsync = promisify(execFile);
 // ── npm install -g (shared) ────────────────────────────────────────────────
 export async function npmInstallGlobal(pkg) {
-    const npmCmd = isWindows ? 'npm.cmd' : 'npm';
-    const execOpts = { timeout: 180000, shell: isWindows };
+    let cmd;
+    let args;
+    // Windows: run via cmd /c to avoid shell:true deprecation warning on Node 22.
+    // Unix: npm directly, no shell needed.
+    if (isWindows) {
+        cmd = 'cmd';
+        args = ['/c', 'npm', 'install', '-g', pkg];
+    }
+    else {
+        cmd = 'npm';
+        args = ['install', '-g', pkg];
+    }
     try {
-        await execFileAsync(npmCmd, ['install', '-g', pkg], execOpts);
+        await execFileAsync(cmd, args, { timeout: 180000 });
     }
     catch (e) {
         if (e.stderr?.includes('EACCES') || e.message?.includes('EACCES')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolclaw",
-  "version": "3.1.10",
+  "version": "3.1.11",
   "description": "Lightweight AI Agent gateway connecting Claude Agent SDK to messaging channels (Feishu, ACP) with multi-project session management",
   "type": "module",
   "main": "dist/index.js",