page-agent-sdk 3.31.0 → 3.32.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 +7 -7
- package/README.zh-CN.md +6 -6
- package/dist/page-agent-sdk.headless.js +2282 -2253
- package/dist/page-agent-sdk.iife.js +143 -143
- package/dist/page-agent-sdk.js +2770 -2741
- package/dist/page-agent-sdk.legacy.js +8490 -8460
- package/dist/page-agent-sdk.umd.cjs +90 -90
- package/package.json +1 -1
- package/types/headless.d.ts +6 -9
- package/types/index.d.ts +6 -9
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
|
|
|
@@ -53,7 +53,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
|
|
|
53
53
|
| **Incremental op** | `write` with `patch`/`patches` (batch, atomic rollback) or advanced `edit_data` patches by `jsonPath` (set/remove/merge/append) | Avoid re-sending the whole large JSON; precise local edits; use `patches` to edit many at once |
|
|
54
54
|
| **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 |
|
|
55
55
|
| **Rollbackable** | per-path snapshots (auto-stacked) + session checkpoint | Bad edit → one-click restore to the last good state |
|
|
56
|
-
| **Optimistic lock** | `
|
|
56
|
+
| **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 |
|
|
57
57
|
|
|
58
58
|
"Editing JSON" moves from free-form LLM text generation to **structured, validatable, auditable, rollbackable** tool operations. This is the fundamental difference from "let the AI output a JSON string directly".
|
|
59
59
|
|
|
@@ -83,7 +83,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
|
|
|
83
83
|
|
|
84
84
|
- **Q: I want an AI assistant embedded in my web page that can edit the page data.** → `page-agent-sdk`: declare a zod schema + `bind`, mount the dialog, done. See [30-second quickstart](#30-second-quickstart).
|
|
85
85
|
- **Q: Alternative to CopilotKit / LangChain for an in-page agent?** → `page-agent-sdk` is framework-agnostic (Vue bundled, host can be React / vanilla), schema-validated, ships optimistic lock + snapshot rollback + MCP, and needs no LangGraph. See [Comparison](#comparison).
|
|
86
|
-
- **Q: How to let AI safely edit a large JSON on my page?** → `data` + zod schema + `write` with `patch` / `patches` + `
|
|
86
|
+
- **Q: How to let AI safely edit a large JSON on my page?** → `data` + zod schema + `write` with `patch` / `patches` + `conflictWatchFields` optimistic lock. Invalid edits are rejected pre-write; bad edits rollback in one click.
|
|
87
87
|
- **Q: Does it work with DeepSeek / OpenAI / any OpenAI-compatible endpoint / Anthropic Claude?** → Yes. `llm: { apiKey, baseUrl, model }` defaults to DeepSeek (OpenAI protocol); `llm: { provider: 'anthropic', apiKey, model: 'claude-...' }` uses Claude native protocol (dynamic-loaded `@langchain/anthropic`, optional peer); any LangChain `BaseChatModel` also accepted.
|
|
88
88
|
- **Q: Can I run it headless / in Node.js?** → Yes. `ui:false` + `storage:'memory'`, drive via `sdk.send`. See [headless-demo](#examples).
|
|
89
89
|
- **Q: Does it support MCP?** → Yes. `mcp: [{ transport, url }]` connects remote MCP servers and injects tools dynamically.
|
|
@@ -95,7 +95,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
|
|
|
95
95
|
| Framework-agnostic, UI bundled | ✅ Vue bundled, host-agnostic | ❌ React-only | ✅ (no UI) | ✅ (no UI) | ✅ (no UI) |
|
|
96
96
|
| Schema-validated JSON ops | ✅ zod, whitelist + merge-safe | ⚠️ partial (tool args) | ⚠️ tool args only | ⚠️ tool args only | ❌ |
|
|
97
97
|
| Incremental patch (jsonPath) | ✅ `write` patch / `edit_data` | ❌ | ❌ | ❌ | ❌ |
|
|
98
|
-
| Optimistic lock + conflict HITL | ✅ `
|
|
98
|
+
| Optimistic lock + conflict HITL | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
|
|
99
99
|
| Snapshot rollback + checkpoint | ✅ per-path + session | ❌ | ❌ | ❌ | ❌ |
|
|
100
100
|
| Proactive human-confirm | ✅ built-in | ⚠️ manual | ❌ | ❌ | ❌ |
|
|
101
101
|
| MCP | ✅ | ✅ | ✅ | ✅ | manual |
|
|
@@ -476,7 +476,7 @@ function switchTo(i: number) {
|
|
|
476
476
|
}
|
|
477
477
|
```
|
|
478
478
|
|
|
479
|
-
> Multiple agents operating on the same `data` need coordination (optimistic lock `
|
|
479
|
+
> Multiple agents operating on the same `data` need coordination (optimistic lock `conflictWatchFields` or `jsonPath` partitioning); each managing its own `data` object has no conflict (recommended). Full example: `examples/multi-agent-demo/`.
|
|
480
480
|
|
|
481
481
|
## Documentation
|
|
482
482
|
|
|
@@ -492,8 +492,8 @@ function switchTo(i: number) {
|
|
|
492
492
|
## Self-tests
|
|
493
493
|
|
|
494
494
|
```bash
|
|
495
|
-
npm test #
|
|
496
|
-
npm run test:e2e #
|
|
495
|
+
npm test # 2525 assertions (tsx, source-level; no LLM dependency)
|
|
496
|
+
npm run test:e2e # 822 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)
|
|
497
497
|
```
|
|
498
498
|
|
|
499
499
|
## 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
|
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
| **增量操作** | `write` 的 `patch`/`patches`(批量,原子回滚)或 advanced `edit_data` 按 `jsonPath` 发 patch(set/remove/merge/append) | 避免重传整个大 JSON,精确改局部;一次改多处用 `patches` |
|
|
54
54
|
| **大对象检索** | `read` 支持 `fields`(字段裁剪)+ `depth`(深度截断)减体积;`query_data`(JSONPath)/`search_data`(文本)/`eval_script`(沙箱 JS) | 大 JSON 高效检索 + 局部定位 |
|
|
55
55
|
| **可回滚** | per-path 快照(自动入栈)+ 会话 checkpoint | 改坏了一键回退到上次正常态 |
|
|
56
|
-
| **乐观锁** | `
|
|
56
|
+
| **乐观锁** | `conflictWatchFields` 声明式乐观锁 + 冲突人工介入(3.29+ `conflictPolicy` 可声明自动裁决:overwrite / keep_external) | 检测并发外部修改 → 挂起,用户选保留/覆盖/回退 |
|
|
57
57
|
|
|
58
58
|
「改 JSON」从 LLM 自由生成文本 → **结构化、可校验、可审计、可回滚**的工具操作。这是它区别于「让 AI 直接输出 JSON 字符串」的根本所在。
|
|
59
59
|
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
|
|
84
84
|
- **Q：我想在网页里加一个能改页面数据的 AI 助手。** → 用 `page-agent-sdk`：声明 zod schema + `bind`、挂载对话框即可。见[30 秒上手](#30-秒上手)。
|
|
85
85
|
- **Q：CopilotKit / LangChain 的页面内 agent 替代方案?** → `page-agent-sdk` 框架无关（Vue 打包进库，宿主可 React / 原生）、schema 校验、自带乐观锁 + 快照回退 + MCP，不依赖 LangGraph。见[对比](#对比)。
|
|
86
|
-
- **Q：怎么让 AI 安全地改页面上的大 JSON?** → `data` + zod schema + `write` 的 `patch` / `patches` + `
|
|
86
|
+
- **Q：怎么让 AI 安全地改页面上的大 JSON?** → `data` + zod schema + `write` 的 `patch` / `patches` + `conflictWatchFields` 乐观锁。非法编辑写前拦截、改错了一键回退。
|
|
87
87
|
- **Q：支持 DeepSeek / OpenAI / 任意 OpenAI 兼容端点 / Anthropic Claude 吗?** → 支持。`llm:{apiKey,baseUrl,model}` 默认接 DeepSeek（OpenAI 协议）；`llm:{provider:'anthropic',apiKey,model:'claude-...'}` 走 Claude 原生协议（动态加载 `@langchain/anthropic`，不用不强求装）；也接受任意 LangChain `BaseChatModel`。
|
|
88
88
|
- **Q：能 headless / 在 Node.js 跑吗?** → 能。`ui:false` + `storage:'memory'`，用 `sdk.send` 驱动。见 [headless-demo](#示例)。
|
|
89
89
|
- **Q：支持 MCP 吗?** → 支持。`mcp:[{transport,url}]` 连远程 MCP server 动态注入工具。
|
|
@@ -95,7 +95,7 @@
|
|
|
95
95
|
| 框架无关、UI 打包进库 | ✅ Vue 打包,宿主任意 | ❌ 仅 React | ✅(无 UI) | ✅(无 UI) | ✅(无 UI) |
|
|
96
96
|
| schema 校验的 JSON 操作 | ✅ zod + 白名单 + merge 防误删 | ⚠️ 部分(工具参数) | ⚠️ 仅工具参数 | ⚠️ 仅工具参数 | ❌ |
|
|
97
97
|
| 增量 patch(jsonPath) | ✅ `write` patch / `edit_data` | ❌ | ❌ | ❌ | ❌ |
|
|
98
|
-
| 乐观锁 + 冲突人工介入 | ✅ `
|
|
98
|
+
| 乐观锁 + 冲突人工介入 | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
|
|
99
99
|
| 快照回退 + checkpoint | ✅ per-path + 会话级 | ❌ | ❌ | ❌ | ❌ |
|
|
100
100
|
| 主动人工确认 | ✅ 内置 | ⚠️ 手动 | ❌ | ❌ | ❌ |
|
|
101
101
|
| MCP | ✅ | ✅ | ✅ | ✅ | 手动 |
|
|
@@ -495,8 +495,8 @@ function switchTo(i: number) {
|
|
|
495
495
|
## 自测
|
|
496
496
|
|
|
497
497
|
```bash
|
|
498
|
-
npm test #
|
|
499
|
-
npm run test:e2e #
|
|
498
|
+
npm test # 2525 项断言（tsx 源码级，不依赖 LLM）
|
|
499
|
+
npm run test:e2e # 822 项集成断言（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 配置 / 错误场景）
|
|
500
500
|
```
|
|
501
501
|
|
|
502
502
|
## 本地 npm 包测试
|