dsh-plugin-om 0.0.20 → 0.0.22

package/dist/index.mjs

@@ -3,40 +3,40 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { toJSONSchema } from "zod/v4/core";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
 //#region src/constants.ts
 /**
-* 共享常量：集中定义插件级魔法字符串与事件名，避免散落各模块。
+* 共享常量：插件级魔法字符串，集中定义避免散落各模块。
+* 导出 PLUGIN_LABEL / HISTORY_TAG / HISTORY_TIP / COMPLETE_MESSAGE_DEFINITION /
+* COMPACT_CHECKPOINT_PLUGIN / isPluginOwnedSource。
 */
-/** 插件标识：压缩消息 source.plugin 取值（注入压缩日志的来源标记）与日志前缀。 */
+/** 插件标识：压缩消息 source.plugin 取值与日志前缀。 */
 const PLUGIN_LABEL = "dsh-plugin-om";
-/** 压缩日志标签名：<history>...</history> 包裹观察/反思日志块（输入与输出均为合法 history 块）。 */
+/** 压缩日志标签名：<history>...</history> 包裹观察/反思日志块。 */
 const HISTORY_TAG = "history";
-/** 压缩日志块开标签上的 tip 属性（对 AI 的提醒：本块是历史压缩产物，不要复述）。 */
+/** 压缩日志块开标签的 tip 属性（对 AI 的提醒：本块是历史压缩产物，不要复述）。 */
 const HISTORY_TIP = "当前块是历史消息的压缩产物，不要复述";
 /**
-* 「完整消息」定义（提示词 / recall 工具描述 / 块顶注释共用同一字符串）。
+* 「完整消息」定义（提示词 / 工具描述 / 块顶注释共用）。
 * 完整消息是摘要日志与 recall 共用的定位单位；首条 index 为 0，按会话顺序递增、全局稳定。
-* 用户消息指 user_message 中 source.kind 为 user 的部分；其余部分（宿主注入的上下文等）
-* 为系统消息，同样是一条完整消息。
 */
 const COMPLETE_MESSAGE_DEFINITION = "`完整消息`被定义为`用户消息`，`系统消息`，`模型输出文本`和`具有result的toolcall`的集合。首条`完整消息`的index是0，后续的index递增。";
-/** 判定 user/message 的 source 是否为本插件自产（压缩日志机制消息；含兼容旧宿主 checkpoint 标记 'compact'）。这类消息不占完整消息 index。 */
+/** 判定 user/message 的 source 是否为本插件自产（压缩日志消息；含旧宿主 checkpoint 标记兼容）。这类消息不占完整消息 index。 */
 function isPluginOwnedSource(source) {
 	if (source?.kind !== "plugin") return false;
 	return source.plugin === "dsh-plugin-om" || source.plugin === "compact";
 }
 //#endregion
 //#region src/utils.ts
-/** 判断值是否为普通对象：typeof object 且非 null 且非数组（类型收窄用）。 */
+/** 判断值是否为普通对象（非 null、非数组）。 */
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** 生成 uuid：优先 crypto.randomUUID，回退为时间戳+随机串拼接（保证唯一性）。 */
+/** 生成 uuid：优先 crypto.randomUUID，回退为时间戳+随机串拼接。 */
 function uuid() {
-	/** 全局 crypto 对象（提供 randomUUID 的现代环境才存在）。 */
 	const cryptoObj = globalThis.crypto;
 	if (cryptoObj && typeof cryptoObj.randomUUID === "function") return cryptoObj.randomUUID();
 	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
@@ -44,15 +44,13 @@ function uuid() {
 /** 提取 content 数组中的纯文本块（type === 'text' 的 block.text 拼接）。 */
 function blocksToText(blocks) {
 	if (!Array.isArray(blocks)) return "";
-	/** 拼接结果缓冲区。 */
 	const out = [];
 	for (const block of blocks) if (isRecord(block) && block.type === "text" && typeof block.text === "string") out.push(block.text);
 	return out.join("");
 }
-/** 消息内容的字符数：递归计入 text 块与 tool-result 内嵌文本（与宿主 token 估算口径一致）。 */
+/** 消息内容的字符数：递归计入 text 块与 tool-result 内嵌文本。 */
 function textCharCount(message) {
 	if (!message || !Array.isArray(message.content)) return 0;
-	/** 累计字符数。 */
 	let total = 0;
 	for (const block of message.content) if (block.type === "text") total += block.text.length;
 	else if (block.type === "tool-result") total += blocksToText(block.content).length;
@@ -61,7 +59,6 @@ function textCharCount(message) {
 /** 面向 recall 的完整消息呈现：text 原样；tool-call 展开（参数=代码）；tool-result 取文本。 */
 function renderMessageText(message) {
 	if (!message || !Array.isArray(message.content)) return "";
-	/** 各内容块呈现后的拼接缓冲区。 */
 	const parts = [];
 	for (const block of message.content) if (block.type === "text") parts.push(block.text);
 	else if (block.type === "tool-call") parts.push(`[tool-call ${block.name} id=${String(block.id)}]
@@ -69,7 +66,7 @@ ${safeJson(block.arguments)}`);
 	else if (block.type === "tool-result") parts.push(blocksToText(block.content));
 	return parts.join("\n");
 }
-/** 安全 JSON 序列化：序列化失败时退回 String 呈现（避免渲染异常）。 */
+/** 安全 JSON 序列化：序列化失败时退回 String 呈现。 */
 function safeJson(value) {
 	try {
 		return JSON.stringify(value, null, 2);
@@ -77,14 +74,13 @@ function safeJson(value) {
 		return String(value);
 	}
 }
-/** 主会话判定：subagent 会话 header.origin === 'subagent'（压缩/recall 仅主会话生效）。 */
+/** 主会话判定：subagent 会话 header.origin === 'subagent'。 */
 function isMainSession(session) {
 	return session.header?.origin !== "subagent";
 }
 /** 解析会话路由目标（provider/model），未路由时返回 undefined。 */
 function routedTarget(session) {
 	try {
-		/** 会话请求头中的路由配置。 */
 		const config = session.requestHeader()?.config;
 		if (config?.provider && config.model) return {
 			provider: config.provider,
@@ -95,39 +91,29 @@ function routedTarget(session) {
 //#endregion
 //#region src/log-index.ts
 /**
-* 会话日志索引：完整消息索引（index 定位完整消息，recall 与摘要共用同一套编号），
-* 以及表层节点定位辅助。事件日志仅追加（被遮蔽的事件仍可读，recall 依赖此性质）。
+* 会话日志索引：完整消息索引与渲染。
+* 导出 indexCompleteMessages（完整消息四类折叠索引，recall 与摘要共用同一套编号）、
+* indexMessages / surfaceIndexOf / messageIdOfEvent（消息级定位辅助）、
+* collectImageRefs / renderCompleteMessageParts / renderCompleteMessage（完整消息渲染
+* 与图片附件收集）。事件日志仅追加（被遮蔽的事件仍可读，recall 依赖此性质）。
 *
-* 完整消息是摘要日志与 recall 共用的定位单位，分四类：
-*  - user：用户消息（user/message 中 source.kind === 'user'）占一条；
-*  - sys：系统消息（user/message 中其余 source.kind 的部分，如宿主注入的上下文）
-*    占一条；压缩日志中以 <sys type="KIND" index="N"> 空块表示（内容不进入输入）；
-*  - assistant：模型输出文本（assistant/message 中的文本块）占一条；
-*  - toolcall：单个工具调用及其结果占一条（同一条 AI 消息里的文本与工具调用拆开，
-*    tool/result 按 source.callId 匹配其 tool-call；未匹配的 result 独立成条，防御）。
-* 本插件自产的压缩日志消息（source.kind === 'plugin' 且 plugin 为本插件标识）不占 index。
-* index 从 0 起、按日志顺序递增、只追加不重排 → 会话内全局稳定，
-* 压缩后旧摘要条目引用的 index 仍然有效。
+* 完整消息分四类：user（用户消息）、sys（系统消息，压缩日志中以 <sys> 空块表示）、
+* assistant（模型输出文本）、toolcall（单个工具调用及其结果，result 按 callId 匹配并入）。
+* index 从 0 起、按日志顺序递增、只追加不重排（压缩后旧摘要条目引用的 index 仍然有效）。
 */
 /**
 * 完整消息索引：按日志顺序把消息事件折叠为完整消息序列（四类，见文件头）。
 * 工具调用结果按 source.callId 匹配其 tool-call 并入该条；未匹配的 result 独立成条（防御）。
-* 插件在 agent/pre-step 触发压缩（日志 call-result 完备），因此压缩时不存在未闭合的
-* tool-call；索引对未闭合调用不设特殊处理。
+* 本插件自产消息不占位；压缩在 agent/pre-step 触发（call-result 完备），不存在未闭合调用。
 */
 function indexCompleteMessages(session) {
-	/** 完整消息序列（index = 数组下标，0 起）。 */
 	const cms = [];
-	/** 等待结果的 toolcall 完整消息（callId → cm）。 */
 	const pending = /* @__PURE__ */ new Map();
-	/** 会话全部事件（仅追加）。 */
 	const events = session.events;
 	for (let seq = 0; seq < events.length; seq += 1) {
-		/** 当前待检查事件。 */
 		const event = events[seq];
 		if (!event) continue;
 		if (event.type === "user/message") {
-			/** 事件 source（区分用户消息与宿主注入/插件消息）。 */
 			const source = event.data.source;
 			if (isPluginOwnedSource(source)) continue;
 			if (source?.kind === "user") cms.push({
@@ -142,10 +128,8 @@ function indexCompleteMessages(session) {
 				...source?.kind === void 0 ? {} : { kind: source.kind }
 			});
 		} else if (event.type === "assistant/message") {
-			/** 助手消息（含文本与 tool-call 块）。 */
 			const message = event.data.message;
 			if (!message || !Array.isArray(message.content)) continue;
-			/** 是否存在文本块（有则先产出 assistant 条）。 */
 			let hasText = false;
 			for (const block of message.content) if (block.type === "text") {
 				hasText = true;
@@ -158,9 +142,7 @@ function indexCompleteMessages(session) {
 			});
 			for (const block of message.content) {
 				if (block.type !== "tool-call") continue;
-				/** 工具调用 id（匹配 result 用）。 */
 				const callId = String(block.id ?? "");
-				/** 本调用对应的完整消息（结果随后并入）。 */
 				const cm = {
 					index: cms.length,
 					type: "toolcall",
@@ -171,11 +153,8 @@ function indexCompleteMessages(session) {
 				if (callId !== "") pending.set(callId, cm);
 			}
 		} else if (event.type === "tool/result") {
-			/** 结果消息的 source（callId 关联调用）。 */
 			const source = event.data.message?.source;
-			/** 关联的调用 id。 */
 			const callId = String(source?.callId ?? "");
-			/** 匹配到的 toolcall 完整消息（无则独立成条）。 */
 			const cm = callId === "" ? void 0 : pending.get(callId);
 			if (cm) {
 				cm.seqs.push(seq);
@@ -191,42 +170,66 @@ function indexCompleteMessages(session) {
 	return cms;
 }
 /**
-* 渲染一条完整消息的文本（recall 输出 / new 模式输入共用）：
-*  - user / sys：消息原文；
-*  - assistant：仅文本块；
-*  - toolcall：调用块（工具名 + 参数）+ 结果文本（pruner 裁剪超大结果）。
+* 递归收集内容块中的图片附件元数据（recall 输出保留图片用）：
+* image 块按附件元数据收集（字段不全则忽略）；tool-result 块递归收集其 content。
 */
-function renderCompleteMessage(session, cm, pruner) {
+function collectImageRefs(content, out) {
+	if (!Array.isArray(content)) return;
+	for (const block of content) {
+		if (!isRecord(block)) continue;
+		if (block.type === "image") {
+			const a = block.attachment;
+			if (isRecord(a) && typeof a.attachmentId === "string" && a.attachmentId !== "" && typeof a.mediaType === "string" && typeof a.bytes === "number" && Number.isFinite(a.bytes) && typeof a.width === "number" && Number.isFinite(a.width) && typeof a.height === "number" && Number.isFinite(a.height)) out.push({
+				attachmentId: a.attachmentId,
+				mediaType: a.mediaType,
+				bytes: a.bytes,
+				width: a.width,
+				height: a.height,
+				...typeof a.name === "string" && a.name !== "" ? { name: a.name } : {}
+			});
+		} else if (block.type === "tool-result") collectImageRefs(block.content, out);
+	}
+}
+/**
+* 渲染一条完整消息为「文本 + 图片」（recall / recall-semantic 输出用）：
+* user/sys 取消息原文，assistant 取文本块，toolcall 为调用块 + 结果文本
+* （pruner 裁剪超大结果）；同时收集该条完整消息携带的图片附件（含 tool-result 嵌套，
+* pruner 裁剪掉的图片不收集）。
+*/
+function renderCompleteMessageParts(session, cm, pruner) {
+	const images = [];
 	if (cm.type === "user" || cm.type === "sys") {
-		/** 用户/系统消息事件（seq 缺失则无法渲染）。 */
 		const seq = cm.seqs[0];
 		const event = seq === void 0 ? void 0 : session.events[seq];
-		/** 派生的消息对象。 */
 		const message = event ? session.deriveEventMessage(event) : null;
-		return message ? renderMessageText(message) : "";
+		if (message && Array.isArray(message.content)) collectImageRefs(message.content, images);
+		return {
+			text: message ? renderMessageText(message) : "",
+			images
+		};
 	}
 	if (cm.type === "assistant") {
-		/** 助手消息事件（seq 缺失则无法渲染）。 */
 		const seq = cm.seqs[0];
 		const event = seq === void 0 ? void 0 : session.events[seq];
-		/** 派生的消息对象。 */
 		const message = event ? session.deriveEventMessage(event) : null;
-		if (!message || !Array.isArray(message.content)) return "";
-		/** 文本块拼接缓冲。 */
+		if (!message || !Array.isArray(message.content)) return {
+			text: "",
+			images
+		};
+		collectImageRefs(message.content, images);
 		const texts = [];
 		for (const block of message.content) if (block.type === "text") texts.push(String(block.text));
-		return texts.join("\n");
+		return {
+			text: texts.join("\n"),
+			images
+		};
 	}
-	/** 渲染缓冲。 */
 	const parts = [];
-	/** 承载调用块的 assistant 事件（seq 缺失则跳过调用块）。 */
 	const callSeq = cm.seqs[0];
 	const callEvent = callSeq === void 0 ? void 0 : session.events[callSeq];
 	if (callEvent?.type === "assistant/message") {
-		/** 助手消息对象（取对应调用块）。 */
 		const message = session.deriveEventMessage(callEvent);
 		if (message && Array.isArray(message.content)) {
-			/** 匹配的 tool-call 块。 */
 			let call;
 			for (const block of message.content) if (block.type === "tool-call" && String(block.id ?? "") === (cm.callId ?? "")) {
 				call = block;
@@ -235,33 +238,35 @@ function renderCompleteMessage(session, cm, pruner) {
 			if (call) parts.push(`[tool-call ${String(call.name ?? "")} id=${String(call.id ?? "")}]\n${safeJson(call.arguments)}`);
 		}
 	}
-	/** 结果事件 seq（无则调用未闭合）。 */
 	const resultSeq = cm.seqs[1];
 	const resultEvent = resultSeq === void 0 ? void 0 : session.events[resultSeq];
 	if (resultEvent?.type === "tool/result") {
-		/** 结果消息对象（pruner 裁剪超大内容后渲染）。 */
 		let message = session.deriveEventMessage(resultEvent);
 		if (message && pruner?.pruneContent) {
-			/** 裁剪后的内容块。 */
 			const pruned = pruner.pruneContent(message.content);
 			if (pruned) message = {
 				...message,
 				content: pruned
 			};
 		}
-		/** 结果文本。 */
+		if (message && Array.isArray(message.content)) collectImageRefs(message.content, images);
 		const text = message ? renderMessageText(message) : "";
 		if (text.trim() !== "") parts.push(`[result]\n${text}`);
 	}
-	return parts.join("\n");
+	return {
+		text: parts.join("\n"),
+		images
+	};
+}
+/** 渲染一条完整消息的文本（压缩输入与语义嵌入共用）：renderCompleteMessageParts 的纯文本投影。 */
+function renderCompleteMessage(session, cm, pruner) {
+	return renderCompleteMessageParts(session, cm, pruner).text;
 }
 //#endregion
 //#region src/logger.ts
 /**
-* 日志辅助：步骤级（debug）日志默认仅 dev（非 production）输出，便于开发调试；
-* 失败等关键日志始终输出（不受 debug 开关影响）。
-* 开关配置键 debug：true 强制开启、false 强制关闭，缺省按 NODE_ENV !== 'production' 判定
-* （默认值由 resolveConfig 解析，见 config.ts）。
+* 插件日志门面：step 为步骤级（debug）日志，按配置开关过滤；info/warn 始终输出。
+* 导出 PluginLogger / makeLogger。
 */
 /** 构建插件日志门面：统一加 PLUGIN_LABEL 前缀，step 按 debug 开关过滤。 */
 function makeLogger(ctx, debug) {
@@ -7368,7 +7373,7 @@ var require_dom_parser = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.onWarningStopParsing = onWarningStopParsing;
 }));
 //#endregion
-//#region src/summarize.ts
+//#region src/rate-limit.ts
 var import_lib = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	var conventions = require_conventions();
 	exports.assign = conventions.assign;
@@ -7409,14 +7414,66 @@ var import_lib = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.onWarningStopParsing = domParser.onWarningStopParsing;
 })))();
 /**
+* 全局限流门（插件进程级共享状态）：任一摘要请求遇 429 后进入冷却期，
+* 此后所有摘要请求发出前先等待到「最近一次 429 + rateLimitWaitMs」之后。
+* 等待期间 signal 中止则立即放弃；等待期间的新 429 顺延冷却期。
+* 导出 isRateLimitError / noteRateLimit / gateRateLimit / RATE_LIMIT_WAIT_MS_DEFAULT /
+* resetRateLimitGate。
+*/
+/** 最近一次 429 限流的时间戳（ms；null = 未遇过限流，门直接放行）。 */
+let lastRateLimitAt = null;
+/** 判定错误信息是否为 429 限流（匹配 429 或 rate limit，大小写不敏感）。 */
+function isRateLimitError(message) {
+	return /\b429\b|rate[\s_-]?limit/i.test(message);
+}
+/** 记录一次 429 限流：把冷却期起点更新为当前时间。 */
+function noteRateLimit() {
+	lastRateLimitAt = Date.now();
+}
+/** 可中止延时：等待满 ms 返回 true；等待期间 signal 中止返回 false。 */
+function delay(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve(false);
+			return;
+		}
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve(true);
+		}, ms);
+		const onAbort = () => {
+			cleanup();
+			resolve(false);
+		};
+		const cleanup = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* 限流等待门：处于 429 冷却期时等待到期限再放行（返回 true）；
+* 等待期间 signal 中止返回 false。未遇过限流或冷却期已过立即放行。waitMs ≤ 0 视为不限流。
+*/
+async function gateRateLimit(waitMs, signal) {
+	if (waitMs <= 0) return true;
+	while (lastRateLimitAt !== null) {
+		const remaining = lastRateLimitAt + waitMs - Date.now();
+		if (remaining <= 0) return true;
+		if (!await delay(remaining, signal)) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/summarize.ts
+/**
 * 共享压缩提示词（观察/反思同一套）：定义 history 块（模型消息 + index 的表达形式）、
-* 完整消息定义、要求压缩（完整保留用户消息 / reasoning 仅参考 / 关联 assistant 合并 /
-* index/start/end 连续）、输出格式（一个合法 <history> 块，无 reasoning）、数据源说明。
-* mode 控制【摘要粒度】：无参为通用提示词（反思调用）；'summary' 要求简单摘要（较早分块）；
-* 'detailed' 要求越往后越细（最后一块保留细节）。观察分块时除最后一块外均用 'summary'。
+* 完整消息定义、压缩要求（完整保留用户/系统消息、reasoning 仅参考、关联 assistant
+* 合并为模块、index 连续）、输出格式与数据源说明。
 */
-function buildHistoryPrompt(mode) {
-	const lines = [
+function buildHistoryPrompt() {
+	return [
 		"把下方的 <history> 消息记录压缩为一份更紧凑的 <history> 压缩日志。不用工具、不展示思考、不输出多余文字。",
 		"",
 		"【history 块定义】",
@@ -7452,37 +7509,23 @@ function buildHistoryPrompt(mode) {
 		`</${HISTORY_TAG}>`,
 		"",
 		"【数据源】下方的 <history> 消息记录是本次要压缩的全部消息；压缩结果作为一个新的 <history> 块输出。"
-	];
-	if (mode !== void 0) {
-		const granularity = mode === "summary" ? "【摘要粒度】本条为较早的消息，做简单摘要即可：概括要点，不必展开细节；但用户消息仍逐条保留原文，不概括、不省略。" : "【摘要粒度】本条为最近的消息，越往后越细：靠近末尾的完整消息保留更多细节（关键文件、改动与结论），前面的可适当从简；但用户消息始终逐条保留原文，不概括、不省略。";
-		const marker = "【输出格式】只输出一个 <history> 包裹的合法 XML 日志块";
-		const markerIndex = lines.findIndex((line) => line.includes(marker));
-		if (markerIndex !== -1) lines.splice(markerIndex, 0, granularity);
-	}
-	return lines.join("\n");
+	].join("\n");
 }
-/** 渲染用户消息条目（DOM 元素）：文本块原样；图片/文件等非文本块以注释补充（说明传入了什么）。 */
+/** 渲染用户消息条目（DOM 元素）：文本块原样；图片/文件等非文本块以注释补充。 */
 function renderUserEntry(doc, session, cm) {
-	/** 用户消息事件（seq 缺失则无法渲染）。 */
 	const seq = cm.seqs[0];
 	const event = seq === void 0 ? void 0 : session.events[seq];
-	/** 派生的消息对象。 */
 	const message = event ? session.deriveEventMessage(event) : null;
 	if (!message || !Array.isArray(message.content)) return null;
-	/** user_message 元素（文本 + 注释）。 */
 	const el = doc.createElement("user_message");
 	el.setAttribute("index", String(cm.index));
-	/** 是否存在可输出内容（文本或注释）。 */
 	let hasContent = false;
 	for (const block of message.content) if (block.type === "text") {
 		el.appendChild(doc.createTextNode(String(block.text)));
 		hasContent = true;
 	} else if (block.type === "image") {
-		/** 图片附件元数据（名称 / 媒体类型 / 尺寸 / 字节数）。 */
 		const ref = block.attachment;
-		/** 显示名（有则附上）。 */
 		const name = ref?.name ? `：${ref.name}` : "";
-		/** 元数据串。 */
 		const meta = ref ? `（${String(ref.mediaType ?? "")} ${String(ref.width ?? "")}×${String(ref.height ?? "")}，${String(ref.bytes ?? "")} bytes）` : "";
 		el.appendChild(doc.createComment(` 图片附件${name}${meta} `));
 		hasContent = true;
@@ -7494,40 +7537,29 @@ function renderUserEntry(doc, session, cm) {
 	return el;
 }
 /**
-* 渲染完整消息记录（观察输入，new 模式）：输出一个合法的 <history> 块——
-*  - user → <user_message index="N">（文本原样；图片/文件注释）；
-*  - sys → <sys type="KIND" index="N"></sys>（系统消息空块，内容不进入压缩输入）；
-*  - 每条 assistant 消息的 reasoning → <reasoning>（参考条目，产物中没有）；
-*  - assistant / toolcall → <assistant index="N">（模型输出文本 / toolcall&result 原样）。
-* 文本经 XML 序列化自动转义（用户输入 / 文本 / reasoning 中的特殊字符不破坏 XML 合法性）。
-* 仅渲染 seqs 全部落在给定集合内的完整消息（本插件自产消息天然不占位）。
+* 渲染完整消息记录（观察输入）：输出一个合法的 <history> 块——
+* user → <user_message>（文本原样、图片注释）、sys → <sys> 空块、assistant 的
+* reasoning → <reasoning>（参考条目）、assistant/toolcall → <assistant>（原样文本）。
+* 文本经 XML 序列化自动转义；仅渲染 seqs 全部落在给定集合内的完整消息。
 */
 function renderMessages(session, seqs) {
-	/** 遮蔽 seq 集合。 */
 	const shadowed = new Set(seqs);
-	/** 各 assistant 消息的 reasoning 文本（seq → 文本列表，按日志顺序）。 */
 	const reasoningBySeq = /* @__PURE__ */ new Map();
 	for (const seq of seqs) {
-		/** 当前 assistant 消息（非消息事件跳过）。 */
 		const event = session.events[seq];
 		if (event?.type !== "assistant/message") continue;
 		const message = event.data.message;
 		if (!message || !Array.isArray(message.content)) continue;
-		/** 该消息的 reasoning 块文本。 */
 		const reasonings = [];
 		for (const block of message.content) if (block.type === "reasoning" && typeof block.text === "string") reasonings.push(block.text);
 		if (reasonings.length > 0) reasoningBySeq.set(seq, reasonings);
 	}
-	/** 已输出 reasoning 的 assistant 消息 seq（每条消息的 reasoning 只输出一次）。 */
 	const emittedReasoning = /* @__PURE__ */ new Set();
-	/** DOM 文档（构建条目元素）。 */
 	const doc = new import_lib.DOMParser().parseFromString(`<${HISTORY_TAG} />`, "text/xml");
-	/** 顶层条目元素（按日志顺序）。 */
 	const entries = [];
 	for (const cm of indexCompleteMessages(session)) {
 		if (!cm.seqs.every((seq) => shadowed.has(seq))) continue;
 		if (cm.type === "sys") {
-			/** sys 元素（type=source.kind，index=完整消息序号）。 */
 			const sysEl = doc.createElement("sys");
 			sysEl.setAttribute("type", cm.kind ?? "");
 			sysEl.setAttribute("index", String(cm.index));
@@ -7536,45 +7568,35 @@ function renderMessages(session, seqs) {
 			continue;
 		}
 		if (cm.type === "user") {
-			/** 用户消息条目（无文本且无注释则跳过）。 */
 			const rendered = renderUserEntry(doc, session, cm);
 			if (rendered === null) continue;
 			entries.push(rendered);
 		} else {
-			/** 承载该条完整消息的 assistant seq（缺失则无 reasoning 可输出）。 */
 			const callSeq = cm.seqs[0];
-			/** 该消息的 reasoning（无则跳过）。 */
 			const reasonings = callSeq === void 0 ? void 0 : reasoningBySeq.get(callSeq);
 			if (callSeq !== void 0 && reasonings !== void 0 && !emittedReasoning.has(callSeq)) {
 				emittedReasoning.add(callSeq);
 				for (const text of reasonings) {
-					/** reasoning 元素（文本自动转义）。 */
 					const re = doc.createElement("reasoning");
 					re.appendChild(doc.createTextNode(text));
 					entries.push(re);
 				}
 			}
-			/** 该条完整消息的文本（assistant=文本；toolcall=调用参数+结果，原样）。 */
 			const text = renderCompleteMessage(session, cm);
 			if (text.trim() === "") continue;
-			/** assistant 元素（文本自动转义）。 */
 			const el = doc.createElement("assistant");
 			el.setAttribute("index", String(cm.index));
 			el.appendChild(doc.createTextNode(text));
 			entries.push(el);
 		}
 	}
-	/** XML 序列化器（文本/注释自动转义）。 */
 	const serializer = new import_lib.XMLSerializer();
 	return `<${HISTORY_TAG}>\n${entries.map((el) => serializer.serializeToString(el)).join("\n")}\n</${HISTORY_TAG}>`;
 }
-/** 流收集器：提取文本输出 + usage + finish（不依赖宿主 BlockAssembler，保持零运行时依赖）。 */
+/** 流收集器：提取文本输出 + usage + finish（不依赖宿主 BlockAssembler）。 */
 var StreamCollector = class {
-	/** 文本输出缓冲（text-delta 拼接；reasoning 不计入）。 */
 	textBuf = "";
-	/** usage chunk（无则 undefined）。 */
 	_usage;
-	/** finish chunk（流结束仍无则视为 stop）。 */
 	_finish;
 	/** 喂入一个流 chunk（仅消费文本/usage/finish，其余忽略）。 */
 	push(chunk) {
@@ -7601,7 +7623,7 @@ var StreamCollector = class {
 		return this._finish ?? { kind: "stop" };
 	}
 };
-/** 构造插件自产 user 消息（指令或 new 模式的输入消息；id 为品牌类型 MessageId）。 */
+/** 构造插件自产 user 消息（摘要调用的输入消息；id 为品牌类型 MessageId）。 */
 function makePluginUserMessage(text) {
 	return {
 		id: uuid(),
@@ -7617,8 +7639,8 @@ function makePluginUserMessage(text) {
 	};
 }
 /**
-* 构建摘要请求选项（new 方式）：指令作为 system，渲染输入（被压缩消息）作为
-* 唯一的 user 消息——不沿用主会话请求前缀（前缀复用需模型自行计数，导致索引异常）。
+* 构建摘要请求选项：指令作为 system，渲染输入作为唯一的 user 消息，
+* 不沿用主会话请求前缀（前缀复用需模型自行计数，导致索引异常）。
 */
 function buildSummaryOptions(session, instruction, contextText, maxTokens, target, signal) {
 	return {
@@ -7636,7 +7658,6 @@ function buildSummaryOptions(session, instruction, contextText, maxTokens, targe
 const HISTORY_FORMAT_NOTE = `<!-- 完整消息：${COMPLETE_MESSAGE_DEFINITION} <TAG index="N">表示单条完整消息，<TAG start="A" end="B"> 表示连续模块，start/end 是首尾完整消息的 index；<sys type="KIND" index="N"> 表示被压缩的系统消息，块中为空 -->`;
 /** 读取元素整数属性（非负整数；缺失 / 非数字返回 undefined）。 */
 function intAttr(el, name) {
-	/** 属性原始值（缺失为 null）。 */
 	const raw = el.getAttribute(name);
 	if (raw === null || raw === "") return void 0;
 	if (!/^\d+$/.test(raw)) return void 0;
@@ -7644,43 +7665,31 @@ function intAttr(el, name) {
 }
 /**
 * 用 XML 解析器解析一个 <history> 块（结构合法性校验）：
-*  - 非法 XML（标签不匹配 / 未闭合 / 多根等）→ null；
-*  - 根节点必须是 <history>；
-*  - 顶层只允许 user_message / assistant / sys 条目元素（其余元素类型视为不合法）；
-*  - 出现 <reasoning> 元素时标记 hasReasoning（产物不允许）。
-* 条目按文档顺序提取（index / start / end 属性缺失或不合法 → 不合法）。
+* 非法 XML / 根非 <history> / 顶层出现未定义元素 / 条目属性缺失或非法 → null；
+* 出现 <reasoning> 元素时标记 hasReasoning（产物不允许）。
 */
 function parseHistoryBlock(xml) {
-	/** DOM 文档（解析失败抛错）。 */
 	let doc;
 	try {
 		doc = new import_lib.DOMParser().parseFromString(xml, "text/xml");
 	} catch {
 		return null;
 	}
-	/** 根节点（必须为 <history>）。 */
 	const root = doc.documentElement;
 	if (!root || root.nodeName !== "history") return null;
-	/** 条目缓冲区。 */
 	const entries = [];
-	/** 是否含 reasoning 元素。 */
 	let hasReasoning = false;
-	/** 根的子节点。 */
 	const children = root.childNodes;
 	for (let i = 0; i < children.length; i += 1) {
-		/** 当前子节点（跳过文本与注释）。 */
 		const node = children[i];
 		if (node?.nodeType !== 1) continue;
-		/** 子元素（节点类型收窄）。 */
 		const el = node;
-		/** 元素标签名。 */
 		const tag = el.nodeName;
 		if (tag === "reasoning") {
 			hasReasoning = true;
 			continue;
 		}
 		if (tag === "user_message") {
-			/** index 属性（缺失/非法 → 不合法）。 */
 			const index = intAttr(el, "index");
 			if (index === void 0) return null;
 			entries.push({
@@ -7688,7 +7697,6 @@ function parseHistoryBlock(xml) {
 				index
 			});
 		} else if (tag === "sys") {
-			/** index 属性（缺失/非法 → 不合法）。 */
 			const index = intAttr(el, "index");
 			if (index === void 0) return null;
 			entries.push({
@@ -7696,7 +7704,6 @@ function parseHistoryBlock(xml) {
 				index
 			});
 		} else if (tag === "assistant") {
-			/** 单条 index 或模块 start..end（二选一）。 */
 			const index = intAttr(el, "index");
 			if (index !== void 0) entries.push({
 				kind: "assistant",
@@ -7721,13 +7728,11 @@ function parseHistoryBlock(xml) {
 }
 /**
 * 解析文本中全部 <history> 块内的条目（反思输入为多个块拼接：逐块解析提取）。
-* 非法块（结构错误 / 根非 history）跳过；仅提取不校验顺序（连续性由 historyContinuity 校验）。
+* 非法块跳过；仅提取不校验顺序（连续性由 historyContinuity 校验）。
 */
 function parseHistoryEntries(text) {
-	/** 条目缓冲区。 */
 	const out = [];
 	for (const m of text.matchAll(/<history[\s\S]*?<\/history>/g)) {
-		/** 单块解析结果（非法块跳过）。 */
 		const parsed = parseHistoryBlock(m[0]);
 		if (parsed === null) continue;
 		out.push(...parsed.entries);
@@ -7735,16 +7740,13 @@ function parseHistoryEntries(text) {
 	return out;
 }
 /**
-* 校验条目 index/start/end 连续性：每条给出覆盖区间 [lo, hi]（单条 index 为自身），
-* 按块内出现顺序，相邻条目必须首尾相接（后一条 lo = 前一条 hi + 1），返回整体覆盖区间；
-* 空条目 / 非法范围（start > end） / 跳号、重叠或乱序 → 返回 null。
+* 校验条目 index/start/end 连续性：每条给出覆盖区间，按出现顺序相邻条目必须首尾相接，
+* 返回整体覆盖区间；空条目 / 非法范围 / 跳号、重叠或乱序 → 返回 null。
 */
 function historyContinuity(entries) {
 	if (entries.length === 0) return null;
-	/** 各条目覆盖区间（保持块内出现顺序）。 */
 	const ranges = [];
 	for (const e of entries) {
-		/** 模块（start/end）或单条（index 为自身）。 */
 		const lo = e.kind === "assistant" && e.start !== void 0 ? e.start : e.index ?? 0;
 		const hi = e.kind === "assistant" && e.end !== void 0 ? e.end : e.index ?? 0;
 		if (lo > hi) return null;
@@ -7754,13 +7756,11 @@ function historyContinuity(entries) {
 		});
 	}
 	for (let i = 1; i < ranges.length; i += 1) {
-		/** 相邻两条（防御性判空）。 */
 		const prev = ranges[i - 1];
 		const curr = ranges[i];
 		if (prev === void 0 || curr === void 0) return null;
 		if (curr.lo !== prev.hi + 1) return null;
 	}
-	/** 首尾条目（防御性判空）。 */
 	const first = ranges[0];
 	const last = ranges[ranges.length - 1];
 	if (first === void 0 || last === void 0) return null;
@@ -7769,83 +7769,141 @@ function historyContinuity(entries) {
 		end: last.hi
 	};
 }
+/** <history> 开标签（允许携带属性）：模糊定位输出中日志块起点。 */
+const HISTORY_OPEN_TAG_RE = /<history(\s[^>]*)?>/;
+/** history 块内条目标签的 token 正则（开 / 闭 / 自闭合）：模糊提取按标签逐个扫描配对。 */
+const HISTORY_ENTRY_TOKEN_RE = /<(\/)?(user_message|sys|assistant|reasoning)\b([^>]*?)(\/)?>/g;
+/** 解析标签属性串为键值对（支持双引号 / 单引号 / 无引号取值；非法片段忽略）。 */
+function parseTagAttrs(raw) {
+	const attrs = {};
+	for (const m of raw.matchAll(/([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g)) {
+		const key = m[1] ?? "";
+		const value = m[3] ?? m[4] ?? m[5] ?? "";
+		if (key !== "") attrs[key] = value;
+	}
+	return attrs;
+}
+/**
+* 解码 XML 预定义实体（&amp; 最后解码，避免 &amp;lt; 之类被二次解码）。
+* 模糊提取的条目文本解码后经 XML 序列化重新转义，已有转义形式不发生二次转义。
+*/
+function decodeXmlEntities(text) {
+	return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+/**
+* 模糊重建 <history> 块（xmldom 原生无模糊匹配，按条目标签做字符串级扫描配对）：
+* 依次提取 user_message / sys / assistant / reasoning 条目——开闭标签就近配对、
+* 自闭合直接成条、未闭合条目以文本末尾收口；未知元素与其间杂文忽略；条目文本
+* 解码后重新序列化为合法 XML。扫描不到任何条目返回 null。
+*/
+function rebuildHistoryBlock(inner) {
+	const entries = [];
+	const stack = [];
+	for (const m of inner.matchAll(HISTORY_ENTRY_TOKEN_RE)) {
+		const tag = m[2] ?? "";
+		if (m[1] === "/") for (let i = stack.length - 1; i >= 0; i -= 1) {
+			const open = stack[i];
+			if (open?.tag === tag) {
+				entries.push({
+					tag,
+					attrs: open.attrs,
+					content: inner.slice(open.contentFrom, m.index)
+				});
+				stack.splice(i, 1);
+				break;
+			}
+		}
+		else if (m[4] === "/") entries.push({
+			tag,
+			attrs: parseTagAttrs(m[3] ?? ""),
+			content: ""
+		});
+		else stack.push({
+			tag,
+			attrs: parseTagAttrs(m[3] ?? ""),
+			contentFrom: m.index + m[0].length
+		});
+	}
+	for (const open of stack) entries.push({
+		tag: open.tag,
+		attrs: open.attrs,
+		content: inner.slice(open.contentFrom)
+	});
+	if (entries.length === 0) return null;
+	const doc = new import_lib.DOMParser().parseFromString(`<${HISTORY_TAG} />`, "text/xml");
+	const root = doc.documentElement;
+	if (!root) return null;
+	for (const e of entries) {
+		const el = doc.createElement(e.tag);
+		for (const [key, value] of Object.entries(e.attrs)) el.setAttribute(key, decodeXmlEntities(value));
+		el.appendChild(doc.createTextNode(decodeXmlEntities(e.content)));
+		root.appendChild(el);
+	}
+	return new import_lib.XMLSerializer().serializeToString(root);
+}
 /**
 * 从 AI 摘要输出中提取合法日志（不信任 AI 的总结结果）：
-*  - 取首个 <history> 到最后一个 </history>（含两个首尾）切为日志；
-*  - 找不到、顺序颠倒（首个开标签在最后一个闭标签之后）或中间内容长度 < MIN_HISTORY_LENGTH
-*    视为不合法（返回 null，调用方按失败重试）；
-*  - 用 XML 解析器校验结构合法性（非法 XML / 多块输出 / 根非 <history> → 不合法）；
-*  - 产物不允许包含 <reasoning> 块（仅作参考）；
-*  - index/start/end 连续性校验（historyContinuity + 与 expected 覆盖区间一致）；
-*  - 产出后把首个开标签改写为带 tip 属性的版本（对 AI 的提醒），并在其后插入
-*    格式说明注释（HISTORY_FORMAT_NOTE，块顶）。
+* 取首个 <history> 开标签（允许带属性）到最后一个 </history> 切为候选块，
+* 找不到或内容过短返回 null；候选块经 XML 结构校验，整块非法时按条目模糊
+* 提取重建为合法块（不要求模型输出整体合法 XML）；随后统一校验：无 reasoning、
+* index 连续且与 expected 覆盖区间一致；通过后统一改写为带 tip 属性的开标签
+* 并在块顶插入格式说明注释。
 */
 function extractSummaryLog(raw, expected) {
-	/** 开标签（模型输出格式）。 */
-	const openTag = `<${HISTORY_TAG}>`;
-	/** 闭标签。 */
 	const closeTag = `</${HISTORY_TAG}>`;
-	/** 带 tip 属性的开标签（插件产出格式）。 */
-	const openTagWithTip = `<${HISTORY_TAG} tip="${HISTORY_TIP}">`;
-	/** 首个开标签位置（无则 -1）。 */
-	const open = raw.indexOf(openTag);
-	/** 最后一个闭标签位置（无则 -1）。 */
+	const openMatch = HISTORY_OPEN_TAG_RE.exec(raw);
+	const open = openMatch?.index ?? -1;
 	const close = raw.lastIndexOf(closeTag);
-	if (open === -1 || close === -1 || close < open) return null;
-	if (raw.slice(open + openTag.length, close).trim().length < 10) return null;
-	/** 完整日志块（含两个首尾）。 */
+	if (openMatch === null || close === -1 || close < open) return null;
+	const inner = raw.slice(open + openMatch[0].length, close);
+	if (inner.trim().length < 10) return null;
 	const block = raw.slice(open, close + closeTag.length);
-	/** XML 解析结果。 */
-	const parsed = parseHistoryBlock(block);
+	const candidate = parseHistoryBlock(block) === null ? rebuildHistoryBlock(inner) : block;
+	if (candidate === null) return null;
+	const parsed = parseHistoryBlock(candidate);
 	if (parsed === null) return null;
 	if (parsed.hasReasoning) return null;
-	/** 条目覆盖区间。 */
 	const span = historyContinuity(parsed.entries);
 	if (span === null) return null;
 	if (expected?.start !== void 0 && span.start !== expected.start) return null;
 	if (expected?.end !== void 0 && span.end !== expected.end) return null;
-	/** 首个开标签改写为带 tip 版本，块顶紧跟格式说明注释。 */
-	return block.replace(openTag, openTagWithTip).replace(openTagWithTip, `${openTagWithTip}\n${HISTORY_FORMAT_NOTE}`);
+	const candidateInner = candidate.slice(candidate.indexOf(">") + 1, candidate.length - closeTag.length).trim();
+	return `<${HISTORY_TAG} tip="${HISTORY_TIP}">\n${HISTORY_FORMAT_NOTE}\n${candidateInner}\n</${HISTORY_TAG}>`;
 }
 /**
 * 直连 LLM 执行一次摘要（观察或反思），返回文本与可选 token usage。
-* 失败（抛异常 / 空输出 / 非 stop 结束 / 校验不通过）均记录日志并重试，总共最多尝试
-* options.maxAttempts 次（默认 SUMMARY_DEFAULT_MAX_ATTEMPTS）；全部尝试失败返回 null
-* （不产生任何日志变更）。输出长度受 maxTokens 限制。
+* 失败（抛异常 / 空输出 / 非 stop 结束 / 校验不通过）均记录日志并重试，最多尝试
+* options.maxAttempts 次；全部失败返回 null（不产生任何日志变更）。每次请求发出前
+* 先过全局限流等待门。
 */
 async function runSummarySubagent(ctx, agent, instruction, contextText, maxTokens, target, debug, signal, options) {
-	/** 当前会话。 */
 	const session = agent.session;
-	/** 插件日志门面（失败日志始终输出）。 */
 	const logger = makeLogger(ctx, debug);
-	/** 总尝试次数（首次 + 重试；缺省兜底）。 */
 	const maxAttempts = options?.maxAttempts ?? 11;
-	/** 最后一次失败的原因（error=调用异常 / finish=未完成原因；最终失败日志使用）。 */
 	let lastFailure = {};
 	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
 		if (signal?.aborted) {
 			logger.warn(`摘要调用中止（第 ${attempt}/${maxAttempts} 次尝试前 signal 已中止），放弃本次摘要`);
 			return null;
 		}
+		const rateLimitWaitMs = options?.rateLimitWaitMs ?? 6e4;
+		if (!await gateRateLimit(rateLimitWaitMs, signal)) {
+			logger.warn(`摘要调用中止（第 ${attempt}/${maxAttempts} 次尝试前限流等待被 signal 中止），放弃本次摘要`);
+			return null;
+		}
 		logger.step(`摘要调用开始（第 ${attempt}/${maxAttempts} 次，provider ${target.provider}，model ${target.model}，maxTokens ${maxTokens}）`);
 		try {
-			/** 摘要请求选项（new 方式组装）。 */
 			const requestOptions = buildSummaryOptions(session, instruction, contextText, maxTokens, target, signal);
-			/** 流收集器（文本/usage/finish）。 */
 			const collector = new StreamCollector();
 			for await (const chunk of ctx.llm.stream(requestOptions)) collector.push(chunk);
-			/** 提取合法日志（首个 <history> 到最后一个 </history>，无 reasoning、index 连续；不信任 AI 输出）。 */
 			const text = extractSummaryLog(collector.text, options?.expected);
-			/** 终止原因（仅 stop 视为完成）。 */
 			const finish = collector.finish;
 			if (finish.kind !== "stop" || text === null) {
-				/** 未完成原因（空输出 / 非法日志 / 校验不通过 / 非 stop 终止原因）。 */
 				const reason = finish.kind === "stop" ? collector.text.trim() === "" ? "无输出" : "缺少合法 <history> 块（含 reasoning 或 index 不连续）" : String(finish.kind);
 				lastFailure = { finish: reason };
 				logger.warn(`摘要未完成（第 ${attempt}/${maxAttempts} 次，${reason}）` + (attempt < maxAttempts ? "，将重试" : "，重试耗尽，忽略本次摘要"));
 				continue;
 			}
-			/** 摘要请求的 token usage（归入主会话记录；无则省略）。 */
 			const usage = collector.usage;
 			logger.step(`摘要调用成功（第 ${attempt}/${maxAttempts} 次，输出 ${text.length} 字符` + (usage === void 0 ? "" : `，input ${String(usage.inputTokens ?? "?")} / output ${String(usage.outputTokens ?? "?")} tokens`) + "）");
 			return {
@@ -7854,162 +7912,67 @@ async function runSummarySubagent(ctx, agent, instruction, contextText, maxToken
 				...usage === void 0 ? {} : { usage }
 			};
 		} catch (error) {
-			/** 错误信息（统一为字符串）。 */
 			const message = error instanceof Error ? error.message : String(error);
+			if (isRateLimitError(message)) {
+				noteRateLimit();
+				logger.warn(`摘要调用触发限流（429，第 ${attempt}/${maxAttempts} 次），下一次请求前至少等待 ${rateLimitWaitMs}ms`);
+			}
 			lastFailure = { error: message };
 			logger.warn(`摘要调用失败（第 ${attempt}/${maxAttempts} 次，${message}）` + (attempt < maxAttempts ? "，将重试" : "，重试耗尽，忽略本次摘要"));
 		}
 	}
-	/** 全部尝试失败：记录最终失败日志（含最后原因，便于诊断）。 */
 	logger.warn(`摘要调用最终失败（已尝试 ${maxAttempts} 次` + (lastFailure.error !== void 0 ? `，最后错误：${lastFailure.error}` : "") + (lastFailure.finish !== void 0 ? `，最后结果：${lastFailure.finish}` : "") + "），忽略本次摘要");
 	return null;
 }
 //#endregion
 //#region src/compress.ts
 /**
-* 自动压缩（OM 观察/反思两级阈值，思路参考 Mastra Observational Memory）：
-*  - 观察：未压缩消息 tokens ≥ observeThresholdTokens（默认 100000）→ 直连 ctx.llm.stream()
-*    摘要（new 方式：共享提示词作为 system、被压缩消息渲染为 <history> 块输入）把未压缩消息
-*    压缩为观察日志，作为独立的新 <history> 块，只精确替换被压缩的新消息区间（旧块原地
-*    保留，多块并存按序排列；不再把旧+新合并进一条消息）；
-*  - 反思：全部 <history> 块 tokens 合计 ≥ reflectThresholdTokens（默认 30000）→
-*    同上摘要调用精简合并（输入为多个块拼接，共用同一套提示词），把整个块区段合并为一条。
-* 两级检查在 pre-step 阻塞串行执行（先反思后观察），避免压缩失败或重复压缩。
-* 自动压缩由配置键 omEnabled 开关（false 时关闭；recall 工具不受影响）。
-*
-* 压缩边界（historySection）：消息列表中最后一个合法的 <history> 块（source 为插件）
-* 之后的消息视为未压缩；其前（含自身）视为已压缩，不重复压缩、不计入观察阈值。
+* 两级自动压缩（观察/反思）与 compaction 生命周期提交。
+* 导出 estimateTextTokens / isPairBalancedAfter / computeCompressRange / historySection /
+* reflectPass / observePass / maybeCompress。
 *
-* 压缩结果写入宿主 compaction/* 生命周期事件（compaction/start → compaction/summary →
-* 替换 <history> 消息 → compaction/end），使消息记录（聊天视图压缩卡片）与轨迹视图
-* 可见；compaction/summary 同时承担影子价格认领（shadowedTokenCount），不再单独发
-* compaction/prune。替换消息的 source 使用插件标识（plugin: 'dsh-plugin-om' +
-* compactionId），UI 据此关联 summary 与替换消息。compaction/start 在摘要调用前追加
-* （UI 压缩中提示行的开启标记，载荷带 phase 区分观察/反思）；摘要失败/无输出或提交
-* 失败时追加 compaction/end(error) 结束生命周期（失败不产生替换消息）。
-*
-* 观察区间：pre-step 触发时日志 call-result 完备，区间不再受 turn/end 封顶——压缩边界 →
-* 表层长度-1-tailCount（尾部保留 config.tailMessageCount 条不压缩），当前 turn 中已
-* 完备的消息同样可压缩；区间终点回退到 tool-call/result 配对平衡点（不切段）。
-* 摘要输出的 <history> 块经连续性校验（无 reasoning、index/start/end 连续且覆盖预期
-* 区间），失败按 config.compressRetryCount 重试。仅主会话生效。
+* - 反思：全部 <history> 块 token 合计 ≥ reflectThresholdTokens 时，摘要合并为一条
+* - 观察：净压力（上下文压力 − 已压缩块 token 合计）≥ observeThresholdTokens 时，
+*   摘要未压缩消息为新 <history> 块并精确替换被压缩区间（旧块保留）
+* - 两级在 pre-step 阻塞串行执行（先反思后观察）；仅主会话生效；omEnabled=false 关闭
+* - 压缩边界：最后一个合法 <history> 块之后的消息视为未压缩，其前不重复压缩
+* - 提交走宿主 compaction/* 生命周期事件（start 带 phase → summary → 替换消息 → end），
+*   失败补 end(error)；替换消息 source 标记插件标识供 UI 认领
 */
 /** 历史文本 token 估算：4 字符 ≈ 1 token（与宿主 dsh-token-meter 启发式一致）。 */
 function estimateTextTokens(text) {
 	return Math.ceil(text.length / 4);
 }
 /**
-* 按 token 边界把完整消息序列分块（观察并行压缩用）：完整消息不跨块——
-* 一条完整消息（含其 thinking/text/toolcall&result 全部 seqs）必然整体落在同一块，
-* 单条超界的消息独立成块。空输入返回空数组。
-*/
-function chunkCompleteMessages(session, cms, tokenBoundary, estimateMessage) {
-	if (cms.length === 0) return [];
-	/** 分块结果。 */
-	const chunks = [];
-	/** 当前块。 */
-	let current = [];
-	/** 当前块累计 token（按各完整消息 seqs 的派生消息估算合计）。 */
-	let currentTokens = 0;
-	for (const cm of cms) {
-		/** 当前完整消息的 token 估算（其全部表层 seqs 的派生消息估算之和）。 */
-		let cmTokens = 0;
-		for (const seq of cm.seqs) {
-			/** 表层事件（seq 缺失跳过）。 */
-			const event = session.events[seq];
-			/** 派生消息（用于 token 估算）。 */
-			const message = event ? session.deriveEventMessage(event) : null;
-			if (message) cmTokens += estimateMessage(message);
-		}
-		if (current.length > 0 && currentTokens + cmTokens > tokenBoundary) {
-			chunks.push(current);
-			current = [];
-			currentTokens = 0;
-		}
-		current.push(cm);
-		currentTokens += cmTokens;
-	}
-	if (current.length > 0) chunks.push(current);
-	return chunks;
-}
-/**
-* 合并分块摘要为单个 <history> 块：剥离各块的 <history> 开/闭标签（保留块内全部内容），
-* 以统一的开标签（带 tip 属性）与闭标签包裹拼接。块内内容原样保留（含格式说明注释）。
-*/
-function mergeChunkReports(parts) {
-	/** 各块内层内容（剥离外壳失败时原样保留该块文本）。 */
-	const inners = [];
-	for (const part of parts) {
-		/** 首个 <history 开标签位置。 */
-		const open = part.indexOf(`<${HISTORY_TAG}`);
-		/** 开标签右括号位置。 */
-		const gt = open === -1 ? -1 : part.indexOf(">", open);
-		/** 最后一个 </history> 闭标签位置。 */
-		const close = part.lastIndexOf(`</${HISTORY_TAG}>`);
-		if (open === -1 || gt === -1 || close === -1 || close <= gt) {
-			inners.push(part);
-			continue;
-		}
-		inners.push(part.slice(gt + 1, close));
-	}
-	return `<${HISTORY_TAG} tip="${HISTORY_TIP}">\n${inners.join("\n").trim()}\n</${HISTORY_TAG}>`;
-}
-/** 合并多块摘要的 token usage（同名数字字段求和；全部为空返回 undefined）。 */
-function mergeUsage(usages) {
-	if (usages.length === 0) return void 0;
-	/** 合并结果（必填字段从 0 起累加）。 */
-	const out = {
-		inputTokens: 0,
-		outputTokens: 0
-	};
-	for (const u of usages) {
-		out.inputTokens += u.inputTokens;
-		out.outputTokens += u.outputTokens;
-		if (u.cacheReadTokens !== void 0) out.cacheReadTokens = (out.cacheReadTokens ?? 0) + u.cacheReadTokens;
-		if (u.cacheWriteTokens !== void 0) out.cacheWriteTokens = (out.cacheWriteTokens ?? 0) + u.cacheWriteTokens;
-		if (u.reasoningTokens !== void 0) out.reasoningTokens = (out.reasoningTokens ?? 0) + u.reasoningTokens;
-	}
-	return out;
-}
-/**
 * 反思输入块引用的最大完整消息 index（解析全部条目取最大 end；无条目返回 -1）。
 * 反思输出必须覆盖输入引用的完整 index 区间（0..max），连续性校验据此约束。
 */
 function reflectExpectedEnd(contextText) {
-	/** 最大 end（无条目保持 -1）。 */
 	let max = -1;
 	for (const e of parseHistoryEntries(contextText)) {
-		/** 当前条目上界（模块 end 或单条 index）。 */
 		const hi = e.kind === "assistant" && e.end !== void 0 ? e.end : e.index ?? 0;
 		if (hi > max) max = hi;
 	}
 	return max;
 }
 /**
-* 判定消息是否为本插件的压缩日志消息并提取日志文本（不通过文本含标签判断，
-* 改用 source 标记——plugin 为插件标识 'dsh-plugin-om'（兼容旧日志的宿主 checkpoint
-* 标记 'compact'）。
-* 仅当消息文本含 <history> 开标签（含带 tip 属性版本）时视为压缩日志，返回整段文本；
-* 其余消息返回 undefined（旧格式 <om-history> 块按「不兼容，干净切换」视为普通消息）。
+* 判定消息是否为本插件的压缩日志消息并提取日志文本（按 source 标记判断，兼容旧宿主
+* checkpoint 标记 'compact'）。仅当消息文本含 <history> 开标签时视为压缩日志，返回整段
+* 文本；其余返回 undefined。
 */
 function historyTextOf(event) {
 	if (event?.type !== "user/message") return void 0;
-	/** 消息 source（本插件自产消息的标记；含兼容旧宿主 checkpoint 标记）。 */
 	const source = event.data.source;
 	if (!isPluginOwnedSource(source)) return void 0;
-	/** 消息纯文本。 */
 	const text = blocksToText(event.data.content);
-	/** 首个 <history 出现位置（无则非压缩日志）。 */
 	const idx = text.indexOf(`<${HISTORY_TAG}`);
 	if (idx === -1) return void 0;
-	/** 开标签校验：<history> 或 <history tip=…>（排除 </history> 等）。 */
 	const rest = text.slice(idx + 7 + 1);
 	if (!rest.startsWith(">") && !rest.startsWith(" tip=")) return void 0;
 	return text;
 }
 /** 提取 <history> 块内文（去掉开/闭标签与首尾空白；非块文本原样返回）。 */
 function historyInnerText(text) {
-	/** 闭标签。 */
 	const closeTag = `</${HISTORY_TAG}>`;
 	const close = text.lastIndexOf(closeTag);
 	if (close === -1) return text;
@@ -8020,44 +7983,12 @@ function historyInnerText(text) {
 	return text.slice(gt + 1, close).trim();
 }
 /**
-* 未压缩消息 token 估算：最后一个 <history> 块之后的表层节点合计
-* （其前含自身视为已压缩，不计入观察阈值衡量对象；无压缩日志时计全部）。
-* 系统消息（user/message 中非 kind:user 的部分，如宿主注入的上下文）不计入阈值。
-*/
-function measureUncompressedTokens(session, meter) {
-	/** 压缩边界（最后一个 history 块的 seq；无则 undefined）。 */
-	const { boundarySeq } = historySection(session);
-	/** token 合计。 */
-	let total = 0;
-	/** 是否已越过压缩边界（开始计入）。 */
-	let measuring = boundarySeq === void 0;
-	for (const seq of session.surface.nodes) {
-		if (!measuring) {
-			if (seq === boundarySeq) measuring = true;
-			continue;
-		}
-		/** 事件对应的消息（用于 token 估算）。 */
-		const event = session.events[seq];
-		const message = event ? session.deriveEventMessage(event) : null;
-		if (!message) continue;
-		if (event?.type === "user/message") {
-			if (event.data.source?.kind !== "user") continue;
-		}
-		total += meter.estimateMessage(message);
-	}
-	return total;
-}
-/**
-* 判定表层节点 seq 之后的切点是否 tool-call/result 配对平衡（与宿主
-* dsh-compaction 的 toolPairingBalancedAfter 同语义）：按表层顺序折叠未闭合的
-* 工具调用数，处理到 seq 后计数为 0 即平衡。pre-step 时日志 call-result 完备，
-* 该检查作为区间边界的安全网（防止把助手 tool-call 与其结果切到两侧）。
+* 判定表层节点 seq 之后的切点是否 tool-call/result 配对平衡：按表层顺序折叠未闭合的
+* 工具调用数，处理到 seq 后计数为 0 即平衡（防止把 tool-call 与其结果切到两侧）。
 */
 function isPairBalancedAfter(session, seq) {
-	/** 未闭合工具调用计数。 */
 	let inProgress = 0;
 	for (const node of session.surface.nodes) {
-		/** 当前表层事件。 */
 		const event = session.events[node];
 		if (event?.type === "assistant/message") inProgress += event.data.message.content.filter((block) => block.type === "tool-call").length;
 		else if (event?.type === "tool/result") inProgress -= 1;
@@ -8066,35 +7997,25 @@ function isPairBalancedAfter(session, seq) {
 	return false;
 }
 /**
-* 观察压缩区间：pre-step 触发时日志 call-result 完备，区间不再受 turn/end 封顶——
-* 头部 → 表层长度-1-tailCount（尾部保留 tailCount 条不压缩），当前 turn 中已完备的
-* 消息同样可压缩；区间终点回退到 tool-call/result 配对平衡点（不切段）。
+* 观察压缩区间：压缩边界后的首个表层节点 → 表层长度-1-tailCount（尾部保留 tailCount
+* 条不压缩）；区间终点回退到 tool-call/result 配对平衡点（不切段）。无可行区间返回
+* undefined。返回区间起止表层 seq 与被遮蔽 seq 列表。
 */
 function computeCompressRange(session, tailCount) {
-	/** 当前表层节点（按日志顺序）。 */
 	const surface = [...session.surface.nodes];
 	if (surface.length === 0) return void 0;
-	/** 压缩边界（最后一个 <history> 块；其前含自身已压缩，起点在其后）。 */
 	const { boundarySeq } = historySection(session);
-	/** 区间起点表层下标：无压缩日志时为 0；否则为压缩边界（最后一个 history 块）在表层
-	*  （消息日志顺序）中的后继第一条消息。注意不能按 seq 比较取「边界之后」——替换块是
-	*  追加到日志末尾的，其 seq 大于被遮蔽的消息；表层顺序才是消息的逻辑日志顺序。 */
 	const startIdx = boundarySeq === void 0 ? 0 : surface.indexOf(boundarySeq) + 1;
 	if (startIdx >= surface.length) return void 0;
-	/** 区间末表层节点下标（尾部保留 tailCount 条不压缩）。 */
 	let endIdx = surface.length - 1 - tailCount;
 	if (endIdx < startIdx) return void 0;
-	/** 区间终点回退到配对平衡点（不切断 tool-call/result 配对）。 */
 	while (endIdx >= startIdx) {
-		/** 当前候选终点节点（表层节点序列稠密，防御性判空）。 */
 		const node = surface[endIdx];
 		if (node === void 0 || isPairBalancedAfter(session, node)) break;
 		endIdx -= 1;
 	}
 	if (endIdx < startIdx) return void 0;
-	/** 区间起点（压缩边界后的首个节点）。 */
 	const start = surface[startIdx];
-	/** 区间终点（表层节点 seq）。 */
 	const end = surface[endIdx];
 	if (start === void 0 || end === void 0) return void 0;
 	return {
@@ -8105,17 +8026,14 @@ function computeCompressRange(session, tailCount) {
 }
 /**
 * 压缩边界（historySection）：扫描表层全部节点，收集所有合法 <history> 压缩日志块
-* （内文 + seq，按表层顺序），并以最后一个块的 seq 作为压缩边界——
-* 边界之后的消息视为未压缩；其前（含边界自身）视为已压缩（不重复压缩、不计入观察阈值）。
-* 无压缩日志时 blocks 为空、boundarySeq 为 undefined（全部视为未压缩）。
+* （内文 + seq，按表层顺序），并以最后一个块的 seq 作为压缩边界——边界之后的消息视为
+* 未压缩，其前（含边界自身）视为已压缩。无压缩日志时 blocks 为空、boundarySeq 为
+* undefined。
 */
 function historySection(session) {
-	/** 收集结果（按表层顺序）。 */
 	const blocks = [];
-	/** 最后一个压缩日志块的 seq（无则 undefined）。 */
 	let boundarySeq;
 	for (const seq of session.surface.nodes) {
-		/** <history> 内文（非压缩日志消息时为 undefined）。 */
 		const text = historyTextOf(session.events[seq]);
 		if (text === void 0) continue;
 		blocks.push({
@@ -8129,9 +8047,8 @@ function historySection(session) {
 		boundarySeq
 	};
 }
-/** 当前打开中的 turn 号（最近 turn/start 且未被 turn/end 关闭）；无则 null（跨轮次场景）。 */
+/** 当前打开中的 turn 号（最近 turn/start 且未被 turn/end 关闭）；无则 null。 */
 function openTurnOf(session) {
-	/** 折叠结果（turn/start 打开、turn/end 关闭）。 */
 	let turn = null;
 	for (const event of session.events) if (event.type === "turn/start") turn = event.data.turn;
 	else if (event.type === "turn/end") turn = null;
@@ -8141,9 +8058,8 @@ function openTurnOf(session) {
 function newCompactionId() {
 	return uuid();
 }
-/** 追加 compaction/start（log-only：仅标记生命周期开始，不进入表层），返回事件 seq。 */
+/** 追加 compaction/start（log-only；载荷带 phase 区分观察/反思），返回事件 seq。 */
 function appendCompactionStart(session, lifecycle, phase) {
-	/** start 事件载荷（宿主类型 + 插件扩展 phase；宿主 append 不做 schema 剥离，扩展字段原样持久化）。 */
 	const payload = {
 		compactionId: lifecycle.compactionId,
 		turn: lifecycle.turn,
@@ -8156,7 +8072,6 @@ function appendCompactionStart(session, lifecycle, phase) {
 * summary 为完整合并后的 <history> 内文；usage 由摘要调用提取（无则省略）。
 */
 function appendCompactionSummary(session, data) {
-	/** summary 事件载荷（宿主类型 + 插件扩展 shadowedCharCount/attemptCount；宿主 append 不做 schema 剥离，扩展字段原样持久化）。 */
 	const payload = {
 		compactionId: data.lifecycle.compactionId,
 		summary: [{
@@ -8183,10 +8098,8 @@ function appendCompactionEnd(session, lifecycle, error) {
 		...error === void 0 ? {} : { error }
 	}).seq;
 }
-/** 追加 <history> 压缩日志消息（surfaceOp 替换遮蔽区间，source 标记插件自产 + compactionId 关联压缩生命周期）。 */
+/** 追加 <history> 压缩日志消息（surfaceOp 替换遮蔽区间，source 标记插件自产 + compactionId）。 */
 function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp, compactionId) {
-	/** 压缩替换消息（内容即 <history> 标签块，不再附加前缀句；对 AI 的提醒在块开标签 tip 属性上；
-	*  source 标记插件标识（plugin: 'dsh-plugin-om'）+ compactionId 供 UI 关联）。 */
 	const message = {
 		id: uuid(),
 		role: "user",
@@ -8206,49 +8119,36 @@ function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp, comp
 	});
 }
 /**
-* 反思：全部 <history> 块 tokens 合计 ≥ reflectThresholdTokens 时，摘要调用
-* 精简合并（多个块拼接为输入，与观察共用同一套提示词），把整个块区段替换为一条
-* 更紧凑的摘要。失败不产生部分替换。
+* 反思：全部 <history> 块 token 合计 ≥ reflectThresholdTokens 时，摘要调用把整个块
+* 区段合并替换为一条更紧凑的摘要。失败不产生部分替换。
 */
 async function reflectPass(ctx, agent, config, target, signal) {
-	/** 当前会话。 */
 	const session = agent.session;
-	/** 插件日志门面。 */
 	const logger = makeLogger(ctx, config.debug);
 	logger.step(`反思检查（反思阈值 ${config.reflectThresholdTokens} tokens）`);
-	/** 全部 <history> 压缩日志块（按表层顺序；无则跳过）。 */
 	const { blocks } = historySection(session);
 	if (blocks.length === 0) {
 		logger.step("反思：无 <history> 压缩日志，跳过");
 		return;
 	}
-	/** 反思阈值（配置的绝对 token 数）。 */
 	const threshold = config.reflectThresholdTokens;
-	/** 全部块 token 估算合计（摘要总长）。 */
 	const tokens = blocks.reduce((total, block) => total + estimateTextTokens(block.text), 0);
-	/** 被压缩块区段的字符数合计（压缩前内文长度；UI 标题统计用，与观察路径一致只计内容不计标签）。 */
 	const shadowedCharCount = blocks.reduce((total, block) => total + historyInnerText(block.text).length, 0);
 	if (tokens < threshold) {
 		logger.step(`反思：摘要 ${tokens} tokens < 阈值 ${threshold}，跳过`);
 		return;
 	}
 	logger.step(`反思：摘要 ${tokens} tokens ≥ 阈值 ${threshold}，触发精简合并（${blocks.length} 个块）`);
-	/** 块区段首尾（historySection 只收集表层节点，天然在表层）。 */
 	const first = blocks[0];
 	const last = blocks[blocks.length - 1];
 	if (first === void 0 || last === void 0) {
 		logger.step("反思：块区段缺失，跳过");
 		return;
 	}
-	/** 被替换块区段的 seq 列表。 */
 	const blockSeqs = blocks.map((block) => block.seq);
-	/** 共享提示词（观察/反思同一套）。 */
 	const instruction = buildHistoryPrompt();
-	/** 渲染输入（全部 <history> 块拼接）。 */
 	const contextText = blocks.map((block) => block.text).join("\n");
-	/** 反思输出应覆盖输入块引用的全部 index（解析输入条目取最大 end；无条目则只校验起点）。 */
 	const expectedEnd = reflectExpectedEnd(contextText);
-	/** 本次压缩生命周期（compactionId + 当前轮次；start 在摘要调用前开启，UI 压缩中提示）。 */
 	const lifecycle = {
 		compactionId: newCompactionId(),
 		turn: openTurnOf(session)
@@ -8257,18 +8157,17 @@ async function reflectPass(ctx, agent, config, target, signal) {
 		logger.step("反思：追加 compaction/start（摘要调用前开启压缩中提示）");
 		appendCompactionStart(session, lifecycle, "reflect");
 	} catch (error) {
-		/** 启动失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
 		logger.warn(`反思压缩启动失败: ${message}`);
 		return;
 	}
-	/** 反思摘要结果（null 表示失败/跳过）。 */
 	const summaryResult = await runSummarySubagent(ctx, agent, instruction, contextText, config.compressMaxTokens, target, config.debug, signal, {
 		maxAttempts: config.compressRetryCount + 1,
 		expected: expectedEnd < 0 ? { start: 0 } : {
 			start: 0,
 			end: expectedEnd
-		}
+		},
+		rateLimitWaitMs: config.rateLimitWaitMs
 	});
 	if (summaryResult === null || summaryResult.text.trim().length === 0) {
 		logger.step("反思：摘要调用失败/无输出，追加 compaction/end(error)");
@@ -8277,11 +8176,9 @@ async function reflectPass(ctx, agent, config, target, signal) {
 		} catch {}
 		return;
 	}
-	/** 反思摘要文本。 */
 	const report = summaryResult.text;
 	try {
 		logger.step("反思提交：追加 compaction/summary（影子价格认领）");
-		/** compaction/summary 事件 seq（承担影子价格认领，紧随其后的替换消息消费）。 */
 		const summarySeq = appendCompactionSummary(session, {
 			lifecycle,
 			summary: report,
@@ -8308,7 +8205,6 @@ async function reflectPass(ctx, agent, config, target, signal) {
 		appendCompactionEnd(session, lifecycle);
 		logger.info(`反思完成（摘要 ${tokens} tokens ≥ 阈值 ${threshold}，合并 ${blocks.length} 个块为一条）`);
 	} catch (error) {
-		/** 提交失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
 		logger.warn(`反思提交失败: ${message}`);
 		try {
@@ -8317,57 +8213,47 @@ async function reflectPass(ctx, agent, config, target, signal) {
 	}
 }
 /**
-* 观察：未压缩消息 tokens ≥ observeThresholdTokens 时，摘要调用把未压缩消息压缩为
-* 观察日志，追加到旧摘要并替换被压缩消息区间。失败不产生部分替换。
+* 观察：净压力 tokens（上下文压力 − 已压缩 <history> 块 token 合计）≥
+* observeThresholdTokens 时，摘要调用把未压缩消息压缩为观察日志，追加到旧摘要并
+* 替换被压缩消息区间。失败不产生部分替换。
 */
 async function observePass(ctx, agent, config, tailCount, target, signal) {
-	/** 当前会话。 */
 	const session = agent.session;
-	/** 插件日志门面。 */
 	const logger = makeLogger(ctx, config.debug);
 	logger.step(`观察检查（观察阈值 ${config.observeThresholdTokens} tokens，尾部保留 ${tailCount} 条）`);
-	/** 观察阈值（配置的绝对 token 数）。 */
 	const threshold = config.observeThresholdTokens;
-	/** 未压缩消息 token 估算（最后一个 <history> 块之后；其前视为已压缩）。 */
-	const uncompressedTokens = measureUncompressedTokens(session, ctx.tokenMeter);
-	if (uncompressedTokens < threshold) {
-		logger.step(`观察：未压缩消息 ${uncompressedTokens} tokens < 阈值 ${threshold}，跳过`);
+	const pressureTokens = ctx.tokenMeter.measure(session).totalTokens;
+	const { blocks } = historySection(session);
+	const historyTokens = blocks.reduce((total, block) => total + estimateTextTokens(block.text), 0);
+	const netTokens = pressureTokens - historyTokens;
+	if (netTokens < threshold) {
+		logger.step(`观察：净压力 ${netTokens} tokens（上下文压力 ${pressureTokens} − 已压缩块 ${historyTokens}）< 阈值 ${threshold}，跳过`);
 		return;
 	}
-	logger.step(`观察：未压缩消息 ${uncompressedTokens} tokens ≥ 阈值 ${threshold}，触发压缩`);
-	/** 观察压缩区间（压缩边界之后；尾部保留 tailCount 条不压缩；无可行区间则跳过）。 */
+	logger.step(`观察：净压力 ${netTokens} tokens（上下文压力 ${pressureTokens} − 已压缩块 ${historyTokens}）≥ 阈值 ${threshold}，触发压缩`);
 	const range = computeCompressRange(session, tailCount);
 	if (!range) {
 		logger.step("观察：无可行压缩区间（边界后消息过短或配对无法平衡），跳过");
 		return;
 	}
 	logger.step(`观察：压缩区间 [${range.start}..${range.end}]，遮蔽 ${range.shadowedSeqs.length} 个表层节点`);
-	/** 旧压缩日志块（保留不替换、不进新消息遮蔽）。 */
-	const { blocks } = historySection(session);
-	/** 实际被替换的新消息表层节点（压缩边界之后；旧块不进入遮蔽、不被重写）。 */
 	const replaceSeqs = range.shadowedSeqs;
-	/** 替换区间起点（首个新消息节点；区间内全部为块时无新消息可压缩）。 */
 	const replaceStart = replaceSeqs[0];
 	if (replaceStart === void 0) {
 		logger.step("观察：区间内无新消息（全部为压缩日志块），跳过");
 		return;
 	}
-	/** 被替换 seq 集合（计算新消息 index 覆盖区间）。 */
 	const shadowedSet = new Set(replaceSeqs);
-	/** 压缩区间内的完整消息（连续性校验的预期覆盖区间）。 */
 	const inRangeCms = indexCompleteMessages(session).filter((cm) => cm.seqs.every((seq) => shadowedSet.has(seq)));
 	if (inRangeCms.length === 0) {
 		logger.step("观察：区间内无完整消息，跳过");
 		return;
 	}
-	/** 新消息起始/结束完整消息 index（模型输入携带绝对 index，校验按此区间约束）。 */
 	const startIndex = inRangeCms[0]?.index ?? 0;
 	const endIndex = inRangeCms[inRangeCms.length - 1]?.index ?? startIndex;
 	logger.step(`观察：保留旧块 ${blocks.length} 条，替换新消息 [${replaceSeqs[0]}..${range.end}]（${replaceSeqs.length} 条），尾部保留 ${tailCount} 条（不压缩、不进日志），新消息 index ${startIndex}..${endIndex}`);
-	/** 按 observeChunkTokens 边界把完整消息分块（完整消息不跨块；每块独立并行压缩）。 */
-	const chunks = chunkCompleteMessages(session, inRangeCms, config.observeChunkTokens, (message) => ctx.tokenMeter.estimateMessage(message));
-	logger.step(`观察：${inRangeCms.length} 条完整消息按 ${config.observeChunkTokens} tokens 边界分为 ${chunks.length} 块（每块摘要 maxTokens ${config.observeChunkMaxTokens}，除最后一块外要求简单摘要）`);
-	/** 本次压缩生命周期（compactionId + 当前轮次；start 在摘要调用前开启，UI 压缩中提示）。 */
+	const instruction = buildHistoryPrompt();
+	const contextText = renderMessages(session, replaceSeqs);
 	const lifecycle = {
 		compactionId: newCompactionId(),
 		turn: openTurnOf(session)
@@ -8376,62 +8262,40 @@ async function observePass(ctx, agent, config, tailCount, target, signal) {
 		logger.step("观察：追加 compaction/start（摘要调用前开启压缩中提示）");
 		appendCompactionStart(session, lifecycle, "observe");
 	} catch (error) {
-		/** 启动失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
 		logger.warn(`观察压缩启动失败: ${message}`);
 		return;
 	}
-	/** 各块摘要结果（Promise.all 并行；null = 该块失败）。 */
-	const chunkResults = await Promise.all(chunks.map(async (chunk, index) => {
-		/** 该块提示词（较早块简单摘要；最后一块越往后越细）。 */
-		const instruction = buildHistoryPrompt(index === chunks.length - 1 ? "detailed" : "summary");
-		/** 该块渲染输入（块内完整消息的 seqs；合法 <history> 块，含绝对 index）。 */
-		const contextText = renderMessages(session, chunk.flatMap((cm) => cm.seqs));
-		/** 该块覆盖的完整消息 index 区间（连续性校验预期）。 */
-		const start = chunk[0]?.index ?? 0;
-		const end = chunk[chunk.length - 1]?.index ?? start;
-		return runSummarySubagent(ctx, agent, instruction, contextText, config.observeChunkMaxTokens, target, config.debug, signal, {
-			maxAttempts: config.compressRetryCount + 1,
-			expected: {
-				start,
-				end
-			}
-		});
-	}));
-	if (chunkResults.find((r) => r === null || r.text.trim().length === 0) !== void 0) {
-		logger.step("观察：分块摘要存在失败/无输出，不产生部分替换，追加 compaction/end(error)");
+	const summaryResult = await runSummarySubagent(ctx, agent, instruction, contextText, config.compressMaxTokens, target, config.debug, signal, {
+		maxAttempts: config.compressRetryCount + 1,
+		expected: {
+			start: startIndex,
+			end: endIndex
+		},
+		rateLimitWaitMs: config.rateLimitWaitMs
+	});
+	if (summaryResult === null || summaryResult.text.trim().length === 0) {
+		logger.step("观察：摘要调用失败/无输出，追加 compaction/end(error)");
 		try {
 			appendCompactionEnd(session, lifecycle, "摘要调用失败/无输出");
 		} catch {}
 		return;
 	}
-	/** 成功结果（上方已排除 null/空输出；每块已独立校验并规范化）。 */
-	const okResults = chunkResults;
-	/** 合并各块摘要为单个带 tip 的 <history> 块（剥离各块外壳拼接内层；不再整体校验）。 */
-	const report = mergeChunkReports(okResults.map((r) => r.text));
-	/** 重试次数合计（各块重试次数之和；每块重试次数 = 该块成功尝试次数 - 1）。 */
-	const attemptCount = okResults.reduce((sum, r) => sum + (r.attemptCount - 1), 0);
-	/** token usage 合计（各块求和；全部缺省为 undefined）。 */
-	const usage = mergeUsage(okResults.map((r) => r.usage).filter((u) => u !== void 0));
-	/** 被替换表层节点的 token 估算合计（仅新消息区间）。 */
+	const report = summaryResult.text;
+	const attemptCount = summaryResult.attemptCount - 1;
+	const usage = summaryResult.usage;
 	const shadowedTokenCount = replaceSeqs.reduce((total, seq) => {
-		/** 当前表层事件。 */
 		const event = session.events[seq];
-		/** 事件对应的消息（用于 token 估算）。 */
 		const message = event ? session.deriveEventMessage(event) : null;
 		return total + (message ? ctx.tokenMeter.estimateMessage(message) : 0);
 	}, 0);
-	/** 被替换消息的字符数合计（压缩前文本长度；UI 标题统计用，递归计入 tool-result 内嵌文本）。 */
 	const shadowedCharCount = replaceSeqs.reduce((total, seq) => {
-		/** 当前表层事件。 */
 		const event = session.events[seq];
-		/** 事件对应的消息（取文本块字符数）。 */
 		const message = event ? session.deriveEventMessage(event) : null;
 		return total + (message ? textCharCount(message) : 0);
 	}, 0);
 	try {
 		logger.step("观察提交：追加 compaction/summary（影子价格认领）");
-		/** compaction/summary 事件 seq（承担影子价格认领，紧随其后的替换消息消费）。 */
 		const summarySeq = appendCompactionSummary(session, {
 			lifecycle,
 			summary: report,
@@ -8444,7 +8308,7 @@ async function observePass(ctx, agent, config, tailCount, target, signal) {
 			shadowedCharCount,
 			provider: target.provider,
 			model: target.model,
-			maxTokens: config.observeChunkMaxTokens,
+			maxTokens: config.compressMaxTokens,
 			attemptCount,
 			...usage === void 0 ? {} : { usage }
 		});
@@ -8456,9 +8320,8 @@ async function observePass(ctx, agent, config, tailCount, target, signal) {
 		}, lifecycle.compactionId);
 		logger.step("观察提交：追加 compaction/end");
 		appendCompactionEnd(session, lifecycle);
-		logger.info(`观察压缩完成（未压缩 ${uncompressedTokens} tokens ≥ 阈值 ${threshold}，替换 ${replaceSeqs.length} 个表层节点，约 ${shadowedTokenCount} tokens）`);
+		logger.info(`观察压缩完成（净压力 ${netTokens} tokens（上下文压力 ${pressureTokens} − 已压缩块 ${historyTokens}）≥ 阈值 ${threshold}，替换 ${replaceSeqs.length} 个表层节点，约 ${shadowedTokenCount} tokens）`);
 	} catch (error) {
-		/** 提交失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
 		logger.warn(`观察压缩提交失败: ${message}`);
 		try {
@@ -8466,28 +8329,20 @@ async function observePass(ctx, agent, config, tailCount, target, signal) {
 		} catch {}
 	}
 }
-/**
-* 压力检查 + 两级压缩：先反思（压缩过往摘要，有必要才做），后观察（压缩新消息，
-* 有必要才做）。在 pre-step 阻塞串行执行（避免压缩失败或重复压缩）。仅主会话生效。
-*/
+/** 压力检查 + 两级压缩入口：先反思后观察，pre-step 阻塞串行执行；仅主会话生效。 */
 async function maybeCompress(ctx, agent, config, signal) {
-	/** 当前会话。 */
 	const session = agent.session;
-	/** 插件日志门面。 */
 	const logger = makeLogger(ctx, config.debug);
-	/** omEnabled=false：关闭自动压缩（观察/反思均不触发，recall 工具不受影响）。 */
 	if (!config.omEnabled) {
 		logger.step("omEnabled=false，跳过压缩");
 		return;
 	}
-	/** 会话路由目标（未路由无法查询容量）。 */
 	const target = routedTarget(session);
 	if (target === void 0) {
 		logger.step("会话未路由（无 provider/model），跳过压缩");
 		return;
 	}
 	logger.step(`会话路由：provider ${target.provider}，model ${target.model}`);
-	/** 尾部保留条数（config.tailMessageCount，缺省 10）。 */
 	const tailCount = config.tailMessageCount;
 	logger.step("反思 pass 开始");
 	await reflectPass(ctx, agent, config, target, signal);
@@ -8498,26 +8353,19 @@ async function maybeCompress(ctx, agent, config, signal) {
 //#endregion
 //#region src/model-download.ts
 /**
-* 嵌入模型下载：recall-semantic 运行时按需下载 + 开发手动预下载共用。
-*
-* - 模型：Xenova/paraphrase-multilingual-MiniLM-L12-v2（量化 ONNX ~113MB，超过
-*   GitHub 单文件 100MB 限制，不能进入 git 仓库；仅小文件随仓库提交）。
-* - 下载目标：<modelDir>/onnx/model_quantized.onnx（modelDir 默认 = 跨版本共享目录
-*   $DSH_HOME/plugin-data/dsh-plugin-om/models/<id>/，见 embedding.ts 的 sharedModelDir；
-*   自定义 modelDir 同样生效）。
-* - 直连 huggingface.co 受限时设置环境变量 HF_ENDPOINT=https://hf-mirror.com 走镜像。
-* - 原子落盘：先写 .tmp 再改名，避免半截文件被当成完整模型加载。
-* - 日志：下载开始/结束（含跳过）经 log 回调输出（默认 console.log）；失败时
-*   错误消息附带 HF_ENDPOINT=https://hf-mirror.com 镜像建议。
-*
-* 运行时编排见 embedding.ts 的 ensureModelReady（下载单飞、未就绪不阻塞）；
-* 本模块只提供纯下载原语（供 src 与 scripts/download-model.mjs CLI 复用）。
+* 嵌入模型下载原语：recall-semantic 运行时按需下载与开发手动预下载（scripts/
+* download-model.mjs）共用。导出 EMBEDDING_MODEL_ID / ONNX_REL / MODEL_SMALL_FILES /
+* modelSourceUrl / modelTargetPath / needsDownload / downloadModel 及 DownloadResult /
+* ModelFetch 类型。
+* 模型为量化 ONNX（~113MB，不进 git，仅小文件随仓库/包分发）；下载目标
+* <modelDir>/onnx/model_quantized.onnx；直连受限时设置 HF_ENDPOINT 走镜像；
+* 原子落盘（先写 .tmp 再改名）。运行时编排见 embedding.ts 的 ensureModelReady。
 */
 /** 模型标识（models/ 下目录名 = 模型 id；transformers.js 加载时的模型名）。 */
 const EMBEDDING_MODEL_ID = "paraphrase-multilingual-MiniLM-L12-v2";
-/** transformers.js 转换仓库（Xenova org）中量化 ONNX 文件的相对路径（相对模型目录）。 */
+/** 量化 ONNX 文件的相对路径（相对模型目录）。 */
 const ONNX_REL = "onnx/model_quantized.onnx";
-/** 随 npm 包分发的小模型文件（相对模型目录；onnx 二进制不随包分发，见 tests/package-pack.test.ts）。 */
+/** 随 npm 包分发的小模型文件（相对模型目录；onnx 二进制不随包分发）。 */
 const MODEL_SMALL_FILES = [
 	"config.json",
 	"special_tokens_map.json",
@@ -8526,19 +8374,16 @@ const MODEL_SMALL_FILES = [
 ];
 /**
 * HuggingFace 原始文件 URL（resolve 会 302 到 CDN，fetch 自动跟随重定向）。
-* base 默认 huggingface.co，可用环境变量 HF_ENDPOINT 覆盖（直连受限时改用镜像，如 https://hf-mirror.com）。
+* base 可用环境变量 HF_ENDPOINT 覆盖（直连受限时改用镜像，如 https://hf-mirror.com）。
 */
 function modelSourceUrl(id = EMBEDDING_MODEL_ID, rel = ONNX_REL, base = process.env.HF_ENDPOINT || "https://huggingface.co") {
 	return `${base}/Xenova/${id}/resolve/main/${rel}`;
 }
-/** 本地目标文件绝对路径（<modelDir>/<rel>，缺省 <modelDir>/onnx/model_quantized.onnx）。 */
+/** 本地目标文件绝对路径（<modelDir>/<rel>）。 */
 function modelTargetPath(modelDir, rel = ONNX_REL) {
 	return path.join(modelDir, rel);
 }
-/**
-* 是否需要下载（纯函数，供测试）。
-* force 强制下载；否则目标已存在即跳过。
-*/
+/** 是否需要下载：force 强制；否则目标已存在即跳过。 */
 function needsDownload(target, { force = false } = {}) {
 	if (force) return true;
 	try {
@@ -8550,8 +8395,7 @@ function needsDownload(target, { force = false } = {}) {
 }
 /**
 * 下载模型到 <modelDir>/onnx/model_quantized.onnx。
-* 开始/结束（含跳过）经 log 回调输出（默认 console.log）；失败时清理临时文件，
-* 并在错误消息中附带镜像建议（直连受限时设置 HF_ENDPOINT=https://hf-mirror.com）。
+* 开始/结束（含跳过）经 log 回调输出；失败时清理临时文件并在错误消息中附带镜像建议。
 * 可注入 fetchImpl / log（供测试）。
 */
 async function downloadModel(modelDir, { force = false, fetchImpl = fetch, log = console.log } = {}) {
@@ -8589,44 +8433,34 @@ async function downloadModel(modelDir, { force = false, fetchImpl = fetch, log =
 //#endregion
 //#region src/embedding.ts
 /**
-* 本地语义嵌入（recall-semantic 的向量引擎）。
-*
-* - 模型：Xenova/paraphrase-multilingual-MiniLM-L12-v2（量化 ONNX，多语言，
-*   中英 + 代码均可处理）。模型目录默认 = $DSH_HOME/plugin-data/dsh-plugin-om/
-*   models/<模型id>/（跨插件版本共享）：随包小文件（config/tokenizer 等）缺失时
-*   从打包目录复制补齐（离线可用），onnx 二进制按需下载。
-* - 运行时下载：模型 onnx 缺失时由 ensureModelReady 后台下载（不阻塞、单飞、
-*   失败自动重试），下载逻辑见 model-download.ts；就绪前工具告知模型。
-* - 懒加载：首次调用才 `import('@huggingface/transformers')` 并加载 pipeline，
-*   插件启动不阻塞；加载结果单例缓存（resetEmbedder 供测试重置）。
-* - 批处理：一次推理多条文本（mean pooling + L2 归一化），输出每条的向量。
-* - 相似度：cosineSimilarity 纯函数（归一化向量点积即余弦）。
-*
-* 依赖说明：@huggingface/transformers 为运行时依赖（v4，dtype q8 加载
-* model_quantized.onnx），node 侧使用 onnxruntime-node 原生绑定。
+* 本地语义嵌入（recall-semantic 的向量引擎）：Xenova/paraphrase-multilingual-MiniLM-L12-v2
+* 量化 ONNX，懒加载 + 批量推理 + cosine 相似度，模型缺失时按需后台下载。
+* 导出 BUNDLED_MODEL_DIR / EMBEDDING_MODEL_ID / resolveDshHome / sharedModelDir /
+* ensureModelSmallFiles / getEmbedder / resetEmbedder / ensureModelReady /
+* resetModelDownloads / cosineSimilarity 及 EmbedFn / ModelStatus 类型。
+* 模型目录默认为跨版本共享目录（$DSH_HOME/plugin-data/dsh-plugin-om/models/<id>）：
+* 随包小文件缺失时从打包目录复制补齐（离线可用），onnx 二进制按需下载
+* （见 model-download.ts）。@huggingface/transformers 为运行时依赖（dtype q8 加载
+* model_quantized.onnx，node 侧使用 onnxruntime-node 原生绑定）。
 */
 /** 当前模块所在路径（dist/ 或 src/，models 在其上一级）。 */
 const here = path.dirname(fileURLToPath(import.meta.url));
 /** 打包模型目录：<包根>/models/<model-id>/。 */
 const BUNDLED_MODEL_DIR = path.join(here, "..", "models", EMBEDDING_MODEL_ID);
-/** DSH 用户数据根目录：$DSH_HOME 优先（空白视为未设置），缺省 ~/.dsh（与宿主解析规则一致）。 */
+/** DSH 用户数据根目录：$DSH_HOME 优先（空白视为未设置），缺省 ~/.dsh。 */
 function resolveDshHome() {
 	const fromEnv = process.env.DSH_HOME;
 	if (fromEnv !== void 0 && fromEnv.trim().length > 0) return path.resolve(fromEnv);
 	return path.join(homedir(), ".dsh");
 }
-/**
-* 跨插件版本共享的默认模型目录：$DSH_HOME/plugin-data/dsh-plugin-om/models/<模型id>。
-* 不随插件包（版本）变化，升级/重装插件后仍复用同一份已下载模型（onnx 不重复下载）。
-*/
+/** 跨插件版本共享的默认模型目录：$DSH_HOME/plugin-data/dsh-plugin-om/models/<模型id>。 */
 function sharedModelDir() {
 	return path.join(resolveDshHome(), "plugin-data", "dsh-plugin-om", "models", EMBEDDING_MODEL_ID);
 }
 /**
-* 补齐模型目录的随包小文件（config/tokenizer 等）：modelDir 与打包目录不同
-* （如共享目录）时，把打包目录中缺失的小文件复制过去，保证模型可离线加载。
-* 已存在的文件不覆盖（同一模型文件跨版本稳定）；打包目录本身缺失则跳过。
-* 幂等、无网络。onnx 二进制不在此列（按需下载，见 model-download.ts）。
+* 补齐模型目录的随包小文件（config/tokenizer 等）：modelDir 与打包目录不同时，
+* 把打包目录中缺失的小文件复制过去（已存在不覆盖；打包目录缺失则跳过）。
+* 幂等、无网络；onnx 二进制不在此列。
 */
 function ensureModelSmallFiles(modelDir, bundledDir = BUNDLED_MODEL_DIR) {
 	if (path.resolve(modelDir) === path.resolve(bundledDir)) return;
@@ -8643,7 +8477,7 @@ const BATCH_SIZE = 32;
 /** 懒加载中的 pipeline 单例（null = 尚未加载/已重置）。 */
 let pipelinePromise = null;
 /**
-* 获取（或加载）嵌入函数。首次调用动态 import transformers 并加载本地模型；
+* 获取（或加载）嵌入函数。首次调用动态 import transformers 并加载本地模型，
 * 之后复用同一 pipeline。失败时抛出可读错误（调用方自行降级）。
 */
 function getEmbedder(modelDir = BUNDLED_MODEL_DIR) {
@@ -8663,7 +8497,6 @@ function getEmbedder(modelDir = BUNDLED_MODEL_DIR) {
 					pooling: "mean",
 					normalize: true
 				});
-				/** 结果张量：dims = [batch, hidden]，data 为扁平数组。 */
 				const dims = result.dims;
 				const hidden = dims.length > 1 ? dims[1] : 0;
 				const data = result.data;
@@ -8681,12 +8514,8 @@ function getEmbedder(modelDir = BUNDLED_MODEL_DIR) {
 const inflightDownloads = /* @__PURE__ */ new Map();
 /**
 * 确保模型就绪（运行时按需下载编排）。
-* - 本地 onnx 已存在 → 'ready'（不触发下载）。
-* - 缺失 → 启动后台下载（不阻塞，单飞）并返回 'downloading'；下载失败仅调用
-*   warn 记录日志并结束本次尝试，下次调用会重新触发下载（自动重试）。
-* - warn 可选：下载失败时的日志回调（默认静默；apply 注入 ctx.logger.warn）。
-* - log 可选：下载开始/结束日志回调（默认静默；apply 注入 console.log + ctx.logger.info 双通道）。
-* - fetchImpl 可注入（测试传替身，默认全局 fetch）。
+* 本地 onnx 已存在 → 'ready'；缺失 → 启动后台下载（不阻塞、单飞，失败经 warn 记录，
+* 下次调用自动重试）并返回 'downloading'。warn/log/fetchImpl 可注入（测试传替身）。
 */
 function ensureModelReady(modelDir = BUNDLED_MODEL_DIR, warn = () => {}, fetchImpl, log = () => {}) {
 	ensureModelSmallFiles(modelDir);
@@ -8704,18 +8533,12 @@ function ensureModelReady(modelDir = BUNDLED_MODEL_DIR, warn = () => {}, fetchIm
 	}
 	return Promise.resolve("downloading");
 }
-/**
-* 两个向量的余弦相似度（向量已 L2 归一化时点积即余弦；这里兜底再归一化）。
-* 任一向量为零向量返回 0。
-*/
+/** 两个向量的余弦相似度（向量已 L2 归一化时点积即余弦；这里兜底再归一化）。零向量返回 0。 */
 function cosineSimilarity(a, b) {
 	const len = Math.min(a.length, b.length);
 	if (len === 0) return 0;
-	/** 点积累加。 */
 	let dot = 0;
-	/** a 的模平方。 */
 	let normA = 0;
-	/** b 的模平方。 */
 	let normB = 0;
 	for (let i = 0; i < len; i += 1) {
 		const x = a[i];
@@ -8730,35 +8553,34 @@ function cosineSimilarity(a, b) {
 //#endregion
 //#region src/config.ts
 /**
-* 插件配置：默认值与合并（preset 行 config 可覆盖全部键）。
-* 宽松校验：不合法的键被忽略、不合法的值回退默认值——配置错误不影响插件加载。
+* 插件配置：默认值与合并。
+* 导出 PluginConfig / DEFAULT_CONFIG / resolveConfig；宽松校验——未知键忽略、
+* 非法值回退默认值，配置错误不影响插件加载。
 */
 /** 默认配置（冻结对象，resolveConfig 合并的基底；debug 缺省值在解析时按 NODE_ENV 判定）。 */
 const DEFAULT_CONFIG = Object.freeze({
-	observeThresholdTokens: 1e5,
-	reflectThresholdTokens: 3e4,
-	compressMaxTokens: 1e4,
-	observeChunkTokens: 3e4,
-	observeChunkMaxTokens: 5e3,
-	tailMessageCount: 10,
-	compressRetryCount: 10,
+	observeThresholdTokens: 35e3,
+	reflectThresholdTokens: 4e4,
+	compressMaxTokens: 5e3,
+	rateLimitWaitMs: 6e4,
+	tailMessageCount: 5,
+	compressRetryCount: 5,
 	omEnabled: true,
 	debug: false,
 	recallEnabled: true,
 	semanticRecallEnabled: true,
 	modelDir: sharedModelDir()
 });
-/** 数值键校验参数表：键名 + [integer]。不限制取值区间——用户提供的值按原样接受（便于调试）。 */
+/** 数值键校验参数表：键名 + [是否必须为整数]。 */
 const NUMBER_KEYS = [
 	["observeThresholdTokens", true],
 	["reflectThresholdTokens", true],
 	["compressMaxTokens", true],
-	["observeChunkTokens", true],
-	["observeChunkMaxTokens", true],
+	["rateLimitWaitMs", true],
 	["tailMessageCount", true],
 	["compressRetryCount", true]
 ];
-/** 归一化原始配置输入：缺省 / null / 空串（含空白串）/ 非对象 视为空对象（全部用默认值）。 */
+/** 归一化原始配置输入：缺省 / null / 空串 / 非对象视为空对象。 */
 function normalizeConfigInput(raw) {
 	if (raw === void 0 || raw === null) return {};
 	if (typeof raw === "string" && raw.trim() === "") return {};
@@ -8772,17 +8594,11 @@ function resolveBoolean(raw, defaultValue) {
 	if (typeof raw === "boolean") return raw;
 	return defaultValue;
 }
-/**
-* 解析合并配置：未知键忽略、不合法值回退默认值，返回冻结的完整配置。
-* 允许所有配置留空——缺省 / null / 空串的键回退默认值，未给出的键亦取默认值。
-*/
+/** 解析合并配置：未知键忽略、不合法值回退默认值，返回冻结的完整配置。 */
 function resolveConfig(raw) {
-	/** 原始输入（留空 / 不合法视为空对象）。 */
 	const input = normalizeConfigInput(raw);
-	/** 合并结果（以默认值为基底）。 */
 	const config = { ...DEFAULT_CONFIG };
 	for (const [key, integer] of NUMBER_KEYS) {
-		/** 该键的原始值（留空 / 不合法则跳过，保持默认值）。 */
 		const value = input[key];
 		if (value === void 0 || value === null) continue;
 		if (typeof value === "string" && value.trim() === "") continue;
@@ -8790,47 +8606,126 @@ function resolveConfig(raw) {
 		if (integer && !Number.isInteger(value)) continue;
 		config[key] = value;
 	}
-	/** OM 自动压缩开关（缺省启用；false 关闭自动压缩，recall 工具不受影响）。 */
 	config.omEnabled = resolveBoolean(input.omEnabled, true);
-	/** 步骤级日志开关（缺省按 NODE_ENV !== 'production' 判定）。 */
 	config.debug = resolveBoolean(input.debug, process.env.NODE_ENV !== "production");
-	/** recall 工具开关（缺省启用）。 */
 	config.recallEnabled = resolveBoolean(input.recallEnabled, true);
-	/** recall-semantic 工具开关（缺省启用）。 */
 	config.semanticRecallEnabled = resolveBoolean(input.semanticRecallEnabled, true);
-	/** modelDir 原始值（留空 / 非空串以外回退默认；非空串必须为字符串）。 */
 	const modelDir = input.modelDir;
 	if (typeof modelDir === "string" && modelDir.trim() !== "") config.modelDir = modelDir;
 	return Object.freeze(config);
 }
 //#endregion
+//#region src/json-schema.ts
+/**
+* zod schema → 工具 wire 参数 JSON Schema 的转换工具。导出 parametersFromZod。
+* 工具参数定义统一由 zod 的 toJSONSchema 生成（.describe() 描述透传），剥除
+* $schema 元键与 additionalProperties（未知键在执行期由 zod 解析剥离）。
+*/
+/** 由 zod schema 生成 wire 参数 JSON Schema（根 type:'object'，含 properties/required）。 */
+function parametersFromZod(schema) {
+	const { $schema: _schema, additionalProperties: _additional, ...rest } = toJSONSchema(schema);
+	return rest;
+}
+//#endregion
+//#region src/recall-output.ts
+/** 纯文本结果（无图片）的便捷构造。 */
+function textOnly(text) {
+	return {
+		text,
+		images: []
+	};
+}
+/** 一张图片的文本标注行：[图片附件：name（mediaType W×H，N bytes）]。 */
+function imageNote(ref) {
+	return `[图片附件${ref.name ? `：${ref.name}` : ""}（${ref.mediaType} ${ref.width}×${ref.height}，${ref.bytes} bytes）]`;
+}
+/** 输出值 wire schema：宿主按此校验 execute 返回值。 */
+const RECALL_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		text: {
+			type: "string",
+			description: "完整消息内容的文本部分（带图位置以 [图片附件：…] 标注行提示）。"
+		},
+		images: {
+			type: "array",
+			description: "文本中引用的图片附件元数据（按出现顺序；渲染为随文本之后的 image 内容块，宿主按 attachmentId 解析字节）。",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					attachmentId: {
+						type: "string",
+						description: "附件服务的持久图片 id。"
+					},
+					mediaType: {
+						type: "string",
+						description: "图片媒体类型（如 image/png）。"
+					},
+					bytes: {
+						type: "integer",
+						description: "字节数。"
+					},
+					width: {
+						type: "integer",
+						description: "固有显示宽度（px）。"
+					},
+					height: {
+						type: "integer",
+						description: "固有显示高度（px）。"
+					},
+					name: {
+						type: "string",
+						description: "原始文件名（可选）。"
+					}
+				},
+				required: [
+					"attachmentId",
+					"mediaType",
+					"bytes",
+					"width",
+					"height"
+				]
+			}
+		}
+	},
+	required: ["text", "images"]
+};
+/** 把输出值投影为模型内容：text 块在前，images 逐个投影为 image 块。 */
+function renderRecallOutput(value) {
+	const blocks = [{
+		type: "text",
+		text: value.text
+	}];
+	for (const ref of value.images) {
+		const block = {
+			type: "image",
+			attachment: ref
+		};
+		blocks.push(block);
+	}
+	return blocks;
+}
+//#endregion
 //#region src/recall.ts
 /**
-* recall 工具：按「完整消息」序号（index）回看原始会话（start/end 为完整消息 index，
-* offset 为相对 start 的完整消息步数）。完整消息即 `用户消息`（user_message 中 kind 为 user
-* 的部分）、`系统消息`（user_message 中其余 kind 的部分）、`模型输出文本`和`具有result的
-* toolcall`；首条完整消息的 index 为 0，后续递增、会话内全局稳定，与摘要日志条目同一套编号。
-* recall 自身不设输出上限：超大的工具结果由 tool-result-pruner 裁剪（pruneContent），
-* 输出 token 由 pruner 配置控制。
-*
-* 参数由 zod schema（recallArgsSchema）在 execute 入口校验：start 必填（number），
-* end/offset 至少提供一个；非法参数抛出可读错误。
+* recall 工具：按完整消息 index 区间回看原始会话（含被压缩内容）。
+* 导出 recallArgsSchema / RecallArgs / parseRecallArgs / buildRecallTool。
+* 输出值为 { text, images }（契约见 recall-output.ts）；recall 自身不设输出上限，
+* 超大工具结果由 tool-result-pruner 裁剪。
 */
 /**
-* recall 工具参数 schema：start 必填（number）；end 与 offset 至少提供一个
-* （二者同时给出时 end 优先，与 execute 语义一致）；未知键自动剥离。
+* recall 工具参数 schema：start 必填；end 与 offset 至少提供一个（同时给出时 end 优先）。
+* 各字段描述经 .describe() 透传到 wire JSON Schema。
 */
 const recallArgsSchema = z.object({
-	start: z.number(),
-	end: z.number().optional(),
-	offset: z.number().optional()
+	start: z.number().describe("完整消息序号（index），作为基准边界，和 end 或 offset 配合，指定区间；end 与 offset 至少提供一个（同时给出时 end 优先）。"),
+	end: z.number().optional().describe("与 offset 互斥，指定区间的另一个边界。"),
+	offset: z.number().optional().describe("与 end 互斥。相对 start 的步数：正数向后、负数向前。")
 }).refine((args) => args.end !== void 0 || args.offset !== void 0, { message: "end 与 offset 至少提供一个" });
-/**
-* 解析并校验 recall 调用参数：校验失败时抛出首个校验问题的可读消息
-* （普通 Error 而非 ZodError，兼容 SDK 展示）。
-*/
+/** 解析并校验 recall 调用参数：失败时抛出首个校验问题的可读消息（普通 Error，兼容 SDK 展示）。 */
 function parseRecallArgs(raw) {
-	/** safeParse 结果（成功时 data 为 RecallArgs，失败时 error 携带问题列表）。 */
 	const result = recallArgsSchema.safeParse(raw);
 	if (!result.success) throw new Error(result.error.issues.map((issue) => `${issue.path.join(".") || "args"}: ${issue.message}`).join("; "));
 	return result.data;
@@ -8842,116 +8737,89 @@ function parseRecallArgs(raw) {
 function buildRecallTool(getPruner) {
 	return {
 		name: "recall",
-		description: `${COMPLETE_MESSAGE_DEFINITION}此工具可以精确查询完整消息。用index指定一个区间，返回区间内所有完整消息的内容。`,
-		parameters: {
-			start: {
-				type: "number",
-				description: "完整消息序号（index），作为基准边界，和end或offset配合，指定区间",
-				required: true
-			},
-			end: {
-				type: "number",
-				description: "与 offset 互斥，指定区间的另一个边界。"
-			},
-			offset: {
-				type: "number",
-				description: "与 end 互斥。相对 start 的步数：正数向后、负数向前。"
-			}
-		},
+		description: `${COMPLETE_MESSAGE_DEFINITION}此工具可以精确查询完整消息。用index指定一个区间，返回区间内所有完整消息的内容；完整消息携带的图片附件随结果保留（文本段以 [图片附件：…] 标注，随后附 image 内容块）。`,
+		parameters: parametersFromZod(recallArgsSchema),
 		output: {
-			schema: { type: "string" },
-			render: (_args, value) => [{
-				type: "text",
-				text: String(value)
-			}]
+			schema: RECALL_OUTPUT_SCHEMA,
+			render: (_args, value) => renderRecallOutput(value)
 		},
 		async execute(args, exec) {
-			/** 解析并校验后的调用参数（不满足 schema 时抛出可读错误）。 */
 			const { start, end, offset } = parseRecallArgs(args);
-			/** 当前会话（缺失则无法回看）。 */
 			const session = exec.agent?.session;
-			if (!session) return "会话异常";
-			if (!isMainSession(session)) return "recall 仅主会话可用";
-			/** 完整消息索引（index = 数组下标，0 起）。 */
+			if (!session) return textOnly("会话异常");
+			if (!isMainSession(session)) return textOnly("recall 仅主会话可用");
 			const cms = indexCompleteMessages(session);
-			/** 起始下标（非整数 floor；越界返回提示）。 */
 			const startIndex = Number.isFinite(start) ? Math.floor(start) : 0;
-			if (startIndex < 0 || startIndex >= cms.length) return `start ${start} 越界（完整消息共 ${cms.length} 条，index 范围 0..${cms.length - 1}）`;
-			/** 终点下标（end 优先，否则 startIndex + offset）。 */
+			if (startIndex < 0 || startIndex >= cms.length) return textOnly(`start ${start} 越界（完整消息共 ${cms.length} 条，index 范围 0..${cms.length - 1}）`);
 			let endIndex;
 			if (end !== void 0) {
-				/** end 取整（非整数 floor）。 */
 				const e = Number.isFinite(end) ? Math.floor(end) : 0;
-				if (e < 0 || e >= cms.length) return `end ${end} 越界（完整消息共 ${cms.length} 条，index 范围 0..${cms.length - 1}）`;
+				if (e < 0 || e >= cms.length) return textOnly(`end ${end} 越界（完整消息共 ${cms.length} 条，index 范围 0..${cms.length - 1}）`);
 				endIndex = e;
 			} else {
-				/** offset 数值（refine 保证此分支 offset 已提供，schema 保证为 number）。 */
 				const raw = offset ?? 0;
 				endIndex = startIndex + (Number.isFinite(raw) ? Math.floor(raw) : 0);
 			}
-			/** 区间下界（钳制到 [0, len-1]）。 */
 			const lo = Math.max(0, Math.min(startIndex, endIndex));
-			/** 区间上界（钳制到 [0, len-1]）。 */
 			const hi = Math.min(cms.length - 1, Math.max(startIndex, endIndex));
-			/** tool-result-pruner（可选，裁剪超大工具结果）。 */
 			const pruner = getPruner?.();
-			/** 渲染结果缓冲（每条完整消息一段，标 index + 类型）。 */
 			const parts = [];
+			const images = [];
 			for (let i = lo; i <= hi; i += 1) {
-				/** 当前完整消息。 */
 				const cm = cms[i];
 				if (!cm) continue;
-				/** 该条完整消息的呈现文本（pruner 裁剪超大结果；单条失败不影响整体）。 */
 				let text = "";
+				let cmImages = [];
 				try {
-					text = renderCompleteMessage(session, cm, pruner);
+					const rendered = renderCompleteMessageParts(session, cm, pruner);
+					text = rendered.text;
+					cmImages = rendered.images;
 				} catch {}
-				/** 类型标注（toolcall 附调用 id，便于模型关联）。 */
 				const callAttr = cm.type === "toolcall" && cm.callId ? ` callId=${cm.callId}` : "";
-				parts.push(`-- [index ${cm.index}] ${cm.type}${callAttr} --\n${text}`);
+				let body = text;
+				if (cmImages.length > 0) {
+					body += (body === "" ? "" : "\n") + cmImages.map(imageNote).join("\n");
+					images.push(...cmImages);
+				}
+				parts.push(`-- [index ${cm.index}] ${cm.type}${callAttr} --\n${body}`);
 			}
-			if (parts.length === 0) return "指定区间没有完整消息";
-			return parts.join("\n\n");
+			if (parts.length === 0) return textOnly("指定区间没有完整消息");
+			return {
+				text: parts.join("\n\n"),
+				images
+			};
 		}
 	};
 }
 //#endregion
 //#region src/semantic-recall.ts
 /**
-* recall-semantic 工具：按自然语言 query 对会话全部完整消息（含被压缩/遮蔽的）做语义
-* 检索，返回最匹配的完整消息与匹配说明。完整消息即 `用户消息`（user_message 中 kind 为 user
-* 的部分）、`系统消息`（user_message 中其余 kind 的部分）、`模型输出文本`和`具有result的
-* toolcall`；首条完整消息的 index 为 0，后续递增、会话内全局稳定。
-*
-* - 参数：query 必填；top_k（默认 3，1-10）；start/end/offset 限定检索区间
-*   （意义同 recall：start 为基准边界，end 与 offset 二选一；end 优先）。
-* - 区间缺省（start 未提供）→ 检索全部消息；区间不合法（start/end 越界等）→
-*   不报错，回退全量检索并在输出中明确告知（模型可见）。
-* - 向量：本地 ONNX embedding（embedding.ts，懒加载 + 批量）；相似度 = cosine。
-* - 输出：命中消息的 index/类型（toolcall 附调用 id）+ 完整渲染文本 + 匹配说明（相似度、
-*   命中的关键词）；超大结果由 tool-result-pruner 裁剪（同 recall）。
-* - 仅主会话可用（subagent 拒绝，与 recall 一致）。
+* recall-semantic 工具：按自然语言 query 对会话全部完整消息（含被压缩/遮蔽的）做
+* 语义检索，返回最匹配的完整消息与匹配说明。
+* 导出 semanticRecallArgsSchema / SemanticRecallArgs / parseSemanticRecallArgs /
+* resolveSemanticRange / tokenize / matchExplanation / buildSemanticRecallTool。
+* 向量为本地 ONNX 嵌入（cosine 相似度）；只匹配文本，纯图片消息不进候选池；
+* 区间缺省检索全部、区间不合法回退全量并在输出中告知；输出契约同 recall
+* （{ text, images }，超大结果由 tool-result-pruner 裁剪）；仅主会话可用。
 */
 /** recall-semantic 工具参数 schema：query 必填；top_k 默认 3（1-10）；区间参数均可选。 */
 const semanticRecallArgsSchema = z.object({
-	query: z.string(),
-	top_k: z.number().int().min(1).max(10).optional(),
-	start: z.number().optional(),
-	end: z.number().optional(),
-	offset: z.number().optional()
+	query: z.string().describe("描述要找的内容的自然语言 query（可混用中英文与代码术语，如 \"修复 retry backoff 的逻辑\"），不能为空。"),
+	top_k: z.number().int().min(1).max(10).optional().describe("返回最匹配的完整消息条数（1-10，默认 3）。"),
+	start: z.number().optional().describe("完整消息序号（index），可选。作为基准边界，和end或offset配合，指定搜索区间。"),
+	end: z.number().optional().describe("必须和start配合使用，与 offset 互斥，指定搜索区间的另一个边界。"),
+	offset: z.number().optional().describe("必须和start配合使用，与 end 互斥。相对 start 的步数：正数向后、负数向前。")
 }).refine((args) => args.query.trim().length > 0, { message: "query 不能为空" });
 /** 解析并校验参数：失败时抛出可读错误（普通 Error 而非 ZodError）。 */
 function parseSemanticRecallArgs(raw) {
-	/** safeParse 结果。 */
 	const result = semanticRecallArgsSchema.safeParse(raw);
 	if (!result.success) throw new Error(result.error.issues.map((issue) => `${issue.path.join(".") || "args"}:${issue.message}`).join("; "));
 	return result.data;
 }
 /**
 * 解析检索区间（完整消息 index，含端点）。
-* - start 未提供 → 全量（fallback=false）。
-* - start 提供：end/offset 计算终点（语义同 recall，end 优先）；
-*   start/end 越界或区间为空 → fallback=true（全量 + 提示）。
+* start 未提供 → 全量（fallback=false）；start/end 越界或区间为空 → fallback=true
+* （回退全量并在输出中告知）。
 */
 function resolveSemanticRange(total, args) {
 	if (total <= 0) return {
@@ -8964,17 +8832,14 @@ function resolveSemanticRange(total, args) {
 		hi: total - 1,
 		fallback: false
 	};
-	/** start 取整（非有限数按 -1 处理，走越界回退）。 */
 	const start = Number.isFinite(args.start) ? Math.floor(args.start) : -1;
 	if (start < 0 || start >= total) return {
 		lo: 0,
 		hi: total - 1,
 		fallback: true
 	};
-	/** 终点 index（end 优先；否则 start + offset 取整）。 */
 	let end;
 	if (args.end !== void 0) {
-		/** end 取整（非有限数按 -1 处理，走越界回退）。 */
 		const found = Number.isFinite(args.end) ? Math.floor(args.end) : -1;
 		if (found < 0 || found >= total) return {
 			lo: 0,
@@ -8984,9 +8849,7 @@ function resolveSemanticRange(total, args) {
 		end = found;
 	} else if (args.offset !== void 0) end = start + (Number.isFinite(args.offset) ? Math.floor(args.offset) : 0);
 	else end = start;
-	/** 区间下界（钳制）。 */
 	const lo = Math.max(0, Math.min(start, end));
-	/** 区间上界（钳制）。 */
 	const hi = Math.min(total - 1, Math.max(start, end));
 	if (lo > hi) return {
 		lo: 0,
@@ -9001,92 +8864,53 @@ function resolveSemanticRange(total, args) {
 }
 /** 简易分词：按非字母数字切分为小写词元（匹配要点用，非检索核心）。 */
 function tokenize(text) {
-	/** 词元集合。 */
 	const tokens = /* @__PURE__ */ new Set();
 	for (const part of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) if (part.length > 0) tokens.add(part);
 	return tokens;
 }
 /** 命中消息的匹配说明行：相似度 + 与 query 共有的关键词（最多 8 个）。 */
 function matchExplanation(query, text, score) {
-	/** query 词元。 */
 	const qTokens = tokenize(query);
-	/** 命中消息文本词元。 */
 	const mTokens = tokenize(text);
-	/** 共有词元（交集，按 query 词序）。 */
 	const shared = [];
 	for (const token of qTokens) {
 		if (mTokens.has(token)) shared.push(token);
 		if (shared.length >= 8) break;
 	}
-	/** 关键词部分（无共有词则省略）。 */
 	const keywords = shared.length > 0 ? `，命中关键词: ${shared.join(" ")}` : "";
 	return `相似度 ${score.toFixed(3)}${keywords}`;
 }
-/** 模型未就绪时返回给模型的文案（告知即可；下载完成后无需另行通知，直接再次调用）。 */
+/** 模型未就绪时返回给模型的文案（下载完成后直接再次调用即可）。 */
 const SEMANTIC_MODEL_NOT_READY_MESSAGE = "语义检索暂不可用，本地向量模型尚未就绪。";
 /** 构建 recall-semantic 工具定义（embedder/modelStatus 可注入，测试传替身；缺省用本地模型）。 */
 function buildSemanticRecallTool(options) {
-	/** pruner 获取器（可选，裁剪超大工具结果）。 */
 	const getPruner = options?.getPruner ?? (() => void 0);
-	/** 嵌入函数（注入替身或懒加载本地模型）。 */
 	const embed = options?.embedder ?? ((texts) => getEmbedder().then((fn) => fn(texts)));
 	return {
 		name: "recall-semantic",
-		description: `${COMPLETE_MESSAGE_DEFINITION}此工具可以按自然语言含义，检索最符合的完整消息。默认在全消息范围搜索，可以指定区间。`,
-		parameters: {
-			query: {
-				type: "string",
-				description: "描述要找的内容的自然语言 query（可混用中英文与代码术语，如 \"修复 retry backoff 的逻辑\"）。",
-				required: true
-			},
-			top_k: {
-				type: "number",
-				description: "返回最匹配的完整消息条数（1-10，默认 3）。"
-			},
-			start: {
-				type: "number",
-				description: "完整消息序号（index），可选。作为基准边界，和end或offset配合，指定搜索区间。"
-			},
-			end: {
-				type: "number",
-				description: "必须和start配合使用，与 offset 互斥，指定搜索区间的另一个边界。"
-			},
-			offset: {
-				type: "number",
-				description: "必须和start配合使用，与 end 互斥。相对 start 的步数：正数向后、负数向前。"
-			}
-		},
+		description: `${COMPLETE_MESSAGE_DEFINITION}此工具可以按自然语言含义，检索最符合的完整消息。默认在全消息范围搜索，可以指定区间。注意：语义检索只匹配文本，图片内容不参与匹配（纯图片消息无法命中，也不能按图片内容检索）；命中的完整消息携带的图片附件随结果保留（文本段以 [图片附件：…] 标注，随后附 image 内容块），与 recall 相同。`,
+		parameters: parametersFromZod(semanticRecallArgsSchema),
 		output: {
-			schema: { type: "string" },
-			render: (_args, value) => [{
-				type: "text",
-				text: String(value)
-			}]
+			schema: RECALL_OUTPUT_SCHEMA,
+			render: (_args, value) => renderRecallOutput(value)
 		},
 		async execute(args, exec) {
-			/** 解析并校验后的调用参数。 */
 			const { query, top_k, start, end, offset } = parseSemanticRecallArgs(args);
-			/** 当前会话。 */
 			const session = exec.agent?.session;
-			if (!session) return "会话异常";
-			if (!isMainSession(session)) return "recall-semantic 仅主会话可用";
-			if ((await options?.modelStatus?.() ?? "ready") !== "ready") return SEMANTIC_MODEL_NOT_READY_MESSAGE;
-			/** 完整消息索引（全部事件，含被压缩/遮蔽）。 */
+			if (!session) return textOnly("会话异常");
+			if (!isMainSession(session)) return textOnly("recall-semantic 仅主会话可用");
+			if ((await options?.modelStatus?.() ?? "ready") !== "ready") return textOnly(SEMANTIC_MODEL_NOT_READY_MESSAGE);
 			const cms = indexCompleteMessages(session);
-			if (cms.length === 0) return "会话中没有可检索的消息";
-			/** 检索区间（完整消息 index；区间不合法时回退全量并标记）。 */
+			if (cms.length === 0) return textOnly("会话中没有可检索的消息");
 			const range = resolveSemanticRange(cms.length, {
 				start,
 				end,
 				offset
 			});
-			/** 候选完整消息渲染文本（区间内；跳过渲染失败/空文本）。 */
 			const candidates = [];
 			for (let i = range.lo; i <= range.hi; i += 1) {
-				/** 当前完整消息。 */
 				const cm = cms[i];
 				if (!cm) continue;
-				/** 渲染文本（嵌入用完整文本，输出时再裁剪）。 */
 				let text = "";
 				try {
 					text = renderCompleteMessage(session, cm);
@@ -9096,67 +8920,54 @@ function buildSemanticRecallTool(options) {
 					text
 				});
 			}
-			if (candidates.length === 0) return "指定范围内没有可检索的消息";
-			/** 查询向量（单条）。 */
+			if (candidates.length === 0) return textOnly("指定范围内没有可检索的消息");
 			const [queryVec] = await embed([query]);
-			if (!queryVec) return "语义检索失败：无法生成查询向量";
-			/** 候选文本批量嵌入。 */
+			if (!queryVec) return textOnly("语义检索失败：无法生成查询向量");
 			const vectors = await embed(candidates.map((c) => c.text));
-			/** 打分结果（相似度 + 候选）。 */
 			const scored = candidates.map((c, i) => ({
 				cm: c.cm,
 				text: c.text,
 				score: cosineSimilarity(queryVec, vectors[i] ?? /* @__PURE__ */ new Float32Array(0))
 			}));
 			scored.sort((a, b) => b.score - a.score);
-			/** 返回条数（top_k 默认 3）。 */
 			const limit = top_k ?? 3;
 			const hits = scored.slice(0, limit);
-			/** 结果缓冲。 */
 			const parts = [];
-			/** 范围描述（回退时明确告知模型）。 */
+			const images = [];
 			const rangeNote = range.fallback ? "指定区间不合法（start/end 越界等），已回退检索全部消息" : start === void 0 ? `检索全部消息（${candidates.length} 条可嵌入）` : `检索区间 [${range.lo}..${range.hi}]（${candidates.length} 条可嵌入）`;
 			parts.push(`查询: ${query}`);
 			parts.push(rangeNote);
 			parts.push(`匹配 TOP-${hits.length}（共 ${scored.length} 条候选）:`);
 			for (let i = 0; i < hits.length; i += 1) {
-				/** 当前命中。 */
 				const hit = hits[i];
 				if (!hit) continue;
-				/** 类型标注（toolcall 附调用 id，与 recall 输出一致）。 */
 				const callAttr = hit.cm.type === "toolcall" && hit.cm.callId ? ` callId=${hit.cm.callId}` : "";
-				/** 输出文本（pruner 裁剪超大内容；裁剪失败保留嵌入用文本）。 */
 				let text = hit.text;
+				let hitImages = [];
 				try {
-					/** tool-result-pruner（可选）。 */
 					const pruner = getPruner();
-					text = renderCompleteMessage(session, hit.cm, pruner);
+					const rendered = renderCompleteMessageParts(session, hit.cm, pruner);
+					text = rendered.text;
+					hitImages = rendered.images;
 				} catch {}
 				parts.push(`-- [${i + 1}] index ${hit.cm.index} ${hit.cm.type}${callAttr} — ${matchExplanation(query, hit.text, hit.score)} --`);
-				parts.push(text);
+				parts.push(hitImages.length > 0 ? [text, ...hitImages.map(imageNote)].join("\n") : text);
+				images.push(...hitImages);
 			}
-			return parts.join("\n\n");
+			return {
+				text: parts.join("\n\n"),
+				images
+			};
 		}
 	};
 }
 //#endregion
 //#region src/index.ts
 /**
-* dsh-plugin-om — Observational Memory（OM）上下文压缩 + recall 检索插件。
-* 不依赖特定 tool mode（native / code / both 均可运行）。
-*
-* 模块：
-*  - recall.ts  recall({ start, end?, offset? }) 工具：按完整消息 index 回看原始会话
-*  - semantic-recall.ts  recall-semantic({ query, top_k?, start?, end?, offset? }) 工具：
-*    按语义在全部完整消息（含被压缩/遮蔽）中检索，返回最匹配的完整消息与匹配说明
-*    （本地 ONNX embedding，模型随插件打包，懒加载）
-*  - compress.ts 自动压缩（OM 观察/反思两级阈值）：pre-step 阻塞串行执行——
-*    反思（<history> 块 tokens 合计 ≥ reflectThresholdTokens 时摘要调用精简合并）、
-*    观察（未压缩消息 tokens ≥ observeThresholdTokens 时摘要调用压缩为观察日志并追加）
-*
-* 约束：不引入自定义会话事件类型——压缩复用宿主已知的 compaction/* 生命周期事件
-* （start/summary/end）与 checkpoint 标记，结果写入消息记录与轨迹。
-* 仅主会话生效（subagent 不压缩、recall 拒绝）。
+* dsh-plugin-om 入口（tsdown 打包入口）：导出 name / inject / apply。
+* apply 注册 recall / recall-semantic 工具，并接线 agent/pre-step 自动压缩
+* （先反思后观察，仅主会话生效）。压缩与检索的实现见 compress.ts / recall.ts /
+* semantic-recall.ts。
 */
 /** 插件名（Loader 识别入口的稳定标识）。 */
 const name = "dsh-plugin-om";
@@ -9167,21 +8978,14 @@ const inject = [
 	"tokenMeter",
 	"sessions"
 ];
-/**
-* 插件激活入口：注册 recall / recall-semantic 工具（由配置键 recallEnabled /
-* semanticRecallEnabled 控制），并在 agent/pre-step 阻塞触发两级自动压缩
-* （先反思后观察）。仅主会话生效。
-*/
+/** 插件激活入口：解析配置、注册工具、接线 pre-step 自动压缩。 */
 function apply(ctx, config) {
-	/** 解析后的插件配置（默认值合并 + 校验）。 */
 	const resolved = resolveConfig(config);
-	/** 插件日志门面（step=debug 按配置 debug 开关输出；info/warn 始终输出）。 */
 	const logger = makeLogger(ctx, resolved.debug);
 	logger.step(`apply 启动：observeThresholdTokens=${String(resolved.observeThresholdTokens)} reflectThresholdTokens=${String(resolved.reflectThresholdTokens)} compressMaxTokens=${String(resolved.compressMaxTokens)} tailMessageCount=${String(resolved.tailMessageCount)} omEnabled=${String(resolved.omEnabled)} debug=${String(resolved.debug)}`);
 	if (resolved.recallEnabled) ctx.tools.register(buildRecallTool(() => ctx.get("toolResultPruner")));
 	if (resolved.semanticRecallEnabled) {
 		const warnModel = (message) => ctx.logger.warn(`dsh-plugin-om: ${message}`);
-		/** 下载开始/结束日志：console + 插件日志双通道（失败经 warnModel 输出）。 */
 		const logModel = (message) => {
 			console.log(message);
 			logger.info(message);