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

package/src/channels/meta.js

@@ -0,0 +1,24 @@
+/** Feishu-only channel metadata. */
+export const CHANNEL_ORDER = ['feishu'];
+
+export const CHANNEL_META = {
+    feishu: {
+        id: 'feishu',
+        label: '飞书',
+        description: '通过飞书机器人接收并回复用户消息',
+        kind: 'qr-or-credentials',
+        fields: [
+            { key: 'appId', label: 'App ID' },
+            { key: 'appSecret', label: 'App Secret', secret: true },
+        ],
+    },
+};
+
+export function listChannelMeta() {
+    return CHANNEL_ORDER.map((id) => CHANNEL_META[id]);
+}
+
+export function supportsQr(id) {
+    const kind = CHANNEL_META[id]?.kind;
+    return kind === 'qr' || kind === 'qr-or-credentials';
+}

package/src/channels/qr/feishu.js

@@ -0,0 +1,84 @@
+/** 飞书设备注册扫码，自动创建机器人。 */
+import { asRecord, cleanString, readJson } from './shared.js';
+import { decorateQrUrl } from '../feishu-app.js';
+
+const FEISHU_ACCOUNTS = 'https://accounts.feishu.cn';
+
+export function parseFeishuBegin(body, now = Date.now()) {
+    const record = asRecord(body);
+    const err = cleanString(record.error);
+    if (err)
+        throw new Error(`飞书注册开始失败：${err}`);
+    const deviceCode = cleanString(record.device_code);
+    const qrUrl = cleanString(record.verification_uri_complete);
+    if (!deviceCode || !qrUrl)
+        throw new Error('飞书注册没有返回完整二维码');
+    const expiresIn = Number(record.expire_in ?? record.expires_in);
+    const interval = Number(record.interval);
+    return {
+        deviceCode,
+        qrUrl,
+        expiresAt: now + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 300) * 1000,
+        pollIntervalMs: (Number.isFinite(interval) && interval > 0 ? interval : 5) * 1000,
+    };
+}
+
+export function parseFeishuPoll(body) {
+    const record = asRecord(body);
+    const userInfo = asRecord(record.user_info);
+    const brand = cleanString(userInfo.tenant_brand);
+    if (brand?.toLowerCase() === 'lark')
+        return { status: 'failed', error: '检测到 Lark 账号；本插件仅支持飞书账号。' };
+    const appId = cleanString(record.client_id);
+    const appSecret = cleanString(record.client_secret);
+    if (appId && appSecret) {
+        const ownerOpenId = cleanString(userInfo.open_id);
+        return {
+            status: 'success',
+            credentials: ownerOpenId ? { appId, appSecret, ownerOpenId } : { appId, appSecret },
+        };
+    }
+    const err = cleanString(record.error);
+    if (err === 'authorization_pending')
+        return { status: 'waiting' };
+    if (err === 'slow_down')
+        return { status: 'waiting', pollIntervalMs: 10_000 };
+    if (err === 'access_denied')
+        return { status: 'failed', error: '用户拒绝授权' };
+    if (err === 'expired_token')
+        return { status: 'expired', error: '二维码已过期' };
+    if (err)
+        return { status: 'failed', error: err };
+    return { status: 'waiting' };
+}
+
+async function call(action, params, signal) {
+    const form = new URLSearchParams({ action, ...params });
+    const response = await fetch(`${FEISHU_ACCOUNTS}/oauth/v1/app/registration`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: form.toString(),
+        redirect: 'error',
+        signal: signal ?? AbortSignal.timeout(15_000),
+    });
+    return readJson(response, `飞书${action}`);
+}
+
+export async function beginFeishuQr(options = {}, signal) {
+    if (options && typeof options.aborted === 'boolean') {
+        signal = options;
+        options = {};
+    }
+    await call('init', {}, signal);
+    const begun = parseFeishuBegin(await call('begin', {
+        archetype: 'PersonalAgent',
+        auth_method: 'client_secret',
+        request_user_info: 'open_id',
+    }, signal));
+    return {
+        qrUrl: decorateQrUrl(begun.qrUrl, { name: options?.name ?? options?.__setting_name }),
+        expiresAt: begun.expiresAt,
+        pollIntervalMs: begun.pollIntervalMs,
+        poll: async (pollSignal) => parseFeishuPoll(await call('poll', { device_code: begun.deviceCode }, pollSignal)),
+    };
+}

package/src/channels/qr/hub.js

@@ -0,0 +1,229 @@
+import { CHANNEL_META } from '../meta.js';
+import { qrPayloadOf, remainingSeconds, sleep } from './shared.js';
+import { renderQrDataUrl } from './render.js';
+import { beginFeishuQr } from './feishu.js';
+export class PairingHub {
+    sessions = new Map();
+    onSuccess;
+    beginFn;
+    renderQr;
+    log;
+    constructor(options = {}) {
+        this.onSuccess = options.onSuccess;
+        this.beginFn = options.beginFn;
+        this.renderQr = options.renderQr ?? renderQrDataUrl;
+        this.log = options.log ?? (() => undefined);
+    }
+    supports(id) {
+        const kind = CHANNEL_META[id]?.kind;
+        return kind === 'qr' || kind === 'qr-or-credentials';
+    }
+    view(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return { channelId: id, status: 'idle' };
+        return {
+            channelId: id,
+            status: session.status,
+            qrUrl: session.qrUrl,
+            qrImage: session.qrImage,
+            expiresAt: session.expiresAt,
+            remainingSeconds: remainingSeconds(session.expiresAt),
+            hint: session.hint,
+            error: session.error,
+        };
+    }
+    async start(id, extra = {}) {
+        if (!this.supports(id))
+            throw new Error(`${id} 不支持扫码绑定`);
+        if (this.sessions.get(id)?.status === 'saving')
+            return this.view(id);
+        this.cancel(id);
+        const session = {
+            channelId: id,
+            status: 'starting',
+            pollIntervalMs: 3000,
+            extra,
+            controller: new AbortController(),
+        };
+        this.sessions.set(id, session);
+        try {
+            const begun = await this.begin(id, session.controller.signal, extra);
+            if (this.sessions.get(id) !== session)
+                return this.view(id);
+            session.begin = begun;
+            const payload = qrPayloadOf(begun);
+            session.qrUrl = payload.qrUrl;
+            session.qrImage = payload.qrImage;
+            if (!session.qrImage && session.qrUrl) {
+                try {
+                    session.qrImage = await this.renderQr(session.qrUrl);
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    session.status = 'failed';
+                    session.error = '二维码生成失败，请查看本机日志';
+                    session.qrUrl = undefined;
+                    session.begin?.dispose?.();
+                    this.log(`[pairing] ${id} 本地二维码生成失败：${detail}`);
+                    return this.view(id);
+                }
+            }
+            session.expiresAt = begun.expiresAt;
+            // 记住初始有效期窗口：连接器自动换码时按同一窗口顺延，而不是被固定 5 分钟误杀
+            const windowMs = (begun.expiresAt ?? 0) - Date.now();
+            if (windowMs > 0)
+                session.expiryWindowMs = windowMs;
+            session.pollIntervalMs = begun.pollIntervalMs;
+            session.status = 'waiting';
+            session.hint = hintOf(id);
+            void this.loop(session);
+            return this.view(id);
+        }
+        catch (error) {
+            if (this.sessions.get(id) !== session)
+                return this.view(id);
+            session.status = 'failed';
+            const detail = error instanceof Error ? error.message : String(error);
+            session.error = '二维码生成失败，请查看本机日志';
+            this.log(`[pairing] ${id} 生成二维码失败：${detail}`);
+            return this.view(id);
+        }
+    }
+    async refresh(id) {
+        const extra = this.sessions.get(id)?.extra ?? {};
+        return this.start(id, extra);
+    }
+    cancel(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return this.view(id);
+        // 外部平台已经返回凭据后必须完成本地保存，避免关闭弹窗留下“机器人已创建但账号未落盘”。
+        if (session.status === 'saving')
+            return this.view(id);
+        session.begin?.dispose?.();
+        session.controller.abort();
+        if (session.status !== 'success') {
+            session.status = 'cancelled';
+            session.qrUrl = undefined;
+            session.qrImage = undefined;
+        }
+        return this.view(id);
+    }
+    dispose() {
+        for (const id of [...this.sessions.keys()])
+            this.cancel(id);
+        this.sessions.clear();
+    }
+    async begin(id, signal, extra = {}) {
+        if (this.beginFn)
+            return this.beginFn(id, signal, extra);
+        if (id === 'feishu')
+            return beginFeishuQr(extra, signal);
+        throw new Error(`${id} 不支持扫码绑定`);
+    }
+    async loop(session) {
+        const begun = session.begin;
+        if (!begun)
+            return;
+        while (!session.controller.signal.aborted && this.sessions.get(session.channelId) === session) {
+            if (session.expiresAt && Date.now() >= session.expiresAt) {
+                session.status = 'expired';
+                session.error = '二维码已过期';
+                session.qrUrl = undefined;
+                session.qrImage = undefined;
+                session.begin?.dispose?.();
+                return;
+            }
+            try {
+                const polled = await begun.poll(session.controller.signal);
+                if (polled.qrUrl && polled.qrUrl !== session.qrUrl) {
+                    try {
+                        const qrImage = await this.renderQr(polled.qrUrl);
+                        if (this.sessions.get(session.channelId) !== session)
+                            return;
+                        session.qrUrl = polled.qrUrl;
+                        session.qrImage = qrImage;
+                        if (session.expiryWindowMs)
+                            session.expiresAt = Date.now() + session.expiryWindowMs;
+                    }
+                    catch (error) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        session.status = 'failed';
+                        session.error = '二维码生成失败，请查看本机日志';
+                        session.qrUrl = undefined;
+                        session.qrImage = undefined;
+                        session.begin?.dispose?.();
+                        this.log(`[pairing] ${session.channelId} 本地二维码刷新失败：${detail}`);
+                        return;
+                    }
+                }
+                if (this.sessions.get(session.channelId) !== session)
+                    return;
+                if (polled.pollIntervalMs)
+                    session.pollIntervalMs = polled.pollIntervalMs;
+                if (polled.status === 'success' && polled.credentials) {
+                    session.status = 'saving';
+                    session.qrUrl = undefined;
+                    session.qrImage = undefined;
+                    session.hint = '正在保存账号';
+                    const credentials = { ...session.extra, ...polled.credentials };
+                    try {
+                        await this.onSuccess?.(session.channelId, credentials);
+                        if (this.sessions.get(session.channelId) !== session)
+                            return;
+                        session.status = 'success';
+                        session.hint = '绑定成功';
+                    }
+                    catch (error) {
+                        if (this.sessions.get(session.channelId) !== session)
+                            return;
+                        session.status = 'failed';
+                        const detail = error instanceof Error ? error.message : String(error);
+                        session.error = '保存凭据失败，请查看本机日志';
+                        this.log(`[pairing] ${session.channelId} 保存凭据失败：${detail}`);
+                    }
+                    return;
+                }
+                if (polled.status === 'scanned') {
+                    session.status = 'scanned';
+                    session.hint = '已扫码，请在手机上确认';
+                }
+                else if (polled.status === 'expired' || polled.status === 'failed') {
+                    session.status = polled.status;
+                    if (polled.status === 'failed') {
+                        if (polled.error)
+                            this.log(`[pairing] ${session.channelId} 绑定失败：${polled.error}`);
+                        session.error = '绑定失败，请查看本机日志';
+                    }
+                    else {
+                        session.error = polled.error;
+                    }
+                    session.qrUrl = undefined;
+                    session.qrImage = undefined;
+                    session.begin?.dispose?.();
+                    return;
+                }
+                else if (session.status !== 'scanned') {
+                    session.status = 'waiting';
+                }
+            }
+            catch (error) {
+                if (session.controller.signal.aborted)
+                    return;
+                this.log(`[pairing] ${session.channelId} 轮询失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                await sleep(session.pollIntervalMs, session.controller.signal);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+}
+function hintOf(id) {
+    if (id === 'feishu')
+        return '请使用飞书扫描二维码，将自动创建机器人';
+    return '请使用飞书扫描二维码';
+}

package/src/channels/qr/render.js

@@ -0,0 +1,8 @@
+/** 把扫码内容画成本地 data URL，避免前端把链接当成图片。 */
+export async function renderQrDataUrl(payload) {
+    const QRCode = await import('qrcode');
+    const toDataURL = QRCode.toDataURL ?? QRCode.default?.toDataURL;
+    if (!toDataURL)
+        throw new Error('缺少二维码生成库 qrcode');
+    return toDataURL(payload, { width: 240, margin: 1, errorCorrectionLevel: 'M' });
+}

package/src/channels/qr/shared.js

@@ -0,0 +1,50 @@
+/** 扫码绑定公共工具。 */
+export function cleanString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+export async function readJson(response, label) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new Error(`${label} 返回了非 JSON`, { cause: error });
+    }
+    if (!response.ok)
+        throw new Error(`${label} HTTP ${response.status}`);
+    return asRecord(body);
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('aborted'));
+        }, { once: true });
+    });
+}
+export function remainingSeconds(expiresAt, now = Date.now()) {
+    if (!expiresAt)
+        return undefined;
+    return Math.max(0, Math.ceil((expiresAt - now) / 1000));
+}
+export function isRasterQr(value) {
+    if (!value)
+        return false;
+    return /^data:image\//i.test(value) || /\.(png|jpe?g|gif|webp)(\?|$)/i.test(value);
+}
+export function qrPayloadOf(begun) {
+    if (isRasterQr(begun.qrImage))
+        return { qrUrl: begun.qrUrl, qrImage: begun.qrImage };
+    const qrUrl = begun.qrUrl || begun.qrImage;
+    return { qrUrl, qrImage: undefined };
+}

package/src/engine/abort.js

@@ -0,0 +1,35 @@
+export function timeoutSignal(timeoutMs, parent) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return parent ? AbortSignal.any([parent, timeout]) : timeout;
+}
+export function isAbortError(error) {
+    return error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError');
+}
+export function sleepWithSignal(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener('abort', aborted, { once: true });
+        function done() {
+            signal.removeEventListener('abort', aborted);
+            resolve();
+        }
+        function aborted() {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }
+    });
+}
+/** SDK 不接收 AbortSignal 时及时结束等待；后续发送仍需检查同一信号。 */
+export function fileOperation(operation, signal) {
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(signal.reason);
+        signal.addEventListener('abort', aborted, { once: true });
+        operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+        if (signal.aborted)
+            aborted();
+    });
+}

package/src/engine/access.js

@@ -0,0 +1,23 @@
+export function normalizeUserId(userId) {
+    return userId?.trim() ?? '';
+}
+export function isUserAllowed(allowlist, userId) {
+    const id = normalizeUserId(userId);
+    if (!id)
+        return false;
+    for (const item of allowlist) {
+        if (item === id)
+            return true;
+    }
+    return false;
+}
+export function decideAccess(input) {
+    if (input.kind === 'group') {
+        return input.addressed === false ? 'ignore' : 'allow';
+    }
+    return input.userAllowed ? 'allow' : 'deny';
+}
+/** 工具授权比普通消息更严：必须已在白名单，且只能在私聊里答复。 */
+export function canAnswerToolApproval(input) {
+    return input.userAllowed && input.kind !== 'group';
+}

package/src/engine/agent-options.js

@@ -0,0 +1,19 @@
+/** 解析 IM 会话要用的模型，禁止把空字符串传给 agents.create。 */
+import { replyText } from './command-locale.js';
+export function resolveImAgentOptions(input) {
+    const provider = input.provider?.trim() || input.fallback?.provider?.trim() || '';
+    const model = input.model?.trim() || input.fallback?.model?.trim() || '';
+    if (!provider || !model) {
+        throw new Error(replyText('请先在设置 → 飞书频道 页面选择模型。'));
+    }
+    return { provider, model };
+}
+/** 用 ctx.get 读默认模型，避免未 inject 时直接访问属性抛错。 */
+export function readHostDefaultModel(ctx) {
+    try {
+        return ctx.get?.('agentDefaultModel')?.currentSelection?.();
+    }
+    catch {
+        return undefined;
+    }
+}

package/src/engine/approval.js

@@ -0,0 +1,70 @@
+/** IM 审批等待上限。到期按取消结束，不按用户拒绝。 */
+export const APPROVAL_WAIT_MS = 5 * 60 * 1000;
+export class ApprovalBroker {
+    pending = new Map();
+    get size() {
+        return this.pending.size;
+    }
+    wait(key, timeoutMs, signal) {
+        if (this.pending.has(key))
+            return undefined;
+        if (signal?.aborted)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            const settle = (value) => {
+                const entry = this.pending.get(key);
+                if (!entry)
+                    return;
+                if (entry.timer)
+                    clearTimeout(entry.timer);
+                if (entry.signal && entry.onAbort)
+                    entry.signal.removeEventListener('abort', entry.onAbort);
+                this.pending.delete(key);
+                resolve(value);
+            };
+            const entry = { resolve: settle, accepting: false };
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                entry.timer = setTimeout(() => settle('timeout'), timeoutMs);
+                entry.timer.unref?.();
+            }
+            if (signal) {
+                entry.signal = signal;
+                entry.onAbort = () => settle(undefined);
+                signal.addEventListener('abort', entry.onAbort, { once: true });
+            }
+            this.pending.set(key, entry);
+        });
+    }
+    token(key) { return this.pending.get(key); }
+    has(key) {
+        return this.pending.has(key);
+    }
+    activate(key) {
+        const entry = this.pending.get(key);
+        if (!entry)
+            return false;
+        entry.accepting = true;
+        return true;
+    }
+    isReady(key) {
+        return this.pending.get(key)?.accepting === true;
+    }
+    answer(key, allow) {
+        const entry = this.pending.get(key);
+        if (!entry || !entry.accepting)
+            return false;
+        entry.resolve(allow ? 'allow' : 'reject');
+        return true;
+    }
+    cancel(key) {
+        const entry = this.pending.get(key);
+        if (!entry)
+            return false;
+        entry.resolve(undefined);
+        return true;
+    }
+    dispose() {
+        for (const key of [...this.pending.keys()])
+            this.cancel(key);
+    }
+}

package/src/engine/assistant-settings.js

@@ -0,0 +1,38 @@
+export function normalizeAssistantModel(input) {
+    const provider = typeof input.provider === 'string' ? input.provider.trim() : '';
+    const model = typeof input.model === 'string' ? input.model.trim() : '';
+    if (!provider || !model)
+        return undefined;
+    const reasoningEffort = normalizeEffort(input.reasoningEffort);
+    return reasoningEffort ? { provider, model, reasoningEffort } : { provider, model };
+}
+export function pickAssistantModel(...candidates) {
+    for (const item of candidates) {
+        if (item?.provider && item.model)
+            return item;
+    }
+    return undefined;
+}
+export function normalizeWorkspacePath(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    const cwd = input.trim();
+    return cwd === '' ? undefined : cwd;
+}
+export function normalizePermission(input, officialNames) {
+    if (typeof input !== 'string')
+        return undefined;
+    // 兼容 0.1.13 及更早版本保存的旧值，读取后统一迁移到 Chat 标准值。
+    const permission = input.trim() === 'full-access' ? 'danger-full-access' : input.trim();
+    if (!permission || (officialNames !== undefined && !officialNames.includes(permission)))
+        return undefined;
+    return permission;
+}
+export function normalizeEffort(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    const effort = input.trim();
+    if (!effort || effort === 'none' || effort === 'default')
+        return undefined;
+    return effort;
+}

package/src/engine/assistant-text.js

@@ -0,0 +1,11 @@
+/**
+ * 提取可投递的助手正文；启用过滤时，含工具调用的整条消息返回 undefined。
+ * undefined 表示主动抑制，不是投递成功；空串表示消息本身没有文字。
+ */
+export function assistantText(content = [], skipInterimText = false) {
+    const blocks = content ?? [];
+    if (skipInterimText && blocks.some(block => block.type === 'tool-call'))
+        return undefined;
+    return blocks.filter(block => block.type === 'text' && typeof block.text === 'string')
+        .map(block => block.text ?? '').join('\n').trim();
+}

package/src/engine/atomic-file.js

@@ -0,0 +1,45 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/** 在目标文件同目录写临时文件，再原子替换，避免进程中断留下半截内容。 */
+export function writeFileAtomicSync(file, data, mode) {
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const temp = join(dir, `.${basename(file)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+    let fd;
+    try {
+        fd = openSync(temp, 'wx', mode);
+        writeFileSync(fd, data, 'utf8');
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        if (mode !== undefined) {
+            try {
+                chmodSync(temp, mode);
+            }
+            catch { /* Windows 或受限文件系统不支持 POSIX mode */ }
+        }
+        renameSync(temp, file);
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* 已关闭 */ }
+        }
+        try {
+            unlinkSync(temp);
+        }
+        catch { /* rename 成功或临时文件尚未创建 */ }
+    }
+}
+/** 在回退为空状态前保留不可解析文件的唯一副本。 */
+export function backupCorruptFileSync(file) {
+    if (!existsSync(file))
+        return undefined;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backup = `${file}.corrupt-${stamp}-${process.pid}`;
+    renameSync(file, backup);
+    return backup;
+}