dsh-deeppilot 0.9.16 → 0.9.17

package/lib/index.js

@@ -1968,7 +1968,8 @@ function projectEvent(sessionId, event) {
 						state: "running",
 						summary: summarizeArgs(data?.arguments),
 						...data?.callId ? { callId: String(data.callId) } : {},
-						...editField(data?.name, data?.arguments)
+						...editField(data?.name, data?.arguments),
+						...targetField(data?.name, data?.arguments)
 					},
 					ts: tsOf(event)
 				}
@@ -2139,6 +2140,40 @@ function attachmentProjection(data) {
 	const attachments = messageAttachments(data);
 	return attachments.length > 0 ? { attachments } : {};
 }
+/**
+* 取出一条事件里手机能看到的图片引用，供附件读回补全参数。
+*
+* 范围与投影保持一致：只看 user/message 与成功的 tool/result——手机只会拿到这两
+* 类行上的 attachmentId，不在投影里的图片也不该被读回。
+* 职责：DSH 0.2.2 起宿主读图接口要完整引用，且不再核对会话是否引用过这张图；
+* Bridge 用这里收集的引用同时完成「补全参数」和「会话归属校验」。
+*/
+function eventImageRefs(event) {
+	let message;
+	if (event.type === "user/message") message = event.data;
+	else if (event.type === "tool/result") {
+		const data = event.data;
+		if (data?.error !== void 0) return [];
+		message = data?.message;
+	} else return [];
+	if (!message || typeof message !== "object") return [];
+	const inner = message.message;
+	const content = (inner && typeof inner === "object" ? inner : message).content;
+	if (!Array.isArray(content)) return [];
+	const refs = [];
+	for (const part of content) {
+		const block = part;
+		if (!block || block.type !== "image") continue;
+		const ref = block.attachment;
+		if (!ref || typeof ref !== "object") continue;
+		if (typeof ref.attachmentId !== "string" || ref.attachmentId.length === 0) continue;
+		refs.push({
+			...ref,
+			attachmentId: ref.attachmentId
+		});
+	}
+	return refs;
+}
 /** Extract reasoning ("thinking") text from assistant message payloads. */
 function messageThinking(data) {
 	if (!data || typeof data !== "object") return "";
@@ -2178,6 +2213,125 @@ function editField(name, raw) {
 	const edit = toolEditOf(name, raw);
 	return edit ? { edit } : {};
 }
+function targetField(name, raw) {
+	const target = toolTargetOf(name, raw);
+	return target ? { target } : {};
+}
+/** `tool.target.value` / `scope` 的 UTF-8 上限。 */
+const MAX_TOOL_TARGET_VALUE_BYTES = 1024;
+/** 读写文件类工具：路径即操作对象。 */
+const PATH_TARGET_TOOLS = /* @__PURE__ */ new Set([
+	"read",
+	"write",
+	"edit",
+	"str_replace_editor"
+]);
+/** 搜索类工具：搜索式为主值，搜索目录为范围。 */
+const PATTERN_TARGET_TOOLS = /* @__PURE__ */ new Set(["grep", "glob"]);
+/** 网页类工具：有网址给网址，否则给查询词。 */
+const WEB_TARGET_TOOLS = /* @__PURE__ */ new Set(["web_fetch", "web_search"]);
+/** 协作类工具：对象是另一个智能体或后台任务，按工具各取一个能认出对象的参数。 */
+const TEXT_TARGET_KEYS = {
+	send_message: ["target", "agent_id"],
+	spawn_teammate: ["name"],
+	subagent: ["description"],
+	job_output: ["job_id"]
+};
+/**
+* 从工具调用的原始参数里挑出操作对象，归一化成 `ToolTargetProjection`。
+*
+* 为什么需要它：`tool.summary` 在结果回来后被替换成结果摘要（read 变成文件正文片段），
+* 客户端从此拿不到「读的是哪个文件」。target 只在调用时生成一次，结果合并时不动。
+* 规则表之外的工具、无法解析或缺少对应参数时返回 undefined，客户端退回 summary。
+* 参数名只在这里出现，客户端不依赖宿主工具参数命名。
+*/
+function toolTargetOf(name, raw) {
+	if (typeof name !== "string" || typeof raw !== "string" || raw.length === 0) return void 0;
+	let args;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+		args = parsed;
+	} catch {
+		return;
+	}
+	/** 取第一个非空字符串参数。 */
+	const pick = (...keys) => {
+		for (const key of keys) {
+			const value = args[key];
+			if (typeof value === "string" && value.trim().length > 0) return value.trim();
+		}
+	};
+	if (PATH_TARGET_TOOLS.has(name)) {
+		const path = pick("file_path", "path");
+		return path ? {
+			kind: "path",
+			value: boundPath(path)
+		} : void 0;
+	}
+	if (name === "bash") {
+		const command = pick("command");
+		if (!command) return void 0;
+		const label = pick("description");
+		return {
+			kind: "command",
+			value: boundText(command, MAX_TOOL_TARGET_VALUE_BYTES),
+			...label ? { label: boundText(label, 256) } : {}
+		};
+	}
+	if (PATTERN_TARGET_TOOLS.has(name)) {
+		const pattern = pick("pattern");
+		if (!pattern) return void 0;
+		const scope = pick("path");
+		return {
+			kind: "pattern",
+			value: boundText(pattern, MAX_TOOL_TARGET_VALUE_BYTES),
+			...scope ? { scope: boundPath(scope) } : {}
+		};
+	}
+	if (WEB_TARGET_TOOLS.has(name)) {
+		const url = pick("url");
+		if (url) return {
+			kind: "url",
+			value: boundText(url, MAX_TOOL_TARGET_VALUE_BYTES)
+		};
+		const query = pick("query");
+		return query ? {
+			kind: "text",
+			value: boundText(query, MAX_TOOL_TARGET_VALUE_BYTES)
+		} : void 0;
+	}
+	const keys = TEXT_TARGET_KEYS[name];
+	if (keys) {
+		const text = pick(...keys);
+		return text ? {
+			kind: "text",
+			value: boundText(text, MAX_TOOL_TARGET_VALUE_BYTES)
+		} : void 0;
+	}
+}
+/** 命令 / 文本：空白折叠成单个空格（手机上只显示一行），超限砍结尾加「…」。 */
+function boundText(value, maxBytes) {
+	const flat = value.replace(/\s+/g, " ");
+	if (Buffer.byteLength(flat, "utf8") <= maxBytes) return flat;
+	return truncateUtf8(flat, maxBytes - Buffer.byteLength("…", "utf8")) + "…";
+}
+/** 路径：超限时砍开头、保留结尾（如 `…/Views/A.swift`），保证文件名完整可认。 */
+function boundPath(value) {
+	const maxBytes = MAX_TOOL_TARGET_VALUE_BYTES;
+	if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+	const budget = maxBytes - Buffer.byteLength("…", "utf8");
+	let low = 0;
+	let high = value.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (Buffer.byteLength(value.slice(value.length - mid), "utf8") <= budget) low = mid;
+		else high = mid - 1;
+	}
+	let start = value.length - low;
+	if (start < value.length && /[\uDC00-\uDFFF]/.test(value[start])) start += 1;
+	return "…" + value.slice(start);
+}
 function summarizeArgs(raw) {
 	if (typeof raw !== "string" || raw.length === 0) return "";
 	try {
@@ -2191,15 +2345,22 @@ function summarizeArgs(raw) {
 }
 /** 宿主的文件编辑工具名（DSH `dsh-tool-str-replace-editor`）。 */
 const EDITOR_TOOL_NAME = "str_replace_editor";
+/** 宿主的字符串替换工具（`file_path` / `old_string` / `new_string` / `replace_all`），实际会话里最常用。 */
+const EDIT_TOOL_NAME = "edit";
+/** 宿主的整文件写入工具（`file_path` / `content`）。 */
+const WRITE_TOOL_NAME = "write";
 /**
 * 把编辑类工具调用的原始参数归一化成 `ToolEditProjection`。
 *
-* 只认 `str_replace_editor` 的 `str_replace` / `create` / `insert`（`view` 不改文件），
-* 其他工具或无法解析的参数返回 undefined，工具行保持原样。与 iOS `ToolEditDiff.parse`
-* 的解析口径一致：`new_str` 缺失视为删除（空串）。
+* 认三种宿主工具，其他工具或无法解析的参数返回 undefined，工具行保持原样：
+* - `edit`：`old_string` → `new_string` 为 `replace`；`old_string` 为空串视为新建（`create`）。
+* - `write`：`content` 为写入后的文件全文，记作 `create`（宿主覆盖已有文件时也一样，原文拿不到）。
+* - `str_replace_editor`：`str_replace` / `create` / `insert`（`view` 不改文件）。
+* 与 iOS `ToolEditDiff.parse` 的解析口径一致：新文本缺失视为删除（空串）。
 */
 function toolEditOf(name, raw) {
-	if (name !== EDITOR_TOOL_NAME || typeof raw !== "string" || raw.length === 0) return void 0;
+	if (name !== EDITOR_TOOL_NAME && name !== EDIT_TOOL_NAME && name !== WRITE_TOOL_NAME) return void 0;
+	if (typeof raw !== "string" || raw.length === 0) return void 0;
 	let args;
 	try {
 		const parsed = JSON.parse(raw);
@@ -2208,6 +2369,10 @@ function toolEditOf(name, raw) {
 	} catch {
 		return;
 	}
+	if (name === EDIT_TOOL_NAME || name === WRITE_TOOL_NAME) {
+		const edit = plainEditOf(name, args);
+		return edit ? boundedEdit(edit) : void 0;
+	}
 	const path = args.path;
 	if (typeof path !== "string" || path.length === 0) return void 0;
 	let edit;
@@ -2240,6 +2405,32 @@ function toolEditOf(name, raw) {
 			break;
 		default: return;
 	}
+	return boundedEdit(edit);
+}
+/** `edit` / `write` 的参数（路径键为 `file_path`）。 */
+function plainEditOf(name, args) {
+	const path = args.file_path;
+	if (typeof path !== "string" || path.length === 0) return void 0;
+	if (name === WRITE_TOOL_NAME) return typeof args.content === "string" ? {
+		path,
+		operation: "create",
+		newText: args.content
+	} : void 0;
+	if (typeof args.old_string !== "string") return void 0;
+	const newText = typeof args.new_string === "string" ? args.new_string : "";
+	return args.old_string.length === 0 ? {
+		path,
+		operation: "create",
+		newText
+	} : {
+		path,
+		operation: "replace",
+		oldText: args.old_string,
+		newText
+	};
+}
+/** 任一侧正文超过上限时两侧都不发，只留路径、操作与 truncated。 */
+function boundedEdit(edit) {
 	return [edit.oldText, edit.newText].some((text) => text !== void 0 && Buffer.byteLength(text, "utf8") > 16384) ? withoutEditBodies(edit) : edit;
 }
 /** 去掉改动正文，只留路径、操作与 truncated 标记（超限或整条消息超限时用）。 */
@@ -2301,7 +2492,8 @@ function projectHistory(events, touched) {
 						name: String(data?.name ?? "tool"),
 						state: "running",
 						summary: summarizeArgs(data?.arguments),
-						...editField(data?.name, data?.arguments)
+						...editField(data?.name, data?.arguments),
+						...targetField(data?.name, data?.arguments)
 					}
 				};
 				messages.push(row);
@@ -3112,128 +3304,153 @@ const categories = [
 	"security-privacy-permission",
 	"other"
 ];
-const commandRows = [...[
-	"commands",
-	"permissions",
-	"feedback",
-	"command"
-].map((name) => ({
-	type: `c2s.session.${name}`,
-	stage: "authenticated",
-	capability: "commands",
-	scopes: name === "commands" || name === "permissions" ? ["sessions.read"] : ["prompt.send"],
-	doc: `PROTOCOL.md c2s.session.${name}`,
-	validate: (value) => {
-		const result = sessionPayload(value);
-		if (!result.ok) return result;
-		const p = result.value;
-		if (name === "command") {
-			if (typeof p.line !== "string" || p.line.length > 65536 || !/^\/[a-z][a-z0-9_-]*(?:\s|$)/.test(p.line)) return reject$1("E_PROTOCOL", "指令格式无效");
-			if (p.expectedDefinitionId !== void 0 && (typeof p.expectedDefinitionId !== "string" || !p.expectedDefinitionId || p.expectedDefinitionId.length > 512)) return reject$1("E_PROTOCOL", "指令定义标识无效");
-			const attachments = p.attachments ?? [];
-			if (!Array.isArray(attachments) || attachments.length > 4) return reject$1("E_PROTOCOL", "附件数量无效");
-			for (const item of attachments) if (!item || !["image", "document"].includes(item.type) || typeof item.name !== "string" || item.name.length > 512 || typeof item.mediaType !== "string" || typeof item.data !== "string" || item.data.length > 16777216 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(item.data) || item.type === "image" && ![
-				"image/png",
-				"image/jpeg",
-				"image/webp",
-				"image/gif"
-			].includes(item.mediaType)) return reject$1("E_PROTOCOL", "附件格式无效");
-			return {
-				ok: true,
-				value: {
-					...p,
-					attachments
-				}
-			};
+const commandRows = [
+	...[
+		"commands",
+		"permissions",
+		"feedback",
+		"command"
+	].map((name) => ({
+		type: `c2s.session.${name}`,
+		stage: "authenticated",
+		capability: "commands",
+		scopes: name === "commands" || name === "permissions" ? ["sessions.read"] : ["prompt.send"],
+		doc: `PROTOCOL.md c2s.session.${name}`,
+		validate: (value) => {
+			const result = sessionPayload(value);
+			if (!result.ok) return result;
+			const p = result.value;
+			if (name === "command") {
+				if (typeof p.line !== "string" || p.line.length > 65536 || !/^\/[a-z][a-z0-9_-]*(?:\s|$)/.test(p.line)) return reject$1("E_PROTOCOL", "指令格式无效");
+				if (p.expectedDefinitionId !== void 0 && (typeof p.expectedDefinitionId !== "string" || !p.expectedDefinitionId || p.expectedDefinitionId.length > 512)) return reject$1("E_PROTOCOL", "指令定义标识无效");
+				const attachments = p.attachments ?? [];
+				if (!Array.isArray(attachments) || attachments.length > 4) return reject$1("E_PROTOCOL", "附件数量无效");
+				for (const item of attachments) if (!item || !["image", "document"].includes(item.type) || typeof item.name !== "string" || item.name.length > 512 || typeof item.mediaType !== "string" || typeof item.data !== "string" || item.data.length > 16777216 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(item.data) || item.type === "image" && ![
+					"image/png",
+					"image/jpeg",
+					"image/webp",
+					"image/gif"
+				].includes(item.mediaType)) return reject$1("E_PROTOCOL", "附件格式无效");
+				return {
+					ok: true,
+					value: {
+						...p,
+						attachments
+					}
+				};
+			}
+			if (name === "feedback" && (typeof p.text !== "string" || p.text.length > 65536 || p.category !== void 0 && !categories.includes(String(p.category)))) return reject$1("E_PROTOCOL", "反馈内容无效");
+			return result;
+		},
+		handle: async (ctx, payload) => {
+			const operation = name === "commands" ? "list" : name === "command" ? "execute" : name;
+			const result = await ctx.bridge.commandOperation(operation, payload);
+			if (!result.ok) return ctx.fail(result.code, result.message);
+			const type = name === "commands" ? "s2c.session.commands" : name === "permissions" ? "s2c.session.permissions" : name === "command" ? "s2c.session.commandResult" : "s2c.ack";
+			ctx.send(type, {
+				sessionId: payload.sessionId,
+				...result.value
+			});
+		}
+	})),
+	{
+		type: "c2s.session.references",
+		stage: "authenticated",
+		scopes: ["sessions.read"],
+		capability: "references",
+		doc: "PROTOCOL.md c2s.session.references",
+		validate: (value) => {
+			const result = sessionPayload(value);
+			if (!result.ok) return result;
+			if (typeof result.value.query !== "string" || result.value.query.length > 1024 || /[\r\n]/.test(result.value.query)) return reject$1("E_PROTOCOL", "引用查询无效");
+			return result;
+		},
+		handle: async (ctx, payload) => {
+			const result = await ctx.bridge.referenceCandidates(payload.sessionId, payload.query, ctx.signal);
+			if (!result.ok) return ctx.fail(result.code, result.message);
+			ctx.send("s2c.session.references", {
+				sessionId: payload.sessionId,
+				query: payload.query,
+				...result.value
+			});
 		}
-		if (name === "feedback" && (typeof p.text !== "string" || p.text.length > 65536 || p.category !== void 0 && !categories.includes(String(p.category)))) return reject$1("E_PROTOCOL", "反馈内容无效");
-		return result;
-	},
-	handle: async (ctx, payload) => {
-		const operation = name === "commands" ? "list" : name === "command" ? "execute" : name;
-		const result = await ctx.bridge.commandOperation(operation, payload);
-		if (!result.ok) return ctx.fail(result.code, result.message);
-		const type = name === "commands" ? "s2c.session.commands" : name === "permissions" ? "s2c.session.permissions" : name === "command" ? "s2c.session.commandResult" : "s2c.ack";
-		ctx.send(type, {
-			sessionId: payload.sessionId,
-			...result.value
-		});
-	}
-})), {
-	type: "c2s.session.export",
-	stage: "authenticated",
-	scopes: ["sessions.read"],
-	capability: "commands",
-	conditionalCapabilities: ["sessionMarkdown"],
-	doc: "PROTOCOL.md c2s.session.export",
-	validate: (value) => {
-		const result = sessionPayload(value);
-		if (!result.ok) return result;
-		if (result.value.format !== void 0 && result.value.format !== "zip" && result.value.format !== "markdown") return reject$1("E_PROTOCOL", "导出格式无效");
-		if (result.value.binary !== void 0 && typeof result.value.binary !== "boolean") return reject$1("E_PROTOCOL", "传输方式无效");
-		return result;
 	},
-	handle: async (ctx, payload) => {
-		const format = payload.format;
-		if (format === "markdown" && ctx.bridge.capabilities.sessionMarkdown !== true) return ctx.fail("E_UNSUPPORTED", "当前主机不支持导出对话正文");
-		const signal = AbortSignal.any([ctx.signal ?? new AbortController().signal, AbortSignal.timeout(6e5)]);
-		let reader;
-		const cancel = () => {
-			reader?.cancel().catch(() => {});
-		};
-		try {
-			reader = (format === void 0 ? await ctx.bridge.exportSession(payload.sessionId, signal) : await ctx.bridge.exportSession(payload.sessionId, signal, format)).body.getReader();
-			signal.addEventListener("abort", cancel, { once: true });
-			const binary = payload.binary === true && ctx.sendBinary !== void 0;
-			let index = 0, bytes = 0;
-			const sendChunk = async (chunk) => {
-				bytes += chunk.length;
-				await ctx.waitForWritable?.();
-				if (binary) ctx.sendBinary("s2c.session.export.chunk", { index: index++ }, chunk);
-				else ctx.send("s2c.session.export.chunk", {
-					index: index++,
-					data: Buffer.from(chunk).toString("base64")
-				});
+	{
+		type: "c2s.session.export",
+		stage: "authenticated",
+		scopes: ["sessions.read"],
+		capability: "commands",
+		conditionalCapabilities: ["sessionMarkdown"],
+		doc: "PROTOCOL.md c2s.session.export",
+		validate: (value) => {
+			const result = sessionPayload(value);
+			if (!result.ok) return result;
+			if (result.value.format !== void 0 && result.value.format !== "zip" && result.value.format !== "markdown") return reject$1("E_PROTOCOL", "导出格式无效");
+			if (result.value.binary !== void 0 && typeof result.value.binary !== "boolean") return reject$1("E_PROTOCOL", "传输方式无效");
+			return result;
+		},
+		handle: async (ctx, payload) => {
+			const format = payload.format;
+			if (format === "markdown" && ctx.bridge.capabilities.sessionMarkdown !== true) return ctx.fail("E_UNSUPPORTED", "当前主机不支持导出对话正文");
+			const signal = AbortSignal.any([ctx.signal ?? new AbortController().signal, AbortSignal.timeout(6e5)]);
+			let reader;
+			const cancel = () => {
+				reader?.cancel().catch(() => {});
 			};
-			let carry;
-			while (true) {
-				signal.throwIfAborted();
-				const next = await reader.read();
-				if (next.done) break;
-				if (!binary) {
-					for (let offset = 0; offset < next.value.length; offset += 49152) await sendChunk(next.value.subarray(offset, offset + 49152));
-					continue;
-				}
-				carry = carry ? Buffer.concat([carry, next.value]) : Buffer.from(next.value);
-				while (carry.length >= BINARY_CHUNK_BYTES) {
-					await sendChunk(carry.subarray(0, BINARY_CHUNK_BYTES));
-					carry = carry.subarray(BINARY_CHUNK_BYTES);
+			try {
+				reader = (format === void 0 ? await ctx.bridge.exportSession(payload.sessionId, signal) : await ctx.bridge.exportSession(payload.sessionId, signal, format)).body.getReader();
+				signal.addEventListener("abort", cancel, { once: true });
+				const binary = payload.binary === true && ctx.sendBinary !== void 0;
+				let index = 0, bytes = 0;
+				const sendChunk = async (chunk) => {
+					bytes += chunk.length;
+					await ctx.waitForWritable?.();
+					if (binary) ctx.sendBinary("s2c.session.export.chunk", { index: index++ }, chunk);
+					else ctx.send("s2c.session.export.chunk", {
+						index: index++,
+						data: Buffer.from(chunk).toString("base64")
+					});
+				};
+				let carry;
+				while (true) {
+					signal.throwIfAborted();
+					const next = await reader.read();
+					if (next.done) break;
+					if (!binary) {
+						for (let offset = 0; offset < next.value.length; offset += 49152) await sendChunk(next.value.subarray(offset, offset + 49152));
+						continue;
+					}
+					carry = carry ? Buffer.concat([carry, next.value]) : Buffer.from(next.value);
+					while (carry.length >= BINARY_CHUNK_BYTES) {
+						await sendChunk(carry.subarray(0, BINARY_CHUNK_BYTES));
+						carry = carry.subarray(BINARY_CHUNK_BYTES);
+					}
 				}
+				signal.throwIfAborted();
+				if (carry !== void 0 && carry.length > 0) await sendChunk(carry);
+				ctx.send("s2c.ack", {
+					sessionId: payload.sessionId,
+					fileName: format === "markdown" ? "dsh-session.md" : "dsh-session-log.zip",
+					chunks: index,
+					bytes,
+					...format === void 0 ? {} : { mediaType: format === "markdown" ? "text/markdown; charset=utf-8" : "application/zip" }
+				});
+			} catch (error) {
+				const failure = hostFailureOf(error, "command/export-cancelled");
+				const message = failure.code === "command/export-cancelled" ? "会话日志导出失败，请重试" : failure.message;
+				const mapped = wireErrorOf("command", {
+					...failure,
+					message
+				});
+				ctx.fail(mapped.code, mapped.message);
+			} finally {
+				signal.removeEventListener("abort", cancel);
+				await reader?.cancel().catch(() => {});
+				reader?.releaseLock();
 			}
-			signal.throwIfAborted();
-			if (carry !== void 0 && carry.length > 0) await sendChunk(carry);
-			ctx.send("s2c.ack", {
-				sessionId: payload.sessionId,
-				fileName: format === "markdown" ? "dsh-session.md" : "dsh-session-log.zip",
-				chunks: index,
-				bytes,
-				...format === void 0 ? {} : { mediaType: format === "markdown" ? "text/markdown; charset=utf-8" : "application/zip" }
-			});
-		} catch (error) {
-			const failure = hostFailureOf(error, "command/export-cancelled");
-			const message = failure.code === "command/export-cancelled" ? "会话日志导出失败，请重试" : failure.message;
-			const mapped = wireErrorOf("command", {
-				...failure,
-				message
-			});
-			ctx.fail(mapped.code, mapped.message);
-		} finally {
-			signal.removeEventListener("abort", cancel);
-			await reader?.cancel().catch(() => {});
-			reader?.releaseLock();
 		}
 	}
-}];
+];
 // src/plugin-update.ts
 const PACKAGE = "dsh-deeppilot";
 const PHASES = [
@@ -3639,9 +3856,8 @@ var PluginUpdater = class {
 				record.restartPhase = "rolled-back";
 				return this.transition(record, "restart-required", "目标安装失败，旧版已重新安装；请在电脑端重启 DSH 后确认恢复");
 			}
-			if (restored.application === "applied" && (restored.version === void 0 || restored.version === record.fromVersion)) {
+			if (restored.version === void 0 || restored.version === record.fromVersion) {
 				if ((await this.listBundles()).find((bundle) => bundle.name === PACKAGE)?.version === record.fromVersion) return this.transition(record, "rolled-back", "目标安装失败，宿主已自动恢复旧版本");
-				return this.transition(record, "failed", "宿主已尝试回滚，但无法核对实际旧版本，请在电脑端检查插件");
 			}
 			return this.transition(record, "failed", "目标安装失败，宿主恢复旧版也未完成，请在电脑端检查插件");
 		}
@@ -7255,6 +7471,7 @@ const HOST_CAPABILITY_PROBES = {
 	models: (proxy) => typeof proxy.sessions.models === "function",
 	skills: (proxy) => typeof proxy.sessions.skills === "function",
 	commands: (proxy) => typeof proxy.commands?.list === "function" && typeof proxy.commands?.execute === "function",
+	references: (proxy) => typeof proxy.references?.list === "function",
 	sessionManagement: (proxy) => typeof proxy.sessions.rename === "function" && typeof proxy.workspace?.archiveSession === "function",
 	sessionFork: (proxy) => typeof proxy.sessions.fork === "function",
 	sessionRestore: (proxy) => typeof proxy.workspace?.unarchiveSession === "function",
@@ -7287,6 +7504,7 @@ function capabilityBits(proxy, pushOutlet) {
 		models: HOST_CAPABILITY_PROBES.models(proxy),
 		skills: HOST_CAPABILITY_PROBES.skills(proxy),
 		commands: HOST_CAPABILITY_PROBES.commands(proxy),
+		references: HOST_CAPABILITY_PROBES.references(proxy),
 		sessionManagement: HOST_CAPABILITY_PROBES.sessionManagement(proxy),
 		sessionFork: HOST_CAPABILITY_PROBES.sessionFork(proxy),
 		sessionRestore: HOST_CAPABILITY_PROBES.sessionRestore(proxy),
@@ -7554,6 +7772,69 @@ var AssistantStream = class {
 		this.attempts.clear();
 	}
 };
+// src/image-ref-index.ts
+/** 缓存条目上限：引用只有几十字节，4096 条足够覆盖手机近期能看到的图片。 */
+const MAX_CACHED_IMAGE_REFS = 4096;
+var ImageRefIndex = class {
+	maxEntries;
+	/** 键为 `sessionId\0attachmentId`；Map 的插入顺序即 LRU 顺序。 */
+	refs = /* @__PURE__ */ new Map();
+	/** 同一会话的并发回查共用一次扫描（冷启动时多张缩略图会同时请求）。 */
+	scans = /* @__PURE__ */ new Map();
+	constructor(maxEntries = MAX_CACHED_IMAGE_REFS) {
+		this.maxEntries = maxEntries;
+	}
+	/** 记下一批事件里的图片引用；对非图片事件是空操作。 */
+	remember(sessionId, events) {
+		for (const event of events) for (const ref of eventImageRefs(event)) this.put(sessionId, ref);
+	}
+	/** 只查缓存，不触发扫描。 */
+	peek(sessionId, attachmentId) {
+		const key = keyOf(sessionId, attachmentId);
+		const ref = this.refs.get(key);
+		if (ref) {
+			this.refs.delete(key);
+			this.refs.set(key, ref);
+		}
+		return ref;
+	}
+	/** 缓存优先；未命中时扫描会话历史后再查一次。找不到返回 undefined。 */
+	async resolve(sessionId, attachmentId, readPage) {
+		const cached = this.peek(sessionId, attachmentId);
+		if (cached) return cached;
+		let scan = this.scans.get(sessionId);
+		if (!scan) {
+			scan = this.scan(sessionId, readPage).finally(() => this.scans.delete(sessionId));
+			this.scans.set(sessionId, scan);
+		}
+		await scan;
+		return this.peek(sessionId, attachmentId);
+	}
+	async scan(sessionId, readPage) {
+		let beforeSeq;
+		for (let page = 0; page < 20; page++) {
+			const result = await readPage(sessionId, beforeSeq);
+			if (!result || result.events.length === 0) return;
+			this.remember(sessionId, result.events);
+			const oldest = Math.min(...result.events.map((event) => event.seq));
+			if (!result.hasMore || !Number.isFinite(oldest) || beforeSeq !== void 0 && oldest >= beforeSeq) return;
+			beforeSeq = oldest;
+		}
+	}
+	put(sessionId, ref) {
+		const key = keyOf(sessionId, ref.attachmentId);
+		this.refs.delete(key);
+		this.refs.set(key, ref);
+		while (this.refs.size > this.maxEntries) {
+			const oldest = this.refs.keys().next().value;
+			if (oldest === void 0) break;
+			this.refs.delete(oldest);
+		}
+	}
+};
+function keyOf(sessionId, attachmentId) {
+	return `${sessionId}\u0000${attachmentId}`;
+}
 // src/host-bridge.ts
 const MAX_RING_DEFAULT = 2e3;
 /** 补发量超过它就改发 s2c.resync（经 Funnel 实测吞吐 40～80 KB/s，约 6～12 秒）。 */
@@ -7602,6 +7883,8 @@ var HostBridge = class {
 	abort = new AbortController();
 	started = false;
 	disposed = false;
+	/** attachmentId → 宿主完整图片引用，供 attachmentData 补全 DSH 0.2.2+ 的读图参数。 */
+	imageRefs = new ImageRefIndex();
 	promptDeliveries;
 	scheduleMutations;
 	forkMutations;
@@ -7978,6 +8261,7 @@ var HostBridge = class {
 				this.noteActivity(sessionId, event);
 				if (event.type === "user/message") this.quietCompletion.noteUserMessage(sessionId, userMessageSourceKind(event.data), event.seq);
 				this.captureAssistantText(sessionId, event);
+				this.imageRefs.remember(sessionId, [event]);
 				const projection = projectEvent(sessionId, event);
 				this.captureActivity(sessionId, event, projection?.data.tool);
 				if (projection) this.record("s2c.session.event", {
@@ -8001,6 +8285,7 @@ var HostBridge = class {
 				const p = frame;
 				if (!p.sessionId) break;
 				if (p.key === "workingDirectory" || p.key === "agentPreset") this.record("s2c.skills.changed", { sessionId: p.sessionId });
+				if (p.key === "permissions") this.record("s2c.commands.changed", { sessionId: p.sessionId });
 				if (p.key === "modelSelection") {
 					const next = p.value?.next;
 					const current = next && typeof next.provider === "string" && typeof next.model === "string" ? {
@@ -8396,6 +8681,7 @@ var HostBridge = class {
 			if (!response.result || !response.result.ok) return false;
 			const result = response.result.value;
 			const events = result.events ?? [];
+			this.imageRefs.remember(sessionId, events.map((row) => row.event));
 			const touched = /* @__PURE__ */ new Map();
 			const projected = projectHistory(events, touched);
 			const page = limitSessionPageMessages(projected);
@@ -8467,6 +8753,7 @@ var HostBridge = class {
 			});
 			if (!response.result || !response.result.ok) return null;
 			const result = response.result.value;
+			this.imageRefs.remember(sessionId, (result.events ?? []).map((row) => row.event));
 			const page = limitSessionPageMessages(projectHistory(result.events ?? []).filter((message) => message.seq < beforeSeq));
 			return {
 				sessionId,
@@ -8477,16 +8764,27 @@ var HostBridge = class {
 			return null;
 		}
 	}
-	/** Result of one attachment read-back for the phone. */
+	/**
+	* Result of one attachment read-back for the phone.
+	*
+	* 宿主读图参数有两代：DSH ≤ 0.2.1 收 `{sessionId, attachmentId}` 并自己在会话日志里
+	* 找引用；DSH 0.2.2 起改收 `{sessionId, attachment: 完整引用}`，且不再核对会话。
+	* 控制器是直接注入的实例、不经参数 schema 校验，所以两代字段一起传：旧宿主读前者，
+	* 新宿主读后者。完整引用来自 imageRefs（本会话投影过的图片）；找不到时不带
+	* `attachment`，旧宿主照常自查，新宿主读不到即回 null（E_NOT_FOUND）——手机因此
+	* 读不到不属于该会话的图片。
+	*/
 	async attachmentData(sessionId, attachmentId) {
 		const read = this.apiProxy.sessions.attachment;
 		if (typeof read !== "function") return null;
 		try {
+			const ref = await this.imageRefs.resolve(sessionId, attachmentId, (id, beforeSeq) => this.readHistoryEvents(id, beforeSeq));
 			const response = await read.call(this.apiProxy.sessions, {
 				rpcId: randomUUID(),
 				payload: {
 					sessionId,
-					attachmentId
+					attachmentId,
+					...ref ? { attachment: ref } : {}
 				}
 			});
 			if (!response.result || !response.result.ok) return null;
@@ -8500,6 +8798,27 @@ var HostBridge = class {
 			return null;
 		}
 	}
+	/** 图片引用回查用的原始历史页：只取事件，不投影、不推给手机。 */
+	async readHistoryEvents(sessionId, beforeSeq) {
+		try {
+			const response = await this.apiProxy.sessions.history({
+				rpcId: randomUUID(),
+				payload: {
+					sessionId,
+					...beforeSeq === void 0 ? {} : { beforeSeq },
+					maxMessages: 500
+				}
+			});
+			if (!response.result || !response.result.ok) return null;
+			const result = response.result.value;
+			return {
+				events: (result.events ?? []).map((row) => row.event),
+				hasMore: Boolean(result.hasMore)
+			};
+		} catch {
+			return null;
+		}
+	}
 	async commandOperation(operation, payload) {
 		const api = this.apiProxy.commands;
 		if (!api) return {
@@ -8521,6 +8840,42 @@ var HostBridge = class {
 			return wireErrorOf("command", hostFailureOf(error, "command/invalid-response"));
 		}
 	}
+	/**
+	* 输入框 `@` 引用候选。两类候选的单类失败已在 reference-api 内吸收为空列表，
+	* 这里只处理「两类都不可用」与代理层意外异常。
+	*/
+	async referenceCandidates(sessionId, query, signal) {
+		const api = this.apiProxy.references;
+		if (!api) return {
+			ok: false,
+			code: "E_UNSUPPORTED",
+			message: "当前主机不支持引用文件或会话"
+		};
+		try {
+			const response = await api.list({
+				rpcId: randomUUID(),
+				payload: {
+					sessionId,
+					query
+				}
+			}, signal);
+			if (response.result?.ok && response.result.value) return {
+				ok: true,
+				value: response.result.value
+			};
+			return {
+				ok: false,
+				code: "E_INTERNAL",
+				message: "无法读取引用候选"
+			};
+		} catch {
+			return {
+				ok: false,
+				code: "E_INTERNAL",
+				message: "无法读取引用候选"
+			};
+		}
+	}
 	async exportSession(sessionId, signal, format) {
 		const api = this.apiProxy.commands;
 		if (!api) throw Object.assign(/* @__PURE__ */ new Error("当前主机不支持日志导出"), { code: "command/export-unsupported" });
@@ -10734,6 +11089,115 @@ var DshCommandApi = class {
 		return response;
 	}
 };
+/** 补全是交互式请求，慢于此值的结果对用户已无意义。 */
+const REFERENCE_TIMEOUT_MS = 5e3;
+const SESSION_MENTION = /^@\[[^\n]*\]\(dsh-session:[A-Za-z0-9_-]+\)$/;
+var DshReferenceApi = class {
+	ctx;
+	peer;
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	get gatewayReady() {
+		return typeof this.ctx.get("typertGateway")?.invoke === "function";
+	}
+	get filesAvailable() {
+		return this.gatewayReady && this.ctx.get("fileReferences") !== void 0;
+	}
+	get sessionsAvailable() {
+		return this.gatewayReady && this.ctx.get("sessionReferenceResolver") !== void 0;
+	}
+	get available() {
+		return this.filesAvailable || this.sessionsAvailable;
+	}
+	owner() {
+		const connection = this.ctx.get("connection");
+		return this.peer ??= connection?.createPeer?.({
+			principal: { kind: "owner" },
+			interactions: "none"
+		}) ?? connection?.operator;
+	}
+	async invoke(namespace, method, args, signal) {
+		return unwrapRemote(await this.ctx.get("typertGateway").invoke({
+			namespace,
+			method,
+			args,
+			peer: this.owner(),
+			signal
+		}));
+	}
+	/**
+	* 并行读两类候选。单类失败（超时、旧主机没有对应 Remote）只让该类为空，
+	* 不拖垮另一类；两类都不可用由调用方在能力位上拦下。
+	*/
+	async list(sessionId, query, signal) {
+		const bounded = AbortSignal.any([signal ?? new AbortController().signal, AbortSignal.timeout(REFERENCE_TIMEOUT_MS)]);
+		const filesAvailable = this.filesAvailable;
+		const sessionsAvailable = this.sessionsAvailable;
+		const [files, sessions] = await Promise.all([filesAvailable ? this.invoke("fileReferences", "list", {
+			agentId: sessionId,
+			query
+		}, bounded).then(fileItems, () => []) : Promise.resolve([]), sessionsAvailable ? this.invoke("sessionReferenceResolver", "candidates", {
+			agentId: sessionId,
+			query
+		}, bounded).then(sessionItems, () => []) : Promise.resolve([])]);
+		return {
+			files: {
+				available: filesAvailable,
+				items: files
+			},
+			sessions: {
+				available: sessionsAvailable,
+				items: sessions
+			}
+		};
+	}
+};
+/**
+* 网关对不同 Remote 的返回形态不一：有的直接给值（如 `commands/list`），有的给
+* `RemoteResult {ok, value | error}`（如 `sessionFeedback/record`）。两种都接受，失败抛出。
+*/
+function unwrapRemote(result) {
+	if (result && typeof result === "object" && !Array.isArray(result) && typeof result.ok === "boolean") {
+		if (result.ok) return result.value;
+		throw Object.assign(new Error(result.error?.message ?? "reference lookup failed"), { code: result.error?.code });
+	}
+	return result;
+}
+/** 只保留形状合法的行；主机排序原样保留。 */
+function fileItems(rows) {
+	if (!Array.isArray(rows)) return [];
+	const items = [];
+	for (const row of rows) {
+		if (items.length >= 30) break;
+		const path = row?.path;
+		const kind = row?.kind;
+		if (typeof path !== "string" || !path || path.length > 4096 || kind !== "file" && kind !== "directory") continue;
+		items.push({
+			path,
+			kind
+		});
+	}
+	return items;
+}
+/** 标签优先用主机给的显示标题（子代理的创建标签），与规范 mention 里的文字一致。 */
+function sessionItems(rows) {
+	if (!Array.isArray(rows)) return [];
+	const items = [];
+	for (const row of rows) {
+		if (items.length >= 10) break;
+		const r = row;
+		const label = typeof r?.displayTitle === "string" && r.displayTitle ? r.displayTitle : r?.label;
+		if (typeof r?.sessionId !== "string" || !r.sessionId || typeof label !== "string" || !label || typeof r.mention !== "string" || r.mention.length > 4096 || !SESSION_MENTION.test(r.mention)) continue;
+		items.push({
+			sessionId: r.sessionId,
+			label,
+			mention: r.mention,
+			sameWorkspace: r.sameWorkspace === true
+		});
+	}
+	return items;
+}
 // src/dsh-api-proxy.ts
 /**
 * Adapter for the DSH rc.2 controller API.
@@ -10775,6 +11239,12 @@ var DshApiProxy = class {
 			export: (request, signal) => this.commandApi.export(request.payload.sessionId, signal, request.payload.format)
 		};
 	}
+	referenceApi;
+	/** 引用服务可能晚于桥接层挂载：每次读取都按当前服务判定，不缓存缺席。 */
+	get references() {
+		if (!this.referenceApi.available) return void 0;
+		return { list: (request, signal) => this.call(() => this.referenceApi.list(request.payload.sessionId, request.payload.query, signal)) };
+	}
 	session;
 	workspaceController;
 	scheduleController;
@@ -10785,6 +11255,7 @@ var DshApiProxy = class {
 	constructor(ctx, options = {}) {
 		this.ctx = ctx;
 		this.commandApi = new DshCommandApi(ctx);
+		this.referenceApi = new DshReferenceApi(ctx);
 		const session = ctx.get("sessionController");
 		if (session === void 0) throw new Error("DSH sessionController is unavailable");
 		this.session = session;