@coolkiller007/my-page-agent 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +89 -0
  3. package/UPSTREAM.md +97 -0
  4. package/dist/index.d.ts +873 -0
  5. package/dist/index.js +4436 -0
  6. package/dist/index.js.map +1 -0
  7. package/package.json +84 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SimonLuvRamen
4
+ Copyright (c) 2026 Alibaba Group Holding Limited
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,89 @@
1
+ # My Page Agent
2
+
3
+ 面向茶颜悦色 Vue 2 多品牌中台的页面内嵌 GUI Agent。项目将自然语言任务转换为受控的页面读取与操作，并以单一 npm 包交付。
4
+
5
+ ## Installation
6
+
7
+ 运行环境要求：Node.js `^22.22.1 || >=24`、npm `^11.6.3`。
8
+
9
+ ```sh
10
+ npm install @coolkiller007/my-page-agent
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { createAgent } from '@coolkiller007/my-page-agent'
17
+
18
+ const agent = createAgent({
19
+ baseURL: '/api/ai/v1',
20
+ apiKey: 'provided-by-the-company-gateway',
21
+ model: 'configured-model',
22
+ language: 'zh-CN',
23
+ })
24
+
25
+ agent.ui.show()
26
+ const result = await agent.execute('打开会员列表并筛选本月新增会员')
27
+
28
+ const writeResult = result.success ? console.log : console.error
29
+ writeResult(result.data)
30
+
31
+ // 用户退出、切换租户或应用卸载时清理资源。
32
+ agent.dispose()
33
+ ```
34
+
35
+ 生产环境必须通过公司后端代理或 AI 网关访问模型，不得把生产 API Key 打进浏览器产物。页面内容在发送给模型前也应通过 `transformPageContent` 完成业务所需的脱敏。
36
+
37
+ ## Public API
38
+
39
+ 包根入口是唯一公共入口：
40
+
41
+ - `createAgent(config)`：创建并组装 `MyPageAgent`。
42
+ - `MyPageAgent`：Agent 门面；提供 `execute(task)`、`stop()`、`dispose()` 和只读 `status`。
43
+ - `agent.ui`：提供 `show()`、`hide()`、`expand()` 和 `collapse()`。
44
+ - `tool(options)`：定义自定义 Agent 工具。
45
+ - 类型：`MyPageAgentConfig`、`AgentActivity`、`AgentStatus`、`ExecutionResult` 和 `HistoricalEvent`。
46
+
47
+ `AgentRuntime`、`BrowserController`、`OpenAICompatibleClient`、UI 内部组件、DOM Tree、Prompt 和自动修复器属于内部实现，不从包根入口导出。
48
+
49
+ ## Architecture
50
+
51
+ - `src/agent`：任务编排、工具和公共门面。
52
+ - `src/browser`：DOM 提取与页面操作。
53
+ - `src/llm`：OpenAI-compatible 模型调用。
54
+ - `src/ui`：页面内用户界面。
55
+ - `src/integrations`：业务框架适配的预留边界。
56
+ - `src/shared`：跨能力共享的无状态工具。
57
+ - `src/index.ts`：限定公共 API 的唯一包入口。
58
+
59
+ 项目只发布 `@coolkiller007/my-page-agent`，不使用 npm workspaces。Browser、Runtime 和 UI 只在 `MyPageAgent` 中组装，内部模块使用相对 import。
60
+
61
+ ## Development
62
+
63
+ ```sh
64
+ npm install
65
+ npm test
66
+ npm run typecheck
67
+ npm run lint
68
+ npm run format:check
69
+ npm run build
70
+ npm run ci
71
+ ```
72
+
73
+ `npm pack --dry-run` 可用于检查发布包白名单。预期发布内容仅包含 `dist/`、README、LICENSE、UPSTREAM 和 npm 包元数据。
74
+
75
+ ## Non-goals
76
+
77
+ 当前迁移不包含：
78
+
79
+ - 浏览器 Extension、MCP Server 或 Website；
80
+ - IIFE Demo、CDN 自动初始化或跨标签页自动化；
81
+ - npm workspace、多包构建与发布脚本；
82
+ - 依赖真实模型密钥的 Live 测试；
83
+ - Vue 2 生命周期、业务上下文、Action Policy、脱敏和审计的业务实现。
84
+
85
+ 这些能力需在独立设计和安全评审后按需实现，不应通过恢复上游多包结构引入。
86
+
87
+ ## Upstream
88
+
89
+ 项目基于 MIT License 选择性迁移 [Alibaba Page Agent](https://github.com/alibaba/page-agent) 的运行能力。来源基线、目录映射、机械重命名和排除范围见 [UPSTREAM.md](UPSTREAM.md) 与 [LICENSE](LICENSE)。
package/UPSTREAM.md ADDED
@@ -0,0 +1,97 @@
1
+ # Upstream
2
+
3
+ This repository selectively derives runtime code from [Alibaba Page Agent](https://github.com/alibaba/page-agent) under the MIT License.
4
+
5
+ - Baseline commit: `d02db1e`
6
+ - Baseline version: `1.12.2`
7
+ - Imported on: `2026-08-11`
8
+
9
+ ## Directory mapping
10
+
11
+ The migration reorganizes upstream package boundaries into capabilities in one npm package:
12
+
13
+ | Alibaba Page Agent source | My Page Agent destination | Notes |
14
+ | ----------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
15
+ | `packages/llms/src/index.ts` | `src/llm/LLM.ts` | LLM orchestration |
16
+ | `packages/llms/src/OpenAIClient.ts` | `src/llm/OpenAICompatibleClient.ts` | Client renamed mechanically |
17
+ | `packages/llms/src/errors.ts` | `src/llm/errors.ts` | Error contracts |
18
+ | `packages/llms/src/types.ts` | `src/llm/types.ts` | Provider contracts |
19
+ | `packages/llms/src/utils.ts` | `src/llm/utils.ts` | Response utilities |
20
+ | `packages/llms/src/index.test.ts` | `src/llm/LLM.test.ts` | Non-Live behavior coverage |
21
+ | `packages/llms/src/OpenAIClient.test.ts` | `src/llm/OpenAICompatibleClient.test.ts` | Client behavior coverage |
22
+ | `packages/llms/src/utils.test.ts` | `src/llm/utils.test.ts` | Utility coverage |
23
+ | `packages/page-controller/src/PageController.ts` | `src/browser/BrowserController.ts` | Controller renamed mechanically |
24
+ | `packages/page-controller/src/actions.ts` | `src/browser/actions.ts` | Browser actions |
25
+ | `packages/page-controller/src/dom/` | `src/browser/dom/` | DOM extraction and DOM Tree |
26
+ | `packages/page-controller/src/mask/` | `src/browser/visual/` | Mask and visual resources |
27
+ | `packages/page-controller/src/patches/` | `src/browser/patches/` | Browser compatibility patches |
28
+ | `packages/page-controller/src/utils/` | `src/browser/utils/` | Browser utilities |
29
+ | `packages/page-controller/src/PageController.ts` | `src/browser/types.ts` | Controller types split into a local barrel |
30
+ | `packages/page-controller/src/PageController.test.ts` | `src/browser/BrowserController.test.ts` | Controller behavior coverage |
31
+ | `packages/core/src/PageAgentCore.ts` | `src/agent/AgentRuntime.ts` | Runtime renamed mechanically |
32
+ | `packages/core/src/types.ts` | `src/agent/types.ts` | Runtime contracts |
33
+ | `packages/core/src/tools/` | `src/agent/tools/` | Agent tools |
34
+ | `packages/core/src/prompts/` | `src/agent/prompts/` | System prompt resources |
35
+ | `packages/core/src/utils/` | `src/agent/utils/` | Runtime utilities |
36
+ | `packages/core/src/env.d.ts` | `src/env.d.ts` | Vite types retained; raw Markdown declaration covered by Vite |
37
+ | `packages/core/src/PageAgentCore.test.ts` | `src/agent/AgentRuntime.test.ts` | Runtime behavior and lifecycle coverage |
38
+ | `packages/page-controller/src/env.d.ts` | `src/env.d.ts` | CSS Module declaration covered by Vite |
39
+ | `packages/ui/src/panel/Panel.ts` | `src/ui/UI.ts` | Behavior retained; terminology changed to UI |
40
+ | `packages/ui/src/panel/Panel.module.css` | `src/ui/styles/UI.module.css` | Styles renamed with the UI surface |
41
+ | `packages/ui/src/panel/cards.ts` | `src/ui/cards.ts` | UI cards |
42
+ | `packages/ui/src/panel/types.ts` | `src/ui/types.ts` | UI adapter contracts |
43
+ | `packages/ui/src/i18n/` | `src/ui/i18n/` | Localized UI resources |
44
+ | upstream UI tests | `src/ui/UI.test.ts` | Focused replacement coverage for migrated UI behavior |
45
+ | `packages/page-agent/src/PageAgent.ts` | `src/agent/MyPageAgent.ts` | Behavior reference only; facade reimplemented for the single package |
46
+ | `packages/page-agent/src/env.d.ts` | `src/env.d.ts` | Vite types retained; IIFE Demo globals intentionally excluded |
47
+ | upstream public package behavior | `tests/integration/public-entry.test.ts` | Public root-entry boundary coverage |
48
+
49
+ The upstream DOM Tree remains JavaScript to minimize drift from the complex extraction algorithm. Its original `@edit` annotations are retained so downstream changes remain auditable.
50
+
51
+ The three upstream environment declaration files are consolidated at `src/env.d.ts`. Its
52
+ `vite/client` reference, together with `types: ["node", "vite/client"]` in `tsconfig.json`, provides
53
+ the Vite client types used by the migrated source. Vite's declarations already cover `*?raw` imports
54
+ such as `system_prompt.md?raw` and `*.module.css`, so the narrower upstream Markdown and CSS Module
55
+ declarations are not duplicated. The upstream `Window.pageAgent` and `Window.PageAgent` globals exist
56
+ only for `packages/page-agent/src/demo.ts`; they were excluded with the IIFE Demo and are not part of
57
+ the library's browser-global or public API contract.
58
+
59
+ ## Mechanical renaming
60
+
61
+ The migration applies these structural names without changing the corresponding capability intent:
62
+
63
+ | Upstream name | Current name |
64
+ | ------------------- | ------------------------ |
65
+ | `OpenAIClient` | `OpenAICompatibleClient` |
66
+ | `PageController` | `BrowserController` |
67
+ | `PageAgentCore` | `AgentRuntime` |
68
+ | `Panel` | `UI` |
69
+ | `PanelConfig` | `UIConfig` |
70
+ | `PanelAgentAdapter` | `UIAdapter` |
71
+ | `agent.panel` | `agent.ui` |
72
+ | `mask/` | `visual/` |
73
+
74
+ UI behavior was migrated selectively, while source identifiers and product terminology were standardized on `UI`. `MyPageAgent` is the only assembly point for Browser, Runtime, and UI.
75
+
76
+ ## License and copyright
77
+
78
+ Migrated code remains covered by the upstream MIT License. [LICENSE](LICENSE) preserves the MIT grant and the Alibaba Group Holding Limited copyright notice. Original copyright headers remain on migrated source files; downstream copyright notices are additive and do not replace upstream attribution.
79
+
80
+ ## Intentionally excluded
81
+
82
+ The following upstream areas were not migrated:
83
+
84
+ - Live model tests that require external services or credentials;
85
+ - Extension and its remote browser-control bridge;
86
+ - MCP server and Extension-dependent control chain;
87
+ - Website and documentation application;
88
+ - IIFE Demo, CDN auto-initialization, and demo API behavior;
89
+ - npm workspace configuration and per-package manifests;
90
+ - multi-package build, version synchronization, pre-publish, post-publish, and release scripts;
91
+ - package wrappers, compatibility exports, and configuration without a single-package caller.
92
+
93
+ These exclusions are deliberate. Extension, MCP, Website, IIFE, workspace, or release infrastructure must not be copied as an incidental part of an upstream sync.
94
+
95
+ ## Synchronization policy
96
+
97
+ Future upstream syncs use capability directories (`agent`, `browser`, `llm`, and `ui`) as review units. They do not merge upstream package or workspace structure. Each sync must preserve local public-entry boundaries, rerun the complete test/type/lint/build/package checks, and review license headers and DOM Tree `@edit` annotations. Extension, MCP, and Website changes require separate designs rather than automatic migration.