dsh-lark-agent 0.1.2 → 0.2.0

package/dist/interaction-cards.js

@@ -0,0 +1,119 @@
+import { cardMarkdown, renderPanel, safePlainText } from './replies.js';
+const code = (value) => '`' + value.replace(/`/g, 'ˋ') + '`';
+/** A fence longer than any backtick run inside keeps the arguments one code block. */
+function fenced(text) {
+    const marks = '`'.repeat(Math.max(2, ...Array.from(text.matchAll(/`+/g), match => match[0].length)) + 1);
+    return `${marks}\n${text}\n${marks}`;
+}
+/** Buttons answer one short single-choice question in one tap; anything else uses a form. */
+export function simpleQuestion(questions) {
+    const only = questions[0];
+    return questions.length === 1 && !only.multiSelect && only.options.length >= 1 && only.options.length <= 6;
+}
+/** The decision card. Without tokens it shows the settled outcome and no buttons. */
+export function approvalCard(prompt, tokens, outcome) {
+    return renderPanel({
+        title: tokens ? '需要你确认' : '确认结果',
+        summary: `是否允许使用工具 ${prompt.toolName}`,
+        sections: [
+            { title: '工具', text: code(prompt.toolName) },
+            ...(prompt.reason ? [{ title: '原因', text: prompt.reason }] : []),
+            ...(prompt.detail ? [{ title: '参数', text: fenced(prompt.detail) }] : []),
+            ...(outcome ? [{ text: `**${outcome}**` }] : []),
+        ],
+        ...(tokens ? { actions: [{ label: '允许一次', value: { token: tokens.allow }, primary: true }, { label: '拒绝', value: { token: tokens.deny } }],
+            actionColumns: 2, note: '只允许这一次，不改变电脑上的权限设置。5 分钟内没有确认会按拒绝处理。' } : {}),
+    });
+}
+function questionText(question) {
+    return [`**${question.question}**`,
+        ...question.options.filter(option => option.description).map(option => `- ${option.label}：${option.description}`),
+        ...(question.detail ? [question.detail] : [])].join('\n');
+}
+/** A question card: buttons for one short choice, otherwise a form. Without tokens it shows the outcome. */
+export function questionCard(questions, tokens, outcome) {
+    const first = questions[0];
+    const title = questions.length === 1 && first.header ? first.header : '需要你选择';
+    const form = Boolean(tokens?.reply);
+    const base = renderPanel({
+        title, summary: `${title}：${first.question}`,
+        sections: [
+            ...(form ? [{ text: questions.length > 1 ? `请回答下面 ${questions.length} 个问题，然后提交。` : '请选择或填写后提交。' }]
+                : questions.map(question => ({ text: questionText(question) }))),
+            ...(outcome ? [{ text: `**${outcome}**` }] : []),
+        ],
+        ...(tokens?.choose ? { actions: [...first.options.map((option, index) => ({ label: option.label, value: { token: tokens.choose[index] }, primary: index === 0 })),
+                { label: '跳过', value: { token: tokens.choose[first.options.length] } }], actionColumns: 1 } : {}),
+        ...(tokens ? { note: '10 分钟内没有回答，Harness 会按未回答继续。' } : {}),
+    });
+    if (!form || base.kind !== 'card')
+        return base;
+    const plain = (content) => ({ tag: 'plain_text', content: safePlainText(content) });
+    base.card.body.elements.push({ tag: 'form', name: 'dsh_result_form', elements: [
+            // Field names come from positions, never from the model-chosen question IDs.
+            ...questions.flatMap((question, index) => [
+                { tag: 'markdown', content: cardMarkdown(questionText(question)) },
+                ...(question.options.length ? [{ tag: question.multiSelect ? 'multi_select_static' : 'select_static', name: `q${index}`,
+                        placeholder: plain(question.multiSelect ? '可多选' : '请选择'), required: false, width: 'fill',
+                        options: question.options.map((option, choice) => ({ text: plain(option.label), value: `o${choice}` })) }] : []),
+                { tag: 'input', name: `c${index}`, placeholder: plain(question.options.length ? '其他想法（可选）' : '在这里输入'),
+                    input_type: 'text', max_length: 1000, required: false, width: 'fill' },
+            ]),
+            { tag: 'button', name: 'dsh_submit', form_name: 'dsh_result_form', text: plain('提交'), type: 'primary', action_type: 'form_submit',
+                form_action_type: 'submit', behaviors: [{ type: 'callback', value: { token: tokens.reply } }] },
+        ] });
+    // An oversized question cannot be asked by card; the caller then lets the model ask in text.
+    if (Buffer.byteLength(JSON.stringify({ msg_type: 'interactive', content: JSON.stringify(base.card) })) > 27_000)
+        return { kind: 'text', text: base.fallbackText };
+    return base;
+}
+/** Map a click or form back to the host's answer shape, echoing the original option labels. */
+export function questionAnswers(questions, answer) {
+    if (answer.verb === 'choose') {
+        if (!simpleQuestion(questions) || answer.index === undefined)
+            return;
+        const question = questions[0];
+        if (answer.index === question.options.length)
+            return [{ id: question.id, selected: [] }];
+        const option = question.options[answer.index];
+        return option ? [{ id: question.id, selected: [option.label] }] : undefined;
+    }
+    if (answer.verb !== 'reply' || !answer.formValues || typeof answer.formValues !== 'object' || Array.isArray(answer.formValues))
+        return;
+    const values = answer.formValues;
+    const fields = new Set(questions.flatMap((question, index) => [...(question.options.length ? [`q${index}`] : []), `c${index}`]));
+    if (Object.keys(values).some(key => !fields.has(key)))
+        return;
+    const answers = [];
+    for (const [index, question] of questions.entries()) {
+        const raw = values[`q${index}`];
+        const picked = raw === undefined || raw === null || raw === '' ? [] : Array.isArray(raw) ? raw : [raw];
+        if (!question.multiSelect && picked.length > 1)
+            return;
+        let selected = [];
+        for (const value of picked) {
+            const choice = typeof value === 'string' ? /^o([0-9]{1,2})$/.exec(value)?.[1] : undefined;
+            const option = choice === undefined ? undefined : question.options[Number(choice)];
+            if (!option || selected.includes(option.label))
+                return;
+            selected.push(option.label);
+        }
+        const custom = values[`c${index}`];
+        if (custom !== undefined && custom !== null && (typeof custom !== 'string' || custom.length > 1000))
+            return;
+        const text = typeof custom === 'string' ? custom.trim() : '';
+        // For a single choice, typed text replaces the selection, as the host defines.
+        if (text && !question.multiSelect)
+            selected = [];
+        answers.push({ id: question.id, selected, ...(text ? { custom: text } : {}) });
+    }
+    return answers;
+}
+export function answeredText(questions, answers) {
+    if (questions.length !== 1)
+        return '已提交回答。';
+    const [answer] = answers;
+    const value = answer?.custom ?? answer?.selected.join('、');
+    return value ? `已回答：${value}` : '已跳过这个问题。';
+}
+//# sourceMappingURL=interaction-cards.js.map

package/dist/lark-cli.d.ts

@@ -58,6 +58,30 @@ export declare class LarkCli {
     /** Replace one bot-owned loading/interactive card, never retry an unknown update. */
     updateFeedback(messageId: string, payload: ReplyPayload): Promise<void>;
     private feedbackContent;
+    /** Create a CardKit card entity. Nothing reaches a chat yet, so a failure needs no delivery guard. */
+    createCardEntity(card: Record<string, unknown>): Promise<string>;
+    /** Reply with a card entity. An unconfirmed reply may still have been delivered; never resend it. */
+    replyCardEntity(messageId: string, cardId: string, options: {
+        idempotencyKey: string;
+        inThread: boolean;
+    }): Promise<void>;
+    /** Stream one element's complete text. Any later update supersedes a failed one. */
+    streamCardText(cardId: string, elementId: string, content: string, sequence: number): Promise<void>;
+    /** Replace a card entity. Applying the same state twice is harmless, so callers may retry with a newer sequence. */
+    updateCardEntity(cardId: string, card: Record<string, unknown>, sequence: number): Promise<void>;
+    /**
+     * Reply with one local file the caller has already validated. Only a
+     * `./basename` crosses argv, resolved from the file's own directory, so it
+     * can never be read as an upload key, a URL or another flag.
+     */
+    replyFile(messageId: string, path: string, options: {
+        idempotencyKey: string;
+        inThread: boolean;
+        image: boolean;
+    }): Promise<void>;
+    private cardEntityData;
+    private static cardId;
+    private static sequence;
     private confirmFeedback;
     /** Menu events have no message ID: create a message for the verified actor instead. */
     sendRichUser(openId: string, payload: ReplyPayload, options: {

package/dist/lark-cli.js

@@ -1,4 +1,6 @@
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, isAbsolute } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 const DEFAULT_EVENT_KEY = 'im.message.receive_v1';
 const MAX_OUTPUT_BYTES = 1_048_576;
@@ -126,11 +128,12 @@ export class LarkCli {
         this.readyTimeoutMs = timeout(options.readyTimeoutMs, 30_000);
         this.commandTimeoutMs = timeout(options.commandTimeoutMs, 30_000);
     }
-    launch(args) {
+    launch(args, cwd) {
         return spawn(this.executable, ['--profile', this.profile, ...args], {
             shell: false,
             windowsHide: true,
             stdio: 'pipe',
+            ...(cwd ? { cwd } : {}),
         });
     }
     start(onEvent, onError) {
@@ -388,6 +391,91 @@ export class LarkCli {
             throw new Error('Invalid Lark feedback card.');
         }
     }
+    /** Create a CardKit card entity. Nothing reaches a chat yet, so a failure needs no delivery guard. */
+    async createCardEntity(card) {
+        const data = this.cardEntityData(card);
+        const result = await this.executeJson(['api', 'POST', '/open-apis/cardkit/v1/cards', '--data', '-', '--as', 'bot', '--format', 'json'], JSON.stringify({ type: 'card_json', data }), 'card', Math.min(this.commandTimeoutMs, 10_000));
+        this.confirmFeedback(result);
+        const receipt = result.data;
+        if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt) || !LarkCli.cardId(receipt.card_id)) {
+            throw new Error('Lark card entity creation was not confirmed.');
+        }
+        return receipt.card_id;
+    }
+    /** Reply with a card entity. An unconfirmed reply may still have been delivered; never resend it. */
+    async replyCardEntity(messageId, cardId, options) {
+        if (typeof messageId !== 'string' || !/^om_[A-Za-z0-9_-]{1,256}$/.test(messageId) || !LarkCli.cardId(cardId)
+            || typeof options?.idempotencyKey !== 'string' || !/^[A-Za-z0-9._:-]{1,50}$/.test(options.idempotencyKey)
+            || typeof options.inThread !== 'boolean')
+            throw new Error('Invalid Lark card reply.');
+        const body = JSON.stringify({ msg_type: 'interactive', content: JSON.stringify({ type: 'card', data: { card_id: cardId } }),
+            uuid: options.idempotencyKey, reply_in_thread: options.inThread });
+        const result = await this.executeJson(['api', 'POST', `/open-apis/im/v1/messages/${messageId}/reply`,
+            '--data', '-', '--as', 'bot', '--format', 'json'], body, 'reply', this.commandTimeoutMs);
+        this.confirmFeedback(result);
+        const receipt = result.data;
+        if (!receipt || typeof receipt !== 'object' || typeof receipt.message_id !== 'string' || !/^om_[A-Za-z0-9_-]{1,256}$/.test(receipt.message_id)) {
+            throw new Error('Lark card reply was not confirmed; delivery is unknown.');
+        }
+    }
+    /** Stream one element's complete text. Any later update supersedes a failed one. */
+    async streamCardText(cardId, elementId, content, sequence) {
+        if (!LarkCli.cardId(cardId) || typeof elementId !== 'string' || !/^[a-z][a-z0-9_]{0,19}$/.test(elementId)
+            || typeof content !== 'string' || !content || Buffer.byteLength(content) > 100_000 || !LarkCli.sequence(sequence)) {
+            throw new Error('Invalid Lark card stream update.');
+        }
+        const result = await this.executeJson(['api', 'PUT', `/open-apis/cardkit/v1/cards/${cardId}/elements/${elementId}/content`,
+            '--data', '-', '--as', 'bot', '--format', 'json'], JSON.stringify({ content, sequence, uuid: randomUUID() }), 'card', Math.min(this.commandTimeoutMs, 10_000));
+        this.confirmFeedback(result);
+    }
+    /** Replace a card entity. Applying the same state twice is harmless, so callers may retry with a newer sequence. */
+    async updateCardEntity(cardId, card, sequence) {
+        if (!LarkCli.cardId(cardId) || !LarkCli.sequence(sequence))
+            throw new Error('Invalid Lark card update.');
+        const data = this.cardEntityData(card);
+        const result = await this.executeJson(['api', 'PUT', `/open-apis/cardkit/v1/cards/${cardId}`, '--data', '-', '--as', 'bot', '--format', 'json'], JSON.stringify({ card: { type: 'card_json', data }, sequence, uuid: randomUUID() }), 'card', Math.min(this.commandTimeoutMs, 10_000));
+        this.confirmFeedback(result);
+    }
+    /**
+     * Reply with one local file the caller has already validated. Only a
+     * `./basename` crosses argv, resolved from the file's own directory, so it
+     * can never be read as an upload key, a URL or another flag.
+     */
+    async replyFile(messageId, path, options) {
+        const name = typeof path === 'string' ? basename(path) : '';
+        if (typeof messageId !== 'string' || !/^om_[A-Za-z0-9_-]{1,256}$/.test(messageId) || typeof path !== 'string' || !isAbsolute(path)
+            || /[\\/]$/.test(path) || !name || name.length > 255 || /[\u0000-\u001f\u007f/\\]/.test(name) || name === '.' || name === '..'
+            || typeof options?.idempotencyKey !== 'string' || !/^[A-Za-z0-9._:-]{1,50}$/.test(options.idempotencyKey)
+            || typeof options.inThread !== 'boolean' || typeof options.image !== 'boolean')
+            throw new Error('Invalid Lark file reply.');
+        const args = ['im', '+messages-reply', '--message-id', messageId, `--${options.image ? 'image' : 'file'}=./${name}`,
+            '--as', 'bot', '--format', 'json', '--idempotency-key', options.idempotencyKey];
+        if (options.inThread)
+            args.push('--reply-in-thread');
+        // Uploads take longer than text; the deadline still bounds an unknown result.
+        await this.executeJson(args, '', 'reply', Math.max(this.commandTimeoutMs, 120_000), dirname(path));
+    }
+    cardEntityData(card) {
+        let data;
+        try {
+            if (!card || typeof card !== 'object' || Array.isArray(card) || card.schema !== '2.0')
+                throw new Error();
+            data = JSON.stringify(card);
+        }
+        catch {
+            throw new Error('Invalid Lark card entity.');
+        }
+        // CardKit rejects cards over 30 KB; keep a margin for the request envelope.
+        if (Buffer.byteLength(data) > 28_500)
+            throw new Error('Lark card entity exceeds the size limit.');
+        return data;
+    }
+    static cardId(value) {
+        return typeof value === 'string' && /^[0-9A-Za-z_-]{1,64}$/.test(value);
+    }
+    static sequence(value) {
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= 2_147_483_647;
+    }
     confirmFeedback(result) {
         if (result.identity !== 'bot' || (result.dry_run !== undefined && result.dry_run !== false)) {
             throw new Error('Lark feedback command did not confirm bot delivery; delivery is unknown.');
@@ -509,15 +597,15 @@ export class LarkCli {
             args.push('--reply-in-thread');
         return this.executeJson(args, input, 'reply', this.commandTimeoutMs).then(() => undefined);
     }
-    executeJson(args, input, operation, deadlineMs) {
+    executeJson(args, input, operation, deadlineMs, cwd) {
         if (this.stopped)
             return Promise.reject(new Error('Lark transport is stopped.'));
         const label = `Lark ${operation} command`;
-        const uncertain = operation === 'progress' ? 'result is unknown.' : 'delivery is unknown.';
+        const uncertain = operation === 'progress' || operation === 'card' ? 'result is unknown.' : 'delivery is unknown.';
         return new Promise((resolve, reject) => {
             let child;
             try {
-                child = this.launch(args);
+                child = this.launch(args, cwd);
             }
             catch {
                 reject(new Error(`Could not start the Lark ${operation} command.`));

package/dist/live-reply.d.ts

@@ -0,0 +1,87 @@
+import type { TurnStreamEvent } from './dsh-runtime.js';
+export interface LiveCardTransport {
+    createCardEntity(card: Record<string, unknown>): Promise<string>;
+    replyCardEntity(messageId: string, cardId: string, options: {
+        idempotencyKey: string;
+        inThread: boolean;
+    }): Promise<void>;
+    streamCardText(cardId: string, elementId: string, content: string, sequence: number): Promise<void>;
+    updateCardEntity(cardId: string, card: Record<string, unknown>, sequence: number): Promise<void>;
+}
+export interface LiveReplyOptions {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    audit?: (stage: string) => void;
+}
+export interface LiveReplyFinal {
+    phase: 'done' | 'stopped' | 'failed';
+    /** Authoritative answer text; replaces whatever was streamed. */
+    answer?: string;
+    reasoning?: string;
+    /** Trusted application text shown under the answer. */
+    note?: string;
+}
+/**
+ * One streaming reply card: the answer, with reasoning and tool steps in a
+ * panel that stays folded unless the reader opens it. Only the initial reply
+ * is a send; every later operation updates the same card entity and is safe
+ * to supersede or repeat. A reply never continues in another message.
+ */
+export declare class LiveReply {
+    private readonly transport;
+    private readonly target;
+    private readonly options;
+    private phase;
+    private readonly steps;
+    private trimmed;
+    private answer;
+    private separator;
+    private mark;
+    private tools;
+    private note?;
+    private cardId?;
+    private sequence;
+    private readonly sent;
+    private dirty;
+    private layoutDirty;
+    private degraded;
+    private streamFailures;
+    private closed;
+    private loop?;
+    private wake?;
+    private streamingSince;
+    private readonly startedAt;
+    private answeredAt?;
+    private finishedAt?;
+    constructor(transport: LiveCardTransport, target: {
+        messageId: string;
+        inThread: boolean;
+        idempotencyKey: string;
+    }, options?: LiveReplyOptions);
+    /** Send the card. False means nothing was sent, so the caller keeps its ordinary reply. */
+    open(): Promise<boolean>;
+    push(event: TurnStreamEvent): void;
+    /** Stop streaming and write the final card. True only when Feishu confirmed it. */
+    finish(final: LiveReplyFinal): Promise<boolean>;
+    private now;
+    private sleep;
+    private audit;
+    /** Keep only what the card can still show; the turn result stays authoritative. */
+    private trim;
+    private schedule;
+    private run;
+    /** Pacing between updates; finishing the reply ends it early. */
+    private pause;
+    private flush;
+    private markSent;
+    private stepsMarkdown;
+    private thinkContent;
+    private answerContent;
+    private panelTitle;
+    /** The folded process panel. Readers open it when they want the reasoning and tool steps. */
+    private panel;
+    /** Live layout when steps is undefined; a final layout otherwise ('' leaves out the panel). */
+    private card;
+    /** The answer comes first. The folded process only gets the space that is left. */
+    private finalCard;
+}