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(orca): lead 可随派发消息向本机 worker 发送图片

Zhang Yunjin766be6eefd0b
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
index 2d11195a87..01b4c08d81 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
@@ -315,6 +315,87 @@ describe('Orca lead/worker dispatcher', () => {
);
});
+ it('attaches validated images as blocks on live send and files on queued entries', async () => {
+ const validateImageAttachments = vi.fn(async (paths: string[]) => ({
+ ok: true as const,
+ images: paths.map((p) => ({
+ path: p, name: p.split(/[\\/]/).pop() ?? p, ext: '.png', size: 10, mimeType: 'image/png',
+ })),
+ }));
+ const live = createHarness({ validateImageAttachments });
+ const result = await live.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({
+ targetSessionId: 'target-session',
+ rawContent: 'Check this screenshot',
+ source: 'lead',
+ senderLabel: 'Lead',
+ imagePaths: ['C:/tmp/a.png', 'C:/tmp/b.png'],
+ meta: { source: 'orca', context: 'images-live-test' },
+ });
+ expect(result).toMatchObject({ ok: true, mode: 'dispatched' });
+ expect(validateImageAttachments).toHaveBeenCalledWith(['C:/tmp/a.png', 'C:/tmp/b.png']);
+ expect(live.liveSession.send.mock.calls[0]?.[0]).toEqual({
+ type: 'user',
+ content: [
+ { type: 'text', text: expect.stringContaining('Check this screenshot') },
+ { type: 'image', path: 'C:/tmp/a.png', mimeType: 'image/png' },
+ { type: 'image', path: 'C:/tmp/b.png', mimeType: 'image/png' },
+ ],
+ });
+
+ const queued = createHarness({
+ validateImageAttachments,
+ shouldQueueNewTurn: vi.fn(() => true),
+ });
+ await queued.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({
+ targetSessionId: 'target-session',
+ rawContent: 'Check this screenshot',
+ source: 'lead',
+ senderLabel: 'Lead',
+ imagePaths: ['C:/tmp/a.png'],
+ meta: { source: 'orca', context: 'images-queued-test' },
+ });
+ const item = firstQueuedItem(queued.queuedItems);
+ expect(item.files).toEqual([expect.objectContaining({
+ path: 'C:/tmp/a.png', category: 'image', mimeType: 'image/png',
+ })]);
+ });
+
+ it('rejects images for remote targets and invalid files without sending', async () => {
+ const remote = createHarness({
+ getSessionRowSnapshot: vi.fn(async () => ({
+ title: 'Target Session',
+ status: 'active',
+ userSendAt: Date.parse('2026-06-12T01:02:03.000Z'),
+ remoteHostId: 'host-1',
+ })),
+ });
+ const remoteResult = await remote.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({
+ targetSessionId: 'target-session',
+ rawContent: 'Look',
+ source: 'lead',
+ senderLabel: 'Lead',
+ imagePaths: ['C:/tmp/a.png'],
+ meta: { source: 'orca', context: 'images-remote-test' },
+ });
+ expect(remoteResult).toMatchObject({ ok: false });
+ expect(remote.liveSession.send).not.toHaveBeenCalled();
+
+ const invalid = createHarness({
+ validateImageAttachments: vi.fn(async () => ({ ok: false as const, message: 'image not found: C:/tmp/missing.png' })),
+ });
+ const invalidResult = await invalid.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({
+ targetSessionId: 'target-session',
+ rawContent: 'Look',
+ source: 'lead',
+ senderLabel: 'Lead',
+ imagePaths: ['C:/tmp/missing.png'],
+ meta: { source: 'orca', context: 'images-invalid-test' },
+ });
+ expect(invalidResult).toMatchObject({ ok: false });
+ expect(invalid.deps.sendToSessionInternal).not.toHaveBeenCalled();
+ expect(invalid.liveSession.send).not.toHaveBeenCalled();
+ });
+
it('prepares an unhealthy live session before direct send and does not reuse the closed handle', async () => {
const closed = { current: false };
const liveSession = createLiveSession(async (_message, opts) => {
diff --git a/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts b/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
index 5ad87f95da..ceafa1d6be 100644
--- a/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
@@ -9,6 +9,7 @@ import type { AgentKind, SessionSendOptions, SessionSendResult, UserMessage } fr
import type {
AgentInputCreateOpts,
AgentInputQueuedMessage,
+ AgentInputSerializedFile,
} from '../../shared/agentInputQueue.js';
import { createLogger } from '../logger.js';
import { createHostSendFailure } from '../maker-host/send-outcome.js';
@@ -61,6 +62,8 @@ export interface DispatchOrcaInterAgentMessageParams {
workerId?: string;
/** 发送方显式选择;缺省排队。steer 只在目标正在运行时插进当前 turn。 */
delivery?: 'queue' | 'steer';
+ /** 可选, 随消息发给目标的本机图片绝对路径; 仅本机 session 支持, SSH 远端目标拒绝。 */
+ imagePaths?: string[];
/** Synchronous reserve boundary hook; must return before drain is scheduled. */
onReserved?: () => void;
beforeReserve?: () => Promise<void>;
@@ -92,6 +95,8 @@ export interface OrcaInterAgentSessionRowSnapshot {
title: string | null;
status: string | null;
userSendAt: string | number | Date | null;
+ /** 图片附件仅支持本机 session; SSH 远端目标必须拒绝。 */
+ remoteHostId?: string | null;
}
/** register.ts 现有 sendToSessionInternal 的窄结果形状,Orca dispatcher 只消费派发语义。 */
@@ -139,6 +144,15 @@ export interface OrcaInterAgentSendToSessionInternalParams {
origin?: AgentInputQueuedMessage['origin'];
}
+/** 校验后的图片附件; host 注入的 validateImageAttachments 产出, dispatcher 只消费。 */
+export interface OrcaInterAgentImageAttachment {
+ path: string;
+ name: string;
+ ext: string;
+ size: number;
+ mimeType: string;
+}
+
/** Orca dispatcher 内部日志接口,保持测试和宿主 logger 可替换。 */
export interface OrcaInterAgentDispatcherLogger {
info: (message: string, meta?: Record<string, unknown>) => void;
@@ -167,6 +181,13 @@ export interface OrcaInterAgentDispatcherDeps<TSessionMeta> {
withSendToSessionLock?: <T>(sessionId: string, task: () => Promise<T>) => Promise<T>;
/** 直发前与 sendToSessionInternal 共用同一套满窗 / compact 失败换窗预检。 */
prepareUnhealthySession?: (sessionId: string) => Promise<boolean | void>;
+ /**
+ * 校验 imagePaths(存在性 + 图片扩展名), 返回逐张附件元数据或错误消息。
+ * fs 属 host 边界, dispatcher 不直接碰文件系统。
+ */
+ validateImageAttachments?: (
+ paths: string[],
+ ) => Promise<{ ok: true; images: OrcaInterAgentImageAttachment[] } | { ok: false; message: string }>;
buildCreateOptsForQueuedSession: (
sessionId: string,
meta: TSessionMeta,
@@ -360,6 +381,66 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
const buildAgentMessageText = async (): Promise<string> =>
formatAgentMessage(params.source, params.rawContent, params.workerId, await resolveRole());
const persistedContent = formatOrcaCommunicationMessage(params.source, params.rawContent);
+ // 图片附件: 入口处一次校验(存在性 + 图片扩展名 + 本机限定);三条投递路径共用。
+ let imageFiles: AgentInputSerializedFile[] = [];
+ if (params.imagePaths?.length) {
+ if (dbRow.remoteHostId) {
+ return {
+ ok: false,
+ dispatchOutcome: {
+ ...createHostSendFailure(
+ 'SEND_FAILED',
+ 'image attachments are only supported for local sessions; SSH remote targets are not supported',
+ ),
+ source: params.meta.source,
+ context: params.meta.context,
+ },
+ };
+ }
+ if (!deps.validateImageAttachments) {
+ return {
+ ok: false,
+ dispatchOutcome: {
+ ...createHostSendFailure('SEND_FAILED', 'image attachments are not supported by this host'),
+ source: params.meta.source,
+ context: params.meta.context,
+ },
+ };
+ }
+ const validated = await deps.validateImageAttachments(params.imagePaths);
+ if (!validated.ok) {
+ return {
+ ok: false,
+ dispatchOutcome: {
+ ...createHostSendFailure('SEND_FAILED', validated.message),
+ source: params.meta.source,
+ context: params.meta.context,
+ },
+ };
+ }
+ imageFiles = validated.images.map((image) => ({
+ id: deps.createId(),
+ name: image.name,
+ path: image.path,
+ ext: image.ext,
+ size: image.size,
+ category: 'image',
+ mimeType: image.mimeType,
+ }));
+ }
+ // 直发时 image block 跟在格式化文本后;排队/插话时文件挂在 entry.files,
+ // drain 由 buildMakerUserMessage 还原成同样的 block 序列。
+ const agentMessageTextWithImages = async (): Promise<UserMessage> => {
+ const text = await buildAgentMessageText();
+ if (imageFiles.length === 0) return { type: 'user', content: text };
+ return {
+ type: 'user',
+ content: [
+ { type: 'text', text },
+ ...imageFiles.map((file) => ({ type: 'image' as const, path: file.path, mimeType: file.mimeType })),
+ ],
+ };
+ };
let acceptedDidRun = false;
const runAccepted = async (): Promise<void> => {
acceptedDidRun = true;
@@ -416,6 +497,7 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
persistedContent,
origin: await resolveOrigin(),
createOpts,
+ ...(imageFiles.length ? { files: imageFiles } : {}),
});
if (params.onAccepted) {
registerQueuedOrcaInterAgentAcceptedCallback(
@@ -462,6 +544,7 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
persistedContent,
origin: await resolveOrigin(),
createOpts,
+ ...(imageFiles.length ? { files: imageFiles } : {}),
});
if (
deps.getLiveSession(params.targetSessionId) !== liveTurn ||
@@ -570,14 +653,11 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
await deps.prepareUnhealthySession?.(params.targetSessionId);
const live = deps.getLiveSession(params.targetSessionId);
if (!live) return null;
- const [origin, agentMessageText] = await Promise.all([
- resolveOrigin(),
- buildAgentMessageText(),
- ]);
+ const origin = await resolveOrigin();
const result = await sendPersistedUserMessageToSession(deps, {
session: live,
dbContent: persistedContent,
- agentMessage: { type: 'user', content: agentMessageText },
+ agentMessage: await agentMessageTextWithImages(),
clientId,
source: params.meta.source,
context: params.meta.context,
@@ -605,6 +685,17 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
? await deps.withSendToSessionLock(params.targetSessionId, dispatchLive)
: await dispatchLive();
if (liveResult) return liveResult;
+ // 带图时 no-live 回退路径(sendToSessionInternal 重建)只支持纯文本,宁拒勿静默丢图。
+ if (imageFiles.length > 0) {
+ return failureResult({
+ ...createHostSendFailure(
+ 'SEND_FAILED',
+ 'image attachments require a live local session; retry after the target session is available',
+ ),
+ source: params.meta.source,
+ context: params.meta.context,
+ });
+ }
return await sendToInternal();
} catch (err) {
return failureResult({
@@ -854,6 +945,7 @@ function buildQueuedOrcaInterAgentMessage(params: {
persistedContent: string;
origin: NonNullable<AgentInputQueuedMessage['origin']>;
createOpts: AgentInputCreateOpts;
+ files?: AgentInputSerializedFile[];
}): AgentInputQueuedMessage {
const createdAt = new Date().toISOString();
return {
@@ -866,6 +958,7 @@ function buildQueuedOrcaInterAgentMessage(params: {
permissionMode: params.createOpts.permissionMode ?? 'bypassPermissions',
workingDir: params.createOpts.workingDir,
vendorOptions: params.createOpts.vendorOptions,
+ ...(params.files?.length ? { files: params.files } : {}),
chatMessage: {
clientId: params.clientId,
role: 'user',
diff --git a/apps/desktop/src/main/maker-ipc/orcaLifecycleService.ts b/apps/desktop/src/main/maker-ipc/orcaLifecycleService.ts
index 3a8ce4efe7..9f227edd09 100644
--- a/apps/desktop/src/main/maker-ipc/orcaLifecycleService.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaLifecycleService.ts
@@ -98,6 +98,7 @@ export interface OrcaLifecycleDeps {
dispatchWorkerTask(params: {
targetSessionId: string;
message: string;
+ imagePaths?: string[];
dispatchMeta: {
source: string;
context: string;
@@ -204,6 +205,7 @@ export function createOrcaLifecycleService(deps: OrcaLifecycleDeps): OrcaLifecyc
async function dispatchInitialTask(params: {
workerSessionId: string;
message: string | undefined;
+ imagePaths?: string[];
context: string;
}, assertCurrent?: () => Promise<void>): Promise<DispatchWorkerTaskResult | undefined> {
if (!params.message) return undefined;
@@ -223,6 +225,7 @@ export function createOrcaLifecycleService(deps: OrcaLifecycleDeps): OrcaLifecyc
const result = await deps.dispatchWorkerTask({
targetSessionId: params.workerSessionId,
message: params.message,
+ ...(params.imagePaths ? { imagePaths: params.imagePaths } : {}),
dispatchMeta: {
source: dispatchSource,
context: params.context,
@@ -275,6 +278,7 @@ export function createOrcaLifecycleService(deps: OrcaLifecycleDeps): OrcaLifecyc
dispatchResult = await dispatchInitialTask({
workerSessionId: created.workerSessionId,
message: initialTask,
+ ...(params.initialTaskImages ? { imagePaths: params.initialTaskImages } : {}),
context: `create_worker/${created.workerSessionId}/initial_task`,
}, assertCreatedCurrent);
} else {
diff --git a/apps/desktop/src/main/maker-ipc/orcaTeamService.ts b/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
index 26ed6de36d..1124fff310 100644
--- a/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
@@ -110,6 +110,8 @@ export type DispatchWorkerMessageResult =
export interface DispatchWorkerTaskParams {
targetSessionId: string;
message: string;
+ /** 可选, 随首条任务发给 worker 的本机图片绝对路径; 仅本机 worker。 */
+ imagePaths?: string[];
dispatchMeta: {
source: string;
context: string;
@@ -286,6 +288,7 @@ export interface OrcaTeamServiceDeps {
message: string;
workerId: string;
delivery?: 'queue' | 'steer';
+ imagePaths?: string[];
dispatchMeta: {
source: string;
context: string;
@@ -908,6 +911,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
message: string;
mode: 'normal' | 'interrupt';
delivery?: 'queue' | 'steer';
+ imagePaths?: string[];
dispatchMeta: DispatchWorkerTaskParams['dispatchMeta'];
assertCurrent?: () => Promise<void>;
}): Promise<ResolvedWorkerDispatchExecution> {
@@ -1041,6 +1045,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
message: params.message,
workerId: link.workerId,
...(params.delivery ? { delivery: params.delivery } : {}),
+ ...(params.imagePaths ? { imagePaths: params.imagePaths } : {}),
dispatchMeta: params.dispatchMeta,
onAccepted,
onAcceptedRollback: rollbackAccepted,
@@ -1123,6 +1128,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
targetSessionId: string;
message: string;
delivery?: 'queue' | 'steer';
+ imagePaths?: string[];
}, assertCurrent?: () => Promise<void>): Promise<SendToWorkerResult> {
return dispatchToWorker({ ...params, mode: 'normal' }, assertCurrent) as Promise<SendToWorkerResult>;
}
@@ -1142,6 +1148,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
message: string;
mode: 'normal' | 'interrupt';
delivery?: 'queue' | 'steer';
+ imagePaths?: string[];
}, captured?: () => Promise<void>): Promise<SendToWorkerResult | InterruptWorkerResult> {
const assertCurrent = captured ?? await deps.captureControlAuthority?.(params.callerLeadSessionId);
const resolved = await resolveWorkerRef(params.callerLeadSessionId, params.targetSessionId);
@@ -1160,6 +1167,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
message: params.message,
mode: params.mode,
...(params.delivery ? { delivery: params.delivery } : {}),
+ ...(params.imagePaths ? { imagePaths: params.imagePaths } : {}),
assertCurrent,
dispatchMeta: {
source: 'maker-ipc/collab',
diff --git a/apps/desktop/src/main/maker-ipc/orcaWorkerCreationService.ts b/apps/desktop/src/main/maker-ipc/orcaWorkerCreationService.ts
index e6b8ade7be..cfdaabf2bb 100644
--- a/apps/desktop/src/main/maker-ipc/orcaWorkerCreationService.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaWorkerCreationService.ts
@@ -206,6 +206,8 @@ export interface OrcaWorkerCreateParams {
*/
providerId?: string | null;
initialTask?: string;
+ /** 可选, 随 initial_task 发给 worker 的本机图片绝对路径; 仅本机 worker。 */
+ initialTaskImages?: string[];
/** Existing absolute directory on the Worker's host; omission inherits Lead. */
workingDir?: string;
/** 显式值用于本次创建;缺省读取全局 Worker 创建偏好。 */
@@ -289,6 +291,7 @@ export interface OrcaWorkerCreationDeps {
dispatchWorkerTask(params: {
targetSessionId: string;
message: string;
+ imagePaths?: string[];
dispatchMeta: {
source: string;
context: string;
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index 79f07c20cf..a02a05f1f1 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -2199,6 +2199,7 @@ interface OrcaCollabService {
label: string;
workingDir?: string;
initialTask?: string;
+ initialTaskImages?: string[];
}) => Promise<
| {
ok: true;
@@ -2307,6 +2308,7 @@ interface OrcaCollabService {
targetSessionId: string;
message: string;
delivery?: 'queue' | 'steer';
+ imagePaths?: string[];
}) => Promise<SendToWorkerResult>;
interruptWorker: (params: {
callerLeadSessionId: string;
@@ -11979,6 +11981,38 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
getSessionMeta: (sessionId) => maker.getSessionMeta(sessionId).catch(() => null),
getSessionRowSnapshot,
getLiveSession: (sessionId) => maker.getSession(sessionId),
+ validateImageAttachments: async (paths) => {
+ // 图片附件仅支持本机;扩展名白名单 + 存在性检查,失败给 Lead 可读的错误。
+ const mimeByExt: Record<string, string> = {
+ '.png': 'image/png',
+ '.jpg': 'image/jpeg',
+ '.jpeg': 'image/jpeg',
+ '.gif': 'image/gif',
+ '.webp': 'image/webp',
+ };
+ const images: Array<{ path: string; name: string; ext: string; size: number; mimeType: string }> = [];
+ for (const rawPath of paths) {
+ const ext = path.extname(rawPath).toLowerCase();
+ const mimeType = mimeByExt[ext];
+ if (!mimeType) {
+ return { ok: false, message: `unsupported image type (png/jpeg/gif/webp only): ${rawPath}` };
+ }
+ try {
+ const stat = await fsp.stat(rawPath);
+ if (!stat.isFile()) throw new Error('not a file');
+ images.push({
+ path: rawPath,
+ name: path.basename(rawPath),
+ ext,
+ size: stat.size,
+ mimeType,
+ });
+ } catch {
+ return { ok: false, message: `image not found or unreadable: ${rawPath}` };
+ }
+ }
+ return { ok: true, images };
+ },
shouldQueueNewTurn: (sessionId): boolean => inputCoordinator.shouldQueueNewTurn(sessionId),
steerControlInput: (sessionId, item, expectedTurn) =>
inputCoordinator.steerControlInput(sessionId, { item }, expectedTurn),
@@ -12521,6 +12555,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
message,
workerId,
delivery,
+ imagePaths,
dispatchMeta,
onAccepted,
onAcceptedRollback,
@@ -12533,6 +12568,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
senderLabel: 'Lead',
workerId,
...(delivery ? { delivery } : {}),
+ ...(imagePaths ? { imagePaths } : {}),
meta: dispatchMeta,
onAccepted,
onAcceptedRollback,
diff --git a/docs/dev-rules/orca-team-architecture.md b/docs/dev-rules/orca-team-architecture.md
index ea41ce1d87..171a2c3483 100644
--- a/docs/dev-rules/orca-team-architecture.md
+++ b/docs/dev-rules/orca-team-architecture.md
@@ -109,11 +109,11 @@ PR #101 之后,Orca 的 main 侧业务由独立 service 承接,`register.ts`
1. `start_team`
2. `end_team`
3. `create_worker`
-4. `create_workers`(批量创建;顺序执行、hard limit 后停止并返回逐项汇总)
+4. `create_workers`(批量创建;顺序执行、hard limit 后停止并返回逐项汇总;每项支持可选 `images` 随 `initial_task` 发本机图片)
5. `list_workers`
6. `switch_focus`
-7. `send_to_worker`
-8. `interrupt_worker`(原子预留下一条输入并优雅停止当前 turn)
+7. `send_to_worker`(支持可选 `images`:本机图片绝对路径,随消息发给本机 worker;SSH 远端 worker 拒绝)
+8. `interrupt_worker`(原子预留下一条输入并优雅停止当前 turn;不支持图片)
9. `get_worker_queue_status`(工作态与完整队列)
10. `update_queued_message`(排队消息控制)
11. `cancel_queued_message`(排队消息控制)
@@ -312,6 +312,17 @@ Git worktree,不改变供应商、模型与 Worker 创建权限偏好。
1a. **空闲 live 直发前必须先做换窗预检(状态:不变量)**<br>
目标空闲且已有 live session 时,dispatcher 仍走 `session.send()`,不经过 `sendToSessionInternal()`。这条直发必须先调用与用户发送相同的 `prepareUnhealthySession`:满窗或当前进程内 `needsRollover` 锁存时关闭旧原生窗口,再 `getLiveSession`。不能把 inter-agent 消息打进应被丢弃的旧窗口。prepare → 重新取 live → send 整段必须复用 `sendToSessionInternal` 的 per-session 锁;锁已被占用时先排队,不要把 in-flight prepare 当成健康状态继续直发。没有 live 后释放锁再走 `sendToSessionInternal`,避免自己把自己排队。实现指针:`orcaInterAgentDispatcher.ts` 的 live 分支,以及 `register.ts` 注入的 `prepareUnhealthySession` / `withSendToSessionLock`。
+1c. **图片附件仅限本机目标,走既有附件通道(状态:不变量)**<br>
+ `send_to_worker` 与 `create_worker` / `create_workers` 的 `images` 参数只接受本机图片绝对路径
+ (png/jpeg/gif/webp,最多 8 张);目标 session 的 DB 快照带 `remoteHostId` 时必须拒绝,
+ 不降级为纯文本(静默丢图是产品错误)。dispatcher 入口经 host 注入的
+ `validateImageAttachments` 做存在性与扩展名校验;直发时 image block 跟在格式化文本后,
+ 排队/插话时文件挂在 entry `files`,drain 由 `buildMakerUserMessage` 还原成同样的
+ block 序列;`update_queued_message` / `merge_queued_messages` 重建只改文本字段,
+ files 随 `...entry` 保留。带图消息的 `persistedContent`(DB/展示)仍是纯文本协议,
+ 队列气泡不预览图片(已知边界)。实现指针:`orcaInterAgentDispatcher.ts` 的
+ `imageFiles` / `agentMessageTextWithImages` 与 `register.ts` 的 `validateImageAttachments`。
+
2. **accepted 才能产生运行副作用(状态:不变量)**<br>
只有底层 send accepted 后,才能把 worker 标成 `running`、建立 auto-bridge pending 并广播 UI;dispatch 失败必须 rollback 到 accepted 前状态,且 rollback 不得覆盖已有终态。实现指针:`orcaTeamService.ts` 的 `dispatchResolvedWorker` 与 `rollbackAcceptedDispatchState`。
diff --git a/packages/lizi-mcps/src/__tests__/createWorkerTool.test.ts b/packages/lizi-mcps/src/__tests__/createWorkerTool.test.ts
index 3fb981e401..0e7a31146a 100644
--- a/packages/lizi-mcps/src/__tests__/createWorkerTool.test.ts
+++ b/packages/lizi-mcps/src/__tests__/createWorkerTool.test.ts
@@ -68,6 +68,23 @@ describe('create_worker tool', () => {
expect(createWorker).not.toHaveBeenCalled();
});
+ it('forwards initial_task images to the host and omits them when absent', async () => {
+ const { registry, createWorker } = setup();
+ await registry.call('create_worker', {
+ role: 'developer', agent: 'codex', label: 'worker',
+ initial_task: 'review the screenshots', images: ['/tmp/a.png'],
+ });
+ expect(createWorker).toHaveBeenCalledWith(expect.objectContaining({
+ initialTask: 'review the screenshots',
+ initialTaskImages: ['/tmp/a.png'],
+ }));
+
+ await registry.call('create_worker', {
+ role: 'developer', agent: 'codex', label: 'worker2', initial_task: 'text only',
+ });
+ expect(vi.mocked(createWorker).mock.calls[1]?.[0]).not.toHaveProperty('initialTaskImages');
+ });
+
it('describes the subagent distinction before creating a worker', () => {
const { registry } = setup();
diff --git a/packages/lizi-mcps/src/__tests__/sessionContext.test.ts b/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
index b6780e3926..86feef4d20 100644
--- a/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
+++ b/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
@@ -179,7 +179,7 @@ describe('dynamic lizi MCP session context', () => {
const schemaKeys = Object.keys(
tools(server).send_to_worker.inputSchema?.shape ?? {},
);
- expect(schemaKeys).toEqual(['target_session_id', 'message', 'delivery']);
+ expect(schemaKeys).toEqual(['target_session_id', 'message', 'delivery', 'images']);
expect(schemaKeys).not.toContain('interrupt');
});
@@ -257,6 +257,31 @@ describe('dynamic lizi MCP session context', () => {
expect(vi.mocked(deps.sendToWorker).mock.calls[0]?.[0]).not.toHaveProperty('delivery');
});
+ it('forwards send_to_worker images to the host and omits them when absent', async () => {
+ const deps = createOrcaDeps();
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ await tools(server).send_to_worker.handler({
+ target_session_id: 'worker-session-1',
+ message: 'review this',
+ images: ['/tmp/a.png', '/tmp/b.jpg'],
+ } as never);
+ expect(vi.mocked(deps.sendToWorker).mock.calls[0]?.[0]).toMatchObject({
+ images: ['/tmp/a.png', '/tmp/b.jpg'],
+ });
+
+ await tools(server).send_to_worker.handler({
+ target_session_id: 'worker-session-1',
+ message: 'text only',
+ } as never);
+ expect(vi.mocked(deps.sendToWorker).mock.calls[1]?.[0]).not.toHaveProperty('images');
+ });
+
it('reads the caller own input queue when get_worker_queue_status omits worker_id', async () => {
const deps = createOrcaDeps({
listWorkerQueuedMessages: vi.fn(async () => ({
diff --git a/packages/lizi-mcps/src/orca/server.ts b/packages/lizi-mcps/src/orca/server.ts
index 4a3e3a1b66..1056b1729e 100644
--- a/packages/lizi-mcps/src/orca/server.ts
+++ b/packages/lizi-mcps/src/orca/server.ts
@@ -106,6 +106,7 @@ export interface OrcaMcpDeps {
label: string;
workingDir?: string;
initialTask?: string;
+ initialTaskImages?: string[];
}) => Promise<
ControlResult<
{ workerId: string; workerSessionId: string; softLimitExceeded?: boolean; dispatched?: boolean; dispatchOutcome?: import('../lizi_xdtHelperMcpServer.js').ControlDispatchOutcome; queuedMessageId?: string },
@@ -130,6 +131,8 @@ export interface OrcaMcpDeps {
message: string;
/** 仅模型显式选择时传入;缺省等价 'queue'。 */
delivery?: OrcaMessageDelivery;
+ /** 可选, 随消息发给 worker 的本机图片绝对路径; 仅本机 worker 支持。 */
+ images?: string[];
}) => Promise<
ControlResult<
{
diff --git a/packages/lizi-mcps/src/xdt-helper/create_worker.ts b/packages/lizi-mcps/src/xdt-helper/create_worker.ts
index 5d44695789..b1b07e1bca 100644
--- a/packages/lizi-mcps/src/xdt-helper/create_worker.ts
+++ b/packages/lizi-mcps/src/xdt-helper/create_worker.ts
@@ -59,6 +59,7 @@ export interface CreateWorkerDeps {
label: string;
workingDir?: string;
initialTask?: string;
+ initialTaskImages?: string[];
}) => Promise<CreateWorkerControlResult>;
}
@@ -103,6 +104,11 @@ export const createWorkerSpecSchema = z.object({
.min(1)
.optional()
.describe('可选, 创建后立即派给 worker 的第一条消息'),
+ images: z
+ .array(z.string().min(1))
+ .max(8)
+ .optional()
+ .describe('可选, 随 initial_task 发给 worker 的本机图片绝对路径(png/jpeg/gif/webp, 最多 8 张); 仅本机 worker 支持, SSH 远端 worker 会拒绝; 不传 initial_task 时忽略'),
working_dir: z.string().min(1).max(4096).refine((value) => value.trim().length > 0).optional()
.describe('可选,Worker 所在主机上已存在的绝对工作目录;省略则继承 Lead。创建前校验并绑定,失败不回退;不创建目录或 Git worktree。'),
}).strict();
@@ -157,7 +163,7 @@ export function registerCreateWorkerTool(
category: 'control',
description: DESCRIPTION,
inputShape: createWorkerSpecSchema.shape,
- handler: async ({ role, agent, model, provider_id, effort, fast, label, initial_task, working_dir }) => {
+ handler: async ({ role, agent, model, provider_id, effort, fast, label, initial_task, images, working_dir }) => {
const ctx = deps.getSessionContext?.() ?? deps;
if (!ctx.sessionId) {
return errorPayload('LEAD_NOT_SUPPORTED', '当前 session 类型不支持作为 Lead。');
@@ -178,6 +184,7 @@ export function registerCreateWorkerTool(
fast,
label,
...(working_dir !== undefined ? { workingDir: working_dir } : {}),
+ ...(images ? { initialTaskImages: images } : {}),
initialTask: initial_task,
});
if (!result.ok) {
diff --git a/packages/lizi-mcps/src/xdt-helper/create_workers.ts b/packages/lizi-mcps/src/xdt-helper/create_workers.ts
index 1025800191..047639a904 100644
--- a/packages/lizi-mcps/src/xdt-helper/create_workers.ts
+++ b/packages/lizi-mcps/src/xdt-helper/create_workers.ts
@@ -153,6 +153,7 @@ export function registerCreateWorkersTool(
fast: worker.fast,
label: worker.label,
...(worker.working_dir !== undefined ? { workingDir: worker.working_dir } : {}),
+ ...(worker.images ? { initialTaskImages: worker.images } : {}),
initialTask: worker.initial_task,
});
limit = result.limit ?? limit;
diff --git a/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts b/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
index bef99b7b96..806a4eca82 100644
--- a/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
+++ b/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
@@ -27,6 +27,8 @@ export interface SendToWorkerDeps {
message: string;
/** 仅调用方显式选择时传入;缺省等价 'queue'(普通直发/排队)。 */
delivery?: OrcaMessageDelivery;
+ /** 可选, 随消息发给 worker 的本机图片绝对路径; 仅本机 worker 支持, SSH 远端 worker 会被拒绝。 */
+ images?: string[];
}) => Promise<
ControlResult<
{
@@ -68,6 +70,7 @@ const DESCRIPTION =
'worker 正忙时消息自动排队(wake_kind=queued)并回传 queued_message_id;' +
'在它被消费前可用 get_worker_queue_status / update_queued_message / cancel_queued_message 查看、修改或撤回。' +
'纠错或 worker 正在等的信息可用 delivery=steer 插进其当前 turn(返回 steered=true);新任务保持默认。' +
+ '要给 worker 发图片时用 images 传本机绝对路径(仅本机 worker), 并在 message 里说明每张图是什么。' +
'没插成时照常直发或排队,排队时附 steer_fallback_reason。' +
'需要替换 worker 当前任务时改用 interrupt_worker。' +
'失败码: LEAD_NOT_SUPPORTED / NOT_FOUND / ARCHIVED / DELETED / BUSY / AGENT_NOT_READY。';
@@ -93,8 +96,13 @@ export function registerSendToWorkerTool(
.enum(['queue', 'steer'])
.optional()
.describe('投递方式:queue(默认)= 直发或排队;steer = 尝试插进 worker 当前 turn'),
+ images: z
+ .array(z.string().min(1))
+ .max(8)
+ .optional()
+ .describe('可选, 随消息发给 worker 的本机图片绝对路径(png/jpeg/gif/webp, 最多 8 张); 仅本机 worker 支持, SSH 远端 worker 返回 INVALID_ARGS'),
},
- handler: async ({ target_session_id, message, delivery }) => {
+ handler: async ({ target_session_id, message, delivery, images }) => {
const ctx = deps.getSessionContext?.();
if (!ctx?.sessionId) {
return errorPayload('LEAD_NOT_SUPPORTED', '当前 session 类型不支持作为 Lead, 已拒绝 worker 控制操作。');
@@ -104,6 +112,7 @@ export function registerSendToWorkerTool(
targetSessionId: target_session_id,
message,
...(delivery ? { delivery } : {}),
+ ...(images ? { images } : {}),
});
if (!result.ok) {