page-agent-sdk 3.47.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "3.47.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "AI agent SDK for web pages — embed a chat assistant that edits page data via schema-validated tools. A lighter, framework-agnostic alternative to CopilotKit/LangChain for in-page JSON-editing agents. Vue-bundled; works with DeepSeek, OpenAI, MCP.",
   "main": "./dist/page-agent-sdk.umd.cjs",

package/skills/page-agent-sdk-integrate/SKILL.md

@@ -9,7 +9,7 @@ Help the user embed `page-agent-sdk` so an AI agent safely edits a structured ma
 
 ## Core concept
 
-The SDK is a **standardized JSON-operation agent**: the integrator declares ONE main data object (`data: { schema, bind, description? }`); the agent edits it via `read` / `write` (high-level entry; `write` merges set/edit/delete + auto optimistic lock + auto snapshot), validated by schema, scoped to schema-declared fields (ZodObject top-level keys auto-whitelist), with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text. `bind` is any reactive/plain object — tools read/write it directly, **no `window` dependency**. Advanced mode (`toolMode:'advanced'`) also exposes low-level `get_data`/`set_data`/`edit_data`/`delete_data` for precise control.
+The SDK is a **standardized JSON-operation agent**: the integrator declares ONE main data object (`data: { schema, bind, description? }`); the agent edits it via `read` / `write` (high-level entry; `write` merges set/edit/delete + auto optimistic lock + auto snapshot), validated by schema, scoped to schema-declared fields (ZodObject top-level keys auto-whitelist), with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text. `bind` is any reactive/plain object — tools read/write it directly, **no `window` dependency**.
 
 ## Workflow
 

package/skills/page-agent-sdk-integrate/references/api.md

@@ -96,23 +96,19 @@ By default (`appendReliableWriteRules: true`), the SDK auto-appends `reliableWri
 
 ## Built-in data tools (auto-injected when `capabilities.dataOps`)
 
-Default `toolMode:'simple'` exposes high-level `read`/`write` + advanced query/snapshot tools (low-level `get`/`set`/`edit`/`delete`/`describe` are hidden, merged into `read`/`write`). `toolMode:'advanced'` exposes all; `toolMode:'minimal'` only `read`/`write`.
-
-| Tool | Purpose | Mode |
-|---|---|---|
-| **`read`** / **`write`** (2.2+, recommended) | High-level entry: `read({jsonPath?, fields?, depth?})` lists/reads (supports field projection + depth truncation); `write({value?, patch?, patches?, del?})` merges set/edit/delete + auto optimistic lock + auto snapshot | simple/minimal |
-| `describe_data` | Show main data description + schema field descriptions | advanced |
-| `get_data` | Read main data (supports `jsonPath` precise sub-path read) | advanced |
-| `set_data` | Write whole main data (schema-validated, scoped to declared fields) | advanced |
-| `edit_data` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON | advanced |
-| `delete_data` | Delete a sub-path (jsonPath) | advanced |
-| `snapshot_data` | Manual snapshot | simple/advanced |
-| `list_data_snapshots` | List snapshots | simple/advanced |
-| `restore_data` | Restore (no id = most recent) | simple/advanced |
-| `query_data` / `search_data` | JSONPath query / full-text search | simple/advanced |
-| `eval_script` | Sandboxed script on data (query/transform; transform supports `{patches:[...]}` incremental mode) | simple/advanced |
-
-**Key rule**: `write`/`set`/`edit`/`delete` only affect **schema-declared** fields (ZodObject auto-whitelist; undeclared fields hidden/denied). Sub-path reads are recursively projected by the sub-schema at that location (e.g. `read components.0` hides child undeclared fields). `jsonPath` is segment-by-segment validated against schema. Invalid schema → structured error, no write. `write`/`edit` writes in-place (preserves Vue reactive refs). `write` auto-tracks hash from `read` for optimistic lock (no manual `expectedHash` needed). Whole-set / `set_data` / `eval` transform become **merge** semantics in whitelist mode (only updates declared fields, undeclared fields preserved — prevents accidental deletion); `interceptors.write`-supplied invisible fields (not in schema) are written back to bind after schema+merge (not stripped).
+High-level `read`/`write` are the main entry points; query/snapshot/eval tools are always available (no mode switch). Low-level CRUD `get_data`/`set_data`/`edit_data`/`delete_data` was **removed in 4.0** — `read`/`write` cover everything (`get_data({p})`→`read({jsonPath:p})`, `set_data({value})`→`write({value})`, `edit_data({op,p,value})`→`write({patch:{op,jsonPath:p,value}})`, `delete_data({p})`→`write({patch:{jsonPath:p},del:true})`).
+
+| Tool | Purpose |
+|---|---|
+| **`read`** / **`write`** (recommended) | High-level entry: `read({jsonPath?, jsonPaths?, fields?, depth?, offset?, limit?})` lists/reads (field projection + depth truncation + array paging); `write({value?, patch?, patches?, del?, dryRun?})` merges set/edit/delete + auto optimistic lock + auto snapshot |
+| `describe_data` | Show main data description + format hints |
+| `schema_data` / `diff_data` | Inspect schema constraints at a path / diff snapshots or JSON |
+| `restore_data` / `history_data` | Restore snapshot (no id = most recent) / list & read snapshots |
+| `query_data` / `search_data` | JSONPath query / full-text search |
+| `eval_script` | Sandboxed script on data (query/transform; transform supports `{patches:[...]}` incremental mode) |
+| `draft_write` / `draft_commit` | Opt-in (`capabilities.draftWrite`) chunked build for very large JSON + atomic commit |
+
+**Key rule**: `write` (all four intents) only affects **schema-declared** fields (ZodObject auto-whitelist; undeclared fields hidden/denied). Sub-path reads are recursively projected by the sub-schema at that location (e.g. `read components.0` hides child undeclared fields). `jsonPath` is segment-by-segment validated against schema. Invalid schema → structured error, no write. `write` writes in-place (preserves Vue reactive refs). `write` auto-tracks hash from `read` for optimistic lock (no manual `expectedHash` needed). Whole-set / `eval` transform become **merge** semantics in whitelist mode (only updates declared fields, undeclared fields preserved — prevents accidental deletion); `interceptors.write`-supplied invisible fields (not in schema) are written back to bind after schema+merge (not stripped).
 
 ### write / jsonPath edit operations
 

package/types/headless.d.ts

@@ -583,6 +583,8 @@ export type SkillToolFactory = () => any | any[] | Promise<any | any[]>;
 export interface VerifyCheckContext {
   messages: any[];
   state: any;
+  /** 结构化日志(debugLogs;render-check 类环境降级留痕用,可缺省) */
+  log?: (type: string, data: unknown) => void;
 }
 export interface VerifyCheckResult {
   ok: boolean;
@@ -1140,7 +1142,7 @@ export declare function defineTool(opts: {
   writeCapable?: boolean | ((args: Record<string, unknown>) => boolean);
 }): any;
 export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
-/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。set_data / write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
+/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
 export declare function commitSetToBind(args: { bindRef: unknown; value: unknown; schema: any; allowKeys: string[] | null; snapshots: any[]; maxSnapshots: number; audit: (e: any) => void; dryRun?: boolean; op?: 'set' | 'draft_commit'; snapshotLabel?: string }): { ok: true; hash: string; data: unknown; notices: string[] } | { ok: false; error: string };
 export interface LocalWriteBack {
   op: 'set' | 'remove' | 'move' | 'mergeKeys' | 'appendElems';
@@ -1455,7 +1457,7 @@ export interface JpNode {
   path: string;
   /** 匹配元素值 */
   value: unknown;
-  /** 父为数组时的索引(便于后续 edit_data_slot 的 jsonPath 定位) */
+  /** 父为数组时的索引(便于后续 write patch 的 jsonPath 定位) */
   index?: number;
 }
 export interface SearchHit {
@@ -1640,6 +1642,76 @@ export interface HtmlFormatCheckOptions {
 }
 /** HTML 格式 verify check(beforeReturn 门禁):扫 state.files 代码文件,不通过回灌 feedback 自纠 */
 export declare function createHtmlFormatCheck(opts?: HtmlFormatCheckOptions): VerifyCheck;
+/** 沙箱采集到的原始渲染信号(console.error / js-error / unhandledrejection / 资源失败 / CSP 违规 / console.warn) */
+export interface RenderSignal {
+    type: 'console-error' | 'console-warn' | 'js-error' | 'unhandledrejection' | 'resource-error' | 'csp-violation';
+    message: string;
+    source?: string;
+    lineno?: number;
+}
+/** 渲染指标(收集窗结束时采集;白屏判定口径 = 内容级:body 子节点数 / scrollHeight / 图片数) */
+export interface RenderMetrics {
+    bodyChildren: number;
+    scrollHeight: number;
+    imgCount: number;
+}
+/** 单组件沙箱渲染的原始结果(未归一;noDom = node/无 DOM 环境标记) */
+export interface RawRenderResult {
+    handshake: boolean;
+    signals: RenderSignal[];
+    metrics?: RenderMetrics;
+    timedOut?: boolean;
+    noDom?: boolean;
+}
+/** 归一后的单组件判定:pass / fail(带 problems)/ unavailable(握手缺失或超时,不算通过防假绿) */
+export interface RenderVerdict {
+    verdict: 'pass' | 'fail' | 'unavailable';
+    problems: string[];
+    warnings: string[];
+    metrics?: RenderMetrics;
+    reason?: 'handshake-missing' | 'timeout';
+}
+/** 渲染自检 VerifyCheck 工厂选项(runner 注入供测试桩用) */
+export interface HtmlRenderCheckOptions {
+    vfsPrefix?: string;
+    codeField?: string;
+    writablePaths?: string[];
+    runner?: (html: string) => Promise<RawRenderResult>;
+    maxTargets?: number;
+}
+/** 渲染自检对象:check 组合进 createHtmlSubagent 的 formatCheck 链;两个注入槽由装配期回填 */
+export interface HtmlRenderCheck {
+    check: VerifyCheck;
+    setGetController: (g: () => {
+        get?: () => { bind?: unknown } | null | undefined;
+    } | null | undefined) => void;
+    setWritablePaths: (paths: string[]) => void;
+}
+/** 沙箱运行参数(活动静默窗/硬上限/指标应答宽限;默认 900ms / 4000ms / 500ms) */
+export interface SandboxRunOptions {
+    silenceMs?: number;
+    hardCapMs?: number;
+    metricsGraceMs?: number;
+}
+/**
+ * 渲染级自检(render-check):本轮触达的 code 资产放沙箱 iframe(srcdoc + sandbox="allow-scripts")独立渲染,
+ * 采集 console.error / window.onerror / unhandledrejection / 资源失败 / 白屏指标 → 归一回灌自纠。
+ * 仅门禁形态(组合进 createHtmlSubagent 的 formatCheck 链);node/无 DOM 自动跳过渲染段保留结构段;
+ * 握手缺失(宿主 CSP 拦沙箱内联脚本)/ 超时 → unavailable 不算通过(零信号 ≠ 通过)。
+ */
+export declare function createHtmlRenderCheck(opts?: HtmlRenderCheckOptions): HtmlRenderCheck;
+/** 组合「结构 → 渲染」为单一 VerifyCheck(结构不过短路渲染;runBeforeReturn 不短路,两段必须单 check 内早返回) */
+export declare function composeStructureThenRender(structure: VerifyCheck, render: VerifyCheck): VerifyCheck;
+/** 信号归一纯函数:storage 类 SecurityError 降 warn(沙箱假阳性);无失败信号但 body 空 + scrollHeight<10 → 疑似白屏 fail */
+export declare function normalizeRenderResult(raw: RawRenderResult): RenderVerdict;
+/** 单组件沙箱渲染(离屏 iframe;用后销毁;node/无 DOM 返回 noDom) */
+export declare function renderInSandbox(html: string, opts?: SandboxRunOptions): Promise<RawRenderResult>;
+/** 沙箱 srcdoc 构造(collector 注入文档最前,不改组件原文) */
+export declare function buildSandboxSrcdoc(html: string, nonce: string): string;
+/** collector 采集脚本源码(nonce 握手 + 信号上报 + 活动信号 + 指标应答) */
+export declare function buildCollectorJs(nonce: string): string;
+/** 累计/销毁的沙箱 iframe 数(测试观察「用后销毁」契约) */
+export declare function getSandboxLifecycle(): { created: number; destroyed: number };
 
 // checkpoint / dataOps / permissions
 export interface CheckpointDeps { [k: string]: any }

package/types/index.d.ts

@@ -950,6 +950,8 @@ export type SkillToolFactory = () => any | any[] | Promise<any | any[]>;
 export interface VerifyCheckContext {
   messages: any[];
   state: any;
+  /** 结构化日志(debugLogs;render-check 类环境降级留痕用,可缺省) */
+  log?: (type: string, data: unknown) => void;
 }
 export interface VerifyCheckResult {
   ok: boolean;
@@ -1569,7 +1571,7 @@ export declare function defineTool(opts: {
   writeCapable?: boolean | ((args: Record<string, unknown>) => boolean);
 }): any;
 export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
-/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。set_data / write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
+/** 整体 set 写入纯函数:schema 校验 + 快照 + merge/替换 + audit。write(set) / draft_commit 共用。返回 {ok,hash,data} 或 {ok:false,error} */
 export declare function commitSetToBind(args: { bindRef: unknown; value: unknown; schema: any; allowKeys: string[] | null; snapshots: any[]; maxSnapshots: number; audit: (e: any) => void; dryRun?: boolean; op?: 'set' | 'draft_commit'; snapshotLabel?: string }): { ok: true; hash: string; data: unknown; notices: string[] } | { ok: false; error: string };
 /** path-scoped-validation:增量 patch 逐目标局部校验(全部 apply 后按最终态;兄弟脏数据不株连)。返回写回计划 */
 export interface LocalWriteBack {
@@ -1590,7 +1592,7 @@ export interface LocalValidationPlan {
 export declare function validateRootValueLocally(args: { schema: any; allowKeys: string[] | null; value: unknown; bindRef: unknown }): { ok: true; assembly: unknown; wholeParsed: Record<string, unknown> | null; notices: string[] } | { ok: false; error: string; notices: string[] };
 /** 增量 patch 逐目标局部校验纯函数(appendCaptures/moveCaptures 由 apply 循环捕获;valueAt 为位移兜底) */
 export declare function validateWriteLocally(args: { schema: any; bindRef: unknown; clone: unknown; patches: { op?: string; jsonPath?: string; value?: unknown }[]; schemaErrorMode?: 'zod' | 'schema_invalid'; appendCaptures: { jp: string; elems: unknown[] }[]; moveCaptures: { jp: string; toPath: string; elem: unknown }[]; valueAt?: (jp: string) => unknown }): LocalValidationPlan;
-/** 增量 patch 写入纯函数(clone + 局部校验 + 快照 + 外科手术式写回);edit_data / write(edit) / eval 共用 */
+/** 增量 patch 写入纯函数(clone + 局部校验 + 快照 + 外科手术式写回);write(edit) / eval 共用 */
 export declare function applyPatchesToBind(args: { bindRef: unknown; patches: { op?: string; jsonPath?: string; value?: unknown }[]; schema: any; allowKeys: string[] | null; snapshots: any[]; maxSnapshots: number; markDataDirty?: () => void; schemaErrorMode?: 'zod' | 'schema_invalid'; snapshotLabel?: string; dryRun?: boolean; internalAfterWrite?: (bind: any, before: any) => void; protectedCtx?: unknown }): { ok: true; applied: { op: string; jp: string; value: unknown }[]; clone: unknown; notices: string[] } | { ok: false; error: string };
 /** 结构化追踪 span(revive-observability-tracing Phase 3) */
 export type SpanType = 'round' | 'model' | 'tool' | 'compression';
@@ -1934,7 +1936,7 @@ export interface JpNode {
   path: string;
   /** 匹配元素值 */
   value: unknown;
-  /** 父为数组时的索引(便于后续 edit_data_slot 的 jsonPath 定位) */
+  /** 父为数组时的索引(便于后续 write patch 的 jsonPath 定位) */
   index?: number;
 }
 export interface SearchHit {
@@ -2126,6 +2128,76 @@ export interface HtmlFormatCheckOptions {
 }
 /** HTML 格式 verify check(beforeReturn 门禁):扫 state.files 代码文件,不通过回灌 feedback 自纠 */
 export declare function createHtmlFormatCheck(opts?: HtmlFormatCheckOptions): VerifyCheck;
+/** 沙箱采集到的原始渲染信号(console.error / js-error / unhandledrejection / 资源失败 / CSP 违规 / console.warn) */
+export interface RenderSignal {
+    type: 'console-error' | 'console-warn' | 'js-error' | 'unhandledrejection' | 'resource-error' | 'csp-violation';
+    message: string;
+    source?: string;
+    lineno?: number;
+}
+/** 渲染指标(收集窗结束时采集;白屏判定口径 = 内容级:body 子节点数 / scrollHeight / 图片数) */
+export interface RenderMetrics {
+    bodyChildren: number;
+    scrollHeight: number;
+    imgCount: number;
+}
+/** 单组件沙箱渲染的原始结果(未归一;noDom = node/无 DOM 环境标记) */
+export interface RawRenderResult {
+    handshake: boolean;
+    signals: RenderSignal[];
+    metrics?: RenderMetrics;
+    timedOut?: boolean;
+    noDom?: boolean;
+}
+/** 归一后的单组件判定:pass / fail(带 problems)/ unavailable(握手缺失或超时,不算通过防假绿) */
+export interface RenderVerdict {
+    verdict: 'pass' | 'fail' | 'unavailable';
+    problems: string[];
+    warnings: string[];
+    metrics?: RenderMetrics;
+    reason?: 'handshake-missing' | 'timeout';
+}
+/** 渲染自检 VerifyCheck 工厂选项(runner 注入供测试桩用) */
+export interface HtmlRenderCheckOptions {
+    vfsPrefix?: string;
+    codeField?: string;
+    writablePaths?: string[];
+    runner?: (html: string) => Promise<RawRenderResult>;
+    maxTargets?: number;
+}
+/** 渲染自检对象:check 组合进 createHtmlSubagent 的 formatCheck 链;两个注入槽由装配期回填 */
+export interface HtmlRenderCheck {
+    check: VerifyCheck;
+    setGetController: (g: () => {
+        get?: () => { bind?: unknown } | null | undefined;
+    } | null | undefined) => void;
+    setWritablePaths: (paths: string[]) => void;
+}
+/** 沙箱运行参数(活动静默窗/硬上限/指标应答宽限;默认 900ms / 4000ms / 500ms) */
+export interface SandboxRunOptions {
+    silenceMs?: number;
+    hardCapMs?: number;
+    metricsGraceMs?: number;
+}
+/**
+ * 渲染级自检(render-check):本轮触达的 code 资产放沙箱 iframe(srcdoc + sandbox="allow-scripts")独立渲染,
+ * 采集 console.error / window.onerror / unhandledrejection / 资源失败 / 白屏指标 → 归一回灌自纠。
+ * 仅门禁形态(组合进 createHtmlSubagent 的 formatCheck 链);node/无 DOM 自动跳过渲染段保留结构段;
+ * 握手缺失(宿主 CSP 拦沙箱内联脚本)/ 超时 → unavailable 不算通过(零信号 ≠ 通过)。
+ */
+export declare function createHtmlRenderCheck(opts?: HtmlRenderCheckOptions): HtmlRenderCheck;
+/** 组合「结构 → 渲染」为单一 VerifyCheck(结构不过短路渲染;runBeforeReturn 不短路,两段必须单 check 内早返回) */
+export declare function composeStructureThenRender(structure: VerifyCheck, render: VerifyCheck): VerifyCheck;
+/** 信号归一纯函数:storage 类 SecurityError 降 warn(沙箱假阳性);无失败信号但 body 空 + scrollHeight<10 → 疑似白屏 fail */
+export declare function normalizeRenderResult(raw: RawRenderResult): RenderVerdict;
+/** 单组件沙箱渲染(离屏 iframe;用后销毁;node/无 DOM 返回 noDom) */
+export declare function renderInSandbox(html: string, opts?: SandboxRunOptions): Promise<RawRenderResult>;
+/** 沙箱 srcdoc 构造(collector 注入文档最前,不改组件原文) */
+export declare function buildSandboxSrcdoc(html: string, nonce: string): string;
+/** collector 采集脚本源码(nonce 握手 + 信号上报 + 活动信号 + 指标应答) */
+export declare function buildCollectorJs(nonce: string): string;
+/** 累计创建/销毁的沙箱 iframe 数(测试观察「用后销毁」契约) */
+export declare function getSandboxLifecycle(): { created: number; destroyed: number };
 /** 内置完整 HTML 生成规范 skill 构造器(示例路径按 root/codeField 参数化,集成方字段命名各异勿写死;默认快照 root='components'/codeField='code') */
 export declare function buildHtmlFragmentSkill(root?: string, codeField?: string): SkillSpec;
 /** 内置完整 HTML 生成规范 skill(createHtmlSubagent 默认装;传自定义 skills 覆盖默认时,显式并回此 skill 保住生成规范/安全底线;默认快照 root='components'/codeField='code') */