Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(x): 补齐视频回复收集与媒体待发恢复 (#6447)

Chris Zhanga82e0e70bb85
diff --git a/apps/desktop/src/main/cindy-media/__tests__/taskImageDelivery.test.ts b/apps/desktop/src/main/cindy-media/__tests__/taskImageDelivery.test.ts
index d639e079d0..3a6fb53c87 100644
--- a/apps/desktop/src/main/cindy-media/__tests__/taskImageDelivery.test.ts
+++ b/apps/desktop/src/main/cindy-media/__tests__/taskImageDelivery.test.ts
@@ -1,3 +1,6 @@
+import { createHookMediaStore } from '../hookOutbox';
+import { createHookRequestLedger, HOOK_TERMINAL_DELIVERY_TTL_MS } from '../../hook-control/requestLedger';
+import type { TurnEndPayload } from '@cindy/slack-hook-protocol';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import fs from 'node:fs/promises';
import os from 'node:os';
@@ -598,3 +601,55 @@ describe('Markdown image contract', () => {
).toBe('before ![a](cindy-media://blobs/test.png "caption") after');
});
});
+
+// #6447 integration: actual media bytes/DB, owner-scoped JSON, fresh store restore,
+// ACK release, task deletion and expiry. Old tests only exercised the JSON ledger.
+it.each(['image/png', 'video/mp4'])('hook outbox manages %s through recovery and deletion', async (mimeType) => {
+ const bytes = mimeType === 'image/png' ? PNG : Buffer.alloc(6 * 1024 * 1024, 7);
+ const attachments = [{ name: 'result', mimeType, dataBase64: bytes.toString('base64') }];
+ const turn: TurnEndPayload = { requestId: 'r', externalKey: 'x:t', sessionId: 's', status: 'ok',
+ finalText: 'done', errorMessage: null, usage: { durationMs: 0 }, attachments };
+ const store = createHookMediaStore();
+ const media = await store.prepare(turn, () => {});
+ const { attachments: _, ...text } = turn;
+ const filePath = path.join(state.root, 'hook-ledger.json');
+ const log = { warn: vi.fn() };
+ const saved = { connectionId: 'x', requestId: 'r', ack: { requestId: 'r', result: 'accepted' as const,
+ sessionId: 's', reason: null, queuePosition: null }, turnEnd: text, media,
+ delivery: 'pending' as const, completedAt: Date.now() };
+ const first = createHookRequestLedger({ filePath, log, releaseMedia: store.release });
+ expect(first.set(saved)).toBe(true);
+ expect((await fs.stat(filePath)).size).toBeLessThan(2048);
+ expect(await fs.readFile(filePath, 'utf8')).not.toContain('dataBase64');
+ const next = createHookMediaStore();
+ const ledgerAfterRestart = createHookRequestLedger({ filePath, log, releaseMedia: next.release });
+ const recovered = ledgerAfterRestart.listPending('x')[0]!;
+ expect((await next.restore(recovered.turnEnd!, recovered.media!))?.attachments).toEqual(attachments);
+ ledgerAfterRestart.markSent('x', 'r');
+ // The release runs asynchronously after the atomic JSON write.
+ await vi.waitFor(() => expect(raw.prepare('SELECT count(*) AS n FROM media_refs').get()).toEqual({ n: 0 }), { interval: 1 });
+ expect((await fs.readFile(resolveSafe(media[0]!.url).absPath)).equals(bytes)).toBe(true); // recycler owns bytes
+
+ const deletedMedia = await next.prepare(turn, () => {});
+ raw.prepare("UPDATE sessions SET status = 'deleted' WHERE id = 's'").run();
+ await ledger.removeSessionRefs('s', client.drizzle);
+ expect(await next.restore(text, deletedMedia)).toBeNull();
+ expect(raw.prepare('SELECT count(*) AS n FROM media_refs').get()).toEqual({ n: 0 });
+
+ raw.prepare("UPDATE sessions SET status = 'active' WHERE id = 's'").run();
+ await next.prepare(turn, () => {});
+ raw.prepare('UPDATE media_refs SET created_at = ?').run(Date.now() - HOOK_TERMINAL_DELIVERY_TTL_MS - 1);
+ await next.prune();
+ expect(raw.prepare('SELECT count(*) AS n FROM media_refs').get()).toEqual({ n: 0 });
+});
+
+// Integration: a switch during ingestion must leave neither a pin nor a replayable result.
+it('rolls back hook media if its owner changes during ingestion', async () => {
+ const store = createHookMediaStore();
+ state.afterIngest = () => { state.valid = false; };
+ await expect(store.prepare({ requestId: 'r', externalKey: 'x:t', sessionId: 's', status: 'ok',
+ finalText: 'done', errorMessage: null, usage: { durationMs: 0 },
+ attachments: [{ name: 'image.png', mimeType: 'image/png', dataBase64: PNG.toString('base64') }],
+ }, () => {})).rejects.toThrow();
+ expect(raw.prepare('SELECT count(*) AS n FROM media_refs').get()).toEqual({ n: 0 });
+});
diff --git a/apps/desktop/src/main/cindy-media/hookOutbox.ts b/apps/desktop/src/main/cindy-media/hookOutbox.ts
new file mode 100644
index 0000000000..6e9c4fb838
--- /dev/null
+++ b/apps/desktop/src/main/cindy-media/hookOutbox.ts
@@ -0,0 +1,123 @@
+/** X's durable outbox borrows managed media; the transport ledger never owns bytes. */
+import fs from 'node:fs/promises';
+import { and, eq, lt } from 'drizzle-orm';
+import type { TurnEndPayload } from '@cindy/slack-hook-protocol';
+import { activeOwnerScopeKey } from '../appSessionState';
+import { getCurrentDbClientSnapshot } from '../localDb/client/current';
+import { mediaRefs, sessions } from '../localDb/schema';
+import { HOOK_TERMINAL_DELIVERY_TTL_MS, type HookMediaReference } from '../hook-control/requestLedger';
+import { ingestMedia } from './ingest';
+import { parseBlobUrl, resolveSafe } from './blobStore';
+import { removeRefById, withSessionMediaRefLock } from './ledger';
+import { captureMediaRefCompensationScope, withMediaRefCompensation } from './refCompensationJournal';
+
+const ORIGIN = 'hook-outbox';
+
+export interface HookMediaStore {
+ prepare(turn: TurnEndPayload, assertCurrent: () => void): Promise<HookMediaReference[]>;
+ restore(turn: TurnEndPayload, media: HookMediaReference[]): Promise<TurnEndPayload | null>;
+ release(media: HookMediaReference[]): Promise<void>;
+ prune(): Promise<void>;
+}
+
+export function createHookMediaStore(): HookMediaStore {
+ const owner = activeOwnerScopeKey();
+ function capture() {
+ const snapshot = getCurrentDbClientSnapshot();
+ if (!snapshot || activeOwnerScopeKey() !== owner) throw new Error('hook-media: owner unavailable');
+ const journal = captureMediaRefCompensationScope(owner);
+ const assertStillValid = () => {
+ journal.assertStillValid();
+ if (getCurrentDbClientSnapshot() !== snapshot) throw new Error('hook-media: owner changed');
+ };
+ return { db: snapshot.client.drizzle, journal, assertStillValid };
+ }
+ return {
+ async prepare(turn, assertCurrent) {
+ const sessionId = turn.sessionId;
+ if (!sessionId) throw new Error('hook-media: task missing');
+ const { db, journal, assertStillValid } = capture();
+ return withSessionMediaRefLock(db, sessionId, async () => {
+ const check = () => { assertStillValid(); assertCurrent(); };
+ check();
+ const [session] = await db.select({ status: sessions.status, clearedAt: sessions.clearedAt })
+ .from(sessions).where(eq(sessions.id, sessionId)).limit(1);
+ check();
+ if (!session || session.status === 'deleted') throw new Error('hook-media: task deleted');
+ const refs: HookMediaReference[] = [];
+ try {
+ for (const attachment of turn.attachments ?? []) {
+ const saved = await ingestMedia({
+ buffer: Buffer.from(attachment.dataBase64, 'base64'), mimeType: attachment.mimeType,
+ refs: [{ refKind: 'message', refId: `hook-outbox:${turn.requestId}`,
+ originSessionId: sessionId, originKind: 'integration', originId: ORIGIN }],
+ assertStillValid: check, refCompensationScope: journal,
+ }, db);
+ refs.push({ url: saved.url, refId: saved.refIds[0]!, name: attachment.name,
+ mimeType: saved.mimeType, bytes: saved.bytes });
+ }
+ const [current] = await db.select({ status: sessions.status, clearedAt: sessions.clearedAt })
+ .from(sessions).where(eq(sessions.id, sessionId)).limit(1);
+ check();
+ if (!current || current.status === 'deleted' || current.clearedAt !== session.clearedAt)
+ throw new Error('hook-media: task changed');
+ return refs;
+ } catch (error) {
+ // Exact ids and the captured owner survive a worker/account boundary.
+ if (refs.length) await withMediaRefCompensation({
+ scope: { ...journal, assertStillValid: () => {} }, refIds: refs.map((ref) => ref.refId),
+ perform: async () => { for (const ref of refs) await removeRefById(ref.refId, db); },
+ compensate: (id) => removeRefById(id, db),
+ });
+ throw error;
+ }
+ });
+ },
+ async restore(turn, media) {
+ const sessionId = turn.sessionId;
+ if (!sessionId) return null;
+ const { db, assertStillValid } = capture();
+ return withSessionMediaRefLock(db, sessionId, async () => {
+ const [session] = await db.select({ status: sessions.status }).from(sessions)
+ .where(eq(sessions.id, sessionId)).limit(1);
+ assertStillValid();
+ if (!session || session.status === 'deleted') return null;
+ const attachments = [];
+ for (const ref of media) {
+ const parsed = parseBlobUrl(ref.url);
+ if (!parsed) return null;
+ const rows = await db.select({ id: mediaRefs.id }).from(mediaRefs).where(and(
+ eq(mediaRefs.id, ref.refId), eq(mediaRefs.hash, parsed.hash),
+ eq(mediaRefs.originSessionId, sessionId), eq(mediaRefs.originId, ORIGIN),
+ )).limit(1);
+ assertStillValid();
+ if (!rows.length) return null; // Business deletion already released the pin.
+ const bytes = await fs.readFile(resolveSafe(ref.url).absPath);
+ assertStillValid();
+ if (bytes.length !== ref.bytes) throw new Error('hook-media: changed blob');
+ attachments.push({ name: ref.name, mimeType: ref.mimeType, dataBase64: bytes.toString('base64') });
+ }
+ return { ...turn, attachments };
+ });
+ },
+ async release(media) {
+ const { db, journal, assertStillValid } = capture();
+ await withMediaRefCompensation({
+ scope: journal, refIds: media.map((ref) => ref.refId),
+ perform: async () => {
+ for (const ref of media) { assertStillValid(); await removeRefById(ref.refId, db); }
+ },
+ compensate: (id) => removeRefById(id, db),
+ });
+ },
+ async prune() {
+ const { db, assertStillValid } = capture();
+ assertStillValid();
+ // Also reclaims staged pins left by a crash before the JSON commit. Shared
+ // message references are removed by the existing task-deletion lifecycle.
+ await db.delete(mediaRefs).where(and(eq(mediaRefs.refKind, 'message'),
+ eq(mediaRefs.originKind, 'integration'), eq(mediaRefs.originId, ORIGIN),
+ lt(mediaRefs.createdAt, Date.now() - HOOK_TERMINAL_DELIVERY_TTL_MS))).run();
+ },
+ };
+}
diff --git a/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts b/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts
index 19743c6a64..e539fcb10e 100644
--- a/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts
+++ b/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts
@@ -5,6 +5,8 @@
*/
import path from 'node:path';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
import { describe, expect, it, vi } from 'vitest';
import {
@@ -47,9 +49,10 @@ import {
type HookSessionRunner,
type PrepareWorktreeResult,
} from '../dispatcher';
+import type { HookMediaStore } from '../../cindy-media/hookOutbox';
import type { HookBindingStore } from '../bindings';
import { isPathWithin } from '../paths';
-import type { HookRequestLedger, HookTerminalRecord } from '../requestLedger';
+import { createHookRequestLedger, type HookRequestLedger, type HookTerminalRecord } from '../requestLedger';
import type { HookConnectionConfig } from '../store';
const noopLog = { info: () => {}, warn: () => {} };
@@ -222,6 +225,7 @@ function makeDispatcher(overrides?: {
runner?: HookSessionRunner;
bindings?: HookBindingStore;
terminalLedger?: HookRequestLedger;
+ mediaStore?: HookMediaStore;
config?: HookConnectionConfig | null;
prepareWorktree?: HookDispatcherDeps['prepareWorktree'];
buildContextPrefix?: HookDispatcherDeps['buildContextPrefix'];
@@ -245,6 +249,7 @@ function makeDispatcher(overrides?: {
(() => (overrides?.config === undefined ? CONFIG : overrides.config)),
bindings,
terminalLedger: overrides?.terminalLedger,
+ mediaStore: overrides?.mediaStore,
runner,
prepareWorktree: overrides?.prepareWorktree,
buildContextPrefix: overrides?.buildContextPrefix,
@@ -3230,48 +3235,90 @@ describe('dispatcher 核心语义', () => {
}
});
- it('ACK 模式回执前重启 -> 新 dispatcher 从账本经 ACK 缓冲补发, 回执后收口 sent', async () => {
- vi.useFakeTimers();
- const firstRunner = fakeRunner();
- const terminalLedger = memoryTerminalLedger();
- const first = makeDispatcher({ runner: firstRunner.runner, terminalLedger });
- const firstCollector = collector();
- try {
- first.d.onConnected('conn-1', firstCollector.send, [HOOK_FEATURE_TURN_DELIVERY]);
- first.d.handleDispatch('conn-1', dispatch(), firstCollector.send);
- await tick();
- firstRunner.finish({ finalText: '重启前完成' });
- await tick();
- expect(terminalLedger.records[0]?.delivery).toBe('pending');
- first.d.dispose();
-
- const secondRunner = fakeRunner();
- const second = makeDispatcher({ runner: secondRunner.runner, terminalLedger });
- const secondCollector = collector();
- second.d.onConnected('conn-1', secondCollector.send, [HOOK_FEATURE_TURN_DELIVERY]);
- expect(secondRunner.calls).toHaveLength(0);
- expect(secondCollector.ofType('turn.end')).toHaveLength(1);
- expect(secondCollector.last('turn.end')?.payload).toMatchObject({
- requestId: 'req-1',
- finalText: '重启前完成',
- });
- // 回执到达前账本保持 pending; 回执后收口, 停止重放。
- expect(terminalLedger.records[0]?.delivery).toBe('pending');
- second.d.handleTurnDelivery('conn-1', {
- requestId: 'req-1',
- state: 'accepted',
- attempt: 0,
- retryAt: null,
- error: null,
- });
- expect(terminalLedger.records[0]?.delivery).toBe('sent');
- await vi.advanceTimersByTimeAsync(120_000);
- expect(secondCollector.ofType('turn.end')).toHaveLength(1);
- second.d.dispose();
- } finally {
- vi.useRealTimers();
- }
- });
+ // #6447: direct ledger tests missed dispatcher stripping media before persistence.
+ // Unit with a temporary ledger: offline X completion -> fresh dispatcher -> exact bytes + ACK.
+ it.each([['x', 'image/png'], ['x', 'video/mp4'], ['telegram', 'image/png']] as const)(
+ '%s 离线 %s 回复恢复遵循渠道附件约定, 回执后停止补发', async (provider, mimeType) => {
+ vi.useFakeTimers();
+ const firstRunner = fakeRunner();
+ const directory = mkdtempSync(path.join(tmpdir(), 'hook-media-recovery-'));
+ const mediaStore: HookMediaStore = {
+ prepare: vi.fn(async () => [{ url: `cindy-media://blobs/${'a'.repeat(64)}.mp4`,
+ refId: 'outbox-pin', name: 'clip.mp4', mimeType, bytes: 6 * 1024 * 1024 }]),
+ restore: vi.fn(async (turn) => ({ ...turn, attachments })),
+ release: vi.fn(async () => {}), prune: vi.fn(async () => {}),
+ };
+ const openLedger = () => createHookRequestLedger({ filePath: path.join(directory, 'ledger.json'),
+ log: noopLog, releaseMedia: mediaStore.release });
+ const terminalLedger = openLedger();
+ const attachments = [{
+ mimeType,
+ name: mimeType === 'video/mp4' ? 'clip.mp4' : 'shot.png',
+ dataBase64: Buffer.alloc(mimeType === 'video/mp4' ? 6 * 1024 * 1024 : 32, 7).toString('base64'),
+ }];
+ const first = makeDispatcher({ runner: firstRunner.runner, terminalLedger, mediaStore });
+ const firstCollector = collector();
+ let secondDispatcher: ReturnType<typeof makeDispatcher>['d'] | undefined;
+ try {
+ first.d.onConnected('conn-1', firstCollector.send, [HOOK_FEATURE_TURN_DELIVERY]);
+ first.d.handleDispatch('conn-1', dispatch({ source: { im: provider } }), firstCollector.send);
+ await tick();
+ firstCollector.setOnline(false);
+ firstRunner.finish({ finalText: '重启前完成', attachments });
+ await tick();
+ expect(terminalLedger.get('conn-1', 'req-1')?.delivery).toBe('pending');
+ expect(readFileSync(path.join(directory, 'ledger.json'), 'utf8')).not.toContain('dataBase64');
+ first.d.dispose();
+
+ const secondRunner = fakeRunner();
+ const restoredLedger = openLedger();
+ const second = makeDispatcher({ runner: secondRunner.runner, terminalLedger: restoredLedger, mediaStore });
+ secondDispatcher = second.d;
+ const secondCollector = collector();
+ second.d.onConnected('conn-1', secondCollector.send, [HOOK_FEATURE_TURN_DELIVERY]);
+ await tick();
+ expect(secondRunner.calls).toHaveLength(0);
+ expect(secondCollector.ofType('turn.end')).toHaveLength(1);
+ expect(secondCollector.last('turn.end')?.payload).toMatchObject({
+ requestId: 'req-1',
+ finalText: '重启前完成',
+ });
+ const restoredAttachments = secondCollector.last('turn.end')?.payload.attachments;
+ if (provider === 'x') {
+ expect(restoredAttachments).toHaveLength(1);
+ expect(restoredAttachments?.[0]?.mimeType).toBe(mimeType);
+ expect(restoredAttachments?.[0]?.dataBase64 === attachments[0]!.dataBase64).toBe(true);
+ } else {
+ expect(restoredAttachments).toBeUndefined();
+ }
+ // 回执到达前账本保持 pending; 回执后收口, 停止重放。
+ expect(restoredLedger.get('conn-1', 'req-1')?.delivery).toBe('pending');
+ second.d.handleTurnDelivery('conn-1', {
+ requestId: 'req-1',
+ state: 'accepted',
+ attempt: 0,
+ retryAt: null,
+ error: null,
+ });
+ expect(restoredLedger.get('conn-1', 'req-1')?.delivery).toBe('sent');
+ expect(restoredLedger.get('conn-1', 'req-1')?.media).toBeUndefined();
+ if (provider === 'x') {
+ expect(mediaStore.release).toHaveBeenCalledTimes(1);
+ second.d.handleDispatch('conn-1', dispatch({ source: { im: provider } }), secondCollector.send);
+ await tick();
+ expect(secondCollector.ofType('turn.end')).toHaveLength(1); // no text-only duplicate
+ }
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(secondCollector.ofType('turn.end')).toHaveLength(1);
+ second.d.dispose();
+ } finally {
+ first.d.dispose();
+ secondDispatcher?.dispose();
+ rmSync(directory, { recursive: true, force: true });
+ vi.useRealTimers();
+ }
+ },
+ );
it('同 socket 能力降级且回落发送失败 -> 旧退避 timer 被缴械, 不再向老 server 重放', async () => {
vi.useFakeTimers();
diff --git a/apps/desktop/src/main/hook-control/__tests__/outbound.test.ts b/apps/desktop/src/main/hook-control/__tests__/outbound.test.ts
index 3bdcaa4440..8960f23eee 100644
--- a/apps/desktop/src/main/hook-control/__tests__/outbound.test.ts
+++ b/apps/desktop/src/main/hook-control/__tests__/outbound.test.ts
@@ -392,3 +392,71 @@ describe('辅助函数', () => {
expect(guessMime('/a/b.tar.gz')).toBe('application/octet-stream');
});
});
+
+// X video regression: real collector input -> attachment bytes/MIME/caption.
+// Existing image and xdt-file cases did not cover managed video links (unit tier).
+describe('X managed video delivery', () => {
+ // #6447: plain-label coverage missed nested visible text (unit, collector output).
+ it.each([
+ ['**成片**', '成片'],
+ ['`clip.mp4`', 'clip.mp4'],
+ ['![封面](https://example.com/cover.png)', '封面'],
+ ])('preserves the visible caption in %s', async (label, expected) => {
+ const result = await collectOutboundAttachments(
+ `[${label}](cindy-media://blobs/clip.mp4)`, [],
+ { ...deps({ '/blobs/blobs/clip.mp4': Buffer.from('video') }), provider: 'x' },
+ );
+ expect(result.text.trim()).toBe(expected);
+ expect(result.attachments).toHaveLength(1);
+ });
+
+ it('collects a video link and generated-media side channel once, with the file limit', async () => {
+ const bytes = Buffer.alloc(6 * 1024 * 1024, 1);
+ const io = deps({ '/blobs/blobs/clip.mp4': bytes });
+ const result = await collectOutboundAttachments(
+ '完成 [视频][clip]\n\n[clip]: cindy-media://blobs/clip.mp4', ['/blobs/blobs/clip.mp4'], { ...io, provider: 'x' },
+ );
+ expect(result.attachments).toHaveLength(1);
+ expect(result.attachments[0]?.mimeType).toBe('video/mp4');
+ expect(Buffer.from(result.attachments[0]!.dataBase64, 'base64').equals(bytes)).toBe(true);
+ expect(result.text.trim()).toBe('完成 视频');
+ expect(result.skipped).toBe(0);
+ });
+
+ it('does not upload code examples and reports an unreadable managed video', async () => {
+ const io = deps({});
+ const result = await collectOutboundAttachments(
+ '`[demo](cindy-media://blobs/example.mp4)`\n[视频](cindy-media://blobs/missing.mp4)', [], { ...io, provider: 'x' },
+ );
+ expect(result.attachments).toEqual([]);
+ expect(io.readFile).toHaveBeenCalledTimes(1);
+ expect(result.skipped).toBe(1);
+ expect(result.text).not.toContain('cindy-media://blobs/missing.mp4');
+ expect(result.text).toContain('Attachment delivery incomplete');
+ });
+
+ it('keeps other channel collection unchanged', async () => {
+ const io = deps({ '/blobs/blobs/clip.mp4': Buffer.from('clip') });
+ const text = '[视频](cindy-media://blobs/clip.mp4)';
+ const result = await collectOutboundAttachments(text, [], { ...io, provider: 'telegram' });
+ expect(result.attachments).toEqual([]);
+ expect(io.readFile).not.toHaveBeenCalled();
+ expect(result.text).toBe(text);
+ });
+});
+
+// #6447: declared tool media and Markdown share the production collector.
+// Unit: a managed WebM must never reach the X transport (no transcoding contract).
+it.each(['markdown', 'tool'] as const)('X rejects unsupported WebM from %s with an explicit warning', async (source) => {
+ const url = `cindy-media://blobs/${'a'.repeat(64)}.webm`;
+ const readFile = vi.fn(async () => Buffer.from('webm'));
+ const result = await collectOutboundAttachments(source === 'markdown' ? `[clip](${url})` : 'clip',
+ source === 'tool' ? ['/blobs/clip.webm'] : [], {
+ provider: 'x', log, readFile,
+ resolveImageUrl: () => ({ absPath: '/blobs/clip.webm', mimeType: 'video/webm' }),
+ });
+ expect(result.attachments).toEqual([]);
+ expect(result.text).toContain('clip');
+ expect(result.text).toContain('Attachment delivery incomplete');
+ expect(readFile).not.toHaveBeenCalled();
+});
diff --git a/apps/desktop/src/main/hook-control/__tests__/requestLedger.test.ts b/apps/desktop/src/main/hook-control/__tests__/requestLedger.test.ts
index 51e6f9042c..23e9622f7b 100644
--- a/apps/desktop/src/main/hook-control/__tests__/requestLedger.test.ts
+++ b/apps/desktop/src/main/hook-control/__tests__/requestLedger.test.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createHookRequestLedger, type HookTerminalRecord } from '../requestLedger';
+import { createHookRequestLedger, HOOK_TERMINAL_DELIVERY_TTL_MS, type HookTerminalRecord } from '../requestLedger';
const warnings: string[] = [];
const log = { warn: (message: string) => warnings.push(message) };
@@ -47,6 +47,34 @@ afterEach(() => {
});
describe('hook request ledger', () => {
+ // #6447: disk contains bounded references; raw wire media must fail closed.
+ it('stores managed video references and drops them after receipt or expiry', () => {
+ const saved = record('x-video');
+ saved.delivery = 'pending';
+ saved.media = [{ url: `cindy-media://blobs/${'a'.repeat(64)}.mp4`, refId: 'pin',
+ name: 'clip.mp4', mimeType: 'video/mp4', bytes: 6 * 1024 * 1024 }];
+ const released: unknown[] = [];
+ let now = saved.completedAt;
+ const open = () => createHookRequestLedger({ filePath: filePath(), log, now: () => now,
+ releaseMedia: async (media) => { released.push(media); } });
+ const first = open();
+ expect(first.set(saved)).toBe(true);
+ const restored = open();
+ expect(restored.listPending('conn-1')[0]?.media).toEqual(saved.media);
+ expect(restored.markSent('conn-1', 'x-video')).toBe(true);
+ expect(restored.get('conn-1', 'x-video')?.media).toBeUndefined();
+ expect(released).toEqual([saved.media]);
+ expect(restored.set(saved)).toBe(true);
+ now += HOOK_TERMINAL_DELIVERY_TTL_MS + 1;
+ restored.prune!();
+ expect(restored.get('conn-1', 'x-video')?.media).toBeUndefined();
+ expect(released).toHaveLength(2);
+ expect(fs.readFileSync(filePath(), 'utf8')).not.toContain('cindy-media://');
+ saved.completedAt = now;
+ saved.turnEnd!.attachments = [{ name: 'clip.mp4', mimeType: 'video/mp4', dataBase64: 'AAAA' }];
+ expect(restored.set(saved)).toBe(false);
+ });
+
it('跨实例读回完整终态, 且按 connectionId + requestId 隔离', () => {
const first = createHookRequestLedger({ filePath: filePath(), log });
const saved = record('req-1');
diff --git a/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts b/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts
index d95c0877a6..a92d3f2422 100644
--- a/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts
+++ b/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts
@@ -394,7 +394,7 @@ vi.mock('../../im/shared/sessionProviderLabel.js', () => ({
resolveSessionErrorContext: vi.fn(async () => ({ providerLabel: 'OpenAI', modelLabel: 'GPT-6 Astra', taskLabel: '测试任务(sess-new)' })),
}));
-import { createMakerHookSessionRunner, extractToolResultImageUrls } from '../session-runner.js';
+import { createMakerHookSessionRunner, extractToolResultMediaUrls } from '../session-runner.js';
import { MAIN_OWNED_SEND_CONTEXT, Session, type AgentSessionHandle, type Capabilities } from '@cindy/maker-core';
import { observeHookTurn } from '../turnObserver.js';
import { buildHookPromptNote, SLACK_HOOK_PROMPT_NOTE } from '../outbound.js';
@@ -3712,23 +3712,40 @@ describe('providerId(来源/供应商)贯通 —— issue #854 回归', () => {
});
});
-describe('extractToolResultImageUrls 的兜底账本回落(xdt_media_produced)', () => {
+describe('extractToolResultMediaUrls 的兜底账本回落(xdt_media_produced)', () => {
+ // #6447: declared video fields suppress the fallback ledger; no caption is required.
+ // Unit: exercise the same extractor used by tool-result events.
+ it.each(['xdt_video_url', 'xdt_video_urls'])('collects declared %s only for X', (field) => {
+ const video = `cindy-media://blobs/${'a'.repeat(64)}.mp4`;
+ const payload = { [field]: field.endsWith('urls') ? [video, video, 42, '/tmp/clip.mp4'] : video };
+ expect(extractToolResultMediaUrls(JSON.stringify(payload), 'x')).toEqual([video]);
+ expect(extractToolResultMediaUrls(JSON.stringify(payload), 'telegram')).toEqual([]);
+ expect(extractToolResultMediaUrls(JSON.stringify({ ...payload, _xdt_render_image: false }), 'x')).toEqual([]);
+ });
+
+ it('X receives generated video URLs while other channels retain image-only behavior', () => {
+ const video = `cindy-media://blobs/${'a'.repeat(64)}.mp4`;
+ const text = JSON.stringify({ xdt_media_produced: [video] });
+ expect(extractToolResultMediaUrls(text, 'x')).toEqual([video]);
+ expect(extractToolResultMediaUrls(text, 'telegram')).toEqual([]);
+ });
+
const IMG = `cindy-media://blobs/${'d'.repeat(64)}.png`;
const MP3 = `cindy-media://blobs/${'e'.repeat(64)}.mp3`;
it('意识未声明媒体字段时,从 xdt_media_produced 接走图片(过滤非图)', () => {
const text = JSON.stringify({ ok: true, xdt_media_produced: [IMG, MP3] });
- expect(extractToolResultImageUrls(text)).toEqual([IMG]);
+ expect(extractToolResultMediaUrls(text)).toEqual([IMG]);
});
it('声明字段与账本并存时合并去重', () => {
const text = JSON.stringify({ ok: true, xdt_image_urls: [IMG], xdt_media_produced: [IMG] });
- expect(extractToolResultImageUrls(text)).toEqual([IMG]);
+ expect(extractToolResultMediaUrls(text)).toEqual([IMG]);
});
it('_xdt_render_image:false 哨兵优先,全部不外发', () => {
const text = JSON.stringify({ ok: true, xdt_media_produced: [IMG], _xdt_render_image: false });
- expect(extractToolResultImageUrls(text)).toEqual([]);
+ expect(extractToolResultMediaUrls(text)).toEqual([]);
});
});
diff --git a/apps/desktop/src/main/hook-control/dispatcher.ts b/apps/desktop/src/main/hook-control/dispatcher.ts
index 1618c9477f..40feed4cf4 100644
--- a/apps/desktop/src/main/hook-control/dispatcher.ts
+++ b/apps/desktop/src/main/hook-control/dispatcher.ts
@@ -33,6 +33,7 @@
* 以 Slack 卡片呈现(允许一次/本对话总是允许/拒绝), 超时安全默认拒绝。
*/
+import type { HookMediaStore } from '../cindy-media/hookOutbox';
import path from 'node:path';
import { randomUUID } from 'node:crypto';
@@ -302,6 +303,7 @@ export interface HookDispatcherDeps {
bindings: HookBindingStore;
/** Durable terminal request state, injected by the Electron owner boundary. */
terminalLedger?: HookRequestLedger;
+ mediaStore?: HookMediaStore;
runner: HookSessionRunner;
/**
* 可选: 为新建 hook 会话预建独立 git worktree(并发隔离 —— 每个
@@ -718,6 +720,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
getConnection,
bindings,
terminalLedger,
+ mediaStore,
runner,
prepareWorktree,
buildContextPrefix,
@@ -1285,14 +1288,45 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
}
}
- function durableTurnEnd(turnEnd: TurnEndPayload): TurnEndPayload {
- // Binary attachment bytes belong to the existing media/transport path,
- // not a new JSON persistence store. The in-process offline queue keeps the
- // original frame; cross-restart recovery retains the terminal text only.
+ let mediaDisposed = false;
+ const mediaCleanupTimer = mediaStore ? setInterval(() => {
+ if (!accountActive) return;
+ terminalLedger?.prune?.();
+ void mediaStore.prune().catch(() => log.warn('hook media expiry cleanup deferred'));
+ }, 60_000) : undefined;
+ mediaCleanupTimer?.unref?.();
+
+ function durableTurnEnd(turnEnd: TurnEndPayload, provider?: string): TurnEndPayload {
+ // An X payload must either be staged into managed references below, or fail
+ // persistence and retain the full in-memory fallback. Other channels remain text-only.
+ if (provider === 'x') return turnEnd;
const { attachments: _attachments, ...withoutAttachments } = turnEnd;
return withoutAttachments;
}
+ function replayManagedTerminal(
+ record: HookTerminalRecord,
+ send: (message: HookMessage) => boolean,
+ publish: (turn: TurnEndPayload) => void,
+ ): void {
+ if (!record.turnEnd || record.mediaReleased) return;
+ if (!record.media?.length) { publish(record.turnEnd); return; }
+ if (!mediaStore) return;
+ const generation = accountGeneration;
+ void mediaStore.restore(record.turnEnd, record.media).then((turn) => {
+ if (!isCurrentGeneration(generation) || sendFns.get(record.connectionId) !== send
+ || terminalDeliveryExpired(record.completedAt, Date.now())) return;
+ if (record.delivery === 'pending'
+ && terminalLedger?.get(record.connectionId, record.requestId)?.delivery === 'sent') return;
+ if (!turn) {
+ markTerminalSent(record.connectionId, record.requestId);
+ log.warn('hook media replay cancelled: task or media reference removed');
+ return;
+ }
+ publish(turn);
+ }).catch(() => log.warn('hook media restore failed; pending reply retained'));
+ }
+
function supportsDeliveryAck(connectionId: string): boolean {
return serverFeatures.get(connectionId)?.includes(HOOK_FEATURE_TURN_DELIVERY) === true;
}
@@ -1375,11 +1409,14 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
connectionId: string,
message: HookTurnEndMessage,
terminal: Omit<HookTerminalRecord, 'completedAt' | 'delivery'>,
+ completedAt: number = Date.now(),
): void {
// 一次取时, 账本行与两条内存队列共用同一个 completedAt —— 三个出口据以判定
// 时效的年龄必须是同一个数, 否则「同一份结果」在不同出口有不同寿命。
- const completedAt = Date.now();
const durable = persistTerminal({ ...terminal, delivery: 'pending' }, completedAt);
+ if (!durable && terminal.media && mediaStore) {
+ void mediaStore.release(terminal.media).catch(() => log.warn('hook media cleanup deferred'));
+ }
if (supportsDeliveryAck(connectionId)) {
// ACK 模式: 会话内重发由 pendingDeliveryTurnEnds 负责; 账本保持 pending,
// 收到任一 turn.delivery 回执才收口为 sent(见 handleTurnDelivery), 跨重启
@@ -2004,7 +2041,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
() => {
persistedBeforePublish = persistTerminal({
...terminalRecord,
- turnEnd: durableTurnEnd(turnEnd),
+ turnEnd: durableTurnEnd(turnEnd, task.run.source?.im),
delivery: 'pending',
});
// 兜底写不进出箱就不走本端发布: 发布中途退出时服务端将收不到任何收口。没配
@@ -2027,13 +2064,33 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
running.delete(sessionId);
return;
}
+ const terminalCompletedAt = Date.now();
+ let durableTurn = durableTurnEnd(turnEnd, task.run.source?.im);
+ let media: HookTerminalRecord['media'];
+ if (task.run.source?.im === 'x' && turnEnd.attachments?.length && mediaStore) {
+ try {
+ media = await mediaStore.prepare(turnEnd, () => {
+ if (mediaDisposed || !isCurrentGeneration(task.accountGeneration)) throw new Error('hook owner changed');
+ });
+ const { attachments: _attachments, ...textOnly } = turnEnd;
+ durableTurn = textOnly;
+ } catch {
+ log.warn('hook media staging failed; complete reply retained in memory');
+ }
+ if (mediaDisposed || !isCurrentGeneration(task.accountGeneration)) {
+ if (media) void mediaStore.release(media).catch(() => {});
+ running.delete(sessionId);
+ return;
+ }
+ }
// Protocol idempotency replays only the original ACK. The terminal record
// is written as a pending outbox entry before sending; an offline frame
// stays buffered in memory until onConnected flushes the full payload.
sendOrBuffer(task.connectionId, makeTurnEnd(turnEnd), {
...terminalRecord,
- turnEnd: durableTurnEnd(turnEnd),
- });
+ turnEnd: durableTurn,
+ ...(media ? { media } : {}),
+ }, terminalCompletedAt);
// 屏障撤在正式帧进入发送 / 缓冲路径之后: 终稿发完到这里还隔着卡片 drain(最长数秒),
// 这段时间重连仍不能拿出箱里的兜底帧抢先重放。
publishingClientFinals.delete(publishingKey);
@@ -2649,34 +2706,37 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
);
return;
}
- if (supportsDeliveryAck(connectionId)) {
- // ACK 模式的重放帧与 sendOrBuffer 同语义: 经 ACK 缓冲重发, 账本保持
- // pending 直到 turn.delivery 回执收口(handleTurnDelivery)。server 既然
- // 重投了这个 requestId, 就说明它没有该结果的持久收据。
- if (terminalReplay.delivery === 'sent') {
- persistTerminalRecord({ ...terminalReplay, delivery: 'pending' });
+ const replayRecord = terminalReplay;
+ replayManagedTerminal(replayRecord, send, (restoredTurn) => {
+ if (supportsDeliveryAck(connectionId)) {
+ // ACK 模式的重放帧与 sendOrBuffer 同语义: 经 ACK 缓冲重发, 账本保持
+ // pending 直到 turn.delivery 回执收口(handleTurnDelivery)。server 既然
+ // 重投了这个 requestId, 就说明它没有该结果的持久收据。
+ if (replayRecord.delivery === 'sent') {
+ persistTerminalRecord({ ...replayRecord, delivery: 'pending' });
+ }
+ trackPendingDelivery(
+ connectionId,
+ makeTurnEnd(restoredTurn),
+ replayRecord.completedAt,
+ );
+ return;
}
- trackPendingDelivery(
- connectionId,
- makeTurnEnd(terminalReplay.turnEnd),
- terminalReplay.completedAt,
- );
- return;
- }
- if (!ackDelivered) {
- persistTerminalRecord({ ...terminalReplay, delivery: 'pending' });
- return;
- }
- if (!send(makeTurnEnd(terminalReplay.turnEnd))) {
- persistTerminalRecord({ ...terminalReplay, delivery: 'pending' });
- return;
- }
- if (
- terminalReplay.delivery === 'pending' &&
- !markTerminalSent(connectionId, payload.requestId)
- ) {
- persistTerminalRecord({ ...terminalReplay, delivery: 'sent' });
- }
+ if (!ackDelivered) {
+ persistTerminalRecord({ ...replayRecord, delivery: 'pending' });
+ return;
+ }
+ if (!send(makeTurnEnd(restoredTurn))) {
+ persistTerminalRecord({ ...replayRecord, delivery: 'pending' });
+ return;
+ }
+ if (
+ replayRecord.delivery === 'pending' &&
+ !markTerminalSent(connectionId, payload.requestId)
+ ) {
+ persistTerminalRecord({ ...replayRecord, delivery: 'sent' });
+ }
+ });
return;
}
@@ -3202,6 +3262,8 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
serverFeatures.delete(connectionId);
},
dispose() {
+ mediaDisposed = true;
+ if (mediaCleanupTimer) clearInterval(mediaCleanupTimer);
backgroundResults.clear();
unsubscribeBackgroundResults?.();
clearRecoveryDeliveries();
@@ -3339,16 +3401,20 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {
if (!pending.turnEnd) continue;
// 本进程正在发布客户端终稿: 兜底帧留给崩溃重启, 发布结束后由正常路径发送。
if (isPublishingClientFinal(connectionId, pending.requestId)) continue;
- if (deliveryAck) {
- // 已在 ACK 缓冲中的条目由本函数开头的循环重放, 不再用文本帧重复补发。
- if (pendingDeliveryTurnEnds.has(ackKey(connectionId, pending.requestId))) continue;
- trackPendingDelivery(connectionId, makeTurnEnd(pending.turnEnd), pending.completedAt);
- continue;
- }
- if (!send(makeTurnEnd(pending.turnEnd))) return;
- if (!markTerminalSent(connectionId, pending.requestId)) {
- persistTerminalRecord({ ...pending, delivery: 'sent' });
- }
+ let transportFailed = false;
+ replayManagedTerminal(pending, send, (restoredTurn) => {
+ if (supportsDeliveryAck(connectionId)) {
+ // 已在 ACK 缓冲中的条目由本函数开头的循环重放, 不再用文本帧重复补发。
+ if (pendingDeliveryTurnEnds.has(ackKey(connectionId, pending.requestId))) return;
+ trackPendingDelivery(connectionId, makeTurnEnd(restoredTurn), pending.completedAt);
+ return;
+ }
+ if (!send(makeTurnEnd(restoredTurn))) { transportFailed = true; return; }
+ if (!markTerminalSent(connectionId, pending.requestId)) {
+ persistTerminalRecord({ ...pending, delivery: 'sent' });
+ }
+ });
+ if (transportFailed) return;
}
},
};
diff --git a/apps/desktop/src/main/hook-control/ipc.ts b/apps/desktop/src/main/hook-control/ipc.ts
index fb18e96d7c..c1ca5b0ad9 100644
--- a/apps/desktop/src/main/hook-control/ipc.ts
+++ b/apps/desktop/src/main/hook-control/ipc.ts
@@ -96,6 +96,7 @@ import { createHookTransport } from './transport.js';
import { registerSlackToolBridge, unregisterSlackToolBridge } from './slackToolBridge.js';
import { createHookBindingStore } from './bindings.js';
import { createHookRequestLedger } from './requestLedger.js';
+import { createHookMediaStore } from '../cindy-media/hookOutbox.js';
import {
buildGroupContextPrefix,
listTelegramKnownGroupsForStableBinding,
@@ -485,6 +486,7 @@ function ensureInstances(): { store: SlackHookStore; manager: HookControlManager
});
}
if (!manager) {
+ const mediaStore = createHookMediaStore();
const dispatcher = createHookDispatcher({
// 两个 provider 复用 dispatcher,但连接身份和服务地址彼此隔离。
getConnection: (connectionId) => {
@@ -532,8 +534,10 @@ function ensureInstances(): { store: SlackHookStore; manager: HookControlManager
}),
terminalLedger: createHookRequestLedger({
filePath: ownerScopedUserDataPath('hook-request-ledger.json'),
+ releaseMedia: mediaStore.release,
log,
}),
+ mediaStore,
runner: createMakerHookSessionRunner({ log }),
buildContextPrefix: buildGroupContextPrefix,
// 新建 hook 会话默认预建独立 worktree(并发隔离); deps 组装与
diff --git a/apps/desktop/src/main/hook-control/outbound.ts b/apps/desktop/src/main/hook-control/outbound.ts
index abd3f6cb02..736c911e19 100644
--- a/apps/desktop/src/main/hook-control/outbound.ts
+++ b/apps/desktop/src/main/hook-control/outbound.ts
@@ -22,6 +22,11 @@
*/
import path from 'node:path';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import type { Definition, PhrasingContent } from 'mdast';
import { promises as fsp } from 'node:fs';
import { localTaskImagePath, taskImageReferences, rewriteTaskImageReferences } from '../cindy-media/taskImageMarkdown';
@@ -68,6 +73,9 @@ export function buildHookPromptNote(im: string | undefined): string {
if (im === 'x') {
return (
`${attachmentNote}\n` +
+ 'X 附件只支持最多四张图片,或一个 GIF/视频,不能混发;不支持普通文件。' +
+ '视频写 `[说明](工具返回的 cindy-media:// 地址)` 或 `[说明](xdt-file:///工作目录内视频路径)`;' +
+ '图片每张至多 5MiB,GIF 至多 15MiB,MP4/MOV 视频至多 10MiB。\n' +
// session-runner 会先用 observer.finalText() 按桌面消息流规则拼出正式正文,
// 再由服务端 X 发送层收口成一条回复。不要退回旧的“只取最后一条消息”描述。
// 标题、列表、表格等结构仍参与正式正文判定,发布时才转换为纯文本。
@@ -147,6 +155,8 @@ function isPathWithin(base: string, target: string): boolean {
}
export interface OutboundDeps {
+ /** X supports managed video links and uses the existing file-size transport limit. */
+ provider?: string;
/** xdt-image:// URL -> absPath(生产: imageCacheStore.resolveSafe; 失败抛错)。 */
resolveImageUrl: (url: string) => { absPath: string };
/** xdt-file:// 允许读取的根目录; 未提供时 fail-closed, 不读取任何本地文件。 */
@@ -193,6 +203,36 @@ export function hasOutboundRefs(text: string): boolean {
);
}
+const mediaLinkParser = unified().use(remarkParse).use(remarkGfm);
+
+function visibleLabelText(node: PhrasingContent): string {
+ if (node.type === 'text' || node.type === 'inlineCode') return node.value;
+ if (node.type === 'image' || node.type === 'imageReference') return node.alt ?? '';
+ if (node.type === 'break') return '\n';
+ return 'children' in node ? node.children.map(visibleLabelText).join('') : '';
+}
+
+/** Managed media links, excluding code examples; never interpret them as file paths. */
+function managedMediaLinks(text: string): Array<{ url: string; start: number; end: number; label: string }> {
+ if (!text.includes('cindy-media://')) return [];
+ const tree = mediaLinkParser.parse(text);
+ const definitions = new Map<string, Definition>();
+ visit(tree, 'definition', (node) => {
+ if (!definitions.has(node.identifier)) definitions.set(node.identifier, node);
+ });
+ const refs: Array<{ url: string; start: number; end: number; label: string }> = [];
+ visit(tree, (node) => {
+ if (node.type !== 'link' && node.type !== 'linkReference') return;
+ const target = node.type === 'link' ? node : definitions.get(node.identifier);
+ const start = node.position?.start.offset;
+ const end = node.position?.end.offset;
+ if (!target?.url.startsWith('cindy-media://') || start === undefined || end === undefined) return;
+ const label = node.children.map(visibleLabelText).join('');
+ refs.push({ url: target.url, start, end, label });
+ });
+ return refs;
+}
+
/**
* 收集出站附件并变换正文。收集失败(单个文件读不到/超限)只跳过该项,
* 绝不抛错 —— 附件是回帖的增强, 不能因它失败拖垮 turn.end。
@@ -206,6 +246,11 @@ export async function collectOutboundAttachments(
const realpath = deps.realpath ?? ((p: string) => fsp.realpath(p));
const attachments: TaskAttachment[] = [];
const sentFileAbsPaths = new Set<string>();
+ const sentMediaPaths = new Set<string>();
+ const mediaLimit = (p: string): number => deps.provider === 'x'
+ ? guessMime(p) === 'image/gif' ? 15 * 1024 * 1024
+ : guessMime(p).startsWith('video/') ? MAX_OUT_FILE_BYTES : MAX_OUT_IMAGE_BYTES
+ : MAX_OUT_IMAGE_BYTES;
const fileAbsPathByUrl = new Map<string, string | null>();
let totalBytes = 0;
let skipped = 0;
@@ -242,6 +287,13 @@ export async function collectOutboundAttachments(
maxBytes: number,
mimeOverride?: string,
): Promise<boolean> => {
+ if (deps.provider === 'x' && sentMediaPaths.has(absPath)) return true;
+ if (deps.provider === 'x' && ![
+ 'image/jpeg', 'image/png', 'image/webp', 'image/gif', 'video/mp4', 'video/quicktime',
+ ].includes(mimeOverride ?? guessMime(absPath))) {
+ skipped += 1;
+ return false;
+ }
if (attachments.length >= MAX_OUT_ATTACHMENTS) {
skipped += 1;
return false;
@@ -266,6 +318,7 @@ export async function collectOutboundAttachments(
return false;
}
totalBytes += bytes.length;
+ sentMediaPaths.add(absPath);
attachments.push({
name: path.basename(absPath),
mimeType: mimeOverride ?? guessMime(absPath),
@@ -309,7 +362,22 @@ export async function collectOutboundAttachments(
}
}
for (const absPath of imageAbsPaths) {
- await push(absPath, MAX_OUT_IMAGE_BYTES);
+ await push(absPath, mediaLimit(absPath));
+ }
+
+ if (deps.provider === 'x') {
+ const seenLinks = new Set<string>();
+ for (const ref of managedMediaLinks(refScanText)) {
+ if (seenLinks.has(ref.url)) continue;
+ seenLinks.add(ref.url);
+ try {
+ const { absPath } = deps.resolveImageUrl(ref.url);
+ await push(absPath, mediaLimit(absPath));
+ } catch {
+ skipped += 1;
+ deps.log.warn('outbound managed media link could not be read');
+ }
+ }
}
// 2. 文件引用(去重同上)
@@ -333,14 +401,32 @@ export async function collectOutboundAttachments(
skipped += 1;
continue;
}
- if (await push(absPath, MAX_OUT_FILE_BYTES)) sentFileAbsPaths.add(absPath);
+ if (await push(absPath, deps.provider === 'x' ? mediaLimit(absPath) : MAX_OUT_FILE_BYTES)) sentFileAbsPaths.add(absPath);
}
// Collection is not a delivery receipt. Keep captions without claiming the channel sent them.
const imageUrls = new Map([...visitedImageUrls].map((url) => [url, url]));
- const captionText = rewriteTaskImageReferences(finalText, imageUrls, (ref) =>
+ let deliveryText = finalText;
+ if (deps.provider === 'x') {
+ for (const ref of managedMediaLinks(finalText).reverse()) {
+ deliveryText = deliveryText.slice(0, ref.start) + ref.label + deliveryText.slice(ref.end);
+ }
+ }
+ let captionText = rewriteTaskImageReferences(deliveryText, imageUrls, (ref) =>
ref.alt ? `🖼️ _${ref.alt.replace(/[*_\[\]\\]/g, '\\$&')}_` : '',
);
+ if (deps.provider === 'x') {
+ // Links have become captions; remove their now-unused private definitions too.
+ const definitions: Definition[] = [];
+ visit(mediaLinkParser.parse(captionText), 'definition', (node) => {
+ if (node.url.startsWith('cindy-media://')) definitions.push(node);
+ });
+ for (const node of definitions.reverse()) {
+ const start = node.position?.start.offset;
+ const end = node.position?.end.offset;
+ if (start !== undefined && end !== undefined) captionText = captionText.slice(0, start) + captionText.slice(end);
+ }
+ }
const transformed = transformXdtRefs(captionText, {
file: ({ alt, url }) => {
const absPath = fileAbsPathByUrl.get(url);
diff --git a/apps/desktop/src/main/hook-control/requestLedger.ts b/apps/desktop/src/main/hook-control/requestLedger.ts
index b2c93ca26b..4c568894a6 100644
--- a/apps/desktop/src/main/hook-control/requestLedger.ts
+++ b/apps/desktop/src/main/hook-control/requestLedger.ts
@@ -91,7 +91,19 @@ export function terminalDeliveryExpired(
return nowMs - completedAt > ttlMs;
}
+export interface HookMediaReference {
+ url: string;
+ refId: string;
+ name: string | null;
+ mimeType: string;
+ bytes: number;
+}
+
export interface HookTerminalRecord {
+ /** Managed pins only; Base64 remains a wire/in-memory representation. */
+ media?: HookMediaReference[];
+ /** Delivered/deleted media is a dedupe tombstone, never a text-only replay. */
+ mediaReleased?: true;
connectionId: string;
requestId: string;
ack: TaskAckPayload;
@@ -110,6 +122,7 @@ export interface HookRequestLedger {
/** Returns false when persistence failed; callers must fall back to in-memory delivery. */
set(record: HookTerminalRecord): boolean;
markSent(connectionId: string, requestId: string): boolean;
+ prune?(): void;
}
interface LedgerFile {
@@ -158,6 +171,13 @@ function isTerminalRecord(value: unknown): value is HookTerminalRecord {
) {
return false;
}
+ if (value.mediaReleased !== undefined && value.mediaReleased !== true) return false;
+ if (value.media !== undefined && (!Array.isArray(value.media) || value.media.length > 8
+ || value.media.some((ref) => !isRecord(ref)
+ || typeof ref.url !== 'string' || !/^cindy-media:\/\/blobs\/[a-f0-9]{64}\.[a-z0-9]+$/.test(ref.url)
+ || typeof ref.refId !== 'string' || (ref.name !== null && typeof ref.name !== 'string') || typeof ref.mimeType !== 'string'
+ || typeof ref.bytes !== 'number' || !Number.isInteger(ref.bytes) || ref.bytes <= 0 || ref.bytes > 15 * 1024 * 1024)
+ || value.media.reduce((sum, ref) => sum + ref.bytes, 0) > 30 * 1024 * 1024)) return false;
if (value.ack.requestId !== value.requestId) return false;
if (value.ack.result === 'rejected') {
return value.turnEnd === undefined && value.delivery === 'sent';
@@ -194,6 +214,7 @@ export function createHookRequestLedger(deps: {
maxFileBytes?: number;
pendingTtlMs?: number;
now?: () => number;
+ releaseMedia?: (media: HookMediaReference[]) => Promise<void>;
}): HookRequestLedger {
const maxEntries = Math.max(1, Math.floor(deps.maxEntries ?? DEFAULT_MAX_ENTRIES));
const maxFileBytes = Math.max(1_024, Math.floor(deps.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES));
@@ -256,7 +277,36 @@ export function createHookRequestLedger(deps: {
return cachedEntries;
}
+ function release(media: HookMediaReference[] | undefined): void {
+ if (media?.length) void deps.releaseMedia?.(media).catch(() => {
+ deps.log.warn('hook media pin cleanup deferred to expiry');
+ });
+ }
+
+ function withoutMedia(record: HookTerminalRecord): HookTerminalRecord {
+ const { media: _media, ...rest } = record;
+ if (!rest.turnEnd) return rest;
+ const { attachments: _bytes, ...turnEnd } = rest.turnEnd;
+ return { ...rest, turnEnd, ...((record.media?.length || _bytes?.length) ? { mediaReleased: true as const } : {}) };
+ }
+
+ function prune(): void {
+ const entries = readEntries();
+ if (!entries) return;
+ for (const record of entries) {
+ if ((record.media?.length || record.turnEnd?.attachments?.length) && reclaimable(record, now()))
+ writeRecord(withoutMedia(record));
+ }
+ }
+
function writeRecord(record: HookTerminalRecord): boolean {
+ if (reclaimable(record, now())) record = withoutMedia(record);
+ // Refuse a text-only durable success when media staging failed. The
+ // dispatcher still keeps/sends the complete frame in memory.
+ if (record.turnEnd?.attachments?.length) {
+ deps.log.warn('write hook request ledger skipped (unmanaged-media)');
+ return false;
+ }
if (!isTerminalRecord(record)) {
deps.log.warn('write hook request ledger skipped (invalid-record)');
return false;
@@ -276,7 +326,11 @@ export function createHookRequestLedger(deps: {
next.push(record);
let data: LedgerFile = { version: FILE_VERSION, entries: next };
let serialized = JSON.stringify(data);
- while (next.length > maxEntries || utf8ByteLength(serialized) > maxFileBytes) {
+ // Keep the existing aggregate outbox budget even though JSON now contains
+ // references: otherwise 2,000 pending records could pin gigabytes of media.
+ const mediaBudget = () => next.reduce((sum, entry) => sum +
+ (entry.media ?? []).reduce((bytes, ref) => bytes + Math.ceil(ref.bytes / 3) * 4, 0), 0);
+ while (next.length > maxEntries || utf8ByteLength(serialized) + mediaBudget() > maxFileBytes) {
// Never evict a *live* undelivered outbox entry to make room. Reclaim the
// oldest entry that is only holding a tombstone — already sent, or pending
// past the delivery horizon. Only a burst of live undelivered answers can
@@ -310,6 +364,8 @@ export function createHookRequestLedger(deps: {
try {
atomicWriteFileSync(deps.filePath, `${serialized}\n`);
cachedEntries = next;
+ const retained = new Set(next.flatMap((entry) => entry.media?.map((ref) => ref.refId) ?? []));
+ release(entries.flatMap((entry) => entry.media ?? []).filter((ref) => !retained.has(ref.refId)));
return true;
} catch (error) {
deps.log.warn(`write hook request ledger failed (${safeErrorCode(error)})`);
@@ -318,7 +374,9 @@ export function createHookRequestLedger(deps: {
}
return {
+ prune,
get(connectionId, requestId) {
+ prune();
const entries = readEntries();
if (entries === null) return null;
for (let index = entries.length - 1; index >= 0; index -= 1) {
@@ -329,6 +387,7 @@ export function createHookRequestLedger(deps: {
},
listPending(connectionId) {
+ prune();
const entries = readEntries();
if (entries === null) return [];
const nowMs = now();
diff --git a/apps/desktop/src/main/hook-control/session-runner.ts b/apps/desktop/src/main/hook-control/session-runner.ts
index aa4fdde11e..b411ce3dbd 100644
--- a/apps/desktop/src/main/hook-control/session-runner.ts
+++ b/apps/desktop/src/main/hook-control/session-runner.ts
@@ -422,17 +422,20 @@ function awaitingInteractionNotice(kind: string): string {
return AWAITING_INTERACTION_NOTICE[kind] ?? AWAITING_INTERACTION_FALLBACK;
}
-/** 兜底账本条目是否图片(hook 本期只外发图片):cindy-media 地址按扩展名判。 */
+/** 兜底账本图片白名单;X 还接收 MP4/MOV 视频:cindy-media 地址按扩展名判。 */
const PRODUCED_IMAGE_EXT_RE = /\.(png|jpe?g|gif|webp)$/i;
/** 导出仅供单测(纯函数,不碰 electron)。 */
-export function extractToolResultImageUrls(toolResultText: string): string[] {
- if (!toolResultText.includes('xdt_image_url') && !toolResultText.includes('xdt_media_produced')) {
+export function extractToolResultMediaUrls(toolResultText: string, provider?: string): string[] {
+ if (!toolResultText.includes('xdt_image_url') && !toolResultText.includes('xdt_media_produced')
+ && !(provider === 'x' && toolResultText.includes('xdt_video_url'))) {
return [];
}
let parsed: {
xdt_image_url?: unknown;
xdt_image_urls?: unknown;
+ xdt_video_url?: unknown;
+ xdt_video_urls?: unknown;
xdt_media_produced?: unknown;
_xdt_render_image?: unknown;
};
@@ -451,11 +454,17 @@ export function extractToolResultImageUrls(toolResultText: string): string[] {
if (typeof u === 'string' && isRenderableImageUrl(u)) urls.push(u);
}
}
+ if (provider === 'x') {
+ const videos = [parsed.xdt_video_url, ...(Array.isArray(parsed.xdt_video_urls) ? parsed.xdt_video_urls : [])];
+ for (const url of videos) {
+ if (typeof url === 'string' && isRenderableImageUrl(url)) urls.push(url);
+ }
+ }
// 兜底账本(xdt_media_produced,ghost_call 层在意识未声明媒体字段时注入,
- // 主机记账、意识删不掉):可能混有视频/音频/3D,这里只接走图片。
+ // 主机记账、意识删不掉):X 接走图片与视频,其余渠道维持图片。
if (Array.isArray(parsed.xdt_media_produced)) {
for (const u of parsed.xdt_media_produced) {
- if (typeof u === 'string' && isRenderableImageUrl(u) && PRODUCED_IMAGE_EXT_RE.test(u)) {
+ if (typeof u === 'string' && isRenderableImageUrl(u) && (PRODUCED_IMAGE_EXT_RE.test(u) || (provider === 'x' && /\.(mp4|mov)$/i.test(u)))) {
urls.push(u);
}
}
@@ -474,12 +483,13 @@ function resolveRenderableImageUrl(url: string): { absPath: string } {
* art image_generate 等工具按设计不在文本里嵌 xdt-image markdown, 渠道侧能拿到
* 图的唯一通路是从 tool_result JSON 里接走 URL。解析失败只 warn, 不拖垮 turn。
*/
-function collectOutboundImages(
+function collectOutboundMedia(
fullText: string,
sink: string[],
log: { warn(msg: string): void },
+ provider?: string,
): void {
- for (const url of extractToolResultImageUrls(fullText)) {
+ for (const url of extractToolResultMediaUrls(fullText, provider)) {
try {
const { absPath } = resolveRenderableImageUrl(url);
sink.push(absPath);
@@ -546,6 +556,7 @@ async function collectOutboundForFinalText(
extraImageAbsPaths: string[],
allowedFileRoots: string[],
log: { warn(msg: string): void },
+ provider?: string,
): Promise<{ finalText: string; attachments?: HookRunOutcome['attachments'] }> {
// Defense in depth for X/Slack/Telegram: live Codex traffic is normalized in
// maker-core, but older persisted/continuation text and future adapters must
@@ -571,6 +582,7 @@ async function collectOutboundForFinalText(
throw new Error('Remote media is not available on this host');
},
allowedFileRoots,
+ provider,
...(wholeTurn !== publicText ? { refScanText: wholeTurn } : {}),
log,
});
@@ -1100,7 +1112,7 @@ export function createMakerHookSessionRunner(deps: {
? { progressBodyMode: 'whole' as const, flushProgressOnDone: true }
: {}),
onToolResult: (fullText) => {
- if (allowedFileRoots.length > 0) collectOutboundImages(fullText, extraImageAbsPaths, log);
+ if (allowedFileRoots.length > 0) collectOutboundMedia(fullText, extraImageAbsPaths, log, req.source?.im);
},
onSilentStopSettled,
log,
@@ -1543,7 +1555,7 @@ export function createMakerHookSessionRunner(deps: {
observer.stop();
const collected = observer.errorReason === 'output-limit'
? await collectOutboundForFinalText(
- session.id, turnTextsFor(observer), extraImageAbsPaths, allowedFileRoots, log,
+ session.id, turnTextsFor(observer), extraImageAbsPaths, allowedFileRoots, log, req.source?.im,
)
: { finalText: '' };
// 额度类失败要说清是哪个供应商: 名字只在这里按需读一次(读不到退回「当前供应商」)。
@@ -1575,6 +1587,7 @@ export function createMakerHookSessionRunner(deps: {
extraImageAbsPaths,
allowedFileRoots,
log,
+ req.source?.im,
);
let finalText = collected.finalText;
const outAttachments = collected.attachments;
@@ -1689,7 +1702,7 @@ function beginContinuationWatch(
? { progressBodyMode: 'whole' as const, flushProgressOnDone: true }
: {}),
onToolResult: (fullText) => {
- if (allowedFileRoots.length > 0) collectOutboundImages(fullText, extraImageAbsPaths, log);
+ if (allowedFileRoots.length > 0) collectOutboundMedia(fullText, extraImageAbsPaths, log, req.source?.im);
},
onSilentStopSettled,
log,
@@ -1733,6 +1746,7 @@ function beginContinuationWatch(
extraImageAbsPaths,
allowedFileRoots,
log,
+ req.source?.im,
);
req.onEnd({
status: errorMessage === null ? 'ok' : 'error',
diff --git a/docs/dev-rules/im-turn-flow.md b/docs/dev-rules/im-turn-flow.md
index e7a4d3d4f3..3dc6d98ebc 100644
--- a/docs/dev-rules/im-turn-flow.md
+++ b/docs/dev-rules/im-turn-flow.md
@@ -101,7 +101,17 @@ Telegram / Slack / X)是同一件事的两套实现:把渠道里的一条消
被召唤的消息永远不经过判定。判定走共享辅助模型链(`im/shared/ambientReplyJudge.ts`),不得在这里起主模型。
7. **计划对账**只在真实用户轮次注入(官方仅 `source.im` 存在时)。
8. **终稿必达**(官方):`turn.end` 先进持久出箱;客户端发布终稿时以 `clientFinal` 交回。
- 带附件的轮次不由客户端发布(出箱只存文本);兜底帧写不进出箱时也不由客户端发布;本进程
+ 带附件的轮次不由客户端发布。Telegram / Slack 的持久出箱只存文本;X 的出箱保留
+ `cindy-media` 地址、引用 ID、名称、MIME 与大小,Base64 只存在传输帧和内存中。
+ X 仅收 JPEG / PNG / WebP / GIF / MP4 / MOV;单图片 5 MiB、GIF 15 MiB、视频 10 MiB,
+ 一轮最多 8 项、总计 30 MiB(服务端再核验 X 的附件组合;持久出箱仍按 32 MB 总预算计入媒体的传输大小)。托管媒体通过 `ingestMedia`
+ 作为非缓存入库;待发 pin 使用 `message` 引用、出生任务与 `hook-outbox` 来源,沿用
+ 任务删除清理。恢复时核对当前账号、任务与引用,失效不重放附件;仍待发的结果保留 24 小时。
+ 收到 `turn.delivery`(未协商回执时为 transport 接受)后清除出箱媒体地址并释放 pin;
+ 定时及读路径清理过期出箱,媒体仓同时回收崩溃遗留 pin,
+ 物理字节仅由既有媒体回收器处置,不删除仍被聊天/画廊引用的媒体。
+ 媒体入仓或出箱失败时保留原有完整内存发送兜底,并记录持久化失败;不得将丢附件记作持久化成功。
+ 兜底帧写不进出箱时也不由客户端发布;本进程
仍在发布、正式 `turn.end` 还没进入发送 / 缓冲路径时,重连扫描与服务端重投 `task.dispatch` 都不重放出箱里的兜底帧(重投只回放 ack);终稿段
回执未知先同 opId 有界重发对账,仍未知才交回。
9. **明确停止 = 与桌面 Stop 同一语义**:撤自动续跑与退避簿记、取消上下文溢出恢复、暂停