chore(ext): update extension version

> If multiple listeners are registered for onMessage,
> only the first listener to respond, reject, or throw
> an error will affect the sender; all other listeners
> will run, but their results will be ignored.

README-zh.md

@@ -28,7 +28,7 @@
 
 以及 😉
 
-- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `-b feat/ext`
+- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `packages/extension`
 
 👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 

README.md

@@ -28,7 +28,7 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 And 😉
 
-- **🧪 `cross-page` control with an experimental chrome extension** - `-b feat/ext`
+- **🧪 `cross-page` control with an experimental chrome extension** - `packages/extension`
 
 👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 

package-lock.json

@@ -11333,7 +11333,7 @@
         },
         "packages/extension": {
             "name": "@page-agent/ext",
-            "version": "0.1.0-beta.1",
+            "version": "0.1.0-b4",
             "hasInstallScript": true,
             "dependencies": {
                 "@page-agent/core": "1.0.0",

packages/core/src/PageAgentCore.ts

@@ -95,7 +95,7 @@ export class PageAgentCore extends EventTarget {
 		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
 			const { attempt, maxAttempts } = (e as CustomEvent).detail
-			this.emitActivity({ type: 'retrying', attempt, maxAttempts })
+			this.#emitActivity({ type: 'retrying', attempt, maxAttempts })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'retry',
@@ -109,7 +109,7 @@ export class PageAgentCore extends EventTarget {
 			const error = (e as CustomEvent).detail.error as Error | InvokeError
 			if ((error as any)?.rawError?.name === 'AbortError') return
 			const message = String(error)
-			this.emitActivity({ type: 'error', message })
+			this.#emitActivity({ type: 'error', message })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'error',
@@ -153,7 +153,7 @@ export class PageAgentCore extends EventTarget {
 	 * Emit activity event - for transient UI feedback
 	 * @param activity - Current agent activity
 	 */
-	emitActivity(activity: AgentActivity): void {
+	#emitActivity(activity: AgentActivity): void {
 		this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
 	}
 
@@ -224,7 +224,7 @@ export class PageAgentCore extends EventTarget {
 
 				// Thinking
 				console.log(chalk.blue('Thinking...'))
-				this.emitActivity({ type: 'thinking' })
+				this.#emitActivity({ type: 'thinking' })
 
 				// invoke LLM
 
@@ -303,7 +303,7 @@ export class PageAgentCore extends EventTarget {
 		} catch (error: unknown) {
 			console.error('Task failed', error)
 			const errorMessage = String(error)
-			this.emitActivity({ type: 'error', message: errorMessage })
+			this.#emitActivity({ type: 'error', message: errorMessage })
 			this.#onDone(false)
 			const result: ExecutionResult = {
 				success: false,
@@ -376,7 +376,7 @@ export class PageAgentCore extends EventTarget {
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
 
 				// Emit executing activity
-				this.emitActivity({ type: 'executing', tool: toolName, input: toolInput })
+				this.#emitActivity({ type: 'executing', tool: toolName, input: toolInput })
 
 				const startTime = Date.now()
 
@@ -387,7 +387,7 @@ export class PageAgentCore extends EventTarget {
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
 
 				// Emit executed activity
-				this.emitActivity({
+				this.#emitActivity({
 					type: 'executed',
 					tool: toolName,
 					input: toolInput,

packages/extension/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/ext",
     "private": true,
-    "version": "0.1.0-beta.1",
+    "version": "0.1.0-b4",
     "type": "module",
     "scripts": {
         "dev": "wxt",

packages/extension/src/agent/MultiPageAgent.ts

@@ -5,12 +5,26 @@ import { TabsController } from './TabsController'
 import SYSTEM_PROMPT from './system_prompt.md?raw'
 import { createTabTools } from './tabTools'
 
+/**
+ * MultiPageAgent
+ * - use with extension
+ * - can be used from a side panel or a content script
+ */
 export class MultiPageAgent extends PageAgentCore {
 	constructor(config: Omit<PageAgentConfig, 'pageController'>) {
 		const tabsController = new TabsController()
 		const pageController = new RemotePageController(tabsController)
 		const customTools = createTabTools(tabsController)
 
+		/**
+		 * When the agent is in side-panel and user closed the side-panel.
+		 * There is no chance for isAgentRunning to be set false.
+		 * (unload event doesn't work well in side panel.)
+		 * (I'm trying not to use long-lived connection because the lifecycle of a sw is hard to predict.)
+		 * This heartbeat mechanism acts as a backup.
+		 */
+		let heartBeatInterval: null | number = null
+
 		super({
 			...config,
 			pageController: pageController as any,
@@ -20,18 +34,34 @@ export class MultiPageAgent extends PageAgentCore {
 			onBeforeTask: async (agent) => {
 				await tabsController.init(agent.task)
 
+				heartBeatInterval = window.setInterval(() => {
+					chrome.storage.local.set({
+						agentHeartbeat: Date.now(),
+					})
+				}, 1_000)
+
 				await chrome.storage.local.set({
 					isAgentRunning: true,
 				})
 			},
 
 			onAfterTask: async () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
 				await chrome.storage.local.set({
 					isAgentRunning: false,
 				})
 			},
 
 			onDispose: () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
 				chrome.storage.local.set({
 					isAgentRunning: false,
 				})

packages/extension/src/agent/RemotePageController.background.ts

@@ -7,12 +7,12 @@ export function handlePageControlMessage(
 	message: { type: 'PAGE_CONTROL'; action: string; payload: any; targetTabId: number },
 	sender: chrome.runtime.MessageSender,
 	sendResponse: (response: unknown) => void
-): boolean {
+): true | undefined {
 	const { action, payload, targetTabId } = message
 
 	if (action === 'get_my_tab_id') {
 		sendResponse({ tabId: sender.tab?.id || null })
-		return false
+		return
 	}
 
 	chrome.tabs

packages/extension/src/agent/RemotePageController.content.ts

@@ -21,17 +21,14 @@ export function initPageController() {
 	}
 
 	intervalID = window.setInterval(async () => {
+		const agentHeartbeat = (await chrome.storage.local.get('agentHeartbeat')).agentHeartbeat
+		const now = Date.now()
+		const agentInTouch = typeof agentHeartbeat === 'number' && now - agentHeartbeat < 2_000
+
 		const isAgentRunning = (await chrome.storage.local.get('isAgentRunning')).isAgentRunning
 		const currentTabId = (await chrome.storage.local.get('currentTabId')).currentTabId
 
-		const shouldShowMask = isAgentRunning && currentTabId === (await myTabIdPromise)
-
-		// console.log('[RemotePageController] polling:', {
-		// 	isAgentRunning,
-		// 	currentTabId,
-		// 	myTabId: await myTabIdPromise,
-		// 	shouldShowMask,
-		// })
+		const shouldShowMask = isAgentRunning && agentInTouch && currentTabId === (await myTabIdPromise)
 
 		if (shouldShowMask) {
 			const pc = getPC()
@@ -45,20 +42,20 @@ export function initPageController() {
 			}
 		}
 
-		if (!isAgentRunning) {
+		if (!isAgentRunning && agentInTouch) {
 			if (pageController) {
 				pageController.dispose()
 				pageController = null
 			}
 		}
-	}, 1_000)
+	}, 500)
 
-	chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
 		if (message.type !== 'PAGE_CONTROL') {
-			sendResponse({
-				success: false,
-				error: `[RemotePageController.ContentScript]: Invalid message type: ${message.type}`,
-			})
+			// sendResponse({
+			// 	success: false,
+			// 	error: `[RemotePageController.ContentScript]: Invalid message type: ${message.type}`,
+			// })
 			return
 		}
 

packages/extension/src/agent/TabsController.background.ts

@@ -7,7 +7,7 @@ export function handleTabControlMessage(
 	message: { type: 'TAB_CONTROL'; action: TabAction; payload: any },
 	sender: chrome.runtime.MessageSender,
 	sendResponse: (response: unknown) => void
-): boolean {
+): true | undefined {
 	const { action, payload } = message
 
 	switch (action as TabAction) {
@@ -102,6 +102,6 @@ export function handleTabControlMessage(
 
 		default:
 			sendResponse({ error: `Unknown action: ${action}` })
-			return false
+			return
 	}
 }

packages/extension/src/agent/TabsController.ts

@@ -3,7 +3,7 @@
  * - live in the agent env (extension page or content script)
  * - no chrome apis. call sw for tab operations
  */
-export class TabsController {
+export class TabsController extends EventTarget {
 	currentTabId: number | null = null
 
 	private tabs: TabMeta[] = []
@@ -38,6 +38,44 @@ export class TabsController {
 		}
 
 		await this.updateCurrentTabId(this.currentTabId)
+
+		const tabChangeHandler = (message: any): void => {
+			if (message.type !== 'TAB_CHANGE') {
+				// throw new Error(`[TabsController]: Invalid message type: ${message.type}`)
+				return
+			}
+
+			if (message.action === 'created') {
+				const tab = message.payload.tab as chrome.tabs.Tab
+				if (tab.groupId === this.tabGroupId && tab.id != null) {
+					// Tab created in our controlled group
+					if (!this.tabs.find((t) => t.id === tab.id)) {
+						this.tabs.push({ id: tab.id, isInitial: false })
+					}
+					this.switchToTab(tab.id)
+				}
+			} else if (message.action === 'removed') {
+				const { tabId } = message.payload as { tabId: number }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					this.tabs = this.tabs.filter((t) => t.id !== tabId)
+					if (this.currentTabId === tabId) {
+						const newCurrentTab = this.tabs[this.tabs.length - 1] || null
+						if (newCurrentTab) {
+							this.switchToTab(newCurrentTab.id)
+						} else {
+							this.updateCurrentTabId(null)
+						}
+					}
+				}
+			}
+		}
+
+		chrome.runtime.onMessage.addListener(tabChangeHandler)
+
+		this.addEventListener('dispose', () => {
+			chrome.runtime.onMessage.removeListener(tabChangeHandler)
+		})
 	}
 
 	async openNewTab(url: string): Promise<{ success: boolean; tabId: number; message: string }> {
@@ -194,6 +232,10 @@ export class TabsController {
 		}
 		return summaries.join('\n')
 	}
+
+	dispose() {
+		this.dispatchEvent(new Event('dispose'))
+	}
 }
 
 export type TabAction =

packages/extension/src/entrypoints/background.ts

@@ -1,7 +1,7 @@
 import { handlePageControlMessage } from '@/agent/RemotePageController.background'
 import { handleTabControlMessage } from '@/agent/TabsController.background'
 
-chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
 	if (message.type === 'TAB_CONTROL') {
 		return handleTabControlMessage(message, sender, sendResponse)
 	} else if (message.type === 'PAGE_CONTROL') {
@@ -19,6 +19,8 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
 export default defineBackground(() => {
 	console.log('[Background] Service Worker started')
 
+	// generate user auth token
+
 	chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
 		if (result.PageAgentExtUserAuthToken) return
 
@@ -26,5 +28,21 @@ export default defineBackground(() => {
 		chrome.storage.local.set({ PageAgentExtUserAuthToken: userAuthToken })
 	})
 
+	// setup
+
 	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
+
+	// Tab change events
+
+	chrome.tabs.onCreated.addListener((tab) => {
+		chrome.runtime.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
+	})
+
+	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
+		chrome.runtime.sendMessage({
+			type: 'TAB_CHANGE',
+			action: 'removed',
+			payload: { tabId, removeInfo },
+		})
+	})
 })

packages/extension/src/entrypoints/content.ts

@@ -54,6 +54,7 @@ async function exposeAgentToPage() {
 
 		switch (action) {
 			case 'execute': {
+				// singleton check
 				if (multiPageAgent && multiPageAgent.status === 'running') {
 					window.postMessage(
 						{
@@ -70,8 +71,64 @@ async function exposeAgentToPage() {
 				try {
 					const { task, llmConfig } = payload
 
+					// create when used
+
 					multiPageAgent = new MultiPageAgent(llmConfig)
 
+					// events
+
+					multiPageAgent.addEventListener('statuschange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'status_change_event',
+								payload: multiPageAgent.status,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('activity', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'activity_event',
+								payload: (event as CustomEvent).detail,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('historychange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'history_change_event',
+								payload: multiPageAgent.history,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('dispose', () => {
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'dispose_event',
+							},
+							'*'
+						)
+					})
+
+					// result
+
 					const result = await multiPageAgent.execute(task)
 
 					window.postMessage(

packages/extension/src/entrypoints/main-world.ts

@@ -1,5 +1,19 @@
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
 import type { LLMConfig } from '@page-agent/llms'
 
+export interface ExecuteHooks {
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+	onDispose?: () => void
+}
+
+export type Execute = (
+	task: string,
+	llmConfig: LLMConfig,
+	hooks?: ExecuteHooks
+) => Promise<ExecutionResult>
+
 export default defineUnlistedScript(() => {
 	const w = window as any
 
@@ -9,7 +23,7 @@ export default defineUnlistedScript(() => {
 		return _lastId
 	}
 
-	w.execute = async (task: string, llmConfig: LLMConfig) => {
+	w.execute = async (task: string, llmConfig: LLMConfig, hooks?: ExecuteHooks) => {
 		if (typeof task !== 'string') throw new Error('Task must be a string')
 		if (task.trim().length === 0) throw new Error('Task cannot be empty')
 		if (!llmConfig) throw new Error('LLM config is required')
@@ -19,14 +33,39 @@ export default defineUnlistedScript(() => {
 
 		const id = getId()
 
-		const promise = new Promise((resolve, reject) => {
+		const promise = new Promise<ExecutionResult>((resolve, reject) => {
 			function handleMessage(e: MessageEvent) {
 				const data = e.data
 				if (typeof data !== 'object' || data === null) return
 				if (data.channel !== 'PAGE_AGENT_EXT_RESPONSE') return
-				if (data.action !== 'execute_result') return
 				if (data.id !== id) return
 
+				// events
+
+				if (data.action === 'status_change_event' && hooks?.onStatusChange) {
+					hooks.onStatusChange(data.payload)
+					return
+				}
+
+				if (data.action === 'activity_event' && hooks?.onActivity) {
+					hooks.onActivity(data.payload)
+					return
+				}
+
+				if (data.action === 'history_change_event' && hooks?.onHistoryUpdate) {
+					hooks.onHistoryUpdate(data.payload)
+					return
+				}
+
+				if (data.action === 'dispose_event' && hooks?.onDispose) {
+					hooks.onDispose()
+					return
+				}
+
+				// result
+
+				if (data.action !== 'execute_result') return
+
 				window.removeEventListener('message', handleMessage)
 
 				if (data.error) {

packages/extension/src/entrypoints/sidepanel/components/cards.tsx

@@ -249,10 +249,10 @@ function StepCard({ event }: { event: AgentStepEvent }) {
 								)}
 							</p>
 							<p className="text-[11px] text-muted-foreground/70 grid grid-cols-[auto_1fr] gap-1.5">
-								<div className="">└</div>
-								<div className="wrap-anywhere break-all line-clamp-1 hover:line-clamp-3">
+								<span className="">└</span>
+								<span className="wrap-anywhere break-all line-clamp-1 hover:line-clamp-3">
 									{event.action.output}
-								</div>
+								</span>
 							</p>
 						</div>
 					</div>

packages/website/src/i18n/locales/en-US/common.ts

@@ -32,6 +32,7 @@ export default {
 		custom_tools: 'Custom Tools',
 		knowledge_injection: 'Instructions',
 		data_masking: 'Data Masking',
+		chrome_extension: 'Chrome Extension',
 		cdn_setup: 'CDN Setup',
 		best_practices: 'Best Practices',
 		third_party_agent: 'Third-party Agent',

packages/website/src/i18n/locales/zh-CN/common.ts

@@ -31,6 +31,7 @@ export default {
 		custom_tools: '自定义工具',
 		knowledge_injection: '知识注入',
 		data_masking: '数据脱敏',
+		chrome_extension: 'Chrome 扩展',
 		cdn_setup: 'CDN 引入',
 		best_practices: '最佳实践',
 		third_party_agent: '接入第三方 Agent',

packages/website/src/pages/docs/Layout.tsx

@@ -36,6 +36,7 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
 				{ title: t('nav.custom_tools'), path: '/features/custom-tools' },
 				{ title: t('nav.knowledge_injection'), path: '/features/custom-instructions' },
 				{ title: t('nav.data_masking'), path: '/features/data-masking' },
+				{ title: t('nav.chrome_extension'), path: '/features/chrome-extension' },
 			],
 		},
 		{

packages/website/src/pages/docs/advanced/page-agent-core/page.tsx

@@ -385,13 +385,6 @@ const result = await agent.execute('Fill in the form with test data')`}
 								? '向历史流推送一个观察事件，会在下一步时被 LLM 看到'
 								: 'Push an observation to history stream, will be seen by LLM in next step',
 						},
-						{
-							name: 'emitActivity(activity: AgentActivity)',
-							type: 'void',
-							description: isZh
-								? '发出活动事件用于 UI 反馈'
-								: 'Emit activity event for UI feedback',
-						},
 						{
 							name: 'dispose(reason?: string)',
 							type: 'void',

packages/website/src/pages/docs/features/chrome-extension/page.tsx

@@ -0,0 +1,310 @@
+import { useTranslation } from 'react-i18next'
+import { siGithub } from 'simple-icons'
+
+import BetaNotice from '@/components/BetaNotice'
+import CodeEditor from '@/components/CodeEditor'
+
+export default function ChromeExtension() {
+	const { i18n } = useTranslation()
+	const isZh = i18n.language === 'zh-CN'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? 'Chrome 扩展' : 'Chrome Extension'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '可选的 Chrome 扩展，解锁多页任务和第三方 API 集成。'
+					: 'Optional Chrome extension that unlocks multi-page tasks and third-party API integration.'}
+			</p>
+
+			<BetaNotice />
+
+			<div className="space-y-8 mt-8">
+				{/* Hero Section */}
+				<section className="p-6 bg-linear-to-r from-blue-50 to-purple-50 dark:from-blue-900/20 dark:to-purple-900/20 rounded-xl">
+					<div className="flex items-start gap-4">
+						<div>
+							<p className="text-gray-600 dark:text-gray-300">
+								{isZh
+									? '解锁多页任务！借助 Chrome 扩展，Agent 可以跨标签页和页面导航，突破单页限制。'
+									: 'Unlock multi-page tasks! With the Chrome extension, your agent can navigate across tabs and pages, breaking the single-page limitation.'}
+							</p>
+						</div>
+					</div>
+				</section>
+
+				{/* Features */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">{isZh ? '核心特性' : 'Key Features'}</h2>
+					<div className="grid md:grid-cols-2 gap-4">
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">🔓 {isZh ? '多页任务' : 'Multi-Page Tasks'}</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '跨多个页面和标签页执行任务，不再局限于单页操作。'
+									: 'Execute tasks across multiple pages and tabs. No longer limited to single-page operations.'}
+							</p>
+						</div>
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">
+								🔌 {isZh ? '开放第三方接口' : 'Third-Party API'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '用户授权后，你的网页、本地 Agent 或云端 Agent 都能通过扩展操作用户浏览器！'
+									: 'After user authorization, your webpage, local agent, or cloud agent can control the browser through the extension.'}
+							</p>
+						</div>
+					</div>
+				</section>
+
+				{/* Download */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">{isZh ? '下载测试版' : 'Download Beta'}</h2>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '扩展目前处于 Beta 阶段，请从 GitHub Releases 下载最新版本。'
+							: 'The extension is currently in beta. Download the latest version from GitHub Releases.'}
+					</p>
+					<a
+						href="https://github.com/alibaba/page-agent/releases"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="inline-flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-medium rounded-lg transition-colors"
+					>
+						<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+							<path d={siGithub.path} />
+						</svg>
+						{isZh ? '前往 GitHub Releases 下载' : 'Download from GitHub Releases'}
+					</a>
+				</section>
+
+				{/* Third-party Integration */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">
+						{isZh ? '第三方接入' : 'Third-Party Integration'}
+					</h2>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '用户授权后，外部应用可以调用扩展 API 来控制浏览器。'
+							: 'After user authorization, external applications can call the extension API to control the browser.'}
+					</p>
+
+					{/* Auth Flow */}
+					<h3 className="text-xl font-semibold mb-3">{isZh ? '授权流程' : 'Authorization Flow'}</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '扩展使用基于 Token 的授权机制，扩展端和页面端必须持有匹配的 Token。'
+							: 'The extension uses a token-based authorization mechanism. Both extension and page must have matching tokens.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 1. 用户安装扩展并在扩展设置中配置 auth token
+// 2. 你的页面读取相同的 token 并存入 localStorage
+// 3. Token 匹配后，扩展会暴露 window.execute() 和 window.dispose()
+
+// ⚠️ 请在扩展弹窗中查看你的 auth token，然后填入下方
+localStorage.setItem('PageAgentExtUserAuthToken', '<从扩展中获取的-token>')`
+								: `// 1. User installs extension and sets an auth token in extension settings
+// 2. Your page reads the same token and stores it in localStorage
+// 3. After token match, extension exposes window.execute() and window.dispose()
+
+// ⚠️ Check your extension popup for the auth token
+localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')`
+						}
+						language="javascript"
+					/>
+				</section>
+
+				{/* API Reference */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">{isZh ? 'API 参考' : 'API Reference'}</h2>
+
+					<h3 className="text-xl font-semibold mb-3">window.execute(task, llmConfig, hooks?)</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '使用 LLM 配置执行任务。返回一个 Promise，在任务完成时 resolve。可选的 hooks 参数用于监听任务执行过程中的事件。'
+							: 'Execute a task with LLM configuration. Returns a Promise that resolves when the task completes. Optional hooks parameter for listening to events during task execution.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 使用 LLM 配置和 hooks 执行任务
+const result = await window.execute(
+	'在 GitHub 上搜索 "page-agent" 并打开第一个结果',
+	{
+		baseURL: 'https://api.openai.com/v1',
+		apiKey: 'your-api-key',
+		model: 'gpt-5-2'
+	},
+	{
+		onStatusChange: status => console.log('状态变化:', status),
+		onActivity: activity => console.log('活动:', activity),
+		onHistoryUpdate: history => console.log('历史更新:', history),
+		onDispose: () => console.log('已停止')
+	}
+)
+
+console.log(result) // 任务执行结果`
+								: `// Execute a task with LLM configuration and hooks
+const result = await window.execute(
+	'Search for "page-agent" on GitHub and open the first result',
+	{
+		baseURL: 'https://api.openai.com/v1',
+		apiKey: 'your-api-key',
+		model: 'gpt-5-2'
+	},
+	{
+		onStatusChange: status => console.log('Status change:', status),
+		onActivity: activity => console.log('Activity:', activity),
+		onHistoryUpdate: history => console.log('History update:', history),
+		onDispose: () => console.log('Disposed')
+	}
+)
+
+console.log(result) // Task execution result`
+						}
+						language="javascript"
+					/>
+
+					<h3 className="text-xl font-semibold mt-6 mb-3">window.dispose()</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '停止当前正在运行的任务。停止后 Agent 可以重新使用。'
+							: 'Stop the current running task. The agent can be reused after disposal.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 停止当前任务
+window.dispose()`
+								: `// Stop current task execution
+window.dispose()`
+						}
+						language="javascript"
+					/>
+				</section>
+
+				{/* LLM Config */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">{isZh ? 'LLM 配置' : 'LLM Configuration'}</h2>
+
+					<CodeEditor
+						code={
+							isZh
+								? `interface LLMConfig {
+	baseURL: string   // LLM API 端点
+	apiKey: string    // API 密钥
+	model: string     // 模型名称
+}`
+								: `interface LLMConfig {
+	baseURL: string   // LLM API endpoint
+	apiKey: string    // API key
+	model: string     // Model name
+}`
+						}
+						language="typescript"
+					/>
+				</section>
+
+				{/* Execute Hooks */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">{isZh ? 'Execute Hooks' : 'Execute Hooks'}</h2>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '通过 hooks 参数，你可以监听任务执行过程中的各种事件，实现实时更新 UI、日志记录等功能。'
+							: 'With hooks parameter, you can listen to various events during task execution for real-time UI updates, logging, and more.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `interface ExecuteHooks {
+	// Agent 状态变化时调用（idle, running, error, completed 等）
+	onStatusChange?: (status: AgentStatus) => void
+
+	// Agent 执行活动时调用（如点击、输入、导航等操作）
+	onActivity?: (activity: AgentActivity) => void
+
+	// 历史记录更新时调用（包含完整的事件历史）
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+
+	// Agent 被停止时调用
+	onDispose?: () => void
+}`
+								: `interface ExecuteHooks {
+	// Called when agent status changes (idle, running, error, completed, etc.)
+	onStatusChange?: (status: AgentStatus) => void
+
+	// Called when agent performs an activity (click, input, navigation, etc.)
+	onActivity?: (activity: AgentActivity) => void
+
+	// Called when history is updated (contains full event history)
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+
+	// Called when agent is disposed
+	onDispose?: () => void
+}`
+						}
+						language="typescript"
+					/>
+				</section>
+
+				{/* Security Notice */}
+				<section className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold text-yellow-900 dark:text-yellow-300 mb-2">
+						⚠️ {isZh ? '安全须知' : 'Security Notes'}
+					</h3>
+					<ul className="text-gray-600 dark:text-gray-300 space-y-1 text-sm">
+						<li>
+							•{' '}
+							{isZh
+								? '用户必须在扩展设置中显式授权每个域名'
+								: 'Users must explicitly authorize each domain in extension settings'}
+						</li>
+						<li>
+							•{' '}
+							{isZh
+								? '生产环境建议使用后端代理 LLM API Key'
+								: 'Consider using backend proxy for LLM API keys in production'}
+						</li>
+					</ul>
+				</section>
+
+				{/* Integration Guide */}
+				<section>
+					<h2 className="text-2xl font-bold mb-4">
+						{isZh
+							? '将 MultiPageAgent 融入你自己的插件'
+							: 'Integrate MultiPageAgent into Your Extension'}
+					</h2>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '你可以将 MultiPageAgent 集成到自己的浏览器扩展中，实现跨页面的 AI 自动化能力。'
+							: 'You can integrate MultiPageAgent into your own browser extension for cross-page AI automation capabilities.'}
+					</p>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">TODO</p>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh ? '参考源码实现：' : 'Reference implementation:'}
+					</p>
+					<a
+						href="https://github.com/alibaba/page-agent/blob/main/packages/extension/src/entrypoints/background.ts"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="inline-flex items-center gap-2 text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300"
+					>
+						<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+							<path d={siGithub.path} />
+						</svg>
+						packages/extension/src/entrypoints/background.ts
+					</a>
+				</section>
+			</div>
+		</div>
+	)
+}

packages/website/src/pages/docs/index.tsx

@@ -6,8 +6,9 @@ import DocsLayout from './Layout'
 import PageAgentCoreDocs from './advanced/page-agent-core/page'
 // Advanced
 import PageAgentDocs from './advanced/page-agent/page'
-import Instructions from './features/custom-instructions/page'
 // Features
+import ChromeExtension from './features/chrome-extension/page'
+import Instructions from './features/custom-instructions/page'
 import CustomTools from './features/custom-tools/page'
 import DataMasking from './features/data-masking/page'
 import Models from './features/models/page'
@@ -73,6 +74,11 @@ export default function DocsRouter() {
 					<Models />
 				</DocsPage>
 			</Route>
+			<Route path="/features/chrome-extension">
+				<DocsPage>
+					<ChromeExtension />
+				</DocsPage>
+			</Route>
 
 			{/* Integration */}
 			<Route path="/integration/cdn-setup">

packages/website/src/pages/docs/integration/best-practices/page.tsx

@@ -5,61 +5,10 @@ export default function BestPractices() {
 	return (
 		<div>
 			<h1 className="text-4xl font-bold mb-6">最佳实践</h1>
-
 			<BetaNotice />
-
 			<p className="text-xl text-gray-600 dark:text-gray-300 mb-6 leading-relaxed">
 				使用 page-agent 的最佳实践和常见问题解决方案。
 			</p>
-
-			<h2 className="text-2xl font-bold mb-3">性能优化</h2>
-
-			<div className="space-y-4 mb-6">
-				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
-						⚡ 减少 API 调用
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300 mb-3">
-						合并多个操作指令，减少与 AI 模型的交互次数。
-					</p>
-
-					<CodeEditor
-						code={`// 推荐：合并操作
-await pageAgent.execute('填写表单：姓名张三，邮箱test@example.com，然后提交');
-
-// 不推荐：分别操作
-await pageAgent.execute('填写姓名张三');
-await pageAgent.execute('填写邮箱test@example.com');
-await pageAgent.execute('点击提交按钮');`}
-					/>
-				</div>
-
-				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
-					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
-						🎯 精确的元素描述
-					</h3>
-					<p className="text-gray-600 dark:text-gray-300">
-						使用具体、明确的元素描述，提高操作成功率。
-					</p>
-				</div>
-			</div>
-
-			<h2 className="text-2xl font-bold mb-3">安全建议</h2>
-
-			<div className="space-y-3 mb-6">
-				<div className="p-3 bg-red-50 dark:bg-red-900/20 rounded-lg border-l-4 border-red-500">
-					<h3 className="font-semibold mb-1 text-red-900 dark:text-red-300">重要操作保护</h3>
-					<p className="text-gray-600 dark:text-gray-300">对删除、支付等敏感操作设置黑名单保护。</p>
-				</div>
-
-				<div className="p-3 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg border-l-4 border-yellow-500">
-					<h3 className="font-semibold mb-1 text-yellow-900 dark:text-yellow-300">数据脱敏</h3>
-					<p className="text-gray-600 dark:text-gray-300">启用数据脱敏功能，保护用户隐私信息。</p>
-				</div>
-			</div>
-
-			<h2 className="text-2xl font-bold mb-3">调试技巧</h2>
-
 			<CodeEditor code={`// TODO`} />
 		</div>
 	)