page-agent-sdk 3.23.1 → 3.24.0

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-2377%20asserts-brightgreen.svg)](#self-tests)
+[![tests](https://img.shields.io/badge/self%20tests-2396%20asserts-brightgreen.svg)](#self-tests)
 
 ---
 
@@ -136,7 +136,7 @@ CDN zero-config: `<script src="https://unpkg.com/page-agent-sdk"></script>` →
 | 🛡️ compression-safe | Live data snapshot + preserved tool results in summary; write returns hint available paths; `systemPromptHelpers.reliableWriteRules` | built-in |
 | 💰 Context economy (3.10/3.11+) | Compression cost cap `promptSoftCapTokens` (defaults to 160K when window ≥320K — huge-window models no longer burn hundreds of thousands of tokens before compressing; reflected via `inspect().compression`) + agent budget self-awareness (70%-rounds / half-cap token hint, consecutive write-failure reminder, per-invocation `roundTokenBudget` friendly wrap-up) + tool-description slimming (-40% prompt) | `contextOptions.promptSoftCapTokens`, `roundTokenBudget` |
 | 💾 persistence | IndexedDB multi-session + quota eviction + switch | `storage` |
-| 👁 DOM read (2.20+) | Read rendered DOM structure (depth-cutoff + attr whitelist); verify modifications took effect — distinct from `eval_script` (structured + read-only) | `capabilities.domInspect` |
+| 👁 DOM inspect (2.20+) | `get_dom` structure read + `dom_search` (selector/text) + `dom_info` (content/computed styles/event bindings from inline/Vue props/listener recorder) — lazy-injected via the `dom-inspect` skill so they don't occupy standing tool context | `capabilities.domInspect` |
 | 📊 Context inspector | Snapshot actual-LLM-message composition (total / occupancy / category ratio); DebugDrawer `📊 上下文` tab + `inspectContext()`; zero LLM cost, default on | `capabilities.contextInspector` |
 | 🤖 Agent-driven compression (2.33+) | `capabilities.agentCompression` (opt-in) lets the summary LLM decide per-trigger compression strategy via an `inspect_context` tool loop (keepRounds / windowRatio / summary mode / recall / preserve); `shouldTriggerCompression` gate avoids per-message LLM cost; decide failure/timeout degrades to static; `decisionTimeoutMs` / `decisionMaxTokens` configurable | `capabilities.agentCompression` + `summaryLlm` |
 | 🎯 Cross-session user preference memory | `capabilities.preferences` (**opt-in, default off** — auto-writing the user's browser is behavior-sensitive): the agent captures durable user preferences from conversation — strong signal (explicit commands like "Remember: …", zero LLM) / medium signal (pattern-word prefilter + small-LLM extraction; the core test is **durable taste vs this-round task instruction**) / behavioral inference **not captured** (better to miss than to learn wrong — one false preference would ride along every future session); preferences persist independently (preferenceStore, IndexedDB, same shape as storage/skillStorage; same topic **later statement overrides earlier**, FIFO ≤20); injected as a pin segment into the system prompt each round (survives sessions and compression); manage wrongly-learned entries via `sdk.getPreferences()/removePreference(id)/clearPreferences()`, plus a read-only DebugDrawer "User preferences" section | `capabilities: { preferences: true }` + optional `preferenceStorage` |
@@ -533,8 +533,8 @@ function switchTo(i: number) {
 ## Self-tests
 
 ```bash
-npm test            # 2377 assertions (tsx, source-level; no LLM dependency)
-npm run test:e2e    # 742 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)
+npm test            # 2396 assertions (tsx, source-level; no LLM dependency)
+npm run test:e2e    # 753 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)
 ```
 
 ## Local npm package test

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-2377%20asserts-brightgreen.svg)](#自测)
+[![tests](https://img.shields.io/badge/self%20tests-2396%20asserts-brightgreen.svg)](#自测)
 
 ---
 
@@ -280,7 +280,8 @@ createChatSdk({ subagents: [
 - **数据操作**（默认 `toolMode:'simple'`）：`read`（合并 describe/get）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`toolMode:'advanced'` 另暴露底层 `describe_data` / `get_data`（@deprecated，改用 read）/ `set_data` / `edit_data`（jsonPath 增量 patch）/ `delete_data` / `restore_data` / `history_data`（含 list 模式）/ `diff_data`
 - **window 查询**：`query_data`（JSONPath）/ `search_data`（模糊搜索）/ `eval_script`（沙箱脚本）
 - **抓取**：`fetch_document`
-- **DOM 读取**（2.18+,`capabilities.domInspect:true` 开,默认关）：`get_dom`（读渲染后 DOM 结构,看修改是否生效;区别于 eval_script 的结构化只读）
+- **DOM 检视**（`capabilities.domInspect`，opt-in）：`get_dom`（常驻）+ `dom_search` / `dom_info`（经内置 `dom-inspect` skill 按需注入 —— `load_skill("dom-inspect")` 激活；skills 关时降级直插）
+- **DOM 检视**（2.18+,`capabilities.domInspect:true` 开,默认关）：`get_dom`（读渲染后 DOM 结构,看修改是否生效）+ `dom_search`（选择器/文本检索元素）/ `dom_info`（内容/计算样式/事件绑定三源:inline on*/Vue props/addEventListener 记录器;经内置 `dom-inspect` skill 按需注入,不占常驻工具上下文）
 - **上下文检查**（`capabilities.contextInspector` 默认开）：`sdk.inspectContext()`/`inspect().context` 读每轮实际消息的分类 token 占比（system 段 / 工具结果 / 历史等）,DebugDrawer「📊 上下文」tab 展示占用/分类/压缩;纯计算零 LLM 成本
 - **压缩决策**（`capabilities.agentCompression` opt-in 默认关,需 `summaryLlm`,2.33+）：开 + summaryLlm 可用 → summarization 每轮先 `shouldTriggerCompression` gate(纯函数 token/轮数两模式,避免每条消息都 decide 烧 LLM)→ `decide` 两段式工具循环(bind `inspect_context` 查构成 → 输出决策 JSON)→ `compress(messages, decision)` 用决策切分/摘要 mode/召回/preserve(∪ 扩展);decide 失败/超时/模型不支持工具 → null 降级静态压缩(零阻塞)。`decisionTimeoutMs`(默认 6s)/`decisionMaxTokens`(默认 2048)可配;决策自动流到 `inspect().lastCompression.decision` + DebugDrawer「🤖 agent 决策」注记
 - **宿主动作**（2.18+,`actions` 注册）：集成方注册 save_draft/publish 等页面操作,SDK 自动生成命名 tool,agent 直接调用触发宿主(无需 trigger_action 中转)
@@ -478,8 +479,8 @@ function switchTo(i: number) {
 ## 自测
 
 ```bash
-npm test            # 2377 项断言（tsx 源码级，不依赖 LLM）
-npm run test:e2e    # 742 项集成断言（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 配置 / 错误场景）
+npm test            # 2396 项断言（tsx 源码级，不依赖 LLM）
+npm run test:e2e    # 753 项集成断言（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 配置 / 错误场景）
 ```
 
 ## 本地 npm 包测试