page-agent-sdk 4.5.0 → 4.6.0

package/dist/page-agent-sdk.js

@@ -5445,7 +5445,7 @@ function cd(e) {
 }
 function ld(e, t) {
 	let n = t || {};
-	if (e === "query_data") return [cd(String(n.expr || ""))];
+	if (e === "query_data") return (Array.isArray(n.queries) && n.queries.length ? n.queries.map(String) : [String(n.expr || "")]).map((e) => cd(e));
 	if (e === "search_data") return [$u];
 	let r = [];
 	if (typeof n.jsonPath == "string" && n.jsonPath && r.push(n.jsonPath), Array.isArray(n.jsonPaths)) for (let e of n.jsonPaths) typeof e == "string" && e && r.push(e);
@@ -5493,7 +5493,7 @@ function ud(e) {
 }
 function dd(e, t, n, r) {
 	let i = e.map(ad).join("、"), a = [...new Set(n.flatMap((e) => e.paths))].map(ad).join("、"), o = [`⏱[过期快照] 此前读取 ${i} 的结果已失效(${r === void 0 ? `已写入 ${a}` : `第 ${r} 轮写入了 ${a}`})。`];
-	return n.some((e) => e.hasPostValue) ? o.push(`该轮写入结果已含 ${a} 最新值与新 hash;${i} 的兄弟子树(未触及部分)仍为读取时原值可参考。`) : o.push(`${i} 的兄弟子树(未触及部分)仍为读取时原值可参考。`), t === "query_data" || t === "search_data" ? o.push(`需当前结果时重跑 ${t}(表达式/条件不变即可)。`) : o.push(`需当前精确值时再 read(建议窄读:${i})。`), o.join("\n");
+	return n.some((e) => e.hasPostValue) ? o.push(`该轮写入结果已含 ${a} 最新值与新 hash,直接引用即可;原读取结果整体已过期,未提及路径需引用时按下方指引重读/重跑。`) : o.push("原读取结果整体已过期(含未触及的兄弟路径),需引用时按下方指引重读/重跑。"), t === "query_data" || t === "search_data" ? o.push(`需当前结果时重跑 ${t}(表达式/条件不变即可)。`) : o.push(`需当前精确值时再 read(建议窄读:${i})。`), o.join("\n");
 }
 function fd(e, t, n = {}) {
 	let r = n.maxParallelTools ?? 1, i = t.map((e) => ud(e)).filter((e) => e !== null);
@@ -11152,7 +11152,7 @@ function qg(e, n = {}) {
 		e.writeCapable = t;
 	}, oe = r(async () => [`说明: ${l}`, "格式: 写入值需为 JSON,且通过声明的 schema 校验(校验失败时 write 会返回结构化错误,含具体字段与期望类型)。"].join("\n"), {
 		name: "describe_data",
-		description: "获取主数据的说明与格式要求。",
+		description: "获取主数据的说明与格式要求(等价于 read 不传 jsonPath;优先用 read 单一入口)。",
 		schema: t.object({})
 	}), se = r(async ({ id: e }, t) => {
 		let n = y(t);
@@ -11180,8 +11180,8 @@ function qg(e, n = {}) {
 		});
 	}, {
 		name: "restore_data",
-		description: "把主数据回退到某个快照(就地还原,保留响应式)。不传 id 则回退最近一次(快速回退)。可用 history_data({list:true}) 查看快照列表。",
-		schema: t.object({ id: t.number().int().optional().describe("指定快照序号;不传则回退最近一次") })
+		description: "把主数据回退到某个快照(不传 id 回退最近一次)。快照列表用 history_data({list:true})。",
+		schema: t.object({ id: t.number().int().optional().describe("快照序号;不传回退最近一次") })
 	});
 	ae(se);
 	let ce = r(async ({ id: e, jsonPath: t, list: n }) => {
@@ -11223,43 +11223,54 @@ function qg(e, n = {}) {
 		return `快照 #${r.id}[${r.op}]${r.label ? `(${r.label})` : ""}${a ? ` @ ${a}` : ""} = ${Op(i)}`;
 	}, {
 		name: "history_data",
-		description: "查看主数据快照(只读不回退当前)。list:true 列时间线;传 id 看某次快照内容(默认最近),jsonPath 可只看子路径。冲突诊断/看上一版用;对比差异用 diff_data;回退用 restore_data。",
+		description: "查看主数据快照(只读不回退):list:true 列时间线;传 id 看某次内容(默认最近),jsonPath 可只看子路径。对比差异用 diff_data;回退用 restore_data。",
 		schema: t.object({
-			id: t.number().int().optional().describe("快照序号;不传则最近一次(list:true 时忽略)"),
-			jsonPath: t.string().optional().describe("只看快照的某子路径(相对主数据根);不传则整个快照"),
-			list: t.boolean().optional().describe("true 则列出快照时间线元信息(序号/操作/标签/时间/大小);不传则查看单条快照内容")
+			id: t.number().int().optional().describe("快照序号;不传看最近一次(list:true 时忽略)"),
+			jsonPath: t.string().optional().describe("只看快照的某子路径"),
+			list: t.boolean().optional().describe("true 列出快照时间线(序号/操作/标签/时间/大小)")
 		})
-	}), L = r(async ({ expr: e, limit: t }, n) => {
-		let r = y(n);
+	}), L = r(async ({ expr: e, queries: t, limit: n }, r) => {
+		let i = y(r);
 		if (typeof c != "object" || !c) return $({
 			code: "NOT_OBJECT",
 			message: `主数据不是对象/数组,无法查询(当前为 ${c === void 0 ? "undefined" : typeof c})`,
 			hint: "query 仅适用于对象/数组;叶子用 read 读"
 		});
-		let i = u ? Lf(c, s) : c, a;
-		try {
-			a = Ju(i, e);
-		} catch (t) {
-			return $({
-				code: "JSONPATH_SYNTAX",
-				message: `JSONPath 解析错误: ${t.message}`,
-				hint: "语法子集:$ .key [n] [\"key\"] [*] [?(filter)] ..key ..*;filter:@.field op literal,&&/||/();对象根需先点出数组字段再过滤,如 $.components[?(@.x>1)]",
-				details: { expr: e }
-			});
-		}
-		let o = t ?? 50, l = a.slice(0, o), d = b(n), f = l.map((e) => `{"path":${JSON.stringify(e.path)},"index":${e.index === void 0 ? "null" : e.index},"value":${Op(Hg(e.value, r === "", te, N, {
-			rootExempt: !1,
-			rootPath: String(e.path ?? ""),
-			fullTextPrefixes: d,
-			onSummarized: S
-		}))}}`);
-		return `{"matched":${a.length},"returned":${l.length},"truncated":${a.length > o},"results":[${f.join(",")}]}`;
+		let a = u ? Lf(c, s) : c, o = b(r), l = (e) => {
+			let t;
+			try {
+				t = Ju(a, e);
+			} catch (t) {
+				return $({
+					code: "JSONPATH_SYNTAX",
+					message: `JSONPath 解析错误: ${t.message}`,
+					hint: "语法子集:$ .key [n] [\"key\"] [*] [?(filter)] ..key ..*;filter:@.field op literal,&&/||/();对象根需先点出数组字段再过滤,如 $.components[?(@.x>1)]",
+					details: { expr: e }
+				});
+			}
+			let r = n ?? 50, s = t.slice(0, r), c = s.map((e) => `{"path":${JSON.stringify(e.path)},"index":${e.index === void 0 ? "null" : e.index},"value":${Op(Hg(e.value, i === "", te, N, {
+				rootExempt: !1,
+				rootPath: String(e.path ?? ""),
+				fullTextPrefixes: o,
+				onSummarized: S
+			}))}}`);
+			return `{"matched":${t.length},"returned":${s.length},"truncated":${t.length > r},"results":[${c.join(",")}]}`;
+		};
+		return t && t.length ? `{"batch":true,"results":[${t.map((e) => {
+			let t = l(e);
+			return t.startsWith("ERROR:") ? `{"expr":${JSON.stringify(e)},"ok":false,"error":${JSON.stringify(t)}}` : `{"expr":${JSON.stringify(e)},"ok":true,${t.slice(1)}`;
+		}).join(",")}]}` : e === void 0 ? $({
+			code: "SCHEMA_INVALID",
+			message: "query_data 需传 expr(单条 JSONPath)或 queries(2-10 条批量),两者都没传",
+			hint: "单表达式用 expr;多条件筛选一次取回用 queries"
+		}) : l(e);
 	}, {
 		name: "query_data",
-		description: "用 JSONPath 查询主数据(只读):$ 根/.key/[n]/[*]/[?(==/!=/</<=/>/>=,&&/||)]/..key 递归。返回匹配元素 path/index/value(path 可作 write patch 的 jsonPath);大数组筛选定位用它。",
+		description: "用 JSONPath 查询主数据(只读):$ 根/.key/[n]/[*]/[?(==/!=/</<=/>/>=,&&/||)]/..key 递归。返回匹配元素 path/index/value(path 可作 write patch 的 jsonPath);大数组筛选定位用它;多条件筛选传 queries 数组一次取回。",
 		schema: t.object({
-			expr: t.string().describe("JSONPath 表达式,如 $.components[?(@.type==\"card\" && @.price<100)] 或 $..title(递归找所有 title)"),
-			limit: t.number().int().min(1).max(200).optional().describe("返回结果上限,默认 50")
+			expr: t.string().optional().describe("单条 JSONPath 表达式,如 $.components[?(@.type==\"card\" && @.price<100)] 或 $..title(递归找所有 title)"),
+			queries: t.array(t.string()).min(2).max(10).optional().describe("批量模式:2-10 条 JSONPath 一次取回(与 expr 同传按 queries);逐条独立返回,单条失败该项标 error 不整批"),
+			limit: t.number().int().min(1).max(200).optional().describe("返回结果上限(批量时逐条适用),默认 50")
 		})
 	}), R = r(async ({ query: e, mode: t, fuzzyThreshold: n, matchKey: r, limit: i }) => {
 		if (c == null) return $({
@@ -11436,11 +11447,11 @@ function qg(e, n = {}) {
 		});
 	}, {
 		name: "eval_script",
-		description: "在 Worker 沙箱对主数据跑自定义 JS(无 window/fetch,超时 3s)。入参 data(深拷贝),返回值即结果。mode:query 只读回给 LLM(过滤/映射/聚合)/transform 落地(返回完整新值或 {patches:[...]} 增量)。jsonPath 可只对子树执行。",
+		description: "在 Worker 沙箱对主数据跑自定义 JS(无网络,超时 3s)。入参 data(深拷贝);mode:query 只读回给 LLM/transform 校验后落地(完整新值或 {patches:[…]} 增量);jsonPath 可限定子树。",
 		schema: t.object({
-			script: t.string().describe("JS 脚本体,如 data.filter(c=>c.stock>0).map(c=>c.id);入参名 data;末尾表达式或 return 即返回值"),
-			mode: t.enum(["query", "transform"]).optional().describe("query=只读返回结果(默认),transform=校验后落地为新值"),
-			jsonPath: t.string().optional().describe("子树模式:仅对 jsonPath 指向的子树执行(降低大 JSON 成本);transform 时返回值作为该子树新值")
+			script: t.string().describe("JS 脚本(入参 data;末尾表达式或 return 即返回值),如 data.filter(c=>c.stock>0)"),
+			mode: t.enum(["query", "transform"]).optional().describe("query=只读返回结果(默认)/transform=校验后落地为新值"),
+			jsonPath: t.string().optional().describe("子树模式:仅对该子树执行;transform 返回值作为子树新值")
 		})
 	});
 	ae(z, (e) => e?.mode === "transform");
@@ -11525,14 +11536,14 @@ function qg(e, n = {}) {
 		return v === void 0 ? `${x}主数据${h ? ` @ ${h}` : ""}${E} = (undefined) (hash=${p})` : `${x}主数据${h ? ` @ ${h}` : ""}${E} = ${Op(v)} (hash=${p})`;
 	}, {
 		name: "read",
-		description: "读取主数据(高层入口,合并 describe/get)。不传 jsonPath → 返回主数据说明 + 格式提示(含字段约束);传 jsonPath → 返回该子路径当前值 + hash;传 jsonPaths → 一次读多个不相关子路径(省多轮往返)。hash 用于乐观锁(声明 conflictWatchFields 后 write 自动比对;未声明不自动校验)。fields(字段裁剪)/depth(深度截断)减体积;offset+limit 对数组目标分页(返回切片 + total/hasMore)。",
+		description: "读主数据(只读):不传 jsonPath 返回整体说明+格式;传 jsonPath 返回该路径当前值+hash;传 jsonPaths 一次读多个不相关路径。fields/depth 裁剪、offset/limit 数组分页减体积;详细规则见系统提示。",
 		schema: t.object({
-			jsonPath: t.string().optional().describe("要读的子路径(相对主数据根,如 components.0.text);不传则读整个主数据并返回说明"),
-			jsonPaths: t.array(t.string()).optional().describe("多路径读取:一次读多个不相关子路径(与 jsonPath 互斥,优先于 jsonPath);返回各路径值,非法路径单项标错不整批失败"),
-			fields: t.array(t.string()).optional().describe("字段裁剪:只返回指定字段(对对象/数组元素投影),减少返回体积,如 [\"id\",\"title\"]"),
-			depth: t.number().int().min(0).optional().describe("嵌套深度限制:0=只根占位,1=根+子,递归到 depth 层后用 {...}/[...] 占位截断,减少深层返回体积"),
-			offset: t.number().int().min(0).optional().describe("数组分页起始偏移(仅当读取目标是数组时生效,默认 0),配合 limit 分页读大数组"),
-			limit: t.number().int().min(1).max(200).optional().describe("数组分页每页条数(默认 50,上限 200;仅数组时生效),返回切片 + total/hasMore")
+			jsonPath: t.string().optional().describe("要读的子路径(如 components.0.text);不传读整体+说明"),
+			jsonPaths: t.array(t.string()).optional().describe("多路径一次读(与 jsonPath 互斥,优先);非法路径单项标错不整批"),
+			fields: t.array(t.string()).optional().describe("只返回指定字段(投影减体积),如 [\"id\",\"title\"]"),
+			depth: t.number().int().min(0).optional().describe("嵌套深度限制(0=只根占位,逐层截断减体积)"),
+			offset: t.number().int().min(0).optional().describe("数组分页起始偏移(仅数组目标,默认 0)"),
+			limit: t.number().int().min(1).max(200).optional().describe("数组分页每页条数(默认 50,上限 200),返回切片+total/hasMore")
 		})
 	}), le = r(async ({ value: e, patch: t, patches: n, del: r, dryRun: a }, l) => {
 		let d = y(l), f = "set";
@@ -11651,9 +11662,9 @@ function qg(e, n = {}) {
 		}
 	}, {
 		name: "write",
-		description: "写入主数据(高层入口,合并 set/edit/delete + 自动乐观锁 + 自动快照)。四意图:① 整体替换 write({value:整个对象});② 增量 write({patch:{op,jsonPath,value}}) op=set/remove/merge/append/move(move 的 value=目标路径字符串);③ 批量原子 write({patches:[...]})(任一失败整批回滚);④ 删子路径 write({patch:{jsonPath},del:true})。dryRun:true 预检不落盘。写入自动 schema 校验(失败不写,按错误修正重试)+ 自动快照。详细用法见系统提示「能力使用提示」。",
+		description: "写主数据(唯一写入口;自动 schema 校验+乐观锁+快照)。四意图:整体替换 {value}/增量 {patch:{op,jsonPath,value}}(op set/remove/merge/append/move)/原子批 {patches:[…]}(任一失败回滚)/删子路径 {patch:{jsonPath},del:true};dryRun 预检;详细规则见系统提示。",
 		schema: t.object({
-			value: t.unknown().optional().describe("JSON 对象(推荐,如 {title:\"x\"})或 JSON 字符串;set 整体或单个 patch 的 set/merge/append 必填"),
+			value: t.unknown().optional().describe("JSON 对象(推荐)或 JSON 字符串;set 整体或 patch 的 set/merge/append 必填"),
 			patch: t.object({
 				op: t.enum([
 					"set",
@@ -11661,10 +11672,10 @@ function qg(e, n = {}) {
 					"merge",
 					"append",
 					"move"
-				]).optional().describe("增量操作:set 设值/remove 删/merge 合并对象/append 追加数组/move 移动数组元素(value=目标路径字符串)。单 patch edit 缺省按 set;del 模式(write({patch:{jsonPath},del:true}))不读 op 可省略"),
-				jsonPath: t.string().optional().describe("相对主数据根的点号路径(如 components.0.text);set/remove 必填,merge/append 不填则作用于根"),
-				value: t.unknown().optional().describe("该 patch 的值(JSON 直传或 JSON 字符串);set/merge/append 必填,remove 不需。与顶层 value 二选一:优先 patch.value,未填则回退顶层 value(向后兼容)。推荐用 patch.value(自带,与 patches 元素一致,无歧义)")
-			}).optional().describe("单个增量编辑(自带 value,与 patches 元素一致);传 patch(无 patches)走单 patch edit 语义"),
+				]).optional().describe("set 设值/remove 删/merge 合并对象/append 追加数组/move 移动元素(value=目标路径字符串);缺省 set"),
+				jsonPath: t.string().optional().describe("相对主数据根的点号路径(如 components.0.text);set/remove 必填,merge/append 不填作用于根"),
+				value: t.unknown().optional().describe("该 patch 的值(JSON 或 JSON 字符串);与顶层 value 二选一,优先 patch.value")
+			}).optional().describe("单个增量编辑(自带 value)"),
 			patches: t.array(t.object({
 				op: t.enum([
 					"set",
@@ -11673,11 +11684,11 @@ function qg(e, n = {}) {
 					"append",
 					"move"
 				]),
-				jsonPath: t.string().optional().describe("相对主数据根的点号路径;set/remove 必填,merge/append 不填则作用于根"),
-				value: t.unknown().optional().describe("JSON 值(推荐直传)或 JSON 字符串;set/merge/append 必填,remove 不需")
-			})).optional().describe("批量增量编辑:一次原子应用多个 patch(任一失败则整体不写入,clone 试跑全部 + schema 校验通过才落 live)。适合一次改多处,减少多轮往返"),
+				jsonPath: t.string().optional().describe("相对主数据根的点号路径;set/remove 必填,merge/append 不填作用于根"),
+				value: t.unknown().optional().describe("JSON 值(推荐直传)或 JSON 字符串;set/merge/append 必填")
+			})).optional().describe("批量原子编辑:一次提交多个 patch,任一失败整体不写入;适合一次改多处"),
 			del: t.boolean().optional().describe("true 则删除 patch.jsonPath 指定的子路径"),
-			dryRun: t.boolean().optional().describe("预检模式:走完整校验链(schema + 白名单 + patch 应用到 clone)但不落盘、不入快照,返回预览。四意图(value/patch/patches/del)均支持;乐观锁冲突照常检测(返回 VERSION_CONFLICT 不挂起)")
+			dryRun: t.boolean().optional().describe("预检:走完整校验链但不落盘不入快照;冲突返回 VERSION_CONFLICT 不挂起")
 		})
 	});
 	ae(le);
@@ -14509,7 +14520,7 @@ function Py(e, t, n) {
 		name: "usageHints",
 		augmentPrompt: (i) => {
 			let a = [];
-			if (r.planning && (a.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), a.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), a.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), a.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), a.push("  · update_todo 标 completed 时附 evidence: 本次实际写入的 jsonPath(如 \"components.2\"),供收口对账;工作经委派子 agent 完成等无主写路径时,如实写明完成方式(勿编造路径)。"), e?.humanConfirm ? a.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。") : a.push("  · 规划出多步方案若需用户拍板 → 以文字列出方案选项等用户回复,勿自行拍板。"), a.push("  · 计划修订有次数上限(maxPlanRevisions,默认 5,只计 write_todos 调用、调研轮不计):勿反复改计划而不执行,规划充分后即开始 write 落地。")), t && (a.push("改主数据前先 read({jsonPath}) 读其当前真实值(返回末尾 hash=xxx 为乐观锁标识),基于真实值改,不要凭记忆。写入是否被自动校验由集成方 conflictWatchFields 声明决定:若已声明且主数据在你 read 之后被外部改过,会触发冲突——集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 read 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 read 拿最新值再改。"), a.push("不确定主数据字段结构时用 describe_data 查看说明。"), a.push("修改大对象/数组优先用 write 增量改({patch:{op,jsonPath,value}} 只发改动部分),避免 write({value}) 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), a.push("修改主数据出错时可用 restore_data 回退最近一次。"), a.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 write({patch}) 改。"), a.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), a.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), a.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), a.push("【省轮次·批量】≥2 个路径一律 read({jsonPaths:[...]}) 一次取回(路径互不相关也合批,禁止连续单路径 read);改多处用 write({patches:[{op:\"set\",jsonPath,value},...]}) 一次提交多改动(原子任一失败回滚),勿逐个 write 烧轮次预算。"), a.push("读到 <subtree Nkb keys:[…] #指纹> 或 <code Nkb> 占位 = 该子树键名/体积可见但内容未见:写入前先窄读全文(read({jsonPath:\"该子树路径\"}),结果根豁免返全文)或 set_focus 聚焦该区域;勿凭键名印象猜路径/猜值直写(直接写占位子树会被拦下要求先窄读)。"), a.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。")), r.subagent && a.push("独立子任务可 spawn_agent 委派(过程隔离,不占主上下文):默认只读,需要子 agent 写数据时传 writablePaths(路径前缀白名单,越界 PATH_OUT_OF_SCOPE)。多个独立子任务可 spawn_agents 并行委派(各子互不通信,结论由你汇总;并行委派不可授写权限,写操作由你收尾执行)。"), r.inspectEnv && a.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && a.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && (a.push("生成超大 JSON(如 50+ 组件页面,单次 write 受 max_tokens 限制装不下)用 draft_write 分块构建 → draft_commit 原子提交:draft_write({draftId, chunk, mode}) mode:\"start\" 新建/\"append\" 追加(拼 JSON 片段到 drafts 池);累积完 draft_commit({draftId}) 合并 + schema 校验 + 写主数据(失败草稿保留可修后重试,成功自动清草稿)。小改仍用 write patch,只在大 JSON 从零生成时用 draft。"), a.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=30(3.43 起;轮次预算吃紧时 system 会注入预算提示段,按提示优先收口);目标组件数很大时集成方仍可在 createChatSdk 显式上调 maxToolRounds(按 N+10 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。")), r.focus && (a.push("【上下文聚焦】判断任务范围,用 set_focus/add_focus/remove_focus/clear_focus 自动收敛工作范围:"), a.push("  · 局部任务(只改某一组件/区域,如「调导航栏」「改 components.3 样式」)→ 先 read 定位 jsonPath,再 set_focus({path:\"该子树路径\"}) 聚焦;聚焦后每轮只看该子树结构,写其他位置会被 PATH_DENIED 拒绝。"), a.push("  · 多个相关组件(如「同时改导航栏和页脚」)→ set_focus 聚焦首个后用 add_focus({path}) 追加其余;聚焦后可写任一焦点子树,越界仍被拒;移除单个用 remove_focus({path})。"), a.push("  · 全局任务(多处/整体结构,如「重排所有组件」「换主题」)→ 不要聚焦,保持全量视野直接写。"), a.push("  · 完成局部精修、要转向其他区域或做整体改动 → 调 clear_focus 退出聚焦(清空全部焦点),恢复全部读写权限。"), a.push("  · set_focus/add_focus 的 path 必须在 schema 内(类型校验);不确定路径先 read/describe_data 查。")), e?.subagents?.length) {
+			if (r.planning && (a.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), a.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), a.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), a.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), a.push("  · update_todo 标 completed 时附 evidence: 本次实际写入的 jsonPath(如 \"components.2\"),供收口对账;工作经委派子 agent 完成等无主写路径时,如实写明完成方式(勿编造路径)。"), e?.humanConfirm ? a.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。") : a.push("  · 规划出多步方案若需用户拍板 → 以文字列出方案选项等用户回复,勿自行拍板。"), a.push("  · 计划修订有次数上限(maxPlanRevisions,默认 5,只计 write_todos 调用、调研轮不计):勿反复改计划而不执行,规划充分后即开始 write 落地。")), t && (a.push("改主数据前先 read({jsonPath}) 读其当前真实值(返回末尾 hash=xxx 为乐观锁标识),基于真实值改,不要凭记忆。写入是否被自动校验由集成方 conflictWatchFields 声明决定:若已声明且主数据在你 read 之后被外部改过,会触发冲突——集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 read 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 read 拿最新值再改。"), a.push("读类分流:取值/结构 → read(多路径用 jsonPaths);字段约束 → schema_data;条件筛选定位 → query_data(多条一次用 queries);名字模糊找 → search_data;整体说明 → read 不传路径(= describe_data)。"), a.push("修改大对象/数组优先用 write 增量改({patch:{op,jsonPath,value}} 只发改动部分),避免 write({value}) 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), a.push("修改主数据出错时可用 restore_data 回退最近一次。"), a.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 write({patch}) 改。"), a.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), a.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), a.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), a.push("【省轮次·批量】≥2 个路径一律 read({jsonPaths:[...]}) 一次取回(路径互不相关也合批,禁止连续单路径 read);多条件筛选用 query_data({queries:[expr1,expr2,…]}) 一次取回(2-10 条);改多处用 write({patches:[{op:\"set\",jsonPath,value},...]}) 一次提交多改动(原子任一失败回滚),勿逐个 write 烧轮次预算。"), a.push("读到 <subtree Nkb keys:[…] #指纹> 或 <code Nkb> 占位 = 该子树键名/体积可见但内容未见:写入前先窄读全文(read({jsonPath:\"该子树路径\"}),结果根豁免返全文)或 set_focus 聚焦该区域;勿凭键名印象猜路径/猜值直写(直接写占位子树会被拦下要求先窄读)。"), a.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。")), r.subagent && a.push("独立子任务可 spawn_agent 委派(过程隔离,不占主上下文):默认只读,需要子 agent 写数据时传 writablePaths(路径前缀白名单,越界 PATH_OUT_OF_SCOPE)。多个独立子任务可 spawn_agents 并行委派(各子互不通信,结论由你汇总;并行委派不可授写权限,写操作由你收尾执行)。"), r.inspectEnv && a.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && a.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && (a.push("生成超大 JSON(如 50+ 组件页面,单次 write 受 max_tokens 限制装不下)用 draft_write 分块构建 → draft_commit 原子提交:draft_write({draftId, chunk, mode}) mode:\"start\" 新建/\"append\" 追加(拼 JSON 片段到 drafts 池);累积完 draft_commit({draftId}) 合并 + schema 校验 + 写主数据(失败草稿保留可修后重试,成功自动清草稿)。小改仍用 write patch,只在大 JSON 从零生成时用 draft。"), a.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=30(3.43 起;轮次预算吃紧时 system 会注入预算提示段,按提示优先收口);目标组件数很大时集成方仍可在 createChatSdk 显式上调 maxToolRounds(按 N+10 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。")), r.focus && (a.push("【上下文聚焦】判断任务范围,用 set_focus/add_focus/remove_focus/clear_focus 自动收敛工作范围:"), a.push("  · 局部任务(只改某一组件/区域,如「调导航栏」「改 components.3 样式」)→ 先 read 定位 jsonPath,再 set_focus({path:\"该子树路径\"}) 聚焦;聚焦后每轮只看该子树结构,写其他位置会被 PATH_DENIED 拒绝。"), a.push("  · 多个相关组件(如「同时改导航栏和页脚」)→ set_focus 聚焦首个后用 add_focus({path}) 追加其余;聚焦后可写任一焦点子树,越界仍被拒;移除单个用 remove_focus({path})。"), a.push("  · 全局任务(多处/整体结构,如「重排所有组件」「换主题」)→ 不要聚焦,保持全量视野直接写。"), a.push("  · 完成局部精修、要转向其他区域或做整体改动 → 调 clear_focus 退出聚焦(清空全部焦点),恢复全部读写权限。"), a.push("  · set_focus/add_focus 的 path 必须在 schema 内(类型校验);不确定路径先 read/describe_data 查。")), e?.subagents?.length) {
 				let t = e.subagents.filter((e) => (e.temperature ?? 0) >= Ny || /规划|创意|设计|方案|brainstorm|plan/i.test(e.description)), n = e.subagents.filter((e) => (e.temperature ?? 0) < Ny && /反思|审查|挑刺|校验|review|critique|reflect/i.test(e.description));
 				a.push("【规划-反思-执行·路由】按任务性质选模式,不要对简单任务过度编排:"), t.length && (a.push(`  · 创作/设计/开放性需求(如"设计主题风格""换个感觉")→ 先调 ${t.map((e) => "use_" + e.id).join("/")} 出 2-3 套方案(高温创意),`), a.push(e?.humanConfirm ? "    不要自己拍板;拿到方案后,若需用户拍板用 request_human_confirmation 弹选项。" : "    不要自己拍板;拿到方案后以文字列出选项等用户回复(humanConfirm 未开,勿调不存在工具)。")), n.length && a.push(`  · 严谨/易错/校验类 → 可先调 ${n.map((e) => "use_" + e.id).join("/")} 反思挑刺(低温审查),据反馈修订。`), a.push("  · 方案定稿后,由你(主 agent)用 write 落地成 JSON(低温度执行 + schema 校验 + 写前确认)。"), a.push("  · 简单/明确任务(如\"标题改红色\")直接执行,不必走规划-反思。");
 			}

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

@@ -55231,7 +55231,7 @@ function UCe(e) {
 }
 function WCe(e, t) {
 	let n = t || {};
-	if (e === "query_data") return [UCe(String(n.expr || ""))];
+	if (e === "query_data") return (Array.isArray(n.queries) && n.queries.length ? n.queries.map(String) : [String(n.expr || "")]).map((e) => UCe(e));
 	if (e === "search_data") return [VZ];
 	let r = [];
 	if (typeof n.jsonPath == "string" && n.jsonPath && r.push(n.jsonPath), Array.isArray(n.jsonPaths)) for (let e of n.jsonPaths) typeof e == "string" && e && r.push(e);
@@ -55281,7 +55281,7 @@ function KZ(e) {
 }
 function GCe(e, t, n, r) {
 	let i = e.map(UZ).join("、"), a = [...new Set(n.flatMap((e) => e.paths))].map(UZ).join("、"), o = [`⏱[过期快照] 此前读取 ${i} 的结果已失效(${r === void 0 ? `已写入 ${a}` : `第 ${r} 轮写入了 ${a}`})。`];
-	return n.some((e) => e.hasPostValue) ? o.push(`该轮写入结果已含 ${a} 最新值与新 hash;${i} 的兄弟子树(未触及部分)仍为读取时原值可参考。`) : o.push(`${i} 的兄弟子树(未触及部分)仍为读取时原值可参考。`), t === "query_data" || t === "search_data" ? o.push(`需当前结果时重跑 ${t}(表达式/条件不变即可)。`) : o.push(`需当前精确值时再 read(建议窄读:${i})。`), o.join("\n");
+	return n.some((e) => e.hasPostValue) ? o.push(`该轮写入结果已含 ${a} 最新值与新 hash,直接引用即可;原读取结果整体已过期,未提及路径需引用时按下方指引重读/重跑。`) : o.push("原读取结果整体已过期(含未触及的兄弟路径),需引用时按下方指引重读/重跑。"), t === "query_data" || t === "search_data" ? o.push(`需当前结果时重跑 ${t}(表达式/条件不变即可)。`) : o.push(`需当前精确值时再 read(建议窄读:${i})。`), o.join("\n");
 }
 function KCe(e, t, n = {}) {
 	var r, i;
@@ -68778,7 +68778,7 @@ function Q6(e, t = {}) {
 		e.writeCapable = t;
 	}, he = WP(async () => [`说明: ${_}`, "格式: 写入值需为 JSON,且通过声明的 schema 校验(校验失败时 write 会返回结构化错误,含具体字段与期望类型)。"].join("\n"), {
 		name: "describe_data",
-		description: "获取主数据的说明与格式要求。",
+		description: "获取主数据的说明与格式要求(等价于 read 不传 jsonPath;优先用 read 单一入口)。",
 		schema: B({})
 	}), ge = WP(async ({ id: e }, t) => {
 		let n = D(t);
@@ -68806,8 +68806,8 @@ function Q6(e, t = {}) {
 		});
 	}, {
 		name: "restore_data",
-		description: "把主数据回退到某个快照(就地还原,保留响应式)。不传 id 则回退最近一次(快速回退)。可用 history_data({list:true}) 查看快照列表。",
-		schema: B({ id: au().int().optional().describe("指定快照序号;不传则回退最近一次") })
+		description: "把主数据回退到某个快照(不传 id 回退最近一次)。快照列表用 history_data({list:true})。",
+		schema: B({ id: au().int().optional().describe("快照序号;不传回退最近一次") })
 	});
 	me(ge);
 	let _e = WP(async ({ id: e, jsonPath: t, list: n }) => {
@@ -68850,46 +68850,57 @@ function Q6(e, t = {}) {
 		return `快照 #${r.id}[${r.op}]${r.label ? `(${r.label})` : ""}${a ? ` @ ${a}` : ""} = ${qQ(i)}`;
 	}, {
 		name: "history_data",
-		description: "查看主数据快照(只读不回退当前)。list:true 列时间线;传 id 看某次快照内容(默认最近),jsonPath 可只看子路径。冲突诊断/看上一版用;对比差异用 diff_data;回退用 restore_data。",
+		description: "查看主数据快照(只读不回退):list:true 列时间线;传 id 看某次内容(默认最近),jsonPath 可只看子路径。对比差异用 diff_data;回退用 restore_data。",
 		schema: B({
-			id: au().int().optional().describe("快照序号;不传则最近一次(list:true 时忽略)"),
-			jsonPath: z().optional().describe("只看快照的某子路径(相对主数据根);不传则整个快照"),
-			list: su().optional().describe("true 则列出快照时间线元信息(序号/操作/标签/时间/大小);不传则查看单条快照内容")
+			id: au().int().optional().describe("快照序号;不传看最近一次(list:true 时忽略)"),
+			jsonPath: z().optional().describe("只看快照的某子路径"),
+			list: su().optional().describe("true 列出快照时间线(序号/操作/标签/时间/大小)")
 		})
-	}), ve = WP(async ({ expr: e, limit: t }, n) => {
-		let r = D(n);
+	}), ve = WP(async ({ expr: e, queries: t, limit: n }, r) => {
+		let i = D(r);
 		if (typeof g != "object" || !g) return lZ({
 			code: "NOT_OBJECT",
 			message: `主数据不是对象/数组,无法查询(当前为 ${g === void 0 ? "undefined" : typeof g})`,
 			hint: "query 仅适用于对象/数组;叶子用 read 读"
 		});
-		let i = v ? wQ(g, h) : g, a;
-		try {
-			a = LZ(i, e);
-		} catch (t) {
-			return lZ({
-				code: "JSONPATH_SYNTAX",
-				message: `JSONPath 解析错误: ${t.message}`,
-				hint: "语法子集:$ .key [n] [\"key\"] [*] [?(filter)] ..key ..*;filter:@.field op literal,&&/||/();对象根需先点出数组字段再过滤,如 $.components[?(@.x>1)]",
-				details: { expr: e }
+		let a = v ? wQ(g, h) : g, o = O(r), s = (e) => {
+			let t;
+			try {
+				t = LZ(a, e);
+			} catch (t) {
+				return lZ({
+					code: "JSONPATH_SYNTAX",
+					message: `JSONPath 解析错误: ${t.message}`,
+					hint: "语法子集:$ .key [n] [\"key\"] [*] [?(filter)] ..key ..*;filter:@.field op literal,&&/||/();对象根需先点出数组字段再过滤,如 $.components[?(@.x>1)]",
+					details: { expr: e }
+				});
+			}
+			let r = n == null ? 50 : n, s = t.slice(0, r), c = s.map((e) => {
+				var t;
+				return `{"path":${JSON.stringify(e.path)},"index":${e.index === void 0 ? "null" : e.index},"value":${qQ(Z6(e.value, i === "", F, ce, {
+					rootExempt: !1,
+					rootPath: String((t = e.path) == null ? "" : t),
+					fullTextPrefixes: o,
+					onSummarized: A
+				}))}}`;
 			});
-		}
-		let o = t == null ? 50 : t, s = a.slice(0, o), c = O(n), l = s.map((e) => {
-			var t;
-			return `{"path":${JSON.stringify(e.path)},"index":${e.index === void 0 ? "null" : e.index},"value":${qQ(Z6(e.value, r === "", F, ce, {
-				rootExempt: !1,
-				rootPath: String((t = e.path) == null ? "" : t),
-				fullTextPrefixes: c,
-				onSummarized: A
-			}))}}`;
-		});
-		return `{"matched":${a.length},"returned":${s.length},"truncated":${a.length > o},"results":[${l.join(",")}]}`;
+			return `{"matched":${t.length},"returned":${s.length},"truncated":${t.length > r},"results":[${c.join(",")}]}`;
+		};
+		return t && t.length ? `{"batch":true,"results":[${t.map((e) => {
+			let t = s(e);
+			return t.startsWith("ERROR:") ? `{"expr":${JSON.stringify(e)},"ok":false,"error":${JSON.stringify(t)}}` : `{"expr":${JSON.stringify(e)},"ok":true,${t.slice(1)}`;
+		}).join(",")}]}` : e === void 0 ? lZ({
+			code: "SCHEMA_INVALID",
+			message: "query_data 需传 expr(单条 JSONPath)或 queries(2-10 条批量),两者都没传",
+			hint: "单表达式用 expr;多条件筛选一次取回用 queries"
+		}) : s(e);
 	}, {
 		name: "query_data",
-		description: "用 JSONPath 查询主数据(只读):$ 根/.key/[n]/[*]/[?(==/!=/</<=/>/>=,&&/||)]/..key 递归。返回匹配元素 path/index/value(path 可作 write patch 的 jsonPath);大数组筛选定位用它。",
+		description: "用 JSONPath 查询主数据(只读):$ 根/.key/[n]/[*]/[?(==/!=/</<=/>/>=,&&/||)]/..key 递归。返回匹配元素 path/index/value(path 可作 write patch 的 jsonPath);大数组筛选定位用它;多条件筛选传 queries 数组一次取回。",
 		schema: B({
-			expr: z().describe("JSONPath 表达式,如 $.components[?(@.type==\"card\" && @.price<100)] 或 $..title(递归找所有 title)"),
-			limit: au().int().min(1).max(200).optional().describe("返回结果上限,默认 50")
+			expr: z().optional().describe("单条 JSONPath 表达式,如 $.components[?(@.type==\"card\" && @.price<100)] 或 $..title(递归找所有 title)"),
+			queries: fu(z()).min(2).max(10).optional().describe("批量模式:2-10 条 JSONPath 一次取回(与 expr 同传按 queries);逐条独立返回,单条失败该项标 error 不整批"),
+			limit: au().int().min(1).max(200).optional().describe("返回结果上限(批量时逐条适用),默认 50")
 		})
 	}), ye = WP(async ({ query: e, mode: t, fuzzyThreshold: n, matchKey: r, limit: i }) => {
 		if (g == null) return lZ({
@@ -69070,11 +69081,11 @@ function Q6(e, t = {}) {
 		});
 	}, {
 		name: "eval_script",
-		description: "在 Worker 沙箱对主数据跑自定义 JS(无 window/fetch,超时 3s)。入参 data(深拷贝),返回值即结果。mode:query 只读回给 LLM(过滤/映射/聚合)/transform 落地(返回完整新值或 {patches:[...]} 增量)。jsonPath 可只对子树执行。",
+		description: "在 Worker 沙箱对主数据跑自定义 JS(无网络,超时 3s)。入参 data(深拷贝);mode:query 只读回给 LLM/transform 校验后落地(完整新值或 {patches:[…]} 增量);jsonPath 可限定子树。",
 		schema: B({
-			script: z().describe("JS 脚本体,如 data.filter(c=>c.stock>0).map(c=>c.id);入参名 data;末尾表达式或 return 即返回值"),
-			mode: Cu(["query", "transform"]).optional().describe("query=只读返回结果(默认),transform=校验后落地为新值"),
-			jsonPath: z().optional().describe("子树模式:仅对 jsonPath 指向的子树执行(降低大 JSON 成本);transform 时返回值作为该子树新值")
+			script: z().describe("JS 脚本(入参 data;末尾表达式或 return 即返回值),如 data.filter(c=>c.stock>0)"),
+			mode: Cu(["query", "transform"]).optional().describe("query=只读返回结果(默认)/transform=校验后落地为新值"),
+			jsonPath: z().optional().describe("子树模式:仅对该子树执行;transform 返回值作为子树新值")
 		})
 	});
 	me(be, (e) => (e == null ? void 0 : e.mode) === "transform");
@@ -69162,14 +69173,14 @@ function Q6(e, t = {}) {
 		return p === void 0 ? `${m}主数据${u ? ` @ ${u}` : ""}${x} = (undefined) (hash=${l})` : `${m}主数据${u ? ` @ ${u}` : ""}${x} = ${qQ(p)} (hash=${l})`;
 	}, {
 		name: "read",
-		description: "读取主数据(高层入口,合并 describe/get)。不传 jsonPath → 返回主数据说明 + 格式提示(含字段约束);传 jsonPath → 返回该子路径当前值 + hash;传 jsonPaths → 一次读多个不相关子路径(省多轮往返)。hash 用于乐观锁(声明 conflictWatchFields 后 write 自动比对;未声明不自动校验)。fields(字段裁剪)/depth(深度截断)减体积;offset+limit 对数组目标分页(返回切片 + total/hasMore)。",
+		description: "读主数据(只读):不传 jsonPath 返回整体说明+格式;传 jsonPath 返回该路径当前值+hash;传 jsonPaths 一次读多个不相关路径。fields/depth 裁剪、offset/limit 数组分页减体积;详细规则见系统提示。",
 		schema: B({
-			jsonPath: z().optional().describe("要读的子路径(相对主数据根,如 components.0.text);不传则读整个主数据并返回说明"),
-			jsonPaths: fu(z()).optional().describe("多路径读取:一次读多个不相关子路径(与 jsonPath 互斥,优先于 jsonPath);返回各路径值,非法路径单项标错不整批失败"),
-			fields: fu(z()).optional().describe("字段裁剪:只返回指定字段(对对象/数组元素投影),减少返回体积,如 [\"id\",\"title\"]"),
-			depth: au().int().min(0).optional().describe("嵌套深度限制:0=只根占位,1=根+子,递归到 depth 层后用 {...}/[...] 占位截断,减少深层返回体积"),
-			offset: au().int().min(0).optional().describe("数组分页起始偏移(仅当读取目标是数组时生效,默认 0),配合 limit 分页读大数组"),
-			limit: au().int().min(1).max(200).optional().describe("数组分页每页条数(默认 50,上限 200;仅数组时生效),返回切片 + total/hasMore")
+			jsonPath: z().optional().describe("要读的子路径(如 components.0.text);不传读整体+说明"),
+			jsonPaths: fu(z()).optional().describe("多路径一次读(与 jsonPath 互斥,优先);非法路径单项标错不整批"),
+			fields: fu(z()).optional().describe("只返回指定字段(投影减体积),如 [\"id\",\"title\"]"),
+			depth: au().int().min(0).optional().describe("嵌套深度限制(0=只根占位,逐层截断减体积)"),
+			offset: au().int().min(0).optional().describe("数组分页起始偏移(仅数组目标,默认 0)"),
+			limit: au().int().min(1).max(200).optional().describe("数组分页每页条数(默认 50,上限 200),返回切片+total/hasMore")
 		})
 	}), Se = WP(async ({ value: e, patch: t, patches: n, del: r, dryRun: i }, a) => {
 		let o = D(a), s = "set";
@@ -69290,9 +69301,9 @@ function Q6(e, t = {}) {
 		}
 	}, {
 		name: "write",
-		description: "写入主数据(高层入口,合并 set/edit/delete + 自动乐观锁 + 自动快照)。四意图:① 整体替换 write({value:整个对象});② 增量 write({patch:{op,jsonPath,value}}) op=set/remove/merge/append/move(move 的 value=目标路径字符串);③ 批量原子 write({patches:[...]})(任一失败整批回滚);④ 删子路径 write({patch:{jsonPath},del:true})。dryRun:true 预检不落盘。写入自动 schema 校验(失败不写,按错误修正重试)+ 自动快照。详细用法见系统提示「能力使用提示」。",
+		description: "写主数据(唯一写入口;自动 schema 校验+乐观锁+快照)。四意图:整体替换 {value}/增量 {patch:{op,jsonPath,value}}(op set/remove/merge/append/move)/原子批 {patches:[…]}(任一失败回滚)/删子路径 {patch:{jsonPath},del:true};dryRun 预检;详细规则见系统提示。",
 		schema: B({
-			value: uu().optional().describe("JSON 对象(推荐,如 {title:\"x\"})或 JSON 字符串;set 整体或单个 patch 的 set/merge/append 必填"),
+			value: uu().optional().describe("JSON 对象(推荐)或 JSON 字符串;set 整体或 patch 的 set/merge/append 必填"),
 			patch: B({
 				op: Cu([
 					"set",
@@ -69300,10 +69311,10 @@ function Q6(e, t = {}) {
 					"merge",
 					"append",
 					"move"
-				]).optional().describe("增量操作:set 设值/remove 删/merge 合并对象/append 追加数组/move 移动数组元素(value=目标路径字符串)。单 patch edit 缺省按 set;del 模式(write({patch:{jsonPath},del:true}))不读 op 可省略"),
-				jsonPath: z().optional().describe("相对主数据根的点号路径(如 components.0.text);set/remove 必填,merge/append 不填则作用于根"),
-				value: uu().optional().describe("该 patch 的值(JSON 直传或 JSON 字符串);set/merge/append 必填,remove 不需。与顶层 value 二选一:优先 patch.value,未填则回退顶层 value(向后兼容)。推荐用 patch.value(自带,与 patches 元素一致,无歧义)")
-			}).optional().describe("单个增量编辑(自带 value,与 patches 元素一致);传 patch(无 patches)走单 patch edit 语义"),
+				]).optional().describe("set 设值/remove 删/merge 合并对象/append 追加数组/move 移动元素(value=目标路径字符串);缺省 set"),
+				jsonPath: z().optional().describe("相对主数据根的点号路径(如 components.0.text);set/remove 必填,merge/append 不填作用于根"),
+				value: uu().optional().describe("该 patch 的值(JSON 或 JSON 字符串);与顶层 value 二选一,优先 patch.value")
+			}).optional().describe("单个增量编辑(自带 value)"),
 			patches: fu(B({
 				op: Cu([
 					"set",
@@ -69312,11 +69323,11 @@ function Q6(e, t = {}) {
 					"append",
 					"move"
 				]),
-				jsonPath: z().optional().describe("相对主数据根的点号路径;set/remove 必填,merge/append 不填则作用于根"),
-				value: uu().optional().describe("JSON 值(推荐直传)或 JSON 字符串;set/merge/append 必填,remove 不需")
-			})).optional().describe("批量增量编辑:一次原子应用多个 patch(任一失败则整体不写入,clone 试跑全部 + schema 校验通过才落 live)。适合一次改多处,减少多轮往返"),
+				jsonPath: z().optional().describe("相对主数据根的点号路径;set/remove 必填,merge/append 不填作用于根"),
+				value: uu().optional().describe("JSON 值(推荐直传)或 JSON 字符串;set/merge/append 必填")
+			})).optional().describe("批量原子编辑:一次提交多个 patch,任一失败整体不写入;适合一次改多处"),
 			del: su().optional().describe("true 则删除 patch.jsonPath 指定的子路径"),
-			dryRun: su().optional().describe("预检模式:走完整校验链(schema + 白名单 + patch 应用到 clone)但不落盘、不入快照,返回预览。四意图(value/patch/patches/del)均支持;乐观锁冲突照常检测(返回 VERSION_CONFLICT 不挂起)")
+			dryRun: su().optional().describe("预检:走完整校验链但不落盘不入快照;冲突返回 VERSION_CONFLICT 不挂起")
 		})
 	});
 	me(Se);
@@ -72235,7 +72246,7 @@ function Yje(e, t, n) {
 		augmentPrompt: (i) => {
 			var a;
 			let o = [];
-			if (r.planning && (o.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), o.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), o.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), o.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), o.push("  · update_todo 标 completed 时附 evidence: 本次实际写入的 jsonPath(如 \"components.2\"),供收口对账;工作经委派子 agent 完成等无主写路径时,如实写明完成方式(勿编造路径)。"), e != null && e.humanConfirm ? o.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。") : o.push("  · 规划出多步方案若需用户拍板 → 以文字列出方案选项等用户回复,勿自行拍板。"), o.push("  · 计划修订有次数上限(maxPlanRevisions,默认 5,只计 write_todos 调用、调研轮不计):勿反复改计划而不执行,规划充分后即开始 write 落地。")), t && (o.push("改主数据前先 read({jsonPath}) 读其当前真实值(返回末尾 hash=xxx 为乐观锁标识),基于真实值改,不要凭记忆。写入是否被自动校验由集成方 conflictWatchFields 声明决定:若已声明且主数据在你 read 之后被外部改过,会触发冲突——集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 read 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 read 拿最新值再改。"), o.push("不确定主数据字段结构时用 describe_data 查看说明。"), o.push("修改大对象/数组优先用 write 增量改({patch:{op,jsonPath,value}} 只发改动部分),避免 write({value}) 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), o.push("修改主数据出错时可用 restore_data 回退最近一次。"), o.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 write({patch}) 改。"), o.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), o.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), o.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), o.push("【省轮次·批量】≥2 个路径一律 read({jsonPaths:[...]}) 一次取回(路径互不相关也合批,禁止连续单路径 read);改多处用 write({patches:[{op:\"set\",jsonPath,value},...]}) 一次提交多改动(原子任一失败回滚),勿逐个 write 烧轮次预算。"), o.push("读到 <subtree Nkb keys:[…] #指纹> 或 <code Nkb> 占位 = 该子树键名/体积可见但内容未见:写入前先窄读全文(read({jsonPath:\"该子树路径\"}),结果根豁免返全文)或 set_focus 聚焦该区域;勿凭键名印象猜路径/猜值直写(直接写占位子树会被拦下要求先窄读)。"), o.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。")), r.subagent && o.push("独立子任务可 spawn_agent 委派(过程隔离,不占主上下文):默认只读,需要子 agent 写数据时传 writablePaths(路径前缀白名单,越界 PATH_OUT_OF_SCOPE)。多个独立子任务可 spawn_agents 并行委派(各子互不通信,结论由你汇总;并行委派不可授写权限,写操作由你收尾执行)。"), r.inspectEnv && o.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && o.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && (o.push("生成超大 JSON(如 50+ 组件页面,单次 write 受 max_tokens 限制装不下)用 draft_write 分块构建 → draft_commit 原子提交:draft_write({draftId, chunk, mode}) mode:\"start\" 新建/\"append\" 追加(拼 JSON 片段到 drafts 池);累积完 draft_commit({draftId}) 合并 + schema 校验 + 写主数据(失败草稿保留可修后重试,成功自动清草稿)。小改仍用 write patch,只在大 JSON 从零生成时用 draft。"), o.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=30(3.43 起;轮次预算吃紧时 system 会注入预算提示段,按提示优先收口);目标组件数很大时集成方仍可在 createChatSdk 显式上调 maxToolRounds(按 N+10 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。")), r.focus && (o.push("【上下文聚焦】判断任务范围,用 set_focus/add_focus/remove_focus/clear_focus 自动收敛工作范围:"), o.push("  · 局部任务(只改某一组件/区域,如「调导航栏」「改 components.3 样式」)→ 先 read 定位 jsonPath,再 set_focus({path:\"该子树路径\"}) 聚焦;聚焦后每轮只看该子树结构,写其他位置会被 PATH_DENIED 拒绝。"), o.push("  · 多个相关组件(如「同时改导航栏和页脚」)→ set_focus 聚焦首个后用 add_focus({path}) 追加其余;聚焦后可写任一焦点子树,越界仍被拒;移除单个用 remove_focus({path})。"), o.push("  · 全局任务(多处/整体结构,如「重排所有组件」「换主题」)→ 不要聚焦,保持全量视野直接写。"), o.push("  · 完成局部精修、要转向其他区域或做整体改动 → 调 clear_focus 退出聚焦(清空全部焦点),恢复全部读写权限。"), o.push("  · set_focus/add_focus 的 path 必须在 schema 内(类型校验);不确定路径先 read/describe_data 查。")), !(e == null || (a = e.subagents) == null) && a.length) {
+			if (r.planning && (o.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), o.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), o.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), o.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), o.push("  · update_todo 标 completed 时附 evidence: 本次实际写入的 jsonPath(如 \"components.2\"),供收口对账;工作经委派子 agent 完成等无主写路径时,如实写明完成方式(勿编造路径)。"), e != null && e.humanConfirm ? o.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。") : o.push("  · 规划出多步方案若需用户拍板 → 以文字列出方案选项等用户回复,勿自行拍板。"), o.push("  · 计划修订有次数上限(maxPlanRevisions,默认 5,只计 write_todos 调用、调研轮不计):勿反复改计划而不执行,规划充分后即开始 write 落地。")), t && (o.push("改主数据前先 read({jsonPath}) 读其当前真实值(返回末尾 hash=xxx 为乐观锁标识),基于真实值改,不要凭记忆。写入是否被自动校验由集成方 conflictWatchFields 声明决定:若已声明且主数据在你 read 之后被外部改过,会触发冲突——集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 read 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 read 拿最新值再改。"), o.push("读类分流:取值/结构 → read(多路径用 jsonPaths);字段约束 → schema_data;条件筛选定位 → query_data(多条一次用 queries);名字模糊找 → search_data;整体说明 → read 不传路径(= describe_data)。"), o.push("修改大对象/数组优先用 write 增量改({patch:{op,jsonPath,value}} 只发改动部分),避免 write({value}) 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), o.push("修改主数据出错时可用 restore_data 回退最近一次。"), o.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 write({patch}) 改。"), o.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), o.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), o.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), o.push("【省轮次·批量】≥2 个路径一律 read({jsonPaths:[...]}) 一次取回(路径互不相关也合批,禁止连续单路径 read);多条件筛选用 query_data({queries:[expr1,expr2,…]}) 一次取回(2-10 条);改多处用 write({patches:[{op:\"set\",jsonPath,value},...]}) 一次提交多改动(原子任一失败回滚),勿逐个 write 烧轮次预算。"), o.push("读到 <subtree Nkb keys:[…] #指纹> 或 <code Nkb> 占位 = 该子树键名/体积可见但内容未见:写入前先窄读全文(read({jsonPath:\"该子树路径\"}),结果根豁免返全文)或 set_focus 聚焦该区域;勿凭键名印象猜路径/猜值直写(直接写占位子树会被拦下要求先窄读)。"), o.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。")), r.subagent && o.push("独立子任务可 spawn_agent 委派(过程隔离,不占主上下文):默认只读,需要子 agent 写数据时传 writablePaths(路径前缀白名单,越界 PATH_OUT_OF_SCOPE)。多个独立子任务可 spawn_agents 并行委派(各子互不通信,结论由你汇总;并行委派不可授写权限,写操作由你收尾执行)。"), r.inspectEnv && o.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && o.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && (o.push("生成超大 JSON(如 50+ 组件页面,单次 write 受 max_tokens 限制装不下)用 draft_write 分块构建 → draft_commit 原子提交:draft_write({draftId, chunk, mode}) mode:\"start\" 新建/\"append\" 追加(拼 JSON 片段到 drafts 池);累积完 draft_commit({draftId}) 合并 + schema 校验 + 写主数据(失败草稿保留可修后重试,成功自动清草稿)。小改仍用 write patch,只在大 JSON 从零生成时用 draft。"), o.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=30(3.43 起;轮次预算吃紧时 system 会注入预算提示段,按提示优先收口);目标组件数很大时集成方仍可在 createChatSdk 显式上调 maxToolRounds(按 N+10 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。")), r.focus && (o.push("【上下文聚焦】判断任务范围,用 set_focus/add_focus/remove_focus/clear_focus 自动收敛工作范围:"), o.push("  · 局部任务(只改某一组件/区域,如「调导航栏」「改 components.3 样式」)→ 先 read 定位 jsonPath,再 set_focus({path:\"该子树路径\"}) 聚焦;聚焦后每轮只看该子树结构,写其他位置会被 PATH_DENIED 拒绝。"), o.push("  · 多个相关组件(如「同时改导航栏和页脚」)→ set_focus 聚焦首个后用 add_focus({path}) 追加其余;聚焦后可写任一焦点子树,越界仍被拒;移除单个用 remove_focus({path})。"), o.push("  · 全局任务(多处/整体结构,如「重排所有组件」「换主题」)→ 不要聚焦,保持全量视野直接写。"), o.push("  · 完成局部精修、要转向其他区域或做整体改动 → 调 clear_focus 退出聚焦(清空全部焦点),恢复全部读写权限。"), o.push("  · set_focus/add_focus 的 path 必须在 schema 内(类型校验);不确定路径先 read/describe_data 查。")), !(e == null || (a = e.subagents) == null) && a.length) {
 				let t = e.subagents.filter((e) => {
 					var t;
 					return ((t = e.temperature) == null ? 0 : t) >= Jje || /规划|创意|设计|方案|brainstorm|plan/i.test(e.description);