page-agent-sdk 4.1.0 → 4.2.0

package/dist/page-agent-sdk.headless.js

@@ -453,10 +453,10 @@ function O(e) {
 }
 var k = process.env.NODE_ENV === "production" ? {} : Object.freeze({});
 process.env.NODE_ENV === "production" || Object.freeze([]);
-var te = () => {}, ne = (e) => e.charCodeAt(0) === 111 && e.charCodeAt(1) === 110 && (e.charCodeAt(2) > 122 || e.charCodeAt(2) < 97), A = (e) => e.startsWith("onUpdate:"), j = Object.assign, M = (e, t) => {
+var te = () => {}, ne = (e) => e.charCodeAt(0) === 111 && e.charCodeAt(1) === 110 && (e.charCodeAt(2) > 122 || e.charCodeAt(2) < 97), A = (e) => e.startsWith("onUpdate:"), j = Object.assign, re = (e, t) => {
 	let n = e.indexOf(t);
 	n > -1 && e.splice(n, 1);
-}, re = Object.prototype.hasOwnProperty, N = (e, t) => re.call(e, t), P = Array.isArray, ie = (e) => le(e) === "[object Map]", F = (e) => le(e) === "[object Set]", I = (e) => typeof e == "function", ae = (e) => typeof e == "string", oe = (e) => typeof e == "symbol", L = (e) => typeof e == "object" && !!e, se = (e) => (L(e) || I(e)) && I(e.then) && I(e.catch), ce = Object.prototype.toString, le = (e) => ce.call(e), ue = (e) => le(e).slice(8, -1), R = (e) => le(e) === "[object Object]", de = (e) => ae(e) && e !== "NaN" && e[0] !== "-" && "" + parseInt(e, 10) === e, z = ((e) => {
+}, M = Object.prototype.hasOwnProperty, N = (e, t) => M.call(e, t), P = Array.isArray, ie = (e) => le(e) === "[object Map]", F = (e) => le(e) === "[object Set]", I = (e) => typeof e == "function", ae = (e) => typeof e == "string", oe = (e) => typeof e == "symbol", L = (e) => typeof e == "object" && !!e, se = (e) => (L(e) || I(e)) && I(e.then) && I(e.catch), ce = Object.prototype.toString, le = (e) => ce.call(e), ue = (e) => le(e).slice(8, -1), R = (e) => le(e) === "[object Object]", de = (e) => ae(e) && e !== "NaN" && e[0] !== "-" && "" + parseInt(e, 10) === e, z = ((e) => {
 	let t = /* @__PURE__ */ Object.create(null);
 	return ((n) => t[n] || (t[n] = e(n)));
 })((e) => e.charAt(0).toUpperCase() + e.slice(1)), B = (e, t) => !Object.is(e, t), fe = (e, t, n, r = !1) => {
@@ -1215,7 +1215,7 @@ function Zt(e, t, n = k) {
 		f = () => Qt(e(), t);
 	}
 	let _ = be(), v = () => {
-		d.stop(), _ && _.active && M(_.effects, d);
+		d.stop(), _ && _.active && re(_.effects, d);
 	};
 	if (a && t) {
 		let e = t;
@@ -3575,7 +3575,7 @@ function No(e) {
 	return Array.isArray(r) && r.length && r[0] && typeof r[0].jsonPath == "string" ? r[0].jsonPath : "";
 }
 function Po(e) {
-	let { apiKey: t, baseUrl: r, model: c = "gpt-3.5-turbo", temperature: l = .7, maxTokens: u, extraBody: d, extraConfig: f, systemPrompt: p, tools: v = [], middleware: y = [], maxToolRounds: S, maxIterations: C, maxRetries: E = 2, retryDelayMs: D = 500, stallMs: O = Bi, streamMaxMs: k = Hi, toolTimeoutMs: te, maxParallelTools: ne = 1, maxVerifyAttempts: A = 0, roundTokenBudget: j = 0, onLog: M, onLlmChange: re, imageContentFormat: N = "openai", staleReadInvalidation: P = !0, debug: ie = !1 } = e, F = S ?? Eo;
+	let { apiKey: t, baseUrl: r, model: c = "gpt-3.5-turbo", temperature: l = .7, maxTokens: u, extraBody: d, extraConfig: f, systemPrompt: p, tools: v = [], middleware: y = [], maxToolRounds: S, maxIterations: C, maxRetries: E = 2, retryDelayMs: D = 500, stallMs: O = Bi, streamMaxMs: k = Hi, toolTimeoutMs: te, maxParallelTools: ne = 1, maxVerifyAttempts: A = 0, roundTokenBudget: j = 0, onLog: re, onLlmChange: M, imageContentFormat: N = "openai", staleReadInvalidation: P = !0, debug: ie = !1 } = e, F = S ?? Eo;
 	(!Number.isFinite(F) || F < 1) && (console.warn(`[page-agent-sdk] maxToolRounds=${F} 非法(须 ≥1 正整数),已 clamp 到 1(0/负数致主循环 while 不进 → agent 不调 LLM 静默返回兜底文案)`), F = 1);
 	let I = m({
 		model: c,
@@ -3593,7 +3593,7 @@ function Po(e) {
 			type: e,
 			data: t
 		};
-		ce.value.push(n), ce.value.length > Do && ce.value.splice(0, ce.value.length - Do), Vt(ce), M?.(n), ie && console.log(`%c[Agent] ${e}`, "color:#667eea;font-weight:bold", t);
+		ce.value.push(n), ce.value.length > Do && ce.value.splice(0, ce.value.length - Do), Vt(ce), re?.(n), ie && console.log(`%c[Agent] ${e}`, "color:#667eea;font-weight:bold", t);
 	}
 	let de = (e) => {
 		ce.value.push(e), ce.value.length > Do && ce.value.splice(0, ce.value.length - Do), Vt(ce);
@@ -3839,7 +3839,7 @@ function Po(e) {
 		return ko(e, t);
 	}
 	function xe(e) {
-		return !ie && !M ? [] : e.map((e) => {
+		return !ie && !re ? [] : e.map((e) => {
 			let t = be(e), n = { role: t === "human" ? "user" : t === "ai" ? "assistant" : t }, r = typeof e.content == "string" ? e.content : JSON.stringify(e.content);
 			r && (n.content = r.length > Oo ? r.slice(0, Oo) + `…(截断 ${r.length - Oo} 字符)` : r);
 			let i = e.tool_calls;
@@ -4297,7 +4297,7 @@ function Po(e) {
 		z = [...y.flatMap((e) => e.tools || []), ...e], me();
 	}
 	function Te(e) {
-		B = e, me(), re?.(e);
+		B = e, me(), M?.(e);
 	}
 	return {
 		invoke: Ce,
@@ -5072,7 +5072,7 @@ function Ws(e, t, n, r) {
 	}
 	if (t === "move") return Ks(e, n, r);
 	let i = n ? Q(e, n) : e;
-	return Array.isArray(i) ? (Array.isArray(r) ? i.push(...r) : i.push(r), null) : `append 目标${n ? `(${n})` : "(根)"}不是数组`;
+	return typeof i == "string" ? typeof r == "string" ? (Ps(e, n, i + r), null) : `append 目标(${n})是字符串,value 必须也是字符串(拼接语义)` : Array.isArray(i) ? (Array.isArray(r) ? i.push(...r) : i.push(r), null) : `append 目标${n ? `(${n})` : "(根)"}不是数组(也不支持非字符串标量拼接)`;
 }
 function Gs(e, t) {
 	let n = t.split("."), r = e;
@@ -7644,47 +7644,63 @@ function Pu(e, t, n, r) {
 		hint: "重新 read 该字段触发懒注册重建句柄,再写回新句柄 ⟦res:<handle>⟧"
 	};
 }
-function Fu(e, t) {
-	let n = t.getBind();
-	for (let [r, i] of t.resourcesByPath) {
-		let a = Q(n, r), o = Q(e, r);
-		if (o === void 0) {
-			a !== void 0 && Ps(e, r, a);
-			continue;
+function Fu(e, t, n) {
+	let r = t.getBind();
+	for (let [i, a] of t.resourcesByPath) {
+		let o = Q(r, i), s = Q(e, i);
+		if (s === void 0) {
+			if (o === void 0) continue;
+			let t = i.split(".");
+			if (Q(e, t.length > 1 ? t.slice(0, -1).join(".") : "") !== void 0) {
+				Ps(e, i, o);
+				continue;
+			}
+			if (!(e && typeof e == "object" && t[0] in e)) {
+				if (n) continue;
+				Ps(e, i, o);
+				continue;
+			}
+			return {
+				ok: !1,
+				code: a.mode === "freeze" ? "FROZEN_FIELD" : "VERBATIM_PROTECTED",
+				path: i,
+				message: `整体替换会移除受保护字段 "${i}"(${a.mode}),已拒绝`,
+				hint: a.mode === "freeze" ? "含冻结字段的容器不可整体清空/替换:保留包含该字段的元素(补齐其必填字段,如 type),或逐个 remove 其余元素;彻底移除该字段需集成方调整 data.resources" : "含 verbatim 字段的容器不可整体清空/替换:保留包含该字段的元素,或先 resource_delete({path}) 释放保护后再整体替换"
+			};
 		}
-		if (i.mode === "freeze") {
-			if (o === Tu(r)) {
-				Ps(e, r, a);
+		if (a.mode === "freeze") {
+			if (s === Tu(i)) {
+				Ps(e, i, o);
 				continue;
 			}
-			if (!Au(o, a)) return {
+			if (!Au(s, o)) return {
 				ok: !1,
 				code: "FROZEN_FIELD",
-				path: r,
-				message: `字段 "${r}" 已冻结(freeze 保护),不可修改`,
+				path: i,
+				message: `字段 "${i}" 已冻结(freeze 保护),不可修改`,
 				hint: "该字段由系统/集成方维护,LLM 不得改动。如需展示其值用 resource_get({path}) 取真值"
 			};
 		} else {
-			let n = Du(o);
+			let n = Du(s);
 			if (n && n.type === "res") {
-				let i = Pu(n.handle, r, a, t.resourceStore);
-				if ("value" in i) {
-					Ps(e, r, i.value);
+				let r = Pu(n.handle, i, o, t.resourceStore);
+				if ("value" in r) {
+					Ps(e, i, r.value);
 					continue;
 				}
 				return {
 					ok: !1,
-					code: i.code,
-					path: r,
-					message: i.message,
-					hint: i.hint
+					code: r.code,
+					path: i,
+					message: r.message,
+					hint: r.hint
 				};
 			}
-			if (!Au(o, a)) return {
+			if (!Au(s, o)) return {
 				ok: !1,
 				code: "VERBATIM_MISMATCH",
-				path: r,
-				message: `字段 "${r}" 为 verbatim 保护(精确原样保留),写入值与原值不符`,
+				path: i,
+				message: `字段 "${i}" 为 verbatim 保护(精确原样保留),写入值与原值不符`,
 				hint: "要改该值请先 resource_update({path, value}) 更新资源池,再写回句柄 ⟦res:<handle>⟧;或写回原值(经 resource_get 取到的值)保持不变"
 			};
 		}
@@ -7705,18 +7721,18 @@ function Iu(e, t, n) {
 	});
 }
 function Lu(e) {
-	let { value: t, ctx: n } = e;
+	let { value: t, ctx: n, mergeMode: r } = e;
 	if (!n || !n.resourcesByPath.size) return {
 		ok: !0,
 		value: t
 	};
-	let r = Is(t), i = Fu(r, n);
-	return i.ok ? {
+	let i = Is(t), a = Fu(i, n, r);
+	return a.ok ? {
 		ok: !0,
-		value: r
+		value: i
 	} : {
 		ok: !1,
-		error: Iu(i)
+		error: Iu(a)
 	};
 }
 function Ru(e) {
@@ -7935,7 +7951,32 @@ function Wu(e) {
 			continue;
 		}
 		if (i === "append") {
-			let e = o[p++]?.elems ?? [];
+			let e = o[p++]?.elems ?? [], r = Q(n, a);
+			if (typeof r == "string" && typeof e[0] == "string") {
+				let n = e[0], i = Vo(t, a);
+				if (i.kind === "missing") return {
+					ok: !1,
+					error: d([a]),
+					writeBacks: [],
+					notices: c
+				};
+				let o = r + n;
+				if (i.kind !== "open") {
+					let e = i.schemas.map((e) => e.safeParse(o)).find((e) => !e.success);
+					if (e) return {
+						ok: !1,
+						error: u(a, e.error?.issues ?? []),
+						writeBacks: [],
+						notices: c
+					};
+				}
+				f.push({
+					op: "appendStr",
+					jp: a,
+					str: n
+				});
+				continue;
+			}
 			if (!e.length) {
 				f.push({
 					op: "appendElems",
@@ -7944,14 +7985,14 @@ function Wu(e) {
 				});
 				continue;
 			}
-			let n = Vo(t, a);
-			if (n.kind === "missing") return {
+			let i = Vo(t, a);
+			if (i.kind === "missing") return {
 				ok: !1,
 				error: d([a || "(根)"]),
 				writeBacks: [],
 				notices: c
 			};
-			if (n.kind === "open") {
+			if (i.kind === "open") {
 				c.push(`${a || "(根)"}=开放节点放行`), f.push({
 					op: "appendElems",
 					jp: a,
@@ -7959,8 +8000,8 @@ function Wu(e) {
 				});
 				continue;
 			}
-			let r = Go(n.schemas);
-			if (!r.length) {
+			let s = Go(i.schemas);
+			if (!s.length) {
 				c.push(`${a || "(根)"}:目标非 schema 声明数组,元素未校验放行`), f.push({
 					op: "appendElems",
 					jp: a,
@@ -7968,36 +8009,36 @@ function Wu(e) {
 				});
 				continue;
 			}
-			let i = [];
+			let l = [];
 			for (let t = 0; t < e.length; t++) {
-				let n = [], o, s = !1;
-				for (let i of r) {
-					let r = i.safeParse(e[t]);
-					if (r.success) {
-						s = !0, o = r.data;
+				let n = [], r, i = !1;
+				for (let a of s) {
+					let o = a.safeParse(e[t]);
+					if (o.success) {
+						i = !0, r = o.data;
 						break;
 					}
-					n.push(...r.error?.issues ?? []);
+					n.push(...o.error?.issues ?? []);
 				}
-				if (!s) return {
+				if (!i) return {
 					ok: !1,
 					error: u(`${a || "(根)"}[新增元素${t}]`, n),
 					writeBacks: [],
 					notices: c
 				};
-				let l = Xs(void 0, e[t], o, a ? `${a}.${t}` : String(t));
-				if (l.length) return {
+				let o = Xs(void 0, e[t], r, a ? `${a}.${t}` : String(t));
+				if (o.length) return {
 					ok: !1,
-					error: d(l),
+					error: d(o),
 					writeBacks: [],
 					notices: c
 				};
-				i.push(o);
+				l.push(r);
 			}
 			f.push({
 				op: "appendElems",
 				jp: a,
-				elems: i
+				elems: l
 			});
 			continue;
 		}
@@ -8130,7 +8171,8 @@ function Gu(e) {
 	if (l) {
 		let e = Lu({
 			value: d,
-			ctx: l
+			ctx: l,
+			mergeMode: !!r
 		});
 		if (!e.ok) return {
 			ok: !1,
@@ -8252,7 +8294,7 @@ function Ku(e) {
 			error: Z({
 				code: "PATCH_FAILED",
 				message: `patches[${e}]: ${c}`,
-				hint: "检查 op 与目标类型:merge 需对象,append 需数组"
+				hint: "检查 op 与目标类型:merge 需对象,append 需数组或字符串"
 			})
 		};
 		v(o, a), m.push({
@@ -8309,6 +8351,9 @@ function Ku(e) {
 	} else if (e.op === "appendElems") {
 		let n = e.jp ? Q(t, e.jp) : t;
 		Array.isArray(n) && e.elems?.length && n.push(...e.elems);
+	} else if (e.op === "appendStr") {
+		let n = e.jp ? Q(t, e.jp) : t;
+		typeof n == "string" && typeof e.str == "string" && Ps(t, e.jp, n + e.str);
 	}
 	return e.internalAfterWrite?.(t, f), s?.(), {
 		ok: !0,
@@ -8494,9 +8539,9 @@ function rd(e, n = {}) {
 			arrayPath: e.slice(0, t),
 			field: e.slice(t + 1)
 		} : null;
-	}).filter((e) => e !== null), M = !0;
-	function re() {
-		M = !0;
+	}).filter((e) => e !== null), re = !0;
+	function M() {
+		re = !0;
 	}
 	let N = {
 		get: () => ({
@@ -8505,15 +8550,15 @@ function rd(e, n = {}) {
 			description: c
 		}),
 		set: (e) => {
-			o = i.length ? ls(e.schema, i).schema : e.schema, s = e.bind, c = e.description ?? "主数据对象", l = Fo(o), m.length = 0, g.clear(), f(e.resources), d?.clear(), re();
+			o = i.length ? ls(e.schema, i).schema : e.schema, s = e.bind, c = e.description ?? "主数据对象", l = Fo(o), m.length = 0, g.clear(), f(e.resources), d?.clear(), M();
 		},
 		update: (e) => {
-			s = e, m.length = 0, g.clear(), re();
+			s = e, m.length = 0, g.clear(), M();
 		},
-		markDataDirty: re,
+		markDataDirty: M,
 		consumeDataDirty: () => {
-			let e = M;
-			return M = !1, e;
+			let e = re;
+			return re = !1, e;
 		},
 		enterScope: (e) => {
 			let t = _;
@@ -8567,7 +8612,7 @@ function rd(e, n = {}) {
 		} : void 0,
 		updateResource: d ? (e, t) => {
 			let n = Ou(e);
-			d.update(n, t), Ps(s, n, t), re(), C(D(), "");
+			d.update(n, t), Ps(s, n, t), M(), C(D(), "");
 		} : void 0,
 		deleteResource: d ? (e) => d.delete(e) : void 0,
 		listResources: d ? () => d.list() : void 0
@@ -8607,7 +8652,7 @@ function rd(e, n = {}) {
 		if (o.action === "restore") {
 			if (await i?.reacquire(), !m.length) return `无历史快照可回退(本次为首次操作)。当前值:${$(s, 400)} (hash=${a})。请重新 read 再改或选「强制覆盖」。`;
 			let e = m[m.length - 1];
-			return Js(s, Is(e.value)), re(), C(D()), `已回退主数据到历史快照 #${e.id}[${e.op}]。当前值:${$(s, 400)} (hash=${D()})。请基于回退后的值重写或停止。`;
+			return Js(s, Is(e.value)), M(), C(D()), `已回退主数据到历史快照 #${e.id}[${e.op}]。当前值:${$(s, 400)} (hash=${D()})。请基于回退后的值重写或停止。`;
 		}
 		await i?.reacquire();
 		let c = D();
@@ -8641,7 +8686,7 @@ function rd(e, n = {}) {
 			hint: "用 history_data({list:true}) 查看可用快照序号"
 		});
 		let i = o.safeParse(r.value);
-		return i.success ? (Js(s, Is(r.value)), re(), P({
+		return i.success ? (Js(s, Is(r.value)), M(), P({
 			op: "restore",
 			detail: `#${r.id}`,
 			timestamp: Date.now()
@@ -8820,7 +8865,7 @@ function rd(e, n = {}) {
 						allowKeys: l,
 						snapshots: m,
 						maxSnapshots: h,
-						markDataDirty: re,
+						markDataDirty: M,
 						schemaErrorMode: "schema_invalid",
 						snapshotLabel: "eval_transform_subtree",
 						internalAfterWrite: a,
@@ -8850,7 +8895,7 @@ function rd(e, n = {}) {
 						allowKeys: l,
 						snapshots: m,
 						maxSnapshots: h,
-						markDataDirty: re,
+						markDataDirty: M,
 						schemaErrorMode: "schema_invalid",
 						snapshotLabel: "eval_transform",
 						internalAfterWrite: a,
@@ -8888,7 +8933,7 @@ function rd(e, n = {}) {
 					value: t,
 					bindRef: s
 				});
-				return e.ok ? (ie("edit", "eval_transform"), e.wholeParsed ? Ys(s, e.assembly) : e.assembly !== null && typeof e.assembly == "object" && Ns(s, e.assembly), re(), P({
+				return e.ok ? (ie("edit", "eval_transform"), e.wholeParsed ? Ys(s, e.assembly) : e.assembly !== null && typeof e.assembly == "object" && Ns(s, e.assembly), M(), P({
 					op: "edit",
 					detail: "eval_transform",
 					timestamp: Date.now()
@@ -9053,11 +9098,11 @@ function rd(e, n = {}) {
 				}
 				ie("delete");
 				let r = Fs(s, t.jsonPath);
-				return re(), P({
+				return M(), P({
 					op: "delete",
 					detail: t.jsonPath,
 					timestamp: Date.now()
-				}), a && (a(s, null), re()), C(D(), d), r ? `已删除主数据 @ ${t.jsonPath}` : `主数据 @ ${t.jsonPath} 不存在(无需删除)`;
+				}), a && (a(s, null), M()), C(D(), d), r ? `已删除主数据 @ ${t.jsonPath}` : `主数据 @ ${t.jsonPath} 不存在(无需删除)`;
 			}
 			if (f === "edit") {
 				if (typeof s != "object" || !s) return Z({
@@ -9078,7 +9123,7 @@ function rd(e, n = {}) {
 					allowKeys: l,
 					snapshots: m,
 					maxSnapshots: h,
-					markDataDirty: re,
+					markDataDirty: M,
 					schemaErrorMode: "zod",
 					dryRun: c,
 					internalAfterWrite: a,
@@ -9108,7 +9153,7 @@ function rd(e, n = {}) {
 				maxSnapshots: h,
 				audit: P,
 				dryRun: c,
-				onWrite: re,
+				onWrite: M,
 				internalAfterWrite: a,
 				protectedCtx: p,
 				hashFn: D
@@ -9251,7 +9296,7 @@ function rd(e, n = {}) {
 					maxSnapshots: h,
 					audit: P,
 					op: "draft_commit",
-					onWrite: re,
+					onWrite: M,
 					internalAfterWrite: a,
 					protectedCtx: p,
 					hashFn: D
@@ -9337,7 +9382,7 @@ function rd(e, n = {}) {
 					details: ei(n.error.issues)
 				});
 			}
-			d.update(i, t), Ps(s, i, t), C(D(), r), re();
+			d.update(i, t), Ps(s, i, t), C(D(), r), M();
 			let l = d.get(i)?.handle;
 			return `已更新 verbatim 资源 "${e}" = ${$(t, 200)}(handle ${l ?? "(未知)"} 不变)。后续 write 该字段写回句柄 ⟦res:${l}⟧ 或新值`;
 		}, {
@@ -9351,14 +9396,22 @@ function rd(e, n = {}) {
 		I(n);
 		let i = r(async () => {
 			let e = d.list();
-			return e.length ? $({ resources: e }) : "当前无已注册的受保护资源(read 受保护路径会懒注册)";
+			if (!e.length) {
+				let e = [...p.resourcesByPath.entries()].filter(([, e]) => e.mode === "freeze").map(([e]) => e);
+				return e.length ? `资源池为空,但集成方静态配置了 freeze 只读字段:${e.join("、 ")}(freeze 无句柄、不可释放;resource_delete 仅对 verbatim 生效)` : "当前无已注册的受保护资源(read 受保护路径会懒注册)";
+			}
+			return $({ resources: e });
 		}, {
 			name: "resource_list",
 			description: "列出所有已注册的受保护资源(path/mode/handle/bytes)。",
 			schema: t.object({})
 		}), a = r(async ({ path: e, handle: t }) => {
 			let n = e;
-			return !n && t && (n = d.get(t)?.path), n ? d.delete(n) ? `已释放资源 "${n}"(后续 read 该字段会重新懒注册)` : `资源 "${n}" 不存在(无需释放)` : Z({
+			return !n && t && (n = d.get(t)?.path), n ? d.delete(n) ? `已释放资源 "${n}"(后续 read 该字段会重新懒注册)` : p.resourcesByPath.get(n)?.mode === "freeze" ? Z({
+				code: "FROZEN_FIELD",
+				message: `字段 "${n}" 为 freeze 静态保护(不在资源池、无句柄、不可释放)`,
+				hint: "freeze 由集成方在 data.resources 静态配置,只读不可解;含冻结字段的元素无法整体删除,请保留该元素或由集成方调整 data.resources"
+			}) : `资源 "${n}" 不存在(无需释放)` : Z({
 				code: "RESOURCE_NOT_FOUND",
 				message: "未提供 path 或有效 handle",
 				hint: "传要释放的受保护字段 path 或 handle"
@@ -10396,6 +10449,7 @@ ${`- 输出形态:完整、自包含的 HTML 页面(.${r},可独立成页)`}
    - **机械决定一次定**:写法选择(read 回读 vs 复制、vfs 草稿 vs 直写 data、并行 vs 串行)快速选一个,**不在思考里反复权衡 token 成本**(为之纠结反更费 token)。
    - **禁止在思考里整段写出完整代码草稿**:CSS/JS/HTML 代码只写进 write / vfs_write / vfs_edit 工具调用(代码只出现一次);思考里只做高层设计(结构 / 字段 / 方案选择),不要先逐行预写一遍代码再在工具里重复一遍 —— 那会让代码 token 翻倍。
    - **终稿纪律(一次写成)**:动手前要点清单一次定稿(≤10 条:结构 + DOM 分层/z-index + 关键尺寸 + 动画时序),清单齐了**直接在工具调用里写终稿**;① 不先写一版再推翻重写第二版(整段重写 = 代码 token 翻倍,写前多花 30 秒把清单想齐);② 同一几何/层级约束(bottom 定位/遮挡/z-index)**只推演一次**,不重复推导第二遍;③ 写完发现小问题(遮挡/重叠/命名),只改那一处,不重写整段。
+   - **大段 code 分块写(超长代码硬约束)**:预计 code 超过 ~8K 字符时,**一次工具调用装不下会被 max_tokens 掐断** —— 必须分块:① 首块用 write 把组件连同 code 第一段写入(如 code 写到 CSS 中段即止);② 后续每段用 write({op:'append', jsonPath:'${n}.N.${t}', value:'下一段文本'}) 逐块尾接(每块 ≤4K 字符);③ 全部拼完再 validate_code。**禁止**在任何一次调用里塞完整超长代码(截断 = 静默失败重来,token 全废)。
    - **代码字符串不纠结转义**:代码字段(${t})/ content 参数就是普通字符串,直接写完整代码文本(换行、引号照常写),不要纠结「\n」转义、单双引号、字面换行会不会被拒 —— 框架自动序列化,反复权衡纯属浪费 token。
    - 一次想清楚 → 动手 → 验证 → 收口。**思考是手段不是目的,产出代码才是**。
 8. **收口格式(必守,最后一行)**:收口回复 = 简短结果总结 + **末行交接笔记** \`[note] <一句话实现要点>\` —— 关键设计决策 / 用户偏好 / 踩坑(如「[note] 液面用 height keyframes 4.2s 循环;装饰仅灯串+光斑 2 类」)。框架只识别末尾 [note] 行存进组件、自动转交下次维护该组件的子 agent;**漏写 = 下任失去交接**(真 LLM 实测漏写率 3/4,务必末行带上)。一行内,只写可复用结论。`;
@@ -12186,9 +12240,9 @@ function am(e, n) {
 			type: "focus_change",
 			focuses: e
 		})
-	}), j = fl(), M = pl(e.memory || "");
-	typeof e.memory == "function" && M.refresh();
-	let re = { current: null }, N = e.data ? {
+	}), j = fl(), re = pl(e.memory || "");
+	typeof e.memory == "function" && re.refresh();
+	let M = { current: null }, N = e.data ? {
 		...e.data,
 		description: e.data.description ?? "主数据对象"
 	} : void 0, P = !(e.subagents ?? []).some((e) => e._codeAsset) && Qf(e.capabilities).subagent, ie = e.subagents;
@@ -12205,7 +12259,7 @@ function am(e, n) {
 		slotPaths: N ? [""] : [],
 		vfsStore: x,
 		todosMw: w,
-		getTodos: () => re.current?.getState?.()?.todos ?? [],
+		getTodos: () => M.current?.getState?.()?.todos ?? [],
 		messages: b,
 		maxCheckpoints: le && typeof le == "object" ? le.maxCheckpoints : void 0
 	}) : null, de = !le || typeof le != "object" || le.auto !== !1, z = Qf(e.capabilities), B = z.dataOps, fe = z.draftWrite, pe = z.automation, me = cu({
@@ -12554,7 +12608,7 @@ function am(e, n) {
 		...ze ? [j] : [],
 		...ke ? [A] : [],
 		...ge ? [ge] : [],
-		...We ? [M] : [],
+		...We ? [re] : [],
 		...$e ? [$e] : [],
 		...ue && de && R ? [Ml(R)] : [],
 		...Ee ? [ne] : [],
@@ -12609,7 +12663,7 @@ function am(e, n) {
 		vfsStore: x,
 		listeners: _t.listeners,
 		todosMw: w,
-		memoryMw: M,
+		memoryMw: re,
 		missionMw: T,
 		workingMemoryMw: j,
 		focusMw: A,
@@ -12645,7 +12699,7 @@ function am(e, n) {
 			K = Ie(), X.agent && X.agent.setTools(K);
 		},
 		applySnapshot(t) {
-			if (t.vfs && x.hydrate && x.hydrate(t.vfs), t.messages?.length && (b.push(..._i(t.messages, (e) => (e ? X.vfsStore?.files?.[e]?.content : void 0) || void 0)), D.markResumed()), t.todos?.length && w.reset(t.todos), t.memory && !e.memory && M.reset(t.memory), t.checkpoints?.length && R && R.importStack(t.checkpoints), t.usage && Object.assign(i, t.usage), t.mission && Re && T.setMission(t.mission), t.workingMemory && ze && j.restore(t.workingMemory), t.planConfirmation && (ee = t.planConfirmation), ke) {
+			if (t.vfs && x.hydrate && x.hydrate(t.vfs), t.messages?.length && (b.push(..._i(t.messages, (e) => (e ? X.vfsStore?.files?.[e]?.content : void 0) || void 0)), D.markResumed()), t.todos?.length && w.reset(t.todos), t.memory && !e.memory && re.reset(t.memory), t.checkpoints?.length && R && R.importStack(t.checkpoints), t.usage && Object.assign(i, t.usage), t.mission && Re && T.setMission(t.mission), t.workingMemory && ze && j.restore(t.workingMemory), t.planConfirmation && (ee = t.planConfirmation), ke) {
 				let n = t.focus, r = n ? Array.isArray(n) ? n : [n] : [];
 				if (r.length) {
 					let t = U()?.schema, n = t ? r.filter((e) => Ro(t, e.path)) : [];
@@ -12881,7 +12935,7 @@ function am(e, n) {
 			}
 			x.flush?.(), await s.flush();
 			let r = t ?? "", i;
-			if (r ? (i = await s.load(n, r), i || await s.createSession(n, e.session?.title, r)) : r = await s.createSession(n, e.session?.title), X.sessionId = r, b.splice(0, b.length), x.clear?.(), w.reset([]), e.memory || M.reset(""), T.reset(), j.reset(), A.reset(), D.reset(), ee = void 0, R && R.importStack([]), X.agent.debugLogs.value = [], X.agent.resetStaleReadsInvalidated?.(), !i) try {
+			if (r ? (i = await s.load(n, r), i || await s.createSession(n, e.session?.title, r)) : r = await s.createSession(n, e.session?.title), X.sessionId = r, b.splice(0, b.length), x.clear?.(), w.reset([]), e.memory || re.reset(""), T.reset(), j.reset(), A.reset(), D.reset(), ee = void 0, R && R.importStack([]), X.agent.debugLogs.value = [], X.agent.resetStaleReadsInvalidated?.(), !i) try {
 				i = await s.load(n, r);
 			} catch (e) {
 				J({
@@ -12896,10 +12950,10 @@ function am(e, n) {
 				type: "session_restored",
 				sessionId: r,
 				rounds: i.messages?.length ?? 0
-			})), e.memory && Gt({ memory: M.get() || (typeof e.memory == "string" ? e.memory : "") }), jt(), Ht = void 0, Ut = !1, X.infoTick.value++, r;
+			})), e.memory && Gt({ memory: re.get() || (typeof e.memory == "string" ? e.memory : "") }), jt(), Ht = void 0, Ut = !1, X.infoTick.value++, r;
 		},
 		resetSession: () => {
-			Pt(), a.resolve("keep_external"), X.sessionId = Sf(), b.splice(0, b.length), x.clear?.(), w.reset([]), e.memory || M.reset(""), T.reset(), j.reset(), A.reset(), D.reset(), ee = void 0, R && R.importStack([]), X.agent && (X.agent.debugLogs.value = [], X.agent.resetStaleReadsInvalidated?.()), s && s.createSession(X.agentId, e.session?.title, X.sessionId).catch((t) => {
+			Pt(), a.resolve("keep_external"), X.sessionId = Sf(), b.splice(0, b.length), x.clear?.(), w.reset([]), e.memory || re.reset(""), T.reset(), j.reset(), A.reset(), D.reset(), ee = void 0, R && R.importStack([]), X.agent && (X.agent.debugLogs.value = [], X.agent.resetStaleReadsInvalidated?.()), s && s.createSession(X.agentId, e.session?.title, X.sessionId).catch((t) => {
 				e.debug && console.warn("[page-agent-sdk][persist] createSession 失败(已吞):", t);
 			}), J({
 				type: "session_restored",
@@ -12971,10 +13025,10 @@ function am(e, n) {
 			X.agent && (X.agent.setLlm(n), X.agent.setModelCaps?.(f)), Tt?.setContextWindow?.(f.contextWindow), pt?.setContextWindow?.(f.contextWindow), X.infoTick.value++, e.debug && console.log("[page-agent-sdk][setLlm] 重解析 modelCaps + 回灌:", f);
 		},
 		setMemory(e) {
-			M.reset(e), typeof e == "function" && M.refresh(), X.infoTick.value++;
+			re.reset(e), typeof e == "function" && re.refresh(), X.infoTick.value++;
 		},
 		refreshMemory() {
-			return M.refresh();
+			return re.refresh();
 		},
 		setSubagents(t) {
 			if (!ct) {
@@ -13027,7 +13081,7 @@ function am(e, n) {
 					summaryThresholdRatio: h.summaryThresholdRatio ?? .5,
 					promptSoftCap: Fc(f.contextWindow, h.promptSoftCapTokens)
 				},
-				memory: M.get(),
+				memory: re.get(),
 				staleReadsInvalidated: X.agent?.getStaleReadsInvalidated?.() ?? 0,
 				middleware: Dt.map((e) => e.name),
 				todos: (X.agent?.getState?.()?.todos ?? []).map((e) => ({
@@ -13179,7 +13233,7 @@ function am(e, n) {
 				}), e.debug && console.log("[page-agent-sdk][restore] 恢复会话", X.sessionId, `${r.messages?.length ?? 0} msgs`)) : e.debug && console.log("[page-agent-sdk][restore] 会话 meta 存在但快照为空", X.sessionId);
 			} else X.sessionId = await s.createSession(n, r.title), e.debug && console.log("[page-agent-sdk][restore] 新建会话(无历史)", X.sessionId);
 		} else X.sessionId = await s.createSession(n, r.title);
-		e.memory && Gt({ memory: M.get() || (typeof e.memory == "string" ? e.memory : "") }), jt();
+		e.memory && Gt({ memory: re.get() || (typeof e.memory == "string" ? e.memory : "") }), jt();
 	}
 	async function It() {
 		await wt();
@@ -13399,7 +13453,7 @@ function am(e, n) {
 				y = e;
 			},
 			debug: e.debug
-		}), re.current = X.agent, st && st.setReconfigureHook && st.setReconfigureHook(() => {
+		}), M.current = X.agent, st && st.setReconfigureHook && st.setReconfigureHook(() => {
 			X.agent && X.agent.setTools(Ie());
 		});
 	})(), X;
@@ -14484,7 +14538,7 @@ function Sm(e = {}) {
 		minute: "2-digit"
 	}), w = () => {
 		let e = T.value;
-		!o.value.trim() && !e.length || (r(o.value, M.value, e.length ? [...e] : void 0), o.value = "", T.value = []);
+		!o.value.trim() && !e.length || (r(o.value, re.value, e.length ? [...e] : void 0), o.value = "", T.value = []);
 	}, T = /* @__PURE__ */ Lt([]), E = /* @__PURE__ */ Lt(""), D = /* @__PURE__ */ Lt(!1), ee, O = (e) => {
 		E.value = e, clearTimeout(ee), ee = setTimeout(() => {
 			E.value = "";
@@ -14519,7 +14573,7 @@ function Sm(e = {}) {
 		if (!r || r.role !== "assistant") return !1;
 		let i = "reasoning" in r ? r.reasoning : void 0, a = "steps" in r ? r.steps : void 0;
 		return n.loading && e === t.length - 1 && !r.content && !i && !(a && a.length);
-	}, M = Zr(() => (e.infoTick?.value, e.getFocuses?.() ?? [])), re = Zr(() => (e.infoTick?.value, e.getInfo?.()?.planConfirmation)), N = (t) => e.onAddFocus ? e.onAddFocus(t) : {
+	}, re = Zr(() => (e.infoTick?.value, e.getFocuses?.() ?? [])), M = Zr(() => (e.infoTick?.value, e.getInfo?.()?.planConfirmation)), N = (t) => e.onAddFocus ? e.onAddFocus(t) : {
 		ok: !1,
 		error: "focus 未启用"
 	}, P = (t) => {
@@ -14558,8 +14612,8 @@ function Sm(e = {}) {
 		compressingImages: D,
 		editQueued: A,
 		isPendingAssistant: j,
-		focuses: M,
-		planConfirmation: re,
+		focuses: re,
+		planConfirmation: M,
 		addFocus: N,
 		removeFocus: P,
 		clearFocus: ie,