page-agent-sdk 2.4.1 → 2.5.1

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

@@ -5,30 +5,33 @@ From the smallest working setup to a full-featured integration. Read top-down; s
 ## Stage 0 — Prerequisites
 
 - An OpenAI-compatible LLM endpoint (DeepSeek works out of the box). Get an API key.
-- Page data you want the AI to edit, placed on `window` (e.g. `window.app = { ... }`).
+- A main data object you want the AI to edit (any plain or reactive object).
 
 ## Stage 1 — Minimal (5 lines, CDN, no build)
 
-Drop into any HTML page. The built-in dialog mounts itself. (`systemPrompt` is optional — a built-in default is used if omitted: a generic page-operation assistant + `systemPromptHelpers.reliableWriteRules`. Shown here explicitly for clarity.)
+Drop into any HTML page. The built-in dialog mounts itself. (`systemPrompt` is optional — a built-in default is used if omitted: a generic JSON-operation assistant + `systemPromptHelpers.reliableWriteRules`. Shown here explicitly for clarity.)
 
 ```html
 <div id="root"></div>
 <script src="https://unpkg.com/page-agent-sdk"></script>
 <script>
-  window.app = { title: 'Hello', theme: 'light' }
+  const app = { title: 'Hello', theme: 'light' }   // plain object (no window needed)
   ChatSdk.createChatSdk({
     container: '#root',
     llm: { apiKey: 'sk-...', baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
-    systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
-    dataSlots: [
-      { path: 'app.title', description: '标题', schema: ChatSdk.z.string() },
-      { path: 'app.theme', description: '主题', schema: ChatSdk.z.enum(['light','dark']) },
-    ],
+    systemPrompt: 'You are a JSON operation assistant. Read/write the main data via tools.',
+    data: {
+      schema: ChatSdk.z.object({
+        title: ChatSdk.z.string().describe('标题'),
+        theme: ChatSdk.z.enum(['light', 'dark']).describe('主题'),
+      }),
+      bind: app,
+    },
   }).mount()
 </script>
 ```
 
-Talk to it: "change theme to dark" → AI calls `write({ path:'app.theme', value:'dark' })` → `window.app.theme === 'dark'`.
+Talk to it: "change theme to dark" → AI calls `write({ value: 'dark', patch: { op: 'set', jsonPath: 'theme' } })` → `app.theme === 'dark'`.
 
 ## Stage 2 — npm + module project
 
@@ -40,17 +43,20 @@ npm i page-agent-sdk zod @langchain/openai @langchain/core
 import { createChatSdk, z } from 'page-agent-sdk'
 import 'page-agent-sdk/style.css'
 
-window.app = { title: 'Hello', theme: 'light', items: [] }
+const app = { title: 'Hello', theme: 'light', items: [] }
 
 const sdk = createChatSdk({
   container: '#root',
   llm: { apiKey: import.meta.env.VITE_AI_API_KEY, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
-  systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
-  dataSlots: [
-    { path: 'app.title',  description: '标题',   schema: z.string() },
-    { path: 'app.theme',  description: '主题',   schema: z.enum(['light','dark']) },
-    { path: 'app.items',  description: '列表项', schema: z.array(z.object({ name: z.string(), price: z.number() })) },
-  ],
+  systemPrompt: 'You are a JSON operation assistant. Read/write the main data via tools.',
+  data: {
+    schema: z.object({
+      title: z.string().describe('标题'),
+      theme: z.enum(['light', 'dark']).describe('主题'),
+      items: z.array(z.object({ name: z.string(), price: z.number() })).describe('列表项'),
+    }),
+    bind: app,
+  },
 }).mount()
 ```
 
@@ -61,10 +67,10 @@ Subscribe via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, ca
 ```ts
 const sdk = createChatSdk({
   onEvent(e) {
-    if (e.type === 'data_slot_change') renderUI()       // host page reactive refresh
+    if (e.type === 'data_change') renderUI()       // host page refresh (plain-object bind needs this; reactive bind auto-refreshes)
     if (e.type === 'error') console.error(e.message)
   },
-  // ...llm, dataSlots...
+  // ...llm, data...
 }).mount()
 
 // runtime listener (e.g. analytics), cancellable
@@ -72,6 +78,8 @@ const off = sdk.hook((e) => { if (e.type === 'tool_call') track(e.name) })
 // off()
 ```
 
+> For Vue + `reactive()` bind, template/watch auto-refresh on write — no manual notify needed. For plain-object bind (React/vanilla/Node), subscribe `data_change` to re-render. Both can coexist (reactive for UI, `onEvent` for audit).
+
 ## Stage 4 — Headless (custom UI, framework-agnostic)
 
 No built-in dialog; drive the reactive `messages` array yourself.
@@ -79,7 +87,7 @@ No built-in dialog; drive the reactive `messages` array yourself.
 ```ts
 const sdk = createChatSdk({
   ui: false,                                  // headless
-  llm: { ... }, systemPrompt: '...', dataSlots: [...],
+  llm: { ... }, systemPrompt: '...', data: { schema, bind: appObj },
 }).mount()
 
 // your own UI reads sdk.messages (reactive) and calls sdk.send
@@ -92,10 +100,10 @@ Reusable `ChatDialog` / `MessageContent` / `CodePreview` components + `useChat`
 
 ```ts
 createChatSdk({
-  // ...llm, dataSlots...
+  // ...llm, data...
   capabilities: { verify: true },             // write-back self-check before agent returns
   verify: { maxAttempts: 2 },                 // auto-correct on failure (default check = write-back read + schema)
-  approval: { tools: ['write'] },                // human-confirm before writes
+  approval: { tools: ['write'] },             // human-confirm before writes
   checkpoint: true,                           // session-level rollback on bad edits
   maxParallelTools: 1,                        // serial tool calls (safe for stateful middleware)
   contextPreset: 'conservative',              // save cost on long sessions
@@ -107,43 +115,35 @@ createChatSdk({
 ```ts
 createChatSdk({
   id: 'my-page-agent',          // STABLE id (multi-agent isolation); omit = random + warn
-  storage: 'indexed',           // persist messages/vfs/todos/memory to IndexedDB
-  // ...llm, dataSlots...
+  storage: 'indexed',           // persist messages/vfs/todos/memory to IndexedDB (NOT bind — store & re-inject via sdk.setData)
+  // ...llm, data...
 }).mount()
 
 // later, switch session:
 await sdk.switchSession('session-abc')   // load or create
 ```
 
-## Stage 7 — Dynamic dataSlots (lazy-loaded components)
+## Stage 7 — Swap data at runtime (dynamic / lazy-loaded schema)
 
-Components loaded on demand with **different schemas each** — register at mount, unregister at unmount. No need to pre-declare every possible component at `createChatSdk`. The agent picks up new registrations immediately (no rebuild); `summarization` also embeds a live registry snapshot in compressed summaries so the agent won't act on stale memory.
+When the page schema changes dynamically (e.g. lazy-loaded components with different structures), swap the whole main data config at runtime — tools pick up the new bind/schema immediately, no rebuild.
 
 ```ts
 const sdk = createChatSdk({
   container: '#root', llm: { ... },
-  // only the static container is pre-declared; per-component paths are dynamic
-  dataSlots: [{ path: 'app.components', description: '动态组件容器(按 id 存)', schema: z.record(z.string(), z.any()) }],
+  data: { schema: initialSchema, bind: initialObj, description: '初始数据' },
 }).mount()
 
-// component mounts (lazy) → register its schema, immediately operative
-function mountComp(comp: { id: string; type: 'banner' | 'card' | 'stat' | 'chart' }) {
-  window.app.components[comp.id] = reactive(comp)
-  sdk.addDataSlot({
-    path: `app.components.${comp.id}`,
-    description: `${typeDescriptions[comp.type]}`,  // ← give the LLM field-level detail (it can't see the zod schema)
-    schema: compSchemas[comp.type],                 // ← validation guardrail
-  })
-}
-// component unmounts → unregister (snapshot stack cleaned too)
-function unmountComp(id: string) {
-  delete window.app.components[id]
-  sdk.removeDataSlot(`app.components.${id}`)
-}
-sdk.listDataSlots()  // live registry (reflects dynamic add/remove)
+// later: swap to a different schema + bind (lazy-loaded / dynamic)
+sdk.setData({
+  schema: newSchema,        // new zod schema (validation + field hints auto-injected)
+  bind: newObj,             // new reactive/plain object
+  description: '新数据',
+})
+// tools now operate on newObj with newSchema — immediately, no rebuild
+sdk.getData()  // read current config
 ```
 
-> Key points: `description` is the LLM's only source of field structure (write it in detail); `schema` is the validation guardrail (the LLM never sees it). Write operations return the current operable path list; long-session compression keeps a live registry snapshot + preserved `describe`/`list` results so the agent never loses track of dynamic components.
+> `summarization` auto-embeds the current data description in compressed summaries, so the agent won't act on stale memory after a swap. Snapshots & optimistic-lock hash reset on swap (old snapshots cleared).
 
 **Full runnable demo**: `examples/dynamic-demo/` (`npm run dev` → `/examples/dynamic-demo/`).
 

package/skills/page-agent-sdk-integrate/references/use-cases.md

@@ -1,13 +1,13 @@
 # Use cases — end-to-end scenarios
 
-Concrete integration patterns for common scenarios. Each shows the key `dataSlots` + options that matter. Adapt the LLM config to your provider.
+Concrete integration patterns for common scenarios. Each shows the key `data` + options that matter. Adapt the LLM config to your provider.
 
 ## 1. Low-code page builder
 
 A visual builder where the page is a component tree; the AI edits the tree via jsonPath patches and the canvas re-renders live.
 
 ```ts
-window.page = {
+const page = {
   components: [
     { id: 'banner', type: 'banner', props: { title: 'Welcome', bg: '#1f4d3a' } },
     { id: 'card1', type: 'card', props: { title: '新品', price: 99 } },
@@ -18,16 +18,18 @@ createChatSdk({
   container: '#chat',
   llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat', temperature: 0.3 },
   systemPrompt: '你是页面搭建助手。用 write 的 patch 按 jsonPath 增量改 components,不要重传整树。',
-  dataSlots: [
-    { path: 'page.components', description: '组件树',
-      schema: z.array(z.object({
+  data: {
+    schema: z.object({
+      components: z.array(z.object({
         id: z.string(), type: z.string(),
         props: z.record(z.any()),
-      })) },
-  ],
-  onEvent(e) { if (e.type === 'data_slot_change') renderCanvas() },  // canvas reactive refresh
+      })).describe('组件树'),
+    }),
+    bind: page,
+  },
+  onEvent(e) { if (e.type === 'data_change') renderCanvas() },  // canvas refresh (plain-object bind)
   checkpoint: true,                       // bad edit → one-click rollback
-  approval: { tools: ['write'] },  // confirm writes
+  approval: { tools: ['write'] },        // confirm writes
 }).mount()
 ```
 
@@ -38,7 +40,7 @@ User: "顶部 Banner 改深色、主标题加粗、加一张新品卡" → AI ca
 Form schema as data; AI edits field definitions, schema validation prevents malformed forms.
 
 ```ts
-window.form = {
+const form = {
   fields: [
     { name: 'phone', label: '手机号', type: 'text', required: true, validation: 'none' },
     { name: 'address', label: '地址', type: 'text', required: false, cascade: false },
@@ -47,29 +49,31 @@ window.form = {
 
 createChatSdk({
   container: '#chat', llm: { ... },
-  systemPrompt: '你是表单设计助手。改 form.fields 的字段定义,保持 schema 合法。',
-  dataSlots: [
-    { path: 'form.fields', description: '字段定义数组',
-      schema: z.array(z.object({
+  systemPrompt: '你是表单设计助手。改 fields 的字段定义,保持 schema 合法。',
+  data: {
+    schema: z.object({
+      fields: z.array(z.object({
         name: z.string(), label: z.string(),
         type: z.enum(['text','number','select','date']),
         required: z.boolean(),
         validation: z.enum(['none','phone','email','idcard']),
         cascade: z.boolean().optional(),
-      })) },
-  ],
-  onEvent(e) { if (e.type === 'data_slot_change') renderForm() },
+      })).describe('字段定义数组'),
+    }),
+    bind: form,
+  },
+  onEvent(e) { if (e.type === 'data_change') renderForm() },
 }).mount()
 ```
 
-User: "手机号加格式校验、地址改三级联动" → AI patches `form.fields[0].validation='phone'`, `form.fields[1].cascade=true`.
+User: "手机号加格式校验、地址改三级联动" → AI patches `fields.0.validation='phone'`, `fields.1.cascade=true`.
 
 ## 3. CMS batch operation
 
-Bulk-edit a product list; use `eval_script` or `search_data_slot` + `write` with `patch` for batch ops.
+Bulk-edit a product list; use `eval_script` or `search_data` + `write` with `patch` for batch ops.
 
 ```ts
-window.products = [
+const products = [
   { id: 1, title: '商品A', price: 99, highlight: false },
   { id: 2, title: '商品B', price: 150, highlight: false },
   // ...hundreds
@@ -77,25 +81,27 @@ window.products = [
 
 createChatSdk({
   container: '#chat', llm: { ... },
-  systemPrompt: '你是运营助手。批量改 products;标题加前缀用 eval_script,按条件筛选用 search_data_slot。',
-  dataSlots: [
-    { path: 'products', description: '商品列表',
-      schema: z.array(z.object({
+  systemPrompt: '你是运营助手。批量改 products;标题加前缀用 eval_script,按条件筛选用 search_data。',
+  data: {
+    schema: z.object({
+      products: z.array(z.object({
         id: z.number(), title: z.string(), price: z.number(), highlight: z.boolean(),
-      })) },
-  ],
-  onEvent(e) { if (e.type === 'data_slot_change') renderTable() },
+      })).describe('商品列表'),
+    }),
+    bind: { products },
+  },
+  onEvent(e) { if (e.type === 'data_change') renderTable() },
 }).mount()
 ```
 
-User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_script` for the prefix loop + `search_data_slot` to find `<100` then `write` with `patch` to set `highlight`.
+User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_script` for the prefix loop + `search_data` to find `<100` then `write` with `patch` to set `highlight`.
 
 ## 4. Ops config console
 
 Edit experiment thresholds / feature flags with human confirmation.
 
 ```ts
-window.config = {
+const config = {
   expA: { threshold: 0.5, enabled: true },
   featureB: { enabled: false },
 }
@@ -103,12 +109,13 @@ window.config = {
 createChatSdk({
   container: '#chat', llm: { ... },
   systemPrompt: '你是运维助手。改 config 前必须经用户确认。',
-  dataSlots: [
-    { path: 'config.expA', description: '实验A',
-      schema: z.object({ threshold: z.number().min(0).max(1), enabled: z.boolean() }) },
-    { path: 'config.featureB', description: 'B开关',
-      schema: z.object({ enabled: z.boolean() }) },
-  ],
+  data: {
+    schema: z.object({
+      expA: z.object({ threshold: z.number().min(0).max(1), enabled: z.boolean() }).describe('实验A'),
+      featureB: z.object({ enabled: z.boolean() }).describe('B开关'),
+    }),
+    bind: config,
+  },
   approval: { tools: ['write'] },  // human-in-the-loop
   checkpoint: true,
   capabilities: { verify: true },           // write-back read + schema check
@@ -119,7 +126,7 @@ User: "A 实验阈值调到 30%、关掉 B 开关" → AI proposes writes → us
 
 ## 5. AI-native assistant (no page data, custom tools)
 
-The agent drives your product's own API via custom tools (no dataSlotOps).
+The agent drives your product's own API via custom tools (no dataOps).
 
 ```ts
 const lookupTool = defineTool({
@@ -134,7 +141,7 @@ createChatSdk({
   llm: { ... },
   systemPrompt: '你是订单助手。用 lookup_order 查询。',
   tools: [lookupTool],
-  capabilities: { dataSlotOps: false, fetch: false },   // pure custom-tool agent
+  capabilities: { dataOps: false, fetch: false },   // pure custom-tool agent
 }).mount()
 ```
 
@@ -146,15 +153,15 @@ Pure research: fetch docs, parallel subagents for multi-source investigation.
 createChatSdk({
   container: '#chat', llm: { ... },
   systemPrompt: '你是调研助手。多源对比用 spawn_agents 并行委派。',
-  capabilities: { dataSlotOps: false },       // read-only, no page edits
+  capabilities: { dataOps: false },       // read-only, no data edits
   subagent: { allowedTools: ['fetch_document'] },
-  contextPreset: 'conservative',             // long research sessions
+  contextPreset: 'conservative',         // long research sessions
 }).mount()
 ```
 
 ## 7. Headless server-side (Node.js)
 
-Run the agent in Node (no browser). Provide `globalThis.window` only if you enable dataSlotOps.
+Run the agent in Node (no browser). dataOps body works in Node with any `bind` object; only `eval_script` needs Web Worker (disable via `capabilities:{dataOps:false}` if unused).
 
 ```ts
 // node mjs
@@ -165,7 +172,8 @@ const sdk = createChatSdk({
   storage: 'memory',
   llm: { apiKey, baseUrl, model },
   systemPrompt: '...',
-  capabilities: { dataSlotOps: false, fetch: false },
+  data: { schema: z.object({ result: z.string() }), bind: { result: '' } },
+  capabilities: { fetch: false },         // dataOps body works; eval_script needs worker
   tools: [/* your tools */],
 })
 await sdk.mount()
@@ -179,9 +187,9 @@ sdk.unmount()
 Two dialogs backed by one agent brain.
 
 ```ts
-const a = createChatSdk({ id: 'shared', container: '#dlg-a', llm: {...}, shareContext: true, dataSlots }).mount()
-const b = createChatSdk({ id: 'shared', container: '#dlg-b', llm: {...}, shareContext: true, dataSlots }).mount()
-// a & b share messages/agent/vfs/todos/memory — two views of one agent
+const a = createChatSdk({ id: 'shared', container: '#dlg-a', llm: {...}, shareContext: true, data }).mount()
+const b = createChatSdk({ id: 'shared', container: '#dlg-b', llm: {...}, shareContext: true, data }).mount()
+// a & b share messages/agent/vfs/todos/memory/bind — two views of one agent
 ```
 
 ## 9. MCP integration (external tool servers)
@@ -199,33 +207,29 @@ createChatSdk({
 
 > Note: `@modelcontextprotocol/sdk` is an optional peerDep — install it only if you use `mcp`. Browser supports only remote transports (http/sse/websocket), not stdio.
 
-## 10. Lazy-loaded components with dynamic schemas (dynamic dataSlots)
+## 10. Dynamic / lazy-loaded schema (swap main data at runtime)
 
-Components loaded on demand with **different structures each** — register their schema at mount time, unregister at unmount. No need to pre-declare every possible component at `createChatSdk`.
+When the page schema changes dynamically (lazy-loaded components with different structures), swap the whole main data config at runtime — tools pick up the new bind/schema immediately, no rebuild.
 
 ```ts
 const sdk = createChatSdk({
   container: '#chat', llm: { ... },
-  // only the static container is pre-declared; per-component paths are dynamic
-  dataSlots: [{ path: 'app.components', description: '动态组件容器', schema: z.record(z.any()) }],
-  systemPrompt: '用 read() 查看当前可操作的组件 path,再按各自 schema 操作',
+  data: { schema: initialSchema, bind: initialObj, description: '初始数据' },
+  systemPrompt: '用 read() 查看当前可操作字段,按 schema 操作',
 }).mount()
 
-// 组件挂载(懒加载)→ 动态注册其 schema,立即对 AI 生效
-function mountComp(comp: { id: string; type: CompType }) {
-  window.app.components[comp.id] = reactive(comp)
-  sdk.addDataSlot({
-    path: `app.components.${comp.id}`,
-    description: `${comp.type} 组件`,
-    schema: compSchemas[comp.type],   // 结构各异:banner/card/stat/chart 各自 schema
+// later: swap to a different schema + bind (lazy-loaded / dynamic)
+function onComponentTypeChange(comp: { schema: z.ZodType; bind: any }) {
+  sdk.setData({
+    schema: comp.schema,   // new zod schema (validation + field hints auto-injected)
+    bind: comp.bind,       // new reactive/plain object
+    description: `${comp.type} 组件数据`,
   })
+  // tools now operate on comp.bind with comp.schema — immediately, no rebuild
 }
-// 组件卸载 → 动态移除注册(快照栈一并清理)
-function unmountComp(id: string) {
-  delete window.app.components[id]
-  sdk.removeDataSlot(`app.components.${id}`)
-}
+
+sdk.getData()  // read current config (reflects runtime swap)
 ```
 
 **完整可运行示例**:`examples/dynamic-demo/`(`npm run dev` → `/examples/dynamic-demo/`)。
-**何时用**:可视化编辑器/低代码平台中,组件按需加载且结构各异(图表/表单/卡片 schema 各不同),无法在初始化时穷举所有组件 schema。详见 `advanced.md` §0。
+**何时用**:可视化编辑器/低代码平台中,组件按需加载且结构各异(图表/表单/卡片 schema 各不同),无法在初始化时确定唯一 schema。详见 `advanced.md` §0。

package/types/index.d.ts

@@ -231,7 +231,13 @@ export interface VerifyMiddlewareOptions {
 export interface WriteBackCheckOptions {
   /** name → zod schema(由 createChatSdk 从 data 构造注入,键 '' 代表主数据);省略则只校验「读回非空」 */
   schemas?: Record<string, any>;
-  /** 读 window 的根对象(默认 globalThis.window) */
+  /**
+   * 读回的根对象。优先于 `window`。
+   * - 单对象 data 模式:传 bind 对象(或 getter `() => liveData()?.bind`,适配 sdk.setData 运行时替换)
+   * - 旧 windowProps 模式:省略则用 `window`(默认 globalThis.window)
+   */
+  root?: unknown | (() => unknown);
+  /** 读 window 的根对象(旧 windowProps 模式;data 模式应传 root)。默认 globalThis.window */
   window?: unknown;
 }