@coolkiller007/my-page-agent 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -268,6 +268,13 @@ declare class AgentRuntime extends EventTarget {
      * 非私有字段：需要被 `tools/index.ts` 中的 `ask_user` 工具从外部写入。
      */
     pendingAnswerAttachments: Attachment[];
+    /**
+     * 图片附件缓存（按附件名索引）：所有出现过的图片附件在此登记原始 dataUrl，
+     * 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按名称"按需重传"重新查看，
+     * 而不必每步都把原图重新塞进主对话历史（节省 token）。
+     * 非私有字段：需要被 `tools/index.ts` 中的 `image_understand` 工具从外部读取。
+     */
+    imageAttachmentCache: Map<string, Attachment>;
     /** 构造函数：初始化配置、LLM、工具集，并注册重试事件监听与注入自定义工具 */
     constructor(config: AgentRuntimeConfig);
     /** 获取当前 Agent 状态 */
@@ -285,6 +292,15 @@ declare class AgentRuntime extends EventTarget {
      * Agent 内部错误会被捕获并加入历史，同时返回失败结果
      */
     execute(task: string, attachments?: Attachment[]): Promise<ExecutionResult>;
+    /**
+     * 针对已缓存的图片附件发起一次独立的视觉问答，不进入主对话历史、不携带主链路的历史上下文。
+     * 供 `image_understand` 工具使用：模型需要复看图片细节时按需调用，而不是每步都重发原图。
+     * @param attachmentName - 附件名（即注入 prompt 时标注的名称）
+     * @param query - 需要从图片中确认的具体问题
+     * @param signal - 取消信号
+     * @returns 视觉模型针对 query 给出的文字答案；附件不存在时返回错误提示
+     */
+    describeImage(attachmentName: string, query: string, signal: AbortSignal): Promise<string>;
     /** 销毁 Agent：中止任务、释放浏览器控制器，并触发 dispose 事件（一次性） */
     dispose(): void;
 }

package/dist/index.js

@@ -4048,6 +4048,47 @@ function retrieveJsonFromString(str) {
 	}
 }
 //#endregion
+//#region src/agent/utils/image.ts
+/**
+* 图片附件处理工具（纯浏览器 Canvas 实现，无额外依赖）
+*/
+/**
+* 按需缩小图片：仅当长边超过 maxDimension 时才缩放并重新编码为 JPEG，
+* 用于降低多模态请求里图片消耗的 token；非浏览器环境或解码/绘制失败时原样返回。
+* @param dataUrl - 原始图片的 base64 data URL
+* @param maxDimension - 长边允许的最大像素
+* @param quality - 重新编码为 JPEG 时的质量（0-1）
+* @returns 缩放后的 data URL，未超阈值或失败时返回原 dataUrl
+*/
+async function resizeImageDataUrl(dataUrl, maxDimension, quality) {
+	if (typeof Image === "undefined" || typeof document === "undefined") return dataUrl;
+	try {
+		const img = await loadImage(dataUrl);
+		const { naturalWidth: width, naturalHeight: height } = img;
+		if (!width || !height || width <= maxDimension && height <= maxDimension) return dataUrl;
+		const scale = maxDimension / Math.max(width, height);
+		const targetWidth = Math.round(width * scale);
+		const targetHeight = Math.round(height * scale);
+		const canvas = document.createElement("canvas");
+		canvas.width = targetWidth;
+		canvas.height = targetHeight;
+		const ctx = canvas.getContext("2d");
+		if (!ctx) return dataUrl;
+		ctx.drawImage(img, 0, 0, targetWidth, targetHeight);
+		return canvas.toDataURL("image/jpeg", quality);
+	} catch {
+		return dataUrl;
+	}
+}
+function loadImage(dataUrl) {
+	return new Promise((resolve, reject) => {
+		const img = new Image();
+		img.onload = () => resolve(img);
+		img.onerror = () => reject(/* @__PURE__ */ new Error("Failed to load image"));
+		img.src = dataUrl;
+	});
+}
+//#endregion
 //#region src/agent/utils/index.ts
 /**
 * 等待 `seconds` 秒。若提供了 `signal`，则等待可被取消：
@@ -4202,6 +4243,16 @@ tools.set("ask_user", tool({
 		return `User answered: ${answer}`;
 	}
 }));
+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.",
+	inputSchema: z.object({
+		attachment_name: z.string(),
+		query: z.string()
+	}),
+	execute: async function(input, { signal }) {
+		return await this.describeImage(input.attachment_name, input.query, signal);
+	}
+}));
 tools.set("click_element_by_index", tool({
 	description: "Click element by index",
 	inputSchema: z.object({ index: z.int().min(0) }),
@@ -4274,6 +4325,14 @@ tools.set("execute_javascript", tool({
 //#region src/agent/AgentRuntime.ts
 /** 文本类附件注入 prompt 时的最大字符数，避免超大文件把上下文撑爆 */
 var ATTACHMENT_TEXT_MAX_LENGTH = 2e4;
+/** 图片长边超过该像素才压缩（OpenAI vision 高清分块阈值附近，兼顾 token 成本与截图文字可读性） */
+var ATTACHMENT_IMAGE_MAX_DIMENSION = 1568;
+/** 图片压缩重编码为 JPEG 时的质量 */
+var ATTACHMENT_IMAGE_JPEG_QUALITY = .85;
+/** 单次注入里最多内联发送的图片张数，超出的仅登记缓存，需模型主动调用 image_understand 查看 */
+var MAX_INLINE_IMAGES = 4;
+/** 历史任务 done 文本注入 prompt 时的最大字符数 */
+var PREVIOUS_TASK_TEXT_MAX_LENGTH = 300;
 /**
 * 用于浏览器自动化的 AI 智能体。
 *
@@ -4348,6 +4407,13 @@ var AgentRuntime = class extends EventTarget {
 	* 非私有字段：需要被 `tools/index.ts` 中的 `ask_user` 工具从外部写入。
 	*/
 	pendingAnswerAttachments = [];
+	/**
+	* 图片附件缓存（按附件名索引）：所有出现过的图片附件在此登记原始 dataUrl，
+	* 使原图在 prompt 里只出现一次之后，仍可被 `image_understand` 工具按名称"按需重传"重新查看，
+	* 而不必每步都把原图重新塞进主对话历史（节省 token）。
+	* 非私有字段：需要被 `tools/index.ts` 中的 `image_understand` 工具从外部读取。
+	*/
+	imageAttachmentCache = /* @__PURE__ */ new Map();
 	/** 当前任务在 history 数组中的起始下标（用于跨任务保留历史时，把 prompt/循环检测限定在当前任务范围内） */
 	#taskHistoryStart = 0;
 	/** 当前一次运行完全结束时 resolve。由 `stop()` 等待。 */
@@ -4467,6 +4533,7 @@ var AgentRuntime = class extends EventTarget {
 		this.taskId = uid();
 		this.#taskAttachments = attachments;
 		this.pendingAnswerAttachments = [];
+		this.imageAttachmentCache = /* @__PURE__ */ new Map();
 		this.#taskHistoryStart = this.history.length;
 		this.#emitHistoryChange({
 			type: "task_start",
@@ -4717,6 +4784,35 @@ var AgentRuntime = class extends EventTarget {
 		return result;
 	}
 	/**
+	* 汇总当前任务之前、同一 AgentRuntime 实例已完成过的历史任务，生成一段纯文字摘要。
+	* 只带文字结论（任务描述 + done 文本 + 涉及的附件文件名），不携带图片原始数据 ——
+	* 图片附件与 `imageAttachmentCache` 一样按任务隔离，跨任务需要复看时应提示用户重新上传。
+	* 只取最近 `PREVIOUS_TASKS_SUMMARY_LIMIT` 个任务，避免任务数增多后 prompt 无限增长。
+	*/
+	#buildPreviousTasksSummary() {
+		const priorHistory = this.history.slice(0, this.#taskHistoryStart);
+		if (priorHistory.length === 0) return "";
+		const summaries = [];
+		let current = null;
+		for (const event of priorHistory) if (event.type === "task_start") {
+			current = {
+				task: event.task,
+				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 ?? ""}`;
+		}
+		const recent = summaries.slice(-5);
+		if (recent.length === 0) return "";
+		return `<previous_tasks_summary>\n${recent.map((s) => {
+			const attachmentNote = s.attachmentNames?.length ? ` [attachments uploaded then: ${s.attachmentNames.join(", ")} — NOT available in this task, ask the user to re-upload if you need to see them again]` : "";
+			const result = s.result ? truncate(s.result, PREVIOUS_TASK_TEXT_MAX_LENGTH) : "(no result recorded — task may have been interrupted)";
+			return `- Task: "${s.task}"${attachmentNote}\n  Result: ${result}`;
+		}).join("\n")}\n</previous_tasks_summary>\n\n`;
+	}
+	/**
 	* 在每一步之前生成系统观察
 	* @todo 控制台错误
 	*/
@@ -4757,6 +4853,7 @@ 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();
 		prompt += "<agent_state>\n";
 		prompt += "<user_request>\n";
 		prompt += `${this.task}\n`;
@@ -4779,6 +4876,7 @@ var AgentRuntime = class extends EventTarget {
 			prompt += `Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}\n`;
 			prompt += `Memory: ${event.reflection.memory}\n`;
 			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`;
 			prompt += `</step_${stepIndex}>\n`;
 		} else if (event.type === "observation") prompt += `<sys>${event.content}</sys>\n`;
@@ -4803,15 +4901,28 @@ var AgentRuntime = class extends EventTarget {
 	/**
 	* 把附件内容注入 prompt：图片转为 image_url 片段；文本类文件解码后截断拼进文字部分。
 	* 仅当存在图片附件时才返回多模态数组，纯文本附件保持返回字符串（不影响不支持 vision 的模型）。
+	* 图片附件会先登记进 `imageAttachmentCache`（存原图，供 `image_understand` 复看细节用），
+	* 内联发给模型的图片先按 `ATTACHMENT_IMAGE_MAX_DIMENSION` 压缩降 token；
+	* 单次超过 `MAX_INLINE_IMAGES` 张时，多出的图片只登记缓存 + 文字提示名称，不内联发送。
+	* 之后步骤不再重复下发原图，需要复看细节时改由模型调用 `image_understand` 按需重传。
 	*/
 	async #injectAttachments(prompt, attachments) {
 		const textSegments = [prompt];
 		const imageParts = [];
+		let inlinedImageCount = 0;
 		for (const attachment of attachments) {
 			if (attachment.mimeType.startsWith("image/")) {
+				this.imageAttachmentCache.set(attachment.name, attachment);
+				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.]`);
+					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}".]`);
 				imageParts.push({
 					type: "image_url",
-					image_url: { url: attachment.dataUrl }
+					image_url: { url: resizedDataUrl }
 				});
 				continue;
 			}
@@ -4824,6 +4935,33 @@ var AgentRuntime = class extends EventTarget {
 			text: textSegments.join("\n\n")
 		}, ...imageParts];
 	}
+	/**
+	* 针对已缓存的图片附件发起一次独立的视觉问答，不进入主对话历史、不携带主链路的历史上下文。
+	* 供 `image_understand` 工具使用：模型需要复看图片细节时按需调用，而不是每步都重发原图。
+	* @param attachmentName - 附件名（即注入 prompt 时标注的名称）
+	* @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"}`;
+		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([{
+			role: "user",
+			content: [{
+				type: "text",
+				text: query
+			}, {
+				type: "image_url",
+				image_url: { url: attachment.dataUrl }
+			}]
+		}], { answer_image_question: answerTool }, signal, { toolChoiceName: "answer_image_question" })).toolResult.answer;
+	}
 	/** 销毁 Agent：中止任务、释放浏览器控制器，并触发 dispose 事件（一次性） */
 	dispose() {
 		if (this.disposed) return;