@webskill/sdk 0.20.0 → 0.21.0

package/dist/toolSource-C9oNuKmr.js

@@ -0,0 +1,565 @@
+import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
+
+//#region ../agent/src/frame.ts
+/**
+* 帧指称的展示形式（分册 18 FR-18.2）。
+*
+* 感知与操作两侧各自声明自己的 scope 类型（那是刻意的，见各自 types.ts），
+* 但「一条帧路径写成给人看的字符串」只能有一份实现——
+* 两处各写一遍，审计里的帧名和确认卡里的帧名就会慢慢对不上。
+*/
+/**
+* 帧路径的稳定展示串：`'self'` / `'#a'` / `'#a >>> #b'`。
+*
+* `>>>` **只是展示分隔符**：CSS 选择器里可以合法出现任意字符，
+* 反向解析这个串取回路径是不成立的，实现层一律传原始形状（D-18-1）。
+* @experimental
+*/
+function frameLabel(frame) {
+	if (typeof frame === "string") return frame;
+	if (frame.length === 0) return "self";
+	return frame.join(" >>> ");
+}
+/** 把两种形状归一成逐层选择器数组；`'self'` 与空数组都归一成空数组 @experimental */
+function frameSteps(frame) {
+	if (typeof frame === "string") return frame === "self" ? [] : [frame];
+	return frame;
+}
+
+//#endregion
+//#region ../agent/src/perception/types.ts
+/**
+* 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`（FR-24.1）。
+*
+* **这是判别的单一来源。** 散在各处写 `'frames' in scope` 会让
+* 「旧配置还等价吗」这个问题没有唯一答案。
+* @experimental
+*/
+function toFrameScopes(scope) {
+	if ("frames" in scope) return scope.frames;
+	return [{
+		frame: "self",
+		include: scope.include,
+		...scope.exclude ? { exclude: scope.exclude } : {}
+	}];
+}
+
+//#endregion
+//#region ../agent/src/pageAction/types.ts
+/**
+* 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`。
+* 与感知侧的 `toFrameScopes` 一样，是本侧判别的**单一来源**。
+* @experimental
+*/
+function toActionFrameScopes(scope) {
+	if ("frames" in scope) return scope.frames;
+	return [{
+		frame: "self",
+		include: scope.include,
+		...scope.exclude ? { exclude: scope.exclude } : {}
+	}];
+}
+/**
+* 本版的操作集（FR-25.1 / 0.16.0 FR-13.6 / 0.18.0 FR-10.1）。拖拽仍不在内（D64）；
+* 导航只有 `back` 一个，且它**不接受地址**——可达面被浏览器历史封死（SC-1）。
+*
+* `select`/`set`/`attach`/`scroll` 与既有几个走**同一条** policy 路径，
+* 范围白名单、逐次确认、审计三条硬约束因此天然覆盖到它们——
+* 前提是新动作不绕过 policy 直调执行器（AC-25.4 守这一点）。
+* @experimental
+*/
+const PAGE_ACTION_KINDS = [
+	"click",
+	"fill",
+	"submit",
+	"select",
+	"set",
+	"attach",
+	"scroll",
+	"back"
+];
+/**
+* `back` 的目标占位（0.16.0 分册 13 §4.1）。
+*
+* **模型不能表达它**：工具源在 `action === 'back'` 时拒绝任何 `ref` 入参。
+* 它存在只为了让 `back` 不必改 `PageActionRequest.ref` 的类型——
+* 改它会波及所有实现过 executor 的宓主。
+* @experimental
+*/
+const PAGE_DOCUMENT_REF = "@document";
+
+//#endregion
+//#region ../agent/src/document/budget.ts
+/** @experimental */
+const DOCUMENT_READ_BUDGET = {
+	textChars: 96e3,
+	visionImages: 8
+};
+
+//#endregion
+//#region ../agent/src/document/format.ts
+const PDF_MAGIC = [
+	37,
+	80,
+	68,
+	70,
+	45
+];
+const ZIP_MAGIC = [
+	80,
+	75,
+	3,
+	4
+];
+function startsWith(bytes, magic) {
+	return magic.every((b, i) => bytes[i] === b);
+}
+/** zip 的本地文件头把条目名以明文 ASCII 存着，扫一遍即可，不必解压 */
+function containsEntry(bytes, name) {
+	const needle = new TextEncoder().encode(name);
+	const find = (from, to) => {
+		outer: for (let i = from; i + needle.length <= to; i += 1) {
+			for (let j = 0; j < needle.length; j += 1) if (bytes[i + j] !== needle[j]) continue outer;
+			return true;
+		}
+		return false;
+	};
+	const WINDOW = 64 * 1024;
+	if (find(0, Math.min(bytes.length, WINDOW))) return true;
+	return find(Math.max(0, bytes.length - WINDOW * 2), bytes.length);
+}
+/**
+* 格式以字节为准，文件名只作次要线索：改扩展名不该改变我们如何解析它。
+* 认不出返回 `undefined`，由调用方归因。
+* @experimental
+*/
+function sniffDocumentFormat(bytes, name) {
+	if (startsWith(bytes, PDF_MAGIC)) return "pdf";
+	if (!startsWith(bytes, ZIP_MAGIC)) return void 0;
+	const lower = (name ?? "").toLowerCase();
+	if (lower.endsWith(".docx")) return "docx";
+	if (lower.endsWith(".xlsx")) return "xlsx";
+	if (containsEntry(bytes, "word/document.xml")) return "docx";
+	if (containsEntry(bytes, "xl/workbook.xml")) return "xlsx";
+}
+
+//#endregion
+//#region ../agent/src/document/pdfQuality.ts
+/**
+* 「这一页抽出来的是不是乱码」的判定（0.21.0 分册 22 · FR-22.2）。
+*
+* 判定必须是纯函数：它决定一页走文本还是走渲染，而渲染要烧一次多模态请求。
+* 靠人眼看一遍不叫判据。
+*/
+/** 坏字符占可打印字符的比例超过它即判文本层不可信 @experimental */
+const PDF_GARBLED_RATIO = .2;
+/** 短于它的页不参与比例判定：三五个字符里有一个私用区字符说明不了任何事 */
+const MIN_SAMPLE = 16;
+/**
+* 坏字符有三类，来源各不相同：
+* - 私用区 U+E000–U+F8FF：字体子集没有 `ToUnicode` 时，pdfjs 把 CID 原样落在这里
+* - U+FFFD：解码失败的替换字符
+* - C0/C1 控制字符：把二进制当文本读出来的残留
+*/
+function isGarbledChar(code) {
+	if (code >= 57344 && code <= 63743) return true;
+	if (code === 65533) return true;
+	if (code < 32 && code !== 9 && code !== 10 && code !== 13) return true;
+	return code >= 127 && code <= 159;
+}
+/**
+* 空白页一律判不可信：它要么是扫描页、要么什么都没有，
+* 两种情况都该让模型自己看一眼，而不是把一页空气交上去。
+* @experimental
+*/
+function measurePdfTextQuality(text) {
+	let printable = 0;
+	let garbled = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (/\s/u.test(ch)) continue;
+		printable += 1;
+		if (isGarbledChar(code)) garbled += 1;
+	}
+	if (printable === 0) return {
+		printable,
+		garbled,
+		trustworthy: false
+	};
+	if (printable < MIN_SAMPLE) return {
+		printable,
+		garbled,
+		trustworthy: garbled === 0
+	};
+	return {
+		printable,
+		garbled,
+		trustworthy: garbled / printable <= PDF_GARBLED_RATIO
+	};
+}
+/** `measurePdfTextQuality(text).trustworthy` 的简写 @experimental */
+function isPdfTextTrustworthy(text) {
+	return measurePdfTextQuality(text).trustworthy;
+}
+
+//#endregion
+//#region ../agent/src/document/deferral.ts
+/** @experimental */
+function takesImage(mode, role) {
+	if (mode === "vision") return true;
+	if (mode === "images") return role === "illustration";
+	return role === "content";
+}
+/** 本次没取、但回头取得到的图（进返回值的 `deferred`） @experimental */
+function defersImage(mode, role) {
+	return mode === "auto" && role === "illustration";
+}
+/** 入参里的 `mode` 只认这三个字面量，其余一律当 `auto` @experimental */
+function asReadMode(raw) {
+	return raw === "vision" || raw === "images" ? raw : "auto";
+}
+
+//#endregion
+//#region ../agent/src/document/toolSource.ts
+/** @experimental */
+const READ_DOCUMENT_TOOL = "read_document";
+/** 大图的门槛：低于它的是页眉 logo、印章、项目符号，投它们等于白烧一次多模态请求 @experimental */
+const PDF_LARGE_IMAGE_RATIO = .15;
+const DESCRIPTION = "Read a PDF, Word (.docx) or Excel (.xlsx) document the user attached or downloaded, one batch of units at a time. Pages that have no usable text layer (scans) are rendered as images, so their content is never lost. Pictures on pages whose text is readable are listed under \"deferred\" instead of being returned, because reading them costs an extra round trip; call again with mode=\"images\" to fetch those.";
+const INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		id: {
+			type: "string",
+			description: "The attachment id, or the id from list_downloaded_files."
+		},
+		from: {
+			type: "object",
+			description: "Where to continue. Omit to start at the beginning; otherwise pass the \"next\" of the previous call.",
+			properties: {
+				page: {
+					type: "number",
+					description: "PDF only: 0-based page index."
+				},
+				block: {
+					type: "number",
+					description: "Word only: 0-based block index."
+				},
+				sheet: {
+					type: "number",
+					description: "Excel only: 0-based sheet index."
+				},
+				row: {
+					type: "number",
+					description: "Excel only: 0-based row index within the sheet."
+				}
+			},
+			additionalProperties: false
+		},
+		mode: {
+			type: "string",
+			enum: [
+				"auto",
+				"images",
+				"vision"
+			],
+			description: "\"auto\" (default) returns text plus the pictures that cannot be replaced by text, and lists the rest under \"deferred\". \"images\" returns only those deferred pictures and no text. \"vision\" (PDF only) renders every page as an image and ignores the text layer."
+		}
+	},
+	required: ["id"],
+	additionalProperties: false
+};
+const SYSTEM_PROMPT = "read_document reads an attached or downloaded PDF/Word/Excel document in batches. It returns a \"next\" cursor whenever the document is not finished: keep calling read_document with that cursor until the result has no \"next\", otherwise you have only seen part of the document. Read the text first and answer from it; a result that carries \"deferred\" means those units hold pictures that were not read yet. Fetch them with mode=\"images\" only when the answer depends on what they show, and tell the user the pictures have not been looked at when you answer without them. Never guess an id, and never claim you read a document you only read part of.";
+function toolError(e) {
+	return {
+		ok: false,
+		content: [],
+		error: {
+			code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+			message: messageOf(e)
+		}
+	};
+}
+/** 包一层：直写 `signal?.aborted` 会被 TS 按第一次检查永久收窄成 false */
+function aborted(signal) {
+	return signal !== void 0 && signal.aborted;
+}
+/**
+* 逐单元读文档，读不出字的地方出图（0.21.0 分册 22）。
+*
+* 三个端口一个都没接时 `listToolSpecs()` 返回空——模型连这个工具的存在都看不到，
+* 而不是看得到再被拒（AC-22.2）。
+* @experimental
+*/
+function createDocumentToolSource(options) {
+	const { files } = options;
+	const available = () => options.pdf !== void 0 || options.docx !== void 0 || options.xlsx !== void 0;
+	const budgetOf = () => options.budget?.() ?? DOCUMENT_READ_BUDGET;
+	return {
+		kind: "document-reader",
+		listToolSpecs: () => Promise.resolve(available() ? [{
+			name: READ_DOCUMENT_TOOL,
+			description: DESCRIPTION,
+			inputSchema: INPUT_SCHEMA
+		}] : []),
+		systemPrompt: () => Promise.resolve(available() ? SYSTEM_PROMPT : void 0),
+		canHandle: (name) => name === READ_DOCUMENT_TOOL,
+		argCaptureTrust: (name) => name === "read_document" ? { tier: "reviewed" } : void 0,
+		call: async (name, args, context) => {
+			try {
+				if (name !== "read_document") throw new WebSkillError("TOOL_NOT_FOUND", `Unknown tool ${name}.`);
+				return await read(args, context?.signal);
+			} catch (e) {
+				return toolError(e);
+			}
+		}
+	};
+	async function read(args, signal) {
+		const id = args["id"];
+		if (typeof id !== "string" || id === "") throw new WebSkillError("TOOL_UNSUPPORTED", "read_document requires the \"id\" of an attachment or download.");
+		const file = await files.read(id);
+		if (file === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `No readable document with id "${id}". It is either not an attachment of the current message, or a download id that has since expired — list the downloads again to get a fresh one.`);
+		const format = sniffDocumentFormat(file.bytes, file.name);
+		if (format === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `"${file.name}" is not a PDF, Word (.docx) or Excel (.xlsx) document, so read_document cannot read it.`);
+		const reader = readerFor(format);
+		if (reader === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `This environment cannot read ${format.toUpperCase()} documents.`);
+		const from = asCursor(args["from"]);
+		const mode = asReadMode(args["mode"]);
+		const budget = budgetOf();
+		const batch = format === "pdf" ? await readPdf(reader, file.bytes, from, mode, budget, signal) : format === "docx" ? await readDocx(reader, file.bytes, from, mode, budget, signal) : await readXlsx(reader, file.bytes, from, mode, budget, signal);
+		return {
+			ok: true,
+			content: describe(file.name, format, batch, aborted(signal))
+		};
+	}
+	function readerFor(format) {
+		if (format === "pdf") return options.pdf;
+		if (format === "docx") return options.docx;
+		return options.xlsx;
+	}
+}
+function asCursor(raw) {
+	if (typeof raw !== "object" || raw === null) return {};
+	const out = {};
+	for (const key of [
+		"page",
+		"block",
+		"sheet",
+		"row"
+	]) {
+		const value = raw[key];
+		if (typeof value === "number" && Number.isInteger(value) && value >= 0) out[key] = value;
+	}
+	return out;
+}
+/**
+* 预算是「加上这一个还超不超」，不是「已经超了没有」：
+* 后者会把一个超大单元整个吞下去再喊停，等于预算形同虚设。
+* 但**至少读一个单元**，否则一个超预算的单元会让续读原地打转。
+*/
+function wouldExceed(budget, taken, chars, images) {
+	if (taken === 0) return false;
+	return chars > budget.textChars || images > budget.visionImages;
+}
+async function readPdf(reader, bytes, from, mode, budget, signal) {
+	const handle = await reader.open(bytes);
+	try {
+		const start = from["page"] ?? 0;
+		const units = [];
+		const deferred = [];
+		let chars = 0;
+		let images = 0;
+		let page = start;
+		for (; page < handle.pageCount; page += 1) {
+			if (aborted(signal)) break;
+			const text = mode === "vision" ? "" : await handle.text(page);
+			const trustworthy = mode !== "vision" && isPdfTextTrustworthy(text);
+			const role = trustworthy ? "illustration" : "content";
+			const hasImage = role === "content" || await hasLargeImage(handle, page);
+			const needsImage = hasImage && takesImage(mode, role);
+			if (mode === "images" && !needsImage) continue;
+			const withText = trustworthy && mode !== "images";
+			const nextChars = chars + (withText ? text.length : 0);
+			const nextImages = images + (needsImage ? 1 : 0);
+			if (wouldExceed(budget, units.length, nextChars, nextImages)) break;
+			if (aborted(signal)) break;
+			const rendered = needsImage ? await handle.render(page) : void 0;
+			if (hasImage && defersImage(mode, role)) deferred.push({ page });
+			units.push({
+				unit: { page },
+				...withText ? { text } : {},
+				...rendered ? { image: rendered } : {}
+			});
+			chars = nextChars;
+			images = nextImages;
+		}
+		return {
+			units,
+			total: handle.pageCount,
+			done: page,
+			skippedImages: 0,
+			deferred,
+			...page < handle.pageCount ? { next: { page } } : {}
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function hasLargeImage(handle, page) {
+	return (await handle.images(page)).some((image) => image.areaRatio >= PDF_LARGE_IMAGE_RATIO);
+}
+async function readDocx(reader, bytes, from, mode, budget, signal) {
+	const { blocks } = await reader.read(bytes);
+	const taken = takeBlocks(blocks, from["block"] ?? 0, mode, budget, signal, (index) => ({ block: index }));
+	return {
+		units: taken.units,
+		total: blocks.length,
+		done: taken.stopped,
+		skippedImages: taken.skippedImages,
+		deferred: taken.deferred,
+		...taken.stopped < blocks.length ? { next: { block: taken.stopped } } : {}
+	};
+}
+async function readXlsx(reader, bytes, from, mode, budget, signal) {
+	const { sheets } = await reader.read(bytes);
+	const flat = [];
+	sheets.forEach((sheet, sheetIndex) => {
+		sheet.rows.forEach((block, rowIndex) => {
+			flat.push({
+				sheet: sheetIndex,
+				sheetName: sheet.name,
+				row: rowIndex,
+				block
+			});
+		});
+	});
+	const startSheet = from["sheet"] ?? 0;
+	const startRow = from["row"] ?? 0;
+	const found = flat.findIndex((entry) => entry.sheet > startSheet || entry.sheet === startSheet && entry.row >= startRow);
+	const start = found === -1 ? flat.length : found;
+	const taken = takeBlocks(flat.map((entry) => entry.block), start, mode, budget, signal, (index) => ({
+		sheet: flat[index].sheet,
+		sheetName: flat[index].sheetName,
+		row: flat[index].row
+	}));
+	const stop = flat[taken.stopped];
+	return {
+		units: taken.units,
+		total: flat.length,
+		done: taken.stopped,
+		skippedImages: taken.skippedImages,
+		deferred: taken.deferred,
+		...stop ? { next: {
+			sheet: stop.sheet,
+			row: stop.row
+		} } : {}
+	};
+}
+function takeBlocks(blocks, start, mode, budget, signal, locate) {
+	const units = [];
+	const deferred = [];
+	let chars = 0;
+	let images = 0;
+	let skippedImages = 0;
+	let index = start;
+	for (; index < blocks.length; index += 1) {
+		if (aborted(signal)) break;
+		const block = blocks[index];
+		if (block.kind === "skipped") {
+			skippedImages += 1;
+			continue;
+		}
+		if (!(block.kind === "text" ? mode !== "images" : takesImage(mode, "illustration"))) {
+			if (block.kind === "image" && defersImage(mode, "illustration")) deferred.push(locate(index));
+			continue;
+		}
+		const nextChars = chars + (block.kind === "text" ? block.text.length : 0);
+		const nextImages = images + (block.kind === "image" ? 1 : 0);
+		if (wouldExceed(budget, units.length, nextChars, nextImages)) break;
+		units.push({
+			unit: locate(index),
+			...block.kind === "text" ? { text: block.text } : {},
+			...block.kind === "image" ? { image: {
+				mimeType: block.mimeType,
+				data: block.data
+			} } : {}
+		});
+		chars = nextChars;
+		images = nextImages;
+	}
+	return {
+		units,
+		stopped: index,
+		skippedImages,
+		deferred
+	};
+}
+/**
+* 图只能走 user 消息，出处只能随同一结果里的 json 分片走——
+* 与下载工具源同款（引擎把图转成 carried 时会丢掉 id 与文件名）。
+*/
+function describe(name, format, batch, cancelled) {
+	const images = [];
+	const units = batch.units.map((entry) => {
+		const located = {
+			...entry.unit,
+			...entry.text === void 0 ? {} : { text: entry.text }
+		};
+		if (entry.image === void 0) return located;
+		const imageId = imageIdOf(entry.unit);
+		images.push({
+			type: "image",
+			id: imageId,
+			mimeType: entry.image.mimeType,
+			data: entry.image.data
+		});
+		return {
+			...located,
+			imageId
+		};
+	});
+	const withText = batch.units.filter((entry) => entry.text !== void 0).length;
+	const withImage = images.length;
+	const remaining = Math.max(0, batch.total - batch.done);
+	const json = {
+		file: name,
+		format,
+		source: withImage === 0 ? "text" : withText === 0 ? "vision" : "mixed",
+		total: batch.total,
+		units,
+		remaining,
+		note: continuationNote(format, batch, remaining, cancelled)
+	};
+	if (batch.next !== void 0) {
+		json["next"] = batch.next;
+		json["truncated"] = true;
+	}
+	if (batch.skippedImages > 0) json["skipped"] = {
+		images: batch.skippedImages,
+		reason: "EMF/WMF images cannot be decoded in a browser and were left out."
+	};
+	if (batch.deferred.length > 0) json["deferred"] = {
+		images: batch.deferred.length,
+		units: batch.deferred,
+		note: `${batch.deferred.length} unit(s) above hold pictures that were not read, because their text is readable on its own. Answer from the text when you can. If the answer depends on what a picture shows, call read_document again with mode="images" and from = ${JSON.stringify(batch.deferred[0])}, and say so if you answer without looking at them.`
+	};
+	return [{
+		type: "json",
+		data: json
+	}, ...images];
+}
+function continuationNote(format, batch, remaining, cancelled) {
+	const noun = format === "pdf" ? "page" : format === "docx" ? "block" : "row";
+	if (batch.next === void 0) return `Reached the end of the document; all ${batch.total} ${noun}s have been read.`;
+	const cursor = JSON.stringify(batch.next);
+	return `${cancelled ? "Stopped because the user cancelled the run" : `${remaining} ${noun}(s) still unread`}. Call read_document again with from = ${cursor} to continue.`;
+}
+/** 由单元坐标推出，因此与 `units[].imageId` 天然对得上，不依赖批次内的序号 */
+function imageIdOf(unit) {
+	if (typeof unit["page"] === "number") return `doc-p${unit["page"]}`;
+	if (typeof unit["block"] === "number") return `doc-b${unit["block"]}`;
+	return `doc-s${unit["sheet"]}r${unit["row"]}`;
+}
+
+//#endregion
+export { frameSteps as _, defersImage as a, isPdfTextTrustworthy as c, DOCUMENT_READ_BUDGET as d, PAGE_ACTION_KINDS as f, frameLabel as g, toFrameScopes as h, asReadMode as i, measurePdfTextQuality as l, toActionFrameScopes as m, READ_DOCUMENT_TOOL as n, takesImage as o, PAGE_DOCUMENT_REF as p, createDocumentToolSource as r, PDF_GARBLED_RATIO as s, PDF_LARGE_IMAGE_RATIO as t, sniffDocumentFormat as u };

package/dist/{types-Btpdd1y--BcxQ10Fa.d.ts → types-BvTV_05--BW8zDuEk.d.ts}

@@ -28,6 +28,12 @@ type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FO
 'UPLOAD_FILE_NOT_FOUND' |
 /** 上传文件超预算。与 DATA_SOURCE_TOO_LARGE 同口径：拒绝而不截断 */
 'UPLOAD_FILE_TOO_LARGE' |
+/** 页面上没有可读的 WebOffice 实例，或指定的 handle 已失效（0.21.0 分册 11） */
+'WEBOFFICE_UNAVAILABLE' |
+/** 认出来的不是我们支持的 WebOffice SDK 版本；不降级去猜（0.21.0 FR-11.6b） */
+'WEBOFFICE_UNSUPPORTED_VERSION' |
+/** `api.ready` 描述符里没有这个方法。与「调用失败」分开：用户的下一步不同 */
+'WEBOFFICE_CAPABILITY_ABSENT' | 'WEBOFFICE_CALL_FAILED' | 'WEBOFFICE_CALL_TIMEOUT' |
 /** 用户拒绝了这次工具调用（0.14.0 分册 20） */
 'TOOL_DENIED';
 /**
@@ -189,6 +195,20 @@ interface FileStat {
   size?: number;
   mtimeMs?: number;
 }
+/**
+ * 分块写入的句柄（0.21.0 分册 18 · FR-18.2）。
+ *
+ * 语义与 `writeBinary` 对齐：`close()` 之前这份内容不得被当成完整文件读到；
+ * 中途失败调 `abort()`，实现必须保证不留下会被误当成完整文件的残件（FR-18.2e）。
+ */
+interface FileWriteStream {
+  /** 追加一块。`close()`/`abort()` 之后再调即为错误。 */
+  write(chunk: Uint8Array): Promise<void>;
+  /** 提交。此后文件才对 `readBinary` / `exists` 可见为完整内容。 */
+  close(): Promise<void>;
+  /** 放弃。已写入的部分必须被丢弃。 */
+  abort(): Promise<void>;
+}
 /**
  * 文件系统抽象：core 只依赖此接口，Node/浏览器各自提供实现。
  * 路径一律使用 `/` 分隔的 POSIX 风格。
@@ -201,6 +221,14 @@ interface FileSystemProvider {
   appendText(path: string, content: string): Promise<void>;
   readBinary(path: string): Promise<Uint8Array>;
   writeBinary(path: string, content: Uint8Array): Promise<void>;
+  /**
+   * 可选：分块写入，避免整份文件进内存（0.21.0 分册 18 · FR-18.2）。
+   *
+   * **必须是可选的**：`FileSystemProvider` 有宿主自己的实现，加必选成员等于让它们
+   * 一夜之间不满足接口。缺省时调用方回落到 `writeBinary`——功能不降级，
+   * 只是内存峰值回到全量读取的水平（FR-18.2b）。
+   */
+  createWriteStream?(path: string): Promise<FileWriteStream>;
   exists(path: string): Promise<boolean>;
   stat(path: string): Promise<FileStat>;
   list(path: string): Promise<FileStat[]>;
@@ -345,6 +373,11 @@ declare class MemoryFS implements FileSystemProvider {
   appendText(path: string, content: string): Promise<void>;
   readBinary(path: string): Promise<Uint8Array>;
   writeBinary(path: string, content: Uint8Array): Promise<void>;
+  /**
+   * 分块写入（FR-18.2c）。内存实现只能先攒着，`close()` 时才合并落表——
+   * 这样中途 `abort()` 或抛错都不会在表里留下半份内容（FR-18.2e）。
+   */
+  createWriteStream(path: string): Promise<FileWriteStream>;
   exists(path: string): Promise<boolean>;
   stat(path: string): Promise<FileStat>;
   list(path: string): Promise<FileStat[]>;
@@ -469,6 +502,12 @@ interface AttachmentTextInput {
   kind: 'text' | 'document-text';
   /** 缺省即用户当场上传；`'download'` 时标签里额外标出本机下载目录（0.14.0 FR-20.5） */
   origin?: 'upload' | 'download';
+  /**
+   * 正文截断的字符上限，缺省 `ATTACHMENT_TEXT_LIMIT`。
+   * 调用方自己有预算、且**按预算拒绝而不是截断**时传自己的值——
+   * 不传就会被这里 32 KiB 的兜底静默切掉，长文档看起来完整、实则只剩开头。
+   */
+  limit?: number;
 }
 /**
  * 文本类附件进模型上下文的最终形态。两条入口共用，差别只有出处那一段（0.14.0 D-20-6）。
@@ -716,7 +755,7 @@ declare function escapeXml(text: string): string;
 declare function renderAvailableSkillsXml(catalog: SkillCatalog): string;
 declare const xmlRenderer: CatalogRenderer;
 //#endregion
-//#region ../runtime/dist/types-Btpdd1y-.d.ts
+//#region ../runtime/dist/types-BvTV_05-.d.ts
 //#region src/llm/streamTypes.d.ts
 /** 流式 LLM 事件（OpenAI SSE / Vercel fullStream 统一映射） */
 type LlmStreamEvent = {
@@ -941,7 +980,19 @@ type InteractionRequest = {
   /** 读取本机下载目录（0.14.0 分册 20） */
   'readDownloadedFile' |
   /** 读取本轮上传的文件（0.15.0 分册 17；0.17.0 分册 19 从 `confirm` 改到这里） */
-  'readUploadFile';
+  'readUploadFile' |
+  /**
+   * 读取页面里嵌的 WPS WebOffice 文档（0.21.0 分册 13）。
+   * 只有一个字面量，三种动作（列出 / 读取 / 截屏）靠 `details.action` 分——
+   * 分成三个能力会让宿主的能力开关变成三个，而用户心里它是一件事。
+   */
+  'readWebOfficeDocument' |
+  /**
+   * 把工具产出的图交给第二个模型端点认（0.21.0 分册 17）。
+   * 这是一次**数据出境**：用户选 A 家模型时并没有同意发给 B 家，
+   * 所以它必须是一个独立能力位，而不是并进任何一个「读」的授权里。
+   */
+  'delegateVision';
   message: string;
   /**
    * 结构化载荷。`message` 是无字典层的英文兜底，持有字典的宿主据本字段重写正文
@@ -1159,4 +1210,4 @@ interface MemoryStore {
   transaction?<T>(scope: string, fn: (inner: MemoryStore) => Promise<T>): Promise<T>;
 }
 //#endregion
-export { SKILLS_LOCKFILE as $, messageOf as $t, extractSkillCandidate as A, ValidationReport as At, DiscoveryResult as B, checkDependencyCycles as Bt, UiSpecActionCapability as C, SkillsLockfile as Ct, UiSpecSnapshot as D, UNTRUSTED_LINE_LIMIT as Dt, UiSpecPatch as E, TrustedKeyStore as Et, CatalogRenderer as F, assertRemoteUrlAllowed as Ft, IMAGE_MIME_TYPES as G, detectSkillArchiveShapeFromFs as Gt, FileStat as H, classifyAttachment as Ht, ChatAttachmentKind as I, assertSafePathSegment as It, MemoryFS as J, formatAttachmentText as Jt, JsonSchema as K, escapeXml as Kt, CryptoKeyLike as L, atomicWriteText as Lt, ATTACHMENT_TEXT_LIMIT as M, WebSkillError as Mt, ArchiveLimits as N, WebSkillErrorCode as Nt, UiSurfaceActionRequest as O, UiSpecNode as Ot, AttachmentTextInput as P, XLSX_MIME as Pt, SIGNATURE_SCHEMA_VERSION as Q, keyIdOf as Qt, DEFAULT_ARCHIVE_LIMITS as R, buildCatalog as Rt, UiBridge as S, SkillSource as St, UiSpecEvent as T, TrustedKey as Tt, FileSystemProvider as U, computeDigest as Ut, FILE_MIME_TYPES as V, checkSkillRules as Vt, FsTrustedKeyStore as W, detectSkillArchiveShape as Wt, PageQuery as X, isValidSkillName as Xt, Page as Y, isAtomicTempPath as Yt, RemoteUrlPolicy as Z, jsonRenderer as Zt, LlmToolSpec as _, xmlRenderer as _n, SkillManifest as _t, InteractionOrigin as a, renderAvailableSkillsXml as an, SignatureAuditSink as at, RenderResultRequest as b, SkillReader as bt, InteractionResponse as c, resolveInsideRoot as cn, SkillArchiveShape as ct, LlmContentPart as d, signaturePayloadBytes as dn, SkillDiscovery as dt, normalizePath as en, SKILL_MANIFEST_FILE as et, LlmMessage as f, stripArchiveRoot as fn, SkillDocument as ft, LlmToolCall as g, verifySkillSignature as gn, SkillManagerPort as gt, LlmTokenUsage as h, verifyManifest as hn, SkillLocation as ht, FormField as i, readSkillSignature as in, SKILL_SIGNATURE_FILE as it, ATOMIC_TMP_SUFFIX_PATTERN as j, VerifyResult as jt, UiSurfaceActionResponse as k, UnsignedPolicy as kt, LlmClient as l, sanitizeUntrustedLine as ln, SkillCatalog as lt, LlmStreamEvent as m, validateSkills as mn, SkillIssue as mt, ArtifactStore as n, parseSkillPackManifest as nn, SKILL_NAME_PATTERN as nt, InteractionPolicy as o, renderCatalogJson as on, SignatureVerdict as ot, LlmResponse as p, unzipWithLimits as pn, SkillInstallSource as pt, MANIFEST_EXCLUDED_FILES as q, exportSkills as qt, ChartSpec as r, readResponseWithLimit as rn, SKILL_PACK_FILE as rt, InteractionRequest as s, resolveArchiveLimits as sn, SkillArchiveDetection as st, Artifact as t, parseSkillMarkdown as tn, SKILL_NAME_MAX_LENGTH as tt, LlmCompleteInput as u, signSkill as un, SkillCatalogEntry as ut, MemoryStore as v, SkillMetadata as vt, UiSpecDrafts as w, TEXT_EXTENSIONS as wt, SkillCandidateMarker as x, SkillSignature as xt, RenderBlock as y, SkillPackManifest as yt, DOCX_MIME as z, buildManifest as zt };
+export { SIGNATURE_SCHEMA_VERSION as $, keyIdOf as $t, extractSkillCandidate as A, UnsignedPolicy as At, DiscoveryResult as B, buildManifest as Bt, UiSpecActionCapability as C, SkillSource as Ct, UiSpecSnapshot as D, TrustedKeyStore as Dt, UiSpecPatch as E, TrustedKey as Et, CatalogRenderer as F, XLSX_MIME as Ft, FsTrustedKeyStore as G, detectSkillArchiveShape as Gt, FileStat as H, checkSkillRules as Ht, ChatAttachmentKind as I, assertRemoteUrlAllowed as It, MANIFEST_EXCLUDED_FILES as J, exportSkills as Jt, IMAGE_MIME_TYPES as K, detectSkillArchiveShapeFromFs as Kt, CryptoKeyLike as L, assertSafePathSegment as Lt, ATTACHMENT_TEXT_LIMIT as M, VerifyResult as Mt, ArchiveLimits as N, WebSkillError as Nt, UiSurfaceActionRequest as O, UNTRUSTED_LINE_LIMIT as Ot, AttachmentTextInput as P, WebSkillErrorCode as Pt, RemoteUrlPolicy as Q, jsonRenderer as Qt, DEFAULT_ARCHIVE_LIMITS as R, atomicWriteText as Rt, UiBridge as S, SkillSignature as St, UiSpecEvent as T, TEXT_EXTENSIONS as Tt, FileSystemProvider as U, classifyAttachment as Ut, FILE_MIME_TYPES as V, checkDependencyCycles as Vt, FileWriteStream as W, computeDigest as Wt, Page as X, isAtomicTempPath as Xt, MemoryFS as Y, formatAttachmentText as Yt, PageQuery as Z, isValidSkillName as Zt, LlmToolSpec as _, verifySkillSignature as _n, SkillManagerPort as _t, InteractionOrigin as a, readSkillSignature as an, SKILL_SIGNATURE_FILE as at, RenderResultRequest as b, SkillPackManifest as bt, InteractionResponse as c, resolveArchiveLimits as cn, SkillArchiveDetection as ct, LlmContentPart as d, signSkill as dn, SkillCatalogEntry as dt, messageOf as en, SKILLS_LOCKFILE as et, LlmMessage as f, signaturePayloadBytes as fn, SkillDiscovery as ft, LlmToolCall as g, verifyManifest as gn, SkillLocation as gt, LlmTokenUsage as h, validateSkills as hn, SkillIssue as ht, FormField as i, readResponseWithLimit as in, SKILL_PACK_FILE as it, ATOMIC_TMP_SUFFIX_PATTERN as j, ValidationReport as jt, UiSurfaceActionResponse as k, UiSpecNode as kt, LlmClient as l, resolveInsideRoot as ln, SkillArchiveShape as lt, LlmStreamEvent as m, unzipWithLimits as mn, SkillInstallSource as mt, ArtifactStore as n, parseSkillMarkdown as nn, SKILL_NAME_MAX_LENGTH as nt, InteractionPolicy as o, renderAvailableSkillsXml as on, SignatureAuditSink as ot, LlmResponse as p, stripArchiveRoot as pn, SkillDocument as pt, JsonSchema as q, escapeXml as qt, ChartSpec as r, parseSkillPackManifest as rn, SKILL_NAME_PATTERN as rt, InteractionRequest as s, renderCatalogJson as sn, SignatureVerdict as st, Artifact as t, normalizePath as tn, SKILL_MANIFEST_FILE as tt, LlmCompleteInput as u, sanitizeUntrustedLine as un, SkillCatalog as ut, MemoryStore as v, xmlRenderer as vn, SkillManifest as vt, UiSpecDrafts as w, SkillsLockfile as wt, SkillCandidateMarker as x, SkillReader as xt, RenderBlock as y, SkillMetadata as yt, DOCX_MIME as z, buildCatalog as zt };