dsh-lark-agent 0.4.0 → 0.5.1

package/dist/media-input.js

@@ -0,0 +1,127 @@
+import { spawn } from 'node:child_process';
+export class MediaInputError extends Error {
+}
+export const MAX_INPUT_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_INPUT_AUDIO_BYTES = 5 * 1024 * 1024;
+export const MAX_INPUT_IMAGES = 4;
+export const MAX_INPUT_TOTAL_BYTES = 20 * 1024 * 1024;
+const MAX_PCM_BYTES = 60 * 16_000 * 2;
+/** Fixed local codec invocation; no user/model arguments, URLs, paths or stderr reach the process. */
+export function decodeVoice(data, signal) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const child = spawn('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-protocol_whitelist', 'pipe', '-i', 'pipe:0',
+            '-vn', '-ac', '1', '-ar', '16000', '-f', 's16le', 'pipe:1'], { shell: false, windowsHide: true, stdio: 'pipe' });
+        let failure;
+        let size = 0;
+        const chunks = [];
+        let kill;
+        const stop = (error) => {
+            failure ??= error;
+            child.kill('SIGTERM');
+            kill ??= setTimeout(() => child.kill('SIGKILL'), 1000);
+        };
+        const abort = () => stop(new MediaInputError('语音处理已取消。'));
+        signal.addEventListener('abort', abort, { once: true });
+        const timeout = setTimeout(() => stop(new MediaInputError('语音转码超时，请改发文字。')), 30_000);
+        child.stdout.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_PCM_BYTES) {
+                stop(new MediaInputError('语音最长支持 60 秒，请分段发送。'));
+                return;
+            }
+            if (!failure)
+                chunks.push(Buffer.from(chunk));
+        });
+        child.stderr.resume();
+        child.stdin.on('error', () => stop(new MediaInputError('语音格式无法读取，请改发文字。')));
+        child.on('error', () => { failure = new MediaInputError('语音输入需要宿主设备安装 FFmpeg。'); });
+        child.on('close', code => {
+            clearTimeout(timeout);
+            clearTimeout(kill);
+            signal.removeEventListener('abort', abort);
+            if (failure)
+                reject(failure);
+            else if (code !== 0 || !size)
+                reject(new MediaInputError('这段语音无法读取，请改发文字。'));
+            else
+                resolve(Buffer.concat(chunks));
+        });
+        child.stdin.end(data);
+    });
+}
+/** Only binary discovery, never a download or installation. */
+export function ffmpegAvailable() {
+    return new Promise(resolve => {
+        const child = spawn('ffmpeg', ['-version'], { shell: false, windowsHide: true, stdio: 'ignore' });
+        const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(false); }, 3000);
+        child.on('error', () => { clearTimeout(timer); resolve(false); });
+        child.on('close', code => { clearTimeout(timer); resolve(code === 0); });
+    });
+}
+function imageType(data) {
+    const bytes = Buffer.from(data);
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+        return 'image/jpeg';
+    if (['GIF87a', 'GIF89a'].includes(bytes.subarray(0, 6).toString('ascii')))
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP')
+        return 'image/webp';
+    throw new MediaInputError('图片格式不支持，请发送 PNG、JPEG、WebP 或 GIF。');
+}
+/** Called inside an admitted lane, after identity, durable claim and current chat access checks. */
+export async function prepareMedia(message, transport, signal, options, decode = decodeVoice) {
+    const resources = message.resources ?? [];
+    if (!resources.length)
+        return { text: message.text };
+    if (message.chatType !== 'p2p')
+        throw new MediaInputError('图片和语音输入仅用于本人私聊，请改发文字。');
+    if (resources.length > MAX_INPUT_IMAGES)
+        throw new MediaInputError(`每条消息最多支持 ${MAX_INPUT_IMAGES} 张图片，请分开发送。`);
+    if (resources.some(resource => resource.kind === 'image') && !options.images)
+        throw new MediaInputError('这个机器人的图片输入已关闭，请在设置中开启。');
+    if (resources.some(resource => resource.kind === 'audio') && !options.voice)
+        throw new MediaInputError('这个机器人的语音输入未启用，请在设置中检查 FFmpeg 和飞书语音识别权限，或改发文字。');
+    if (!transport.readResource)
+        throw new MediaInputError('当前消息通道无法下载附件，请更新插件。');
+    const images = [];
+    let total = 0, text = message.text;
+    for (const resource of resources) {
+        signal.throwIfAborted();
+        if (resource.kind === 'audio' && resource.duration !== undefined && resource.duration > 60)
+            throw new MediaInputError('语音最长支持 60 秒，请分段发送。');
+        let data;
+        try {
+            data = await transport.readResource(resource, signal);
+        }
+        catch {
+            throw new MediaInputError('附件未能下载，请检查机器人的 im:message:readonly 权限和消息是否仍可访问。');
+        }
+        signal.throwIfAborted();
+        total += data.byteLength;
+        if (!data.byteLength || total > MAX_INPUT_TOTAL_BYTES || data.byteLength > (resource.kind === 'image' ? MAX_INPUT_IMAGE_BYTES : MAX_INPUT_AUDIO_BYTES)) {
+            throw new MediaInputError('附件超出大小限制：单张图片 10 MB、单段语音 5 MB，每条消息合计 20 MB。');
+        }
+        if (resource.kind === 'image')
+            images.push({ data, mediaType: imageType(data) });
+        else {
+            if (!transport.recognizeSpeech)
+                throw new MediaInputError('当前消息通道没有语音识别能力，请改发文字。');
+            const pcm = await decode(data, signal);
+            try {
+                text = (await transport.recognizeSpeech(pcm, signal)).trim();
+            }
+            catch {
+                throw new MediaInputError('语音识别失败，请检查 speech_to_text:speech 权限及租户套餐，或改发文字。');
+            }
+            if (!text || text.length > options.maxText)
+                throw new MediaInputError('没有得到可用的语音文字，请缩短语音后重试。');
+            // A transcript is conversation input. It must never become a slash command or card action.
+            text = `用户发来的语音转写（可能有识别误差）：\n${text}`;
+        }
+    }
+    return { text, ...(images.length ? { images } : {}) };
+}
+//# sourceMappingURL=media-input.js.map

package/dist/media-scopes.d.ts

@@ -0,0 +1,5 @@
+/** Fixed bot scopes. UI callers choose a feature, never supply arbitrary permissions. */
+export type MediaInputKind = 'images' | 'voice';
+export declare const MEDIA_RESOURCE_SCOPE = "im:message:readonly";
+export declare const SPEECH_SCOPE = "speech_to_text:speech";
+export declare function mediaScopes(kind: MediaInputKind): readonly string[];

package/dist/media-scopes.js

@@ -0,0 +1,6 @@
+export const MEDIA_RESOURCE_SCOPE = 'im:message:readonly';
+export const SPEECH_SCOPE = 'speech_to_text:speech';
+export function mediaScopes(kind) {
+    return kind === 'voice' ? [MEDIA_RESOURCE_SCOPE, SPEECH_SCOPE] : [MEDIA_RESOURCE_SCOPE];
+}
+//# sourceMappingURL=media-scopes.js.map

package/dist/message.d.ts

@@ -6,6 +6,13 @@ export interface IncomingMessage {
     chatType: 'p2p' | 'group';
     threadId: string;
     text: string;
+    resources?: IncomingResource[];
+}
+export interface IncomingResource {
+    kind: 'image' | 'audio';
+    key: string;
+    messageId: string;
+    duration?: number;
 }
 /** Accept only the verified, compact Lark CLI event contract. Fail closed on raw/unknown events. */
 export declare function parseMessage(raw: unknown, botOpenId: string): IncomingMessage | undefined;

package/dist/message.js

@@ -6,7 +6,7 @@ export function parseMessage(raw, botOpenId) {
     const data = object(raw);
     if (!data || data.type !== 'im.message.receive_v1' || data.sender_type !== 'user')
         return;
-    if (data.message_type !== 'text' && data.message_type !== 'post')
+    if (!['text', 'post', 'image', 'audio'].includes(String(data.message_type)))
         return;
     if (!validId(data.message_id, 'om') || !validId(data.chat_id, 'oc') || !validId(data.sender_id, 'ou'))
         return;
@@ -21,6 +21,27 @@ export function parseMessage(raw, botOpenId) {
     // Text events render @name; rich posts can render <at user_id="...">.
     // Authorization always uses the structured open_id, never a display name.
     let text = data.content;
+    const resources = [];
+    // The CLI compact contract renders media markers, not the original Lark JSON.
+    // Keys stay bound to this real event's message ID; no arbitrary URL or path is accepted.
+    if (data.message_type === 'image' || data.message_type === 'post') {
+        text = text.replace(/\[Image: (img_[A-Za-z0-9_-]{1,200})\]|!\[Image\]\((img_[A-Za-z0-9_-]{1,200})\)/g, (_tag, marker, inline) => {
+            const key = (marker ?? inline);
+            if (!resources.some(resource => resource.key === key))
+                resources.push({ kind: 'image', key, messageId: data.message_id });
+            return '';
+        });
+        if (data.message_type === 'image' && (!resources.length || text.trim()))
+            return;
+    }
+    if (data.message_type === 'audio') {
+        const audio = /^<audio key="(file_[A-Za-z0-9_-]{1,200})"(?: duration="([0-9]{1,6})s")?\s*\/>$/.exec(text.trim());
+        if (!audio)
+            return;
+        resources.push({ kind: 'audio', key: audio[1], messageId: data.message_id,
+            ...(audio[2] === undefined ? {} : { duration: Number(audio[2]) }) });
+        text = '';
+    }
     for (const mention of ours) {
         if (typeof mention.key === 'string' && mention.key.length > 0)
             text = text.split(mention.key).join('');
@@ -32,12 +53,15 @@ export function parseMessage(raw, botOpenId) {
             text = text.slice(rendered.length).trimStart();
         }
     }
-    if (!text)
+    if (!text && !resources.length)
         return;
+    if (!text)
+        text = data.message_type === 'audio' ? '请处理这段语音。' : '请查看这些图片。';
     // Only a real Lark thread is its own conversation. A quote reply also carries
     // root_id, but it continues the chat's current conversation.
     const threadId = typeof data.thread_id === 'string' && /^(om|omt)_[a-zA-Z0-9_-]+$/.test(data.thread_id) ? data.thread_id : '';
-    return { messageId: data.message_id, chatId: data.chat_id, senderId: data.sender_id, chatType: data.chat_type, threadId, text };
+    return { messageId: data.message_id, chatId: data.chat_id, senderId: data.sender_id, chatType: data.chat_type, threadId, text,
+        ...(resources.length ? { resources } : {}) };
 }
 export function authorize(message, config) {
     const policy = config.users.find(user => user.openId === message.senderId);

package/dist/onboarding/agents.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentCatalog, AgentSettings } from './protocol.js';
+import { SettingsStore } from './settings-store.js';
+export declare const defaultAgentSettings: AgentSettings;
+export declare function parseAgentSettings(raw: unknown): AgentSettings;
+export declare function agentSettingsStore(directory: string): SettingsStore<AgentSettings>;
+/** A metadata-only catalog; no plugin definitions, paths, provider endpoints or secrets. */
+export declare function agentCatalog(ctx: Context): Promise<AgentCatalog>;
+export declare function validateAgentSettings(ctx: Context, settings: AgentSettings): Promise<AgentSettings>;

package/dist/onboarding/agents.js

@@ -0,0 +1,100 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { SetupError } from './controller.js';
+import { SettingsStore } from './settings-store.js';
+import { ffmpegAvailable } from '../media-input.js';
+const controls = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u;
+export const defaultAgentSettings = { label: '', agentPreset: '', workspace: '', imageInput: true, voiceInput: false };
+export function parseAgentSettings(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('Invalid agent settings');
+    const data = raw;
+    for (const [key, limit] of [['label', 80], ['agentPreset', 200], ['workspace', 4096]]) {
+        const value = data[key];
+        if (typeof value !== 'string' || value.length > limit || value !== value.trim() || controls.test(value))
+            throw new Error('Invalid agent settings');
+    }
+    if (typeof data.imageInput !== 'boolean' || typeof data.voiceInput !== 'boolean'
+        || (data.workspace && !isAbsolute(data.workspace)))
+        throw new Error('Invalid agent settings');
+    return { label: data.label, agentPreset: data.agentPreset, workspace: data.workspace,
+        imageInput: data.imageInput, voiceInput: data.voiceInput };
+}
+export function agentSettingsStore(directory) {
+    return new SettingsStore(directory, 'agent.json', parseAgentSettings);
+}
+/** A metadata-only catalog; no plugin definitions, paths, provider endpoints or secrets. */
+export async function agentCatalog(ctx) {
+    const service = ctx.get('agentPresets');
+    const available = typeof service?.list === 'function' && typeof service.resolve === 'function' && typeof service.mount === 'function';
+    const catalog = { presets: [], presetsAvailable: available, model: '跟随宿主模型',
+        imagesAvailable: typeof ctx.get('attachments')?.saveImages === 'function',
+        voiceAvailable: await ffmpegAvailable() };
+    const display = (value, limit) => typeof value === 'string' && !controls.test(value) ? value.slice(0, limit) : '';
+    if (available) {
+        const rows = await service.list();
+        if (!Array.isArray(rows) || rows.length > 200)
+            throw new SetupError('Agent 预设列表暂时不可用，请检查宿主设置。');
+        catalog.presets = rows.filter(row => typeof row.id === 'string' && row.id.length > 0 && row.id.length <= 200 && !controls.test(row.id))
+            .map(row => ({ id: row.id, name: display(row.name, 200) || row.id,
+            ...(display(row.description, 600) ? { description: display(row.description, 600) } : {}), available: !row.broken }));
+        try {
+            catalog.defaultPreset = (await service.resolve()).id;
+        }
+        catch { /* An explicit working preset is still selectable. */ }
+    }
+    const selection = ctx.get('agentDefaultModel')?.currentSelection?.();
+    if (display(selection?.model, 200))
+        catalog.model = display(selection?.model, 200);
+    catalog.modelImages = 'unknown';
+    const llm = ctx.get('llm');
+    if (selection?.provider && selection.model && typeof llm?.resolveModelInfo === 'function') {
+        const aborter = new AbortController();
+        let timer;
+        try {
+            // Adapter metadata only. No test message, Agent creation or tool execution.
+            const info = await Promise.race([
+                llm.resolveModelInfo(selection.provider, selection.model, aborter.signal),
+                new Promise(resolve => { timer = setTimeout(() => { aborter.abort(); resolve(undefined); }, 3000); }),
+            ]);
+            if (Array.isArray(info?.inputModalities))
+                catalog.modelImages = info.inputModalities.includes('image') ? 'supported' : 'unsupported';
+        }
+        catch { /* Missing metadata is shown as unknown, and checked again for the actual chat model at admission. */ }
+        finally {
+            clearTimeout(timer);
+            aborter.abort();
+        }
+    }
+    return catalog;
+}
+export async function validateAgentSettings(ctx, settings) {
+    const next = parseAgentSettings(settings);
+    if (next.agentPreset) {
+        const presets = ctx.get('agentPresets');
+        if (typeof presets?.resolve !== 'function' || typeof presets.mount !== 'function')
+            throw new SetupError('当前宿主不支持选择 Agent 预设。');
+        try {
+            const resolved = await presets.resolve(next.agentPreset);
+            if (resolved.id !== next.agentPreset || resolved.broken)
+                throw new Error();
+        }
+        catch {
+            throw new SetupError('这个 Agent 预设已不可用，请刷新后重新选择。');
+        }
+    }
+    if (next.workspace) {
+        try {
+            next.workspace = await realpath(next.workspace);
+            if (!(await stat(next.workspace)).isDirectory())
+                throw new Error();
+        }
+        catch {
+            throw new SetupError('工作区必须是这台设备上已有的文件夹。');
+        }
+    }
+    if (next.voiceInput && !await ffmpegAvailable())
+        throw new SetupError('请先在宿主设备安装 FFmpeg，再启用语音输入。');
+    return next;
+}
+//# sourceMappingURL=agents.js.map

package/dist/onboarding/controller.d.ts

@@ -3,9 +3,9 @@ import { type BotService } from '../bot-service.js';
 import { LarkPlatform } from './lark-platform.js';
 import { ConnectionStore } from './store.js';
 import { waitForPairing } from './pairing.js';
-import type { ConnectionEndpoint, ConnectionProfile, ConnectionSnapshot } from './protocol.js';
+import type { AgentSettings, ConnectionEndpoint, ConnectionProfile, ConnectionSnapshot } from './protocol.js';
 export interface OnboardingDependencies {
-    platform: Pick<LarkPlatform, 'listProfiles' | 'registerNew' | 'saveNewProfile' | 'inspect' | 'configureAndPublish'> & Partial<Pick<LarkPlatform, 'enableDocuments'>>;
+    platform: Pick<LarkPlatform, 'listProfiles' | 'registerNew' | 'saveNewProfile' | 'inspect' | 'configureAndPublish'> & Partial<Pick<LarkPlatform, 'enableDocuments' | 'enableInput'>>;
     store: ConnectionStore;
     checkRuntime(): void;
     start(config: BotConfig, signal: AbortSignal, onHealth: (ready: boolean) => void, pairedChat?: {
@@ -19,6 +19,10 @@ export interface OnboardingDependencies {
     executable?: string;
     /** Delay before automatic restore attempt `attempt` (0-based) of an enabled connection. */
     retryDelay?: (attempt: number) => number;
+    validateAgent?: (settings: AgentSettings) => Promise<AgentSettings>;
+    reserveApp?: (appId: string) => void;
+    /** Release former reservations only after the replacement record is durable. */
+    commitApp?: (appId: string) => void;
 }
 export declare class SetupError extends Error {
     readonly retryable: boolean;
@@ -39,20 +43,27 @@ export declare class ConnectionController {
     private unsafeStop;
     private menuReady;
     private documentsReady;
+    private imagesReady;
+    private voiceReady;
     /** Menu entries the published app lacks; the owner adds them in the developer console. */
     private menuMissing;
     private documentSetup?;
     private documentJob?;
+    private inputSetup?;
     private documentAborter?;
     private candidate?;
     private commands;
     private retryTimer?;
     private retryAttempts;
+    private settings;
+    private readonly settingsStore;
+    private settingsFailed;
     constructor(deps: OnboardingDependencies);
     snapshot(): ConnectionSnapshot;
     private phase;
     private action;
     private consoleUrl;
+    private inspectCapabilities;
     private assertCurrent;
     private save;
     private launch;
@@ -68,6 +79,8 @@ export declare class ConnectionController {
     command(endpoint: Exclude<ConnectionEndpoint, 'profiles' | 'status'>, payload: unknown): Promise<ConnectionSnapshot>;
     private create;
     private check;
+    private botDirectory;
+    private defaultWorkspace;
     private config;
     private bind;
     private start;