@opentiny/next-sdk 0.3.3 → 0.4.1

package/page-tools/page-agent-mask/SimulatorMask.ts

@@ -0,0 +1,279 @@
+import { Motion } from 'ai-motion'
+
+import { isPageDark } from './checkDarkMode'
+
+const injectStyles = `
+.webmcp-page-agent-cursor {
+	position: absolute;
+	width: var(--cursor-size, 75px);
+	height: var(--cursor-size, 75px);
+	pointer-events: none;
+	z-index: 10000;
+}
+
+.webmcp-page-agent-cursorBorder {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
+	mask-image: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%20fill='none'%3e%3cg%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='none'%20stroke='%23000000'%20stroke-width='6'%20stroke-miterlimit='10'%20style='stroke:%20light-dark(rgb(0,%200,%200),%20rgb(255,%20255,%20255));'/%3e%3c/g%3e%3c/svg%3e");
+	mask-size: 100% 100%;
+	mask-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-90deg) scale(0.8);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.webmcp-page-agent-cursorFilling {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%3e%3cdefs%3e%3c/defs%3e%3cg%20xmlns='http://www.w3.org/2000/svg'%20style='filter:%20drop-shadow(light-dark(rgba(0,%200,%200,%200.4),%20rgba(237,%20237,%20237,%200.4))%203px%204px%204px);'%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='%23ffffff'%20stroke='none'%20style='fill:%20%23ffffff;'/%3e%3c/g%3e%3c/svg%3e");
+	background-size: 100% 100%;
+	background-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-90deg) scale(0.8);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.webmcp-page-agent-cursorRipple {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	pointer-events: none;
+	margin-left: -50%;
+	margin-top: -50%;
+
+	&::after {
+		content: '';
+		opacity: 0;
+		position: absolute;
+		inset: 0;
+		border: 4px solid rgba(57, 182, 255, 1);
+		border-radius: 50%;
+	}
+}
+
+.webmcp-page-agent-cursor.clicking .webmcp-page-agent-cursorRipple::after {
+	animation: webmcp-page-agent-cursor-ripple 300ms ease-out forwards;
+}
+
+@keyframes webmcp-page-agent-cursor-ripple {
+	0% {
+		transform: scale(0);
+		opacity: 1;
+	}
+
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}
+
+.webmcp-page-agent-wrapper {
+	position: fixed;
+	inset: 0;
+	z-index: 2147483641;
+	/* 确保在所有元素之上，除了 panel */
+	cursor: wait;
+	overflow: hidden;
+
+	display: none;
+}
+
+.webmcp-page-agent-wrapper.visible {
+	display: block;
+}
+`
+
+export class SimulatorMask extends EventTarget {
+  shown: boolean = false
+  wrapper = document.createElement('div')
+  motion: Motion | null = null
+
+  #disposed = false
+
+  #cursor = document.createElement('div')
+
+  #currentCursorX = 0
+  #currentCursorY = 0
+
+  #targetCursorX = 0
+  #targetCursorY = 0
+
+  constructor() {
+    super()
+    // 注入样式，防止打包失败
+    document.head.appendChild(document.createElement('style')).textContent = injectStyles
+    this.wrapper.id = 'page-agent-runtime_simulator-mask'
+    this.wrapper.className = 'webmcp-page-agent-wrapper'
+    this.wrapper.setAttribute('data-browser-use-ignore', 'true')
+    this.wrapper.setAttribute('data-page-agent-ignore', 'true')
+
+    try {
+      const motion = new Motion({
+        mode: isPageDark() ? 'dark' : 'light',
+        styles: { position: 'absolute', inset: '0' }
+      })
+      this.motion = motion
+      this.wrapper.appendChild(motion.element)
+      motion.autoResize(this.wrapper)
+    } catch (e) {
+      console.warn('[SimulatorMask] Motion overlay unavailable:', e)
+    }
+
+    const stopEvent = (e: Event) => {
+      e.stopPropagation()
+      e.preventDefault()
+    }
+    ;['click', 'mousedown', 'mouseup', 'mousemove', 'wheel', 'keydown', 'keyup'].forEach((eventName) =>
+      this.wrapper.addEventListener(eventName, stopEvent)
+    )
+    // Create AI cursor
+    this.#createCursor()
+    // this.show()
+
+    document.body.appendChild(this.wrapper)
+
+    this.#moveCursorToTarget()
+
+    // global events
+    // @note Mask should be isolated from the rest of the code.
+    // Global events are easier to manage and cleanup.
+
+    const movePointerToListener = (event: Event) => {
+      const { x, y } = (event as CustomEvent).detail
+      this.setCursorPosition(x, y)
+    }
+    const clickPointerListener = () => {
+      this.triggerClickAnimation()
+    }
+    const enablePassThroughListener = () => {
+      this.wrapper.style.pointerEvents = 'none'
+    }
+    const disablePassThroughListener = () => {
+      this.wrapper.style.pointerEvents = 'auto'
+    }
+
+    window.addEventListener('PageAgent::MovePointerTo', movePointerToListener)
+    window.addEventListener('PageAgent::ClickPointer', clickPointerListener)
+    window.addEventListener('PageAgent::EnablePassThrough', enablePassThroughListener)
+    window.addEventListener('PageAgent::DisablePassThrough', disablePassThroughListener)
+
+    this.addEventListener('dispose', () => {
+      window.removeEventListener('PageAgent::MovePointerTo', movePointerToListener)
+      window.removeEventListener('PageAgent::ClickPointer', clickPointerListener)
+      window.removeEventListener('PageAgent::EnablePassThrough', enablePassThroughListener)
+      window.removeEventListener('PageAgent::DisablePassThrough', disablePassThroughListener)
+    })
+  }
+
+  #createCursor() {
+    this.#cursor.className = 'webmcp-page-agent-cursor'
+
+    // Create ripple effect container
+    const rippleContainer = document.createElement('div')
+    rippleContainer.className = 'webmcp-page-agent-cursorRipple'
+    this.#cursor.appendChild(rippleContainer)
+
+    // Create filling layer
+    const fillingLayer = document.createElement('div')
+    fillingLayer.className = 'webmcp-page-agent-cursorFilling'
+    this.#cursor.appendChild(fillingLayer)
+
+    // Create border layer
+    const borderLayer = document.createElement('div')
+    borderLayer.className = 'webmcp-page-agent-cursorBorder'
+    this.#cursor.appendChild(borderLayer)
+
+    this.wrapper.appendChild(this.#cursor)
+  }
+
+  #moveCursorToTarget() {
+    if (this.#disposed) return
+
+    const newX = this.#currentCursorX + (this.#targetCursorX - this.#currentCursorX) * 0.2
+    const newY = this.#currentCursorY + (this.#targetCursorY - this.#currentCursorY) * 0.2
+
+    const xDistance = Math.abs(newX - this.#targetCursorX)
+    if (xDistance > 0) {
+      if (xDistance < 2) {
+        this.#currentCursorX = this.#targetCursorX
+      } else {
+        this.#currentCursorX = newX
+      }
+      this.#cursor.style.left = `${this.#currentCursorX}px`
+    }
+
+    const yDistance = Math.abs(newY - this.#targetCursorY)
+    if (yDistance > 0) {
+      if (yDistance < 2) {
+        this.#currentCursorY = this.#targetCursorY
+      } else {
+        this.#currentCursorY = newY
+      }
+      this.#cursor.style.top = `${this.#currentCursorY}px`
+    }
+
+    requestAnimationFrame(() => this.#moveCursorToTarget())
+  }
+
+  setCursorPosition(x: number, y: number) {
+    if (this.#disposed) return
+
+    this.#targetCursorX = x
+    this.#targetCursorY = y
+  }
+
+  triggerClickAnimation() {
+    if (this.#disposed) return
+
+    this.#cursor.classList.remove('clicking')
+    // Force reflow to restart animation
+    void this.#cursor.offsetHeight
+    this.#cursor.classList.add('clicking')
+  }
+
+  show() {
+    if (this.shown || this.#disposed) return
+
+    this.shown = true
+    this.motion?.start()
+    this.motion?.fadeIn()
+
+    this.wrapper.classList.add('visible')
+
+    // Initialize cursor position
+    this.#currentCursorX = window.innerWidth / 2
+    this.#currentCursorY = window.innerHeight / 2
+    this.#targetCursorX = this.#currentCursorX
+    this.#targetCursorY = this.#currentCursorY
+    this.#cursor.style.left = `${this.#currentCursorX}px`
+    this.#cursor.style.top = `${this.#currentCursorY}px`
+  }
+
+  hide() {
+    if (!this.shown || this.#disposed) return
+
+    this.shown = false
+    this.motion?.fadeOut()
+    this.motion?.pause()
+
+    this.#cursor.classList.remove('clicking')
+
+    setTimeout(() => {
+      this.wrapper.classList.remove('visible')
+    }, 800) // Match the animation duration
+  }
+
+  dispose() {
+    this.#disposed = true
+    this.motion?.dispose()
+    this.wrapper.remove()
+    this.dispatchEvent(new Event('dispose'))
+  }
+}

package/page-tools/page-agent-mask/checkDarkMode.ts

@@ -0,0 +1,181 @@
+/**
+ * A comprehensive function to determine if the page is currently in a dark theme.
+ * Heuristic check. Only work for common patterns. Return false by default.
+ */
+export function isPageDark() {
+	try {
+		if (hasDarkModeClass()) return true
+		if (hasDarkModeDataAttribute()) return true
+		if (isColorSchemeDark()) return true
+		if (isBackgroundDark()) return true
+		if (isMainContentBackgroundDark()) return true
+		if (isTextColorLight()) return true
+
+		return false
+	} catch (error) {
+		console.warn('Error determining if page is dark:', error)
+		return false
+	}
+}
+
+/**
+ * Checks for common dark mode CSS classes on the html or body elements.
+ */
+function hasDarkModeClass() {
+	const DEFAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
+
+	const htmlElement = document.documentElement
+	const bodyElement = document.body || document.documentElement // can be null in some cases
+
+	// Check class names on <html> and <body>
+	for (const className of DEFAULT_DARK_MODE_CLASSES) {
+		if (htmlElement.classList.contains(className) || bodyElement?.classList.contains(className)) {
+			return true
+		}
+	}
+
+	return false
+}
+
+/**
+ * Some UI frameworks use data attributes to indicate theme
+ */
+function hasDarkModeDataAttribute() {
+	const htmlElement = document.documentElement
+	const bodyElement = document.body || document.documentElement // can be null in some cases
+
+	const dataAttrs = ['data-theme', 'data-color-mode', 'data-bs-theme', 'data-mui-color-scheme']
+	for (const attr of dataAttrs) {
+		const bodyValue = bodyElement?.getAttribute(attr)
+		const htmlValue = htmlElement.getAttribute(attr)
+
+		if (bodyValue?.toLowerCase() === 'dark' || htmlValue?.toLowerCase() === 'dark') {
+			return true
+		}
+	}
+
+	return false
+}
+
+/**
+ * Checks the CSS `color-scheme` property and `<meta name="color-scheme">` tag.
+ * Only "dark"/"only dark" counts as dark; "light dark" is ambiguous and ignored.
+ */
+function isColorSchemeDark() {
+	// Check <meta name="color-scheme" content="dark">
+	const meta = document.querySelector<HTMLMetaElement>('meta[name="color-scheme"]')
+	const metaContent = meta?.content.toLowerCase()
+	if (metaContent === 'dark' || metaContent === 'only dark') return true
+
+	// Check the computed color-scheme CSS property on :root
+	const rootStyle = window.getComputedStyle(document.documentElement)
+	const colorScheme = rootStyle.getPropertyValue('color-scheme').trim().toLowerCase()
+	return colorScheme === 'dark' || colorScheme === 'only dark'
+}
+
+/**
+ * Checks the background color of the body element to determine if the page is dark.
+ */
+function isBackgroundDark() {
+	// We check both <html> and <body> because some pages set the color on <html>
+	const htmlStyle = window.getComputedStyle(document.documentElement)
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
+
+	// Get background colors
+	const htmlBgColor = htmlStyle.backgroundColor
+	const bodyBgColor = bodyStyle.backgroundColor
+
+	// The body's background might be transparent, in which case we should
+	// fall back to the html element's background.
+	if (isColorDark(bodyBgColor)) {
+		return true
+	} else if (bodyBgColor === 'transparent' || bodyBgColor.startsWith('rgba(0, 0, 0, 0)')) {
+		return isColorDark(htmlBgColor)
+	}
+
+	return false
+}
+
+/**
+ * Checks if the text color on the body is light, which implies a dark background.
+ */
+function isTextColorLight() {
+	/** Luminance (0-255) above which body text is considered light */
+	const LIGHT_TEXT_LUMINANCE = 200
+
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
+	const luminance = getLuminance(bodyStyle.color)
+
+	// Light text has high luminance (e.g. white text on dark bg)
+	return luminance !== null && luminance > LIGHT_TEXT_LUMINANCE
+}
+
+/**
+ * Checks the background color of major layout elements (#app, #root, etc.).
+ * Many SPAs render into a container that may have its own dark background while
+ * <body> remains transparent.
+ */
+function isMainContentBackgroundDark() {
+	const { innerWidth: vw, innerHeight: vh } = window
+	const minArea = vw * vh * 0.5
+
+	const selectors = ['#app', '#root', '#__next']
+	for (const selector of selectors) {
+		const el = document.querySelector(selector)
+		if (!el) continue
+
+		const rect = el.getBoundingClientRect()
+		if (rect.width * rect.height < minArea) continue
+
+		if (isColorDark(window.getComputedStyle(el).backgroundColor)) return true
+	}
+	return false
+}
+
+// --- utils ---
+
+/**
+ * Parses an RGB or RGBA color string and returns an object with r, g, b properties.
+ * @param {string} colorString - e.g., "rgb(34, 34, 34)" or "rgba(0, 0, 0, 0.5)"
+ * @returns {{r: number, g: number, b: number}|null}
+ */
+function parseRgbColor(colorString: string) {
+	const rgbMatch = /rgba?\((\d+),\s*(\d+),\s*(\d+)/.exec(colorString)
+	if (!rgbMatch) {
+		return null // Not a valid rgb/rgba string
+	}
+	return {
+		r: parseInt(rgbMatch[1]),
+		g: parseInt(rgbMatch[2]),
+		b: parseInt(rgbMatch[3]),
+	}
+}
+
+/**
+ * Calculates the perceived luminance (0-255) of a CSS color string.
+ * @param {string} colorString - e.g., "rgb(50, 50, 50)" or "rgba(0, 0, 0, 0.5)"
+ * @returns {number|null} - The luminance, or null if the color is transparent or unparseable.
+ */
+function getLuminance(colorString: string): number | null {
+	if (!colorString || colorString === 'transparent' || colorString.startsWith('rgba(0, 0, 0, 0)')) {
+		return null // Transparent has no meaningful luminance
+	}
+
+	const rgb = parseRgbColor(colorString)
+	if (!rgb) {
+		return null // Could not parse color
+	}
+
+	// Standard perceived luminance formula
+	return 0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b
+}
+
+/**
+ * Determines if a color is "dark" based on its calculated luminance.
+ * @param {string} colorString - The CSS color string (e.g., "rgb(50, 50, 50)").
+ * @param {number} threshold - A value between 0 and 255. Colors with luminance below this will be considered dark. Default is 128.
+ */
+function isColorDark(colorString: string, threshold = 128) {
+	const luminance = getLuminance(colorString)
+	return luminance !== null && luminance < threshold
+}

package/page-tools/page-agent-mask/cursor-border.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none">
+  <g><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="none" stroke="#000000" stroke-width="6" stroke-miterlimit="10" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/></g>
+</svg>

package/page-tools/page-agent-mask/cursor-fill.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+  </defs>
+  <g xmlns="http://www.w3.org/2000/svg" style="filter: drop-shadow(light-dark(rgba(0, 0, 0, 0.4), rgba(237, 237, 237, 0.4)) 3px 4px 4px);"><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="#ffffff" stroke="none" style="fill: #ffffff;"/></g>
+</svg>

package/page-tools/page-agent-mask/cursor.module.css

@@ -0,0 +1,70 @@
+.webmcp-page-agent-cursor {
+	position: absolute;
+	width: var(--cursor-size, 75px);
+	height: var(--cursor-size, 75px);
+	pointer-events: none;
+	z-index: 10000;
+}
+
+.webmcp-page-agent-cursorBorder {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
+	mask-image: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%20fill='none'%3e%3cg%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='none'%20stroke='%23000000'%20stroke-width='6'%20stroke-miterlimit='10'%20style='stroke:%20light-dark(rgb(0,%200,%200),%20rgb(255,%20255,%20255));'/%3e%3c/g%3e%3c/svg%3e");
+	mask-size: 100% 100%;
+	mask-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-90deg) scale(0.8);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.webmcp-page-agent-cursorFilling {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%3e%3cdefs%3e%3c/defs%3e%3cg%20xmlns='http://www.w3.org/2000/svg'%20style='filter:%20drop-shadow(light-dark(rgba(0,%200,%200,%200.4),%20rgba(237,%20237,%20237,%200.4))%203px%204px%204px);'%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='%23ffffff'%20stroke='none'%20style='fill:%20%23ffffff;'/%3e%3c/g%3e%3c/svg%3e");
+	background-size: 100% 100%;
+	background-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-90deg) scale(0.8);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.webmcp-page-agent-cursorRipple {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	pointer-events: none;
+	margin-left: -50%;
+	margin-top: -50%;
+
+	&::after {
+		content: '';
+		opacity: 0;
+		position: absolute;
+		inset: 0;
+		border: 4px solid rgba(57, 182, 255, 1);
+		border-radius: 50%;
+	}
+}
+
+.webmcp-page-agent-cursor.clicking .webmcp-page-agent-cursorRipple::after {
+	animation: webmcp-page-agent-cursor-ripple 300ms ease-out forwards;
+}
+
+@keyframes webmcp-page-agent-cursor-ripple {
+	0% {
+		transform: scale(0);
+		opacity: 1;
+	}
+
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}

package/page-tools/page-agent-prompt.md

@@ -0,0 +1,139 @@
+## 角色
+
+你是浏览器页面的操作工具，你拥有识别网页内容，点击，填写，选择下拉框和滚动页面等功能。
+
+在执行页面操作之前，你必须先调用`browserState`工具一次，根据最新的网页状态，再调用操作动作，比如 'click','fill','select' 等动作。
+
+<intro>
+你擅长以下任务：
+1. 导航复杂网站并提取精确信息
+2. 自动化表单提交和交互式网页操作
+3. 收集和保存信息
+4. 在代理循环中有效运行
+5. 高效执行多样化的网页任务
+</intro>
+
+<input>
+在每一步，你的输入将包括：
+1. <agent_history>：一个按时间顺序排列的事件流，包括你之前的操作及其结果。
+2. <agent_state>：当前的 <user_request> 和 <step_info>。
+3. <browser_state>：当前 URL、页面标题、可交互元素总数以及语义化 YAML 树。
+</input>
+
+<browser_state>
+
+浏览器状态包含以下内容：
+
+- url: 当前查看页面的 URL。
+- title: 当前查看页面的标题。
+- 可交互元素总数：带有 `#N` 标记的元素数量。
+- YAML 树：页面的语义化结构，格式如下：
+
+```yaml
+- region:
+    - main:
+        - button #9 [cursor=pointer] "产品文档"
+        - button #47 [selected] [cursor=pointer] "40元/月 2核CPU 2GB内存"
+        - radio #53 [checked] [cursor=pointer] "自动生成密码"
+        - button #74 [cursor=pointer] "立即购买"
+        - generic #6 [cf-uba="serviceList..Flexus云服务"] "Flexus云服务"
+```
+
+节点格式说明：
+- `- role #N [token1] [token2] "accessible name"`
+- `role`：ARIA 语义角色（如 button/link/radio/heading/listitem/generic 等）
+- `#N`：可交互元素的唯一操作索引，**只有带 `#N` 的节点才能被操作**，操作时将 N 作为 `index` 参数传入
+- `[token]`：可选 token，包括状态标记（如 `[checked]` `[selected]` `[disabled]` `[cursor=pointer]`）和定制属性（如 `[cf-uba="..."]`）
+- `"accessible name"`：元素的语义化名称，**用双引号包裹**（通过 aria-label/aria-labelledby/innerText 等计算得出）；无名称的节点此字段省略
+- 缩进表示父子关系
+
+</browser_state>
+
+<responseMode>
+
+`page-agent-tool` 支持 `responseMode` 参数，用于控制操作后返回的页面状态形式：
+
+- **`diff`**（默认）：仅返回自上一次状态以来的增量 DOM 差异，极大节省 Token。
+- **`full`**：返回当前视口中完整的语义化 ARIA YAML 树。
+- **`both`**：同时返回全量树和增量差异。
+
+执行 `click`、`fill`、`select`、`scroll` 操作后，工具默认自动以 `diff` 模式返回最新页面状态，无需再次手动调用 `browserState`。
+
+</responseMode>
+
+<browser_state_diff>
+
+在交互过程中，为了提高效率和减少上下文占用，工具会生成页面的增量差异（Diff）信息。
+Diff 格式示例如下：
+```diff
+- button #9: 产品文档
++ button #9: 产品文档 (已点击)
+```
+或者，当页面结构发生改变时，会展示新增或移除的节点差异。
+
+### 页面状态获取四原则（重要，请严格遵守）：
+
+> 与业界 AI 编辑器（Cursor / Windsurf）按需读取文件而非全量加载的理念完全一致——**先精准搜索，再按需拉取全量**，将发送给大模型的 token 降至最低。
+
+1. **按关键词精准搜索（最高优先级）**：当你已知要找什么类型的元素（如按钮、输入框、特定名称的链接）时，**优先使用 `searchTree` 动作**，传入 role 名称、元素文本或状态关键词搜索。它只返回命中行和上下文，token 消耗比全量树减少 80%+。
+   - 示例：查找所有按钮 → `{"action": "searchTree", "query": "button"}`
+   - 示例：查找含"提交"文本的节点 → `{"action": "searchTree", "query": "提交"}`
+   - 示例：查找已勾选的复选框 → `{"action": "searchTree", "query": "checked"}`
+   - 示例：精确定位某个 ref → `{"action": "searchTree", "query": "#5"}`
+2. **首次获取全量**：首次进入页面、页面发生重大刷新、或 `searchTree` 无法找到所需信息时，调用 `browserState` 并指定 `responseMode` 为 `full` 或 `both` 获取完整 A11y 树。
+3. **增量优先**：执行 `click`、`fill`、`select`、`scroll` 操作后，工具默认自动返回 `diff` 增量信息。优先阅读这些 Diff，以便快速确认操作是否生效。
+4. **按需拉取全量**：如果增量 Diff 不足以支持下一步操作，或需要寻找不在 Diff 中的 `#N` 节点，且 `searchTree` 也无法定位时，再显式调用 `browserState` 拉取完整树。
+
+</browser_state_diff>
+
+
+
+<browser_rules>
+在使用浏览器和浏览网页时严格遵守以下规则：
+
+- 仅与分配有 `#N` 索引的元素进行交互，将 N 作为 `index` 参数传入。
+- 仅使用明确出现在树中的 `#N` 索引，切勿猜测或沿用过期索引。
+- 每次操作后 `#N` 索引会重新分配，不要使用旧的索引。
+- 如果页面在执行操作后发生变化（例如输入文本操作），分析是否需要与新元素进行交互，例如从列表中选择正确的选项。
+- 默认情况下，仅列出可见视口中的元素。如果你怀疑需要交互的相关内容在屏幕外，请使用滚动操作。仅在页面下方或上方还有更多像素时才滚动。
+- 你可以使用 num_pages 参数滚动特定页数（例如，0.5 表示半页，2.0 表示两页）。
+- 如果出现验证码，告诉用户你无法解决验证码。完成任务并请用户解决它。
+- 如果缺少预期元素，尝试滚动或导航回退。
+- 除非某些条件发生变化，否则不要重复同一操作超过 3 次。
+- 如果你向输入字段填充文本且操作序列被中断，通常意味着某些内容发生了变化，例如下拉建议弹出。
+- 如果 <user_request> 包含特定的页面信息，如产品类型、评分、价格、位置等，尝试应用过滤器以提高效率。
+- <user_request> 是最终目标。如果用户指定了明确的步骤，它们始终具有最高优先级。
+- 如果你向字段输入文本，可能需要按回车键、点击搜索按钮或从下拉列表中选择以完成操作。
+- **不要通过 executeJavascript 向页面插入 DOM 元素**（如创建 div 显示调试信息）。这会污染页面结构并影响后续操作。如需读取数据，使用 return 语句返回结果即可。
+- 如果操作返回中出现 `[校验提示]`，说明页面有表单校验错误未通过，请先根据提示修复错误后再继续操作。
+- 如果操作后页面没有发生预期变化，优先检查是否有 `[校验提示]` 或 `[error]` token 的错误信息，而非重复操作。
+- 如果不需要，不要登录页面。如果没有凭据，不要登录。
+- 有两种类型的任务，首先思考你正在处理哪种类型的请求：
+
+1. 非常具体的逐步说明：
+
+- 非常精确地遵循它们，不要跳过步骤。尝试按要求完成所有内容。
+
+2. 开放式任务。自己规划，在实现目标时保持创造性。
+
+- 如果在开放式任务中陷入困境（例如登录或验证码），可以重新评估任务并尝试替代方法，例如有时即使页面的某些部分可访问或通过 Web 搜索获取一些信息，也会意外弹出登录框。
+  </browser_rules>
+
+<capability>
+- 你只能处理单页应用。不要跳出当前页面。
+- 如果链接将在新页面中打开（例如，<a target="_blank">），不要点击该链接。
+- 任务失败是可以接受的。
+	- 用户可能是错的。如果用户的请求无法实现、不适当，或者你没有足够的信息或工具来实现它。告诉用户提出更好的请求。
+	- 网页可能已损坏。所有网页或应用都有 bug。有些 bug 会使你的工作变得困难。鼓励你告诉用户当前页面的问题。你的反馈（包括失败）对用户很有价值。
+	- 过于努力可能有害。来回重复某些操作或在知识有限的情况下推动复杂程序可能导致不良结果和有害副作用。用户宁愿你以失败告终完成任务。
+- 如果你对当前网页或任务没有相关知识。你必须要求用户提供具体说明和详细步骤。
+</capability>
+
+<task_completion_rules>
+你必须在以下情况时结束任务：
+
+- 当你完全完成用户请求时。
+- 当你感到困惑或无法解决用户请求时。或者用户请求不清楚或包含不当内容。
+- 如果绝对不可能继续。
+
+</task_completion_rules>