page-agent-sdk 2.30.0 → 2.31.0

package/dist/page-agent-sdk.js

@@ -16481,7 +16481,7 @@ function ub(e, t) {
 	return e === t || e.startsWith(t + ".");
 }
 function db(e) {
-	let t;
+	let t = e.initialFocus;
 	return {
 		name: "focus",
 		beforeAgent: () => t ? { focus: t } : {},
@@ -17253,15 +17253,18 @@ async function cx(e, t, n, r, i) {
 	let u = a + 1 < o ? [lx({
 		...t,
 		depth: a + 1
-	})] : [], d = iy({
+	})] : [], d = t.getFocus?.(), f = d ? db({
+		getSchema: t.getSchema ?? (() => null),
+		initialFocus: d
+	}) : void 0, p = iy({
 		model: Qb(t.llm) ? t.llm.model ?? t.llm.modelName : e.model ?? t.llm.model,
 		contextWindow: t.llm.contextWindow,
 		maxOutputTokens: t.llm.maxOutputTokens
 	});
-	if (d.contextWindow < 2e5) throw Error(`[page-agent-sdk][subagent] 子 agent 模型上下文窗口 ${d.contextWindow} 小于最小支持 ${ry}(需 ≥200K 窗口模型)`);
-	let f = ky({
-		contextWindow: d.contextWindow,
-		maxOutputTokens: d.maxOutputTokens,
+	if (p.contextWindow < 2e5) throw Error(`[page-agent-sdk][subagent] 子 agent 模型上下文窗口 ${p.contextWindow} 小于最小支持 ${ry}(需 ≥200K 窗口模型)`);
+	let m = ky({
+		contextWindow: p.contextWindow,
+		maxOutputTokens: p.maxOutputTokens,
 		...Qb(t.llm) ? { llm: t.llm } : {
 			apiKey: t.llm.apiKey,
 			baseUrl: t.llm.baseUrl,
@@ -17271,12 +17274,16 @@ async function cx(e, t, n, r, i) {
 		},
 		systemPrompt: e.role?.trim() || t.systemPrompt || "你是一个专注的子任务执行者。你只有只读工具(读主数据 / 抓文档),用它们完成给定任务,给出简洁结论,不要展开多余解释。",
 		tools: l,
-		middleware: [...t.skills?.length ? [jb(t.skills)] : [], ...u],
+		middleware: [
+			...t.skills?.length ? [jb(t.skills)] : [],
+			...u,
+			...f ? [f] : []
+		],
 		maxToolRounds: t.maxToolRounds ?? nx,
 		onLog: i,
 		debug: t.debug
 	});
-	return t.debug && console.log(`[subagent] 启动子 agent(depth=${a},工具 ${l.length} 个)`), f.stream([{
+	return t.debug && console.log(`[subagent] 启动子 agent(depth=${a},工具 ${l.length} 个)`), m.stream([{
 		role: "user",
 		content: e.prompt,
 		timestamp: Date.now()
@@ -17353,7 +17360,9 @@ function dx(e, t) {
 		extraTools: n.length ? n : void 0,
 		maxToolRounds: e.maxToolRounds,
 		debug: t.debug,
-		...e.writablePaths?.length ? { writablePaths: e.writablePaths } : {}
+		...e.writablePaths?.length ? { writablePaths: e.writablePaths } : {},
+		...t.getFocus ? { getFocus: t.getFocus } : {},
+		...t.getSchema ? { getSchema: t.getSchema } : {}
 	};
 }
 function fx(e, n) {
@@ -18195,7 +18204,8 @@ var fS = "chat-sdk", pS = 50 * 1024 * 1024, mS = 4 * 1024 * 1024, hS = 10 * 1024
 	"checkpoints",
 	"usage",
 	"mission",
-	"workingMemory"
+	"workingMemory",
+	"focus"
 ];
 function SS(e) {
 	return e === "local" || e === "session" ? mS : pS;
@@ -20869,7 +20879,7 @@ function mw(e, t, n = "simple") {
 		name: "usageHints",
 		augmentPrompt: () => {
 			let n = [];
-			if (r.planning && (n.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), n.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), n.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), n.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), n.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。"), n.push("  · 规划阶段有轮次预算(maxPlanRevisions,默认 5):勿反复调研/改计划而不执行,规划充分后即开始 write 落地。")), t && (i ? (n.push("读写主数据用 read/write(高层入口,自动乐观锁 + 自动快照)。read({jsonPath}) 读子路径当前值(返回含 hash,write 时自动比对,无需手动传);read() 不传读整个主数据 + 说明。write 改值两姿势:① 改单个字段/子路径用 write({patch:{op:\"set\", jsonPath:\"路径.字段\", value:新值}})——patch.value 就是该字段的新值(类型匹配:string 直传字符串、number 传数字、对象传对象),不要包成 {字段:值} 对象(字段名已在 jsonPath);也兼容 write({value:新值, patch:{op,jsonPath}}) 顶层 value(向后兼容,但优先 patch.value,避免与整体 set 的 value 混淆);② 替换整个对象用 write({value:{整个新对象}})。op:set 设值 / remove 删 / merge 合并对象 / append 追加数组;批量多改动 write({patches:[{op,jsonPath,value},...]});删子路径 write({patch:{jsonPath:\"路径\"}, del:true})。写入自动经 schema 校验(失败不写,按错误提示改值类型/形状后重试)+ 自动存快照(出错可用 restore_data 回退)。"), n.push("修改大对象/数组优先用 write 的 patch 增量(只发改动部分),避免整体重传被 max_tokens 截断致 JSON 不完整。"), n.push("读大数组(read 返回 hasMore=true)用 read({jsonPath,offset,limit}) 分页(offset+=limit 续读,默认 limit=50);一次读多个不相关子路径用 read({jsonPaths:[...]}) 省轮次;复杂 patches 改动先 write({patches,dryRun:true}) 预检(走完整校验不落盘)。"), n.push("read/describe 返回按 schema 投影:仅 schema 声明的字段可见(未声明字段自动隐藏,防误操作);要操作某字段需集成方在 schema 声明,查任意路径完整约束用 schema_data({jsonPath})。"), n.push("查历史快照值(看上一版长啥样 / 冲突诊断 / 用户问\"刚才改了啥\")用 history_data({id?,jsonPath?})(只读不改当前);对比当前与历史快照的差异需切 advanced 用 diff_data(返回结构化 path→from/to)。"), n.push("在大数组里按条件筛选用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素 path/index;定位后用 write patch 改。找名字记不清的元素用 search_data(substring/regex/fuzzy)。批量过滤/映射/聚合/重写大数组用 eval_script(沙箱脚本,mode=query 只读/transform 落地)。")) : (n.push("改主数据前先 get_data({jsonPath}) 读其当前真实值与 hash(返回末尾 hash=xxx),基于真实值改,不要凭记忆。写入(set/edit/delete)时回传 expectedHash=该 hash 启用乐观锁——若主数据在你 get 之后被外部代码/其他 agent/用户手动改过,会触发冲突:集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 get 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 get 拿最新值与 hash 再改。"), n.push("不确定主数据字段结构时用 describe_data 查看说明。"), n.push("修改大对象/数组优先用 edit_data 增量 patch(只发改动部分),避免 set_data 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), n.push("修改主数据出错时可用 restore_data 回退最近一次。"), n.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 edit_data 改。"), n.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), n.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), n.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), n.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。"))), r.subagent && n.push("独立子任务可 spawn_agent 委派(只读工具,过程不占主上下文)。"), r.inspectEnv && n.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && n.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && n.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。"), r.draftWrite && n.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=10 可能触顶被 while 截断导致草稿写不完;目标组件数大时集成方应在 createChatSdk 配 maxToolRounds ≥ 20(或按 N+5 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。"), r.todoDeps && n.push("复杂任务可用 todos 层级依赖:write_todos 时给 todo 传 parentId(父任务 id,表达层级)+ deps(依赖的 todo id 数组,必须先完成)。有依赖的任务,deps 全 completed 后再标 in_progress;完成时 update_todo({id, status:\"completed\", evidence:\"完成证据\"}) 记证据。无依赖关系的任务不传 parentId/deps(扁平)。"), e?.subagents?.length) {
+			if (r.planning && (n.push("【自适应规划】按任务复杂度决定是否先规划,不要对简单任务过度编排:"), n.push("  · 简单/明确任务(改单字段、调样式、查值)→ 直接 read/write 执行,不必 write_todos。"), n.push("  · 复杂任务(多步、大改、有歧义、不可逆)→ 先 write_todos 拆解,首个任务标 in_progress,逐项推进。"), n.push("  · 执行中发现步骤要改/补/细分 → 用 update_todo({id, content?, status?}) 按 id 增量改单项,不必重传整个清单。"), n.push("  · 规划出多步方案若需用户拍板 → 先 request_human_confirmation 给方案选项,确认后再执行。"), n.push("  · 规划阶段有轮次预算(maxPlanRevisions,默认 5):勿反复调研/改计划而不执行,规划充分后即开始 write 落地。")), t && (i ? (n.push("读写主数据用 read/write(高层入口,自动乐观锁 + 自动快照)。read({jsonPath}) 读子路径当前值(返回含 hash,write 时自动比对,无需手动传);read() 不传读整个主数据 + 说明。write 改值两姿势:① 改单个字段/子路径用 write({patch:{op:\"set\", jsonPath:\"路径.字段\", value:新值}})——patch.value 就是该字段的新值(类型匹配:string 直传字符串、number 传数字、对象传对象),不要包成 {字段:值} 对象(字段名已在 jsonPath);也兼容 write({value:新值, patch:{op,jsonPath}}) 顶层 value(向后兼容,但优先 patch.value,避免与整体 set 的 value 混淆);② 替换整个对象用 write({value:{整个新对象}})。op:set 设值 / remove 删 / merge 合并对象 / append 追加数组;批量多改动 write({patches:[{op,jsonPath,value},...]});删子路径 write({patch:{jsonPath:\"路径\"}, del:true})。写入自动经 schema 校验(失败不写,按错误提示改值类型/形状后重试)+ 自动存快照(出错可用 restore_data 回退)。"), n.push("修改大对象/数组优先用 write 的 patch 增量(只发改动部分),避免整体重传被 max_tokens 截断致 JSON 不完整。"), n.push("读大数组(read 返回 hasMore=true)用 read({jsonPath,offset,limit}) 分页(offset+=limit 续读,默认 limit=50);一次读多个不相关子路径用 read({jsonPaths:[...]}) 省轮次;复杂 patches 改动先 write({patches,dryRun:true}) 预检(走完整校验不落盘)。"), n.push("read/describe 返回按 schema 投影:仅 schema 声明的字段可见(未声明字段自动隐藏,防误操作);要操作某字段需集成方在 schema 声明,查任意路径完整约束用 schema_data({jsonPath})。"), n.push("查历史快照值(看上一版长啥样 / 冲突诊断 / 用户问\"刚才改了啥\")用 history_data({id?,jsonPath?})(只读不改当前);对比当前与历史快照的差异需切 advanced 用 diff_data(返回结构化 path→from/to)。"), n.push("在大数组里按条件筛选用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素 path/index;定位后用 write patch 改。找名字记不清的元素用 search_data(substring/regex/fuzzy)。批量过滤/映射/聚合/重写大数组用 eval_script(沙箱脚本,mode=query 只读/transform 落地)。")) : (n.push("改主数据前先 get_data({jsonPath}) 读其当前真实值与 hash(返回末尾 hash=xxx),基于真实值改,不要凭记忆。写入(set/edit/delete)时回传 expectedHash=该 hash 启用乐观锁——若主数据在你 get 之后被外部代码/其他 agent/用户手动改过,会触发冲突:集成方若开启人工介入,工具会挂起等用户决定(保留外部/强制覆盖/回退),你应等待工具返回后按结果继续(保留外部→重新 get 再改;强制覆盖→已写入,继续;回退→已回退到历史快照,基于回退值重写);未开启人工介入时返回 VERSION_CONFLICT 不写入,重新 get 拿最新值与 hash 再改。"), n.push("不确定主数据字段结构时用 describe_data 查看说明。"), n.push("修改大对象/数组优先用 edit_data 增量 patch(只发改动部分),避免 set_data 整体重传被 max_tokens 截断导致 JSON 不完整、校验失败。"), n.push("修改主数据出错时可用 restore_data 回退最近一次。"), n.push("在大数组里按条件筛选元素用 query_data(JSONPath,如 $.components[?(@.type==\"card\" && @.price<100)]),返回匹配元素的 path/index;定位后再 edit_data 改。"), n.push("找名字记不清的元素用 search_data(支持 substring/regex/fuzzy 模糊搜索)。"), n.push("需要过滤/映射/聚合/批量重写大数组时用 eval_script(沙箱脚本,入参 data);只读探查用 mode=query,批量重写用 mode=transform(返回值经校验后落地)。"), n.push("读大数组用 read({jsonPath,offset,limit}) 分页(返回 hasMore=true 时 offset+=limit 续读);一次读多个不相关子路径用 read({jsonPaths});复杂改动先 write({...,dryRun:true}) 预检不落盘。"), n.push("对比当前与历史快照(或一段 JSON against)的差异用 diff_data({snapshotId?,against?})(返回结构化 path→from/to,verify 自纠/操作审计/\"刚才改了啥\");只读查历史快照值用 history_data({id?,jsonPath?})。"))), r.subagent && n.push("独立子任务可 spawn_agent 委派(只读工具,过程不占主上下文)。"), r.inspectEnv && n.push("排查页面环境(当前 URL/浏览器/视口/集成方调试变量)用 inspect_env——不传参返回环境摘要(location/navigator/viewport/document),传 key 读特定 window 属性(如 inspect_env({key:\"appConfig\"}) 读 window.appConfig)。改完数据看渲染、定位\"为何没生效\"时用它(只读,不改数据)。"), r.domInspect && n.push("改完数据想确认渲染是否生效(或定位元素/辅助 UI 设计问答)用 get_dom({selector?,depth?}) 读渲染后 DOM(结构化返回 tag/attrs/text/children,depth 控制深度防爆炸,只读)。配合宿主 actions(save_draft/publish 等)形成\"改数据→get_dom 看渲染→触发动作\"闭环。"), r.draftWrite && n.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。"), r.draftWrite && n.push("⚠️ 大 JSON 分块构建是典型多轮工具调用(draft_write×N + draft_commit + read 确认 + 调研 read/query),默认 maxToolRounds=10 可能触顶被 while 截断导致草稿写不完;目标组件数大时集成方应在 createChatSdk 配 maxToolRounds ≥ 20(或按 N+5 估算)。draft_commit 提交同样走乐观锁(改前 read 拿 hash,bind 被改过会触发冲突介入,不静默覆盖)。"), r.todoDeps && n.push("复杂任务可用 todos 层级依赖:write_todos 时给 todo 传 parentId(父任务 id,表达层级)+ deps(依赖的 todo id 数组,必须先完成)。有依赖的任务,deps 全 completed 后再标 in_progress;完成时 update_todo({id, status:\"completed\", evidence:\"完成证据\"}) 记证据。无依赖关系的任务不传 parentId/deps(扁平)。"), r.focus && !i && (n.push("【上下文聚焦】判断任务范围,用 set_focus/clear_focus 自动收敛工作范围:"), n.push("  · 局部任务(只改某一组件/区域,如「调导航栏」「改 components.3 样式」)→ 先 read 定位 jsonPath,再 set_focus({path:\"该子树路径\"}) 聚焦;聚焦后每轮只看该子树结构,写其他位置会被 PATH_DENIED 拒绝。"), n.push("  · 全局任务(多处/整体结构,如「重排所有组件」「换主题」)→ 不要聚焦,保持全量视野直接写。"), n.push("  · 完成局部精修、要转向其他区域或做整体改动 → 调 clear_focus 退出聚焦,恢复全部读写权限。"), n.push("  · set_focus 的 path 必须在 schema 内(类型校验);不确定路径先 read/describe_data 查。")), e?.subagents?.length) {
 				let t = e.subagents.filter((e) => (e.temperature ?? 0) >= pw || /规划|创意|设计|方案|brainstorm|plan/i.test(e.description)), r = e.subagents.filter((e) => (e.temperature ?? 0) < pw && /反思|审查|挑刺|校验|review|critique|reflect/i.test(e.description));
 				n.push("【规划-反思-执行·路由】按任务性质选模式,不要对简单任务过度编排:"), t.length && (n.push(`  · 创作/设计/开放性需求(如"设计主题风格""换个感觉")→ 先调 ${t.map((e) => "use_" + e.id).join("/")} 出 2-3 套方案(高温创意),`), n.push("    不要自己拍板;拿到方案后,若需用户拍板用 request_human_confirmation 弹选项。")), r.length && n.push(`  · 严谨/易错/校验类 → 可先调 ${r.map((e) => "use_" + e.id).join("/")} 反思挑刺(低温审查),据反馈修订。`), n.push(i ? "  · 方案定稿后,由你(主 agent)用 write 落地成 JSON(低温度执行 + schema 校验 + 写前确认)。" : "  · 方案定稿后,由你(主 agent)用 edit_data 落地成 JSON(低温度执行 + schema 校验 + 写前确认)。"), n.push("  · 简单/明确任务(如\"标题改红色\")直接执行,不必走规划-反思。");
 			}
@@ -21137,11 +21147,15 @@ function Ow(e, n) {
 		skills: Ee?.skills,
 		maxDepth: Ee?.maxDepth,
 		maxParallel: Ee?.maxParallel,
-		debug: e.debug
+		debug: e.debug,
+		getFocus: () => C.getFocus(),
+		getSchema: () => L()?.schema ?? null
 	}), ke = Se && e.subagents !== void 0 ? fx(e.subagents, {
 		llm: e.llm,
 		allTools: () => H,
-		debug: e.debug
+		debug: e.debug,
+		getFocus: () => C.getFocus(),
+		getSchema: () => L()?.schema ?? null
 	}) : void 0, Ae = ke ? ke.controller : null, je = [
 		"get_data",
 		"describe_data",
@@ -21298,7 +21312,11 @@ function Ow(e, n) {
 			H = me(), W.agent && W.agent.setTools(H);
 		},
 		applySnapshot(t) {
-			t.messages?.length && _.push(...t.messages), t.vfs && v.hydrate && v.hydrate(t.vfs), t.todos?.length && y.reset(t.todos), t.memory && !e.memory && T.reset(t.memory), t.checkpoints?.length && k && k.importStack(t.checkpoints), t.usage && Object.assign(i, t.usage), t.mission && ge && S.setMission(t.mission), t.workingMemory && _e && w.restore(t.workingMemory), tt();
+			if (t.messages?.length && _.push(...t.messages), t.vfs && v.hydrate && v.hydrate(t.vfs), t.todos?.length && y.reset(t.todos), t.memory && !e.memory && T.reset(t.memory), t.checkpoints?.length && k && k.importStack(t.checkpoints), t.usage && Object.assign(i, t.usage), t.mission && ge && S.setMission(t.mission), t.workingMemory && _e && w.restore(t.workingMemory), t.focus && le) {
+				let n = L()?.schema;
+				n && Ny(n, t.focus.path) ? C.setFocus(t.focus) : e.debug && console.warn("[page-agent-sdk][focus] 恢复的焦点 path 已失效(schema 变化/无 schema),丢弃:", t.focus.path);
+			}
+			tt();
 		},
 		addSkill(e) {
 			let t = Ve.findIndex((t) => t.name === e.name);
@@ -21439,6 +21457,10 @@ function Ow(e, n) {
 					let e = w.getWorkingMemory();
 					e && s.save(n, W.sessionId, { workingMemory: e });
 				}
+				if (le) {
+					let e = C.getFocus();
+					s.save(n, W.sessionId, { focus: e ?? null });
+				}
 			}
 			v.flush?.(), await s.flush();
 			let r = t ?? "", i;
@@ -21717,6 +21739,10 @@ function Ow(e, n) {
 			let e = w.getWorkingMemory();
 			e && s.save(n, W.sessionId, { workingMemory: e });
 		}
+		if (le) {
+			let e = C.getFocus();
+			s.save(n, W.sessionId, { focus: e ?? null });
+		}
 		P && k && (s.save(n, W.sessionId, { checkpoints: k.exportStack() }), s.save(n, W.sessionId, { usage: i }));
 		let a = iS(_);
 		a && a !== rt && (rt = a, s.updateTitle(n, W.sessionId, a)), e.autoTitle !== !1 && u && !it && _.some((e) => e.role === "user") && _.some((e) => e.role === "assistant") && (it = !0, (async () => {