evolcore 0.0.1 → 0.0.2

package/dist/aun/msg/history.js

@@ -0,0 +1,123 @@
+import path from 'path';
+import { isValidAid } from '../aid/identity.js';
+import { isTransientProtocolMessage, messageLogPath } from '../../core/message/message-log.js';
+import { chatDirPath, readAllJsonlLines, readJsonFile, readLastJsonlLine } from '../../core/session/session-fs-store.js';
+import { resolvePaths } from '../../paths.js';
+const DEFAULT_LIMIT = 50;
+export const MAX_MSG_HISTORY_LIMIT = 500;
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+export function msgHistory(args, options = {}) {
+    if (!isValidAid(args.from)) {
+        return error('INVALID_SELF_AID', `无效 self AID: ${args.from}`);
+    }
+    if (!isValidAid(args.target)) {
+        return error('INVALID_TARGET_AID', `无效 target AID: ${args.target}`);
+    }
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_MSG_HISTORY_LIMIT) {
+        return error('INVALID_LIMIT', `limit 必须是 1-${MAX_MSG_HISTORY_LIMIT} 的整数`);
+    }
+    const direction = args.direction ?? 'all';
+    if (direction !== 'in' && direction !== 'out' && direction !== 'all') {
+        return error('INVALID_DIRECTION', `direction 仅支持 in|out|all: ${String(args.direction)}`);
+    }
+    if (args.before !== undefined && (!Number.isFinite(args.before) || args.before < 0)) {
+        return error('INVALID_BEFORE', 'before 必须是有效时间');
+    }
+    if (args.after !== undefined && (!Number.isFinite(args.after) || args.after < 0)) {
+        return error('INVALID_AFTER', 'after 必须是有效时间');
+    }
+    if (args.before !== undefined && args.after !== undefined && args.after >= args.before) {
+        return error('INVALID_TIME_RANGE', 'after 必须早于 before');
+    }
+    const sessionsDir = options.sessionsDir ?? resolvePaths().sessionsDir;
+    const chatDir = chatDirPath(sessionsDir, 'aun', args.target, args.from);
+    const resolvedSession = resolveSessionFilter(chatDir, args.from, args.target, args.session ?? 'latest');
+    if (!resolvedSession.ok)
+        return resolvedSession;
+    let entries;
+    try {
+        entries = readAllJsonlLines(messageLogPath(chatDir));
+    }
+    catch (cause) {
+        return error('HISTORY_READ_FAILED', cause instanceof Error ? cause.message : String(cause));
+    }
+    const messages = entries
+        .filter(entry => isMessageLogEntry(entry))
+        .filter(entry => !isTransientProtocolMessage(entry))
+        .filter(entry => resolvedSession.sessionId === undefined || entry.sessionId === resolvedSession.sessionId)
+        .filter(entry => direction === 'all' || entry.dir === direction)
+        .filter(entry => args.after === undefined || entry.ts > args.after)
+        .filter(entry => args.before === undefined || entry.ts < args.before)
+        .sort((left, right) => left.ts - right.ts)
+        .slice(-limit);
+    return {
+        ok: true,
+        self_aid: args.from,
+        target_aid: args.target,
+        session_id: resolvedSession.sessionId,
+        count: messages.length,
+        messages,
+    };
+}
+function resolveSessionFilter(chatDir, selfAid, targetAid, requested) {
+    if (requested === 'all')
+        return { ok: true };
+    if (requested === 'latest') {
+        const active = readJsonFile(path.join(chatDir, 'active.json'));
+        if (!active?.id) {
+            return error('LATEST_SESSION_NOT_FOUND', '该 AID 对暂无最新会话');
+        }
+        if (!sessionBelongsToPair(active, selfAid, targetAid)) {
+            return error('SESSION_SCOPE_MISMATCH', 'active.json 不属于指定 AID 对');
+        }
+        return { ok: true, sessionId: active.id };
+    }
+    if (!SESSION_ID_RE.test(requested)) {
+        return error('INVALID_SESSION_ID', `无效 session ID: ${requested}`);
+    }
+    const active = readJsonFile(path.join(chatDir, 'active.json'));
+    if (active?.id === requested) {
+        if (!sessionBelongsToPair(active, selfAid, targetAid)) {
+            return error('SESSION_SCOPE_MISMATCH', '指定会话不属于该 AID 对');
+        }
+        return { ok: true, sessionId: requested };
+    }
+    for (const sessionPath of [
+        path.join(chatDir, `${requested}.jsonl`),
+        path.join(chatDir, '_threads', `${requested}.jsonl`),
+    ]) {
+        const session = readLastJsonlLine(sessionPath);
+        if (!session || session.id !== requested)
+            continue;
+        if (!sessionBelongsToPair(session, selfAid, targetAid)) {
+            return error('SESSION_SCOPE_MISMATCH', '指定会话不属于该 AID 对');
+        }
+        return { ok: true, sessionId: requested };
+    }
+    return error('SESSION_NOT_FOUND', `在该 AID 对中找不到会话: ${requested}`);
+}
+function sessionBelongsToPair(session, selfAid, targetAid) {
+    if (session.channelType && session.channelType !== 'aun')
+        return false;
+    if (session.channelId && session.channelId !== targetAid)
+        return false;
+    const storedSelfAid = session.selfAID ?? session.selfId;
+    if (storedSelfAid && storedSelfAid !== selfAid)
+        return false;
+    return true;
+}
+function isMessageLogEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return Number.isFinite(entry.ts)
+        && (entry.dir === 'in' || entry.dir === 'out')
+        && typeof entry.from === 'string'
+        && typeof entry.to === 'string'
+        && typeof entry.content === 'string'
+        && typeof entry.msgType === 'string';
+}
+function error(code, message) {
+    return { ok: false, code, error: message };
+}

package/dist/aun/msg/index.js

@@ -0,0 +1,5 @@
+export { msgSend, msgPull, msgAck, msgRecall, msgOnline, } from './p2p.js';
+export { msgHistory, MAX_MSG_HISTORY_LIMIT } from './history.js';
+export { groupSend, groupPull, groupAck, groupCreate, groupInfo, groupList, groupUpdate, groupDissolve, groupSuspend, groupResume, groupJoin, groupLeave, groupInvite, groupKick, groupMembers, groupOnline, groupSetRole, groupTransferOwner, groupBan, groupUnban, groupBanlist, groupRules, groupUpdateRules, groupRulesFileGet, groupRulesFileSet, groupRulesFilePublish, } from './group.js';
+export { uploadFileAndBuildPayload } from './upload.js';
+export { inferPayloadType, isValidPayloadType } from './payload-type.js';

package/dist/aun/msg/p2p.js

@@ -0,0 +1,393 @@
+import fs from 'fs';
+import path from 'path';
+import { createShortConnection } from '../rpc/index.js';
+import { getAidStore, SLOT } from '../aid/store.js';
+import { uploadFileAndBuildPayload } from './upload.js';
+import { appendMessageLog, buildOutboundEntry, classifyAunPayloadForLog } from '../../core/message/message-log.js';
+import { readBestTaskRuntimeContext, runtimeRefMessageIdForMsgSend } from '../../cli/task-context.js';
+import { chatDirPath } from '../../core/session/session-fs-store.js';
+import { resolvePaths } from '../../paths.js';
+import { ipcQuery } from '../../ipc.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../../core/auth/agent-delegation.js';
+const DEFAULT_TASK_EXECUTION_MS = 60 * 60 * 1000;
+const DAEMON_SEND_TIMEOUT_GRACE_MS = 10_000;
+const MAX_TIMER_MS = 2_147_483_647;
+export function daemonTaskSendIpcTimeoutMs(file = false) {
+    let executionMs = DEFAULT_TASK_EXECUTION_MS;
+    try {
+        const config = JSON.parse(fs.readFileSync(resolvePaths().daemonConfig, 'utf8'));
+        const seconds = config.idleMonitor?.maxExecutionTime;
+        if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0) {
+            executionMs = seconds * 1000;
+        }
+    }
+    catch { }
+    return Math.min(MAX_TIMER_MS, Math.max(file ? 120_000 : 5_000, executionMs + DAEMON_SEND_TIMEOUT_GRACE_MS));
+}
+function buildSimplePayload(body) {
+    switch (body.mode) {
+        case 'text':
+            return { type: 'text', text: body.text };
+        case 'payload':
+            return { ...body.payload };
+        case 'link': {
+            const payload = { type: 'link', url: body.url };
+            if (body.title)
+                payload.title = body.title;
+            if (body.description)
+                payload.description = body.description;
+            return payload;
+        }
+    }
+}
+function messageLogContent(body) {
+    return body.mode === 'text' ? body.text
+        : body.mode === 'link' ? `[link] ${body.url}`
+            : body.mode === 'file' ? `[file] ${body.filePath}`
+                : `[payload]`;
+}
+function applyRoutingPayloadFields(payload, args, runtimeContext, includeRuntimeRef = true) {
+    const threadId = msgSendThreadId(args, payload, runtimeContext);
+    if (threadId && !payload.thread_id)
+        payload.thread_id = threadId;
+    if (!includeRuntimeRef)
+        return;
+    const refMessageId = runtimeRefMessageIdForMsgSend({ from: args.from, runtime: runtimeContext });
+    if (refMessageId && !payload.ref_message_id)
+        payload.ref_message_id = refMessageId;
+}
+function msgSendThreadId(args, payload, runtimeContext) {
+    const payloadThreadId = typeof payload?.thread_id === 'string' && payload.thread_id.trim()
+        ? payload.thread_id.trim()
+        : undefined;
+    const currentThreadId = runtimeContext?.channel === 'aun'
+        && runtimeContext.chatType === 'private'
+        && runtimeContext.selfAid === args.from
+        && runtimeContext.channelId === args.to
+        ? runtimeContext.threadId
+        : undefined;
+    return payloadThreadId || args.thread || currentThreadId;
+}
+function msgSendLogMetadata(args, payload, runtimeContext) {
+    const isInSession = !!process.env.EVOLCORE_SESSION_ID || !!runtimeContext;
+    const source = isInSession ? 'msg' : 'cli';
+    const classified = payload === undefined ? undefined : classifyAunPayloadForLog(payload);
+    const threadId = msgSendThreadId(args, payload && typeof payload === 'object' ? payload : undefined, runtimeContext);
+    const sessionId = runtimeContext?.channel === 'aun'
+        && runtimeContext.chatType === 'private'
+        && runtimeContext.selfAid === args.from
+        && runtimeContext.peerId === args.to
+        ? runtimeContext.sessionId
+        : undefined;
+    return {
+        content: classified?.content ?? messageLogContent(args.body),
+        sessionId,
+        threadId: threadId || null,
+        msgType: classified?.msgType,
+        payloadType: classified?.payloadType,
+        payloadSummary: classified?.payloadSummary,
+        source,
+    };
+}
+async function tryDaemonMsgSend(args, payload, runtimeContext, file) {
+    const delegatedTask = !!process.env.EVOLCORE_SESSION_ID
+        || !!process.env[AGENT_DELEGATION_TOKEN_ENV];
+    if (!runtimeContext) {
+        return delegatedTask
+            ? { ok: false, code: 'DELEGATION_REQUIRED', error: 'Task runtime context is unavailable' }
+            : null;
+    }
+    if (!runtimeContext.selfAid || runtimeContext.selfAid !== args.from) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task sender does not match the delegated agent' };
+    }
+    if (!runtimeContext.sessionId || !runtimeContext.messageId) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task runtime context is incomplete' };
+    }
+    if (args.slotId || args.aunPath) {
+        return { ok: false, code: 'INVALID_DELEGATION', error: 'Task sends cannot override the daemon AUN connection' };
+    }
+    const thread = msgSendThreadId(args, payload, runtimeContext);
+    const response = await ipcQuery(resolvePaths().socket, {
+        type: 'aun-msg-send',
+        aid: args.from,
+        to: args.to,
+        scope: 'msg',
+        ...(payload ? { payload } : { file }),
+        encrypt: args.encrypt === true,
+        thread,
+        returnPolicy: args.returnPolicy,
+        originSessionId: runtimeContext.sessionId,
+        originMessageId: runtimeContext.messageId,
+        delegationToken: process.env[AGENT_DELEGATION_TOKEN_ENV],
+        log: msgSendLogMetadata(args, payload, runtimeContext),
+    }, daemonTaskSendIpcTimeoutMs(!!file));
+    return response ?? {
+        ok: false,
+        code: 'AUN_DAEMON_UNAVAILABLE',
+        error: 'EvolCore daemon did not complete the delegated AUN send',
+    };
+}
+async function daemonMsgSendResult(args, payload, runtimeContext, daemonResult) {
+    if (!daemonResult.ok) {
+        return {
+            ok: false,
+            error: daemonResult.error || 'daemon AUN message send failed',
+            code: daemonResult.code,
+            handoff_id: daemonResult.handoff_id,
+            target_session_id: daemonResult.target_session_id,
+        };
+    }
+    if (!daemonResult.message_id && !daemonResult.handoff_id) {
+        return { ok: false, error: 'daemon AUN message send returned no message_id' };
+    }
+    const sent = {
+        ok: true,
+        message_id: daemonResult.message_id || daemonResult.handoff_id || '',
+        handoff_id: daemonResult.handoff_id,
+        target_session_id: daemonResult.target_session_id,
+        seq: daemonResult.seq,
+        timestamp: daemonResult.timestamp,
+        status: daemonResult.status,
+        delivery_mode: daemonResult.delivery_mode,
+    };
+    if (!daemonResult.handoff_id && !daemonResult.log_written) {
+        await appendMsgSendOutboundLog(args, sent, {
+            payload,
+            runtimeContext,
+            chatmode: daemonResult.chatmode,
+            encrypt: daemonResult.encrypt ?? args.encrypt === true,
+        });
+    }
+    return sent;
+}
+async function appendMsgSendOutboundLog(args, result, opts) {
+    const sessionsDir = resolvePaths().sessionsDir;
+    const chatDir = chatDirPath(sessionsDir, 'aun', args.to, args.from);
+    const log = msgSendLogMetadata(args, opts.payload, opts.runtimeContext);
+    fs.mkdirSync(chatDir, { recursive: true });
+    appendMessageLog(chatDir, buildOutboundEntry({
+        from: args.from,
+        to: args.to,
+        sessionId: log.sessionId,
+        threadId: log.threadId,
+        chatType: 'private',
+        msgId: result.message_id,
+        content: log.content,
+        encrypt: opts.encrypt === true,
+        chatmode: opts.chatmode,
+        msgType: log.msgType,
+        payloadType: log.payloadType,
+        payloadSummary: log.payloadSummary,
+        source: log.source,
+    }));
+    // 通知 daemon 更新 stats（如果 daemon 在运行）
+    try {
+        await ipcQuery(resolvePaths().socket, {
+            type: 'aun-aid-stats-record-outbound',
+            aid: args.from,
+            toPeer: args.to,
+            text: log.content,
+            encrypt: opts.encrypt === true,
+            chatmode: opts.chatmode,
+        }, 1000);
+    }
+    catch { /* daemon 不在或 IPC 失败都忽略 */ }
+}
+export async function msgSend(args) {
+    const runtimeContext = await readBestTaskRuntimeContext();
+    let conn;
+    try {
+        let payload;
+        if (args.body.mode !== 'file') {
+            payload = buildSimplePayload(args.body);
+            applyRoutingPayloadFields(payload, args, runtimeContext, false);
+            const daemonResult = await tryDaemonMsgSend(args, payload, runtimeContext);
+            if (daemonResult)
+                return daemonMsgSendResult(args, payload, runtimeContext, daemonResult);
+        }
+        else {
+            const daemonResult = await tryDaemonMsgSend(args, undefined, runtimeContext, {
+                filePath: path.resolve(args.body.filePath),
+                as: args.body.as,
+                contentType: args.body.contentType,
+                text: args.body.text,
+                transcript: args.body.transcript,
+            });
+            if (daemonResult) {
+                return daemonMsgSendResult(args, { type: args.body.as || 'file' }, runtimeContext, daemonResult);
+            }
+        }
+        conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+        if (args.body.mode === 'file') {
+            const built = await uploadFileAndBuildPayload(conn, args.from, args.body.filePath, {
+                as: args.body.as,
+                contentType: args.body.contentType,
+                text: args.body.text,
+                transcript: args.body.transcript,
+                onProgress: args.onUploadProgress,
+            });
+            payload = built.payload;
+            applyRoutingPayloadFields(payload, args, runtimeContext, false);
+            const daemonResult = await tryDaemonMsgSend(args, payload, runtimeContext);
+            if (daemonResult)
+                return daemonMsgSendResult(args, payload, runtimeContext, daemonResult);
+        }
+        // 1. 解析对端身份（30天缓存）。身份解析走 HTTP+PKI（store），与发消息的短连接无关。
+        const { agentsDir } = resolvePaths();
+        const selfAgentDir = path.join(agentsDir, args.from);
+        const { PeerIdentityCache } = await import('../../core/relation/peer-identity.js');
+        const idStore = await getAidStore({ slotId: args.slotId ?? SLOT.cli, aunPath: args.aunPath });
+        let peerIdentity;
+        try {
+            peerIdentity = await PeerIdentityCache.resolve('aun', args.to, selfAgentDir, idStore, false);
+        }
+        finally {
+            try {
+                idStore.close();
+            }
+            catch { /* ignore */ }
+        }
+        // 2. 决定 chatmode（遵循来源1-3）
+        // 私聊：非 human 对端 → proactive，human 对端 → interactive
+        const chatmode = peerIdentity.isAgent ? 'proactive' : 'interactive';
+        // 3. 构建 payload
+        if (!payload) {
+            payload = buildSimplePayload(args.body);
+        }
+        // 4. 写入 payload.chatmode
+        payload.chatmode = chatmode;
+        // 5. 写入 payload.thread_id/ref_message_id（如果指定）
+        applyRoutingPayloadFields(payload, args, runtimeContext, false);
+        applyRoutingPayloadFields(payload, args, runtimeContext);
+        const sendParams = { to: args.to, payload };
+        // Default: plaintext. Set encrypt: true to enable E2EE.
+        sendParams.encrypt = args.encrypt === true;
+        const result = await conn.call('message.send', sendParams);
+        // 5. 写出方向 jsonl（与 daemon 一致格式，标记 source）
+        // source 标记：
+        // - 'cli': 用户手动调用 ec msg send
+        // - 'msg': agent 在会话中调用 ec msg send
+        if (result?.message_id) {
+            try {
+                await appendMsgSendOutboundLog(args, { ok: true, message_id: result.message_id }, {
+                    payload,
+                    runtimeContext,
+                    chatmode,
+                    encrypt: args.encrypt === true,
+                });
+            }
+            catch { }
+        }
+        return {
+            ok: true,
+            message_id: result?.message_id,
+            seq: result?.seq,
+            timestamp: result?.timestamp,
+            status: result?.status,
+            delivery_mode: result?.delivery_mode,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        if (conn)
+            await conn.close();
+    }
+}
+export async function msgPull(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const params = {};
+        if (args.afterSeq !== undefined)
+            params.after_seq = args.afterSeq;
+        if (args.limit !== undefined)
+            params.limit = args.limit;
+        const result = await conn.call('message.pull', params);
+        return {
+            ok: true,
+            messages: result?.messages ?? [],
+            count: result?.count ?? 0,
+            latest_seq: result?.latest_seq ?? 0,
+            earliest_available_seq: result?.earliest_available_seq ?? null,
+            ephemeral_earliest_available_seq: result?.ephemeral_earliest_available_seq ?? null,
+            ephemeral_dropped_count: result?.ephemeral_dropped_count ?? 0,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function msgAck(args) {
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('message.ack', { seq: args.seq });
+        return {
+            ok: true,
+            ack_seq: result?.ack_seq ?? args.seq,
+            event_published: result?.event_published,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function msgRecall(args) {
+    if (args.messageIds.length === 0) {
+        return { ok: false, error: 'message_ids 不能为空' };
+    }
+    if (args.messageIds.length > 100) {
+        return { ok: false, error: 'message_ids 最多 100 个' };
+    }
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('message.recall', { message_ids: args.messageIds });
+        return {
+            ok: true,
+            accepted: result?.accepted ?? 0,
+            recalled: result?.recalled ?? 0,
+            errors: result?.errors ?? null,
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+export async function msgOnline(args) {
+    if (args.targets.length === 0) {
+        return { ok: false, error: '查询目标不能为空' };
+    }
+    if (args.targets.length > 100) {
+        return { ok: false, error: '一次最多查询 100 个 AID' };
+    }
+    const conn = await createShortConnection(args.from, { aunPath: args.aunPath, slotId: args.slotId });
+    try {
+        const result = await conn.call('message.query_online', { aids: args.targets });
+        return {
+            ok: true,
+            online: result?.online ?? {},
+        };
+    }
+    catch (e) {
+        return formatRpcError(e);
+    }
+    finally {
+        await conn.close();
+    }
+}
+// ==================== Internal ====================
+function formatRpcError(e) {
+    if (e?.code !== undefined && e?.message !== undefined) {
+        return { ok: false, error: String(e.message), code: e.code };
+    }
+    return { ok: false, error: String(e?.message ?? e) };
+}

package/dist/aun/msg/payload-type.js

@@ -0,0 +1,27 @@
+import path from 'path';
+const EXT_TYPE_MAP = {
+    // image
+    '.png': 'image', '.jpg': 'image', '.jpeg': 'image',
+    '.gif': 'image', '.webp': 'image', '.svg': 'image',
+    '.bmp': 'image', '.heic': 'image', '.heif': 'image',
+    // video
+    '.mp4': 'video', '.mov': 'video', '.webm': 'video',
+    '.avi': 'video', '.mkv': 'video', '.m4v': 'video',
+    // voice
+    '.opus': 'voice', '.mp3': 'voice', '.aac': 'voice',
+    '.m4a': 'voice', '.wav': 'voice', '.flac': 'voice', '.ogg': 'voice',
+};
+/**
+ * 按扩展名推断 payload.type。
+ * 未识别的扩展名归类为 'file'。
+ */
+export function inferPayloadType(filename) {
+    const ext = path.extname(filename).toLowerCase();
+    return EXT_TYPE_MAP[ext] ?? 'file';
+}
+/**
+ * 校验显式传入的 --as 值。
+ */
+export function isValidPayloadType(value) {
+    return value === 'image' || value === 'video' || value === 'voice' || value === 'file';
+}

package/dist/aun/msg/upload.js

@@ -0,0 +1,137 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { guessMime, formatSize } from '../../utils/media-cache.js';
+import { inferPayloadType, isValidPayloadType } from './payload-type.js';
+/** 单次上传最大大小（与 daemon sendFile 一致）。 */
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+/** server 端 inline 上限错误的识别特征。优先匹配错误消息里的“inline 上限”字样。 */
+function isInlineLimitError(err) {
+    const msg = err?.message ?? '';
+    return /inline\s*上限|inline limit|create_upload_session/i.test(msg);
+}
+/**
+ * 上传本地文件并构造发送用的 payload。
+ *
+ * 策略：先无脑 storage.put_object（内联 base64）。server 报“超过 inline 上限”
+ * 时降级到 storage.create_upload_session + HTTP PUT + storage.complete_upload，
+ * 此时通过 onProgress 上报字节级进度。
+ */
+export async function uploadFileAndBuildPayload(conn, ownerAid, filePath, opts) {
+    const absPath = path.resolve(filePath);
+    if (!fs.existsSync(absPath)) {
+        throw new Error(`文件不存在: ${absPath}`);
+    }
+    const stat = fs.statSync(absPath);
+    if (stat.size === 0) {
+        throw new Error(`文件为空: ${absPath}`);
+    }
+    if (stat.size > MAX_FILE_SIZE) {
+        throw new Error(`文件过大 (${formatSize(stat.size)}, 上限 ${formatSize(MAX_FILE_SIZE)}): ${absPath}`);
+    }
+    const filename = path.basename(absPath);
+    const fileData = fs.readFileSync(absPath);
+    const sha256 = crypto.createHash('sha256').update(fileData).digest('hex');
+    const contentType = opts?.contentType ?? guessMime(filename);
+    const objectKey = `shared/${crypto.randomUUID()}/${filename}`;
+    const total = stat.size;
+    const report = (phase, bytes) => opts?.onProgress?.({ phase, bytes, total });
+    // 1. 先按 inline 走
+    let inlineRejected = false;
+    try {
+        report('inline', 0);
+        await conn.call('storage.put_object', {
+            object_key: objectKey,
+            content: fileData.toString('base64'),
+            content_type: contentType,
+            is_private: false,
+            overwrite: true,
+        });
+        report('inline', total);
+    }
+    catch (e) {
+        if (!isInlineLimitError(e))
+            throw e;
+        inlineRejected = true;
+    }
+    // 2. inline 被拒：降级到 session + HTTP PUT
+    if (inlineRejected) {
+        report('session-create', 0);
+        const session = await conn.call('storage.create_upload_session', {
+            object_key: objectKey,
+            size_bytes: total,
+            content_type: contentType,
+        });
+        const uploadUrl = session?.upload_url;
+        if (!uploadUrl)
+            throw new Error('storage.create_upload_session 未返回 upload_url');
+        // 简单 Buffer 上传 + 周期性进度（不用流，避免某些 storage 网关对 chunked / duplex 不友好）
+        report('http-put', 0);
+        const PROGRESS_TICK_MS = 250;
+        let lastBytes = 0;
+        const tickerStart = Date.now();
+        // 简单的“估算”进度：实际上一次性发，但在等待响应期间按 elapsed 模拟字节数，让用户看到在跑
+        const ticker = setInterval(() => {
+            const elapsed = Date.now() - tickerStart;
+            // 假设 2MB/s 估算；不超过 99%
+            const estimated = Math.min(total - 1, Math.floor((elapsed / 1000) * 2 * 1024 * 1024));
+            if (estimated > lastBytes) {
+                lastBytes = estimated;
+                report('http-put', estimated);
+            }
+        }, PROGRESS_TICK_MS);
+        let uploadResp;
+        try {
+            uploadResp = await fetch(uploadUrl, {
+                method: 'PUT',
+                body: new Blob([new Uint8Array(fileData)], { type: contentType }),
+                headers: { 'Content-Type': contentType },
+            });
+        }
+        finally {
+            clearInterval(ticker);
+        }
+        if (!uploadResp.ok)
+            throw new Error(`HTTP 上传失败: ${uploadResp.status}`);
+        report('http-put', total);
+        report('session-complete', total);
+        await conn.call('storage.complete_upload', {
+            object_key: objectKey,
+            sha256,
+            content_type: contentType,
+            is_private: false,
+            size_bytes: total,
+        });
+    }
+    report('done', total);
+    const attachment = {
+        owner_aid: ownerAid,
+        object_key: objectKey,
+        filename,
+        size_bytes: total,
+        sha256,
+        content_type: contentType,
+    };
+    // 确定渲染类型
+    let type;
+    if (opts?.as) {
+        if (!isValidPayloadType(opts.as)) {
+            throw new Error(`--as 必须是 image|video|voice|file，收到: ${opts.as}`);
+        }
+        type = opts.as;
+    }
+    else {
+        type = inferPayloadType(filename);
+    }
+    const payload = {
+        type,
+        attachments: [attachment],
+    };
+    if (opts?.text)
+        payload.text = opts.text;
+    else if (type === 'file')
+        payload.text = `📎 ${filename} (${formatSize(total)})`;
+    if (type === 'voice' && opts?.transcript)
+        payload.transcript = opts.transcript;
+    return { payload, type, attachment };
+}