From 55a3ce16e5f471023e728155efaf27e9ebc3ef1a Mon Sep 17 00:00:00 2001 From: Simon <10131203+gaomeng1900@users.noreply.github.com> Date: Tue, 21 Oct 2025 22:02:51 +0800 Subject: [PATCH] feat: update pages --- pages/docs/integration/cdn-setup/page.tsx | 11 +- pages/docs/integration/configuration/page.tsx | 106 ++++++++++++++---- src/config/index.ts | 8 +- 3 files changed, 92 insertions(+), 33 deletions(-) diff --git a/pages/docs/integration/cdn-setup/page.tsx b/pages/docs/integration/cdn-setup/page.tsx index bfa871b..b4eed33 100644 --- a/pages/docs/integration/cdn-setup/page.tsx +++ b/pages/docs/integration/cdn-setup/page.tsx @@ -6,8 +6,6 @@ export default function CdnSetup() {

CDN 引入

- -

通过 CDN 快速集成 page-agent，无需复杂的构建配置。

@@ -16,13 +14,12 @@ export default function CdnSetup() { -// @todo find a cdn - + code={` +// 仅供测试使用，稳定 CDN 待定 + `} /> diff --git a/pages/docs/integration/configuration/page.tsx b/pages/docs/integration/configuration/page.tsx index 4373319..3ebff5a 100644 --- a/pages/docs/integration/configuration/page.tsx +++ b/pages/docs/integration/configuration/page.tsx @@ -1,4 +1,3 @@ -import BetaNotice from '@pages/components/BetaNotice' import CodeEditor from '@pages/components/CodeEditor' export default function Configuration() { @@ -6,33 +5,96 @@ export default function Configuration() {

配置选项

- + - 详细的配置选项说明，帮助你定制 page-agent 的行为。 -

+interface LLMConfig { + baseURL?: string + apiKey?: string + model?: string + temperature?: number + maxTokens?: number + maxRetries?: number +} -

基础配置

+interface AgentConfig { + language?: "en-US" | "zh-CN" - + /** + * Custom tools to extend PageAgent capabilities + * @experimental + * @note You can also override or remove internal tools by using the same name. + * @see [tools](../tools/index.ts) + * + * @example + * // override internal tool + * import { tool } from 'page-agent' + * const customTools = { + * ask_user: tool({ + * description: + * 'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.', + * inputSchema: zod.object({ + * question: zod.string(), + * }), + * execute: async function (this: PageAgent, input) { + * const answer = await do_some_thing(input.question) + * return "✅ Received user answer: " + answer + * }, + * }) + * } + * + * @example + * // remove internal tool + * const customTools = { + * ask_user: null // never ask user questions + * } + */ + customTools?: Record -

高级选项

+ // lifecycle hooks + // @todo: use event instead of hooks -
-
-

- 🎯 元素选择策略 -

-

配置 AI 如何选择和操作页面元素的策略。

-
+ onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise | void + onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise | void + onBeforeTask?: (this: PageAgent) => Promise | void + onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise | void -
-

- ⏱️ 超时设置 -

-

设置操作超时时间，避免长时间等待。

-
-
+ /** + * @note this hook can block the disposal process + * @note when dispose caused by page unload, "reason" will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut. + */ + onDispose?: (this: PageAgent, reason?: string) => void + + // page behavior hooks + + /** + * TODO: @unimplemented + * hook when action causes a new page to be opened + * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable. + */ + onNewPageOpen?: (this: PageAgent, url: string) => Promise | void + + /** + * TODO: @unimplemented + * try to navigate to a new page instead of opening a new tab/window. + * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window. + */ + experimentalPreventNewPage?: boolean +} + +interface DomConfig { + interactiveBlacklist?: (Element | (() => Element))[] + interactiveWhitelist?: (Element | (() => Element))[] + include_attributes?: string[] + highlightOpacity?: number + highlightLabelOpacity?: number +} + +`} + />
) } diff --git a/src/config/index.ts b/src/config/index.ts index 9187afe..a99e239 100644 --- a/src/config/index.ts +++ b/src/config/index.ts @@ -21,7 +21,7 @@ export interface LLMConfig { maxRetries?: number } -export interface UIConfig { +export interface AgentConfig { // theme?: 'light' | 'dark' language?: SupportedLanguage @@ -43,7 +43,7 @@ export interface UIConfig { * }), * execute: async function (this: PageAgent, input) { * const answer = await do_some_thing(input.question) - * return `✅ Received user answer: ${answer}` + * return "✅ Received user answer: " + answer * }, * }) * } @@ -66,7 +66,7 @@ export interface UIConfig { /** * @note this hook can block the disposal process - * @note when dispose caused by page unload, `reason` will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut. + * @note when dispose caused by page unload, reason will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut. */ onDispose?: (this: PageAgent, reason?: string) => void @@ -87,7 +87,7 @@ export interface UIConfig { experimentalPreventNewPage?: boolean } -export type PageAgentConfig = LLMConfig & DomConfig & UIConfig +export type PageAgentConfig = LLMConfig & AgentConfig & DomConfig export function parseLLMConfig(config: LLMConfig): Required { return {