Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Simon
|
67f6a56a87 | ||
|
Simon
|
6f0ff1fd33 | ||
|
Simon
|
6fdb8d03f2 |
+3
-3
@@ -40,7 +40,7 @@
|
||||
|
||||
```html
|
||||
<script
|
||||
src="https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js"
|
||||
src="https://registry.npmmirror.com/page-agent/1.1.2/files/dist/iife/page-agent.demo.js"
|
||||
crossorigin="true"
|
||||
></script>
|
||||
```
|
||||
@@ -50,8 +50,8 @@
|
||||
|
||||
| Mirrors | URL |
|
||||
| ------- | ---------------------------------------------------------------------------------- |
|
||||
| Global | https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js |
|
||||
| China | https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js |
|
||||
| Global | https://cdn.jsdelivr.net/npm/page-agent@1.1.2/dist/iife/page-agent.demo.js |
|
||||
| China | https://registry.npmmirror.com/page-agent/1.1.2/files/dist/iife/page-agent.demo.js |
|
||||
|
||||
### NPM 安装
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ Fastest way to try PageAgent with our free Demo LLM:
|
||||
|
||||
```html
|
||||
<script
|
||||
src="https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js"
|
||||
src="https://cdn.jsdelivr.net/npm/page-agent@1.1.2/dist/iife/page-agent.demo.js"
|
||||
crossorigin="true"
|
||||
></script>
|
||||
```
|
||||
@@ -50,8 +50,8 @@ Fastest way to try PageAgent with our free Demo LLM:
|
||||
|
||||
| Mirrors | URL |
|
||||
| ------- | ---------------------------------------------------------------------------------- |
|
||||
| Global | https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js |
|
||||
| China | https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js |
|
||||
| Global | https://cdn.jsdelivr.net/npm/page-agent@1.1.2/dist/iife/page-agent.demo.js |
|
||||
| China | https://registry.npmmirror.com/page-agent/1.1.2/files/dist/iife/page-agent.demo.js |
|
||||
|
||||
### NPM Installation
|
||||
|
||||
|
||||
Generated
+29
-18
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "root",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "root",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT",
|
||||
"workspaces": [
|
||||
"packages/page-controller",
|
||||
@@ -41,6 +41,7 @@
|
||||
"typescript-eslint": "^8.54.0",
|
||||
"unplugin-dts": "^1.0.0-beta.6",
|
||||
"vite": "^7.3.1",
|
||||
"vite-bundle-analyzer": "^1.3.6",
|
||||
"vite-plugin-css-injected-by-js": "^3.5.2"
|
||||
},
|
||||
"engines": {
|
||||
@@ -10411,6 +10412,16 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"node_modules/vite-bundle-analyzer": {
|
||||
"version": "1.3.6",
|
||||
"resolved": "https://registry.npmjs.org/vite-bundle-analyzer/-/vite-bundle-analyzer-1.3.6.tgz",
|
||||
"integrity": "sha512-elFXkF9oGy4CJEeOdP1DSEHRDKWfmaEDfT9/GuF4jmyfmUF6nC//iN+ythqMEVvrtchOEHGKLumZwnu1NjoI0w==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"analyze": "dist/bin.js"
|
||||
}
|
||||
},
|
||||
"node_modules/vite-node": {
|
||||
"version": "5.3.0",
|
||||
"resolved": "https://registry.npmjs.org/vite-node/-/vite-node-5.3.0.tgz",
|
||||
@@ -11049,11 +11060,11 @@
|
||||
},
|
||||
"packages/core": {
|
||||
"name": "@page-agent/core",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1",
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2",
|
||||
"chalk": "^5.6.2",
|
||||
"zod": "^4.3.5"
|
||||
}
|
||||
@@ -11063,10 +11074,10 @@
|
||||
"version": "0.1.3",
|
||||
"hasInstallScript": true,
|
||||
"dependencies": {
|
||||
"@page-agent/core": "1.1.1",
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1",
|
||||
"@page-agent/ui": "1.1.1",
|
||||
"@page-agent/core": "1.1.2",
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2",
|
||||
"@page-agent/ui": "1.1.2",
|
||||
"@radix-ui/react-hover-card": "^1.1.15",
|
||||
"@radix-ui/react-icons": "^1.3.2",
|
||||
"@radix-ui/react-label": "^2.1.8",
|
||||
@@ -11100,7 +11111,7 @@
|
||||
},
|
||||
"packages/llms": {
|
||||
"name": "@page-agent/llms",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"chalk": "^5.6.2",
|
||||
@@ -11108,20 +11119,20 @@
|
||||
}
|
||||
},
|
||||
"packages/page-agent": {
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@page-agent/core": "1.1.1",
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1",
|
||||
"@page-agent/ui": "1.1.1",
|
||||
"@page-agent/core": "1.1.2",
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2",
|
||||
"@page-agent/ui": "1.1.2",
|
||||
"chalk": "^5.6.2",
|
||||
"zod": "^4.3.5"
|
||||
}
|
||||
},
|
||||
"packages/page-controller": {
|
||||
"name": "@page-agent/page-controller",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"ai-motion": "^0.4.8"
|
||||
@@ -11129,12 +11140,12 @@
|
||||
},
|
||||
"packages/ui": {
|
||||
"name": "@page-agent/ui",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"license": "MIT"
|
||||
},
|
||||
"packages/website": {
|
||||
"name": "@page-agent/website",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"dependencies": {
|
||||
"@radix-ui/react-icons": "^1.3.2",
|
||||
"@radix-ui/react-separator": "^1.1.8",
|
||||
|
||||
+3
-2
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "root",
|
||||
"private": true,
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"workspaces": [
|
||||
"packages/page-controller",
|
||||
@@ -59,7 +59,8 @@
|
||||
"typescript-eslint": "^8.54.0",
|
||||
"unplugin-dts": "^1.0.0-beta.6",
|
||||
"vite": "^7.3.1",
|
||||
"vite-plugin-css-injected-by-js": "^3.5.2"
|
||||
"vite-plugin-css-injected-by-js": "^3.5.2",
|
||||
"vite-bundle-analyzer": "^1.3.6"
|
||||
},
|
||||
"overrides": {
|
||||
"typescript": "^5.9.3"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@page-agent/core",
|
||||
"private": false,
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"main": "./dist/esm/page-agent-core.js",
|
||||
"module": "./dist/esm/page-agent-core.js",
|
||||
@@ -45,7 +45,7 @@
|
||||
"dependencies": {
|
||||
"chalk": "^5.6.2",
|
||||
"zod": "^4.3.5",
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1"
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -5,13 +5,13 @@
|
||||
import { InvokeError, LLM, type Tool } from '@page-agent/llms'
|
||||
import type { PageController } from '@page-agent/page-controller'
|
||||
import chalk from 'chalk'
|
||||
import zod from 'zod'
|
||||
import * as zod from 'zod'
|
||||
|
||||
import { type PageAgentConfig } from './config'
|
||||
import { DEFAULT_MAX_STEPS } from './config/constants'
|
||||
import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
|
||||
import { tools } from './tools'
|
||||
import {
|
||||
import type {
|
||||
AgentActivity,
|
||||
AgentReflection,
|
||||
AgentStatus,
|
||||
@@ -21,8 +21,7 @@ import {
|
||||
MacroToolInput,
|
||||
MacroToolResult,
|
||||
} from './types'
|
||||
import { normalizeResponse, trimLines, uid, waitFor } from './utils'
|
||||
import { assert } from './utils/assert'
|
||||
import { assert, normalizeResponse, trimLines, uid, waitFor } from './utils'
|
||||
|
||||
export { type PageAgentConfig }
|
||||
export { tool, type PageAgentTool } from './tools'
|
||||
@@ -209,20 +208,20 @@ export class PageAgentCore extends EventTarget {
|
||||
lastURL: '',
|
||||
}
|
||||
|
||||
try {
|
||||
let step = 0
|
||||
let step = 0
|
||||
|
||||
while (true) {
|
||||
try {
|
||||
console.group(`step: ${step}`)
|
||||
|
||||
while (true) {
|
||||
await this.#generateObservations(step)
|
||||
|
||||
await onBeforeStep?.(this, step)
|
||||
|
||||
console.group(`step: ${step}`)
|
||||
|
||||
// abort
|
||||
if (this.#abortController.signal.aborted) throw new Error('AbortError')
|
||||
|
||||
// Thinking
|
||||
// status
|
||||
console.log(chalk.blue('Thinking...'))
|
||||
this.#emitActivity({ type: 'thinking' })
|
||||
|
||||
@@ -270,22 +269,13 @@ export class PageAgentCore extends EventTarget {
|
||||
|
||||
//
|
||||
|
||||
await onAfterStep?.(this, this.history)
|
||||
|
||||
console.log(chalk.green('Step finished:'), actionName)
|
||||
console.groupEnd()
|
||||
|
||||
await onAfterStep?.(this, this.history)
|
||||
// finish task if done
|
||||
|
||||
step++
|
||||
if (step > this.config.maxSteps) {
|
||||
this.#onDone(false)
|
||||
const result: ExecutionResult = {
|
||||
success: false,
|
||||
data: 'Step count exceeded maximum limit',
|
||||
history: this.history,
|
||||
}
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
if (actionName === 'done') {
|
||||
const success = action.input?.success ?? false
|
||||
const text = action.input?.text || 'no text provided'
|
||||
@@ -299,19 +289,32 @@ export class PageAgentCore extends EventTarget {
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
console.groupEnd() // to prevent nested groups
|
||||
console.error('Task failed', error)
|
||||
const errorMessage = String(error)
|
||||
this.#emitActivity({ type: 'error', message: errorMessage })
|
||||
this.#onDone(false)
|
||||
const result: ExecutionResult = {
|
||||
success: false,
|
||||
data: errorMessage,
|
||||
history: this.history,
|
||||
}
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
console.error('Task failed', error)
|
||||
const errorMessage = String(error)
|
||||
this.#emitActivity({ type: 'error', message: errorMessage })
|
||||
this.#onDone(false)
|
||||
const result: ExecutionResult = {
|
||||
success: false,
|
||||
data: errorMessage,
|
||||
history: this.history,
|
||||
|
||||
step++
|
||||
if (step > this.config.maxSteps) {
|
||||
this.#onDone(false)
|
||||
const result: ExecutionResult = {
|
||||
success: false,
|
||||
data: 'Step count exceeded maximum limit',
|
||||
history: this.history,
|
||||
}
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
* Internal tools for PageAgent.
|
||||
* @note Adapted from browser-use
|
||||
*/
|
||||
import zod, { type z } from 'zod'
|
||||
import * as zod from 'zod'
|
||||
|
||||
import type { PageAgentCore } from '../PageAgentCore'
|
||||
import { waitFor } from '../utils'
|
||||
@@ -13,7 +13,7 @@ import { waitFor } from '../utils'
|
||||
export interface PageAgentTool<TParams = any> {
|
||||
// name: string
|
||||
description: string
|
||||
inputSchema: z.ZodType<TParams>
|
||||
inputSchema: zod.ZodType<TParams>
|
||||
execute: (this: PageAgentCore, args: TParams) => Promise<string>
|
||||
}
|
||||
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
import chalk from 'chalk'
|
||||
|
||||
/**
|
||||
* Simple assertion function that throws an error if the condition is falsy
|
||||
* @param condition - The condition to assert
|
||||
* @param message - Optional error message
|
||||
* @throws Error if condition is falsy
|
||||
*/
|
||||
export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
|
||||
if (!condition) {
|
||||
const errorMessage = message ?? 'Assertion failed'
|
||||
|
||||
if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
|
||||
|
||||
throw new Error(errorMessage)
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,5 @@
|
||||
import chalk from 'chalk'
|
||||
|
||||
export { normalizeResponse } from './autoFixer'
|
||||
|
||||
/**
|
||||
@@ -85,3 +87,19 @@ export function uid() {
|
||||
ids.push(id)
|
||||
return id
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple assertion function that throws an error if the condition is falsy
|
||||
* @param condition - The condition to assert
|
||||
* @param message - Optional error message
|
||||
* @throws Error if condition is falsy
|
||||
*/
|
||||
export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
|
||||
if (!condition) {
|
||||
const errorMessage = message ?? 'Assertion failed'
|
||||
|
||||
if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
|
||||
|
||||
throw new Error(errorMessage)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -23,10 +23,10 @@
|
||||
"wxt": "^0.20.13"
|
||||
},
|
||||
"dependencies": {
|
||||
"@page-agent/core": "1.1.1",
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1",
|
||||
"@page-agent/ui": "1.1.1",
|
||||
"@page-agent/core": "1.1.2",
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2",
|
||||
"@page-agent/ui": "1.1.2",
|
||||
"@radix-ui/react-hover-card": "^1.1.15",
|
||||
"@radix-ui/react-icons": "^1.3.2",
|
||||
"@radix-ui/react-label": "^2.1.8",
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
* - switch_to_tab: Switch to an existing tab
|
||||
* - close_tab: Close a tab (optionally switch to another)
|
||||
*/
|
||||
import zod from 'zod'
|
||||
import * as zod from 'zod'
|
||||
|
||||
import type { TabsController } from './TabsController'
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@page-agent/llms",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"main": "./dist/lib/page-agent-llms.js",
|
||||
"module": "./dist/lib/page-agent-llms.js",
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
* Utility functions for LLM integration
|
||||
*/
|
||||
import chalk from 'chalk'
|
||||
import { z } from 'zod'
|
||||
import * as z from 'zod'
|
||||
|
||||
import type { Tool } from './types'
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "page-agent",
|
||||
"private": false,
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"main": "./dist/esm/page-agent.js",
|
||||
"module": "./dist/esm/page-agent.js",
|
||||
@@ -44,11 +44,11 @@
|
||||
"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
|
||||
},
|
||||
"dependencies": {
|
||||
"@page-agent/core": "1.1.2",
|
||||
"@page-agent/llms": "1.1.2",
|
||||
"@page-agent/page-controller": "1.1.2",
|
||||
"@page-agent/ui": "1.1.2",
|
||||
"chalk": "^5.6.2",
|
||||
"zod": "^4.3.5",
|
||||
"@page-agent/llms": "1.1.1",
|
||||
"@page-agent/page-controller": "1.1.1",
|
||||
"@page-agent/core": "1.1.1",
|
||||
"@page-agent/ui": "1.1.1"
|
||||
"zod": "^4.3.5"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,6 +3,7 @@ import { config as dotenvConfig } from 'dotenv'
|
||||
import { dirname, resolve } from 'path'
|
||||
import { fileURLToPath } from 'url'
|
||||
import { defineConfig } from 'vite'
|
||||
// import { analyzer } from 'vite-bundle-analyzer'
|
||||
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url))
|
||||
@@ -14,8 +15,11 @@ dotenvConfig({ path: resolve(__dirname, '../../.env') })
|
||||
// - alias all local packages so that they can be build in
|
||||
// - no external
|
||||
// - no d.ts. dts does not work with monorepo aliasing
|
||||
export default defineConfig(({ mode }) => ({
|
||||
plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
|
||||
export default defineConfig(() => ({
|
||||
plugins: [
|
||||
cssInjectedByJsPlugin({ relativeCSSInjection: true }),
|
||||
// analyzer()
|
||||
],
|
||||
publicDir: false,
|
||||
esbuild: {
|
||||
keepNames: true,
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@page-agent/page-controller",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"main": "./dist/lib/page-controller.js",
|
||||
"module": "./dist/lib/page-controller.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@page-agent/ui",
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"main": "./dist/lib/page-agent-ui.js",
|
||||
"module": "./dist/lib/page-agent-ui.js",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@page-agent/website",
|
||||
"private": true,
|
||||
"version": "1.1.1",
|
||||
"version": "1.1.2",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite --host 0.0.0.0",
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
// Demo build (auto-init with demo LLM, for quick testing)
|
||||
export const CDN_DEMO_URL =
|
||||
'https://cdn.jsdelivr.net/npm/page-agent@1.1.1/dist/iife/page-agent.demo.js'
|
||||
'https://cdn.jsdelivr.net/npm/page-agent@1.1.2/dist/iife/page-agent.demo.js'
|
||||
export const CDN_DEMO_CN_URL =
|
||||
'https://registry.npmmirror.com/page-agent/1.1.1/files/dist/iife/page-agent.demo.js'
|
||||
'https://registry.npmmirror.com/page-agent/1.1.2/files/dist/iife/page-agent.demo.js'
|
||||
|
||||
// Demo LLM for website testing
|
||||
export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
|
||||
|
||||
@@ -30,6 +30,10 @@ export default function DocsLayout({ children }: DocsLayoutProps) {
|
||||
{ title: isZh ? '概览' : 'Overview', path: '/introduction/overview' },
|
||||
{ title: isZh ? '快速开始' : 'Quick Start', path: '/introduction/quick-start' },
|
||||
{ title: isZh ? '使用限制' : 'Limitations', path: '/introduction/limitations' },
|
||||
{
|
||||
title: isZh ? '故障排查' : 'Troubleshooting',
|
||||
path: '/introduction/troubleshooting',
|
||||
},
|
||||
{
|
||||
title: '🚧 ' + (isZh ? '最佳实践' : 'Best Practices'),
|
||||
path: '/integration/best-practices',
|
||||
|
||||
@@ -25,7 +25,7 @@ export default function CustomTools() {
|
||||
</p>
|
||||
|
||||
<CodeEditor
|
||||
code={`import zod from 'zod'
|
||||
code={`import * as zod from 'zod'
|
||||
import { PageAgent, tool } from 'page-agent'
|
||||
|
||||
// override internal tool
|
||||
|
||||
@@ -20,6 +20,7 @@ import Limitations from './introduction/limitations/page'
|
||||
// Introduction
|
||||
import Overview from './introduction/overview/page'
|
||||
import QuickStart from './introduction/quick-start/page'
|
||||
import Troubleshooting from './introduction/troubleshooting/page'
|
||||
|
||||
function DocsPage({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
@@ -51,6 +52,11 @@ export default function DocsRouter() {
|
||||
<Limitations />
|
||||
</DocsPage>
|
||||
</Route>
|
||||
<Route path="/introduction/troubleshooting">
|
||||
<DocsPage>
|
||||
<Troubleshooting />
|
||||
</DocsPage>
|
||||
</Route>
|
||||
|
||||
{/* Features */}
|
||||
<Route path="/features/custom-tools">
|
||||
|
||||
@@ -0,0 +1,424 @@
|
||||
import { useEffect, useRef, useState } from 'react'
|
||||
import { Link } from 'wouter'
|
||||
|
||||
import CodeEditor from '@/components/CodeEditor'
|
||||
import { useLanguage } from '@/i18n/context'
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Data: each section is a typed object for easy extension
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
interface TroubleshootingSection {
|
||||
id: string
|
||||
title: { en: string; zh: string }
|
||||
symptom: { en: string; zh: string }
|
||||
color: 'red' | 'amber' | 'orange' | 'violet'
|
||||
content: (isZh: boolean) => React.ReactNode
|
||||
}
|
||||
|
||||
const SECTIONS: TroubleshootingSection[] = [
|
||||
{
|
||||
id: 'format-errors',
|
||||
title: { en: 'Model Response Format Errors', zh: '模型返回格式错误' },
|
||||
symptom: {
|
||||
en: 'The model returns malformed tool calls, plain text, or unexpected JSON instead of structured actions.',
|
||||
zh: '模型返回了格式错误的 tool call、纯文本或非预期的 JSON，而非结构化的操作指令。',
|
||||
},
|
||||
color: 'amber',
|
||||
content: FormatErrorsContent,
|
||||
},
|
||||
{
|
||||
id: 'low-success-rate',
|
||||
title: { en: 'Low Task Success Rate', zh: '任务成功率低' },
|
||||
symptom: {
|
||||
en: 'The agent appears to understand the task but frequently fails to complete it, or produces incorrect results.',
|
||||
zh: 'Agent 似乎理解了任务，但频繁执行失败或产生不正确的结果。',
|
||||
},
|
||||
color: 'amber',
|
||||
content: LowSuccessRateContent,
|
||||
},
|
||||
{
|
||||
id: 'wrong-element',
|
||||
title: { en: "Can't Hit Target Elements", zh: '无法点击目标元素' },
|
||||
symptom: {
|
||||
en: 'The agent repeatedly retries but keeps interacting with the wrong element, or fails to locate the correct one.',
|
||||
zh: 'Agent 反复重试，但始终点击在错误的元素上，或无法定位到正确的目标元素。',
|
||||
},
|
||||
color: 'amber',
|
||||
content: WrongElementContent,
|
||||
},
|
||||
{
|
||||
id: 'api-errors',
|
||||
title: { en: 'API Request Errors', zh: 'API 请求错误' },
|
||||
symptom: {
|
||||
en: 'HTTP 400 Bad Request or similar errors when calling the LLM API.',
|
||||
zh: '调用 LLM API 时出现 HTTP 400 Bad Request 或类似的参数错误。',
|
||||
},
|
||||
color: 'amber',
|
||||
content: ApiErrorsContent,
|
||||
},
|
||||
]
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Section content components
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function FormatErrorsContent(isZh: boolean) {
|
||||
return (
|
||||
<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
|
||||
<li>
|
||||
<strong>{isZh ? '确认模型是否支持' : 'Verify model compatibility'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '并非所有模型都能正确处理 page-agent 的 tool 定义。请查看'
|
||||
: 'Not all models can handle page-agent tool definitions correctly. Check the '}
|
||||
<Link
|
||||
href="/features/models"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
{isZh ? '已测试模型列表' : 'tested models list'}
|
||||
</Link>
|
||||
{isZh ? '。' : '.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>
|
||||
{isZh ? '检查代理/网关的参数转发' : 'Check proxy/gateway parameter forwarding'}
|
||||
</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '如果使用了 API 代理或网关，请确保请求中的 '
|
||||
: 'If using an API proxy or gateway, make sure the '}
|
||||
<code>tools</code>
|
||||
{isZh
|
||||
? ' 字段被完整、无修改地转发给模型供应商。部分代理可能会剥离或修改此字段。'
|
||||
: ' parameter is forwarded to the model provider intact. Some proxies may strip or alter this field.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '寻求社区帮助' : 'Get community help'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh ? (
|
||||
<>
|
||||
如果以上步骤无法解决问题，欢迎在{' '}
|
||||
<a
|
||||
href="https://github.com/alibaba/page-agent/discussions"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
GitHub Discussions
|
||||
</a>{' '}
|
||||
中反馈，附上模型名称和错误信息。
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
If the above steps don't help, join the{' '}
|
||||
<a
|
||||
href="https://github.com/alibaba/page-agent/discussions"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
GitHub Discussions
|
||||
</a>{' '}
|
||||
with your model name and error details.
|
||||
</>
|
||||
)}
|
||||
</p>
|
||||
</li>
|
||||
</ol>
|
||||
)
|
||||
}
|
||||
|
||||
function LowSuccessRateContent(isZh: boolean) {
|
||||
return (
|
||||
<>
|
||||
<p className="text-sm text-gray-500 dark:text-gray-400 mb-4 italic">
|
||||
{isZh
|
||||
? '按以下顺序逐步排查，从最简单的情况开始：'
|
||||
: 'Follow this diagnostic funnel from simplest to most advanced:'}
|
||||
</p>
|
||||
<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
|
||||
<li>
|
||||
<strong>{isZh ? '先从简单指令开始' : 'Start with a simple instruction'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '给一个具体的、单步的简单指令（如"点击登录按钮"），看 Agent 能否完成。如果连简单操作都失败了，问题可能不在模型能力上。'
|
||||
: 'Give a concrete, single-step instruction (e.g. "click the login button"). If even simple actions fail, the issue is likely not model capability.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '尝试最强模型' : 'Try the strongest model available'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '切换到你能获取到的最先进、最大的模型，以排除是否是模型智能水平不足导致的问题。'
|
||||
: "Switch to the most capable model you have access to, to isolate whether it's a model intelligence issue."}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '优化指令质量' : 'Improve instruction quality'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '给出尽可能具体的指令。对于复杂任务，建议使用另一个 LLM 来预先拆分和细化用户的需求，然后逐步执行。'
|
||||
: "Be as specific as possible. For complex tasks, consider using another LLM to decompose and refine the user's request before execution."}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '提供充足的上下文' : 'Provide sufficient context'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '通过 instructions 配置注入网站背景描述、关键术语解释等上下文信息，帮助 Agent 更好地理解页面。'
|
||||
: 'Use the instructions config to inject website descriptions, key terminology, and background context to help the agent understand the page.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '检查 HTML 清洗结果' : 'Check HTML sanitization output'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '使用开发者工具检查清洗后的 HTML，确认关键信息、文本和可操作元素是否被正确保留。'
|
||||
: 'Inspect the sanitized HTML in dev tools to confirm that key information, text, and interactive elements are preserved correctly.'}
|
||||
</p>
|
||||
</li>
|
||||
</ol>
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
function WrongElementContent(isZh: boolean) {
|
||||
return (
|
||||
<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
|
||||
<li>
|
||||
<strong>{isZh ? '了解现实局限' : 'Understand the reality'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '并非所有网站都提供了完善的语义化 HTML 和 accessibility 标签。对于此类网站，DOM 清洗可能无法产出足够好的结果。'
|
||||
: 'Not all websites provide proper semantic HTML and accessibility labels. For such sites, DOM sanitization may not produce good enough results.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '检查目标元素类型' : 'Check target element type'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '确认目标元素是否为图片、Canvas、或需要复杂交互（如拖拽、基于坐标的点击）的元素。这些本身就超出了当前的能力范围。'
|
||||
: 'Verify if the target is an image, Canvas, or requires complex interactions (drag-and-drop, coordinate-based clicking). These are beyond current capabilities.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '检查清洗后的 HTML' : 'Inspect sanitized HTML'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '检查清洗结果中是否存在关键信息丢失、可操作元素未被编号等问题。'
|
||||
: 'Look for missing key information or unnumbered interactive elements in the sanitized output.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '注入 accessibility 增强' : 'Inject accessibility improvements'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh
|
||||
? '通过注入脚本为网站添加 aria-label、语义化标签等 accessibility 属性，改善 DOM 清洗质量。'
|
||||
: 'Inject scripts to add aria-labels, semantic attributes, and other a11y improvements to enhance DOM sanitization quality.'}
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<strong>{isZh ? '开发专用 Tool' : 'Build a custom Tool'}</strong>
|
||||
<p className="mt-1">
|
||||
{isZh ? (
|
||||
<>
|
||||
对于特定的、持续难以操作的元素，考虑开发{' '}
|
||||
<Link
|
||||
href="/features/custom-tools"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
自定义 Tool
|
||||
</Link>{' '}
|
||||
来直接操作这些元素。
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
For consistently difficult elements, consider building a{' '}
|
||||
<Link
|
||||
href="/features/custom-tools"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
custom Tool
|
||||
</Link>{' '}
|
||||
to interact with them directly.
|
||||
</>
|
||||
)}
|
||||
</p>
|
||||
</li>
|
||||
</ol>
|
||||
)
|
||||
}
|
||||
|
||||
function ApiErrorsContent(isZh: boolean) {
|
||||
return (
|
||||
<div className="space-y-4 text-gray-700 dark:text-gray-300">
|
||||
<p>
|
||||
{isZh
|
||||
? '一些 LLM 供应商使用了与 OpenAI 不完全兼容的参数格式，导致请求参数校验失败。'
|
||||
: 'Some LLM providers use parameter formats that are not fully compatible with the OpenAI spec, causing request validation failures.'}
|
||||
</p>
|
||||
<div className="bg-gray-50 dark:bg-gray-800/50 rounded-lg p-4">
|
||||
<p className="font-medium mb-2">
|
||||
{isZh ? '解决方案：使用 customFetch' : 'Solution: use customFetch'}
|
||||
</p>
|
||||
<p className="text-sm mb-3">
|
||||
{isZh
|
||||
? '通过 customFetch 配置拦截请求，在发送前调整参数格式以适配目标供应商的要求。'
|
||||
: 'Use the customFetch config to intercept requests and adapt parameters before sending them to the target provider.'}
|
||||
</p>
|
||||
<CodeEditor
|
||||
code={`const agent = new PageAgent({
|
||||
// ...
|
||||
customFetch: async (url, init) => {
|
||||
const body = JSON.parse(init.body)
|
||||
// Adapt parameters for your provider
|
||||
delete body.stream_options
|
||||
return fetch(url, { ...init, body: JSON.stringify(body) })
|
||||
},
|
||||
})`}
|
||||
/>
|
||||
</div>
|
||||
<p className="text-sm">
|
||||
{isZh ? '参见 ' : 'See '}
|
||||
<Link
|
||||
href="/advanced/page-agent-core"
|
||||
className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
|
||||
>
|
||||
PageAgentCore API
|
||||
</Link>
|
||||
{isZh ? ' 了解 customFetch 的完整用法。' : ' for full customFetch documentation.'}
|
||||
</p>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Color mapping for symptom callouts
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const SYMPTOM_COLORS = {
|
||||
red: 'border-red-400 bg-red-50 dark:bg-red-900/15 text-red-800 dark:text-red-200',
|
||||
amber: 'border-amber-400 bg-amber-50 dark:bg-amber-900/15 text-amber-800 dark:text-amber-200',
|
||||
orange:
|
||||
'border-orange-400 bg-orange-50 dark:bg-orange-900/15 text-orange-800 dark:text-orange-200',
|
||||
violet:
|
||||
'border-violet-400 bg-violet-50 dark:bg-violet-900/15 text-violet-800 dark:text-violet-200',
|
||||
} as const
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Right-side TOC with IntersectionObserver
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function useActiveSection(ids: string[]) {
|
||||
const [activeId, setActiveId] = useState(ids[0])
|
||||
const observerRef = useRef<IntersectionObserver | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
observerRef.current?.disconnect()
|
||||
|
||||
const visibleEntries = new Map<string, number>()
|
||||
|
||||
observerRef.current = new IntersectionObserver(
|
||||
(entries) => {
|
||||
for (const entry of entries) {
|
||||
if (entry.isIntersecting) {
|
||||
visibleEntries.set(entry.target.id, entry.intersectionRatio)
|
||||
} else {
|
||||
visibleEntries.delete(entry.target.id)
|
||||
}
|
||||
}
|
||||
// Pick the first visible section in document order
|
||||
const firstVisible = ids.find((id) => visibleEntries.has(id))
|
||||
if (firstVisible) setActiveId(firstVisible)
|
||||
},
|
||||
{ rootMargin: '-80px 0px -60% 0px', threshold: [0, 0.25] }
|
||||
)
|
||||
|
||||
for (const id of ids) {
|
||||
const el = document.getElementById(id)
|
||||
if (el) observerRef.current.observe(el)
|
||||
}
|
||||
|
||||
return () => observerRef.current?.disconnect()
|
||||
}, [ids])
|
||||
|
||||
return activeId
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Page component
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export default function TroubleshootingPage() {
|
||||
const { isZh } = useLanguage()
|
||||
const sectionIds = SECTIONS.map((s) => s.id)
|
||||
const activeId = useActiveSection(sectionIds)
|
||||
|
||||
return (
|
||||
<div className="max-w-5xl mx-auto">
|
||||
{/* Header */}
|
||||
<div className="mb-10">
|
||||
<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">Troubleshooting</h1>
|
||||
</div>
|
||||
|
||||
{/* Two-column: content + TOC */}
|
||||
<div className="flex gap-8">
|
||||
{/* Main content */}
|
||||
<div className="flex-1 min-w-0 space-y-12">
|
||||
{SECTIONS.map((section) => (
|
||||
<section key={section.id} id={section.id} className="scroll-mt-24">
|
||||
<h2 className="text-2xl font-bold mb-4 text-gray-900 dark:text-white">
|
||||
{isZh ? section.title.zh : section.title.en}
|
||||
</h2>
|
||||
|
||||
{/* Symptom callout */}
|
||||
<div
|
||||
className={`border-l-4 px-4 py-3 rounded-r-lg mb-6 ${SYMPTOM_COLORS[section.color]}`}
|
||||
>
|
||||
<span className="text-xs font-semibold uppercase tracking-wider opacity-70">
|
||||
{isZh ? '症状' : 'Symptom'}
|
||||
</span>
|
||||
<p className="mt-1 text-sm">{isZh ? section.symptom.zh : section.symptom.en}</p>
|
||||
</div>
|
||||
|
||||
{/* Diagnostic steps */}
|
||||
<div className="prose-sm">{section.content(isZh)}</div>
|
||||
</section>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* Right TOC */}
|
||||
<aside className="hidden lg:block w-48 shrink-0">
|
||||
<div className="sticky top-24">
|
||||
<h4 className="text-xs font-semibold text-gray-400 dark:text-gray-500 uppercase tracking-wider mb-3">
|
||||
{isZh ? '目录' : 'On this page'}
|
||||
</h4>
|
||||
<nav className="space-y-1">
|
||||
{SECTIONS.map((section) => (
|
||||
<button
|
||||
key={section.id}
|
||||
type="button"
|
||||
onClick={() =>
|
||||
document
|
||||
.getElementById(section.id)
|
||||
?.scrollIntoView({ behavior: 'smooth', block: 'start' })
|
||||
}
|
||||
className={`block text-sm py-1 text-left transition-colors ${
|
||||
activeId === section.id
|
||||
? 'text-blue-600 dark:text-blue-400 font-medium'
|
||||
: 'text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'
|
||||
}`}
|
||||
>
|
||||
{isZh ? section.title.zh : section.title.en}
|
||||
</button>
|
||||
))}
|
||||
</nav>
|
||||
</div>
|
||||
</aside>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
Reference in New Issue
Block a user