cli-claw-kit 0.0.1

package/dist/group-runtime.js

@@ -0,0 +1,35 @@
+import { resolveEffectiveHostWorkspaceCwd } from './host-workspace-cwd.js';
+export function normalizeAgentType(raw) {
+    if (raw === 'codex')
+        return 'codex';
+    return 'claude';
+}
+export function enforceAgentExecutionMode(agentType, executionMode) {
+    if (agentType === 'codex' && executionMode !== 'host') {
+        return 'Codex only supports host execution mode';
+    }
+    return null;
+}
+export function validateGroupRuntimeUpdate(options) {
+    if (options.isHome &&
+        options.nextExecutionMode !== options.currentExecutionMode) {
+        return 'Cannot change execution mode of home containers';
+    }
+    return enforceAgentExecutionMode(options.nextAgentType, options.nextExecutionMode);
+}
+export function hasRuntimeBoundaryChange(options) {
+    return (options.currentAgentType !== options.nextAgentType ||
+        options.currentExecutionMode !== options.nextExecutionMode);
+}
+export function buildEffectiveGroupFromHomeSibling(group, homeGroup) {
+    return {
+        ...group,
+        agentType: homeGroup.agentType ?? group.agentType,
+        executionMode: homeGroup.executionMode ?? group.executionMode,
+        model: homeGroup.model ?? group.model,
+        reasoningEffort: homeGroup.reasoningEffort ?? group.reasoningEffort,
+        customCwd: resolveEffectiveHostWorkspaceCwd(group, homeGroup),
+        created_by: group.created_by || homeGroup.created_by,
+        is_home: true,
+    };
+}

package/dist/host-workspace-cwd.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { LAUNCH_CWD } from './app-root.js';
+import { findAllowedRoot, loadMountAllowlist } from './mount-security.js';
+export function validateHostWorkspaceCwd(cwd, options = {}) {
+    const fieldLabel = options.fieldLabel ?? 'custom_cwd';
+    if (!path.isAbsolute(cwd)) {
+        return { error: `${fieldLabel} must be an absolute path` };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(cwd);
+    }
+    catch {
+        return { error: `${fieldLabel} directory does not exist` };
+    }
+    if (!stat.isDirectory()) {
+        return { error: `${fieldLabel} must be an existing directory` };
+    }
+    const normalizedCwd = fs.realpathSync(cwd);
+    const allowlist = options.allowlist !== undefined ? options.allowlist : loadMountAllowlist();
+    if (allowlist?.allowedRoots?.length) {
+        const allowedRoot = findAllowedRoot(normalizedCwd, allowlist.allowedRoots);
+        if (!allowedRoot) {
+            const allowedPaths = allowlist.allowedRoots
+                .map((root) => root.path)
+                .join(', ');
+            return {
+                error: `${fieldLabel} must be under an allowed root. Allowed roots: ${allowedPaths}. Check config/mount-allowlist.json`,
+            };
+        }
+    }
+    return { cwd: normalizedCwd };
+}
+export function materializeHostWorkspaceDefaultCwd(group, launchCwdOrOptions = {}, maybeOptions = {}) {
+    const options = typeof launchCwdOrOptions === 'string'
+        ? {
+            ...maybeOptions,
+            launchCwd: launchCwdOrOptions,
+        }
+        : launchCwdOrOptions;
+    if ((group.executionMode ?? 'container') !== 'host') {
+        return { group, materialized: false };
+    }
+    if (group.customCwd) {
+        const validation = validateHostWorkspaceCwd(group.customCwd, {
+            allowlist: options.allowlist,
+            fieldLabel: options.fieldLabel ?? 'custom_cwd',
+        });
+        if ('error' in validation) {
+            return validation;
+        }
+        return {
+            group: {
+                ...group,
+                customCwd: validation.cwd,
+            },
+            materialized: false,
+        };
+    }
+    const launchCwd = options.launchCwd ?? LAUNCH_CWD;
+    const validation = validateHostWorkspaceCwd(launchCwd, {
+        allowlist: options.allowlist,
+        fieldLabel: options.fieldLabel ?? 'launch cwd',
+    });
+    if ('error' in validation) {
+        return validation;
+    }
+    return {
+        group: {
+            ...group,
+            customCwd: validation.cwd,
+        },
+        materialized: true,
+    };
+}
+export function resolveEffectiveHostWorkspaceCwd(group, homeGroup) {
+    const effectiveExecutionMode = group.is_home
+        ? group.executionMode
+        : (homeGroup?.executionMode ?? group.executionMode);
+    if ((effectiveExecutionMode ?? 'container') !== 'host') {
+        return undefined;
+    }
+    return homeGroup?.customCwd || group.customCwd;
+}

package/dist/im-channel.js

@@ -0,0 +1,384 @@
+/**
+ * Unified IM Channel Interface
+ *
+ * Defines a standard interface for all IM integrations (Feishu, Telegram, etc.)
+ * and provides adapter factories that wrap existing connection implementations.
+ */
+import { createFeishuConnection, } from './feishu.js';
+import { createTelegramConnection, } from './telegram.js';
+import { createQQConnection, } from './qq.js';
+import { createWeChatConnection, } from './wechat.js';
+import { createDingTalkConnection, } from './dingtalk.js';
+import { logger } from './logger.js';
+import { StreamingCardController, } from './feishu-streaming-card.js';
+import { CHANNEL_PREFIXES } from './channel-prefixes.js';
+// ─── Channel Registry ───────────────────────────────────────────
+/** Backward-compatible registry derived from the shared CHANNEL_PREFIXES. */
+export const CHANNEL_REGISTRY = Object.fromEntries(Object.entries(CHANNEL_PREFIXES).map(([type, prefix]) => [
+    type,
+    { prefix },
+]));
+/**
+ * Determine the channel type from a JID string.
+ * Returns the matching channelType key or null if no prefix matches.
+ */
+export function getChannelType(jid) {
+    for (const [type, prefix] of Object.entries(CHANNEL_PREFIXES)) {
+        if (jid.startsWith(prefix))
+            return type;
+    }
+    return null;
+}
+/**
+ * Strip the channel prefix from a JID, returning the raw chat ID.
+ */
+export function extractChatId(jid) {
+    for (const prefix of Object.values(CHANNEL_PREFIXES)) {
+        if (jid.startsWith(prefix))
+            return jid.slice(prefix.length);
+    }
+    return jid;
+}
+// ─── Feishu Adapter ─────────────────────────────────────────────
+export function createFeishuChannel(config) {
+    let inner = null;
+    const channel = {
+        channelType: 'feishu',
+        async connect(opts) {
+            inner = createFeishuConnection(config);
+            const connected = await inner.connect({
+                onReady: opts.onReady,
+                onNewChat: opts.onNewChat,
+                ignoreMessagesBefore: opts.ignoreMessagesBefore,
+                onCommand: opts.onCommand,
+                resolveGroupFolder: opts.resolveGroupFolder,
+                resolveEffectiveChatJid: opts.resolveEffectiveChatJid,
+                onAgentMessage: opts.onAgentMessage,
+                onBotAddedToGroup: opts.onBotAddedToGroup,
+                onBotRemovedFromGroup: opts.onBotRemovedFromGroup,
+                shouldProcessGroupMessage: opts.shouldProcessGroupMessage,
+                onCardInterrupt: opts.onCardInterrupt,
+            });
+            if (!connected) {
+                inner = null;
+            }
+            return connected;
+        },
+        async disconnect() {
+            if (inner) {
+                await inner.stop();
+                inner = null;
+            }
+        },
+        async sendMessage(chatId, text, localImagePaths) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Feishu channel not connected, skip sending message');
+                return;
+            }
+            await inner.sendMessage(chatId, text, localImagePaths);
+        },
+        async sendImage(chatId, imageBuffer, mimeType, caption, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Feishu channel not connected, skip sending image');
+                return;
+            }
+            await inner.sendImage(chatId, imageBuffer, mimeType, caption, fileName);
+        },
+        async setTyping(chatId, isTyping) {
+            if (!inner)
+                return;
+            await inner.sendReaction(chatId, isTyping);
+        },
+        clearAckReaction(chatId) {
+            if (!inner)
+                return;
+            inner.clearAckReaction(chatId);
+        },
+        isConnected() {
+            return inner?.isConnected() ?? false;
+        },
+        async syncGroups() {
+            if (!inner)
+                return;
+            await inner.syncGroups();
+        },
+        async sendFile(chatId, filePath, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Feishu channel not connected, skip sending file');
+                return;
+            }
+            await inner.sendFile(chatId, filePath, fileName);
+        },
+        async getChatInfo(chatId) {
+            if (!inner)
+                return null;
+            return inner.getChatInfo(chatId);
+        },
+        createStreamingSession(chatId, onCardCreated) {
+            if (!inner)
+                return undefined;
+            const larkClient = inner.getLarkClient();
+            if (!larkClient)
+                return undefined;
+            const opts = {
+                client: larkClient,
+                chatId,
+                replyToMsgId: inner.getLastMessageId(chatId),
+                onCardCreated,
+            };
+            return new StreamingCardController(opts);
+        },
+    };
+    return channel;
+}
+// ─── Telegram Adapter ───────────────────────────────────────────
+export function createTelegramChannel(config) {
+    let inner = null;
+    // Telegram typing indicator expires after ~5s; resend every 4s while active.
+    let typingTimer = null;
+    function clearTypingTimer() {
+        if (typingTimer) {
+            clearInterval(typingTimer);
+            typingTimer = null;
+        }
+    }
+    const channel = {
+        channelType: 'telegram',
+        async connect(opts) {
+            inner = createTelegramConnection(config);
+            try {
+                await inner.connect({
+                    onReady: opts.onReady,
+                    onNewChat: opts.onNewChat,
+                    isChatAuthorized: opts.isChatAuthorized ?? (() => true),
+                    onPairAttempt: opts.onPairAttempt,
+                    onCommand: opts.onCommand,
+                    ignoreMessagesBefore: opts.ignoreMessagesBefore,
+                    resolveGroupFolder: opts.resolveGroupFolder,
+                    resolveEffectiveChatJid: opts.resolveEffectiveChatJid,
+                    onAgentMessage: opts.onAgentMessage,
+                    onBotAddedToGroup: opts.onBotAddedToGroup,
+                    onBotRemovedFromGroup: opts.onBotRemovedFromGroup,
+                });
+                return inner.isConnected();
+            }
+            catch (err) {
+                logger.error({ err }, 'Telegram channel connect failed');
+                inner = null;
+                return false;
+            }
+        },
+        async disconnect() {
+            clearTypingTimer();
+            if (inner) {
+                await inner.disconnect();
+                inner = null;
+            }
+        },
+        async sendMessage(chatId, text, localImagePaths) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Telegram channel not connected, skip sending message');
+                return;
+            }
+            await inner.sendMessage(chatId, text, localImagePaths);
+        },
+        async sendImage(chatId, imageBuffer, mimeType, caption, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Telegram channel not connected, skip sending image');
+                return;
+            }
+            await inner.sendImage(chatId, imageBuffer, mimeType, caption, fileName);
+        },
+        async sendFile(chatId, filePath, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'Telegram channel not connected, skip sending file');
+                return;
+            }
+            await inner.sendFile(chatId, filePath, fileName);
+        },
+        async setTyping(chatId, isTyping) {
+            // Always clear existing timer first
+            clearTypingTimer();
+            if (!isTyping || !inner)
+                return;
+            const sendAction = async () => {
+                if (!inner)
+                    return;
+                await inner.sendChatAction(chatId, 'typing');
+            };
+            // Send immediately, then repeat every 4s to keep indicator alive
+            void sendAction();
+            typingTimer = setInterval(() => {
+                void sendAction();
+            }, 4000);
+        },
+        isConnected() {
+            return inner?.isConnected() ?? false;
+        },
+    };
+    return channel;
+}
+// ─── QQ Adapter ─────────────────────────────────────────────────
+export function createQQChannel(config) {
+    let inner = null;
+    const channel = {
+        channelType: 'qq',
+        async connect(opts) {
+            inner = createQQConnection(config);
+            try {
+                await inner.connect({
+                    onReady: opts.onReady,
+                    onNewChat: opts.onNewChat,
+                    isChatAuthorized: opts.isChatAuthorized ?? (() => true),
+                    onPairAttempt: opts.onPairAttempt,
+                    onCommand: opts.onCommand,
+                    ignoreMessagesBefore: opts.ignoreMessagesBefore,
+                    resolveGroupFolder: opts.resolveGroupFolder,
+                    resolveEffectiveChatJid: opts.resolveEffectiveChatJid,
+                    onAgentMessage: opts.onAgentMessage,
+                });
+                return inner.isConnected();
+            }
+            catch (err) {
+                logger.error({ err }, 'QQ channel connect failed');
+                inner = null;
+                return false;
+            }
+        },
+        async disconnect() {
+            if (inner) {
+                await inner.disconnect();
+                inner = null;
+            }
+        },
+        async sendMessage(chatId, text) {
+            if (!inner) {
+                logger.warn({ chatId }, 'QQ channel not connected, skip sending message');
+                return;
+            }
+            await inner.sendMessage(chatId, text);
+        },
+        async setTyping(_chatId, _isTyping) {
+            // QQ Bot API v2 does not support typing indicators
+        },
+        isConnected() {
+            return inner?.isConnected() ?? false;
+        },
+    };
+    return channel;
+}
+// ─── WeChat Adapter ─────────────────────────────────────────────
+export function createWeChatChannel(config) {
+    let inner = null;
+    const channel = {
+        channelType: 'wechat',
+        async connect(opts) {
+            inner = createWeChatConnection(config);
+            try {
+                await inner.connect({
+                    onReady: opts.onReady,
+                    onNewChat: opts.onNewChat,
+                    onCommand: opts.onCommand,
+                    ignoreMessagesBefore: opts.ignoreMessagesBefore,
+                    resolveGroupFolder: opts.resolveGroupFolder,
+                    resolveEffectiveChatJid: opts.resolveEffectiveChatJid,
+                    onAgentMessage: opts.onAgentMessage,
+                });
+                return inner.isConnected();
+            }
+            catch (err) {
+                logger.error({ err }, 'WeChat channel connect failed');
+                inner = null;
+                return false;
+            }
+        },
+        async disconnect() {
+            if (inner) {
+                await inner.disconnect();
+                inner = null;
+            }
+        },
+        async sendMessage(chatId, text) {
+            if (!inner) {
+                logger.warn({ chatId }, 'WeChat channel not connected, skip sending message');
+                return;
+            }
+            await inner.sendMessage(chatId, text);
+        },
+        async setTyping(chatId, isTyping) {
+            if (!inner)
+                return;
+            await inner.sendTyping(chatId, isTyping);
+        },
+        isConnected() {
+            return inner?.isConnected() ?? false;
+        },
+    };
+    return channel;
+}
+// ─── DingTalk Adapter ────────────────────────────────────────────
+export function createDingTalkChannel(config) {
+    let inner = null;
+    const channel = {
+        channelType: 'dingtalk',
+        async connect(opts) {
+            inner = createDingTalkConnection(config);
+            try {
+                await inner.connect({
+                    onReady: opts.onReady,
+                    onNewChat: opts.onNewChat,
+                    isChatAuthorized: opts.isChatAuthorized ?? (() => true),
+                    onPairAttempt: opts.onPairAttempt,
+                    onCommand: opts.onCommand,
+                    ignoreMessagesBefore: opts.ignoreMessagesBefore,
+                    resolveGroupFolder: opts.resolveGroupFolder,
+                    resolveEffectiveChatJid: opts.resolveEffectiveChatJid,
+                    onAgentMessage: opts.onAgentMessage,
+                    onBotAddedToGroup: opts.onBotAddedToGroup,
+                    onBotRemovedFromGroup: opts.onBotRemovedFromGroup,
+                    shouldProcessGroupMessage: opts.shouldProcessGroupMessage,
+                });
+                return inner.isConnected();
+            }
+            catch (err) {
+                logger.error({ err }, 'DingTalk channel connect failed');
+                inner = null;
+                return false;
+            }
+        },
+        async disconnect() {
+            if (inner) {
+                await inner.disconnect();
+                inner = null;
+            }
+        },
+        async sendMessage(chatId, text) {
+            if (!inner) {
+                logger.warn({ chatId }, 'DingTalk channel not connected, skip sending message');
+                return;
+            }
+            await inner.sendMessage(chatId, text);
+        },
+        async setTyping(_chatId, _isTyping) {
+            // DingTalk Stream SDK does not support typing indicators
+        },
+        async sendImage(chatId, imageBuffer, mimeType, caption, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'DingTalk channel not connected, skip sending image');
+                return;
+            }
+            await inner.sendImage(chatId, imageBuffer, mimeType, caption, fileName);
+        },
+        async sendFile(chatId, filePath, fileName) {
+            if (!inner) {
+                logger.warn({ chatId }, 'DingTalk channel not connected, skip sending file');
+                return;
+            }
+            await inner.sendFile(chatId, filePath, fileName);
+        },
+        isConnected() {
+            return inner?.isConnected() ?? false;
+        },
+    };
+    return channel;
+}

package/dist/im-command-utils.js

@@ -0,0 +1,142 @@
+/**
+ * Pure utility functions for IM slash commands.
+ * Extracted from index.ts to enable unit testing without DB/state dependencies.
+ */
+// ─── Context Formatting ─────────────────────────────────────────
+/**
+ * Format recent messages into a compact context summary.
+ * Messages should be in chronological order (oldest first).
+ *
+ * @param messages  Array of messages (oldest first)
+ * @param maxLen    Per-message truncation length
+ * @returns         Formatted text block, or empty string if no displayable messages
+ */
+export function formatContextMessages(messages, maxLen = 80) {
+    if (messages.length === 0)
+        return '';
+    const lines = [];
+    for (const msg of messages) {
+        if (msg.sender === '__system__')
+            continue;
+        const who = msg.is_from_me ? '🤖' : `👤${msg.sender_name || ''}`;
+        let text = msg.content || '';
+        if (text.length > maxLen)
+            text = text.slice(0, maxLen) + '…';
+        text = text.replace(/\n/g, ' ');
+        lines.push(`  ${who}: ${text}`);
+    }
+    return lines.length > 0 ? '\n\n📋 最近消息:\n' + lines.join('\n') : '';
+}
+// ─── List Formatting ────────────────────────────────────────────
+/**
+ * Format workspace list with current-position markers.
+ */
+export function formatWorkspaceList(workspaces, currentFolder, currentAgentId, currentOnMain = true) {
+    if (workspaces.length === 0)
+        return '没有可用的工作区';
+    const lines = ['📂 工作区列表：'];
+    for (const ws of workspaces) {
+        const isCurrent = ws.folder === currentFolder;
+        const marker = isCurrent ? ' ▶' : '';
+        lines.push(`${marker} ${ws.name} (${ws.folder})`);
+        const mainMarker = isCurrent && currentOnMain ? ' ← 当前' : '';
+        lines.push(`  · 主对话${mainMarker}`);
+        for (const agent of ws.agents) {
+            const agentMarker = isCurrent && currentAgentId === agent.id ? ' ← 当前' : '';
+            const statusIcon = agent.status === 'running' ? '🔄' : '';
+            const shortId = agent.id.slice(0, 4);
+            lines.push(`  · ${agent.name} [${shortId}] ${statusIcon}${agentMarker}`);
+        }
+    }
+    lines.push('');
+    lines.push('💡 /sw <消息> 并行任务 · /recall 总结 · /clear 重置');
+    return lines.join('\n');
+}
+/**
+ * Resolve location info from a registered group.
+ * Pure function — all state access goes through callbacks.
+ */
+export function resolveLocationInfo(group, getRegisteredGroup, getAgent, findGroupNameByFolder) {
+    let locationLine;
+    let folder;
+    if (group.target_agent_id) {
+        const agent = getAgent(group.target_agent_id);
+        const parent = agent ? getRegisteredGroup(agent.chat_jid) : undefined;
+        const workspaceName = parent?.name || parent?.folder || group.folder;
+        locationLine = `${workspaceName} / ${agent?.name || group.target_agent_id}`;
+        folder = parent?.folder || group.folder;
+    }
+    else if (group.target_main_jid) {
+        const target = getRegisteredGroup(group.target_main_jid);
+        locationLine = `${target?.name || group.target_main_jid} / 主对话`;
+        folder = target?.folder || group.folder;
+    }
+    else {
+        const folderName = findGroupNameByFolder(group.folder);
+        locationLine = `${folderName} / 主对话`;
+        folder = group.folder;
+    }
+    const replyPolicy = group.target_main_jid || group.target_agent_id
+        ? group.reply_policy || 'source_only'
+        : null;
+    return { locationLine, folder, replyPolicy };
+}
+/**
+ * Resolve the real chat target for IM slash commands.
+ *
+ * Non-main workspaces use random web JIDs (`web:<uuid>`), so commands must not
+ * reconstruct targets from `folder`. They need the actual bound workspace JID.
+ */
+export function resolveBoundChatTarget(sourceChatJid, group, getRegisteredGroup, getAgent, findGroupNameByFolder) {
+    if (group.target_agent_id) {
+        const agent = getAgent(group.target_agent_id);
+        const parent = agent ? getRegisteredGroup(agent.chat_jid) : undefined;
+        const workspaceName = parent?.name || findGroupNameByFolder(parent?.folder || group.folder);
+        const baseChatJid = agent?.chat_jid || sourceChatJid;
+        return {
+            baseChatJid,
+            targetChatJid: `${baseChatJid}#agent:${group.target_agent_id}`,
+            folder: parent?.folder || group.folder,
+            agentId: group.target_agent_id,
+            locationLine: `${workspaceName} / ${agent?.name || group.target_agent_id}`,
+        };
+    }
+    if (group.target_main_jid) {
+        const target = getRegisteredGroup(group.target_main_jid);
+        return {
+            baseChatJid: group.target_main_jid,
+            targetChatJid: group.target_main_jid,
+            folder: target?.folder || group.folder,
+            agentId: null,
+            locationLine: `${target?.name || group.target_main_jid} / 主对话`,
+        };
+    }
+    const workspaceName = findGroupNameByFolder(group.folder);
+    return {
+        baseChatJid: sourceChatJid,
+        targetChatJid: sourceChatJid,
+        folder: group.folder,
+        agentId: null,
+        locationLine: `${workspaceName} / 主对话`,
+    };
+}
+/**
+ * Format system status output for /status command.
+ */
+export function formatSystemStatus(location, queueStatus, isActive, queuePosition) {
+    const statusText = isActive
+        ? '运行中'
+        : queuePosition !== null
+            ? `排队中 (#${queuePosition})`
+            : '空闲';
+    const lines = [
+        '📊 系统状态',
+        '━━━━━━━━━━',
+        `📍 位置: ${location.locationLine}`,
+        `⚡ 状态: ${statusText}`,
+        `📦 负载: ${queueStatus.activeContainerCount}/${queueStatus.maxContainers} 容器, ${queueStatus.activeHostProcessCount}/${queueStatus.maxHostProcesses} 进程`,
+        '',
+        '💡 /sw <消息> 并行任务 · /where 绑定 · /list 全部',
+    ];
+    return lines.join('\n');
+}

package/dist/im-downloader.js

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+import { GROUPS_DIR } from './config.js';
+export const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+export class FileTooLargeError extends Error {
+    constructor(filename, size) {
+        super(`File "${filename}" is too large: ${size} bytes (max ${MAX_FILE_SIZE} bytes)`);
+        this.name = 'FileTooLargeError';
+    }
+}
+/**
+ * 将 Buffer 写入 downloads/{channel}/{YYYY-MM-DD}/ 目录，
+ * 返回工作区相对路径（如 downloads/feishu/2026-03-01/report.pdf）。
+ * @throws FileTooLargeError 当 buffer.length > MAX_FILE_SIZE
+ */
+export async function saveDownloadedFile(groupFolder, channel, originalFilename, buffer) {
+    if (buffer.length > MAX_FILE_SIZE) {
+        throw new FileTooLargeError(originalFilename, buffer.length);
+    }
+    const dateStr = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const dir = path.join(GROUPS_DIR, groupFolder, 'downloads', channel, dateStr);
+    fs.mkdirSync(dir, { recursive: true });
+    // 安全处理：剥离目录部分，空时 fallback 为时间戳名
+    let safeName = path.basename(originalFilename).trim();
+    if (!safeName) {
+        safeName = `file_${Date.now()}`;
+    }
+    // 冲突处理：目标文件已存在时，在扩展名之前追加 _HHmmss 后缀
+    let absPath = path.join(dir, safeName);
+    if (fs.existsSync(absPath)) {
+        const now = new Date();
+        const hh = String(now.getHours()).padStart(2, '0');
+        const mm = String(now.getMinutes()).padStart(2, '0');
+        const ss = String(now.getSeconds()).padStart(2, '0');
+        const suffix = `_${hh}${mm}${ss}`;
+        const ext = path.extname(safeName);
+        const base = path.basename(safeName, ext);
+        safeName = `${base}${suffix}${ext}`;
+        absPath = path.join(dir, safeName);
+    }
+    fs.writeFileSync(absPath, buffer, { mode: 0o644 });
+    // 返回相对于群组工作区根目录的路径
+    const groupRoot = path.join(GROUPS_DIR, groupFolder);
+    return path.relative(groupRoot, absPath).replace(/\\/g, '/');
+}