page-agent-sdk 4.1.0 → 4.2.1

package/dist/page-agent-sdk.js

@@ -20,7 +20,7 @@ function v(e) {
 	return !!(e == null || typeof e == "string" || e instanceof ArrayBuffer || ArrayBuffer.isView(e) || typeof Blob < "u" && e instanceof Blob || e instanceof URLSearchParams || e instanceof FormData);
 }
 function y(e) {
-	let t = e.model || "gpt-3.5-turbo", r = e.temperature, i = e.maxTokens, a = e.baseUrl;
+	let t = e.model || "deepseek-v4-flash", r = e.temperature, i = e.maxTokens, a = e.baseUrl;
 	if (e.mode === "direct") {
 		let o = !1;
 		try {
@@ -5996,7 +5996,7 @@ function yf(e) {
 	return Array.isArray(r) && r.length && r[0] && typeof r[0].jsonPath == "string" ? r[0].jsonPath : "";
 }
 function bf(e) {
-	let { apiKey: t, baseUrl: r, model: c = "gpt-3.5-turbo", temperature: l = .7, maxTokens: u, extraBody: d, extraConfig: f, systemPrompt: p, tools: m = [], middleware: h = [], maxToolRounds: g, maxIterations: _, maxRetries: v = 2, retryDelayMs: y = 500, stallMs: b = Eu, streamMaxMs: x = Ou, toolTimeoutMs: S, maxParallelTools: D = 1, maxVerifyAttempts: ee = 0, roundTokenBudget: te = 0, onLog: A, onLlmChange: ne, imageContentFormat: re = "openai", staleReadInvalidation: ie = !0, debug: P = !1 } = e, F = g ?? ff;
+	let { apiKey: t, baseUrl: r, model: c = "deepseek-v4-flash", temperature: l = .7, maxTokens: u, extraBody: d, extraConfig: f, systemPrompt: p, tools: m = [], middleware: h = [], maxToolRounds: g, maxIterations: _, maxRetries: v = 2, retryDelayMs: y = 500, stallMs: b = Eu, streamMaxMs: x = Ou, toolTimeoutMs: S, maxParallelTools: D = 1, maxVerifyAttempts: ee = 0, roundTokenBudget: te = 0, onLog: A, onLlmChange: ne, imageContentFormat: re = "openai", staleReadInvalidation: ie = !0, debug: P = !1 } = e, F = g ?? ff;
 	(!Number.isFinite(F) || F < 1) && (console.warn(`[page-agent-sdk] maxToolRounds=${F} 非法(须 ≥1 正整数),已 clamp 到 1(0/负数致主循环 while 不进 → agent 不调 LLM 静默返回兜底文案)`), F = 1);
 	let I = C({
 		model: c,
@@ -7493,7 +7493,7 @@ function Mp(e, t, n, r) {
 	}
 	if (t === "move") return Pp(e, n, r);
 	let i = n ? bp(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" ? (xp(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 Np(e, t) {
 	let n = t.split("."), r = e;
@@ -7636,6 +7636,7 @@ function Wp(e) {
 				"## 当前精修目标",
 				t.map((e) => `· ${e.path}${e.label ? `(${e.label})` : ""}`).join("\n"),
 				`仅操作上述 ${t.length} 个聚焦子树${t.length > 1 ? "之一" : ""},用户未指明目标的指令默认作用于聚焦组件(「增加/修改/删除 X」类指令优先理解为对聚焦组件本身的改动 —— 如为其加页签/子项,写焦点路径的子路径;仅用户明确要求新建独立组件时才需解除焦点);不要改动其他组件;${a}`,
+				"用户用指示代词提问(「这是啥/这个/它是干什么的」等)时,所指默认是聚焦目标 —— 先 read 聚焦子树,再围绕聚焦组件回答,勿泛答整页",
 				"read 不带路径时默认只返回聚焦子树;需要全量主数据时显式列顶层键(read({jsonPaths:[...]}) )"
 			], r = e.getSchema();
 			if (r) {
@@ -10065,47 +10066,63 @@ function Sg(e, t, n, r) {
 		hint: "重新 read 该字段触发懒注册重建句柄,再写回新句柄 ⟦res:<handle>⟧"
 	};
 }
-function Cg(e, t) {
-	let n = t.getBind();
-	for (let [r, i] of t.resourcesByPath) {
-		let a = bp(n, r), o = bp(e, r);
-		if (o === void 0) {
-			a !== void 0 && xp(e, r, a);
-			continue;
+function Cg(e, t, n) {
+	let r = t.getBind();
+	for (let [i, a] of t.resourcesByPath) {
+		let o = bp(r, i), s = bp(e, i);
+		if (s === void 0) {
+			if (o === void 0) continue;
+			let t = i.split(".");
+			if (bp(e, t.length > 1 ? t.slice(0, -1).join(".") : "") !== void 0) {
+				xp(e, i, o);
+				continue;
+			}
+			if (!(e && typeof e == "object" && t[0] in e)) {
+				if (n) continue;
+				xp(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 === pg(r)) {
-				xp(e, r, a);
+		if (a.mode === "freeze") {
+			if (s === pg(i)) {
+				xp(e, i, o);
 				continue;
 			}
-			if (!vg(o, a)) return {
+			if (!vg(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 = hg(o);
+			let n = hg(s);
 			if (n && n.type === "res") {
-				let i = Sg(n.handle, r, a, t.resourceStore);
-				if ("value" in i) {
-					xp(e, r, i.value);
+				let r = Sg(n.handle, i, o, t.resourceStore);
+				if ("value" in r) {
+					xp(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 (!vg(o, a)) return {
+			if (!vg(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 取到的值)保持不变"
 			};
 		}
@@ -10126,18 +10143,18 @@ function wg(e, t, n) {
 	});
 }
 function Tg(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 = Cp(t), i = Cg(r, n);
-	return i.ok ? {
+	let i = Cp(t), a = Cg(i, n, r);
+	return a.ok ? {
 		ok: !0,
-		value: r
+		value: i
 	} : {
 		ok: !1,
-		error: wg(i)
+		error: wg(a)
 	};
 }
 function Eg(e) {
@@ -10356,7 +10373,32 @@ function Mg(e) {
 			continue;
 		}
 		if (i === "append") {
-			let e = o[p++]?.elems ?? [];
+			let e = o[p++]?.elems ?? [], r = bp(n, a);
+			if (typeof r == "string" && typeof e[0] == "string") {
+				let n = e[0], i = Df(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",
@@ -10365,14 +10407,14 @@ function Mg(e) {
 				});
 				continue;
 			}
-			let n = Df(t, a);
-			if (n.kind === "missing") return {
+			let i = Df(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,
@@ -10380,8 +10422,8 @@ function Mg(e) {
 				});
 				continue;
 			}
-			let r = jf(n.schemas);
-			if (!r.length) {
+			let s = jf(i.schemas);
+			if (!s.length) {
 				c.push(`${a || "(根)"}:目标非 schema 声明数组,元素未校验放行`), f.push({
 					op: "appendElems",
 					jp: a,
@@ -10389,36 +10431,36 @@ function Mg(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 = Rp(void 0, e[t], o, a ? `${a}.${t}` : String(t));
-				if (l.length) return {
+				let o = Rp(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;
 		}
@@ -10551,7 +10593,8 @@ function Ng(e) {
 	if (l) {
 		let e = Tg({
 			value: d,
-			ctx: l
+			ctx: l,
+			mergeMode: !!r
 		});
 		if (!e.ok) return {
 			ok: !1,
@@ -10673,7 +10716,7 @@ function Pg(e) {
 			error: $({
 				code: "PATCH_FAILED",
 				message: `patches[${e}]: ${c}`,
-				hint: "检查 op 与目标类型:merge 需对象,append 需数组"
+				hint: "检查 op 与目标类型:merge 需对象,append 需数组或字符串"
 			})
 		};
 		v(o, a), m.push({
@@ -10730,6 +10773,9 @@ function Pg(e) {
 	} else if (e.op === "appendElems") {
 		let n = e.jp ? bp(t, e.jp) : t;
 		Array.isArray(n) && e.elems?.length && n.push(...e.elems);
+	} else if (e.op === "appendStr") {
+		let n = e.jp ? bp(t, e.jp) : t;
+		typeof n == "string" && typeof e.str == "string" && xp(t, e.jp, n + e.str);
 	}
 	return e.internalAfterWrite?.(t, f), s?.(), {
 		ok: !0,
@@ -11772,14 +11818,22 @@ function Gg(e, n = {}) {
 		I(n);
 		let i = r(async () => {
 			let e = d.list();
-			return e.length ? Op({ 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 Op({ 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}" 不存在(无需释放)` : $({
+			return !n && t && (n = d.get(t)?.path), n ? d.delete(n) ? `已释放资源 "${n}"(后续 read 该字段会重新懒注册)` : p.resourcesByPath.get(n)?.mode === "freeze" ? $({
+				code: "FROZEN_FIELD",
+				message: `字段 "${n}" 为 freeze 静态保护(不在资源池、无句柄、不可释放)`,
+				hint: "freeze 由集成方在 data.resources 静态配置,只读不可解;含冻结字段的元素无法整体删除,请保留该元素或由集成方调整 data.resources"
+			}) : `资源 "${n}" 不存在(无需释放)` : $({
 				code: "RESOURCE_NOT_FOUND",
 				message: "未提供 path 或有效 handle",
 				hint: "传要释放的受保护字段 path 或 handle"
@@ -12817,6 +12871,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,务必末行带上)。一行内,只写可复用结论。`;