My Page Agent

面向中台的页面内嵌 GUI Agent。项目将自然语言任务转换为受控的页面读取与操作，并以单一 npm 包交付。

Installation

运行环境要求：Node.js ^22.22.1 || >=24、npm ^11.6.3。

npm install @coolkiller007/my-page-agent

Usage

import { createAgent } from '@coolkiller007/my-page-agent'

const agent = createAgent({
    baseURL: '/api/ai/v1',
    apiKey: 'provided-by-the-company-gateway',
    model: 'configured-model',
    language: 'zh-CN',
})

agent.ui.show()
const result = await agent.execute('打开会员列表并筛选本月新增会员')

const writeResult = result.success ? console.log : console.error
writeResult(result.data)

// 用户退出、切换租户或应用卸载时清理资源。
agent.dispose()

生产环境必须通过公司后端代理或 AI 网关访问模型，不得把生产 API Key 打进浏览器产物。页面内容在发送给模型前也应通过 transformPageContent 完成业务所需的脱敏。

Public API

包根入口是唯一公共入口：

• createAgent(config)：创建并组装 MyPageAgent。
• MyPageAgent：Agent 门面；提供 execute(task)、stop()、dispose() 和只读status。
• agent.ui：提供 show()、hide()、expand() 和 collapse()。
• tool(options)：定义自定义 Agent 工具。
• 类型：MyPageAgentConfig、AgentActivity、AgentStatus、ExecutionResult和 HistoricalEvent。

AgentRuntime、BrowserController、OpenAICompatibleClient、UI 内部组件、DOM Tree、Prompt 和自动修复器属于内部实现，不从包根入口导出。

Architecture

• src/agent：任务编排、工具和公共门面。
• src/browser：DOM 提取与页面操作。
• src/llm：OpenAI-compatible 模型调用。
• src/ui：页面内用户界面。
• src/shared：跨能力共享的无状态工具。
• src/index.ts：限定公共 API 的唯一包入口。

项目只发布 @coolkiller007/my-page-agent，不使用 npm workspaces。Browser、Runtime 和 UI 只在 MyPageAgent 中组装，内部模块使用相对 import。