page-agent-sdk 2.28.0 → 2.30.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 +8 -5
- package/README.zh-CN.md +8 -5
- package/dist/page-agent-sdk.iife.js +113 -112
- package/dist/page-agent-sdk.js +4554 -4259
- package/dist/page-agent-sdk.umd.cjs +80 -79
- package/dist/style.css +1 -1
- package/package.json +1 -1
- package/types/index.d.ts +22 -1
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
|
|
|
@@ -141,6 +141,7 @@ CDN zero-config: `<script src="https://unpkg.com/page-agent-sdk"></script>` →
|
|
|
141
141
|
| 🧩 schema tiered disclosure (2.20+) | Large schema → systemPrompt injects top-level overview only (no constraints/no recursion); deep constraints via `schema_data` on demand; small schema unaffected (full) | `schemaHint` |
|
|
142
142
|
| 📌 cross-compress working memory (2.20+) | Pin recent read/query paths + hashes across compression; no re-fetch, correct optimistic-lock hash | `capabilities.workingMemory` |
|
|
143
143
|
| 🤖 unattended automation (2.20+) | Resource budget guard (`tokenBudget`/`timeBudgetMs`) + fatal-error auto-recovery (`maxAutoRetries`: restore checkpoint + retry) + cross-refresh resume + `sdk.batch(tasks)` batch processing | `capabilities.automation` |
|
|
144
|
+
| 📐 context resilience (2.30+) | Hard floor `contextWindow ≥200K` (rejects <200K models like legacy `deepseek`/`gpt-4o`/`glm-4.5` at startup); three gates (compress/trim/offload) thresholds follow the live window after `setLlm`; reactive retry on `context_length_exceeded` (aggressive trim → single retry, never fails raw); vfs large-result refs protected from LRU eviction + OOM 1.5× fallback; system-prompt budget (25% window, drops non-pinned segments, keeps base/mission/workingMemory) | built-in |
|
|
144
145
|
|
|
145
146
|
Capabilities default on (`verify`/`approval`/`checkpoint` default off; **proactive `humanConfirm` default on** — AI asks when uncertain/multi-plan instead of guessing). Turn off unneeded ones via `capabilities` to save tokens.
|
|
146
147
|
|
|
@@ -187,7 +188,7 @@ createVerifyMiddleware, createWriteBackCheck, createApprovalMiddleware,
|
|
|
187
188
|
createHumanConfirmMiddleware, createHumanConfirmTool, createCheckpointMiddleware, createCheckpointManager,
|
|
188
189
|
createUsageHintsMiddleware, createDataOps, createVfs, connectMcp
|
|
189
190
|
// context & model
|
|
190
|
-
resolveContextOptions, CONTEXT_PRESETS, resolveModelCaps, estimateTokens
|
|
191
|
+
resolveContextOptions, CONTEXT_PRESETS, resolveModelCaps, estimateTokens, isContextLengthError, MIN_CONTEXT_WINDOW
|
|
191
192
|
// storage
|
|
192
193
|
createSessionStore, createMemoryBackend, createWebStorageBackend, isQuotaError
|
|
193
194
|
// UI (reuse when headless)
|
|
@@ -207,7 +208,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, useChat
|
|
|
207
208
|
| | `augmentSystem` | `(ctx:{state,data?}) => string \| undefined` | Dynamic system prompt injection hook: called each turn, returns a string injected as a segment based on runtime state/data; return undefined to skip; callback errors degrade to skip (no crash). `ctx.data` is taken from liveData() each turn (auto-syncs after setData), enabling dynamic component descriptions / partial schema hints. Not set = current behavior |
|
|
208
209
|
| **Page data** | `data` | `{schema,bind,description?}` | Single main object: declare zod schema (validation + field descriptions auto-injected into prompt) + bind (reactive/plain object, tools read/write directly, no `window`) + description |
|
|
209
210
|
| | `tools` / `skills` / `memory` | `Tool[]` / `SkillSpec[]` / `string` | Custom tools / skills / AGENTS.md-style directives |
|
|
210
|
-
| **Capability toggles** | `capabilities` | `{planning?,dataOps?,fetch?,skills?,vfs?,summarization?,memory?,subagent?,verify?}` | Default all on (`verify` default off); `false` to turn off |
|
|
211
|
+
| **Capability toggles** | `capabilities` | `{planning?,dataOps?,fetch?,skills?,vfs?,summarization?,memory?,subagent?,verify?,focus?}` | Default all on (`verify` default off; `focus` = context focus for refining one component, default on); `false` to turn off |
|
|
211
212
|
| | `permissions` | `PermissionRule[]` | Scope whitelist (first-match-wins, default off) |
|
|
212
213
|
| | `humanConfirm` | `boolean` · default `true` | Proactive inquiry (AI asks when uncertain/multi-plan) |
|
|
213
214
|
| | `approval` | `{tools?,confirm?,timeoutMs?,humanConfirmTool?}` · default off | Passive confirm whitelist (pre-write allow/deny) |
|
|
@@ -409,6 +410,8 @@ VITE_AI_TEMPERATURE=0.3 # low temp recommended for structured ops
|
|
|
409
410
|
# VITE_AI_MAX_TOKENS= # omit → model default
|
|
410
411
|
```
|
|
411
412
|
|
|
413
|
+
> ⚠️ **Minimum context window 200K (2.30+)**: the SDK rejects models with `contextWindow < 200000` at startup (`setLlm`/subagent too) — excludes legacy `deepseek`/`deepseek-reasoner`/`glm-4.5`/`gpt-4o`/`qwen-max` etc. Use a ≥200K model (`deepseek-v4`/`glm-5.2`/`claude-3-*`/`kimi-k3`/`qwen-1m`) or declare `llm: { contextWindow: 500000 }` to override the table lookup.
|
|
414
|
+
|
|
412
415
|
```ts
|
|
413
416
|
createChatSdk({
|
|
414
417
|
container: '#root',
|
|
@@ -520,8 +523,8 @@ function switchTo(i: number) {
|
|
|
520
523
|
## Self-tests
|
|
521
524
|
|
|
522
525
|
```bash
|
|
523
|
-
npm test #
|
|
524
|
-
npm run test:e2e #
|
|
526
|
+
npm test # 1342 assertions (tsx, source-level; no LLM dependency)
|
|
527
|
+
npm run test:e2e # 353 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)
|
|
525
528
|
```
|
|
526
529
|
|
|
527
530
|
## 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
|
|
|
@@ -136,6 +136,7 @@ CDN 零配置：`<script src="https://unpkg.com/page-agent-sdk"></script>` → `
|
|
|
136
136
|
| 🛡️ 压缩不丢信息 | 摘要内嵌当前 data 快照 + 保留指定工具结果；写返回附可操作 path；`systemPromptHelpers.reliableWriteRules` | 内置 |
|
|
137
137
|
| 💾 持久化 | IndexedDB 多会话 + 配额淘汰 + 切换 | `storage` |
|
|
138
138
|
| 🤖 无人值守自动化 (2.20+) | 资源预算闸（`tokenBudget`/`timeBudgetMs`）+ 致命错误自动恢复（`maxAutoRetries`：回退 checkpoint + 重试）+ 刷新续跑 + `sdk.batch(tasks)` 批处理 | `capabilities.automation` |
|
|
139
|
+
| 📐 上下文健壮性 (2.30+) | 硬地板 `contextWindow ≥200K`(启动拒绝 <200K 模型如老款 `deepseek`/`gpt-4o`/`glm-4.5`);三道闸(压缩/trim/offload)阈值在 `setLlm` 后跟随实时窗口;遇 `context_length_exceeded` 反应性重试(激进 trim → 重试一次,不裸失败);vfs 大结果引用受保护免 LRU 淘汰 + OOM 1.5× 兜底;系统段预算(25% 窗口,丢弃非 pin 段保 base/mission/workingMemory) | 内置 |
|
|
139
140
|
|
|
140
141
|
能力默认开（`verify`/`approval`/`checkpoint` 默认关；**主动征询 `humanConfirm` 默认开**——AI 遇不确定/多方案主动问你、不猜测），可经 `capabilities` 关掉无用的省 token。
|
|
141
142
|
|
|
@@ -182,7 +183,7 @@ createVerifyMiddleware, createWriteBackCheck, createApprovalMiddleware,
|
|
|
182
183
|
createHumanConfirmMiddleware, createHumanConfirmTool, createCheckpointMiddleware, createCheckpointManager,
|
|
183
184
|
createUsageHintsMiddleware, createDataOps, createVfs, connectMcp
|
|
184
185
|
// 上下文/模型
|
|
185
|
-
resolveContextOptions, CONTEXT_PRESETS, resolveModelCaps, estimateTokens
|
|
186
|
+
resolveContextOptions, CONTEXT_PRESETS, resolveModelCaps, estimateTokens, isContextLengthError, MIN_CONTEXT_WINDOW
|
|
186
187
|
// 存储
|
|
187
188
|
createSessionStore, createMemoryBackend, createWebStorageBackend, isQuotaError
|
|
188
189
|
// UI(headless 自建 UI 复用)
|
|
@@ -202,7 +203,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, useChat
|
|
|
202
203
|
| | `augmentSystem` | `(ctx:{state,data?}) => string \| undefined` | 动态 system prompt 注入钩子:每轮调,按运行时 state/data 返回字符串作为一段注入;返回 undefined 跳过;回调抛错降级跳过(不崩)。`ctx.data` 每轮从 liveData() 取最新(setData 后自动同步),可据此动态算当前组件说明 / 部分 schema 描述。不配 = 现状行为 |
|
|
203
204
|
| **页面数据** | `data` | `{schema,bind,description?}` | 单主对象:声明 zod schema(校验 + 字段描述自动注入提示词)+ bind(reactive/普通对象,工具直接读写,不挂 window)+ description |
|
|
204
205
|
| | `tools` / `skills` / `memory` | `Tool[]` / `SkillSpec[]` / `string` | 自定义工具 / 技能 / AGENTS.md 风格持久指令 |
|
|
205
|
-
| **能力开关** | `capabilities` | `{planning?,missionAnchor?,dataOps?,fetch?,skills?,vfs?,summarization?,memory?,workingMemory?,subagent?,verify?,domInspect?}` | 核心默认开（`verify`/`domInspect` 默认关,opt-in
|
|
206
|
+
| **能力开关** | `capabilities` | `{planning?,missionAnchor?,dataOps?,fetch?,skills?,vfs?,summarization?,memory?,workingMemory?,subagent?,verify?,domInspect?,focus?}` | 核心默认开（`verify`/`domInspect` 默认关,opt-in;`focus` 上下文聚焦·指定组件精修,默认开)；`false` 关掉省 token |
|
|
206
207
|
| | `actions` | `Record<string,{description,run,params?}>` | **(2.18+) 宿主动作**：注册 save_draft/publish 等页面操作 → SDK 自动生成命名 tool 供 agent 触发 |
|
|
207
208
|
| | `schemaHint` | `{maxKeys?,maxChars?}` · 默认 `{15,4000}` | **(2.18+) 大 schema 分层披露阈值**：超则 systemPrompt 只注入顶层概览（不带约束/不递归）,深层约束按需 `schema_data` 查;小 schema 无感（全量） |
|
|
208
209
|
| | `permissions` | `PermissionRule[]` | scope 白名单（first-match-wins，默认不启用） |
|
|
@@ -354,6 +355,8 @@ VITE_AI_TEMPERATURE=0.3 # 结构化操作建议低温
|
|
|
354
355
|
# VITE_AI_MAX_TOKENS= # 不配则按模型自动取值
|
|
355
356
|
```
|
|
356
357
|
|
|
358
|
+
> ⚠️ **最小上下文窗口 200K(2.30+)**:SDK 启动(`setLlm`/子 agent 同样)拒绝 `contextWindow < 200000` 的模型 —— 排除老款 `deepseek`/`deepseek-reasoner`/`glm-4.5`/`gpt-4o`/`qwen-max` 等。用 ≥200K 模型(`deepseek-v4`/`glm-5.2`/`claude-3-*`/`kimi-k3`/`qwen-1m`)或声明 `llm: { contextWindow: 500000 }` 覆盖查表。
|
|
359
|
+
|
|
357
360
|
```ts
|
|
358
361
|
createChatSdk({
|
|
359
362
|
container: '#root',
|
|
@@ -465,8 +468,8 @@ function switchTo(i: number) {
|
|
|
465
468
|
## 自测
|
|
466
469
|
|
|
467
470
|
```bash
|
|
468
|
-
npm test #
|
|
469
|
-
npm run test:e2e #
|
|
471
|
+
npm test # 1342 项断言（tsx 源码级，不依赖 LLM）
|
|
472
|
+
npm run test:e2e # 353 项集成断言（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 配置 / 错误场景）
|
|
470
473
|
```
|
|
471
474
|
|
|
472
475
|
## 本地 npm 包测试
|