@coolkiller007/my-page-agent 0.1.13 → 0.1.15

package/dist/index.d.ts

@@ -6,13 +6,13 @@ declare interface ActionResult {
 }
 
 /**
- * Agent activity - transient state for immediate UI feedback.
+ * Agent 活动 - 用于即时 UI 反馈的瞬态状态。
  *
- * Unlike historical events (which are persisted), activities are ephemeral
- * and represent "what the agent is doing right now". UI components should
- * listen to 'activity' events to show real-time feedback.
+ * 与历史事件（被持久化）不同，活动是短暂的，
+ * 表示"Agent 此刻正在做什么"。UI 组件应监听
+ * 'activity' 事件以显示实时反馈。
  *
- * Note: There is no 'idle' activity - absence of activity events means idle.
+ * 注：没有 'idle' 活动 —— 没有活动事件即表示空闲。
  */
 export declare type AgentActivity = {
     type: 'thinking';
@@ -38,18 +38,23 @@ export declare type AgentActivity = {
 declare interface AgentConfig extends LLMConfig {
     language?: SupportedLanguage;
     /**
-     * Maximum number of steps the agent can take per task.
+     * 每个任务中 Agent 可以执行的最大步数。
      * @default 40
      */
     maxSteps?: number;
     /**
-     * Custom tools to extend PageAgent capabilities
+     * 拼装 LLM 提示词时，最近保留完整详情的历史步数；更早的步骤会被压缩成一行。
+     * @default 15
+     */
+    historyWindow?: number;
+    /**
+     * 用于扩展 PageAgent 能力的自定义工具
      * @experimental
-     * @note You can also override or remove internal tools by using the same name.
+     * @note 你也可以通过使用相同名称来覆盖或移除内部工具。
      * @see AgentTool
      *
      * @example
-     * // override internal tool
+     * // 覆盖内部工具
      * import { z } from 'zod/v4'
      * import { tool } from '@coolkiller007/my-page-agent'
      * const customTools = {
@@ -67,112 +72,112 @@ declare interface AgentConfig extends LLMConfig {
      * }
      *
      * @example
-     * // remove internal tool
+     * // 移除内部工具
      * const customTools = {
-     * 	ask_user: null // never ask user questions
+     * 	ask_user: null // 永远不要向用户提问
      * }
      */
     customTools?: Record<string, AgentTool | null>;
     /**
-     * Instructions to guide the agent's behavior
+     * 用于引导 Agent 行为的指令
      */
     instructions?: {
         /**
-         * Global system-level instructions, applied to all tasks
+         * 全局系统级指令，应用于所有任务
          */
         system?: string;
         /**
-         * Dynamic page-level instructions callback
-         * Called before each step to get instructions for the current page
-         * @param url - Current page URL (window.location.href)
-         * @returns Instructions string, or undefined/null to skip
+         * 动态的页面级指令回调
+         * 每一步前调用，以获取当前页面的指令
+         * @param url - 当前页面 URL（window.location.href）
+         * @returns 指令字符串，或返回 undefined/null 以跳过
          */
         getPageInstructions?: (url: string) => string | undefined | null;
     };
     /**
-     * Lifecycle hooks for task execution.
-     * @experimental API may change in future versions.
+     * 任务执行的生命周期钩子。
+     * @experimental API 在未来版本中可能变化。
      *
-     * All hooks receive the agent instance as first parameter.
+     * 所有钩子都接收 Agent 实例作为第一个参数。
      */
     /**
-     * Called before each step execution.
+     * 每一步执行前调用。
      * @experimental
-     * @param agent - The AgentRuntime instance
-     * @param stepCount - Current step number (0-indexed)
+     * @param agent - AgentRuntime 实例
+     * @param stepCount - 当前步骤序号（从 0 开始）
      */
     onBeforeStep?: (agent: AgentRuntime, stepCount: number) => Promise<void> | void;
     /**
-     * Called after each step execution.
+     * 每一步执行后调用。
      * @experimental
-     * @param agent - The AgentRuntime instance
-     * @param history - Current history of events
+     * @param agent - AgentRuntime 实例
+     * @param history - 当前的事件历史
      */
     onAfterStep?: (agent: AgentRuntime, history: HistoricalEvent[]) => Promise<void> | void;
     /**
-     * Called before task execution starts.
+     * 任务执行开始前调用。
      * @experimental
-     * @param agent - The AgentRuntime instance
+     * @param agent - AgentRuntime 实例
      */
     onBeforeTask?: (agent: AgentRuntime) => Promise<void> | void;
     /**
-     * Called after task execution completes (success or failure).
+     * 任务执行完成（成功或失败）后调用。
      * @experimental
-     * @param agent - The AgentRuntime instance
-     * @param result - The execution result
+     * @param agent - AgentRuntime 实例
+     * @param result - 执行结果
      */
     onAfterTask?: (agent: AgentRuntime, result: ExecutionResult) => Promise<void> | void;
     /**
-     * Called when the agent is disposed.
+     * Agent 被销毁时调用。
      * @experimental
-     * @note This hook can block the disposal process if it's async.
-     * @param agent - The AgentRuntime instance
-     * @param reason - Optional reason for disposal
+     * @note 若该钩子是异步的，它可能会阻塞销毁流程。
+     * @param agent - AgentRuntime 实例
+     * @param reason - 可选的销毁原因
      */
     onDispose?: (agent: AgentRuntime, reason?: string) => void;
     /**
      * @experimental
-     * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
-     * @note Can cause unpredictable side effects.
-     * @note May bypass some safe guards and data-masking mechanisms.
+     * 启用实验性的脚本执行工具，允许在页面上执行生成的 JavaScript 代码。
+     * @note 可能产生不可预测的副作用。
+     * @note 可能绕过某些安全防护和数据遮蔽机制。
      */
     experimentalScriptExecutionTool?: boolean;
     /**
      * @experimental
-     * Fetch /llms.txt from current site origin and include as context.
-     * Only fetched once per origin per task.
+     * 从当前站点源拉取 /llms.txt 并作为上下文包含进来。
+     * 每个源每个任务只拉取一次。
      * @default false
      */
     experimentalLlmsTxt?: boolean;
     /**
-     * Transform page content before sending to LLM.
-     * Called after DOM extraction and simplification, before LLM invocation.
-     * Use cases: inspect extraction results, modify page info, mask sensitive data.
+     * 在发送给 LLM 之前转换页面内容。
+     * 在 DOM 提取和简化之后、调用 LLM 之前调用。
+     * 使用场景：检查提取结果、修改页面信息、遮蔽敏感数据。
      *
-     * @param content - Simplified page content that will be sent to LLM
-     * @returns Transformed content
+     * @param content - 将被发送给 LLM 的简化页面内容
+     * @returns 转换后的内容
      *
      * @example
-     * // Mask phone numbers
+     * // 遮蔽手机号
      * transformPageContent: async (content) => {
      *   return content.replace(/1[3-9]\d{9}/g, '***********')
      * }
      */
     transformPageContent?: (content: string) => Promise<string> | string;
     /**
-     * Completely override the default system prompt.
-     * @experimental Use with caution - incorrect prompts may break agent behavior.
+     * 完全覆盖默认的系统提示词。
+     * @experimental 谨慎使用 - 错误的提示词可能破坏 Agent 行为。
      */
     customSystemPrompt?: string;
     /**
-     * Delay between steps in seconds.
+     * 步骤之间的延迟（秒）。
      * @default 0.4
      */
     stepDelay?: number;
 }
 
 /**
- * Error event - fatal error from LLM or execution
+ * 错误事件 - 来自 LLM 或执行的致命错误
  */
 declare interface AgentErrorEvent {
     type: 'error';
@@ -181,12 +186,12 @@ declare interface AgentErrorEvent {
 }
 
 /**
- * Agent reflection state - the reflection-before-action model
+ * Agent 反思状态 - 行动前先反思的模型
  *
- * Every tool call must first reflect on:
- * - evaluation_previous_goal: How well did the previous action achieve its goal?
- * - memory: Key information to remember for future steps
- * - next_goal: What should be accomplished in the next action?
+ * 每次工具调用都必须先反思：
+ * - evaluation_previous_goal: 上一个动作在多大程度上实现了其目标？
+ * - memory: 需要在未来步骤中记住的关键信息
+ * - next_goal: 下一个动作应该完成什么？
  */
 declare interface AgentReflection {
     evaluation_previous_goal: string;
@@ -195,75 +200,83 @@ declare interface AgentReflection {
 }
 
 /**
- * AI agent for browser automation.
+ * 用于浏览器自动化的 AI 智能体。
  *
  * @remarks
- * ## Re-act Agent Loop
- * - step
- *    - observe (gather information about current environment and context)
- *    - think (LLM calling)
- *      - reflection (evaluate history, generate memory, short-term planning)
- *      - action (give the action to approach the next goal)
- *    - act (execute the action)
- * - loop
+ * ## 反应式 Agent 循环
+ * - 步骤
+ *    - 观察（收集当前环境与上下文信息）
+ *    - 思考（调用 LLM）
+ *      - 反思（评估历史、生成记忆、短期规划）
+ *      - 行动（给出接近下一个目标的动作）
+ *    - 执行（执行动作）
+ * - 循环
  *
- * ## Event System
- * - `statuschange` - Agent status transitions (idle → running → completed/error/stopped)
- * - `historychange` - History events updated (persistent, part of agent memory)
- * - `activity` - Real-time activity feedback (transient, for UI only)
- * - `dispose` - Agent cleanup triggered
+ * ## 事件系统
+ * - `statuschange` - Agent 状态变更（idle → running → completed/error/stopped）
+ * - `historychange` - 历史事件更新（持久化，属于 Agent 记忆的一部分）
+ * - `activity` - 实时活动反馈（瞬态，仅用于 UI）
+ * - `dispose` - 触发 Agent 清理
  *
- * ## Information Streams
- * 1. **History Events** (`history` array)
- *    - Persistent event stream that forms agent's memory
- *    - Included in LLM context across steps
- *    - Types: steps, observations, user takeovers, llm errors
+ * ## 信息流
+ * 1. **历史事件**（`history` 数组）
+ *    - 构成 Agent 记忆的持久事件流
+ *    - 跨步骤包含在 LLM 上下文中
+ *    - 类型：步骤、观察、用户接管、LLM 错误
  *
- * 2. **Activity Events** (via `activity` event)
- *    - Transient UI feedback during task execution
- *    - NOT included in LLM context
- *    - Types: thinking, executing, executed, retrying, error
+ * 2. **活动事件**（通过 `activity` 事件）
+ *    - 任务执行期间的瞬时 UI 反馈
+ *    - 不包含在 LLM 上下文中
+ *    - 类型：thinking、executing、executed、retrying、error
  */
 declare class AgentRuntime extends EventTarget {
     #private;
+    /** Agent 唯一 ID */
     readonly id: string;
+    /** 合并后的 Agent 配置（含最大步数上限） */
     readonly config: AgentRuntimeConfig & {
         maxSteps: number;
+        historyWindow: number;
     };
+    /** 内部工具集合（按工具名索引） */
     readonly tools: typeof tools;
-    /** BrowserController for DOM operations */
+    /** 用于 DOM 操作的 BrowserController */
     readonly browserController: BrowserController;
+    /** 当前任务描述 */
     task: string;
+    /** 当前任务 ID */
     taskId: string;
-    /** History events */
+    /** 历史事件 */
     history: HistoricalEvent[];
-    /** Whether this agent has been disposed */
+    /** 该 Agent 是否已被销毁 */
     disposed: boolean;
     /**
-     * Called when the agent needs to ask the user questions.
-     * If unset, the `ask_user` tool will be disabled.
-     * Implementations should reject the promise when `signal` aborts.
+     * 当 Agent 需要向用户提问时调用。
+     * 若未设置，`ask_user` 工具将被禁用。
+     * 实现应在 `signal` 中止时 reject 该 Promise。
      * @example onAskUser: (q) => window.prompt(q) || ''
      */
     onAskUser?: (question: string, options?: {
         signal: AbortSignal;
     }) => Promise<string>;
+    /** 构造函数：初始化配置、LLM、工具集，并注册重试事件监听与注入自定义工具 */
     constructor(config: AgentRuntimeConfig);
-    /** Get current agent status */
+    /** 获取当前 Agent 状态 */
     get status(): AgentStatus;
-    /** Result of the most recent run, or `null` before the first run completes. */
+    /** 最近一次运行的结果，首次运行完成前为 `null`。 */
     get lastResult(): ExecutionResult | null;
     /* Excluded from this release type: pushObservation */
     /**
-     * Stop the current task and wait until the run has fully settled (including lifecycle hooks).
-     * @note never await .stop() in a lifecycle hook.
+     * 停止当前任务，并等待运行完全结束（包括生命周期钩子）。
+     * @note 切勿在生命周期钩子中 await .stop()。
      */
     stop(): Promise<void>;
     /**
-     * external errors (pre-checks/config/hooks) will threw;
-     * agent errors will be caught and added to history, and return a failed result
+     * 外部错误（前置检查/配置/钩子）会直接抛出；
+     * Agent 内部错误会被捕获并加入历史，同时返回失败结果
      */
     execute(task: string): Promise<ExecutionResult>;
+    /** 销毁 Agent：中止任务、释放浏览器控制器，并触发 dispose 事件（一次性） */
     dispose(): void;
 }
 
@@ -272,12 +285,12 @@ declare type AgentRuntimeConfig = AgentConfig & {
 };
 
 /**
- * Agent lifecycle status.
+ * Agent 生命周期状态。
  */
 export declare type AgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped';
 
 /**
- * A single agent step with reflection and action
+ * 带反思和动作的单个 Agent 步骤
  */
 declare interface AgentStepEvent {
     type: 'step';
@@ -295,14 +308,14 @@ declare interface AgentStepEvent {
         cachedTokens?: number;
         reasoningTokens?: number;
     };
-    /** Raw LLM response for debugging */
+    /** 原始 LLM 响应（用于调试） */
     rawResponse?: unknown;
-    /** Raw LLM request for debugging */
+    /** 原始 LLM 请求（用于调试） */
     rawRequest?: unknown;
 }
 
 /**
- * Internal tool definition that has access to PageAgent `this` context
+ * 内部工具定义，可访问 PageAgent 的 `this` 上下文
  */
 declare interface AgentTool<TParams = any> {
     description: string;
@@ -311,84 +324,86 @@ declare interface AgentTool<TParams = any> {
 }
 
 /**
- * BrowserController manages DOM state and element interactions.
- * It provides async methods for all DOM operations, keeping state isolated.
+ * BrowserController 管理 DOM 状态和元素交互。
+ * 它为所有 DOM 操作提供异步方法，并保持状态隔离。
  *
  * @lifecycle
- * - beforeUpdate: Emitted before the DOM tree is updated.
- * - afterUpdate: Emitted after the DOM tree is updated.
+ * - beforeUpdate: 在 DOM 树更新之前触发。
+ * - afterUpdate: 在 DOM 树更新之后触发。
  */
 declare class BrowserController extends EventTarget {
     private config;
-    /** Corresponds to eval_page in browser-use */
+    /** 对应 browser-use 中的 eval_page */
     private flatTree;
     /**
-     * All highlighted index-mapped interactive elements
-     * Corresponds to DOMState.selector_map in browser-use
+     * 所有已索引的高亮交互元素
+     * 对应 browser-use 中的 DOMState.selector_map
      */
     private selectorMap;
-    /** Index -> element text description mapping */
+    /** 索引 -> 元素文本描述映射 */
     private elementTextMap;
     /**
-     * Simplified HTML for LLM consumption.
-     * Corresponds to clickable_elements_to_string in browser-use
+     * 供 LLM 消费的简化 HTML。
+     * 对应 browser-use 中的 clickable_elements_to_string
      */
     private simplifiedHTML;
-    /** last time the tree was updated */
+    /** 树最后一次更新的时间 */
     private lastTimeUpdate;
-    /** Whether the tree has been indexed at least once */
+    /** 树是否至少被索引过一次 */
     private isIndexed;
-    /** Visual mask overlay for blocking user interaction during automation */
+    /** 用于在自动化期间阻止用户交互的视觉遮罩层 */
     private mask;
+    /** mask 异步初始化完成的 Promise，用于在调用前等待初始化完成 */
     private maskReady;
+    /** 是否已释放资源 */
     private disposed;
     constructor(config?: BrowserControllerConfig);
     /**
-     * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
+     * 异步初始化遮罩层（动态导入以避免在 Node 中加载 CSS）
      */
     initMask(): void;
     /**
-     * Get current page URL
+     * 获取当前页面 URL
      */
     getCurrentUrl(): Promise<string>;
     /**
-     * Get last tree update timestamp
+     * 获取树最后一次更新的时间戳
      */
     getLastUpdateTime(): Promise<number>;
     /**
-     * Get structured browser state for LLM consumption.
-     * Automatically calls updateTree() to refresh the DOM state.
+     * 获取供 LLM 消费的结构化浏览器状态。
+     * 自动调用 updateTree() 刷新 DOM 状态。
      */
     getBrowserState(): Promise<BrowserState>;
     /**
-     * Update DOM tree, returns simplified HTML for LLM.
-     * This is the main method to refresh the page state.
-     * Automatically bypasses mask during DOM extraction if enabled.
+     * 更新 DOM 树，返回供 LLM 使用的简化 HTML。
+     * 这是刷新页面状态的主要方法。
+     * 若已启用遮罩，DOM 提取期间会自动绕过遮罩。
      */
     updateTree(): Promise<string>;
     /**
-     * Clean up all element highlights
+     * 清理所有元素高亮
      */
     cleanUpHighlights(): Promise<void>;
     /**
-     * Ensure the tree has been indexed before any index-based operation.
-     * Throws if updateTree() hasn't been called yet.
+     * 在任何基于索引的操作之前确保树已被索引。
+     * 若尚未调用 updateTree() 则抛出异常。
      */
     private assertIndexed;
     /**
-     * Click element by index
+     * 根据索引点击元素
      */
     clickElement(index: number): Promise<ActionResult>;
     /**
-     * Input text into element by index
+     * 根据索引向元素输入文本
      */
     inputText(index: number, text: string): Promise<ActionResult>;
     /**
-     * Select dropdown option by index and option text
+     * 根据索引和选项文本在下拉框中选中选项
      */
     selectOption(index: number, optionText: string): Promise<ActionResult>;
     /**
-     * Scroll vertically
+     * 垂直滚动
      */
     scroll(options: {
         down: boolean;
@@ -397,7 +412,7 @@ declare class BrowserController extends EventTarget {
         index?: number;
     }): Promise<ActionResult>;
     /**
-     * Scroll horizontally
+     * 水平滚动
      */
     scrollHorizontally(options: {
         right: boolean;
@@ -405,51 +420,55 @@ declare class BrowserController extends EventTarget {
         index?: number;
     }): Promise<ActionResult>;
     /**
-     * Execute arbitrary JavaScript on the page.
-     * The optional `signal` is exposed to the script scope so cooperative code
-     * can abort promptly when the task is stopped.
+     * 在页面上执行任意 JavaScript。
+     * 可选的 `signal` 会暴露到脚本作用域中，使协作代码能在任务被中止时及时退出。
      */
     executeJavascript(script: string, signal?: AbortSignal): Promise<ActionResult>;
     /**
-     * Show the visual mask overlay.
-     * Only works after mask is setup.
+     * 显示视觉遮罩层。
+     * 仅在遮罩初始化完成后可用。
      */
     showMask(): Promise<void>;
     /**
-     * Hide the visual mask overlay.
-     * Only works after mask is setup.
+     * 隐藏视觉遮罩层。
+     * 仅在遮罩初始化完成后可用。
      */
     hideMask(): Promise<void>;
     /**
-     * Dispose and clean up resources
+     * 释放资源并清理
      */
     dispose(): void;
 }
 
 /**
- * Configuration for BrowserController
+ * BrowserController 的配置
  */
 declare interface BrowserControllerConfig extends dom.DomConfig {
-    /** Enable visual mask overlay during operations (default: false) */
+    /** 操作期间启用视觉遮罩层（默认：false） */
     enableMask?: boolean;
 }
 
 /**
- * Structured browser state for LLM consumption
+ * 供 LLM 使用的结构化浏览器状态
  */
 declare interface BrowserState {
     url: string;
     title: string;
-    /** Page info + scroll position hint (e.g. "Page info: 1920x1080px...\n[Start of page]") */
+    /** 页面信息 + 滚动位置提示（例如 "Page info: 1920x1080px...\n[Start of page]"） */
     header: string;
-    /** Simplified HTML of interactive elements */
+    /** 可交互元素的简化 HTML */
     content: string;
-    /** Page footer hint (e.g. "... 300 pixels below ..." or "[End of page]") */
+    /** 页面底部提示（例如 "... 300 pixels below ..." 或 "[End of page]"） */
     footer: string;
 }
 
 declare function cleanUpHighlights(): void;
 
+/**
+ * 创建智能体实例的快捷函数，内部直接实例化 MyPageAgent。
+ * @param config 智能体的配置对象
+ * @returns 创建好的 MyPageAgent 实例
+ */
 export declare function createAgent(config: MyPageAgentConfig): MyPageAgent;
 
 declare namespace dom {
@@ -474,8 +493,8 @@ declare interface DomConfig {
     highlightOpacity?: number;
     highlightLabelOpacity?: number;
     /**
-     * Preserve semantic landmark tags in dehydrated output even if not interactive
-     * @note maybe confusing for LLM combining with page scrolling, use with caution
+     * 即使不可交互，也保留脱水输出中的语义化地标标签
+     * @note 结合页面滚动时可能让 LLM 感到困惑，请谨慎使用
      **/
     keepSemanticTags?: boolean;
 }
@@ -497,6 +516,7 @@ declare interface ElementDomNode {
     [key: string]: unknown;
 }
 
+/** 任务执行结果 */
 export declare interface ExecutionResult {
     success: boolean;
     data: string;
@@ -542,9 +562,9 @@ declare function getFlatTree(config: DomConfig): FlatDomTree;
 declare function getSelectorMap(flatTree: FlatDomTree): Map<number, InteractiveElementDomNode>;
 
 /**
- * Union type for all history events
+ * 所有历史事件的联合类型
  */
-export declare type HistoricalEvent = AgentStepEvent | ObservationEvent | UserTakeoverEvent | RetryEvent | AgentErrorEvent;
+export declare type HistoricalEvent = AgentStepEvent | ObservationEvent | UserTakeoverEvent | TaskStartEvent | RetryEvent | AgentErrorEvent;
 
 declare interface InteractiveElementDomNode {
     tagName: string;
@@ -564,38 +584,39 @@ declare interface InteractiveElementDomNode {
 }
 
 /**
- * LLM configuration
+ * LLM 配置
  */
 declare interface LLMConfig {
     baseURL: string;
     model: string;
     apiKey?: string;
     /**
-     * @deprecated No longer a standard parameter; many models reject it outright.
-     * Use `transformRequestBody` to set it only for models you've verified.
+     * @deprecated 已不再是标准参数，许多模型会直接拒绝该参数。
+     * 请使用 `transformRequestBody` 仅为已验证支持的模型设置该参数。
      */
     temperature?: number;
     maxRetries?: number;
     /**
-     * Transform the final request body before sending it to the provider.
-     * Use this to implement provider-specific request tweaks such as caching hints or custom flags.
+     * 在发送给服务商之前转换最终的请求体。
+     * 用于实现特定服务商的请求定制，例如缓存提示或自定义标记。
      *
-     * Return a new object, or mutate the input object and return undefined.
+     * 返回一个新对象，或就地修改输入对象并返回 undefined。
      */
     transformRequestBody?: (requestBody: Record<string, unknown>) => Record<string, unknown> | undefined;
     /**
-     * remove the tool_choice field from the request.
-     * @note fix "Invalid tool_choice type: 'object'" for some LLMs.
+     * 从请求中移除 tool_choice 字段。
+     * @note 修复部分 LLM 报出的 "Invalid tool_choice type: 'object'" 错误。
      */
     disableNamedToolChoice?: boolean;
     /**
-     * Custom fetch function for LLM API requests.
-     * Use this to customize headers, credentials, proxy, etc.
-     * The response should follow OpenAI API format.
+     * 用于 LLM API 请求的自定义 fetch 函数。
+     * 可用于自定义请求头、凭据、代理等。
+     * 返回的响应应符合 OpenAI API 格式。
      */
     customFetch?: typeof globalThis.fetch;
 }
 
+/** 语言包集合：键为语言代码，值为对应翻译表 */
 declare const locales: {
     readonly 'en-US': {
         readonly ui: {
@@ -687,15 +708,21 @@ declare const locales: {
     };
 };
 
+/**
+ * 完整页面智能体：组合了 AgentRuntime、BrowserController 与 UI
+ */
 export declare class MyPageAgent extends AgentRuntime {
+    /** UI 实例（用于用户交互与反馈） */
     readonly ui: UI;
+    /** 构造函数：创建浏览器控制器、父类运行时与 UI 实例 */
     constructor(config: MyPageAgentConfig);
 }
 
+/** MyPageAgent 的配置：Agent 配置 + 浏览器控制器配置 + UI 配置（语言除外） */
 export declare type MyPageAgentConfig = Omit<AgentConfig, 'experimentalScriptExecutionTool'> & BrowserControllerConfig & Omit<UIConfig, 'language'>;
 
 /**
- * Persistent observation event (stays in memory)
+ * 持久观察事件（保留在记忆中）
  */
 declare interface ObservationEvent {
     type: 'observation';
@@ -705,7 +732,7 @@ declare interface ObservationEvent {
 declare function resolveViewportExpansion(viewportExpansion?: number): number;
 
 /**
- * Retry event - LLM call is being retried
+ * 重试事件 - LLM 调用正在重试
  */
 declare interface RetryEvent {
     type: 'retry';
@@ -714,11 +741,22 @@ declare interface RetryEvent {
     maxAttempts: number;
 }
 
-/** Supported UI languages */
+/** 支持的 UI 语言 */
 declare type SupportedLanguage = 'en-US' | 'zh-CN';
 
+/** 受支持的语言代码类型 */
 declare type SupportedLanguage_2 = keyof typeof locales;
 
+/**
+ * 任务开始事件 - 标记一个新任务的起点
+ * @note history 数组跨任务持久保留（不再在每次 execute 时清空），
+ * 该事件用于在历史记录中分隔不同任务，UI 据此渲染各自的任务卡片。
+ */
+declare interface TaskStartEvent {
+    type: 'task_start';
+    task: string;
+}
+
 declare interface TextDomNode {
     type: 'TEXT_NODE';
     text: string;
@@ -726,19 +764,20 @@ declare interface TextDomNode {
     [key: string]: unknown;
 }
 
+/** 创建一个工具定义（直接透传 options） */
 export declare function tool<TParams>(options: AgentTool<TParams>): AgentTool<TParams>;
 
 /**
- * Per-invocation context passed to every tool execution.
- * Tools MUST honor `signal` to support cooperative cancellation.
+ * 每次工具调用都会传入的上下文。
+ * 工具必须遵守 `signal` 以支持协作式取消。
  */
 declare interface ToolContext {
     signal: AbortSignal;
 }
 
 /**
- * Internal tools for PageAgent.
- * Note: Using any to allow different parameter types for each tool
+ * PageAgent 的内部工具。
+ * 注：使用 any 以允许每个工具拥有不同的参数类型
  */
 declare const tools: Map<string, AgentTool<any>>;
 
@@ -761,110 +800,118 @@ declare interface TreeNode {
 }
 
 /**
- * Agent control UI
+ * Agent 控制 UI
  *
- * Architecture:
- * - History list: renders directly from agent.history (historical events)
- * - Header bar: shows activity events (transient state) and agent status
+ * 架构：
+ * - 历史列表：直接从 agent.history 渲染（历史事件）
+ * - 头部栏：展示活动事件（瞬时状态）和 agent 状态
  *
- * This separation ensures data consistency - history is the single source of truth
- * for what has been done, while activity shows what is happening now.
+ * 这种分离保证了数据一致性 - 历史是已完成内容的唯一数据源，
+ * 而活动状态展示的是当前正在发生的事情。
  */
 declare class UI {
     #private;
+    /** 获取 UI 的根容器元素 */
     get wrapper(): HTMLElement;
     /**
-     * Create a UI bound to an agent
-     * @param agent - Agent instance that implements UIAdapter
-     * @param config - Optional UI configuration
+     * 创建绑定到某个 agent 的 UI
+     * @param agent - 实现 UIAdapter 的 Agent 实例
+     * @param config - 可选的 UI 配置
      */
     constructor(agent: UIAdapter, config?: UIConfig);
+    /** 显示 UI（淡入 + 平移效果） */
     show(): void;
+    /** 隐藏 UI（淡出 + 下移效果） */
     hide(): void;
+    /** 重置 UI 状态（拒绝挂起问题、清空状态文本、收起历史并显示输入框） */
     reset(): void;
+    /** 展开历史弹窗（公开方法） */
     expand(): void;
+    /** 收起历史弹窗（公开方法） */
     collapse(): void;
     /**
-     * Dispose UI and clean up event listeners
+     * 销毁 UI 并清理事件监听器
      */
     dispose(): void;
 }
 
 /**
- * Minimal interface that UI expects from an agent.
- * UI does not depend on PageAgent directly - it only requires this interface.
- * This enables decoupling and allows any agent implementation to work with UI.
+ * UI 对 agent 的最简接口要求。
+ * UI 不直接依赖 PageAgent - 只需实现该接口即可。
+ * 这样实现了解耦，任何 agent 实现都能与 UI 配合使用。
  *
- * Events:
- * - 'statuschange': Agent status changed
- * - 'historychange': Historical events updated (persisted)
- * - 'activity': Transient activity for immediate UI feedback (thinking/executing/etc)
- * - 'dispose': Agent is being disposed
+ * 事件：
+ * - 'statuschange'：agent 状态发生变化
+ * - 'historychange'：历史事件更新（已持久化）
+ * - 'activity'：供 UI 即时反馈的瞬时活动（思考/执行等）
+ * - 'dispose'：agent 正在被销毁
  */
 declare interface UIAdapter extends EventTarget {
-    /** Current agent status */
+    /** 当前 agent 状态 */
     readonly status: 'idle' | 'running' | 'completed' | 'error' | 'stopped';
-    /** Result of the most recent run, or `null` before the first run completes */
+    /** 最近一次运行的结果，首次运行完成前为 `null` */
     readonly lastResult: {
         success: boolean;
     } | null;
-    /** History of agent events */
+    /** agent 事件历史 */
     readonly history: readonly {
-        type: 'step' | 'observation' | 'user_takeover' | 'retry' | 'error';
+        type: 'step' | 'observation' | 'user_takeover' | 'task_start' | 'retry' | 'error';
         stepIndex?: number;
-        /** For 'step' type */
+        /** 仅用于 'step' 类型 */
         reflection?: {
             evaluation_previous_goal?: string;
             memory?: string;
             next_goal?: string;
         };
-        /** For 'step' type */
+        /** 仅用于 'step' 类型 */
         action?: {
             name: string;
             input: unknown;
             output: string;
         };
-        /** For 'observation' type */
+        /** 仅用于 'observation' 类型 */
         content?: string;
-        /** For 'retry' type */
+        /** 仅用于 'task_start' 类型 */
+        task?: string;
+        /** 仅用于 'retry' 类型 */
         attempt?: number;
         maxAttempts?: number;
-        /** For 'retry' and 'error' types */
+        /** 仅用于 'retry' 和 'error' 类型 */
         message?: string;
     }[];
-    /** Current task being executed */
+    /** 当前正在执行的任务 */
     readonly task: string;
     /**
-     * Called when the agent needs to ask the user questions.
-     * If unset, the `ask_user` tool will be disabled.
-     * UI will set this to handle user questions via its UI.
-     * The optional `signal` aborts when the task is stopped or disposed.
+     * 当 agent 需要向用户提问时调用。
+     * 如果未设置，`ask_user` 工具将被禁用。
+     * UI 会设置该回调以便通过自身的界面处理用户提问。
+     * 可选参数 `signal` 在任务被停止或销毁时触发中止。
      */
     onAskUser?: (question: string, options?: {
         signal: AbortSignal;
     }) => Promise<string>;
-    /** Execute a task */
+    /** 执行一个任务 */
     execute(task: string): Promise<unknown>;
-    /** Stop the current task (agent remains reusable) */
+    /** 停止当前任务（agent 仍可复用） */
     stop(): Promise<void>;
-    /** Dispose the agent (terminal, cannot be reused) */
+    /** 销毁 agent（终态，不可复用） */
     dispose(): void;
 }
 
 /**
- * UI configuration
+ * UI 配置
  */
 declare interface UIConfig {
     language?: SupportedLanguage_2;
     /**
-     * Whether to prompt for next task after task completion
+     * 任务完成后是否提示输入下一个任务
      * @default true
      */
     promptForNextTask?: boolean;
 }
 
 /**
- * User takeover event
+ * 用户接管事件
  */
 declare interface UserTakeoverEvent {
     type: 'user_takeover';