dsh-plugin-om 0.0.5 → 0.0.6

package/dist/index.mjs

@@ -1,5 +1,13 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 //#region src/constants.ts
+/**
+* 共享常量：集中定义插件级魔法字符串与事件名，避免散落各模块。
+*/
+/** 插件标识：压缩消息 source.plugin 取值与日志前缀。 */
+const PLUGIN_LABEL = "dsh-plugin-om";
 /** 压缩日志标签名：<om-history>...</om-history> 包裹观察/反思日志块。 */
 const HISTORY_TAG = "om-history";
 /** 宿主压缩 checkpoint 标记的 plugin 名（dsh-compaction-basic 的 COMPACT_CHECKPOINT_MARKER.plugin）。 */
@@ -52,6 +60,28 @@ function indexMessages(session) {
 	};
 }
 //#endregion
+//#region src/logger.ts
+/**
+* 日志辅助：步骤级（debug）日志默认仅 dev（非 production）输出，便于开发调试；
+* 失败等关键日志始终输出（不受 debug 开关影响）。
+* 开关配置键 debug：true 强制开启、false 强制关闭，缺省按 NODE_ENV !== 'production' 判定
+* （默认值由 resolveConfig 解析，见 config.ts）。
+*/
+/** 构建插件日志门面：统一加 PLUGIN_LABEL 前缀，step 按 debug 开关过滤。 */
+function makeLogger(ctx, debug) {
+	return {
+		step(message) {
+			if (debug) ctx.logger.debug(`${PLUGIN_LABEL}: ${message}`);
+		},
+		info(message) {
+			ctx.logger.info(`${PLUGIN_LABEL}: ${message}`);
+		},
+		warn(message) {
+			ctx.logger.warn(`${PLUGIN_LABEL}: ${message}`);
+		}
+	};
+}
+//#endregion
 //#region src/utils.ts
 /** 判断值是否为普通对象：typeof object 且非 null 且非数组（类型收窄用）。 */
 function isRecord(value) {
@@ -62,13 +92,17 @@ function fail(message) {
 	throw new Error(`dsh-plugin-om: ${message}`);
 }
 /**
-* 校验配置数值：必须是有限数且在 [min, max] 内（可选整数约束），
+* 校验配置数值：必须是有限数（可选整数约束），不限制取值区间；
 * 不满足时抛出带插件前缀的错误。
 */
-function assertNumber(name, value, { min = 0, max = Infinity, integer = false } = {}) {
-	if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) fail(`config ${name} must be a finite number in [${min}, ${max}]`);
+function assertNumber(name, value, { integer = false } = {}) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(`config ${name} must be a finite number`);
 	if (integer && !Number.isInteger(value)) fail(`config ${name} must be an integer`);
 }
+/** 校验配置字符串：必须是非空（含非空白）字符串，否则抛出带插件前缀的错误。 */
+function assertNonEmptyString(name, value) {
+	if (typeof value !== "string" || value.trim() === "") fail(`config ${name} must be a non-empty string`);
+}
 /** 生成 uuid：优先 crypto.randomUUID，回退为时间戳+随机串拼接（保证唯一性）。 */
 function uuid() {
 	/** 全局 crypto 对象（提供 randomUUID 的现代环境才存在）。 */
@@ -120,26 +154,17 @@ function routedTarget(session) {
 }
 //#endregion
 //#region src/summarize.ts
-/**
-* 摘要子会话（OM 观察/反思）：两级阈值下分别 fork 子会话——
-*  - observe：把「上下文中最后一次 <om-history> 之后」的未压缩消息压缩为观察日志
-*    （结果追加到旧摘要末尾，替换被压缩消息区间）；
-*  - reflect：把当前 <om-history> 精简合并（结果替换单个摘要节点）。
-*
-* 提示词不内嵌消息/摘要全文：fork 子会话继承父会话日志前缀（seed 截断于最后一个
-* turn/end，宿主 fork 提供方语义），按上下文中的 <om-history> 定位待处理部分；
-* message_id 对照表与中断标记由插件从日志计算后内嵌（id 非原文，保留关键 id 供
-* recall 检索）。摘要以工具调用为核心节点，不限于 run_code。
-* 仅主会话生效（index.ts 守卫）。
-*/
 /** 观察者 persona：只针对未压缩消息产出观察日志，不用工具、不展示思考。 */
 const OBSERVER_PERSONA = "你是 dsh-plugin-om 的上下文观察者（Observer，机制参考 Mastra Observational Memory）：把会话中尚未压缩的消息压缩为一份观察日志。不用工具、不展示思考、不评价代码、不输出多余文字。";
 /** 反思者 persona：只精简合并当前摘要，不用工具、不展示思考。 */
 const REFLECTOR_PERSONA = "你是 dsh-plugin-om 的上下文反思者（Reflector，机制参考 Mastra Observational Memory）：把当前 <om-history> 压缩日志精简合并为一份更紧凑的日志。不用工具、不展示思考、不输出多余文字。";
 /**
-* 构建观察提示词：规则（消息概括为要点 / 工具调用按目的聚合——不限于 run_code /
-* 仅关键消息保留 message_id / 中断标注 / 未完成写进度与下一步）+ message_id 对照表 +
-* 中断标记 + 追加说明。全文由继承上下文提供。
+* 构建观察指令主体：任务声明（fork：停止任务/禁止工具；new：说明总结日志）+ 模式相关
+* 的上下文定位与压缩范围（fork：上方完整会话记录——尾部已在输入中实际截断，提示词不含
+* 尾部规则；new：下方消息即压缩对象）+ 规则（用户消息完整保留原文 / AI 消息模块化压缩
+* ——工具调用按目的聚合——不限于 run_code / 倾向于新消息 / 中断标注 / 未完成写进度与
+* 下一步）+ 输出格式（合法 XML）+ 对照表 + 中断标记 + 追加说明。persona 由调用方拼接
+* 到指令开头。
 */
 function buildObservePrompt(options) {
 	/** 对照表段落（无则标注「无」）。 */
@@ -147,134 +172,277 @@ function buildObservePrompt(options) {
 	/** 中断标记段落（无则标注「无」）。 */
 	const interruptionSection = options.interruptions.length > 0 ? options.interruptions : ["（无）"];
 	return [
-		`你继承的会话上下文中，最后一次 <${HISTORY_TAG}> 块之后的全部消息都是「未压缩消息」；只对这些消息做压缩，忽略更早的历史。`,
-		`如果上下文里还没有 <${HISTORY_TAG}> 块，则除本消息外的全部消息都是未压缩消息。`,
+		options.mode === "fork" ? "停止一切现有任务，禁止调用任何工具，改为将过往消息总结为一份日志。" : "将过往消息总结为一份日志。",
+		"",
+		...options.mode === "fork" ? [
+			"上方的消息记录是主会话的完整历史（系统提示词与全部消息）。",
+			`总结范围：最后一次 <${HISTORY_TAG}> 块之后的全部消息；只对这些消息做压缩，忽略更早的历史。`,
+			`如果消息记录里还没有 <${HISTORY_TAG}> 块，则除本指令外的全部消息都是压缩对象。`
+		] : ["下方的消息记录是本次要压缩的全部消息（上一个 <om-history> 块之后的新消息；不含旧压缩日志、不含尾部）。", "你的压缩结果会作为新的 <om-history> 块追加到已有压缩日志之后。"],
 		"",
 		"【规则】",
-		"- 用户消息概括为 user_message 条目（保留需求要点与关键事实：数字、路径、命令、决定），仅对关键消息保留 message_id（格式：user_message message_id:<id> text:<要点>）。关键消息指开启新任务/提出需求的请求、包含关键决策或不可再得事实的输入；普通消息（寒暄、重复、可推断内容）可以省略 message_id。",
-		"- 所有工具调用（run_code 与其他工具同等对待，不限于 run_code）按调用目的聚合为一行 toolcall message_id:<该组最后一条消息的 message_id> purpose:<聚合目的> summary:<行为与结果摘要>；工具组内部细节（参数、完整输出）不保留，需要原文时用 recall 按 message_id 回看。",
+		"- 用户消息完整保留原文，输出为 <user_message> 条目（id 为该消息的 message_id，内容为消息原文，不概括、不省略）。",
+		"- AI 消息划分模块压缩（与现状一致）：所有工具调用（run_code 与其他工具同等对待，不限于 run_code）按调用目的聚合为一行 toolcall message_id:<该组最后一条消息的 message_id> purpose:<聚合目的> summary:<行为与结果摘要>；目的相同、关联度高的连续行为聚合为一个 <assistant> 模块，模块内最后一条消息的 message_id 作为 last_id；工具组内部细节（参数、完整输出）不保留，需要原文时用 recall 按 message_id 回看。",
+		"- 总结时倾向于新消息，旧消息一句话带过即可；新旧消息冲突时强调新消息，不修改旧日志条目。",
 		"- 若【中断标记】非空，在对应位置明确写出中断（例如「被用户打断，因此上一段工作未完成」），帮助后续理解用户为何再次输入消息、为何不延续之前的工作。",
 		"- 若当前工作看起来未完成（最后一次工具调用没有结果、或对话被中断/异常结束），在日志末尾说明当前进度与下一步要做什么。",
-		`- 只输出日志条目本身；不要 <${HISTORY_TAG}> 标签、不要解释、不要复述规则。`,
+		"【输出格式】只输出一个 <om-history> 包裹的合法 XML 日志块，不要解释、不要复述规则：",
+		`<${HISTORY_TAG}>`,
+		"<user_message id=\"(message_id)\">",
+		"(user 消息原文)",
+		"</user_message>",
+		"<assistant last_id=\"(该组最后一条消息的 message_id)\">",
+		"(压缩模块：toolcall 聚合行等，与现有格式一致)",
+		"</assistant>",
+		`</${HISTORY_TAG}>`,
 		"",
-		"【message_id 对照表】（按顺序对应你上下文中的消息，用于产出正确的 message_id）",
+		"【message_id 对照表】（按顺序对应消息记录中的未压缩消息，用于产出正确的 message_id）",
 		...tableSection,
 		"",
 		"【中断标记】",
 		...interruptionSection,
 		"",
-		...options.hasOldHistory ? [`【说明】你的压缩结果会被直接追加到上一次压缩产物（<${HISTORY_TAG}>）的末尾，条目格式须与上一条目保持一致。`] : [`【说明】你的压缩结果将成为第一条 <${HISTORY_TAG}> 压缩日志。`]
+		...options.hasOldHistory ? [`【说明】你的压缩结果会被直接追加到上一次压缩产物（<${HISTORY_TAG}>）的末尾，作为新的 <${HISTORY_TAG}> 块；条目格式与本块一致。`] : [`【说明】你的压缩结果将成为第一条 <${HISTORY_TAG}> 压缩日志。`]
 	].join("\n");
 }
-/** 构建反思提示词：精简合并当前 <om-history>；全文由继承上下文提供。 */
-function buildReflectPrompt() {
+/** 构建反思指令主体：任务声明（fork：停止任务/禁止工具；new：说明总结日志）+ 精简合并
+* 当前 <om-history> 的规则 + 输出格式（合法 XML）；消息记录全文由请求（fork）或渲染输入（new）提供。 */
+function buildReflectPrompt(mode) {
 	return [
-		`你继承的会话上下文中包含当前的 <${HISTORY_TAG}> 压缩日志（最后一次 <${HISTORY_TAG}> 块）。`,
-		"只对这份压缩日志做精简合并；不要涉及日志之外的消息。",
+		mode === "fork" ? "停止一切现有任务，禁止调用任何工具，改为将当前压缩日志精简合并为一份更紧凑的日志。" : "将当前压缩日志精简合并为一份更紧凑的日志。",
+		"",
+		...mode === "new" ? ["下方的消息记录包含当前的 <om-history> 压缩日志（最后一次 <om-history> 块）。", "只对这份压缩日志做精简合并；不要涉及日志之外的消息。"] : ["上方的消息记录是主会话的完整历史，其中包含当前的 <om-history> 压缩日志（最后一次 <om-history> 块）。", "只对这份压缩日志做精简合并；不要涉及日志之外的消息。"],
 		"",
 		"【规则】",
-		"- 用户消息保留要点，仅保留关键 message_id（格式：user_message message_id:<id> text:<要点>）；可省略的 message_id 删除。",
+		"- 用户消息保留要点与 message_id（格式：<user_message id=\"(message_id)\"> 要点 </user_message>）；可省略的条目删除。",
 		"- toolcall 条目按调用目的进一步聚合，保留组内最后一条消息的 message_id；不重要的条目 summary 写「（略）」。",
 		"- 保留中断说明与未完成说明（若原日志中有）。",
-		"- 过时事实丢弃，不逐字复制旧文本。",
-		`- 只输出合并后的日志条目本身；不要 <${HISTORY_TAG}> 标签、不要解释、不要复述规则。`,
+		"- 过时事实丢弃，不逐字复制旧文本；新旧条目冲突时保留新条目。",
+		"【输出格式】只输出一个 <om-history> 包裹的合法 XML 日志块，不要解释、不要复述规则：",
+		`<${HISTORY_TAG}>`,
+		"<user_message id=\"(message_id)\">",
+		"(user 消息要点)",
+		"</user_message>",
+		"<assistant last_id=\"(该组最后一条消息的 message_id)\">",
+		"(压缩模块：toolcall 聚合行等，与现有格式一致)",
+		"</assistant>",
+		`</${HISTORY_TAG}>`,
 		"",
 		`【说明】你的合并结果会替换当前的 <${HISTORY_TAG}> 块内容。`
 	].join("\n");
 }
+/** 流收集器：提取文本输出 + usage + finish（不依赖宿主 BlockAssembler，保持零运行时依赖）。 */
+var StreamCollector = class {
+	/** 文本输出缓冲（text-delta 拼接；reasoning 不计入）。 */
+	textBuf = "";
+	/** usage chunk（无则 undefined）。 */
+	_usage;
+	/** finish chunk（流结束仍无则视为 stop）。 */
+	_finish;
+	/** 喂入一个流 chunk（仅消费文本/usage/finish，其余忽略）。 */
+	push(chunk) {
+		switch (chunk.type) {
+			case "text-delta":
+				this.textBuf += chunk.text;
+				break;
+			case "usage":
+				this._usage = chunk.usage;
+				break;
+			case "finish": this._finish = chunk.reason;
+		}
+	}
+	/** 拼接后的文本输出。 */
+	get text() {
+		return this.textBuf;
+	}
+	/** 摘要 token usage（无则 undefined）。 */
+	get usage() {
+		return this._usage;
+	}
+	/** 终止原因（流未给出 finish 时视为 stop）。 */
+	get finish() {
+		return this._finish ?? { kind: "stop" };
+	}
+};
 /**
-* 提取 fork 子会话（run.localAgent.session）的 token usage：仅统计子会话自身事件
-* （firstLiveSeq 之后，不含继承的父会话 seed 前缀），按 turn/step 去重（同 step 的
-* usage chunk 与 assistant/message 后写覆盖）后累加四桶；无 usage 返回 undefined。
-*/
-function extractSubagentUsage(agent) {
-	if (!agent) return void 0;
-	/** 子会话自身事件的起点（构造 seed 长度；缺省回退 0）。 */
-	const start = Number.isFinite(agent.session.firstLiveSeq) ? agent.session.firstLiveSeq : 0;
-	/** 子会话自身事件（跳过继承的父会话前缀）。 */
-	const ownEvents = agent.session.events.slice(start);
-	/** turn/step → usage（同 step 后写覆盖，与宿主投影语义一致）。 */
-	const perStep = /* @__PURE__ */ new Map();
-	for (const event of ownEvents) if (event.type === "assistant/message" && event.data.usage !== void 0) perStep.set(`${event.data.turn}:${event.data.step}`, event.data.usage);
-	else if (event.type === "assistant/chunk" && event.data.chunk.type === "usage") perStep.set(`${event.data.turn}:${event.data.step}`, event.data.chunk.usage);
-	if (perStep.size === 0) return void 0;
-	/** 累加结果（四桶互斥，不重复累加推理 token）。 */
-	const total = {
-		inputTokens: 0,
-		outputTokens: 0,
-		cacheReadTokens: 0,
-		cacheWriteTokens: 0
+* 渲染表层消息记录（new 模式输入）：按表层顺序分组为合法 XML——
+*  - 用户消息 → <user_message id="(message_id)">(原文)</user_message>；
+*  - 连续 AI 消息（assistant/message 与其后的 tool/result）聚合为一个
+*    <assistant last_id="(组内最后一条消息的 message_id)">(各消息文本)</assistant>。
+* 组内文本沿用 role 头 + message_id + 文本（tool-call 展开参数、tool-result 取文本）。
+*/
+function renderMessages(session, seqs) {
+	/** 渲染段缓冲区。 */
+	const parts = [];
+	/** 当前 assistant 组（组内消息文本行 + 最后一条消息 id）。 */
+	let group;
+	/** 结束当前 assistant 组并输出 <assistant> 块。 */
+	const flush = () => {
+		if (!group || group.lines.length === 0) return;
+		/** last_id 属性（组内最后一条消息 id；缺失/空串则省略）。 */
+		const lastAttr = group.lastId ? ` last_id="${group.lastId}"` : "";
+		parts.push(`<assistant${lastAttr}>\n${group.lines.join("\n")}\n</assistant>`);
+		group = void 0;
 	};
-	for (const usage of perStep.values()) {
-		total.inputTokens += usage.inputTokens;
-		total.outputTokens += usage.outputTokens;
-		total.cacheReadTokens = (total.cacheReadTokens ?? 0) + (usage.cacheReadTokens ?? 0);
-		total.cacheWriteTokens = (total.cacheWriteTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+	for (const seq of seqs) {
+		/** 当前待渲染事件。 */
+		const event = session.events[seq];
+		if (!event) continue;
+		/** 消息 id（缺失则省略）。 */
+		const id = messageIdOfEvent(event);
+		/** 消息文本呈现。 */
+		const text = renderMessageText(session.deriveEventMessage(event));
+		if (event.type === "user/message") {
+			flush();
+			/** id 属性（缺失/空串则省略）。 */
+			const idAttr = id ? ` id="${id}"` : "";
+			parts.push(`<user_message${idAttr}>\n${text}\n</user_message>`);
+		} else if (event.type === "assistant/message" || event.type === "tool/result") {
+			if (!group) group = {
+				lines: [],
+				lastId: void 0
+			};
+			/** role 标签（tool/result 属 user 角色但标注为工具结果）。 */
+			const role = event.type === "assistant/message" ? "assistant" : "tool/result";
+			group.lines.push(`--- ${role}${id ? ` message_id=${id}` : ""} ---\n${text}`);
+			if (id) group.lastId = id;
+		}
 	}
-	return total;
+	flush();
+	return parts.join("\n\n");
+}
+/** 构造插件自产 user 消息（指令或 new 模式的输入消息；id 为品牌类型 MessageId）。 */
+function makePluginUserMessage(text) {
+	return {
+		id: uuid(),
+		role: "user",
+		content: [{
+			type: "text",
+			text
+		}],
+		source: {
+			kind: "plugin",
+			plugin: PLUGIN_LABEL
+		}
+	};
 }
 /**
-* Fork 子会话执行一次摘要（观察或反思），返回文本与可选 token usage；
-* 失败或无法 fork 返回 null。工具被 toolFilter 禁用，输出长度受 maxTokens 限制。
+* 构建摘要请求选项：
+*  - fork：system/tools 取自主会话 requestHeader()，messages = 完整派生历史（从尾部
+*    tailCount 条消息之前开始，尾部不注入） + 指令 user 消息；
+*  - new：system = 指令，messages = 渲染输入（被压缩消息）user 消息。
 */
-async function runSummarySubagent(ctx, agent, persona, prompt, maxTokens, signal) {
-	/** subagents 服务（缺失则无法分叉摘要）。 */
-	const subagents = ctx.get("subagents");
-	if (!subagents) {
-		ctx.logger.warn("dsh-plugin-om: 未找到 subagents 服务，跳过摘要分叉");
-		return null;
-	}
-	if (!subagents.getProvider("fork")) {
-		ctx.logger.warn("dsh-plugin-om: fork 子代理提供方未注册，跳过摘要分叉");
-		return null;
-	}
-	/** 本次 fork 运行的句柄（用于取结果与 dispose）。 */
-	let run;
-	try {
-		run = await subagents.start("fork", {
-			label: "om-summary",
-			prompt: [{
-				type: "text",
-				text: prompt
-			}],
-			parent: agent,
-			persona,
-			toolFilter: { allow: [] },
-			agentOptions: { maxTokens },
-			...signal !== void 0 ? { signal } : {}
-		});
-		/** 子代理运行结果。 */
-		const result = await run.result;
-		/** 拼接、去标签、去首尾空白的摘要文本。 */
-		const text = blocksToText(Array.isArray(result.output) ? result.output : []).trim().replace(new RegExp(`</?${HISTORY_TAG}>`, "g"), "").trim();
-		if (result.stopReason !== "completed" || text.length === 0) {
-			ctx.logger.warn("dsh-plugin-om: 摘要未完成（" + (result.stopReason === "completed" ? "无输出" : String(result.stopReason)) + "），忽略本次摘要");
+function buildSummaryOptions(session, instruction, contextText, maxTokens, mode, tailCount, target, signal) {
+	/** 公共请求字段（provider/model/输出上限/会话归属/用途/取消）。 */
+	const base = {
+		provider: target.provider,
+		model: target.model,
+		maxTokens,
+		sessionId: session.id,
+		purpose: "compaction",
+		...signal === void 0 ? {} : { signal }
+	};
+	if (mode === "new") return {
+		...base,
+		system: instruction,
+		messages: [makePluginUserMessage(contextText ?? "")]
+	};
+	/** 主会话上次请求的请求头（system/tools 前缀对齐；无则省略）。 */
+	const header = session.requestHeader();
+	/** 主会话派生历史（从尾部 tailCount 条消息之前开始，实际截断尾部）。 */
+	const history = session.deriveMessages();
+	const forked = tailCount > 0 && tailCount < history.length ? history.slice(0, history.length - tailCount) : history;
+	return {
+		...base,
+		...header?.system === void 0 ? {} : { system: header.system },
+		...header?.tools === void 0 ? {} : { tools: [...header.tools] },
+		messages: [...forked, makePluginUserMessage(instruction)]
+	};
+}
+/** 产出日志后插入首个 <om-history> 后的格式说明（XML 注释，避免被误读为日志条目）。 */
+const HISTORY_FORMAT_NOTE = "<!-- <user_message>块内包含了用户的原文 id表示该消息的id；<assistant>块是多条ai连续消息的聚合，last_id指向最后一条消息 -->";
+/**
+* 从 AI 摘要输出中提取合法日志（不信任 AI 的总结结果）：
+*  - 取首个 <om-history> 到最后一个 </om-history>（含两个首尾）切为日志；
+*  - 找不到、顺序颠倒（首个开标签在最后一个闭标签之后）或中间内容长度 < MIN_HISTORY_LENGTH
+*    视为不合法（返回 null，调用方按失败重试）；
+*  - 产出后在首个 <om-history> 后插入格式说明注释（HISTORY_FORMAT_NOTE）。
+*/
+function extractSummaryLog(raw) {
+	/** 开标签。 */
+	const openTag = `<${HISTORY_TAG}>`;
+	/** 闭标签。 */
+	const closeTag = `</${HISTORY_TAG}>`;
+	/** 首个开标签位置（无则 -1）。 */
+	const open = raw.indexOf(openTag);
+	/** 最后一个闭标签位置（无则 -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;
+	return raw.slice(open, close + closeTag.length).replace(openTag, `${openTag}\n${HISTORY_FORMAT_NOTE}`);
+}
+/**
+* 直连 LLM 执行一次摘要（观察或反思），返回文本与可选 token usage。
+* 失败（抛异常 / 空输出 / 非 stop 结束）均记录日志并重试，总共最多尝试
+* SUMMARY_MAX_ATTEMPTS 次；全部尝试失败返回 null（不产生任何日志变更）。
+* 输出长度受 maxTokens 限制。
+*/
+async function runSummarySubagent(ctx, agent, instruction, contextText, maxTokens, mode, tailCount, target, debug, signal) {
+	/** 当前会话。 */
+	const session = agent.session;
+	/** 插件日志门面（失败日志始终输出）。 */
+	const logger = makeLogger(ctx, debug);
+	/** 最后一次失败的原因（error=调用异常 / finish=未完成原因；最终失败日志使用）。 */
+	let lastFailure = {};
+	for (let attempt = 1; attempt <= 3; attempt += 1) {
+		if (signal?.aborted) {
+			logger.warn(`摘要调用中止（第 ${attempt}/3 次尝试前 signal 已中止），放弃本次摘要`);
 			return null;
 		}
-		/** fork 子会话的 token usage（归入主会话记录；无则省略）。 */
-		const usage = extractSubagentUsage(run.localAgent);
-		return {
-			text,
-			...usage === void 0 ? {} : { usage }
-		};
-	} catch (error) {
-		/** 错误信息（统一为字符串）。 */
-		const message = error instanceof Error ? error.message : String(error);
-		ctx.logger.warn(`dsh-plugin-om: 摘要子代理失败: ${message}，忽略`);
-		return null;
-	} finally {
-		if (run && typeof run.dispose === "function") try {
-			await run.dispose();
-		} catch {}
+		logger.step(`摘要调用开始（第 ${attempt}/3 次，模式 ${mode}，provider ${target.provider}，model ${target.model}，maxTokens ${maxTokens}）`);
+		try {
+			/** 摘要请求选项（按模式组装）。 */
+			const options = buildSummaryOptions(session, instruction, contextText, maxTokens, mode, tailCount, target, signal);
+			/** 流收集器（文本/usage/finish）。 */
+			const collector = new StreamCollector();
+			for await (const chunk of ctx.llm.stream(options)) collector.push(chunk);
+			/** 提取合法日志（首个 <om-history> 到最后一个 </om-history>，含格式说明注释；不信任 AI 输出）。 */
+			const text = extractSummaryLog(collector.text);
+			/** 终止原因（仅 stop 视为完成）。 */
+			const finish = collector.finish;
+			if (finish.kind !== "stop" || text === null) {
+				/** 未完成原因（空输出 / 非法日志 / 非 stop 终止原因）。 */
+				const reason = finish.kind === "stop" ? collector.text.trim() === "" ? "无输出" : "缺少 <om-history> 块或内容过短" : String(finish.kind);
+				lastFailure = { finish: reason };
+				logger.warn(`摘要未完成（第 ${attempt}/3 次，${reason}）` + (attempt < 3 ? "，将重试" : "，重试耗尽，忽略本次摘要"));
+				continue;
+			}
+			/** 摘要请求的 token usage（归入主会话记录；无则省略）。 */
+			const usage = collector.usage;
+			logger.step(`摘要调用成功（第 ${attempt}/3 次，输出 ${text.length} 字符` + (usage === void 0 ? "" : `，input ${String(usage.inputTokens ?? "?")} / output ${String(usage.outputTokens ?? "?")} tokens`) + "）");
+			return {
+				text,
+				...usage === void 0 ? {} : { usage }
+			};
+		} catch (error) {
+			/** 错误信息（统一为字符串）。 */
+			const message = error instanceof Error ? error.message : String(error);
+			lastFailure = { error: message };
+			logger.warn(`摘要调用失败（第 ${attempt}/3 次，${message}）` + (attempt < 3 ? "，将重试" : "，重试耗尽，忽略本次摘要"));
+		}
 	}
+	/** 全部尝试失败：记录最终失败日志（含最后原因，便于诊断）。 */
+	logger.warn(`摘要调用最终失败（已尝试 3 次` + (lastFailure.error !== void 0 ? `，最后错误：${lastFailure.error}` : "") + (lastFailure.finish !== void 0 ? `，最后结果：${lastFailure.finish}` : "") + "），忽略本次摘要");
+	return null;
 }
 //#endregion
 //#region src/compress.ts
 /**
 * 自动压缩（OM 观察/反思两级阈值，思路参考 Mastra Observational Memory）：
-*  - 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio → fork 子会话把未压缩消息压缩为
-*    观察日志，追加到旧摘要（<om-history> 原文保留），替换被压缩消息区间；
-*  - 反思：摘要 tokens ≥ 窗口 × historyMergeRatio（默认 0.2）→ fork 子会话精简合并摘要，
+*  - 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio → 直连 ctx.llm.stream() 摘要
+*    （fork 模式复用主会话请求前缀缓存；new 模式指令作为 system）把未压缩消息压缩为
+*    观察日志，以新的 <om-history> 块追加到旧日志（多块按序拼接），替换被压缩消息区间；
+*  - 反思：摘要 tokens ≥ 窗口 × historyMergeRatio（默认 0.2）→ 同上摘要调用精简合并摘要，
 *    替换单个 <om-history> 节点。
 * 两级检查在 pre-step 阻塞串行执行（先反思后观察），避免压缩失败或重复压缩。
 *
@@ -282,24 +450,36 @@ async function runSummarySubagent(ctx, agent, persona, prompt, maxTokens, signal
 * 替换 <om-history> 消息 → compaction/end），使消息记录（聊天视图压缩卡片）与轨迹视图
 * 可见；compaction/summary 同时承担影子价格认领（shadowedTokenCount），不再单独发
 * compaction/prune。替换消息的 source 使用宿主 checkpoint 标记（plugin: 'compact' +
-* compactionId），UI 据此关联 summary 与替换消息。生命周期事件在 fork 摘要成功后才写入
+* compactionId），UI 据此关联 summary 与替换消息。生命周期事件在摘要成功后才写入
 * （失败不产生任何日志变更）。
 *
-* 观察区间：尾部保留 config.tailMessageCount（默认 10）条消息不压缩；
-* 其余全部未压缩消息一次压缩。fork seed 截断于最后一个 turn/end，
-* 故区间表层节点封顶在最后一个已结束 turn 的表层节点（当前 turn 消息留待下次）。
+* 观察区间：pre-step 触发时日志 call-result 完备，区间不再受 turn/end 封顶——头部 →
+* 表层长度-1-tailCount（尾部保留 config.tailMessageCount 条不压缩，作为摘要模型的
+* 参考尾部），当前 turn 中已完备的消息同样可压缩；区间终点回退到 tool-call/result
+* 配对平衡点（不切段）。
 * 仅主会话生效。
 */
 /** 历史文本 token 估算：4 字符 ≈ 1 token（与宿主 dsh-token-meter 启发式一致）。 */
 function estimateTextTokens(text) {
 	return Math.ceil(text.length / 4);
 }
-/** 提取 <om-history> 压缩日志消息的内文（去掉标签）；非压缩日志消息返回 undefined。 */
+/**
+* 判定消息是否为本插件的压缩日志消息并提取日志文本（D：不通过文本含 <om-history> 判断，
+* 改用 source 标记——plugin 为宿主 checkpoint 标记 'compact' 或插件标识 'dsh-plugin-om'）。
+* 日志文本取首个 <om-history> 起的内容（含标签与格式说明注释，多块拼接时返回全部块）；
+* 非压缩日志消息返回 undefined。
+*/
 function historyTextOf(event) {
 	if (event?.type !== "user/message") return void 0;
+	/** 消息 source（插件自产消息的标记）。 */
+	const source = event.data.source;
+	if (source?.kind !== "plugin") return void 0;
+	if (source.plugin !== "compact" && source.plugin !== "dsh-plugin-om") return void 0;
 	/** 消息纯文本。 */
 	const text = blocksToText(event.data.content);
-	return text.includes(`<om-history>`) ? text.replace(new RegExp(`</?${HISTORY_TAG}>`, "g"), "").trim() : void 0;
+	/** 首个 <om-history> 的位置（日志文本起点；无则整段视为日志）。 */
+	const start = text.indexOf(`<${HISTORY_TAG}>`);
+	return start === -1 ? text : text.slice(start);
 }
 /**
 * 未压缩消息 token 估算：表层节点合计，不含 <om-history> 摘要节点
@@ -332,30 +512,45 @@ function findLatestHistory(session) {
 	}
 }
 /**
-* 观察压缩区间：尾部保留 tailCount 条消息不压缩，区间封顶在最后一个已结束 turn 的
-* 表层节点（fork seed 截断于最后一个 turn/end，当前 turn 消息不可压缩）。
+* 判定表层节点 seq 之后的切点是否 tool-call/result 配对平衡（与宿主
+* dsh-compaction 的 toolPairingBalancedAfter 同语义）：按表层顺序折叠未闭合的
+* 工具调用数，处理到 seq 后计数为 0 即平衡。pre-step 时日志 call-result 完备，
+* 该检查作为区间边界的安全网（防止把助手 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;
+		if (node === seq) return inProgress === 0;
+	}
+	return false;
+}
+/**
+* 观察压缩区间：pre-step 触发时日志 call-result 完备，区间不再受 turn/end 封顶——
+* 头部 → 表层长度-1-tailCount（尾部保留 tailCount 条不压缩），当前 turn 中已完备的
+* 消息同样可压缩；区间终点回退到 tool-call/result 配对平衡点（不切段）。
+* lastEndSeq 仅为中断扫描提供最后一个已结束 turn 的边界（无则 -1）。
 */
 function computeCompressRange(session, tailCount) {
 	/** 当前表层节点（按日志顺序）。 */
 	const surface = [...session.surface.nodes];
 	if (surface.length === 0) return void 0;
-	/** 最后一个 turn/end（fork seed 截断于此；无则无可压缩内容）。 */
-	const lastEnd = session.events.findLast((event) => event.type === "turn/end");
-	if (!lastEnd) return void 0;
-	/** seed 覆盖的最后表层节点下标（其后为当前 turn 消息，不可压缩）。 */
-	let seedIdx = -1;
-	for (let i = surface.length - 1; i >= 0; i -= 1) {
-		const node = surface[i];
-		if (node !== void 0 && node <= lastEnd.seq) {
-			seedIdx = i;
-			break;
-		}
+	/** 区间末表层节点下标（尾部保留 tailCount 条不压缩）。 */
+	let endIdx = surface.length - 1 - tailCount;
+	if (endIdx < 0) return void 0;
+	/** 区间终点回退到配对平衡点（不切断 tool-call/result 配对）。 */
+	while (endIdx >= 0) {
+		/** 当前候选终点节点（表层节点序列稠密，防御性判空）。 */
+		const node = surface[endIdx];
+		if (node === void 0 || isPairBalancedAfter(session, node)) break;
+		endIdx -= 1;
 	}
-	if (seedIdx === -1) return void 0;
-	/** 区间末表层节点下标（尾部保留与 seed 封顶取小）。 */
-	const endIdx = Math.min(surface.length - 1 - tailCount, seedIdx);
 	if (endIdx < 0) return void 0;
-	/** 区间起点（表层首节点）。 */
+	/** 区间起点（表层首节点，含旧 <om-history> 时一并合并）。 */
 	const start = surface[0];
 	/** 区间终点（表层节点 seq）。 */
 	const end = surface[endIdx];
@@ -364,7 +559,7 @@ function computeCompressRange(session, tailCount) {
 		start,
 		end,
 		shadowedSeqs: surface.slice(0, endIdx + 1),
-		lastEndSeq: lastEnd.seq
+		lastEndSeq: session.events.findLast((event) => event.type === "turn/end")?.seq ?? -1
 	};
 }
 /**
@@ -409,7 +604,7 @@ function extractHistoryText(session, shadowedSeqs) {
 }
 /**
 * message_id 对照表：遮蔽区间内消息事件按表层顺序产出 id 行（插件自产 user/message
-* 如运行时上下文快照与 <om-history> 不入表；观察子会话据此产出正确的 message_id）。
+* 如运行时上下文快照与 <om-history> 不入表；观察摘要据此产出正确的 message_id）。
 * 按表层顺序（shadowedSeqs）扫描：与 extractHistoryText 同理，seq 区间扫描会漏。
 */
 function buildMessageIdTable(session, shadowedSeqs) {
@@ -432,7 +627,7 @@ function buildMessageIdTable(session, shadowedSeqs) {
 			/** 结果消息 id。 */
 			const id = messageIdOfEvent(event);
 			if (id) {
-				/** 关联调用 id（供子会话按 callId 定位代码与结果）。 */
+				/** 关联调用 id（供摘要模型按 callId 定位代码与结果）。 */
 				const callId = String(event.data.message.source.callId ?? "");
 				rows.push(`[tool/result callId=${callId}] message_id=${id}`);
 			}
@@ -458,7 +653,7 @@ function appendCompactionStart(session, lifecycle) {
 }
 /**
 * 追加 compaction/summary（log-only，承担影子价格认领：紧随其后的替换消息消费 claim）。
-* summary 为完整合并后的 <om-history> 内文；usage 由 fork 子会话提取（无则省略）。
+* summary 为完整合并后的 <om-history> 内文；usage 由摘要调用提取（无则省略）。
 */
 function appendCompactionSummary(session, data) {
 	return session.append("compaction/summary", {
@@ -486,7 +681,7 @@ function appendCompactionEnd(session, lifecycle, error) {
 }
 /** 追加 <om-history> 压缩日志消息（surfaceOp 替换遮蔽区间，source 为宿主 checkpoint 标记）。 */
 function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp, compactionId) {
-	/** 压缩替换消息（<om-history> 包裹摘要，source 标记宿主 checkpoint 供 UI 关联）。 */
+	/** 压缩替换消息（内容已含 <om-history> 标签块，不再额外包裹；source 标记宿主 checkpoint 供 UI 关联）。 */
 	const message = {
 		id: uuid(),
 		role: "user",
@@ -495,9 +690,7 @@ function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp, comp
 			text: [
 				"以下是过往会话的压缩日志（<om-history>），为已确立背景：直接继续，不要复述。",
 				"",
-				`<${HISTORY_TAG}>`,
-				content,
-				`</${HISTORY_TAG}>`
+				content
 			].join("\n")
 		}],
 		source: {
@@ -512,35 +705,54 @@ function appendHistoryMessage(session, content, sourceEventSeqs, surfaceOp, comp
 	});
 }
 /**
-* 反思：摘要 tokens ≥ 窗口 × historyMergeRatio 时，fork 子会话精简合并摘要，
+* 反思：摘要 tokens ≥ 窗口 × historyMergeRatio 时，摘要调用精简合并摘要，
 * 替换单个 <om-history> 节点。失败不产生部分替换。
 */
 async function reflectPass(ctx, agent, config, window, target, signal) {
 	/** 当前会话。 */
 	const session = agent.session;
+	/** 插件日志门面。 */
+	const logger = makeLogger(ctx, config.debug);
+	logger.step(`反思检查（窗口 ${window} × historyMergeRatio ${config.historyMergeRatio}）`);
 	/** 当前摘要（最后一次 <om-history>；无则跳过）。 */
 	const history = findLatestHistory(session);
-	if (!history) return;
+	if (!history) {
+		logger.step("反思：无 <om-history> 压缩日志，跳过");
+		return;
+	}
 	/** 反思阈值（窗口 × historyMergeRatio 向下取整）。 */
 	const threshold = Math.floor(window * config.historyMergeRatio);
 	/** 摘要 token 估算。 */
 	const tokens = estimateTextTokens(history.text);
-	if (tokens < threshold) return;
+	if (tokens < threshold) {
+		logger.step(`反思：摘要 ${tokens} tokens < 阈值 ${threshold}，跳过`);
+		return;
+	}
+	logger.step(`反思：摘要 ${tokens} tokens ≥ 阈值 ${threshold}，触发精简合并`);
 	/** 摘要节点须仍在表层才可替换。 */
-	if (surfaceIndexOf([...session.surface.nodes], history.seq) === -1) return;
-	/** 反思子会话结果（null 表示失败/跳过）。 */
-	const summaryResult = await runSummarySubagent(ctx, agent, REFLECTOR_PERSONA, buildReflectPrompt(), config.compressMaxTokens, signal);
-	if (summaryResult === null || summaryResult.text.trim().length === 0) return;
+	if (surfaceIndexOf([...session.surface.nodes], history.seq) === -1) {
+		logger.step("反思：摘要节点已不在表层，跳过");
+		return;
+	}
+	/** 反思摘要结果（null 表示失败/跳过）。 */
+	const summaryResult = await runSummarySubagent(ctx, agent, `${REFLECTOR_PERSONA}\n\n${buildReflectPrompt(config.summaryMode)}`, config.summaryMode === "new" ? history.text : void 0, config.compressMaxTokens, config.summaryMode, 0, target, config.debug, signal);
+	if (summaryResult === null || summaryResult.text.trim().length === 0) {
+		logger.step("反思：摘要调用失败/无输出，不产生替换");
+		return;
+	}
 	/** 反思摘要文本。 */
 	const report = summaryResult.text;
-	/** 本次压缩生命周期（compactionId + 当前轮次；fork 成功后才写入日志）。 */
+	/** 本次压缩生命周期（compactionId + 当前轮次；摘要成功后才写入日志）。 */
 	const lifecycle = {
 		compactionId: newCompactionId(),
 		turn: openTurnOf(session)
 	};
 	try {
+		logger.step("反思提交：追加 compaction/start");
 		appendCompactionStart(session, lifecycle);
-		appendHistoryMessage(session, report, [appendCompactionSummary(session, {
+		logger.step("反思提交：追加 compaction/summary（影子价格认领）");
+		/** compaction/summary 事件 seq（承担影子价格认领，紧随其后的替换消息消费）。 */
+		const summarySeq = appendCompactionSummary(session, {
 			lifecycle,
 			summary: report,
 			shadowedRange: {
@@ -553,50 +765,72 @@ async function reflectPass(ctx, agent, config, window, target, signal) {
 			model: target.model,
 			maxTokens: config.compressMaxTokens,
 			...summaryResult.usage === void 0 ? {} : { usage: summaryResult.usage }
-		}), history.seq], {
+		});
+		logger.step("反思提交：替换 <om-history> 摘要节点");
+		appendHistoryMessage(session, report, [summarySeq, history.seq], {
 			op: "replace",
 			start: history.seq,
 			end: history.seq
 		}, lifecycle.compactionId);
+		logger.step("反思提交：追加 compaction/end");
 		appendCompactionEnd(session, lifecycle);
-		ctx.logger.info(`dsh-plugin-om: 反思完成（摘要 ${tokens} tokens ≥ 阈值 ${threshold}，替换摘要节点）`);
+		logger.info(`反思完成（摘要 ${tokens} tokens ≥ 阈值 ${threshold}，替换摘要节点）`);
 	} catch (error) {
 		/** 提交失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
-		ctx.logger.warn(`dsh-plugin-om: 反思提交失败: ${message}`);
+		logger.warn(`反思提交失败: ${message}`);
 		try {
 			appendCompactionEnd(session, lifecycle, message);
 		} catch {}
 	}
 }
 /**
-* 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio 时，fork 子会话把未压缩消息压缩为
+* 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio 时，摘要调用把未压缩消息压缩为
 * 观察日志，追加到旧摘要并替换被压缩消息区间。失败不产生部分替换。
 */
 async function observePass(ctx, agent, config, window, tailCount, target, signal) {
 	/** 当前会话。 */
 	const session = agent.session;
+	/** 插件日志门面。 */
+	const logger = makeLogger(ctx, config.debug);
+	logger.step(`观察检查（窗口 ${window} × thresholdRatio ${config.thresholdRatio}，尾部保留 ${tailCount} 条）`);
 	/** 观察阈值（窗口 × thresholdRatio 向下取整）。 */
 	const threshold = Math.floor(window * config.thresholdRatio);
 	/** 未压缩消息 token 估算（不含 <om-history> 摘要节点）。 */
 	const uncompressedTokens = measureUncompressedTokens(session, ctx.tokenMeter);
-	if (uncompressedTokens < threshold) return;
-	/** 观察压缩区间（尾部保留 tailCount 条 + seed 封顶；无可行区间则跳过）。 */
+	if (uncompressedTokens < threshold) {
+		logger.step(`观察：未压缩消息 ${uncompressedTokens} tokens < 阈值 ${threshold}，跳过`);
+		return;
+	}
+	logger.step(`观察：未压缩消息 ${uncompressedTokens} tokens ≥ 阈值 ${threshold}，触发压缩`);
+	/** 观察压缩区间（尾部保留 tailCount 条不压缩；无可行区间则跳过）。 */
 	const range = computeCompressRange(session, tailCount);
-	if (!range) return;
+	if (!range) {
+		logger.step("观察：无可行压缩区间（表层过短或配对无法平衡），跳过");
+		return;
+	}
+	logger.step(`观察：压缩区间 [${range.start}..${range.end}]，遮蔽 ${range.shadowedSeqs.length} 个表层节点`);
 	/** 区间内旧摘要（追加基准；无则首次压缩）。 */
 	const history = extractHistoryText(session, range.shadowedSeqs);
 	/** 中断标记行。 */
 	const interruptions = scanInterruptions(session, Math.min(...range.shadowedSeqs), range.lastEndSeq);
-	/** 观察提示词。 */
+	/** message_id 对照表行。 */
+	const table = buildMessageIdTable(session, range.shadowedSeqs);
+	const actualTailCount = [...session.surface.nodes].length - range.shadowedSeqs.length;
+	logger.step(`观察：实际保留尾部 ${actualTailCount} 条（不压缩、不进日志），中断标记 ${interruptions.length} 条，message_id 对照表 ${table.length} 行`);
+	/** 观察指令（persona + 规则主体）。 */
 	const prompt = buildObservePrompt({
-		table: buildMessageIdTable(session, range.shadowedSeqs),
+		table,
 		interruptions,
-		hasOldHistory: history !== void 0
+		hasOldHistory: history !== void 0,
+		mode: config.summaryMode
 	});
-	/** 观察子会话结果（null 表示失败/跳过）。 */
-	const summaryResult = await runSummarySubagent(ctx, agent, OBSERVER_PERSONA, prompt, config.compressMaxTokens, signal);
-	if (summaryResult === null || summaryResult.text.trim().length === 0) return;
+	/** 观察摘要结果（null 表示失败/跳过）。 */
+	const summaryResult = await runSummarySubagent(ctx, agent, `${OBSERVER_PERSONA}\n\n${prompt}`, config.summaryMode === "new" ? renderMessages(session, range.shadowedSeqs.filter((seq) => historyTextOf(session.events[seq]) === void 0)) : void 0, config.compressMaxTokens, config.summaryMode, actualTailCount, target, config.debug, signal);
+	if (summaryResult === null || summaryResult.text.trim().length === 0) {
+		logger.step("观察：摘要调用失败/无输出，不产生替换");
+		return;
+	}
 	/** 观察摘要文本。 */
 	const report = summaryResult.text;
 	/** 合并后的摘要（旧摘要原文保留，新观察日志追加在末尾）。 */
@@ -609,14 +843,17 @@ async function observePass(ctx, agent, config, window, tailCount, target, signal
 		const message = event ? session.deriveEventMessage(event) : null;
 		return total + (message ? ctx.tokenMeter.estimateMessage(message) : 0);
 	}, 0);
-	/** 本次压缩生命周期（compactionId + 当前轮次；fork 成功后才写入日志）。 */
+	/** 本次压缩生命周期（compactionId + 当前轮次；摘要成功后才写入日志）。 */
 	const lifecycle = {
 		compactionId: newCompactionId(),
 		turn: openTurnOf(session)
 	};
 	try {
+		logger.step("观察提交：追加 compaction/start");
 		appendCompactionStart(session, lifecycle);
-		appendHistoryMessage(session, combined, [appendCompactionSummary(session, {
+		logger.step("观察提交：追加 compaction/summary（影子价格认领）");
+		/** compaction/summary 事件 seq（承担影子价格认领，紧随其后的替换消息消费）。 */
+		const summarySeq = appendCompactionSummary(session, {
 			lifecycle,
 			summary: combined,
 			shadowedRange: {
@@ -629,17 +866,20 @@ async function observePass(ctx, agent, config, window, tailCount, target, signal
 			model: target.model,
 			maxTokens: config.compressMaxTokens,
 			...summaryResult.usage === void 0 ? {} : { usage: summaryResult.usage }
-		}), ...range.shadowedSeqs], {
+		});
+		logger.step("观察提交：替换被压缩消息区间为 <om-history>");
+		appendHistoryMessage(session, combined, [summarySeq, ...range.shadowedSeqs], {
 			op: "replace",
 			start: range.start,
 			end: range.end
 		}, lifecycle.compactionId);
+		logger.step("观察提交：追加 compaction/end");
 		appendCompactionEnd(session, lifecycle);
-		ctx.logger.info(`dsh-plugin-om: 观察压缩完成（未压缩 ${uncompressedTokens} tokens ≥ 阈值 ${threshold}，遮蔽 ${range.shadowedSeqs.length} 个表层节点，约 ${shadowedTokenCount} tokens）`);
+		logger.info(`观察压缩完成（未压缩 ${uncompressedTokens} tokens ≥ 阈值 ${threshold}，遮蔽 ${range.shadowedSeqs.length} 个表层节点，约 ${shadowedTokenCount} tokens）`);
 	} catch (error) {
 		/** 提交失败信息（统一字符串）。 */
 		const message = error instanceof Error ? error.message : String(error);
-		ctx.logger.warn(`dsh-plugin-om: 观察压缩提交失败: ${message}`);
+		logger.warn(`观察压缩提交失败: ${message}`);
 		try {
 			appendCompactionEnd(session, lifecycle, message);
 		} catch {}
@@ -652,24 +892,226 @@ async function observePass(ctx, agent, config, window, tailCount, target, signal
 async function maybeCompress(ctx, agent, config, signal) {
 	/** 当前会话。 */
 	const session = agent.session;
+	/** 插件日志门面。 */
+	const logger = makeLogger(ctx, config.debug);
+	/** disable 模式：关闭自动压缩（观察/反思均不触发，recall 工具不受影响）。 */
+	if (config.summaryMode === "disable") {
+		logger.step("summaryMode=disable，跳过压缩");
+		return;
+	}
 	/** 会话路由目标（未路由无法查询容量）。 */
 	const target = routedTarget(session);
-	if (target === void 0) return;
+	if (target === void 0) {
+		logger.step("会话未路由（无 provider/model），跳过压缩");
+		return;
+	}
+	logger.step(`会话路由：provider ${target.provider}，model ${target.model}`);
 	/** 模型容量信息（contextWindow 决定两级阈值）。 */
 	let info;
 	try {
 		info = await ctx.llm.resolveModelInfo(target.provider, target.model, signal);
 	} catch (error) {
-		ctx.logger.warn("dsh-plugin-om: 解析模型容量失败: " + (error instanceof Error ? error.message : String(error)));
+		logger.warn(`解析模型容量失败: ${error instanceof Error ? error.message : String(error)}`);
 		return;
 	}
 	/** 模型上下文窗口大小（非法值视为无法压缩）。 */
 	const window = info.context?.contextWindow;
-	if (typeof window !== "number" || !Number.isFinite(window) || window <= 0) return;
+	if (typeof window !== "number" || !Number.isFinite(window) || window <= 0) {
+		logger.step(`模型上下文窗口非法（${String(window)}），跳过压缩`);
+		return;
+	}
+	logger.step(`模型上下文窗口 ${window} tokens，开始两级压缩（先反思后观察）`);
 	/** 尾部保留条数（config.tailMessageCount，缺省 10）。 */
 	const tailCount = config.tailMessageCount;
+	logger.step("反思 pass 开始");
 	await reflectPass(ctx, agent, config, window, target, signal);
+	logger.step("反思 pass 结束，观察 pass 开始");
 	await observePass(ctx, agent, config, window, tailCount, target, signal);
+	logger.step("观察 pass 结束，压缩流程完成");
+}
+//#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 默认 = 插件包内
+*   models/<id>/，与 embedding.ts 的本地加载路径一致；自定义 modelDir 同样生效）。
+* - 直连 huggingface.co 受限时设置环境变量 HF_ENDPOINT=https://hf-mirror.com 走镜像。
+* - 原子落盘：先写 .tmp 再改名，避免半截文件被当成完整模型加载。
+*
+* 运行时编排见 embedding.ts 的 ensureModelReady（下载单飞、未就绪不阻塞）；
+* 本模块只提供纯下载原语（供 src 与 scripts/download-model.mjs CLI 复用）。
+*/
+/** 模型标识（models/ 下目录名 = 模型 id；transformers.js 加载时的模型名）。 */
+const EMBEDDING_MODEL_ID = "paraphrase-multilingual-MiniLM-L12-v2";
+/** transformers.js 转换仓库（Xenova org）中量化 ONNX 文件的相对路径（相对模型目录）。 */
+const ONNX_REL = "onnx/model_quantized.onnx";
+/**
+* HuggingFace 原始文件 URL（resolve 会 302 到 CDN，fetch 自动跟随重定向）。
+* base 默认 huggingface.co，可用环境变量 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）。 */
+function modelTargetPath(modelDir, rel = ONNX_REL) {
+	return path.join(modelDir, rel);
+}
+/**
+* 是否需要下载（纯函数，供测试）。
+* force 强制下载；否则目标已存在即跳过。
+*/
+function needsDownload(target, { force = false } = {}) {
+	if (force) return true;
+	try {
+		statSync(target);
+		return false;
+	} catch {
+		return true;
+	}
+}
+/**
+* 下载模型到 <modelDir>/onnx/model_quantized.onnx。
+* 可注入 fetchImpl / log（供测试）；失败时清理临时文件并抛出。
+*/
+async function downloadModel(modelDir, { force = false, fetchImpl = fetch, log = console.log } = {}) {
+	const target = modelTargetPath(modelDir);
+	if (!needsDownload(target, { force })) {
+		log(`[download-model] 已存在，跳过：${target}`);
+		return {
+			downloaded: false,
+			bytes: 0,
+			target
+		};
+	}
+	const url = modelSourceUrl();
+	mkdirSync(path.dirname(target), { recursive: true });
+	const tmp = `${target}.tmp`;
+	try {
+		const resp = await fetchImpl(url);
+		if (!resp.ok) throw new Error(`下载失败：HTTP ${resp.status} ${resp.statusText}（${url}）`);
+		const buf = Buffer.from(await resp.arrayBuffer());
+		writeFileSync(tmp, buf);
+		renameSync(tmp, target);
+		log(`[download-model] 已下载 ${buf.length} 字节 → ${target}`);
+		return {
+			downloaded: true,
+			bytes: buf.length,
+			target
+		};
+	} catch (err) {
+		rmSync(tmp, { force: true });
+		throw err;
+	}
+}
+//#endregion
+//#region src/embedding.ts
+/**
+* 本地语义嵌入（recall-semantic 的向量引擎）。
+*
+* - 模型：Xenova/paraphrase-multilingual-MiniLM-L12-v2（量化 ONNX，多语言，
+*   中英 + 代码均可处理），模型文件在 models/ 下，完全离线、零下载。
+* - 运行时下载：模型 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 原生绑定。
+*/
+/** 当前模块所在路径（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);
+/** 单批最大文本数（避免单次推理过大）。 */
+const BATCH_SIZE = 32;
+/** 懒加载中的 pipeline 单例（null = 尚未加载/已重置）。 */
+let pipelinePromise = null;
+/**
+* 获取（或加载）嵌入函数。首次调用动态 import transformers 并加载本地模型；
+* 之后复用同一 pipeline。失败时抛出可读错误（调用方自行降级）。
+*/
+function getEmbedder(modelDir = BUNDLED_MODEL_DIR) {
+	if (pipelinePromise !== null) return pipelinePromise;
+	pipelinePromise = (async () => {
+		const { env, pipeline } = await import("@huggingface/transformers");
+		env.localModelPath = `${path.dirname(modelDir)}${path.sep}`;
+		env.allowLocalModels = true;
+		env.allowRemoteModels = false;
+		const extractor = await pipeline("feature-extraction", EMBEDDING_MODEL_ID, { dtype: "q8" });
+		return async (texts) => {
+			const vectors = [];
+			for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+				const batch = texts.slice(i, i + BATCH_SIZE);
+				const result = await extractor(batch, {
+					pooling: "mean",
+					normalize: true
+				});
+				/** 结果张量：dims = [batch, hidden]，data 为扁平数组。 */
+				const dims = result.dims;
+				const hidden = dims.length > 1 ? dims[1] : 0;
+				const data = result.data;
+				for (let j = 0; j < batch.length; j += 1) {
+					const start = j * hidden;
+					if (hidden > 0) vectors.push(Float32Array.from(Array.prototype.slice.call(data, start, start + hidden)));
+				}
+			}
+			return vectors;
+		};
+	})();
+	return pipelinePromise;
+}
+/** 每个 modelDir 的在途下载任务（单飞：并发查询只发起一次下载）。 */
+const inflightDownloads = /* @__PURE__ */ new Map();
+/**
+* 确保模型就绪（运行时按需下载编排）。
+* - 本地 onnx 已存在 → 'ready'（不触发下载）。
+* - 缺失 → 启动后台下载（不阻塞，单飞）并返回 'downloading'；下载失败仅调用
+*   warn 记录日志并结束本次尝试，下次调用会重新触发下载（自动重试）。
+* - warn 可选：下载失败时的日志回调（默认静默；apply 注入 ctx.logger.warn）。
+* - fetchImpl 可注入（测试传替身，默认全局 fetch）。
+*/
+function ensureModelReady(modelDir = BUNDLED_MODEL_DIR, warn = () => {}, fetchImpl) {
+	if (!needsDownload(modelTargetPath(modelDir))) return Promise.resolve("ready");
+	if (!inflightDownloads.has(modelDir)) {
+		const task = downloadModel(modelDir, fetchImpl === void 0 ? { log: () => {} } : {
+			fetchImpl,
+			log: () => {}
+		}).then(() => {}).catch((err) => {
+			warn("[download-model] 下载失败：" + (err instanceof Error ? err.message : String(err)));
+		}).finally(() => {
+			inflightDownloads.delete(modelDir);
+		});
+		inflightDownloads.set(modelDir, task);
+	}
+	return Promise.resolve("downloading");
+}
+/**
+* 两个向量的余弦相似度（向量已 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];
+		const y = b[i];
+		dot += x * y;
+		normA += x * x;
+		normB += y * y;
+	}
+	if (normA === 0 || normB === 0) return 0;
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }
 //#endregion
 //#region src/config.ts
@@ -677,46 +1119,36 @@ async function maybeCompress(ctx, agent, config, signal) {
 * 插件配置：默认值、键校验与合并（preset 行 config 可覆盖全部键）。
 * 手写校验，保持零运行时外部依赖。
 */
-/** 默认配置（冻结对象，resolveConfig 合并的基底）。 */
+/** 默认配置（冻结对象，resolveConfig 合并的基底；debug 缺省值在解析时按 NODE_ENV 判定）。 */
 const DEFAULT_CONFIG = Object.freeze({
 	thresholdRatio: .5,
 	historyMergeRatio: .2,
 	compressMaxTokens: 4096,
-	tailMessageCount: 10
+	tailMessageCount: 10,
+	summaryMode: "fork",
+	debug: false,
+	recallEnabled: true,
+	semanticRecallEnabled: true,
+	modelDir: BUNDLED_MODEL_DIR
 });
 /** 合法配置键集合（未知键直接拒绝）。 */
 const CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"thresholdRatio",
 	"historyMergeRatio",
 	"compressMaxTokens",
-	"tailMessageCount"
+	"tailMessageCount",
+	"summaryMode",
+	"debug",
+	"recallEnabled",
+	"semanticRecallEnabled",
+	"modelDir"
 ]);
-/** 数值键校验参数表：键名 + [min, max, integer]。 */
+/** 数值键校验参数表：键名 + [integer]。不限制取值区间——用户提供的值按原样接受（便于调试）。 */
 const NUMBER_KEYS = [
-	[
-		"thresholdRatio",
-		.01,
-		1,
-		false
-	],
-	[
-		"historyMergeRatio",
-		.01,
-		1,
-		false
-	],
-	[
-		"compressMaxTokens",
-		1,
-		Infinity,
-		true
-	],
-	[
-		"tailMessageCount",
-		1,
-		Infinity,
-		true
-	]
+	["thresholdRatio", false],
+	["historyMergeRatio", false],
+	["compressMaxTokens", true],
+	["tailMessageCount", true]
 ];
 /** 归一化原始配置输入：缺省 / null / 空串（含空白串）视为空对象（全部用默认值）。 */
 function normalizeConfigInput(raw) {
@@ -726,7 +1158,24 @@ function normalizeConfigInput(raw) {
 	return raw;
 }
 /**
-* 解析合并配置：校验未知键与数值类型，返回冻结的完整配置。
+* 解析摘要模式配置值：缺省 / 空串回退 fork；仅接受 'fork'/'new'/'disable'；
+* 其余值抛错（配置错误须立即可见）。
+*/
+function resolveSummaryMode(raw) {
+	if (raw === void 0 || raw === null) return "fork";
+	if (typeof raw === "string" && raw.trim() === "") return "fork";
+	if (raw === "fork" || raw === "new" || raw === "disable") return raw;
+	fail("config summaryMode must be \"fork\", \"new\" or \"disable\"");
+}
+/** 解析布尔配置值：缺省 / null / 空串回退默认值；必须为 boolean 否则抛错。 */
+function resolveBoolean(name, raw, defaultValue) {
+	if (raw === void 0 || raw === null) return defaultValue;
+	if (typeof raw === "string" && raw.trim() === "") return defaultValue;
+	if (typeof raw === "boolean") return raw;
+	fail(`config ${name} must be a boolean`);
+}
+/**
+* 解析合并配置：校验未知键与数值/字符串类型，返回冻结的完整配置。
 * 允许所有配置留空——缺省 / null / 空串的键回退默认值，未给出的键亦取默认值。
 */
 function resolveConfig(raw) {
@@ -735,18 +1184,28 @@ function resolveConfig(raw) {
 	for (const key of Object.keys(input)) if (!CONFIG_KEYS.has(key)) fail(`unknown config key "${key}"`);
 	/** 合并结果（以默认值为基底）。 */
 	const config = { ...DEFAULT_CONFIG };
-	for (const [key, min, max, integer] of NUMBER_KEYS) {
+	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;
-		assertNumber(key, value, {
-			min,
-			max,
-			integer
-		});
+		assertNumber(key, value, { integer });
 		config[key] = value;
 	}
+	/** 摘要模式（缺省 fork；非法值报错）。 */
+	config.summaryMode = resolveSummaryMode(input.summaryMode);
+	/** 步骤级日志开关（缺省按 NODE_ENV !== 'production' 判定）。 */
+	config.debug = resolveBoolean("debug", input.debug, process.env.NODE_ENV !== "production");
+	/** recall 工具开关（缺省启用）。 */
+	config.recallEnabled = resolveBoolean("recallEnabled", input.recallEnabled, true);
+	/** recall-semantic 工具开关（缺省启用）。 */
+	config.semanticRecallEnabled = resolveBoolean("semanticRecallEnabled", input.semanticRecallEnabled, true);
+	/** modelDir 原始值（留空回退默认；非空串必须为字符串）。 */
+	const modelDir = input.modelDir;
+	if (modelDir !== void 0 && modelDir !== null) {
+		if (typeof modelDir === "string" && modelDir.trim() !== "") config.modelDir = modelDir;
+		else assertNonEmptyString("modelDir", modelDir);
+	}
 	return Object.freeze(config);
 }
 //#endregion
@@ -870,6 +1329,248 @@ function buildRecallTool(getPruner) {
 	};
 }
 //#endregion
+//#region src/semantic-recall.ts
+/**
+* recall-semantic 工具：按自然语言 query 对会话全部消息日志（含被压缩/遮蔽的
+* user/assistant/tool-result 事件）做语义检索，返回最匹配的完整消息与匹配说明。
+*
+* - 参数：query 必填；top_k（默认 3，1-10）；start_id/end_id/offset 限定检索区间
+*   （意义同 recall：start_id 为基准边界，end_id 与 offset 二选一；end_id 优先）。
+* - 区间缺省（start_id 未提供）→ 检索全部消息；区间不合法（id 不存在等）→
+*   不报错，回退全量检索并在输出中明确告知（模型可见）。
+* - 向量：本地 ONNX embedding（embedding.ts，懒加载 + 批量）；相似度 = cosine。
+* - 输出：命中消息的 message_id/seq/类型 + 完整渲染文本 + 匹配说明（相似度、
+*   命中的关键词）；超大结果由 tool-result-pruner 裁剪（同 recall）。
+* - 仅主会话可用（subagent 拒绝，与 recall 一致）。
+*/
+/** 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_id: z.string().optional(),
+	end_id: z.string().optional(),
+	offset: z.number().optional()
+}).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;
+}
+/**
+* 解析检索区间（消息序列下标，含端点）。
+* - start_id 未提供 → 全量（fallback=false）。
+* - start_id 提供：end_id/offset 计算终点（语义同 recall，end_id 优先）；
+*   start_id/end_id 不存在或区间为空 → fallback=true（全量 + 提示）。
+*/
+function resolveSemanticRange(index, args) {
+	const total = index.messages.length;
+	if (total === 0) return {
+		lo: 0,
+		hi: -1,
+		fallback: false
+	};
+	if (args.start_id === void 0) return {
+		lo: 0,
+		hi: total - 1,
+		fallback: false
+	};
+	/** start_id 在消息序列中的下标。 */
+	const start = index.byId.get(args.start_id);
+	if (start === void 0) return {
+		lo: 0,
+		hi: total - 1,
+		fallback: true
+	};
+	/** 终点下标（end_id 优先；否则 start + offset 取整）。 */
+	let end;
+	if (args.end_id !== void 0) {
+		/** end_id 在消息序列中的下标。 */
+		const found = index.byId.get(args.end_id);
+		if (found === void 0) return {
+			lo: 0,
+			hi: total - 1,
+			fallback: true
+		};
+		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,
+		hi: total - 1,
+		fallback: true
+	};
+	return {
+		lo,
+		hi,
+		fallback: false
+	};
+}
+/** 简易分词：按非字母数字切分为小写词元（匹配要点用，非检索核心）。 */
+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 = "语义检索暂不可用：本地嵌入模型尚未就绪（正在后台下载约 113MB；下载完成后无需提示，直接再次调用本工具即可。若下载失败，下次调用会自动重试）。可稍后重试，或先用 recall 工具按 message_id 精确检索。";
+/** 构建 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: "按语义（自然语言含义）在会话全部消息中检索：用一句话描述你要找的内容（可混用中英文与代码术语）。返回最匹配的若干条完整消息、message_id 与匹配说明；如需精确定位某个 message_id 周边的消息，请再用 recall 工具。",
+		parameters: {
+			query: {
+				type: "string",
+				description: "描述要找的内容的自然语言 query（可混用中英文与代码术语，如 \"修复 retry backoff 的逻辑\"）。",
+				required: true
+			},
+			top_k: {
+				type: "number",
+				description: "返回最匹配的消息条数（1-10，默认 3）。"
+			},
+			start_id: {
+				type: "string",
+				description: "message_id(uuid)，可选。限定检索区间：以该消息为基准边界（意义同 recall）。缺省检索全部消息。区间不合法时自动回退全量检索并在结果中说明。"
+			},
+			end_id: {
+				type: "string",
+				description: "message_id(uuid)，可选，与 offset 互斥，限定区间的另一个边界（意义同 recall）。"
+			},
+			offset: {
+				type: "number",
+				description: "可选，与 end_id 互斥。相对 start_id 的步数：正数向后、负数向前（意义同 recall）。"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(args, exec) {
+			/** 解析并校验后的调用参数。 */
+			const { query, top_k, start_id, end_id, 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;
+			/** 会话消息索引（全部消息事件，含被压缩/遮蔽）。 */
+			const index = indexMessages(session);
+			if (index.messages.length === 0) return "会话中没有可检索的消息";
+			/** 检索区间（消息序列下标；区间不合法时回退全量并标记）。 */
+			const range = resolveSemanticRange(index, {
+				start_id,
+				end_id,
+				offset
+			});
+			/** 候选消息渲染文本（区间内；跳过渲染失败/空文本）。 */
+			const candidates = [];
+			for (let i = range.lo; i <= range.hi; i += 1) {
+				/** 当前消息节点。 */
+				const node = index.messages[i];
+				if (!node) continue;
+				/** 节点对应的会话事件。 */
+				const event = session.events[node.seq];
+				if (!event) continue;
+				/** 事件派生的消息对象。 */
+				let message = null;
+				try {
+					message = session.deriveEventMessage(event);
+				} catch {}
+				/** 渲染文本。 */
+				const text = message ? renderMessageText(message) : "";
+				if (text.trim().length > 0) candidates.push({
+					node,
+					text
+				});
+			}
+			if (candidates.length === 0) return "指定范围内没有可检索的消息";
+			/** 查询向量（单条）。 */
+			const [queryVec] = await embed([query]);
+			if (!queryVec) return "语义检索失败：无法生成查询向量";
+			/** 候选文本批量嵌入。 */
+			const vectors = await embed(candidates.map((c) => c.text));
+			/** 打分结果（相似度 + 候选）。 */
+			const scored = candidates.map((c, i) => ({
+				node: c.node,
+				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 rangeNote = range.fallback ? "指定区间不合法（start_id/end_id 不存在等），已回退检索全部消息" : start_id === 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;
+				/** 消息事件（用于类型与 pruner）。 */
+				const event = session.events[hit.node.seq];
+				/** 命中消息的 id（缺失则省略）。 */
+				const id = event ? messageIdOfEvent(event) ?? "" : "";
+				/** 命中消息文本（pruner 裁剪超大内容后渲染）。 */
+				let text = hit.text;
+				/** pruner（可选）。 */
+				const pruner = getPruner();
+				if (pruner?.pruneContent && event) {
+					/** 事件派生的消息对象（裁剪用）。 */
+					let message = null;
+					try {
+						message = session.deriveEventMessage(event);
+					} catch {}
+					if (message) {
+						/** 裁剪后的内容块。 */
+						const pruned = pruner.pruneContent(message.content);
+						if (pruned) text = renderMessageText({
+							...message,
+							content: pruned
+						});
+					}
+				}
+				parts.push(`-- [${i + 1}] seq ${hit.node.seq} ${hit.node.type} message_id=${id} — ${matchExplanation(query, hit.text, hit.score)} --`);
+				parts.push(text);
+			}
+			return parts.join("\n\n");
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 /**
 * dsh-plugin-om — Observational Memory（OM）上下文压缩 + recall 检索插件。
@@ -877,9 +1578,12 @@ function buildRecallTool(getPruner) {
 *
 * 模块：
 *  - recall.ts  recall({ start_id, end_id?, offset? }) 工具：按 message_id 回看原始会话
+*  - semantic-recall.ts  recall-semantic({ query, top_k?, start_id?, end_id?, offset? }) 工具：
+*    按语义在全部消息日志（含被压缩/遮蔽）中检索，返回最匹配的完整消息与匹配说明
+*    （本地 ONNX embedding，模型随插件打包，懒加载）
 *  - compress.ts 自动压缩（OM 观察/反思两级阈值）：pre-step 阻塞串行执行——
-*    反思（摘要 ≥ 窗口 × historyMergeRatio 时 fork 精简合并 <om-history>）、
-*    观察（未压缩消息 ≥ 窗口 × thresholdRatio 时 fork 压缩为观察日志并追加）
+*    反思（摘要 ≥ 窗口 × historyMergeRatio 时摘要调用精简合并 <om-history>）、
+*    观察（未压缩消息 ≥ 窗口 × thresholdRatio 时摘要调用压缩为观察日志并追加）
 *
 * 约束：不引入自定义会话事件类型——压缩复用宿主已知的 compaction/* 生命周期事件
 * （start/summary/end）与 checkpoint 标记，结果写入消息记录与轨迹。
@@ -895,18 +1599,36 @@ const inject = [
 	"sessions"
 ];
 /**
-* 插件激活入口：注册 recall 工具，并在 agent/pre-step 阻塞触发两级自动压缩
+* 插件激活入口：注册 recall / recall-semantic 工具（由配置键 recallEnabled /
+* semanticRecallEnabled 控制），并在 agent/pre-step 阻塞触发两级自动压缩
 * （先反思后观察）。仅主会话生效。
 */
 function apply(ctx, config) {
 	/** 解析后的插件配置（默认值合并 + 校验）。 */
 	const resolved = resolveConfig(config);
-	ctx.tools.register(buildRecallTool(() => ctx.get("toolResultPruner")));
+	/** 插件日志门面（step=debug 按配置 debug 开关输出；info/warn 始终输出）。 */
+	const logger = makeLogger(ctx, resolved.debug);
+	logger.step(`apply 启动：thresholdRatio=${String(resolved.thresholdRatio)} historyMergeRatio=${String(resolved.historyMergeRatio)} compressMaxTokens=${String(resolved.compressMaxTokens)} tailMessageCount=${String(resolved.tailMessageCount)} summaryMode=${resolved.summaryMode} 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);
+		ensureModelReady(resolved.modelDir, warnModel);
+		ctx.tools.register(buildSemanticRecallTool({
+			getPruner: () => ctx.get("toolResultPruner"),
+			modelStatus: () => ensureModelReady(resolved.modelDir, warnModel),
+			embedder: (texts) => getEmbedder(resolved.modelDir).then((embed) => embed(texts))
+		}));
+	}
 	ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
 		try {
-			if (!signal.aborted && isMainSession(agent.session)) await maybeCompress(ctx, agent, resolved, signal);
+			if (signal.aborted) logger.step("pre-step 已中止（signal aborted），跳过压缩");
+			else if (!isMainSession(agent.session)) logger.step("subagent 会话，跳过压缩（仅主会话生效）");
+			else {
+				logger.step(`pre-step 触发压缩（会话 ${agent.session.id}）`);
+				await maybeCompress(ctx, agent, resolved, signal);
+			}
 		} catch (error) {
-			ctx.logger.warn("dsh-plugin-om: pre-step 处理失败: " + (error instanceof Error ? error.message : String(error)));
+			logger.warn(`pre-step 处理失败: ${error instanceof Error ? error.message : String(error)}`);
 		}
 		return next();
 	});