page-agent-sdk 4.2.2 → 4.3.0

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-3055%20asserts-brightgreen.svg)](#self-tests)
+[![tests](https://img.shields.io/badge/self%20tests-3079%20asserts-brightgreen.svg)](#self-tests)
 
 ---
 
@@ -280,6 +280,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | `i18n` | `I18nOptions` | **Top-level i18n group (3.22+; replaces `dialog.locale`/`dialog.messages`)**: `locale` switches the built-in message pack — chat surface + Debug drawer + Skill panel + CodePreview; `formatTime` (12h/24h), autoTitle, and the **default systemPrompt** follow (`en-US` → English `DEFAULT_SYSTEM_PROMPT_EN` with a "Respond in English" anchor, so agent replies match the UI language; a custom `systemPrompt` is untouched, but the auto-appended `reliableWriteRules` segment switches to English). `messages` = per-key overrides (priority over the locale pack, e.g. `statusDone: '<b style="color:#10b981">Done ✓</b>'` — values may be inline HTML fragments on rich-text render spots, sanitized via a text allowlist). Full key list (~226 keys) in `DialogMessages` |
 | `icons` | `Partial<DialogIcons>` | **Icon customization**: partial override of default emojis (`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️; `assistantAvatar`/`userAvatar`/`send` and the header-button keys `newSession`/`history`/`more`/`close` default to built-in SVG — pass emoji/char/HTML fragment to replace; history delete button `sessionDelete` defaults to ✕ text). Values: plain text (emoji/char) **or an HTML fragment** (starting with `<`, e.g. inline `<svg>`/`<img>` — sanitized via a DOMPurify icon allowlist; event attributes/dangerous protocols stripped); empty string hides the icon (button keys treat it as unset, prevents an empty button); unset keys keep defaults |
 | `headerLabels` | `boolean` · default `true` | **Adaptive header-button text labels**: when wide enough (header content ≥440px ≈ dialog ≥472px with default padding), "New chat / History / More" show text+icon; narrower widths fall back to icon-only (close stays icon-only; pure CSS container queries, old browsers gracefully degrade to icon-only); `false` = always icon-only. Button text = i18n `newSession`/`history`/`more` keys (overridable via `i18n.messages`), icons = the four same-named `dialog.icons` keys |
+| `toolStepView` | `ToolStepViewFn` | **Tool-step display mapper (pure display-layer interceptor)**: replaces raw tool names (read/write/use_html …) on the tool-call step rows with business-friendly names/content. Called on each tool-call render with `name`/`args`/`status`/`result` (map dynamically by args); return `{ title?, detail? }` or `undefined` (fall back to the raw name); mapper exceptions are safe (fall back to the raw name). Example: `toolStepView: (s) => s.name === 'write' ? { title: 'Edit page', detail: (s.args as any)?.jsonPath } : undefined`. Never affects the tool names/protocol/validation sent to the LLM; subagent steps map too; the expanded args/result detail panel stays raw |
 
 ### Extension points
 

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-3055%20asserts-brightgreen.svg)](#自测)
+[![tests](https://img.shields.io/badge/self%20tests-3079%20asserts-brightgreen.svg)](#自测)
 
 ---
 
@@ -276,6 +276,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | `i18n` | `I18nOptions` | **顶层国际化配置组(3.22+;原 `dialog.locale`/`dialog.messages` 两键合并至此)**:`locale` 切换内置文案包 —— 聊天面 + Debug 抽屉 + Skill 面板 + 代码预览;`formatTime`(12h/24h)、autoTitle 与**默认 systemPrompt** 跟随(`en-US` → 英文版 `DEFAULT_SYSTEM_PROMPT_EN` 含 "Respond in English" 语言锚,agent 回复语言与 UI 一致;自定义 `systemPrompt` 不受影响,但其自动追加的 `reliableWriteRules` 段切英文)。`messages` = 键级覆盖(优先于 locale 包,如 `statusDone: '<b style="color:#10b981">完成</b>'` —— 富文本渲染位的值支持行内 HTML 片段,文案白名单净化);完整键清单(~226 键)见 `DialogMessages` |
 | `icons` | `Partial<DialogIcons>` | **图标自定义**:局部覆盖默认 emoji(`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️;`assistantAvatar`/`userAvatar`/`send` 与顶部按钮四键 `newSession`/`history`/`more`/`close` 缺省 = 内置 SVG,传 emoji/字符/HTML 片段替换;历史删除按钮 `sessionDelete` 缺省 = ✕ 文本)。值为纯文本(emoji/字符)或 **HTML 片段**(以 `<` 开头,如内联 `<svg>`/`<img>`,经 DOMPurify 图标白名单净化,事件属性/危险协议剥除);空串 = 隐藏该图标(按钮键视为未传,防空按钮);未传键用默认 |
 | `headerLabels` | `boolean` · 默认 `true` | **顶部按钮自适应文字标签**:宽度足够(头部内容区 ≥440px,默认 padding 下 ≈ 对话框 ≥472px)时「新建会话/历史记录/更多」展示文字+图标,更窄自动回退纯图标(关闭钮恒纯图标;纯 CSS 容器查询,旧浏览器优雅降级为纯图标);`false` 恒纯图标。按钮文字走 i18n `newSession`/`history`/`more` 键(`i18n.messages` 键级覆盖生效),图标走 `dialog.icons` 同名四键 |
+| `toolStepView` | `ToolStepViewFn` | **工具步骤展示映射(纯展示层拦截器)**:把工具调用步骤行的原始工具名(read/write/use_html …)替换为业务友好名称/内容。每次工具调用渲染时调,入参含 `name`/`args`/`status`/`result`(可按 args 动态映射),返回 `{ title?, detail? }` 或 `undefined`(回退原始工具名);映射抛错安全(回退原名)。例:`toolStepView: (s) => s.name === 'write' ? { title: '修改页面', detail: (s.args as any)?.jsonPath } : undefined`。不影响发给 LLM 的工具名/协议/校验;子 agent 步骤同样应用;展开细节面板的 args/result 仍为原始数据 |
 
 ### 扩展点
 

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

@@ -186,6 +186,22 @@ var d = [
 			vision: !0
 		}
 	},
+	{
+		pattern: /qwen3(\.\d+)?-vl/i,
+		caps: {
+			contextWindow: 262144,
+			maxOutputTokens: 32768,
+			vision: !0
+		}
+	},
+	{
+		pattern: /qwen3(\.\d+)?-(max|plus|flash)/i,
+		caps: {
+			contextWindow: 262144,
+			maxOutputTokens: 32768,
+			thinking: !0
+		}
+	},
 	{
 		pattern: /qwen-max|qwen-plus/i,
 		caps: {
@@ -5202,63 +5218,70 @@ function tc(e, t) {
 	return Array.isArray(a) && Number(i) >= a.length;
 }
 function nc(e) {
-	let t = e.initialFocuses ? [...e.initialFocuses] : [], n = () => e.onChange?.([...t]), r = e.unfocusGuidance ?? "tool", i = (e) => `若你的意图是修改聚焦组件本身(如给它新增页签/子项),请改写焦点路径的子路径重试${e ? `(如 ${e})` : ""};`, a = r === "tool" ? `需改其他组件请先 remove_focus / clear_focus 或换焦点。${i()}` : r === "ask-user" ? `焦点由用户在输入框设定与移除(聚焦 chip ✕);用户要求改其他组件时,提示用户移除聚焦后重试,勿尝试写焦点外(会被拒)。${i()}` : `需改其他组件时,在收口回复中说明需先取消焦点(焦点由主会话管理),勿尝试越界写。${i()}`, o = (e) => r === "tool" ? `${i(e)}需操作焦点外组件请先 remove_focus / clear_focus 或换焦点后重试。` : r === "ask-user" ? `${i(e)}焦点由用户在输入框管理,请提示用户移除输入框中的聚焦 chip 后重试(当前模式无 focus 工具)。` : `${i(e)}请只改焦点子树;需改其他组件时,在收口回复中说明需先取消焦点。`;
+	let t = e.initialFocuses ? [...e.initialFocuses] : [], n = null, r = () => n ?? t, i = () => e.onChange?.([...t]), a = (e, r) => {
+		t = r(t), n !== null && e === "agent" && (n = r(n)), i();
+	}, o = e.unfocusGuidance ?? "tool", s = (e) => `若你的意图是修改聚焦组件本身(如给它新增页签/子项),请改写焦点路径的子路径重试${e ? `(如 ${e})` : ""};`, c = o === "tool" ? `需改其他组件请先 remove_focus / clear_focus 或换焦点。${s()}` : o === "ask-user" ? `焦点由用户在输入框设定与移除(聚焦 chip ✕);用户要求改其他组件时,提示用户移除聚焦后重试,勿尝试写焦点外(会被拒)。${s()}` : `需改其他组件时,在收口回复中说明需先取消焦点(焦点由主会话管理),勿尝试越界写。${s()}`, l = (e) => o === "tool" ? `${s(e)}需操作焦点外组件请先 remove_focus / clear_focus 或换焦点后重试。` : o === "ask-user" ? `${s(e)}焦点由用户在输入框管理,请提示用户移除输入框中的聚焦 chip 后重试(当前模式无 focus 工具)。` : `${s(e)}请只改焦点子树;需改其他组件时,在收口回复中说明需先取消焦点。`;
 	return {
 		name: "focus",
-		beforeAgent: () => t.length ? {
-			focuses: [...t],
-			focus: t[0]
-		} : {},
+		beforeAgent: () => (n = [...t], n.length ? {
+			focuses: [...n],
+			focus: n[0]
+		} : {}),
+		afterAgent: () => {
+			n = null;
+		},
 		augmentPrompt: () => {
+			let t = r();
 			if (!t.length) return;
 			let n = [
 				"## 当前精修目标",
 				t.map((e) => `· ${e.path}${e.label ? `(${e.label})` : ""}`).join("\n"),
-				`仅操作上述 ${t.length} 个聚焦子树${t.length > 1 ? "之一" : ""},用户未指明目标的指令默认作用于聚焦组件(「增加/修改/删除 X」类指令优先理解为对聚焦组件本身的改动 —— 如为其加页签/子项,写焦点路径的子路径;仅用户明确要求新建独立组件时才需解除焦点);不要改动其他组件;${a}`,
+				`仅操作上述 ${t.length} 个聚焦子树${t.length > 1 ? "之一" : ""},用户未指明目标的指令默认作用于聚焦组件(「增加/修改/删除 X」类指令优先理解为对聚焦组件本身的改动 —— 如为其加页签/子项,写焦点路径的子路径;仅用户明确要求新建独立组件时才需解除焦点);不要改动其他组件;${c}`,
 				"用户用指示代词提问(「这是啥/这个/它是干什么的」等)时,所指默认是聚焦目标 —— 先 read 聚焦子树,再围绕聚焦组件回答,勿泛答整页",
 				"read 不带路径时默认只返回聚焦子树;需要全量主数据时显式列顶层键(read({jsonPaths:[...]}) )"
-			], r = e.getSchema();
-			if (r) {
+			], i = e.getSchema();
+			if (i) {
 				let e = t.map((e) => {
-					let t = Ro(r, e.path);
+					let t = Ro(i, e.path);
 					return t ? _s(t) : null;
 				}).filter((e) => !!e);
 				e.length && n.push("", "## 焦点子树结构(仅此范围可操作)", ...e);
 			}
 			return n.join("\n");
 		},
-		wrapToolCall: async (n, r) => {
-			if (t.length) {
-				let i = t.map((e) => e.label ? `${e.path}(${e.label})` : e.path).join(", "), a = t.length === 1 ? `${t[0].path}.props.xxx` : void 0, s = (e) => ({
-					content: `PATH_DENIED · 聚焦越界:当前聚焦 [${i}],不可操作「${e}」。${o(a)}`,
+		wrapToolCall: async (t, n) => {
+			let i = r();
+			if (i.length) {
+				let r = i.map((e) => e.label ? `${e.path}(${e.label})` : e.path).join(", "), a = i.length === 1 ? `${i[0].path}.props.xxx` : void 0, o = (e) => ({
+					content: `PATH_DENIED · 聚焦越界:当前聚焦 [${r}],不可操作「${e}」。${l(a)}`,
 					status: "error"
 				});
-				if (n.name === "eval_script") {
-					if (n.args?.mode !== "transform") return r(n);
-					let i = $s(n.args);
-					if (!i.length) return s("(整体数据)");
-					for (let n of i) if (!t.some((e) => ec(n, e.path)) && !tc(n, e.getBind?.())) return s(n);
-					return r(n);
+				if (t.name === "eval_script") {
+					if (t.args?.mode !== "transform") return n(t);
+					let r = $s(t.args);
+					if (!r.length) return o("(整体数据)");
+					for (let t of r) if (!i.some((e) => ec(t, e.path)) && !tc(t, e.getBind?.())) return o(t);
+					return n(t);
 				}
-				if (Qs.has(n.name)) {
-					let r = $s(n.args);
-					if (!r.length) return s("(整体数据)");
-					for (let n of r) if (!t.some((e) => ec(n, e.path)) && !tc(n, e.getBind?.())) return s(n);
+				if (Qs.has(t.name)) {
+					let n = $s(t.args);
+					if (!n.length) return o("(整体数据)");
+					for (let t of n) if (!i.some((e) => ec(t, e.path)) && !tc(t, e.getBind?.())) return o(t);
 				}
-				if (n.name === "read") {
-					n.callConfig = {
-						...n.callConfig ?? {},
-						__pgFullTextPaths: t.map((e) => e.path)
+				if (t.name === "read") {
+					t.callConfig = {
+						...t.callConfig ?? {},
+						__pgFullTextPaths: i.map((e) => e.path)
 					};
-					let e = n.args;
+					let e = t.args;
 					if (!e?.jsonPath && !e?.jsonPaths) {
-						let i = t.map((e) => e.path), a = await r({
-							...n,
+						let r = i.map((e) => e.path), a = await n({
+							...t,
 							args: {
 								...e,
-								jsonPaths: i
+								jsonPaths: r
 							}
-						}), o = `【聚焦模式】read 未带路径 → 默认返回聚焦子树(${i.join(", ")});需要全量主数据时显式列顶层键,如 read({jsonPaths:['<顶层键1>','<顶层键2>']})\n`;
+						}), o = `【聚焦模式】read 未带路径 → 默认返回聚焦子树(${r.join(", ")});需要全量主数据时显式列顶层键,如 read({jsonPaths:['<顶层键1>','<顶层键2>']})\n`;
 						return {
 							...a,
 							content: o + a.content
@@ -5266,26 +5289,33 @@ function nc(e) {
 					}
 				}
 			}
-			return r(n);
+			return n(t);
 		},
-		setFocus: (e) => {
-			t = e ? [e] : [], n();
+		setFocus: (e, t) => {
+			a(t, () => e ? [e] : []);
 		},
 		getFocus: () => t[0],
 		getFocuses: () => [...t],
-		addFocus: (e) => {
-			let r = t.findIndex((t) => t.path === e.path);
-			r >= 0 ? t[r] = e : t.push(e), n();
+		addFocus: (e, t) => {
+			a(t, (t) => {
+				let n = t.findIndex((t) => t.path === e.path);
+				if (n >= 0) {
+					let r = [...t];
+					return r[n] = e, r;
+				}
+				return [...t, e];
+			});
 		},
-		removeFocus: (e) => {
-			t = t.filter((t) => t.path !== e), n();
+		removeFocus: (e, t) => {
+			a(t, (t) => t.filter((t) => t.path !== e));
 		},
-		clearFocus: () => {
-			t = [], n();
+		clearFocus: (e) => {
+			a(e, () => []);
 		},
 		reset: () => {
-			t = [], n();
-		}
+			t = [], n = null, i();
+		},
+		isInvokeActive: () => n !== null
 	};
 }
 //#endregion
@@ -12330,7 +12360,7 @@ function am(e, n) {
 		return n ? Ro(n, e) ? (A.setFocus({
 			path: e,
 			...t ? { label: t } : {}
-		}), `已聚焦到 ${e}${t ? `(${t})` : ""}。后续仅可写该子树(越界被拒),每轮只看到该组件结构。完成精修后调 clear_focus 退出。`) : `PATH_DENIED · 聚焦失败:path "${e}" 不在 schema 内。请先用 read 查看可操作路径再聚焦。` : "聚焦失败:当前无主数据 schema,无法聚焦。";
+		}, "agent"), `已聚焦到 ${e}${t ? `(${t})` : ""}。后续仅可写该子树(越界被拒),每轮只看到该组件结构。完成精修后调 clear_focus 退出。`) : `PATH_DENIED · 聚焦失败:path "${e}" 不在 schema 内。请先用 read 查看可操作路径再聚焦。` : "聚焦失败:当前无主数据 schema,无法聚焦。";
 	}, {
 		name: "set_focus",
 		description: "聚焦到指定组件子树(如 components.3)精修,替换全部已有焦点(非累积;要保留已有焦点追加用 add_focus)。聚焦后:仅可写该子树(越界 PATH_DENIED)+ 每轮只看到该组件结构。多组件页面精修其中一个时用,避免改到别处。先 read 定位 path 再聚焦;完成调 clear_focus。",
@@ -12338,7 +12368,7 @@ function am(e, n) {
 			path: t.string().describe("要聚焦的组件 jsonPath,如 components.3"),
 			label: t.string().optional().describe("人类可读标签,如「导航栏」")
 		})
-	}), je = r(async () => (A.clearFocus(), "已清除聚焦,恢复全量可操作范围(可读写所有组件)。"), {
+	}), je = r(async () => (A.clearFocus("agent"), "已清除聚焦,恢复全量可操作范围(可读写所有组件)。"), {
 		name: "clear_focus",
 		description: "清除当前聚焦,退出精修模式,恢复对全部组件的读写权限。",
 		schema: t.object({}).optional()
@@ -12349,7 +12379,7 @@ function am(e, n) {
 		A.addFocus({
 			path: e,
 			...t ? { label: t } : {}
-		});
+		}, "agent");
 		let r = A.getFocuses();
 		return `已聚焦 ${e}${t ? `(${t})` : ""}(当前共 ${r.length} 个焦点:${r.map((e) => e.path).join(", ")})。后续仅可写这些子树之一(越界被拒)。`;
 	}, {
@@ -12361,7 +12391,7 @@ function am(e, n) {
 		})
 	}), Ne = r(async ({ path: e }) => {
 		let t = A.getFocuses().length;
-		A.removeFocus(e);
+		A.removeFocus(e, "agent");
 		let n = A.getFocuses();
 		return n.length === t ? `path "${e}" 不在当前焦点列表中(当前:${n.map((e) => e.path).join(", ") || "无"})。` : n.length ? `已移除焦点 ${e}(剩余 ${n.length} 个:${n.map((e) => e.path).join(", ")})。` : `已移除焦点 ${e},聚焦已清空,恢复全量操作范围。`;
 	}, {
@@ -13188,14 +13218,14 @@ function am(e, n) {
 		},
 		setFocus(t) {
 			let n = im(t, "setFocus", ke, () => U()?.schema, e.debug);
-			return n.ok ? (A.setFocus(t), X.infoTick.value++, { ok: !0 }) : n;
+			return n.ok ? (A.setFocus(t), e.debug && A.isInvokeActive() && console.info("[page-agent-sdk][focus] 在途流程进行中,聚焦将在下一次输入生效(当前流程不受影响)"), X.infoTick.value++, { ok: !0 }) : n;
 		},
 		addFocus(t) {
 			let n = im(t, "addFocus", ke, () => U()?.schema, e.debug);
 			return n.ok ? A.getFocuses().length >= 8 ? (e.debug && console.warn("[page-agent-sdk][focus] addFocus 拒绝:焦点数已达上限 8(augmentPrompt 注入每焦点子树 schema,过多致 system prompt 超预算)"), {
 				ok: !1,
 				error: "焦点数上限 8(避免 system prompt 撑爆)"
-			}) : (A.addFocus(t), X.infoTick.value++, { ok: !0 }) : n;
+			}) : (A.addFocus(t), e.debug && A.isInvokeActive() && console.info("[page-agent-sdk][focus] 在途流程进行中,聚焦将在下一次输入生效(当前流程不受影响)"), X.infoTick.value++, { ok: !0 }) : n;
 		},
 		removeFocus(e) {
 			ke && (A.removeFocus(e), X.infoTick.value++);
@@ -13938,8 +13968,8 @@ function hm(e = {}) {
 			await r?.(s.messages);
 		} catch {}
 		s.loading = !1, u = null;
-		let e = d.value.shift();
-		e !== void 0 && (g("user", e), s.loading = !0, s.error = null, u = new AbortController(), await _(u.signal));
+		let t = d.value.shift();
+		t !== void 0 && (g("user", t, e.getFocuses?.()), s.loading = !0, s.error = null, u = new AbortController(), await _(u.signal));
 	}
 	function b(e) {
 		d.value.splice(e, 1);
@@ -14078,7 +14108,7 @@ var vm = {
 	copyThinkingTruncTitle: "复制完整思考(渲染已截尾,复制取全量)",
 	focusChipTitlePrefix: "精修中:",
 	focusChipTitleHint: "(点击回看 · ✕ 移除)",
-	historyFocusChipTitlePrefix: "回看 ",
+	historyFocusChipTitlePrefix: "发送时聚焦(路径可能已变):",
 	removeFocus: "移除此焦点",
 	sendHint: "Enter 发送 · Shift+Enter 换行",
 	sendTitle: "发送",
@@ -14304,7 +14334,7 @@ var vm = {
 		copyThinkingTruncTitle: "Copy full reasoning (display truncated, copy gets all)",
 		focusChipTitlePrefix: "Focus:",
 		focusChipTitleHint: "(click to view · ✕ remove)",
-		historyFocusChipTitlePrefix: "View ",
+		historyFocusChipTitlePrefix: "Focused at send (path may have changed): ",
 		removeFocus: "Remove this focus",
 		sendHint: "Enter to send · Shift+Enter for newline",
 		sendTitle: "Send",
@@ -14508,7 +14538,8 @@ function Sm(e = {}) {
 		onPersist: e.onPersist,
 		onClear: e.onClear,
 		onQueuedCleared: e.onQueuedCleared,
-		onBeforeRegenerate: e.onBeforeRegenerate
+		onBeforeRegenerate: e.onBeforeRegenerate,
+		getFocuses: e.getFocuses
 	}), { state: n, sendMessage: r, removeQueuedTask: i, queuedTasks: a } = t, o = /* @__PURE__ */ Lt(""), s = /* @__PURE__ */ Lt(!0), c = () => {
 		s.value = !s.value;
 	}, l = /* @__PURE__ */ Lt(!1), u = () => {
@@ -14622,7 +14653,8 @@ function Sm(e = {}) {
 		focusChipClick: F,
 		icons: I,
 		locale: ae,
-		messages: oe
+		messages: oe,
+		toolStepView: e.toolStepView
 	};
 }
 function Cm() {