From 53144a802106dd99ce3d54fba3a574e6be8e68e4 Mon Sep 17 00:00:00 2001 From: Simon <10131203+gaomeng1900@users.noreply.github.com> Date: Sat, 14 Feb 2026 15:12:03 +0800 Subject: [PATCH] chore(ext): rm zh doc --- packages/extension/docs/extension_api_zh.md | 226 ------------------ .../docs/features/chrome-extension/page.tsx | 10 +- 2 files changed, 1 insertion(+), 235 deletions(-) delete mode 100644 packages/extension/docs/extension_api_zh.md diff --git a/packages/extension/docs/extension_api_zh.md b/packages/extension/docs/extension_api_zh.md deleted file mode 100644 index 8ad4411..0000000 --- a/packages/extension/docs/extension_api_zh.md +++ /dev/null @@ -1,226 +0,0 @@ -# Page Agent 浏览器插件 API - -在你的网页应用中接入 Page Agent 插件，并通过页面 JavaScript 发起多页面浏览器任务。 - -## 安装 - -### 1. 安装浏览器插件 - -首选渠道： - -- Chrome 应用商店：https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj - -通常更快提供最新构建的渠道： - -- GitHub Releases：https://github.com/alibaba/page-agent/releases - -### 2. 安装类型定义（推荐） - -```bash -npm install @page-agent/core --save-dev -``` - -### 3. 授权（Token） - -token 用于让页面 JS 调用扩展 API（`window.PAGE_AGENT_EXT`）并执行多页面任务。 - -为什么必须使用 token： - -- 插件具备较广的浏览器权限（页面访问、导航、多标签控制）。 -- 若被滥用，可能危害用户隐私与安全。 -- 用户必须主动将 token 提供给其信任的应用。 - -配置步骤： - -1. 在扩展侧边栏中复制 auth token。 -2. 在页面中设置 token： - -```typescript -localStorage.setItem('PageAgentExtUserAuthToken', 'your-token') -``` - -## 快速开始 - -```typescript -import type { - AgentActivity, - AgentStatus, - ExecutionResult, - HistoricalEvent, -} from '@page-agent/core' - -// 等待插件注入（最多 1 秒） -async function waitForExtension(timeout = 1000): Promise { - const start = Date.now() - while (Date.now() - start < timeout) { - if (window.PAGE_AGENT_EXT) return true - await new Promise((r) => setTimeout(r, 100)) - } - return false -} - -// 使用 -if (await waitForExtension()) { - const result = await window.PAGE_AGENT_EXT!.execute('点击登录按钮', { - baseURL: 'https://api.openai.com/v1', - apiKey: 'your-api-key', - model: 'gpt-5.2', - onStatusChange: (status) => console.log('状态:', status), - onActivity: (activity) => console.log('活动:', activity), - }) - console.log('结果:', result) -} -``` - -## 全局 API - -token 匹配后，插件会在 `window` 上注入 API。 - -### `window.PAGE_AGENT_EXT_VERSION` - -插件版本号字符串，可用于在访问主 API 前做能力检查。 - -### `window.PAGE_AGENT_EXT` - -主命名空间对象。 - -#### `PAGE_AGENT_EXT.execute(task, config)` - -执行 Agent 任务。 - -参数： - -| 名称 | 类型 | 必填 | 说明 | -| ---- | ---- | ---- | ---- | -| `task` | `string` | 是 | 任务描述 | -| `config` | `ExecuteConfig` | 是 | LLM 设置、执行选项和回调 | - -返回：`Promise` - -#### `PAGE_AGENT_EXT.stop()` - -停止当前任务。 - -## 类型定义 - -安装 `@page-agent/core` 获取完整类型： - -```typescript -import type { - AgentActivity, - AgentStatus, - ExecutionResult, - HistoricalEvent, -} from '@page-agent/core' - -export interface ExecuteConfig { - baseURL: string - apiKey: string - model: string - - // 是否包含启动脚本所在标签页。默认 true。 - includeInitialTab?: boolean - - onStatusChange?: (status: AgentStatus) => void - onActivity?: (activity: AgentActivity) => void - onHistoryUpdate?: (history: HistoricalEvent[]) => void -} - -export type Execute = (task: string, config: ExecuteConfig) => Promise -``` - -`AgentStatus` - -```typescript -type AgentStatus = 'idle' | 'running' | 'completed' | 'error' -``` - -`AgentActivity` - -```typescript -type AgentActivity = - | { type: 'thinking' } - | { type: 'executing'; tool: string; input: unknown } - | { type: 'executed'; tool: string; input: unknown; output: string; duration: number } - | { type: 'retrying'; attempt: number; maxAttempts: number } - | { type: 'error'; message: string } -``` - -`HistoricalEvent` - -```typescript -type HistoricalEvent = - | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action } - | { type: 'observation'; content: string } - | { type: 'user_takeover' } - | { type: 'retry'; message: string; attempt: number; maxAttempts: number } - | { type: 'error'; message: string; rawResponse?: unknown } -``` - -`ExecutionResult` - -```typescript -interface ExecutionResult { - success: boolean - data: string - history: HistoricalEvent[] -} -``` - -## 使用示例 - -### 基础执行 - -```typescript -const result = await window.PAGE_AGENT_EXT!.execute( - '在邮箱输入框填入 test@example.com 然后点击提交', - { - baseURL: 'https://api.openai.com/v1', - apiKey: process.env.OPENAI_API_KEY!, - model: 'gpt-5.2', - includeInitialTab: false, // 可选：排除当前标签页 - onStatusChange: (status) => console.log(status), - onActivity: (activity) => console.log(activity), - } -) -``` - -### 停止当前任务 - -```typescript -window.PAGE_AGENT_EXT!.stop() -``` - -## Window 类型声明 - -如果你不直接引入 `@page-agent/core`，可添加以下声明： - -```typescript -import type { - AgentActivity, - AgentStatus, - ExecutionResult, - HistoricalEvent, -} from '@page-agent/core' - -interface ExecuteConfig { - baseURL: string - apiKey: string - model: string - includeInitialTab?: boolean - onStatusChange?: (status: AgentStatus) => void - onActivity?: (activity: AgentActivity) => void - onHistoryUpdate?: (history: HistoricalEvent[]) => void -} - -declare global { - interface Window { - PAGE_AGENT_EXT_VERSION?: string - PAGE_AGENT_EXT?: { - version: string - execute: Execute - stop: () => void - } - } -} -``` diff --git a/packages/website/src/pages/docs/features/chrome-extension/page.tsx b/packages/website/src/pages/docs/features/chrome-extension/page.tsx index 0bf8fe4..f58b197 100644 --- a/packages/website/src/pages/docs/features/chrome-extension/page.tsx +++ b/packages/website/src/pages/docs/features/chrome-extension/page.tsx @@ -164,15 +164,7 @@ localStorage.setItem('PageAgentExtUserAuthToken', '') rel="noopener noreferrer" className="block text-sm text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300 hover:underline" > - 📄 {isZh ? '英文版 API 文档' : 'API Documentation (English)'} - - - 📄 {isZh ? '中文版 API 文档' : 'API Documentation (Chinese)'} + 📄 {isZh ? 'API 文档' : 'API Documentation'}