page-agent-sdk 4.1.0 → 4.2.0

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

@@ -57341,7 +57341,7 @@ function v$(e, t, n, r) {
 	}
 	if (t === "move") return b$(e, n, r);
 	let i = n ? s$(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" ? (c$(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 y$(e, t) {
 	let n = t.split("."), r = e;
@@ -67659,47 +67659,63 @@ function Mke(e, t, n, r) {
 		hint: "重新 read 该字段触发懒注册重建句柄,再写回新句柄 ⟦res:<handle>⟧"
 	};
 }
-function Nke(e, t) {
-	let n = t.getBind();
-	for (let [r, i] of t.resourcesByPath) {
-		let a = s$(n, r), o = s$(e, r);
-		if (o === void 0) {
-			a !== void 0 && c$(e, r, a);
-			continue;
+function Nke(e, t, n) {
+	let r = t.getBind();
+	for (let [i, a] of t.resourcesByPath) {
+		let o = s$(r, i), s = s$(e, i);
+		if (s === void 0) {
+			if (o === void 0) continue;
+			let t = i.split(".");
+			if (s$(e, t.length > 1 ? t.slice(0, -1).join(".") : "") !== void 0) {
+				c$(e, i, o);
+				continue;
+			}
+			if (!(e && typeof e == "object" && t[0] in e)) {
+				if (n) continue;
+				c$(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 === V6(r)) {
-				c$(e, r, a);
+		if (a.mode === "freeze") {
+			if (s === V6(i)) {
+				c$(e, i, o);
 				continue;
 			}
-			if (!W6(o, a)) return {
+			if (!W6(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 = Oke(o);
+			let n = Oke(s);
 			if (n && n.type === "res") {
-				let i = Mke(n.handle, r, a, t.resourceStore);
-				if ("value" in i) {
-					c$(e, r, i.value);
+				let r = Mke(n.handle, i, o, t.resourceStore);
+				if ("value" in r) {
+					c$(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 (!W6(o, a)) return {
+			if (!W6(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 取到的值)保持不变"
 			};
 		}
@@ -67719,18 +67735,18 @@ function Pke(e, t, n) {
 	} }));
 }
 function Fke(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 = u$(t), i = Nke(r, n);
-	return i.ok ? {
+	let i = u$(t), a = Nke(i, n, r);
+	return a.ok ? {
 		ok: !0,
-		value: r
+		value: i
 	} : {
 		ok: !1,
-		error: Pke(i)
+		error: Pke(a)
 	};
 }
 function Ike(e) {
@@ -67954,8 +67970,34 @@ function Rke(e) {
 		}
 		if (i === "append") {
 			var v;
-			let e = o[p++], n = (v = e == null ? void 0 : e.elems) == null ? [] : v;
-			if (!n.length) {
+			let e = o[p++], r = (v = e == null ? void 0 : e.elems) == null ? [] : v, i = s$(n, a);
+			if (typeof i == "string" && typeof r[0] == "string") {
+				let e = r[0], n = IQ(t, a);
+				if (n.kind === "missing") return {
+					ok: !1,
+					error: d([a]),
+					writeBacks: [],
+					notices: c
+				};
+				let o = i + e;
+				if (n.kind !== "open") {
+					var y, b;
+					let e = n.schemas.map((e) => e.safeParse(o)).find((e) => !e.success);
+					if (e) return {
+						ok: !1,
+						error: u(a, (y = (b = e.error) == null ? void 0 : b.issues) == null ? [] : y),
+						writeBacks: [],
+						notices: c
+					};
+				}
+				f.push({
+					op: "appendStr",
+					jp: a,
+					str: e
+				});
+				continue;
+			}
+			if (!r.length) {
 				f.push({
 					op: "appendElems",
 					jp: a,
@@ -67963,61 +68005,61 @@ function Rke(e) {
 				});
 				continue;
 			}
-			let r = IQ(t, a);
-			if (r.kind === "missing") return {
+			let s = IQ(t, a);
+			if (s.kind === "missing") return {
 				ok: !1,
 				error: d([a || "(根)"]),
 				writeBacks: [],
 				notices: c
 			};
-			if (r.kind === "open") {
+			if (s.kind === "open") {
 				c.push(`${a || "(根)"}=开放节点放行`), f.push({
 					op: "appendElems",
 					jp: a,
-					elems: n
+					elems: r
 				});
 				continue;
 			}
-			let i = BQ(r.schemas);
-			if (!i.length) {
+			let l = BQ(s.schemas);
+			if (!l.length) {
 				c.push(`${a || "(根)"}:目标非 schema 声明数组,元素未校验放行`), f.push({
 					op: "appendElems",
 					jp: a,
-					elems: n
+					elems: r
 				});
 				continue;
 			}
-			let s = [];
-			for (let e = 0; e < n.length; e++) {
-				let t = [], r, o = !1;
-				for (let a of i) {
-					var y, b;
-					let i = a.safeParse(n[e]);
-					if (i.success) {
-						o = !0, r = i.data;
+			let m = [];
+			for (let e = 0; e < r.length; e++) {
+				let t = [], n, i = !1;
+				for (let a of l) {
+					var x, S;
+					let o = a.safeParse(r[e]);
+					if (o.success) {
+						i = !0, n = o.data;
 						break;
 					}
-					t.push(...(y = (b = i.error) == null ? void 0 : b.issues) == null ? [] : y);
+					t.push(...(x = (S = o.error) == null ? void 0 : S.issues) == null ? [] : x);
 				}
-				if (!o) return {
+				if (!i) return {
 					ok: !1,
 					error: u(`${a || "(根)"}[新增元素${e}]`, t),
 					writeBacks: [],
 					notices: c
 				};
-				let l = C$(void 0, n[e], r, a ? `${a}.${e}` : String(e));
-				if (l.length) return {
+				let o = C$(void 0, r[e], n, a ? `${a}.${e}` : String(e));
+				if (o.length) return {
 					ok: !1,
-					error: d(l),
+					error: d(o),
 					writeBacks: [],
 					notices: c
 				};
-				s.push(r);
+				m.push(n);
 			}
 			f.push({
 				op: "appendElems",
 				jp: a,
-				elems: s
+				elems: m
 			});
 			continue;
 		}
@@ -68048,7 +68090,7 @@ function Rke(e) {
 				if (e.startsWith("__pg") || i$.has(e)) continue;
 				let r = a ? `${a}.${e}` : e, o = l(r), s = LQ(t, r, o);
 				if (!s.ok) {
-					var x;
+					var C;
 					if (s.resolution === "missing") {
 						if (s$(n, r) === void 0) return {
 							ok: !1,
@@ -68061,7 +68103,7 @@ function Rke(e) {
 					}
 					return {
 						ok: !1,
-						error: u(r, (x = s.issues) == null ? [] : x),
+						error: u(r, (C = s.issues) == null ? [] : C),
 						writeBacks: [],
 						notices: c
 					};
@@ -68083,9 +68125,9 @@ function Rke(e) {
 			});
 			continue;
 		}
-		let C = l(a), w = a.lastIndexOf(".");
-		if (w > 0 && /^\d+$/.test(a.slice(w + 1))) {
-			let e = s$(r, a.slice(0, w));
+		let T = l(a), E = a.lastIndexOf(".");
+		if (E > 0 && /^\d+$/.test(a.slice(E + 1))) {
+			let e = s$(r, a.slice(0, E));
 			if (Array.isArray(e)) {
 				for (let t = 0; t < e.length; t++) if (!(t in e)) return {
 					ok: !1,
@@ -68099,10 +68141,10 @@ function Rke(e) {
 				};
 			}
 		}
-		let T = LQ(t, a, C);
-		if (!T.ok) {
-			var S;
-			if (T.resolution === "missing") {
+		let D = LQ(t, a, T);
+		if (!D.ok) {
+			var w;
+			if (D.resolution === "missing") {
 				if (s$(n, a) === void 0) return {
 					ok: !1,
 					error: d([a]),
@@ -68112,29 +68154,29 @@ function Rke(e) {
 				f.push({
 					op: "set",
 					jp: a,
-					value: C
+					value: T
 				});
 				continue;
 			}
 			return {
 				ok: !1,
-				error: u(a, (S = T.issues) == null ? [] : S),
+				error: u(a, (w = D.issues) == null ? [] : w),
 				writeBacks: [],
 				notices: c
 			};
 		}
-		T.resolution === "open" && c.push(`${a || "(根)"}=开放节点放行`);
-		let E = C$(s$(n, a), C, T.data, a);
-		if (E.length) return {
+		D.resolution === "open" && c.push(`${a || "(根)"}=开放节点放行`);
+		let O = C$(s$(n, a), T, D.data, a);
+		if (O.length) return {
 			ok: !1,
-			error: d(E),
+			error: d(O),
 			writeBacks: [],
 			notices: c
 		};
 		f.push({
 			op: "set",
 			jp: a,
-			value: T.data
+			value: D.data
 		});
 	}
 	return {
@@ -68153,7 +68195,8 @@ function Y6(e) {
 	if (d) {
 		let e = Fke({
 			value: p,
-			ctx: d
+			ctx: d,
+			mergeMode: !!a
 		});
 		if (!e.ok) return {
 			ok: !1,
@@ -68276,7 +68319,7 @@ function X6(e) {
 			error: AZ({
 				code: "PATCH_FAILED",
 				message: `patches[${e}]: ${c}`,
-				hint: "检查 op 与目标类型:merge 需对象,append 需数组"
+				hint: "检查 op 与目标类型:merge 需对象,append 需数组或字符串"
 			})
 		};
 		y(o, n), h.push({
@@ -68339,6 +68382,9 @@ function X6(e) {
 		var w;
 		let t = e.jp ? s$(n, e.jp) : n;
 		Array.isArray(t) && (w = e.elems) != null && w.length && t.push(...e.elems);
+	} else if (e.op === "appendStr") {
+		let t = e.jp ? s$(n, e.jp) : n;
+		typeof t == "string" && typeof e.str == "string" && c$(n, e.jp, t + e.str);
 	}
 	return (t = e.internalAfterWrite) == null || t.call(e, n, p), c == null || c(), {
 		ok: !0,
@@ -69406,15 +69452,23 @@ function t8(e, t = {}) {
 		fe(t);
 		let n = fF(async () => {
 			let e = v.list();
-			return e.length ? m$({ resources: e }) : "当前无已注册的受保护资源(read 受保护路径会懒注册)";
+			if (!e.length) {
+				let e = [...b.resourcesByPath.entries()].filter(([, e]) => e.mode === "freeze").map(([e]) => e);
+				return e.length ? `资源池为空,但集成方静态配置了 freeze 只读字段:${e.join("、 ")}(freeze 无句柄、不可释放;resource_delete 仅对 verbatim 生效)` : "当前无已注册的受保护资源(read 受保护路径会懒注册)";
+			}
+			return m$({ resources: e });
 		}, {
 			name: "resource_list",
 			description: "列出所有已注册的受保护资源(path/mode/handle/bytes)。",
 			schema: B({})
 		}), r = fF(async ({ path: e, handle: t }) => {
-			var n;
-			let r = e;
-			return !r && t && (r = (n = v.get(t)) == null ? void 0 : n.path), r ? v.delete(r) ? `已释放资源 "${r}"(后续 read 该字段会重新懒注册)` : `资源 "${r}" 不存在(无需释放)` : AZ({
+			var n, r;
+			let i = e;
+			return !i && t && (i = (n = v.get(t)) == null ? void 0 : n.path), i ? v.delete(i) ? `已释放资源 "${i}"(后续 read 该字段会重新懒注册)` : ((r = b.resourcesByPath.get(i)) == null ? void 0 : r.mode) === "freeze" ? AZ({
+				code: "FROZEN_FIELD",
+				message: `字段 "${i}" 为 freeze 静态保护(不在资源池、无句柄、不可释放)`,
+				hint: "freeze 由集成方在 data.resources 静态配置,只读不可解;含冻结字段的元素无法整体删除,请保留该元素或由集成方调整 data.resources"
+			}) : `资源 "${i}" 不存在(无需释放)` : AZ({
 				code: "RESOURCE_NOT_FOUND",
 				message: "未提供 path 或有效 handle",
 				hint: "传要释放的受保护字段 path 或 handle"
@@ -70489,6 +70543,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,务必末行带上)。一行内,只写可复用结论。`;