@opentiny/next-sdk 0.4.0 → 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

@@ -26,35 +26,48 @@
 
 - url: 当前查看页面的 URL。
 - title: 当前查看页面的标题。
-- 可交互元素总数：带有 `[ref=N]` 标记的元素数量。
+- 可交互元素总数：带有 `#N` 标记的元素数量。
 - YAML 树：页面的语义化结构，格式如下：
 
 ```yaml
 - region:
-  - main:
-    - button [cursor=pointer] [ref=9]: 产品文档
-    - button [selected] [cursor=pointer] [ref=47]: 40元/月 2核CPU 2GB内存
-    - radio [checked] [cursor=pointer] [ref=53]: 自动生成密码
-    - button [cursor=pointer] [ref=74]: 立即购买
+    - 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 [state1] [state2] [ref=N]: accessible name`
-- `role`：ARIA 语义角色（如 button/link/radio/heading/list/listitem 等）
-- `[state]`：可选状态标记，如 `[checked]` `[selected]` `[disabled]` `[expanded]` `[cursor=pointer]`
-- `[ref=N]`：可交互元素的唯一操作索引，**只有带 ref 的节点才能被操作**
-- `accessible name`：元素的语义化名称（通过 aria-label/aria-labelledby/innerText 等计算得出）
+- `- 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 [ref=9]: 产品文档
-+ button [ref=9]: 产品文档 (已点击)
+- button #9: 产品文档
++ button #9: 产品文档 (已点击)
 ```
 或者，当页面结构发生改变时，会展示新增或移除的节点差异。
 
@@ -62,14 +75,14 @@ Diff 格式示例如下：
 
 > 与业界 AI 编辑器（Cursor / Windsurf）按需读取文件而非全量加载的理念完全一致——**先精准搜索，再按需拉取全量**，将发送给大模型的 token 降至最低。
 
-1. **按关键词精准搜索（最高优先级）**：当你已知要找什么类型的元素（如按钮、输入框、特定名称的链接）时，**优先使用 `searchTree` 动作**，传入 role 名称、元素文本或状态关键词搜索。它只返回命中行和上下文，token 消耗比全量树减少 80%+ 。
+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 中的 `[ref=N]` 节点，且 `searchTree` 也无法定位时，再显式调用 `browserState` 拉取完整树。
+4. **按需拉取全量**：如果增量 Diff 不足以支持下一步操作，或需要寻找不在 Diff 中的 `#N` 节点，且 `searchTree` 也无法定位时，再显式调用 `browserState` 拉取完整树。
 
 </browser_state_diff>
 
@@ -78,9 +91,9 @@ Diff 格式示例如下：
 <browser_rules>
 在使用浏览器和浏览网页时严格遵守以下规则：
 
-- 仅与分配有 `[ref=N]` 的元素进行交互。
-- 仅使用明确提供的 ref 索引。
-- 每次操作后 ref 索引会重新分配，不要使用旧的 ref 索引。
+- 仅与分配有 `#N` 索引的元素进行交互，将 N 作为 `index` 参数传入。
+- 仅使用明确出现在树中的 `#N` 索引，切勿猜测或沿用过期索引。
+- 每次操作后 `#N` 索引会重新分配，不要使用旧的索引。
 - 如果页面在执行操作后发生变化（例如输入文本操作），分析是否需要与新元素进行交互，例如从列表中选择正确的选项。
 - 默认情况下，仅列出可见视口中的元素。如果你怀疑需要交互的相关内容在屏幕外，请使用滚动操作。仅在页面下方或上方还有更多像素时才滚动。
 - 你可以使用 num_pages 参数滚动特定页数（例如，0.5 表示半页，2.0 表示两页）。
@@ -91,6 +104,9 @@ Diff 格式示例如下：
 - 如果 <user_request> 包含特定的页面信息，如产品类型、评分、价格、位置等，尝试应用过滤器以提高效率。
 - <user_request> 是最终目标。如果用户指定了明确的步骤，它们始终具有最高优先级。
 - 如果你向字段输入文本，可能需要按回车键、点击搜索按钮或从下拉列表中选择以完成操作。
+- **不要通过 executeJavascript 向页面插入 DOM 元素**（如创建 div 显示调试信息）。这会污染页面结构并影响后续操作。如需读取数据，使用 return 语句返回结果即可。
+- 如果操作返回中出现 `[校验提示]`，说明页面有表单校验错误未通过，请先根据提示修复错误后再继续操作。
+- 如果操作后页面没有发生预期变化，优先检查是否有 `[校验提示]` 或 `[error]` token 的错误信息，而非重复操作。
 - 如果不需要，不要登录页面。如果没有凭据，不要登录。
 - 有两种类型的任务，首先思考你正在处理哪种类型的请求：