page-agent-sdk 3.46.0 → 4.0.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.
- package/README.md +5 -5
- package/README.zh-CN.md +5 -5
- package/dist/page-agent-sdk.headless.js +2610 -2330
- package/dist/page-agent-sdk.iife.js +149 -146
- package/dist/page-agent-sdk.js +3613 -3329
- package/dist/page-agent-sdk.legacy.js +15484 -15190
- package/dist/page-agent-sdk.umd.cjs +112 -109
- package/dist/style.css +1 -1
- package/package.json +1 -1
- package/skills/page-agent-sdk-integrate/SKILL.md +1 -1
- package/skills/page-agent-sdk-integrate/references/api.md +13 -17
- package/style.css +1 -1
- package/types/headless.d.ts +86 -4
- package/types/index.d.ts +87 -5
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/page-agent-sdk)
|
|
10
10
|
[](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
|
|
11
|
-
[](#self-tests)
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -51,7 +51,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
|
|
|
51
51
|
|---|---|---|
|
|
52
52
|
| **Scope control** | Declared schema fields (`data`) — only declared keys are writable; schema shape auto-whitelist (top-level + sub-path recursively projected by sub-schema; undeclared fields hidden/denied; whole-set becomes merge to prevent accidental deletion) | AI touching undeclared fields → `PATH_DENIED` |
|
|
53
53
|
| **Validity check** | zod schema — `write`/`set`/`edit` validated against schema | Invalid type/enum/structure → structured error, no write |
|
|
54
|
-
| **Incremental op** | `write` with `patch
|
|
54
|
+
| **Incremental op** | `write` with `patch` (set/remove/merge/append/move) or `patches` (batch, atomic rollback) by `jsonPath` | Avoid re-sending the whole large JSON; precise local edits; use `patches` to edit many at once |
|
|
55
55
|
| **Large-object retrieval** | `read` supports `fields` (projection) + `depth` (truncation) to shrink payload; `query_data` (JSONPath)/`search_data` (text)/`eval_script` (sandboxed JS) | Efficient retrieval + pinpoint location in large JSON |
|
|
56
56
|
| **Rollbackable** | per-path snapshots (auto-stacked) + session checkpoint | Bad edit → one-click restore to the last good state |
|
|
57
57
|
| **Optimistic lock** | `conflictWatchFields` opt-in optimistic lock + conflict human-in-the-loop (3.29+ `conflictPolicy` declares auto-adjudication: overwrite / keep_external) | Concurrent external edits detected → suspend, user picks keep/overwrite/restore |
|
|
@@ -95,7 +95,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
|
|
|
95
95
|
|---|---|---|---|---|---|
|
|
96
96
|
| Framework-agnostic, UI bundled | ✅ Vue bundled, host-agnostic | ❌ React-only | ✅ (no UI) | ✅ (no UI) | ✅ (no UI) |
|
|
97
97
|
| Schema-validated JSON ops | ✅ zod, whitelist + merge-safe | ⚠️ partial (tool args) | ⚠️ tool args only | ⚠️ tool args only | ❌ |
|
|
98
|
-
| Incremental patch (jsonPath) | ✅ `write` patch / `
|
|
98
|
+
| Incremental patch (jsonPath) | ✅ `write` patch / `patches` | ❌ | ❌ | ❌ | ❌ |
|
|
99
99
|
| Optimistic lock + conflict HITL | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
|
|
100
100
|
| Snapshot rollback + checkpoint | ✅ per-path + session | ❌ | ❌ | ❌ | ❌ |
|
|
101
101
|
| Proactive human-confirm | ✅ built-in | ⚠️ manual | ❌ | ❌ | ❌ |
|
|
@@ -308,7 +308,7 @@ createChatSdk({ subagents: [
|
|
|
308
308
|
|
|
309
309
|
### Built-in tools (Agent-callable)
|
|
310
310
|
|
|
311
|
-
- **data ops** (all
|
|
311
|
+
- **data ops** (all 10 tools always exposed): `read` (list/get/describe merged) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `restore_data` / `history_data` (snapshot rollback/history); `describe_data` / `schema_data` / `diff_data` / focus tools (low-level CRUD `get_data`/`set_data`/`edit_data`/`delete_data` removed in 4.0 — `read`/`write` cover everything)
|
|
312
312
|
- **window query**: `query_data` (JSONPath) / `search_data` (fuzzy) / `eval_script` (sandboxed)
|
|
313
313
|
- **fetch**: `fetch_document`
|
|
314
314
|
- **vfs**: `vfs_read` / `vfs_write` / `vfs_edit` / `vfs_ls` / `vfs_glob` / `vfs_grep`
|
|
@@ -500,7 +500,7 @@ function switchTo(i: number) {
|
|
|
500
500
|
|
|
501
501
|
```bash
|
|
502
502
|
npm test # 2894 assertions (tsx, source-level; no LLM dependency)
|
|
503
|
-
npm run test:e2e #
|
|
503
|
+
npm run test:e2e # 957 integration assertions (node, built dist; covers APIs/options/modules/simple&complex scenes: default systemPrompt(capability overview) / dynamic register + inspect sync / inspect(tools/middleware/subagent/verify/mcp/todos/lastCompression/checkpoints reflect config) / custom tools/middleware/skills/memory injection / runtime dynamic reconfiguration(setTools/addTool/removeTool/setLlm/setMemory/setSubagents reflect) / switchSession(on/off) / shareContext on/off sharing/independent / storage backends + object config / presets(3) / checkpoint / exports complete(39+ fns/components) / util fns usable(isQuotaError/estimateTokens/jpEval/searchJson) / source=builtin / mount boundary / hook multi-listener / llm config / hide/show / error scenes)
|
|
504
504
|
```
|
|
505
505
|
|
|
506
506
|
## Local npm package test
|
package/README.zh-CN.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/page-agent-sdk)
|
|
10
10
|
[](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
|
|
11
|
-
[](#自测)
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
|---|---|---|
|
|
52
52
|
| **范围控制** | schema 校验(`data`)—— 只能改 schema 允许的值;schema 形状自动白名单(顶层 + 子路径按子 schema 递归投影,未声明字段隐藏/拒改/整体 set 转 merge 防误删) | AI 传非法值 → 拒绝;非声明字段 → `PATH_DENIED` |
|
|
53
53
|
| **合法性校验** | zod schema —— `write`/`set`/`edit` 按 schema 校验 | 类型/枚举/结构不合法 → 结构化错误,不写入 |
|
|
54
|
-
| **增量操作** | `write` 的 `patch
|
|
54
|
+
| **增量操作** | `write` 的 `patch`(set/remove/merge/append/move)或 `patches`(批量,原子回滚)按 `jsonPath` 发 patch | 避免重传整个大 JSON,精确改局部;一次改多处用 `patches` |
|
|
55
55
|
| **大对象检索** | `read` 支持 `fields`(字段裁剪)+ `depth`(深度截断)减体积;`query_data`(JSONPath)/`search_data`(文本)/`eval_script`(沙箱 JS) | 大 JSON 高效检索 + 局部定位 |
|
|
56
56
|
| **可回滚** | per-path 快照(自动入栈)+ 会话 checkpoint | 改坏了一键回退到上次正常态 |
|
|
57
57
|
| **乐观锁** | `conflictWatchFields` 声明式乐观锁 + 冲突人工介入(3.29+ `conflictPolicy` 可声明自动裁决:overwrite / keep_external) | 检测并发外部修改 → 挂起,用户选保留/覆盖/回退 |
|
|
@@ -95,7 +95,7 @@
|
|
|
95
95
|
|---|---|---|---|---|---|
|
|
96
96
|
| 框架无关、UI 打包进库 | ✅ Vue 打包,宿主任意 | ❌ 仅 React | ✅(无 UI) | ✅(无 UI) | ✅(无 UI) |
|
|
97
97
|
| schema 校验的 JSON 操作 | ✅ zod + 白名单 + merge 防误删 | ⚠️ 部分(工具参数) | ⚠️ 仅工具参数 | ⚠️ 仅工具参数 | ❌ |
|
|
98
|
-
| 增量 patch(jsonPath) | ✅ `write` patch / `
|
|
98
|
+
| 增量 patch(jsonPath) | ✅ `write` patch / `patches` | ❌ | ❌ | ❌ | ❌ |
|
|
99
99
|
| 乐观锁 + 冲突人工介入 | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
|
|
100
100
|
| 快照回退 + checkpoint | ✅ per-path + 会话级 | ❌ | ❌ | ❌ | ❌ |
|
|
101
101
|
| 主动人工确认 | ✅ 内置 | ⚠️ 手动 | ❌ | ❌ | ❌ |
|
|
@@ -306,7 +306,7 @@ createChatSdk({ subagents: [
|
|
|
306
306
|
|
|
307
307
|
### 内置工具（Agent 可调用）
|
|
308
308
|
|
|
309
|
-
- **数据操作**（
|
|
309
|
+
- **数据操作**（10 工具恒全暴露）：`read`（合并 describe/get）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`restore_data` / `history_data`（快照回退/查历史）；`describe_data` / `schema_data` / `diff_data` / focus 工具族（底层 CRUD `get_data`/`set_data`/`edit_data`/`delete_data` 已于 4.0 移除，`read`/`write` 全覆盖）
|
|
310
310
|
- **window 查询**：`query_data`（JSONPath）/ `search_data`（模糊搜索）/ `eval_script`（沙箱脚本）
|
|
311
311
|
- **抓取**：`fetch_document`
|
|
312
312
|
- **DOM 检视**（`capabilities.domInspect`，opt-in）：`get_dom`（常驻）+ `dom_search` / `dom_info`（经内置 `dom-inspect` skill 按需注入 —— `load_skill("dom-inspect")` 激活；skills 关时降级直插）
|
|
@@ -503,7 +503,7 @@ function switchTo(i: number) {
|
|
|
503
503
|
|
|
504
504
|
```bash
|
|
505
505
|
npm test # 2894 项断言（tsx 源码级，不依赖 LLM）
|
|
506
|
-
npm run test:e2e #
|
|
506
|
+
npm run test:e2e # 957 项集成断言（node 跑构建产物 dist；覆盖各 API/配置项/功能模块/简单与复杂场景：默认 systemPrompt(含能力概述) / 动态注册与 inspect 同步 / inspect(tools/middleware/subagent/verify/mcp/todos/lastCompression/checkpoints 反映配置) / 自定义 tools/middleware/skills/memory 注入 / 运行时动态重配置(setTools/addTool/removeTool/setLlm/setMemory/setSubagents 反映) / switchSession(开/未开) / shareContext 开/关共享独立 / storage 后端+对象配置 / presets 三预设 / checkpoint / 导出项完整(39+ 函数/组件) / 工具函数可用(isQuotaError/estimateTokens/jpEval/searchJson) / source=builtin / mount 边界 / hook 多监听器 / llm 配置 / 错误场景）
|
|
507
507
|
```
|
|
508
508
|
|
|
509
509
|
## 本地 npm 包测试
|