page-agent-sdk 4.19.1 → 4.20.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-3705%20asserts-brightgreen.svg)](#self-tests)
+[![tests](https://img.shields.io/badge/self%20tests-3716%20asserts-brightgreen.svg)](#self-tests)
 
 ---
 
@@ -171,7 +171,7 @@ CDN zero-config: `<script src="https://unpkg.com/page-agent-sdk"></script>` →
 | 🤖 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` |
 | 🧭 Instruction adherence (3.35+) | **Completion gate**: if the agent tries to close with plain text while todos still have unfinished items, a "two-exit" nudge is injected (mark done via update_todo, or keep executing; ≤2 retries) — fixes "planned 3 tasks, did 1, then stopped" premature interruption. **Question-intent guard**: a 3-tier regex heuristic classifies each user message as a question; on hit a "answer first, don't act" pin segment is injected (survives compression) — fixes long-chat questions being dragged into actions by history (e.g. asking "what is this component" but ending up generating code). Both default on, zero config, prefer-miss-over-false-positive | built-in |
 | 🎨 Subagent model/thinking tiering | `createHtmlSubagent({ llm, thinkingMode })`: code-gen subagents get their own stronger model (main stays light for orchestration) + thinking-depth lock (`'deep'` injects thinking params for quality / `'simple'` strips them to save tokens; top-level `subagent.thinkingMode` as global default). LLMConfig construction path only (pre-built instance → warn + no-op); requires a thinking-capable model (deepseek-thinking / claude); `inspect().subagent.subagents` reflects the effective state | `createHtmlSubagent({ llm, thinkingMode })` |
-| ⚡ host actions (2.20+) | Register save/publish/preview etc; SDK auto-generates named tools, agent triggers page ops directly (no `trigger_action` indirection) | `actions` |
+| ⚡ host actions (2.20+) | Register save/publish/preview etc; SDK auto-generates named tools, agent triggers page ops directly (no `trigger_action` indirection). Semantic flags (4.20+): `readsHostState` (action reads host state → past results become stale placeholders on `notifyHostChange`), `deferredWrite` (proposal-style, effect awaits user confirmation → fact sheet annotates "awaiting confirmation", preventing false "changes complete" claims) | `actions` |
 | 🧩 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` |
 | 🖼 image input | Built-in three entry points (📎 pick / drag / paste screenshot) → compression gate (long edge ≤1568px, ≤4 per round, >20MB rejected); multimodal main model (gpt-4o/claude/qwen-vl table hit, or `llm.vision:true`) → images sent directly as content parts, zero config; text-only main model (deepseek etc.) → `images.describe` captions each image into the user context (image never sent); neither → honest rejection, never silently dropped; `images.upload` swaps the original for an https URL (integrator OSS); persistence keeps only a thumbnail + vfs reference | `images: { upload?, describe? }` + `llm.vision` |
 | 📌 cross-compress working memory (2.20+) | Pin recent read/query paths + hashes across compression; no re-fetch, correct optimistic-lock hash | `capabilities.workingMemory` |
@@ -248,7 +248,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | | `tools` / `skills` / `memory` | `Tool[]` / `SkillSpec[]` / `string` | Custom tools / skills / AGENTS.md-style directives |
 | | `images` | `{upload?,describe?,describeTimeoutMs?}` | **Image input (image-input-vision)**: built-in three entry points (📎 pick / drag / paste) → compression gate (long edge ≤1568px, ≤4 per round, >20MB rejected). Multimodal main model (table hit or `llm.vision:true`) → images sent directly as content parts, zero config; text-only main model → configure `describe` to caption each image into the context (image never sent); neither → honest rejection, never silently dropped; `upload` swaps the original for an https URL (integrator OSS). See [usage-guide §6.17](doc/usage-guide.en.md#617-image-input-multimodal-direct--captioning-bypass) |
 | | `dialog.autoQuote` | `boolean` | **Selection quoting · silent capture (page-quote, default false)**: when true, opening the drawer or clicking the input area lazily captures the host page's current text selection (outside the dialog) into a removable quote chip, sent with the next message as question context. Privacy opt-in; `sdk.setQuote/clearQuote` work regardless of this toggle. See [usage-guide §6.20](doc/usage-guide.en.md#620-text-selection-quoting--page-qa-page-quote--read_page--pagecontext) |
-| | `dialog.selectionMenu` | `boolean` | **Selection floating menu (page-quote explicit confirm, default false)**: selecting text floats a "❝ Quote to chat" toolbar above the selection; click = attach the quote chip + open the dialog + focus the input; dismiss on outside click / scroll / Esc; composable with autoQuote. See [usage-guide §6.20](doc/usage-guide.en.md#620-text-selection-quoting--page-qa-page-quote--read_page--pagecontext) |
+| | `dialog.selectionMenu` | `boolean` | **Selection floating menu (page-quote explicit confirm, default false)**: selecting text floats a "❝ Quote to AI assistant" toolbar above the selection; click = attach the quote chip + open the dialog + focus the input; dismiss on outside click / scroll / Esc; composable with autoQuote. See [usage-guide §6.20](doc/usage-guide.en.md#620-text-selection-quoting--page-qa-page-quote--read_page--pagecontext) |
 | | `capabilities.pageContext` | `boolean` | **Page anchor (default false)**: injects the current page title + URL as a pinned system segment each round (pair with `domInspect`'s read_page for page QA). See [usage-guide §6.20](doc/usage-guide.en.md#620-text-selection-quoting--page-qa-page-quote--read_page--pagecontext) |
 | | `screenshot` | `{renderer?}` | **Screenshot config (take_screenshot)**: assembled when domInspect is on AND (multimodal main model \|\| images.describe); default renderer is html-to-image, pass `renderer` when CSP restricts. See [usage-guide §6.21](doc/usage-guide.en.md#621-screenshot-viewing--page-content-analysis-take_screenshot--page-analysis) |
 | | `capabilities.domEdit` | `boolean` | **DOM editing (default false; requires domInspect)**: assembles `dom_edit` (atomic batch ops on the host page — set_text/set_html/set_attr/add_class/set_style/insert/remove/move/highlight) + `dom_restore` (snapshot rollback, stack of 20). Unique-selector discipline, dangerous-content gate (script / on\* / javascript:), SDK-own-DOM protection; edits are session-ephemeral — data-driven pages should edit data (`write`) instead. See [usage-guide §6.22](doc/usage-guide.en.md#622-dom-editing-dom_edit--dom_restore) |

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-3705%20asserts-brightgreen.svg)](#自测)
+[![tests](https://img.shields.io/badge/self%20tests-3716%20asserts-brightgreen.svg)](#自测)
 
 ---
 
@@ -173,7 +173,7 @@ CDN 零配置：`<script src="https://unpkg.com/page-agent-sdk"></script>` → `
 | 🧭 指令执行力增强 (3.35+) | **完结门禁**:todos 有未完成项却欲纯文本收尾 → 回灌「双出口」反馈续跑(≤2 次),防「拆 3 项做 1 项就收口」的莫名中断;**问句意图守卫**:正则三档启发式逐消息定性问句,命中注入「先答勿做」pin 段(跨压缩存活),防长对话提问被历史拖着误路由成操作(如问「这是啥组件」却去生成代码)。均默认开、零配置、宁漏勿误 | 内置 |
 | 🎨 子 agent 模型/思考分层 | `createHtmlSubagent({ llm, thinkingMode })`:代码生成子 agent 独立强模型(主保持轻量编排)+ 思考深度锁定(`'deep'` 注入思考参数质量优先 / `'simple'` 剥除省 token;顶层 `subagent.thinkingMode` 全局缺省)。仅 LLMConfig 构造路径生效(预构造实例 warn+no-op);需模型支持思考(deepseek thinking 版/claude);`inspect().subagent.subagents` 反射生效状态 | `createHtmlSubagent({ llm, thinkingMode })` |
 | 🖼 图片输入 | 对话框内置三入口(📎 选择/拖拽/粘贴截图)→ 压缩闸(长边 ≤1568px/单轮 ≤4 张/超 20MB 拒);主模型多模态(gpt-4o/claude/qwen-vl 查表,或 `llm.vision:true`)→ 图片直发 content parts 零配置;纯文本主模型(deepseek 等)→ 配 `images.describe` 逐图识图转述注入(图不直发);都不配则诚实拒绝不静默丢图;`images.upload` 原图换 https URL(集成方 OSS);持久化只存缩略图 + vfs 引用 | `images: { upload?, describe? }` + `llm.vision` |
-| ❝ 划词引用 | 用户选中页面文字 → 引用 chip 自动挂上(打开抽屉/点输入框双懒捕获)→ 随下一条消息作为提问上下文;`AgentMessage.quote` 消息级字段(content 干净,气泡结构化引用块,LLM 前缀注入,随消息持久化);`sdk.setQuote/clearQuote` 宿主 API(headless 同享);来源自动推导 = 页面 title + 最近在前标题;排队/快捷指令不消费(与图片同口径);隐私 opt-in 默认关;另有 `dialog.selectionMenu` 显式确认形态(划选浮出「❝ 引用到对话」工具条,点击挂引用并打开对话框) | `dialog.autoQuote` / `dialog.selectionMenu` + `sdk.setQuote` |
+| ❝ 划词引用 | 用户选中页面文字 → 引用 chip 自动挂上(打开抽屉/点输入框双懒捕获)→ 随下一条消息作为提问上下文;`AgentMessage.quote` 消息级字段(content 干净,气泡结构化引用块,LLM 前缀注入,随消息持久化);`sdk.setQuote/clearQuote` 宿主 API(headless 同享);来源自动推导 = 页面 title + 最近在前标题;排队/快捷指令不消费(与图片同口径);隐私 opt-in 默认关;另有 `dialog.selectionMenu` 显式确认形态(划选浮出「❝ 引用到 AI 助手」工具条,点击挂引用并打开对话框) | `dialog.autoQuote` / `dialog.selectionMenu` + `sdk.setQuote` |
 | 📖 页面问答 | `read_page` 读当前页正文纯文本(智能定位 article/main/[role=main]/.content,排除 SDK 自身 DOM 与 script/style,`hasMore` 分页续读,大结果自动外存 vfs);`pageContext` 每轮注入当前页 title+URL 锚点 pin 段(跨压缩;子 agent 不继承) | `capabilities: { domInspect: true, pageContext: true }` |
 | 📸 截图查看 | `take_screenshot` 三模式(selector 局部 / fullPage 整页 / 视口);条件注入(domInspect 开 && vision 主模型 \|\| images.describe,不满足 warn 留痕);分层图通道(vision → 工具结果后合成 user 消息 image parts,免疫 trim/offload;纯文本 → describe 转述);压缩闸 ≤1568 + 原图收 vfs;工具步骤行缩略图观察面;`page-analysis` skill(问题分型/探索纪律/回答纪律) | `capabilities: { domInspect: true }` + `llm.vision` 或 `images.describe` + `screenshot.renderer`(可选) |
 | 🖍 DOM 编辑 | `dom_edit` 批量原子操作(set_text/set_html/set_attr/add_class/set_style/insert/remove/move/highlight)+ `dom_restore` 快照回滚(栈 20 批);唯一 selector 纪律(多匹配拒)/危险闸(script·on*·javascript: 拒)/SDK 自身 DOM 保护/单根快照 256KB 上限;改动为会话临时态,数据驱动页面仍走 write | `capabilities: { domInspect: true, domEdit: true }` |
@@ -247,11 +247,11 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | **页面数据** | `data` | `{schema,bind,description?}` | 单主对象:声明 zod schema(校验 + 字段描述自动注入提示词)+ bind(reactive/普通对象,工具直接读写,不挂 window)+ description |
 | | `tools` / `skills` / `memory` | `Tool[]` / `SkillSpec[]` / `string` | 自定义工具 / 技能 / AGENTS.md 风格持久指令 |
 | **能力开关** | `capabilities` | `{planning?,missionAnchor?,dataOps?,fetch?,skills?,vfs?,summarization?,memory?,workingMemory?,subagent?,verify?,domInspect?,focus?}` | 核心默认开（`verify`/`domInspect` 默认关,opt-in;`focus` 上下文聚焦·指定组件精修,默认开）；`false` 关掉省 token |
-| | `actions` | `Record<string,{description,run,params?}>` | **(2.18+) 宿主动作**：注册 save_draft/publish 等页面操作 → SDK 自动生成命名 tool 供 agent 触发 |
+| | `actions` | `Record<string,{description,run,params?,readsHostState?,deferredWrite?}>` | **(2.18+) 宿主动作**：注册 save_draft/publish 等页面操作 → SDK 自动生成命名 tool 供 agent 触发；**(4.20+) 两语义标记**:`readsHostState`(action 读宿主态 → 旧结果随 `notifyHostChange` 置过期占位)/ `deferredWrite`(提案类,效果待用户确认 → 事实清单注记「待确认」防谎报完成) |
 | | `schemaHint` | `{maxKeys?,maxChars?}` · 默认 `{15,4000}` | **(2.18+) 大 schema 分层披露阈值**：超则 systemPrompt 只注入顶层概览（不带约束/不递归）,深层约束按需 `schema_data` 查;小 schema 无感（全量） |
 | | `images` | `{upload?,describe?,describeTimeoutMs?}` | **图片输入(image-input-vision)**：对话框内置三入口(📎/拖拽/粘贴)→ 压缩闸(长边≤1568/≤4 张/超 20MB 拒)。主模型多模态(查表或 `llm.vision:true`)→ 图片直发 content parts,零配置;纯文本主模型 → 配 `describe` 逐图识图转述注入(图不直发),都不配则诚实拒绝不静默丢图;`upload` 原图换 https URL(集成方 OSS)。见 [usage-guide §6.17](doc/usage-guide.md#617-图片输入多模态直发--识图转述旁路) |
 | | `dialog.autoQuote` | `boolean` | **划词引用·静默捕获(page-quote,默认 false)**:true 时打开抽屉/点输入区瞬间懒捕获宿主页面(对话框外)当前选中文本挂「引用 chip」(可删),随下一条消息发给 LLM。隐私 opt-in;`sdk.setQuote/clearQuote` 不受此开关影响。见 [usage-guide §6.20](doc/usage-guide.md#620-划词引用与页面问答page-quote--read_page--pagecontext) |
-| | `dialog.selectionMenu` | `boolean` | **划词浮动菜单(page-quote 显式确认,默认 false)**:划选文字浮出「❝ 引用到对话」工具条,点击 = 挂引用 chip + 打开对话框 + 聚焦输入;点别处/滚动/Esc 消失;与 autoQuote 独立可组合。见 [usage-guide §6.20](doc/usage-guide.md#620-划词引用与页面问答page-quote--read_page--pagecontext) |
+| | `dialog.selectionMenu` | `boolean` | **划词浮动菜单(page-quote 显式确认,默认 false)**:划选文字浮出「❝ 引用到 AI 助手」工具条,点击 = 挂引用 chip + 打开对话框 + 聚焦输入;点别处/滚动/Esc 消失;与 autoQuote 独立可组合。见 [usage-guide §6.20](doc/usage-guide.md#620-划词引用与页面问答page-quote--read_page--pagecontext) |
 | | `capabilities.pageContext` | `boolean` | **页面锚点(默认 false)**:每轮 system 注入当前页 title+URL(pin 段跨压缩;配合 `domInspect` 的 read_page 读正文答问)。见 [usage-guide §6.20](doc/usage-guide.md#620-划词引用与页面问答page-quote--read_page--pagecontext) |
 | | `screenshot` | `{renderer?}` | **截图配置组(take_screenshot)**:装配条件 = domInspect 开 &&(多模态主模型 \|\| images.describe);默认渲染 html-to-image,CSP 限制时传 `renderer` 自定义。见 [usage-guide §6.21](doc/usage-guide.md#621-截图查看与页面内容分析take_screenshot--page-analysis) |
 | | `capabilities.domEdit` | `boolean` | **DOM 编辑(默认 false;需 domInspect)**:装配 `dom_edit`(宿主页面批量原子操作:set_text/set_html/set_attr/add_class/set_style/insert/remove/move/highlight)+ `dom_restore`(快照回滚,栈 20 批)。唯一 selector 纪律/危险闸(script·on\*·javascript:)//SDK 自身 DOM 保护;改动为会话临时态 —— 数据驱动页面应改数据(`write`)。见 [usage-guide §6.22](doc/usage-guide.md#622-dom-编辑dom_edit--dom_restore) |