dsh-caduceus 0.7.0 → 0.10.5

package/dist/index.js

@@ -16,9 +16,11 @@ import { dirname, join } from 'node:path';
 import { backfillSessionOwnership, scanSessionDirs } from './backfill.js';
 import { Bridge } from './bridge/bridge.js';
 import { runHarnessCommand } from './commands/harness.js';
+import { cleanupExportCache, parseSessionEvents } from './export.js';
+import { resolveLang } from './i18n.js';
 import { Config, accessControlWarning, resolveGatewayConfig, } from './config.js';
 import { FileLogger } from './file-logger.js';
-import { defaultLogPath } from './home.js';
+import { defaultExportCacheDir, defaultLogPath } from './home.js';
 import { adaptLogger, teeLoggers } from './logger.js';
 import { formatStartupLine } from './observability.js';
 import { autoSyncPersona } from './persona/auto-sync.js';
@@ -140,6 +142,9 @@ export function apply(ctx, config = {}) {
         busyMode: resolved.bridge.busyMode,
     }));
     logger.info(`agent preset=${resolved.agentPreset}`);
+    if (resolved.approvalPolicy !== undefined) {
+        logger.info(`approval policy override=${resolved.approvalPolicy}`);
+    }
     const accessWarning = accessControlWarning(resolved.bridge.admins ?? []);
     if (accessWarning !== undefined)
         logger.warn(accessWarning);
@@ -177,6 +182,10 @@ export function apply(ctx, config = {}) {
         },
         logger,
         sendCard: (sessionId, card) => bridge.sendInteractiveCard(sessionId, card),
+        permissionSwitch: (action, name) => {
+            void bridge.handlePermissionCardAction(action, name);
+        },
+        turnStop: (action) => bridge.handleStopCardAction(action),
         updateCard: (messageId, card) => transport.updateCard(messageId, card),
     });
     transport.onCardAction?.((action) => {
@@ -197,6 +206,31 @@ export function apply(ctx, config = {}) {
         rootCtx: ctx,
         approvalProvider: () => ctx.get('approval'),
         attachmentProvider: () => ctx.get('attachments'),
+        permissionPresetsProvider: () => ctx.get('permissionPresets'),
+        usageProvider: async (sessionId) => {
+            const query = ctx.get('sessionQuery');
+            if (query?.readSession === undefined)
+                return undefined;
+            const snapshot = await query.readSession(sessionId);
+            return snapshot.events ?? [];
+        },
+        languageProvider: () => resolveLang(resolved.lang, () => ctx.get('settings')),
+        exportProvider: async (sessionId) => {
+            const query = ctx.get('sessionQuery');
+            if (query?.readSession === undefined)
+                return undefined;
+            try {
+                const snapshot = await query.readSession(sessionId);
+                const events = snapshot.events ?? [];
+                return {
+                    messages: parseSessionEvents(events),
+                    rawJsonl: events.map((event) => JSON.stringify(event)).join('\n') + '\n',
+                };
+            }
+            catch {
+                return undefined;
+            }
+        },
         approvalPolicy: resolved.approvalPolicy,
         sessionPresetLookup: (sessionId) => ctx.get('sessions')?.get(sessionId)?.header
             ?.agentPreset,
@@ -262,6 +296,19 @@ export function apply(ctx, config = {}) {
             logger.error(`inbound message failed: ${errorText(error)}`);
         });
     });
+    const exportCacheDir = defaultExportCacheDir();
+    try {
+        mkdirSync(exportCacheDir, { recursive: true });
+    }
+    catch (error) {
+        logger.warn(`export cache dir unavailable (${exportCacheDir}): ${errorText(error)}`);
+    }
+    try {
+        cleanupExportCache(exportCacheDir, resolved.exportCacheMaxAgeHours, Date.now(), logger);
+    }
+    catch (error) {
+        logger.warn(`export cache cleanup failed: ${errorText(error)}`);
+    }
     ctx.on('session/event', (session, event) => {
         const sessionId = String(session.id);
         if (!bridge.ownsSession(sessionId))

package/dist/interactive/approval.js

@@ -39,7 +39,7 @@ export function createApprovalAnswerer(host, contextFor) {
             meta: { toolName: request.toolName, message: request.reason },
         });
         host.logger.info(`interactive: approval request id=${entry.id} questions=0 scope=${context.scopeKey}`);
-        const card = approvalCard(entry.id, context.sessionId, request.toolName, request.reason);
+        const card = approvalCard(entry.id, context.sessionId, request.toolName, request.reason, context.permissionLine);
         let timer;
         const onAbort = () => {
             if (host.pending.delete(entry.id) === undefined)

package/dist/interactive/cards.d.ts

@@ -2,13 +2,14 @@ import type { FeishuCard, FeishuCardElement } from '../transport/types.js';
 export interface CardButton {
     readonly label: string;
     readonly type?: 'primary' | 'danger' | 'default';
+    readonly disabled?: boolean;
     readonly value: Record<string, unknown>;
 }
 /** A card with optional buttons. */
 export declare function interactiveCard(title: string, lines: readonly string[], buttons?: readonly CardButton[], template?: string): FeishuCard;
 /** Card from pre-built elements (forms, inputs, action rows). */
 export declare function interactiveElementsCard(title: string, elements: readonly FeishuCardElement[], template?: string): FeishuCard;
-export declare function approvalCard(requestId: string, sessionId: string, toolName: string, reason: string | undefined): FeishuCard;
+export declare function approvalCard(requestId: string, sessionId: string, toolName: string, reason: string | undefined, permissionLine?: string): FeishuCard;
 export declare function approvalTerminalCard(toolName: string, outcome: string): FeishuCard;
 export interface QuestionCardInput {
     readonly requestId: string;

package/dist/interactive/cards.js

@@ -14,6 +14,7 @@ function actionRow(buttons) {
             tag: 'button',
             text: { tag: 'plain_text', content: button.label },
             type: button.type ?? 'default',
+            ...(button.disabled === true ? { disabled: true } : {}),
             value: button.value,
         })),
     };
@@ -29,8 +30,9 @@ export function interactiveCard(title, lines, buttons = [], template = 'orange')
 export function interactiveElementsCard(title, elements, template = 'orange') {
     return buildCard({ title, template, elements });
 }
-export function approvalCard(requestId, sessionId, toolName, reason) {
+export function approvalCard(requestId, sessionId, toolName, reason, permissionLine) {
     return interactiveCard(`审批请求 · ${toolName}`, [
+        ...(permissionLine === undefined ? [] : [permissionLine]),
         reason === undefined || reason.trim().length === 0 ? '（无说明）' : reason,
     ], [
         {

package/dist/interactive/runtime.d.ts

@@ -18,6 +18,10 @@ export interface InteractiveRuntimeOptions {
         readonly threadId?: string;
     }>;
     updateCard(messageId: string, card: FeishuCard): Promise<void>;
+    /** Button callback for the permission card (`caduceus.permission.switch`). */
+    permissionSwitch?(action: CardAction, name: string): void | Promise<void>;
+    /** Button callback for the process-card stop button. */
+    turnStop?(action: CardAction): void | Promise<void>;
 }
 export declare class InteractiveRuntime {
     #private;

package/dist/interactive/runtime.js

@@ -12,12 +12,16 @@ export class InteractiveRuntime {
     pending = new PendingRegistry();
     #sendCard;
     #updateCard;
+    #permissionSwitch;
+    #turnStop;
     constructor(options) {
         this.config = options.config;
         this.logger = options.logger ?? silentLogger();
         this.clock = options.clock ?? systemClock;
         this.#sendCard = options.sendCard;
         this.#updateCard = options.updateCard;
+        this.#permissionSwitch = options.permissionSwitch;
+        this.#turnStop = options.turnStop;
     }
     /**
      * Register both waterfall answerers ONCE on the plugin root context, as dsh's
@@ -58,6 +62,17 @@ export class InteractiveRuntime {
      * a warning and do not resolve or patch anything.
      */
     async handleCardAction(action) {
+        if (action.value['action'] === 'caduceus.turn.stop') {
+            this.logger.info(`card action stop operator=${logPrefix(action.operatorOpenId)}`);
+            await this.#turnStop?.(action);
+            return;
+        }
+        if (action.value['action'] === 'caduceus.permission.switch' &&
+            typeof action.value['name'] === 'string') {
+            this.logger.info(`card action permission switch name=${action.value['name']} operator=${logPrefix(action.operatorOpenId)}`);
+            await this.#permissionSwitch?.(action, action.value['name']);
+            return;
+        }
         const id = typeof action.value['id'] === 'string' ? action.value['id'] : undefined;
         if (id === undefined) {
             this.logger.info('card action ignored (unknown id)');

package/dist/interactive/types.d.ts

@@ -26,6 +26,8 @@ export interface InteractiveContext {
     readonly chatId: string;
     readonly ownerOpenId: string;
     readonly sessionId: string;
+    /** Optional permission summary line for approval cards. */
+    readonly permissionLine?: string;
 }
 /** A Cordis context (the plugin root or an agent scope); only `on` is needed. */
 export interface EventScopeLike {

package/dist/metrics.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Card/`/usage` metrics aggregated from durable session events:
+ * rounds, steps, tok/s, cumulative tokens, cache hit rate, context usage.
+ *
+ * These are deliberately derived from the event log (not the in-memory status
+ * tracker), so a restarted gateway can still show the same numbers.
+ *
+ * @module dsh-caduceus/metrics
+ */
+export type MetricsMode = 'off' | 'compact' | 'detailed';
+export interface Metrics {
+    readonly rounds: number;
+    readonly steps: number;
+    readonly tokensPerSecond?: number;
+    readonly totalTokens: number;
+    /** Raw sums (used when merging an in-flight turn with the full log). */
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheHitPercent?: number;
+    readonly contextPercent?: number;
+}
+/** Aggregate metrics from one session event sequence. */
+export declare function aggregateMetrics(events: readonly unknown[]): Metrics;
+/** Compact number format: 999, 1.6k, 7.9M. */
+export declare function formatTokenCount(value: number): string;
+/** One-line metrics summary; empty when mode is off or nothing to show. */
+export declare function formatMetricsLine(metrics: Metrics, mode: MetricsMode): string;

package/dist/metrics.js

@@ -0,0 +1,135 @@
+function asRecord(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : undefined;
+}
+function num(record, key) {
+    const value = record?.[key];
+    return typeof value === 'number' ? value : 0;
+}
+function usageDelta(value) {
+    const record = asRecord(value);
+    if (record === undefined)
+        return undefined;
+    const input = num(record, 'inputTokens');
+    const output = num(record, 'outputTokens');
+    const cacheRead = num(record, 'cacheReadTokens');
+    const cacheWrite = num(record, 'cacheWriteTokens');
+    const providerTotal = typeof record['totalTokens'] === 'number' ? record['totalTokens'] : 0;
+    if (input === 0 && output === 0 && cacheRead === 0 && cacheWrite === 0 && providerTotal === 0) {
+        return undefined;
+    }
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        total: providerTotal > 0 ? providerTotal : input + output + cacheRead + cacheWrite,
+    };
+}
+/** Aggregate metrics from one session event sequence. */
+export function aggregateMetrics(events) {
+    let rounds = 0;
+    let steps = 0;
+    let totalTokens = 0;
+    let cacheRead = 0;
+    let input = 0;
+    let outputTotal = 0;
+    const outputByTurn = new Map();
+    const promptByTurn = new Map();
+    const startByTurn = new Map();
+    const endByTurn = new Map();
+    let lastEventAt;
+    let contextWindow;
+    for (const event of events) {
+        const row = asRecord(event);
+        if (row === undefined)
+            continue;
+        const data = asRecord(row.data);
+        const time = typeof row.time === 'number' ? row.time : undefined;
+        if (time !== undefined)
+            lastEventAt = time;
+        const turn = typeof data?.['turn'] === 'number' ? data['turn'] : undefined;
+        if (turn !== undefined)
+            rounds = Math.max(rounds, turn);
+        if (row.type === 'turn/start' && turn !== undefined && time !== undefined) {
+            startByTurn.set(turn, time);
+        }
+        if (row.type === 'turn/end' && turn !== undefined && time !== undefined) {
+            endByTurn.set(turn, time);
+        }
+        if (row.type === 'step/start')
+            steps += 1;
+        if (row.type === 'request/context') {
+            const window = num(data, 'contextWindow');
+            if (window > 0)
+                contextWindow = window;
+        }
+        if (row.type !== 'assistant/message')
+            continue;
+        const delta = usageDelta(data?.usage);
+        if (delta === undefined)
+            continue;
+        totalTokens += delta.total;
+        cacheRead += delta.cacheRead;
+        input += delta.input;
+        outputTotal += delta.output;
+        if (turn !== undefined) {
+            outputByTurn.set(turn, (outputByTurn.get(turn) ?? 0) + delta.output);
+            promptByTurn.set(turn, (promptByTurn.get(turn) ?? 0) + delta.input + delta.cacheRead + delta.cacheWrite);
+        }
+    }
+    let tokensPerSecond;
+    const start = startByTurn.get(rounds);
+    const end = endByTurn.get(rounds) ?? lastEventAt;
+    const output = outputByTurn.get(rounds) ?? 0;
+    if (start !== undefined && end !== undefined && end - start >= 1000 && output > 0) {
+        tokensPerSecond = output / ((end - start) / 1000);
+    }
+    const promptTokens = promptByTurn.get(rounds - 1);
+    const contextPercent = contextWindow !== undefined && promptTokens !== undefined && contextWindow > 0
+        ? Math.round((promptTokens / contextWindow) * 100)
+        : undefined;
+    const denominator = cacheRead + input;
+    const cacheHitPercent = denominator > 0 ? Math.round((cacheRead / denominator) * 100) : undefined;
+    return {
+        rounds,
+        steps,
+        totalTokens,
+        inputTokens: input,
+        outputTokens: outputTotal,
+        cacheReadTokens: cacheRead,
+        ...(tokensPerSecond === undefined ? {} : { tokensPerSecond }),
+        ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }),
+        ...(contextPercent === undefined ? {} : { contextPercent }),
+    };
+}
+/** Compact number format: 999, 1.6k, 7.9M. */
+export function formatTokenCount(value) {
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(1)}k`;
+    return String(Math.round(value));
+}
+/** One-line metrics summary; empty when mode is off or nothing to show. */
+export function formatMetricsLine(metrics, mode) {
+    if (mode === 'off')
+        return '';
+    const parts = [];
+    if (metrics.rounds > 0)
+        parts.push(`${metrics.rounds} 轮`);
+    if (metrics.steps > 0)
+        parts.push(`${metrics.steps} 步`);
+    if (metrics.tokensPerSecond !== undefined) {
+        parts.push(`${Math.round(metrics.tokensPerSecond)} tok/s`);
+    }
+    if (metrics.totalTokens > 0)
+        parts.push(`${formatTokenCount(metrics.totalTokens)} tok`);
+    if (metrics.cacheHitPercent !== undefined)
+        parts.push(`缓存 ${metrics.cacheHitPercent}%`);
+    if (mode === 'detailed' && metrics.contextPercent !== undefined) {
+        parts.push(`上下文 ${metrics.contextPercent}%`);
+    }
+    return parts.join(' · ');
+}

package/dist/render/cards.d.ts

@@ -26,6 +26,10 @@ export declare function buildCard(input: CardInput): FeishuCard;
 export declare function tailText(text: string, maxBytes?: number): string;
 export interface ProgressCardInput {
     readonly title: string;
+    /** Extra status lines (compaction, teammate, stop requested). */
+    readonly extraLines?: readonly string[];
+    /** Show the stop button (running turns only). */
+    readonly stopButton?: boolean;
     readonly stateLabel: string;
     readonly steps: number;
     readonly tools: number;

package/dist/render/cards.js

@@ -64,9 +64,26 @@ export function progressCard(input) {
         div(stateLine.join(' · ')),
         div(`最近：${clipLabel(input.recentEvent ?? '（无）')}`),
     ];
+    for (const line of input.extraLines ?? []) {
+        if (line.trim().length > 0)
+            elements.push(div(line));
+    }
     const tail = input.tail === undefined ? '' : tailText(input.tail);
     if (tail.trim().length > 0)
         elements.push(div(tail));
+    if (input.stopButton === true) {
+        elements.push({
+            tag: 'action',
+            actions: [
+                {
+                    tag: 'button',
+                    text: { tag: 'plain_text', content: '停止' },
+                    type: 'danger',
+                    value: { action: 'caduceus.turn.stop' },
+                },
+            ],
+        });
+    }
     elements.push(div('_过程消息；收尾会把终稿更新到本卡。_'));
     return buildCard({ title: input.title, template: 'blue', elements });
 }

package/dist/render/permission-card.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Permission UI rendered once as a Feishu card and once as plain text (the
+ * send-failure fallback). Both consume the same data and the same i18n dict.
+ *
+ * @module dsh-caduceus/render/permission-card
+ */
+import type { FeishuCard } from '../transport/types.js';
+import type { Lang } from '../i18n.js';
+export interface PermissionPresetView {
+    readonly name: string;
+    readonly sandbox?: string;
+    readonly approval?: string;
+    /** False/absent when resolve failed: render the bare name only. */
+    readonly resolved?: boolean;
+}
+export interface PermissionView {
+    readonly lang: Lang;
+    readonly current: string;
+    readonly presets: readonly PermissionPresetView[];
+}
+export declare const PERMISSION_SWITCH_ACTION = "caduceus.permission.switch";
+export declare function buildPermissionCard(view: PermissionView): FeishuCard;
+export declare function renderPermissionText(view: PermissionView): string;

package/dist/render/permission-card.js

@@ -0,0 +1,22 @@
+import { presetLabel, t } from '../i18n.js';
+import { interactiveCard } from '../interactive/cards.js';
+export const PERMISSION_SWITCH_ACTION = 'caduceus.permission.switch';
+function title(view, dict) {
+    const label = view.current === 'custom' ? dict.customLabel : presetLabel(view.lang, view.current);
+    return dict.permissionTitle(label);
+}
+function buttonLabels(view) {
+    return view.presets.map((preset) => presetLabel(view.lang, preset.name));
+}
+export function buildPermissionCard(view) {
+    const dict = t(view.lang);
+    return interactiveCard(title(view, dict), [dict.usage], view.presets.map((preset) => ({
+        label: presetLabel(view.lang, preset.name),
+        disabled: preset.name === view.current,
+        value: { action: PERMISSION_SWITCH_ACTION, name: preset.name },
+    })));
+}
+export function renderPermissionText(view) {
+    const dict = t(view.lang);
+    return [title(view, dict), dict.usage, buttonLabels(view).join(' / ')].join('\n');
+}

package/dist/status.d.ts

@@ -21,6 +21,14 @@
  */
 /** Derived session states. */
 export type StatusState = 'idle' | 'waiting-input' | 'running' | 'completed' | 'failed' | 'waiting-approval' | 'interrupted';
+/** Disjoint token totals for one or more model calls. */
+export interface UsageTotals {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+}
 /** Immutable status snapshot. */
 export interface StatusSnapshot {
     readonly state: StatusState;
@@ -41,6 +49,20 @@ export interface StatusSnapshot {
     readonly terminalKind?: string;
     /** Provider failure text for `turn/end error`. */
     readonly errorMessage?: string;
+    /** Token usage for the current turn (`assistant/message.usage`). */
+    readonly usageTurn?: UsageTotals;
+    /** Usage of the previous turn. */
+    readonly usagePrevious?: UsageTotals;
+    /** Cumulative usage of the session. */
+    readonly usageTotal?: UsageTotals;
+    /** True once at least one usage-bearing assistant message was seen. */
+    readonly usageSeen?: boolean;
+    /** Context compaction lifecycle. */
+    readonly compaction?: 'running' | 'done' | 'failed';
+    /** Messages retained after compaction when the event reports it. */
+    readonly compactionKept?: number;
+    /** Latest teammate/task line (only one, later overwrites earlier). */
+    readonly teamLine?: string;
 }
 /** Structural subset of a dsh `SessionEvent` used by the reducer. */
 export interface StatusEventLike {

package/dist/status.js

@@ -19,6 +19,42 @@
  *
  * @module dsh-caduceus/status
  */
+const ZERO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+function usageFromEvent(data) {
+    const usage = data?.['usage'];
+    if (typeof usage !== 'object' || usage === null)
+        return undefined;
+    const record = usage;
+    const number = (key) => typeof record[key] === 'number' ? record[key] : 0;
+    const input = number('inputTokens');
+    const output = number('outputTokens');
+    const cacheRead = number('cacheReadTokens');
+    const cacheWrite = number('cacheWriteTokens');
+    if (input === 0 && output === 0 && cacheRead === 0 && cacheWrite === 0)
+        return undefined;
+    const total = typeof record['totalTokens'] === 'number'
+        ? record['totalTokens']
+        : input + output + cacheRead + cacheWrite;
+    return { input, output, cacheRead, cacheWrite, total };
+}
+function addUsage(base, delta) {
+    const left = base ?? ZERO_USAGE;
+    return {
+        input: left.input + delta.input,
+        output: left.output + delta.output,
+        cacheRead: left.cacheRead + delta.cacheRead,
+        cacheWrite: left.cacheWrite + delta.cacheWrite,
+        total: left.total + delta.total,
+    };
+}
+function keptFromEvent(data) {
+    for (const key of ['kept', 'retained', 'messages', 'messageCount']) {
+        const value = data?.[key];
+        if (typeof value === 'number')
+            return value;
+    }
+    return undefined;
+}
 const INITIAL = { state: 'idle', steps: 0, tools: 0, turn: 0 };
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : undefined;
@@ -39,11 +75,14 @@ export class StatusTracker {
             case 'turn/start': {
                 const turn = typeof data?.['turn'] === 'number' ? data['turn'] : base.turn + 1;
                 this.snapshot = {
+                    ...base,
                     state: 'running',
                     steps: 0,
                     tools: 0,
                     turn,
                     ...(time === undefined ? {} : { startedAt: time }),
+                    ...(base.usageTurn === undefined ? {} : { usagePrevious: base.usageTurn }),
+                    usageTurn: ZERO_USAGE,
                     ...common,
                 };
                 return this.snapshot;
@@ -60,6 +99,46 @@ export class StatusTracker {
                 this.snapshot = { ...base, tools: base.tools + 1, ...common };
                 return this.snapshot;
             }
+            case 'assistant/message': {
+                const usage = usageFromEvent(data);
+                if (usage === undefined) {
+                    this.snapshot = { ...base, ...common };
+                    return this.snapshot;
+                }
+                this.snapshot = {
+                    ...base,
+                    usageSeen: true,
+                    usageTurn: addUsage(base.usageTurn, usage),
+                    usageTotal: addUsage(base.usageTotal, usage),
+                    ...common,
+                };
+                return this.snapshot;
+            }
+            case 'compaction/start': {
+                this.snapshot = { ...base, compaction: 'running', ...common };
+                return this.snapshot;
+            }
+            case 'compaction/end': {
+                const failed = typeof data?.['error'] === 'string';
+                const kept = keptFromEvent(data);
+                this.snapshot = {
+                    ...base,
+                    compaction: failed ? 'failed' : 'done',
+                    ...(kept === undefined ? {} : { compactionKept: kept }),
+                    ...common,
+                };
+                return this.snapshot;
+            }
+            case 'team/member':
+            case 'team/task': {
+                const line = teamLineFromEvent(event.type, data);
+                this.snapshot = {
+                    ...base,
+                    ...(line === undefined ? {} : { teamLine: line }),
+                    ...common,
+                };
+                return this.snapshot;
+            }
             case 'turn/end': {
                 const turnData = (data ?? {});
                 const kind = turnData.reason?.kind;
@@ -90,6 +169,22 @@ export class StatusTracker {
         this.snapshot = INITIAL;
     }
 }
+function teamLineFromEvent(type, data) {
+    if (type === 'team/member') {
+        const member = asRecord(data?.['member']);
+        const name = typeof member?.['name'] === 'string' ? member['name'] : undefined;
+        const phase = typeof member?.['phase'] === 'string' ? member['phase'] : undefined;
+        if (name === undefined)
+            return undefined;
+        return `队友 ${name}：${phase ?? '更新'}`;
+    }
+    const task = asRecord(data?.['task']);
+    const subject = typeof task?.['subject'] === 'string' ? task['subject'] : undefined;
+    const status = typeof task?.['status'] === 'string' ? task['status'] : undefined;
+    if (subject === undefined)
+        return undefined;
+    return `队友 ${subject}：${status ?? '更新'}`;
+}
 /** Map a `turn/end` reason kind to the derived state. */
 export function stateForTurnEnd(kind) {
     switch (kind) {

package/dist/transport/feishu-response.d.ts

@@ -0,0 +1 @@
+export declare function unwrapFeishuData<T extends object>(response: unknown, operation: string): T;

package/dist/transport/feishu-response.js

@@ -0,0 +1,25 @@
+/**
+ * Some Feishu SDK methods return a `{code,msg,data}` envelope, while the
+ * file/image upload endpoints return the bare `data` object. Normalize both.
+ *
+ * @module dsh-caduceus/transport/feishu-response
+ */
+import { FeishuApiError } from './types.js';
+export function unwrapFeishuData(response, operation) {
+    if (typeof response !== 'object' || response === null) {
+        throw new FeishuApiError(`feishu ${operation} returned no data`, -1);
+    }
+    const record = response;
+    if (typeof record.code === 'number') {
+        if (record.code !== 0) {
+            throw new FeishuApiError(`feishu ${operation} failed (code ${record.code}): ${typeof record.msg === 'string' ? record.msg : 'unknown error'}`, record.code);
+        }
+        const data = record.data;
+        if (typeof data !== 'object' || data === null) {
+            throw new FeishuApiError(`feishu ${operation} returned no data`, -1);
+        }
+        return data;
+    }
+    // Bare data shape (file/image upload endpoints in the installed SDK).
+    return record;
+}

package/dist/transport/lark.js

@@ -13,6 +13,7 @@ import { silentLogger } from '../logger.js';
 import { normalizeCardAction, normalizeMessageEvent, } from './normalize.js';
 import { formatGateLine } from '../gate.js';
 import { FeishuApiError } from './types.js';
+import { unwrapFeishuData } from './feishu-response.js';
 /** Long-connection Feishu implementation of {@link FeishuApi}. */
 export class LarkFeishuApi {
     client;
@@ -174,8 +175,8 @@ export class LarkFeishuApi {
                 file: Buffer.from(bytes),
             },
         }));
-        this.assertOk(response, 'im.v1.file.create');
-        const fileKey = response.data?.file_key;
+        const data = unwrapFeishuData(response, 'im.v1.file.create');
+        const fileKey = data.file_key;
         if (fileKey === undefined || fileKey.length === 0) {
             throw new FeishuApiError('feishu im.v1.file.create returned no file_key', -1);
         }
@@ -188,8 +189,8 @@ export class LarkFeishuApi {
                 image: Buffer.from(bytes),
             },
         }));
-        this.assertOk(response, 'im.v1.image.create');
-        const imageKey = response.data?.image_key;
+        const data = unwrapFeishuData(response, 'im.v1.image.create');
+        const imageKey = data.image_key;
         if (imageKey === undefined || imageKey.length === 0) {
             throw new FeishuApiError('feishu im.v1.image.create returned no image_key', -1);
         }