page-agent-sdk 2.5.0 → 2.5.1

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;
 }