@coolkiller007/my-page-agent 0.2.8 → 0.2.9

package/dist/index.d.ts

@@ -264,20 +264,14 @@ declare class AgentRuntime extends EventTarget {
         attachments?: Attachment[];
     }>;
     /**
-     * `ask_user` 工具收到带附件的回答后暂存于此，供下一步 `#assembleUserPrompt` 注入 LLM prompt 后清空。
-     * 非私有字段：需要被 `tools/index.ts` 中的 `ask_user` 工具从外部写入。
-     */
-    pendingAnswerAttachments: Attachment[];
-    /**
-     * 图片附件缓存（按附件名索引）：所有出现过的图片附件在此登记原始 dataUrl，
-     * 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按名称"按需重传"重新查看，
+     * 图片附件缓存（按稳定附件 ID 索引）：所有出现过的图片附件在此登记原始 dataUrl，
+     * 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按稳定 ID“按需重传”重新查看，
      * 而不必每步都把原图重新塞进主对话历史（节省 token）。
      * @note 跨任务持久保留（不随 `execute()` 清空）：缓存本身是纯内存 Map，不进 prompt 就不占 token，
      * 只有模型主动调用 `image_understand` 时才会产生一次性 token 成本。唯一真实开销是内存，
-     * 因此按 `MAX_CACHED_IMAGES` 做容量上限，超出淘汰最早插入的一张（见 `#cacheImageAttachment`）。
-     * 非私有字段：需要被 `tools/index.ts` 中的 `image_understand` 工具从外部读取。
+     * 因此按 `MAX_CACHED_IMAGES` 做容量上限，超出时淘汰最久未读取的一张。
      */
-    imageAttachmentCache: Map<string, Attachment>;
+    readonly imageAttachmentCache: Map<string, StoredImageAttachment>;
     /** 构造函数：初始化配置、LLM、工具集，并注册重试事件监听与注入自定义工具 */
     constructor(config: AgentRuntimeConfig);
     /** 获取当前 Agent 状态 */
@@ -295,15 +289,17 @@ declare class AgentRuntime extends EventTarget {
      * Agent 内部错误会被捕获并加入历史，同时返回失败结果
      */
     execute(task: string, attachments?: Attachment[]): Promise<ExecutionResult>;
+    /* Excluded from this release type: setPendingAnswerAttachments */
+    /* Excluded from this release type: listAvailableAttachments */
     /**
      * 针对已缓存的图片附件发起一次独立的视觉问答，不进入主对话历史、不携带主链路的历史上下文。
      * 供 `image_understand` 工具使用：模型需要复看图片细节时按需调用，而不是每步都重发原图。
-     * @param attachmentName - 附件名（即注入 prompt 时标注的名称）
+     * @param attachmentIdOrName - 优先使用稳定附件 ID；为兼容旧调用也接受文件名
      * @param query - 需要从图片中确认的具体问题
      * @param signal - 取消信号
      * @returns 视觉模型针对 query 给出的文字答案；附件不存在时返回错误提示
      */
-    describeImage(attachmentName: string, query: string, signal: AbortSignal): Promise<string>;
+    describeImage(attachmentIdOrName: string, query: string, signal: AbortSignal): Promise<string>;
     /** 销毁 Agent：中止任务、释放浏览器控制器，并触发 dispose 事件（一次性） */
     dispose(): void;
 }
@@ -328,6 +324,8 @@ declare interface AgentStepEvent {
         name: string;
         input: any;
         output: string;
+        attachmentNames?: string[];
+        attachments?: AttachmentReference[];
     };
     usage: {
         promptTokens: number;
@@ -370,6 +368,13 @@ declare interface Attachment_2 {
     dataUrl: string;
 }
 
+/** 历史与 prompt 中使用的轻量图片引用，不包含原图数据 */
+declare interface AttachmentReference {
+    id: string;
+    name: string;
+    mimeType: string;
+}
+
 /**
  * BrowserController 管理 DOM 状态和元素交互。
  * 它为所有 DOM 操作提供异步方法，并保持状态隔离。
@@ -798,6 +803,16 @@ declare interface RetryEvent {
     maxAttempts: number;
 }
 
+/** 会话级图片仓库记录；原图仅保存在应用内存中，不进入普通任务 prompt */
+declare interface StoredImageAttachment extends AttachmentReference {
+    dataUrl: string;
+    taskId: string;
+    task: string;
+    source: 'task' | 'answer';
+    createdAt: number;
+    lastAccessedAt: number;
+}
+
 /** 支持的 UI 语言 */
 declare type SupportedLanguage = 'en-US' | 'zh-CN';
 
@@ -813,6 +828,7 @@ declare interface TaskStartEvent {
     type: 'task_start';
     task: string;
     attachmentNames?: string[];
+    attachments?: AttachmentReference[];
 }
 
 declare interface TextDomNode {
@@ -926,6 +942,12 @@ declare interface UIAdapter extends EventTarget {
             name: string;
             input: unknown;
             output: string;
+            attachmentNames?: string[];
+            attachments?: {
+                id: string;
+                name: string;
+                mimeType: string;
+            }[];
         };
         /** 仅用于 'observation' 类型 */
         content?: string;
@@ -933,6 +955,12 @@ declare interface UIAdapter extends EventTarget {
         task?: string;
         /** 仅用于 'task_start' 类型 */
         attachmentNames?: string[];
+        /** 仅用于 'task_start' 类型 */
+        attachments?: {
+            id: string;
+            name: string;
+            mimeType: string;
+        }[];
         /** 仅用于 'retry' 类型 */
         attempt?: number;
         maxAttempts?: number;

package/dist/index.js

@@ -3494,6 +3494,7 @@ var UI = class {
 		} else if (action.name === "ask_user") {
 			const input = action.input;
 			const answer = action.output.replace(/^User answered:\s*/i, "");
+			const answerContent = action.attachmentNames?.length ? [`Answer: ${answer}`, this.#i18n.t("ui.attachmentsLabel", { names: action.attachmentNames.join(", ") })] : `Answer: ${answer}`;
 			cards.push(createCard({
 				icon: "❓",
 				content: `Question: ${input.question || ""}`,
@@ -3502,7 +3503,7 @@ var UI = class {
 			}));
 			cards.push(createCard({
 				icon: "💬",
-				content: `Answer: ${answer}`,
+				content: answerContent,
 				meta,
 				type: "input"
 			}));
@@ -4315,18 +4316,28 @@ tools.set("ask_user", tool({
 		const raw = await this.onAskUser(input.question, { signal });
 		const answer = typeof raw === "string" ? raw : raw.text;
 		const attachments = typeof raw === "string" ? void 0 : raw.attachments;
-		if (attachments?.length) this.pendingAnswerAttachments = attachments;
+		if (attachments?.length) this.setPendingAnswerAttachments(attachments);
 		return `User answered: ${answer}`;
 	}
 }));
+tools.set("list_attachments", tool({
+	description: "List image attachments still available in this agent session without loading their image data. Use this when the relevant attachment ID is not present in the current context.",
+	inputSchema: z.object({ query: z.string().optional() }),
+	execute: async function(input) {
+		return this.listAvailableAttachments(input.query);
+	}
+}));
 tools.set("image_understand", tool({
-	description: "Re-examine a previously shown image attachment to answer a specific visual question about it. Images are only sent once — use this instead of assuming you can still \"see\" an image from an earlier step. Only call this when the info is NOT already recorded in your memory/history; do not call it repeatedly for the same question.",
+	description: "Re-examine a previously shown image attachment to answer a specific visual question about it. Prefer attachment_id from available_attachments/list_attachments; attachment_name remains supported for compatibility. Images are loaded only by this tool — use it instead of assuming you can still \"see\" an image from an earlier step or task. Only call this when the info is NOT already recorded in your memory/history; do not call it repeatedly for the same question.",
 	inputSchema: z.object({
-		attachment_name: z.string(),
-		query: z.string()
+		attachment_id: z.string().optional(),
+		attachment_name: z.string().optional(),
+		query: z.string().min(1)
 	}),
 	execute: async function(input, { signal }) {
-		return await this.describeImage(input.attachment_name, input.query, signal);
+		const identifier = input.attachment_id ?? input.attachment_name;
+		if (!identifier) return "❌ attachment_id or attachment_name is required.";
+		return await this.describeImage(identifier, input.query, signal);
 	}
 }));
 tools.set("click_element_by_index", tool({
@@ -4407,8 +4418,10 @@ var ATTACHMENT_IMAGE_MAX_DIMENSION = 1568;
 var ATTACHMENT_IMAGE_JPEG_QUALITY = .85;
 /** 单次注入里最多内联发送的图片张数，超出的仅登记缓存，需模型主动调用 image_understand 查看 */
 var MAX_INLINE_IMAGES = 4;
-/** 图片缓存跨任务最多保留的张数，超出时淘汰最早插入的一张（防止长会话内存无限增长；缓存本身不占 prompt token） */
+/** 图片仓库跨任务最多保留的张数，超出时按 LRU 淘汰（仓库本身不占 prompt token） */
 var MAX_CACHED_IMAGES = 20;
+/** 相同图片、相同问题的视觉结果缓存上限，避免重复视觉调用同时控制内存 */
+var MAX_IMAGE_UNDERSTANDING_CACHE_ENTRIES = 100;
 /** 历史任务 done 文本注入 prompt 时的最大字符数 */
 var PREVIOUS_TASK_TEXT_MAX_LENGTH = 300;
 /**
@@ -4480,21 +4493,27 @@ var AgentRuntime = class extends EventTarget {
 	#observations = [];
 	/** 本次任务上传的附件；仅在任务第一步注入 LLM prompt，之后步骤不重复携带原文件以节省 token */
 	#taskAttachments = [];
+	/** 本次任务图片在会话级仓库中的轻量引用 */
+	#taskAttachmentReferences = [];
 	/**
 	* `ask_user` 工具收到带附件的回答后暂存于此，供下一步 `#assembleUserPrompt` 注入 LLM prompt 后清空。
-	* 非私有字段：需要被 `tools/index.ts` 中的 `ask_user` 工具从外部写入。
 	*/
-	pendingAnswerAttachments = [];
+	#pendingAnswerAttachments = [];
+	/** 追问回答中的图片在会话级仓库中的轻量引用 */
+	#pendingAnswerAttachmentReferences = [];
 	/**
-	* 图片附件缓存（按附件名索引）：所有出现过的图片附件在此登记原始 dataUrl，
-	* 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按名称"按需重传"重新查看，
+	* 图片附件缓存（按稳定附件 ID 索引）：所有出现过的图片附件在此登记原始 dataUrl，
+	* 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按稳定 ID“按需重传”重新查看，
 	* 而不必每步都把原图重新塞进主对话历史（节省 token）。
 	* @note 跨任务持久保留（不随 `execute()` 清空）：缓存本身是纯内存 Map，不进 prompt 就不占 token，
 	* 只有模型主动调用 `image_understand` 时才会产生一次性 token 成本。唯一真实开销是内存，
-	* 因此按 `MAX_CACHED_IMAGES` 做容量上限，超出淘汰最早插入的一张（见 `#cacheImageAttachment`）。
-	* 非私有字段：需要被 `tools/index.ts` 中的 `image_understand` 工具从外部读取。
+	* 因此按 `MAX_CACHED_IMAGES` 做容量上限，超出时淘汰最久未读取的一张。
 	*/
 	imageAttachmentCache = /* @__PURE__ */ new Map();
+	/** 同一个附件对象只注册一次，避免首次注入 prompt 时重复生成 ID */
+	#attachmentObjectIds = /* @__PURE__ */ new WeakMap();
+	/** 独立视觉问答结果缓存，key 由附件 ID 和规范化后的问题组成 */
+	#imageUnderstandingCache = /* @__PURE__ */ new Map();
 	/** 当前任务在 history 数组中的起始下标（用于跨任务保留历史时，把 prompt/循环检测限定在当前任务范围内） */
 	#taskHistoryStart = 0;
 	/** 当前一次运行完全结束时 resolve。由 `stop()` 等待。 */
@@ -4613,12 +4632,15 @@ var AgentRuntime = class extends EventTarget {
 		this.task = task;
 		this.taskId = uid();
 		this.#taskAttachments = attachments;
-		this.pendingAnswerAttachments = [];
+		this.#taskAttachmentReferences = this.#registerImageAttachments(attachments, "task");
+		this.#pendingAnswerAttachments = [];
+		this.#pendingAnswerAttachmentReferences = [];
 		this.#taskHistoryStart = this.history.length;
 		this.#emitHistoryChange({
 			type: "task_start",
 			task,
-			...attachments.length > 0 ? { attachmentNames: attachments.map((a) => a.name) } : {}
+			...attachments.length > 0 ? { attachmentNames: attachments.map((a) => a.name) } : {},
+			...this.#taskAttachmentReferences.length > 0 ? { attachments: this.#taskAttachmentReferences } : {}
 		});
 		this.#observations = [];
 		this.#states = {
@@ -4700,7 +4722,9 @@ var AgentRuntime = class extends EventTarget {
 					const action = {
 						name: actionName,
 						input: input.action[actionName],
-						output
+						output,
+						...macroResult.attachmentNames?.length ? { attachmentNames: macroResult.attachmentNames } : {},
+						...macroResult.attachments?.length ? { attachments: macroResult.attachments } : {}
 					};
 					this.#emitHistoryChange({
 						type: "step",
@@ -4826,9 +4850,13 @@ var AgentRuntime = class extends EventTarget {
 				});
 				if (toolName === "wait") this.#states.totalWaitTime += toolInput?.seconds || 0;
 				else this.#states.totalWaitTime = 0;
+				const attachmentNames = toolName === "ask_user" && this.#pendingAnswerAttachments.length > 0 ? this.#pendingAnswerAttachments.map((attachment) => attachment.name) : void 0;
+				const attachments = toolName === "ask_user" && this.#pendingAnswerAttachmentReferences.length > 0 ? this.#pendingAnswerAttachmentReferences : void 0;
 				return {
 					input,
-					output: result
+					output: result,
+					...attachmentNames ? { attachmentNames } : {},
+					...attachments ? { attachments } : {}
 				};
 			}
 		};
@@ -4881,9 +4909,12 @@ var AgentRuntime = class extends EventTarget {
 				attachmentNames: event.attachmentNames
 			};
 			summaries.push(current);
-		} else if (event.type === "step" && event.action.name === "done" && current) {
-			const input = event.action.input;
-			current.result = `${input?.success === false ? "❌" : "✅"} ${input?.text ?? ""}`;
+		} else if (event.type === "step" && current) {
+			if (event.action.name === "ask_user" && event.action.attachmentNames?.length) current.attachmentNames = [.../* @__PURE__ */ new Set([...current.attachmentNames ?? [], ...event.action.attachmentNames])];
+			if (event.action.name === "done") {
+				const input = event.action.input;
+				current.result = `${input?.success === false ? "❌" : "✅"} ${input?.text ?? ""}`;
+			}
 		}
 		const recent = summaries.slice(-5);
 		if (recent.length === 0) return "";
@@ -4900,12 +4931,28 @@ var AgentRuntime = class extends EventTarget {
 	#describeAttachmentAvailability(attachmentNames) {
 		const viewable = [];
 		const unavailable = [];
-		for (const name of attachmentNames) (this.imageAttachmentCache.has(name) ? viewable : unavailable).push(name);
+		for (const name of attachmentNames) (this.#resolveImageAttachment(name, false) ? viewable : unavailable).push(name);
 		const parts = [];
 		if (viewable.length > 0) parts.push(`still viewable via image_understand: ${viewable.join(", ")}`);
 		if (unavailable.length > 0) parts.push(`NOT available in this task, ask the user to re-upload if you need to see them again: ${unavailable.join(", ")}`);
 		return `[attachments uploaded then — ${parts.join("; ")}]`;
 	}
+	/** 生成新任务首步使用的轻量图片清单；不包含 dataUrl。 */
+	#buildAvailableAttachmentsManifest() {
+		if (this.imageAttachmentCache.size === 0) return "";
+		const attachments = [...this.imageAttachmentCache.values()].reverse().map((attachment) => ({
+			id: attachment.id,
+			name: attachment.name,
+			mimeType: attachment.mimeType,
+			sourceTask: truncate(attachment.task, 100),
+			source: attachment.source
+		}));
+		return `<available_attachments>
+These session images are not included inline. Use image_understand with attachment_id only when visual details are needed.
+${JSON.stringify(attachments)}\n</available_attachments>
+
+`;
+	}
 	/**
 	* 在每一步之前生成系统观察
 	* @todo 控制台错误
@@ -4955,7 +5002,10 @@ var AgentRuntime = class extends EventTarget {
 		prompt += await this.#getInstructions();
 		const currentTaskHistory = this.#currentTaskHistory;
 		const stepCount = currentTaskHistory.filter((e) => e.type === "step").length;
-		if (stepCount === 0) prompt += this.#buildPreviousTasksSummary();
+		if (stepCount === 0) {
+			prompt += this.#buildPreviousTasksSummary();
+			prompt += this.#buildAvailableAttachmentsManifest();
+		}
 		prompt += "<agent_state>\n";
 		prompt += "<user_request>\n";
 		prompt += `${this.task}\n`;
@@ -4980,6 +5030,8 @@ var AgentRuntime = class extends EventTarget {
 			prompt += `Next Goal: ${event.reflection.next_goal}\n`;
 			prompt += `Action: ${event.action.name}(${JSON.stringify(event.action.input)})\n`;
 			prompt += `Action Results: ${event.action.output}\n`;
+			if (event.action.attachments?.length) prompt += `User-uploaded attachments: ${JSON.stringify(event.action.attachments)}\n`;
+			else if (event.action.attachmentNames?.length) prompt += `User-uploaded attachment names: ${JSON.stringify(event.action.attachmentNames)}\n`;
 			prompt += `</step_${stepIndex}>\n`;
 		} else if (event.type === "observation") prompt += `<sys>${event.content}</sys>\n`;
 		else if (event.type === "user_takeover") prompt += `<sys>User took over control and made changes to the page</sys>\n`;
@@ -4993,28 +5045,107 @@ var AgentRuntime = class extends EventTarget {
 		prompt += browserState.footer + "\n\n";
 		prompt += "</browser_state>\n\n";
 		if (stepCount === 0 && this.#taskAttachments.length > 0) return await this.#injectAttachments(prompt, this.#taskAttachments);
-		if (this.pendingAnswerAttachments.length > 0) {
-			const attachments = this.pendingAnswerAttachments;
-			this.pendingAnswerAttachments = [];
+		if (this.#pendingAnswerAttachments.length > 0) {
+			const attachments = this.#pendingAnswerAttachments;
+			this.#pendingAnswerAttachments = [];
+			this.#pendingAnswerAttachmentReferences = [];
 			return await this.#injectAttachments(prompt, attachments);
 		}
 		return prompt;
 	}
 	/**
-	* 把图片附件登记进 `imageAttachmentCache`；超出 `MAX_CACHED_IMAGES` 容量时淘汰最早插入的一张。
-	* 缓存跨任务持久，容量上限只为控内存，不影响 token（未被 `image_understand` 读取的缓存项不进 prompt）。
+	* 保存 ask_user 回答附件，供下一个主循环步骤注入；图片会同时登记进跨任务仓库。
+	* @internal 供内置 ask_user 工具调用。
 	*/
-	#cacheImageAttachment(attachment) {
-		if (!this.imageAttachmentCache.has(attachment.name) && this.imageAttachmentCache.size >= MAX_CACHED_IMAGES) {
-			const oldestName = this.imageAttachmentCache.keys().next().value;
-			if (oldestName !== void 0) this.imageAttachmentCache.delete(oldestName);
+	setPendingAnswerAttachments(attachments) {
+		this.#pendingAnswerAttachments = attachments;
+		this.#pendingAnswerAttachmentReferences = this.#registerImageAttachments(attachments, "answer");
+	}
+	/** 把图片登记进按稳定 ID 索引的会话级 LRU 仓库，并返回不含原图的引用。 */
+	#registerImageAttachments(attachments, source) {
+		const references = [];
+		for (const attachment of attachments) {
+			if (!attachment.mimeType.startsWith("image/")) continue;
+			const existingId = this.#attachmentObjectIds.get(attachment);
+			const existing = existingId ? this.imageAttachmentCache.get(existingId) : void 0;
+			if (existing) {
+				this.#touchImageAttachment(existing.id);
+				references.push(this.#toAttachmentReference(existing));
+				continue;
+			}
+			while (this.imageAttachmentCache.size >= MAX_CACHED_IMAGES) {
+				const oldestId = this.imageAttachmentCache.keys().next().value;
+				if (oldestId === void 0) break;
+				this.#evictImageAttachment(oldestId);
+			}
+			const id = `att_${uid()}`;
+			const now = Date.now();
+			const stored = {
+				id,
+				name: attachment.name,
+				mimeType: attachment.mimeType,
+				dataUrl: attachment.dataUrl,
+				taskId: this.taskId,
+				task: this.task,
+				source,
+				createdAt: now,
+				lastAccessedAt: now
+			};
+			this.imageAttachmentCache.set(id, stored);
+			this.#attachmentObjectIds.set(attachment, id);
+			references.push(this.#toAttachmentReference(stored));
 		}
-		this.imageAttachmentCache.set(attachment.name, attachment);
+		return references;
+	}
+	#toAttachmentReference(attachment) {
+		return {
+			id: attachment.id,
+			name: attachment.name,
+			mimeType: attachment.mimeType
+		};
+	}
+	/** 按 ID 精确查找；旧文件名调用兼容为最近上传的同名图片。 */
+	#resolveImageAttachment(attachmentIdOrName, touch = true) {
+		let attachment = this.imageAttachmentCache.get(attachmentIdOrName);
+		if (!attachment) attachment = [...this.imageAttachmentCache.values()].reverse().find((candidate) => candidate.name === attachmentIdOrName);
+		if (attachment && touch) this.#touchImageAttachment(attachment.id);
+		return attachment;
+	}
+	/** 读取图片时移动到 Map 末尾，使容量淘汰遵循 LRU 而非单纯 FIFO。 */
+	#touchImageAttachment(attachmentId) {
+		const attachment = this.imageAttachmentCache.get(attachmentId);
+		if (!attachment) return;
+		attachment.lastAccessedAt = Date.now();
+		this.imageAttachmentCache.delete(attachmentId);
+		this.imageAttachmentCache.set(attachmentId, attachment);
+	}
+	#evictImageAttachment(attachmentId) {
+		this.imageAttachmentCache.delete(attachmentId);
+		for (const key of this.#imageUnderstandingCache.keys()) if (key.startsWith(`${attachmentId}\n`)) this.#imageUnderstandingCache.delete(key);
+	}
+	/**
+	* 返回不含原图数据的附件列表，供 list_attachments 工具在任务中途重新发现历史图片。
+	* @internal
+	*/
+	listAvailableAttachments(query) {
+		const needle = query?.trim().toLowerCase();
+		const attachments = [...this.imageAttachmentCache.values()].reverse().filter((attachment) => {
+			if (!needle) return true;
+			return attachment.id.toLowerCase().includes(needle) || attachment.name.toLowerCase().includes(needle) || attachment.task.toLowerCase().includes(needle);
+		}).map((attachment) => ({
+			id: attachment.id,
+			name: attachment.name,
+			mimeType: attachment.mimeType,
+			sourceTask: truncate(attachment.task, 100),
+			source: attachment.source
+		}));
+		if (attachments.length === 0) return "No matching image attachments are available.";
+		return `Available image attachments (metadata only): ${JSON.stringify(attachments)}`;
 	}
 	/**
 	* 把附件内容注入 prompt：图片转为 image_url 片段；文本类文件解码后截断拼进文字部分。
 	* 仅当存在图片附件时才返回多模态数组，纯文本附件保持返回字符串（不影响不支持 vision 的模型）。
-	* 图片附件会先登记进 `imageAttachmentCache`（存原图，供 `image_understand` 复看细节用），
+	* 图片附件已在接收时登记进 `imageAttachmentCache`（存原图，供 `image_understand` 复看细节用），
 	* 内联发给模型的图片先按 `ATTACHMENT_IMAGE_MAX_DIMENSION` 压缩降 token；
 	* 单次超过 `MAX_INLINE_IMAGES` 张时，多出的图片只登记缓存 + 文字提示名称，不内联发送。
 	* 之后步骤不再重复下发原图，需要复看细节时改由模型调用 `image_understand` 按需重传。
@@ -5025,14 +5156,14 @@ var AgentRuntime = class extends EventTarget {
 		let inlinedImageCount = 0;
 		for (const attachment of attachments) {
 			if (attachment.mimeType.startsWith("image/")) {
-				this.#cacheImageAttachment(attachment);
+				const attachmentId = this.#registerImageAttachments([attachment], "task")[0].id;
 				if (inlinedImageCount >= MAX_INLINE_IMAGES) {
-					textSegments.push(`[Image attachment "${attachment.name}" was NOT shown inline (too many images in this batch). Call image_understand with attachment_name="${attachment.name}" if you need to see it.]`);
+					textSegments.push(`[Image attachment "${attachment.name}" was NOT shown inline (too many images in this batch). Call image_understand with attachment_id="${attachmentId}" if you need to see it.]`);
 					continue;
 				}
 				inlinedImageCount++;
 				const resizedDataUrl = await resizeImageDataUrl(attachment.dataUrl, ATTACHMENT_IMAGE_MAX_DIMENSION, ATTACHMENT_IMAGE_JPEG_QUALITY);
-				textSegments.push(`[Image attachment "${attachment.name}" is shown below. It will NOT be resent in later steps — note only the key facts you need into memory, don't transcribe it verbatim. If you need to re-examine its visual details (e.g. exact small text) in a later step, call image_understand with attachment_name="${attachment.name}".]`);
+				textSegments.push(`[Image attachment "${attachment.name}" (attachment_id="${attachmentId}") is shown below. It will NOT be resent in later steps — note only the key facts you need into memory, don't transcribe it verbatim. If you need to re-examine its visual details (e.g. exact small text) in a later step, call image_understand with attachment_id="${attachmentId}".]`);
 				imageParts.push({
 					type: "image_url",
 					image_url: { url: resizedDataUrl }
@@ -5051,20 +5182,25 @@ var AgentRuntime = class extends EventTarget {
 	/**
 	* 针对已缓存的图片附件发起一次独立的视觉问答，不进入主对话历史、不携带主链路的历史上下文。
 	* 供 `image_understand` 工具使用：模型需要复看图片细节时按需调用，而不是每步都重发原图。
-	* @param attachmentName - 附件名（即注入 prompt 时标注的名称）
+	* @param attachmentIdOrName - 优先使用稳定附件 ID；为兼容旧调用也接受文件名
 	* @param query - 需要从图片中确认的具体问题
 	* @param signal - 取消信号
 	* @returns 视觉模型针对 query 给出的文字答案；附件不存在时返回错误提示
 	*/
-	async describeImage(attachmentName, query, signal) {
-		const attachment = this.imageAttachmentCache.get(attachmentName);
-		if (!attachment) return `❌ Attachment "${attachmentName}" not found. Available image attachments: ${[...this.imageAttachmentCache.keys()].join(", ") || "none"}`;
+	async describeImage(attachmentIdOrName, query, signal) {
+		signal.throwIfAborted();
+		const attachment = this.#resolveImageAttachment(attachmentIdOrName);
+		if (!attachment) return `❌ Attachment "${attachmentIdOrName}" not found. ${this.listAvailableAttachments()}`;
+		const normalizedQuery = query.trim().replace(/\s+/g, " ").toLowerCase();
+		const cacheKey = `${attachment.id}\n${normalizedQuery}`;
+		const cached = this.#imageUnderstandingCache.get(cacheKey);
+		if (cached !== void 0) return cached;
 		const answerTool = {
 			description: "Answer the question about the image as precisely and completely as possible.",
 			inputSchema: z.object({ answer: z.string() }),
 			execute: async (args) => args
 		};
-		return (await this.#llm.invoke([{
+		const answer = (await this.#llm.invoke([{
 			role: "user",
 			content: [{
 				type: "text",
@@ -5074,6 +5210,12 @@ var AgentRuntime = class extends EventTarget {
 				image_url: { url: attachment.dataUrl }
 			}]
 		}], { answer_image_question: answerTool }, signal, { toolChoiceName: "answer_image_question" })).toolResult.answer;
+		if (this.#imageUnderstandingCache.size >= MAX_IMAGE_UNDERSTANDING_CACHE_ENTRIES) {
+			const oldestKey = this.#imageUnderstandingCache.keys().next().value;
+			if (oldestKey !== void 0) this.#imageUnderstandingCache.delete(oldestKey);
+		}
+		this.#imageUnderstandingCache.set(cacheKey, answer);
+		return answer;
 	}
 	/** 销毁 Agent：中止任务、释放浏览器控制器，并触发 dispose 事件（一次性） */
 	dispose() {
@@ -5090,6 +5232,15 @@ var AgentRuntime = class extends EventTarget {
 		};
 		cleanUp(() => this.#abortController.abort());
 		cleanUp(() => this.browserController.dispose());
+		cleanUp(() => this.imageAttachmentCache.clear());
+		cleanUp(() => this.#imageUnderstandingCache.clear());
+		cleanUp(() => {
+			this.#attachmentObjectIds = /* @__PURE__ */ new WeakMap();
+			this.#taskAttachments = [];
+			this.#taskAttachmentReferences = [];
+			this.#pendingAnswerAttachments = [];
+			this.#pendingAnswerAttachmentReferences = [];
+		});
 		cleanUp(() => this.dispatchEvent(new Event("dispose")));
 		cleanUp(() => this.config.onDispose?.(this));
 		if (errors.length === 1) throw errors[0];