@cubeai/dsh-feishu-channels 0.0.0-stage → 0.2.0

package/src/engine/image-input.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import { replyText } from './command-locale.js';
+export class ImageInputError extends Error {
+}
+/** Safe feedback: never forward raw host errors (paths, tokens, or bytes) to IM. */
+export function imageInputFailure(error) {
+    if (error instanceof ImageInputError)
+        return replyText(error.message);
+    const reason = error?.details?.reason;
+    if (reason === 'MODEL_DOES_NOT_SUPPORT_IMAGES')
+        return replyText('当前会话模型不支持图片输入，请在 Chat 中切换支持视觉的模型后重新发送。');
+    return replyText('图片输入失败，消息未提交。请检查图片格式、大小或当前会话模型后重新发送；详情见本机日志。');
+}
+/** Encode a channel download for Chat's public prompt API. Host owns validation. */
+export async function imagePromptPart(media) {
+    const data = media.data ? Buffer.from(media.data) : media.path ? await readFile(media.path).catch(() => { throw new ImageInputError('图片读取失败，请重新发送。'); }) : Buffer.alloc(0);
+    if (data.length === 0)
+        throw new ImageInputError('图片下载失败或内容为空，请重新发送。');
+    let mediaType = media.mediaType;
+    // Encrypted CDNs may report octet-stream or the adapter may guess from a
+    // filename. Actual image bytes take precedence; Host still fully decodes them.
+    if (data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        mediaType = 'image/png';
+    else if (data[0] === 255 && data[1] === 216 && data[2] === 255)
+        mediaType = 'image/jpeg';
+    else if (['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString('ascii')))
+        mediaType = 'image/gif';
+    else if (data.subarray(0, 4).toString('ascii') === 'RIFF' && data.subarray(8, 12).toString('ascii') === 'WEBP')
+        mediaType = 'image/webp';
+    return { type: 'image', data: data.toString('base64'), mediaType, ...(media.name ? { name: media.name } : {}) };
+}

package/src/engine/json-state.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { backupCorruptFileSync, writeFileAtomicSync } from './atomic-file.js';
+export class JsonStateFile {
+    file;
+    fallback;
+    constructor(file, fallback) {
+        this.file = file;
+        this.fallback = fallback;
+    }
+    read() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new TypeError('状态文件顶层必须是对象');
+            return parsed;
+        }
+        catch {
+            backupCorruptFileSync(this.file);
+            return structuredClone(this.fallback);
+        }
+    }
+    write(value) {
+        writeFileAtomicSync(this.file, `${JSON.stringify(value, null, 2)}\n`);
+    }
+}

package/src/engine/keyed-queue.js

@@ -0,0 +1,20 @@
+/** 对同一 key 串行、不同 key 并行的轻量异步操作队列。 */
+export class KeyedSerialQueue {
+    operations = new Map();
+    keys() {
+        return [...this.operations.keys()];
+    }
+    async run(key, operation) {
+        const previous = this.operations.get(key) ?? Promise.resolve();
+        const result = previous.catch(() => undefined).then(operation);
+        const tracked = result.then(() => undefined, () => undefined);
+        this.operations.set(key, tracked);
+        try {
+            return await result;
+        }
+        finally {
+            if (this.operations.get(key) === tracked)
+                this.operations.delete(key);
+        }
+    }
+}

package/src/engine/merge.js

@@ -0,0 +1,56 @@
+export function stripControlSuffix(text) {
+    if (text.endsWith('!!'))
+        return { text: text.slice(0, -2), control: 'commit' };
+    if (text.endsWith('..'))
+        return { text: text.slice(0, -2), control: 'continue' };
+    return { text, control: 'none' };
+}
+export class SessionMerger {
+    mergeTimeoutMs;
+    onFlush;
+    buffers = new Map();
+    constructor(mergeTimeoutMs, onFlush) {
+        this.mergeTimeoutMs = mergeTimeoutMs;
+        this.onFlush = onFlush;
+    }
+    ingest(key, raw) {
+        const { text, control } = stripControlSuffix(raw);
+        if (text.trim() === '' && control === 'none')
+            return { kind: 'ignored' };
+        const existing = this.buffers.get(key);
+        if (control === 'continue') {
+            this.setBuffer(key, existing ? `${existing.text}${text}` : text);
+            return { kind: 'buffered' };
+        }
+        if (existing) {
+            this.clear(key);
+            return { kind: 'flushed', text: `${existing.text}${text}` };
+        }
+        if (control === 'commit')
+            return { kind: 'flushed', text };
+        this.setBuffer(key, text);
+        return { kind: 'buffered' };
+    }
+    dispose() {
+        for (const key of [...this.buffers.keys()])
+            this.clear(key);
+    }
+    has(key) { return this.buffers.has(key); }
+    cancel(key) { this.clear(key); }
+    setBuffer(key, text) {
+        this.clear(key);
+        const timer = setTimeout(() => {
+            this.clear(key);
+            this.onFlush(key, text);
+        }, this.mergeTimeoutMs);
+        timer.unref?.();
+        this.buffers.set(key, { text, timer });
+    }
+    clear(key) {
+        const entry = this.buffers.get(key);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.buffers.delete(key);
+    }
+}

package/src/engine/message-progress.js

@@ -0,0 +1,274 @@
+import { replyText, withReplyLocale } from './command-locale.js';
+import { fileOperation } from './abort.js';
+/** 单条原消息的状态请求独立排队，失败和超时不阻塞正文。 */
+export class MessageProgress {
+    channel;
+    message;
+    host;
+    log;
+    tail = Promise.resolve();
+    reaction;
+    state;
+    terminal = false;
+    releaseTyping;
+    expiry;
+    constructor(channel, message, host, log, initial = 'processing') {
+        this.channel = channel;
+        this.message = message;
+        this.host = host;
+        this.log = log;
+        this.expiry = setTimeout(() => this.finish('cleared'), 30 * 60_000);
+        this.expiry.unref?.();
+        this.update(initial);
+    }
+    async safely(operation) {
+        const signal = AbortSignal.timeout(2000);
+        try {
+            await fileOperation(operation(signal), signal);
+        }
+        catch {
+            this.log(`[${this.channel.id}] 消息状态更新失败，正文继续处理`);
+        }
+    }
+    update(state) {
+        if (this.terminal || this.state === state)
+            return;
+        this.transition(state);
+        this.releaseTyping?.();
+        this.releaseTyping = state === 'processing'
+            ? acquireTyping(this.channel, this.message.chatId, operation => this.safely(operation)) : undefined;
+    }
+    finish(state) {
+        if (this.terminal)
+            return;
+        this.terminal = true;
+        clearTimeout(this.expiry);
+        this.releaseTyping?.();
+        this.releaseTyping = undefined;
+        this.transition(state);
+    }
+    isFinished() { return this.terminal; }
+    settled() { return this.tail; }
+    transition(state) {
+        this.state = state;
+        this.tail = this.tail.then(async () => {
+            if (this.state !== state)
+                return;
+            if (this.reaction) {
+                const old = this.reaction;
+                this.reaction = undefined;
+                await this.safely(async (signal) => { await this.channel.removeStatusReaction?.(this.message, old, signal); });
+            }
+            if (state === 'cleared' || !this.channel.addStatusReaction || !this.message.messageId)
+                return;
+            const label = withReplyLocale(this.host, () => ({
+                queued: replyText('⏳排队中'), processing: replyText('🤔思考中'), waiting: replyText('⏳等待确认'), success: replyText('✅已完成'),
+                ended: replyText('✅已结束'), error: replyText('❌处理失败'), cancelled: replyText('🚫已取消'),
+            })[state]);
+            await this.safely(async (signal) => {
+                const reaction = await this.channel.addStatusReaction(this.message, state, label, signal);
+                // 不清理超时请求的迟到响应：平台的撤销会清空新状态。
+                if (!signal.aborted)
+                    this.reaction = reaction;
+            });
+        });
+    }
+}
+/** 以 user/message 的 id 或 source.rpcId 认领回合，不按聊天或 FIFO 猜测任务归属。 */
+export class ProgressTracker {
+    onComplete;
+    onSettled;
+    groups = new Set();
+    ended = new Set();
+    turns = new Map();
+    currentTurn = new Map();
+    constructor(onComplete = () => { }, onSettled = () => { }) {
+        this.onComplete = onComplete;
+        this.onSettled = onSettled;
+    }
+    hasTurn(sessionId, turn) {
+        return turn !== undefined && (this.turns.has(`${sessionId}:${turn}`) || this.ended.has(`${sessionId}:${turn}`));
+    }
+    hasNewerTurn(sessionId, turn) {
+        const current = this.currentTurn.get(sessionId);
+        return current !== undefined && current > turn;
+    }
+    begin(sessionId, requestId, items) {
+        for (const old of this.groups)
+            if (old.items.every(item => item.isFinished()))
+                this.groups.delete(old);
+        const group = { sessionId, requestId, items };
+        this.groups.add(group);
+        return () => { for (const item of items)
+            item.finish('error'); this.groups.delete(group); };
+    }
+    event(sessionId, event) {
+        if (![...this.groups].some(group => group.sessionId === sessionId))
+            return;
+        const data = event.data;
+        if (event.type === 'turn/start' && Number.isSafeInteger(data?.turn))
+            this.currentTurn.set(sessionId, data.turn);
+        if (event.type === 'user/message' && event.surfaceOp === 'append') {
+            const turn = this.currentTurn.get(sessionId);
+            if (turn === undefined)
+                return;
+            for (const group of this.groups) {
+                if (group.sessionId !== sessionId || group.turn !== undefined
+                    || (group.requestId !== data?.id && group.requestId !== data?.source?.rpcId))
+                    continue;
+                group.turn = turn;
+                for (const item of group.items)
+                    item.update('processing');
+                const key = `${sessionId}:${turn}`;
+                let active = this.turns.get(key);
+                if (!active)
+                    this.turns.set(key, active = { groups: [], deliveries: [] });
+                active.groups.push(group);
+            }
+        }
+        if (event.type === 'turn/end') {
+            const key = `${sessionId}:${data?.turn}`;
+            const active = this.turns.get(key);
+            if (!active)
+                return;
+            this.turns.delete(key);
+            if (this.ended.size >= 512)
+                this.ended.delete(this.ended.values().next().value);
+            this.ended.add(key);
+            void Promise.all(active.deliveries).then(deliveries => {
+                const results = deliveries.filter((value) => value !== undefined);
+                const allSent = results.length > 0 && results.every(value => value === true);
+                // 全部都是「平台明确拒绝」才能自动补发；混进任何结果不明的失败都不行。
+                const allRejected = results.length > 0 && results.every(value => value === 'rejected');
+                const state = data?.reason?.kind === 'error' ? 'error'
+                    : data?.reason?.kind !== 'completed' ? 'cancelled'
+                        : results.length === 0 ? 'ended' : allSent ? 'success' : 'error';
+                // 交付确认不依赖是否仍适合发送下一步导航，新回合不能遗留旧请求。
+                this.onSettled(sessionId, data.turn, data?.reason?.kind === 'completed' && allSent, allRejected);
+                const superseded = this.hasNewerTurn(sessionId, data.turn);
+                const live = active.groups.filter(group => this.groups.has(group) && group.items.some(item => !item.isFinished()));
+                for (const group of live) {
+                    for (const item of group.items)
+                        item.finish(state);
+                    this.groups.delete(group);
+                }
+                if (![...this.groups].some(group => group.sessionId === sessionId))
+                    this.currentTurn.delete(sessionId);
+                if (live.length && !superseded)
+                    this.onComplete({ sessionId, turn: data.turn, items: live.flatMap(group => group.items),
+                        status: data?.reason?.kind === 'error' ? 'error' : data?.reason?.kind !== 'completed' ? 'cancelled'
+                            : results.length === 0 ? 'empty' : allSent ? 'completed' : 'delivery-failed' });
+            });
+        }
+    }
+    inbox(kind, payload) {
+        const sessionId = String(payload.agent?.session?.id ?? payload.agent?.id ?? '');
+        const message = payload.message;
+        if (kind === 'claimed' && Number.isSafeInteger(payload.turn)) {
+            this.event(sessionId, { type: 'turn/start', data: { turn: payload.turn } });
+            this.event(sessionId, { type: 'user/message', surfaceOp: 'append', data: message });
+            return;
+        }
+        for (const group of this.groups) {
+            if (group.sessionId !== sessionId || group.turn !== undefined
+                || (group.requestId !== message?.id && group.requestId !== message?.source?.rpcId))
+                continue;
+            const revision = group.revision = (group.revision ?? 0) + 1;
+            if (kind === 'discarded')
+                queueMicrotask(() => {
+                    // queue steer 会先移除再插入；同一同步操作中的重插入不算取消。
+                    if (group.revision !== revision || group.turn !== undefined || !this.groups.has(group))
+                        return;
+                    for (const item of group.items)
+                        item.finish('cancelled');
+                    this.groups.delete(group);
+                });
+        }
+    }
+    delivery(sessionId, turn, work) {
+        if (turn !== undefined)
+            this.turns.get(`${sessionId}:${turn}`)?.deliveries.push(work.catch(() => false));
+    }
+    waiting(sessionId, waiting) {
+        const turn = this.currentTurn.get(sessionId);
+        const active = [...this.groups].filter(group => group.sessionId === sessionId && group.turn !== undefined && group.turn === turn);
+        const update = (delta) => {
+            for (const group of active) {
+                group.waiting = Math.max(0, (group.waiting ?? 0) + delta);
+                for (const item of group.items)
+                    item.update(group.waiting > 0 ? 'waiting' : 'processing');
+            }
+        };
+        update(waiting ? 1 : -1);
+        let released = false;
+        return () => {
+            if (released || !waiting)
+                return;
+            released = true;
+            update(-1);
+        };
+    }
+    cancel(channelId, sessionId) {
+        for (const group of this.groups) {
+            if (sessionId && group.sessionId !== sessionId)
+                continue;
+            if (channelId && !group.items.some(item => item.channel.id === channelId))
+                continue;
+            for (const item of group.items)
+                item.finish('cancelled');
+            this.groups.delete(group);
+        }
+        for (const [key, turn] of this.turns)
+            if (turn.groups.every(group => !this.groups.has(group)))
+                this.turns.delete(key);
+        if (!channelId && !sessionId)
+            this.currentTurn.clear();
+        else if (sessionId)
+            this.currentTurn.delete(sessionId);
+    }
+}
+const typingGroups = new WeakMap();
+/** 同一账号同一聊天只有一个 typing 定时器；旧任务结束不能停掉新任务。 */
+function acquireTyping(channel, chatId, safely) {
+    if (!channel.sendAction)
+        return () => { };
+    let chats = typingGroups.get(channel);
+    if (!chats)
+        typingGroups.set(channel, chats = new Map());
+    let group = chats.get(chatId);
+    if (!group) {
+        group = { users: 0 };
+        chats.set(chatId, group);
+        const current = group;
+        const pulse = () => {
+            if (current.pending)
+                return;
+            current.pending = Promise.resolve().then(() => channel.sendAction(chatId, 'typing'))
+                .catch(() => { }).finally(() => { current.pending = undefined; });
+            void safely(() => current.pending);
+        };
+        pulse();
+        if (channel.typingIntervalMs) {
+            current.timer = setInterval(pulse, channel.typingIntervalMs);
+            current.timer.unref?.();
+        }
+    }
+    group.users++;
+    const current = group;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (--current.users > 0)
+            return;
+        if (current.timer)
+            clearInterval(current.timer);
+        chats.delete(chatId);
+        // 等本轮 start 返回后再 stop，且不打断已启动的新一组。
+        void (current.pending ?? Promise.resolve()).then(() => {
+            if (!chats.has(chatId))
+                return safely(async () => { await channel.stopAction?.(chatId); });
+        });
+    };
+}

package/src/engine/question.js

@@ -0,0 +1,201 @@
+import { replyText } from './command-locale.js';
+function nonEmptyText(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text || undefined;
+}
+export function validUserQuestion(question) {
+    if (!question || typeof question !== 'object')
+        return false;
+    const item = question;
+    if (typeof item.id !== 'string' || typeof item.question !== 'string')
+        return false;
+    if (item.header !== undefined && typeof item.header !== 'string')
+        return false;
+    if (item.detail !== undefined && typeof item.detail !== 'string')
+        return false;
+    if (item.multiSelect !== undefined && typeof item.multiSelect !== 'boolean')
+        return false;
+    if (item.intent !== undefined) {
+        if (!item.intent || typeof item.intent !== 'object')
+            return false;
+        const intent = item.intent;
+        if (typeof intent.kind !== 'string')
+            return false;
+        if (intent.approve !== undefined && typeof intent.approve !== 'string')
+            return false;
+    }
+    if (item.options !== undefined) {
+        if (!Array.isArray(item.options))
+            return false;
+        for (const option of item.options) {
+            if (!option || typeof option !== 'object')
+                return false;
+            const value = option;
+            if (typeof value.label !== 'string')
+                return false;
+            if (value.description !== undefined && typeof value.description !== 'string')
+                return false;
+        }
+    }
+    return true;
+}
+export function formatUserQuestion(question, index, total, options = {}) {
+    const progress = total > 1 ? `（${index + 1}/${total}）` : '';
+    const lines = [replyText('DeepSeek Harness 需要你补充信息{0}：', progress)];
+    const header = nonEmptyText(question.header);
+    const prompt = nonEmptyText(question.question) ?? replyText('请输入你的回答。');
+    const detail = nonEmptyText(question.detail);
+    if (header)
+        lines.push('', header);
+    lines.push('', prompt);
+    if (detail)
+        lines.push('', detail);
+    const choices = question.options ?? [];
+    if (choices.length > 0) {
+        lines.push('');
+        choices.forEach((choice, choiceIndex) => {
+            const description = nonEmptyText(choice.description);
+            const checked = question.multiSelect && options.selected?.has(choiceIndex) ? '✓ ' : '';
+            lines.push(`${choiceIndex + 1}. ${checked}${choice.label}${description ? ` — ${description}` : ''}`);
+        });
+        // 提交项属于选项列表，不能接在回复说明之后；部分平台按钮只有数字。
+        if (question.multiSelect === true && options.selected?.size)
+            lines.push(`${choices.length + 1}. ${replyText('提交所选')}`);
+        lines.push('', question.multiSelect === true
+            ? replyText('请回复选项序号或文字；多选用逗号分隔，也可补充其他内容。')
+            : replyText('请回复一个选项序号或文字，也可直接输入其他答案。'));
+    }
+    else {
+        lines.push('', replyText('请直接回复你的答案。'));
+    }
+    if (options.requiresMention)
+        lines.push('', replyText('群聊中请 @机器人 后发送答案。'));
+    return lines.join('\n');
+}
+function optionLabel(token, options) {
+    const value = token.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return options[Number(value) - 1]?.label;
+    return options.find((option) => option.label === value)?.label;
+}
+export function answerUserQuestion(question, input) {
+    const text = input.trim();
+    const options = question.options ?? [];
+    if (options.length === 0)
+        return { id: question.id, selected: [], custom: text };
+    const whole = optionLabel(text, options);
+    if (question.multiSelect !== true) {
+        return whole
+            ? { id: question.id, selected: [whole] }
+            : { id: question.id, selected: [], custom: text };
+    }
+    if (whole)
+        return { id: question.id, selected: [whole] };
+    const selected = [];
+    const custom = [];
+    for (const raw of text.split(/[,，、;；\n]+/)) {
+        const value = raw.trim();
+        if (!value)
+            continue;
+        const label = optionLabel(value, options);
+        if (label) {
+            if (!selected.includes(label))
+                selected.push(label);
+        }
+        else {
+            custom.push(value);
+        }
+    }
+    return {
+        id: question.id,
+        selected,
+        ...(custom.length > 0 ? { custom: custom.join('、') } : {}),
+    };
+}
+export class QuestionBroker {
+    pending = new Map();
+    has(key) {
+        return this.pending.has(key);
+    }
+    current(key) {
+        const pending = this.pending.get(key);
+        const question = pending?.questions[pending.index];
+        if (!pending || !question)
+            return undefined;
+        return { question, index: pending.index, total: pending.questions.length };
+    }
+    signal(key) {
+        return this.pending.get(key)?.signal;
+    }
+    begin(key, questions, signal) {
+        if (this.pending.has(key) || signal?.aborted)
+            return undefined;
+        return new Promise((resolve, reject) => {
+            const pending = {
+                questions,
+                answers: [],
+                index: 0,
+                accepting: false,
+                resolve,
+                reject,
+            };
+            if (signal) {
+                pending.signal = signal;
+                pending.onAbort = () => this.cancel(key, signal.reason ?? new DOMException('Aborted', 'AbortError'));
+                signal.addEventListener('abort', pending.onAbort, { once: true });
+            }
+            this.pending.set(key, pending);
+        });
+    }
+    isReady(key) { return this.pending.get(key)?.accepting === true; }
+    activate(key) {
+        const pending = this.pending.get(key);
+        if (!pending)
+            return false;
+        pending.accepting = true;
+        return true;
+    }
+    answer(key, text) {
+        const pending = this.pending.get(key);
+        const question = pending?.questions[pending.index];
+        if (!pending || !question)
+            return { handled: false };
+        if (!pending.accepting)
+            return { handled: true, waitingPresentation: true };
+        pending.answers.push(answerUserQuestion(question, text));
+        pending.index += 1;
+        const next = pending.questions[pending.index];
+        if (next) {
+            pending.accepting = false;
+            return {
+                handled: true,
+                next: { question: next, index: pending.index, total: pending.questions.length },
+            };
+        }
+        this.cleanup(pending);
+        this.pending.delete(key);
+        pending.resolve({ answers: pending.answers });
+        return { handled: true, completed: true };
+    }
+    cancel(key, reason = new DOMException('Aborted', 'AbortError')) {
+        const pending = this.pending.get(key);
+        if (!pending)
+            return false;
+        this.cleanup(pending);
+        this.pending.delete(key);
+        pending.reject(reason);
+        return true;
+    }
+    dispose() {
+        for (const key of [...this.pending.keys()])
+            this.cancel(key);
+    }
+    cleanup(pending) {
+        if (pending.signal && pending.onAbort)
+            pending.signal.removeEventListener('abort', pending.onAbort);
+    }
+}

package/src/engine/quiet-logger.js

@@ -0,0 +1,25 @@
+/** 渠道 SDK 日志：只上报告警和错误，不打印握手 info。 */
+export function quietSdkLogger(log, prefix) {
+    const emit = (args) => {
+        const text = args.map((item) => typeof item === 'string' ? item : safe(item)).join(' ').trim();
+        if (text)
+            log(`[${prefix}] ${text}`);
+    };
+    return {
+        debug: () => undefined,
+        info: () => undefined,
+        trace: () => undefined,
+        warn: (...args) => emit(args),
+        error: (...args) => emit(args),
+    };
+}
+function safe(value) {
+    if (value instanceof Error)
+        return value.message;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}