page-agent-sdk 2.5.0 → 2.5.1

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

@@ -1,77 +1,73 @@
-# Advanced examples — custom tools, skills, subagents, MCP, dynamic dataSlots
+# Advanced examples — custom tools, skills, subagents, MCP, dynamic schema
 
 Detailed, copy-paste examples for the extensibility surfaces. Read the section matching the user's need.
 
-## 0. Dynamic dataSlots (lazy-loaded components) — `sdk.addDataSlot` / `removeDataSlot`
+## 0. Dynamic schema (lazy-loaded / runtime swap) — `sdk.setData` / `getData`
 
-When components are lazy-loaded with **different schemas each**, don't declare all `dataSlots` upfront. Register them at runtime as components mount/unmount. The agent's data slot tools pick up new registrations immediately (no agent rebuild).
+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 agent rebuild.
 
 ```ts
 const sdk = createChatSdk({
   container: '#chat', llm: { ... },
-  systemPrompt: '你是页面助手,按组件类型操作数据槽.app.components.<id>。',
-  dataSlots: [
-    // statically-declared ones (always present)
-    { path: 'app.config', description: '全局配置', schema: z.record(z.any()) },
-  ],
+  systemPrompt: '你是 JSON 操作助手,按当前 schema 操作主数据。',
+  data: { schema: initialSchema, bind: initialObj, description: '初始数据' },
 }).mount()
 
-// 组件懒加载时动态注册其 schema(结构各异)
-function onComponentMount(comp: { id: string; type: string; schema: z.ZodType }) {
-  sdk.addDataSlot({ path: `app.components.${comp.id}`, description: `${comp.type} 组件`, schema: comp.schema })
-  // 立即生效:AI 现在能 write 这个 path,按其 schema 校验
-}
-
-// 组件卸载时移除(快照栈一并清理)
-function onComponentUnmount(id: string) {
-  sdk.removeDataSlot(`app.components.${id}`)
+// later: swap to a different schema + bind (lazy-loaded / dynamic)
+function onSchemaChange(newConfig: { schema: z.ZodType; bind: any; description?: string }) {
+  sdk.setData({
+    schema: newConfig.schema,    // new zod schema (validation + field hints auto-injected)
+    bind: newConfig.bind,        // new reactive/plain object
+    description: newConfig.description,
+  })
+  // 立即生效:AI 现在能 write newConfig.bind,按其 schema 校验
 }
 
-// 查看当前所有注册项(反映动态增删)
-const current: DataSlotSpec[] = sdk.listDataSlots()
+// 查看当前配置(反映运行时 swap)
+const current: DataConfig | undefined = sdk.getData()
 ```
 
 Notes:
-- `addDataSlot` 覆盖同名 path 时保留旧快照栈;按新 schema 校验。
-- 动态注册的属性**不自动纳入 checkpoint 快照**(checkpoint 的 slotPaths 在构造时固定);如需回滚动态组件,自行管理或重建。
-- `inspect().dataSlots` 与 `verify`(默认 `createWriteBackCheck`)均反映动态注册的最新 schemas(verify 每次 check 实时取 `listDataSlots()`)。
-- `capabilities.dataSlotOps:false` 时 `addDataSlot`/`removeDataSlot` 为 no-op(并 warn)。
+- `setData` replaces the whole config; old snapshots cleared & optimistic-lock hash reset.
+- `inspect().data` 与 `verify`(默认 `createWriteBackCheck`)均反映 `setData` 后的最新 schema/bind(verify 每次 check 实时取 `getData()`)。
+- `capabilities.dataOps:false` 时 `setData`/`getData` 仍可调用(仅替换配置,工具不暴露);工具调用为 no-op。
+- `summarization` 压缩时自动注入当前 `getData()` 的 description 进摘要 system 消息,LLM 不会基于过时记忆操作旧 schema。
 
-**完整可运行示例**:`examples/dynamic-demo/`(dev 启动后访问 `/examples/dynamic-demo/`)—— 演示加载/卸载结构各异的组件(banner/card/stat/chart),挂载即 `addDataSlot` 注册其 schema,AI 立即可按各自 schema 操作,卸载即 `removeDataSlot`;右侧实时显示 `sdk.listDataSlots()` 反映动态增删。
+**完整可运行示例**:`examples/dynamic-demo/`(dev 启动后访问 `/examples/dynamic-demo/`)—— 演示运行时 `setData` 切换不同 schema 的组件数据,AI 立即可按新 schema 操作。
 
 ### 动态场景下「压缩后不丢信息」的保障(内置,无需额外配置)
 
-动态组件随时增删,长会话压缩后 LLM 可能基于过时记忆操作已卸载的组件、或不知道新组件已注册。SDK 内置两道保障:
+schema 随时 swap,长会话压缩后 LLM 可能基于过时记忆操作旧 schema。SDK 内置两道保障:
 
-- **A. 压缩时注入注册表快照**:`summarization` 中间件压缩 older 轮次时,自动把当前 `listDataSlots()` 的 `path + description` 作为一段附进摘要 system 消息(不进压缩)。LLM 即便忘了历史 `describe`,每轮仍看得到「当前有哪些可操作 path」,不会再去操作已卸载的组件。`dataSlotOps` 关闭时返回空,无影响。
-- **C. preserveLastToolResults**:`contextOptions.preserveLastToolResults`(默认 `['describe_data_slot','list_data_slots']`)指定这些工具的步骤 `result` 在跨轮摘要时额外保留摘要片段进 summaryMsg。即便 older 轮被摘要,关键字段说明仍在摘要里,LLM 不必反复 `describe`。设为 `[]` 关闭。
+- **A. 压缩时注入数据描述**:`summarization` 中间件压缩 older 轮次时,自动把当前 `getData()` 的 `description` 作为一段附进摘要 system 消息(不进压缩)。LLM 即便忘了历史 `describe`,每轮仍看得到「当前主数据是什么」,不会操作过时 schema。`dataOps` 关闭时返回空,无影响。
+- **C. preserveLastToolResults**:`contextOptions.preserveLastToolResults`(默认 `['describe_data','read']`)指定这些工具的步骤 `result` 在跨轮摘要时额外保留摘要片段进 summaryMsg。即便 older 轮被摘要,关键字段说明仍在摘要里,LLM 不必反复 `describe`。设为 `[]` 关闭。
 
 ```ts
 // 默认即开启 A + C;如需关闭或自定义:
 createChatSdk({
   contextOptions: {
     preserveLastToolResults: [],  // 关闭 C(不保留工具结果摘要)
-    // getRegisteredSlots 由 SDK 内部注入(来自 sdk.listDataSlots),无需手动传
+    // getRegisteredData 由 SDK 内部注入(来自 sdk.getData),无需手动传
   },
   // ...
 })
 ```
 
-- **B. 写操作返回附当前可操作 path 列表**:`set`/`edit`/`delete` 成功返回末尾自动附 `(当前可操作 path: a, b, c)`,LLM 写完即知全貌,多组件批量场景减少 `list` 调用。超过 8 项或过长时只报数量,避免提示过长。
+- **B. 写操作返回附当前可操作字段列表**:`set`/`edit`/`delete` 成功返回末尾自动附 `(当前可操作字段: a, b, c)`,LLM 写完即知全貌,减少 `describe` 调用。超过 8 项或过长时只报数量,避免提示过长。
 - **D. `systemPromptHelpers.reliableWriteRules`**:导出的标准化「可靠写入规则」片段,建议拼进 `systemPrompt`:
 
 ```ts
 import { systemPromptHelpers } from 'page-agent-sdk'
 createChatSdk({
-  systemPrompt: `你是页面助手。\n${systemPromptHelpers.reliableWriteRules}`,
+  systemPrompt: `你是 JSON 操作助手。\n${systemPromptHelpers.reliableWriteRules}`,
   // ...
 })
 ```
-内容:改前先 `get` 读真实值、动态场景先 `list`、字段以 `describe` 为准、写错看校验错误重试、优先 `edit` 增量 patch。避免集成方忘了写这些元规则导致 LLM 凭记忆瞎改。
+内容:改前先 `read` 读真实值、字段以 `describe` 为准、写错看校验错误重试、优先 `edit` 增量 patch。避免集成方忘了写这些元规则导致 LLM 凭记忆瞎改。
 
 ## 1. Custom tools (`defineTool`)
 
-Custom tools extend the agent beyond built-in `dataSlotOps`/`fetch`. Use them to expose your product's API to the AI.
+Custom tools extend the agent beyond built-in `dataOps`/`fetch`. Use them to expose your product's API to the AI.
 
 ### Minimal
 
@@ -99,31 +95,31 @@ const updatePrice = defineTool({
   schema: z.object({ sku: z.string(), price: z.number().positive() }),
   handler: async ({ sku, price }) => {
     const ok = await api.setPrice(sku, price)
-    if (!ok) return toolError({ path: sku, code: 'NOT_FOUND', message: `SKU ${sku} 不存在` })
+    if (!ok) return toolError({ code: 'NOT_FOUND', message: `SKU ${sku} 不存在` })
     return `已更新 ${sku} 价格为 ${price}`
   },
 })
 ```
 
-### Coexisting with dataSlotOps
+### Coexisting with dataOps
 
-Mix custom tools with built-in data slot tools:
+Mix custom tools with built-in data tools:
 
 ```ts
 createChatSdk({
   container: '#chat', llm: { ... },
-  dataSlots: [{ path: 'app.config', description: '配置', schema: z.record(z.any()) }],
-  tools: [lookupOrder, updatePrice],   // custom + built-in dataSlotOps together
+  data: { schema: z.object({ config: z.record(z.any()) }), bind: { config: {} } },
+  tools: [lookupOrder, updatePrice],   // custom + built-in dataOps together
 }).mount()
 ```
 
-### Pure custom-tool agent (no dataSlotOps)
+### Pure custom-tool agent (no dataOps)
 
 ```ts
 createChatSdk({
   container: '#chat', llm: { ... },
   tools: [lookupOrder, updatePrice],
-  capabilities: { dataSlotOps: false, fetch: false },   // drop built-ins
+  capabilities: { dataOps: false, fetch: false },   // drop built-ins
 }).mount()
 ```
 
@@ -205,7 +201,7 @@ createChatSdk({
     {
       id: 'reviewer',
       description: '审查专家:检查代码/配置的安全与性能问题',
-      tools: ['read', 'search_data_slot'],
+      tools: ['read', 'search_data'],
       systemPrompt: '你是审查专家,只报告问题不改数据。',
       temperature: 0.1,
     },
@@ -270,7 +266,7 @@ createChatSdk({
   container: '#chat',
   llm: { apiKey, baseUrl, model },
   systemPrompt: '...',
-  dataSlots: [{ path: 'app.data', description: '...', schema: z.record(z.any()) }],
+  data: { schema: z.object({ data: z.record(z.any()) }), bind: { data: {} } },
   tools: [lookupOrder, updatePrice],          // custom tools
   skills: [apiDesignSkill, brandSkill],         // progressive skills
   subagents: [{ id: 'researcher', description: '...', tools: ['fetch_document'] }],  // pre-declared

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

@@ -1,4 +1,4 @@
-# API reference — instance methods, tool/skill definition, data slot tools, events
+# API reference — instance methods, tool/skill definition, data tools, events
 
 ## ChatSdk instance (`createChatSdk(...)` return)
 
@@ -9,12 +9,11 @@
 | `messages` | `AgentMessage[]` (reactive) | The conversation. Headless reads this to render. UI shares the same array (single source). |
 | `send(message)` | `(msg: string) => Promise<string>` | Send a user message (invoke mode, no stream events). Returns final content. |
 | `stream` | `(messages, onEvent, signal?) => Promise<string>` | Low-level stream. UI uses this internally; headless can call directly for streaming. |
-| `inspect()` | `() => AgentInfo` | Inspect agent: tools/skills/dataSlots/middleware/todos/mcp.servers (each tool's `source`: `builtin`/`mcp:<name>`/`user`). DebugDrawer uses this. |
+| `inspect()` | `() => AgentInfo` | Inspect agent: tools/skills/data/middleware/todos/mcp.servers (each tool's `source`: `builtin`/`mcp:<name>`/`user`). DebugDrawer uses this. |
 | `switchSession(id?)` | `(id?: string) => Promise<string>` | Switch session context (load or create by id). Requires `storage` enabled. |
 | `hook(handler)` | `(h: SdkEventHandler) => () => void` | Runtime event subscription (multi-listener, returns unsubscribe). Complements `onEvent`. |
-| `addDataSlot(spec)` | `(spec: DataSlotSpec) => void` | Runtime register/override a data slot (lazy-loaded components). Takes effect immediately, no rebuild. Needs `dataSlotOps` enabled. |
-| `removeDataSlot(path)` | `(path: string) => boolean` | Remove a registered data slot (component unmount); returns whether it existed. Clears its snapshot stack. |
-| `listDataSlots()` | `() => DataSlotSpec[]` | List currently-registered data slots (reflects dynamic add/remove). |
+| `setData(config)` | `(config: DataConfig) => void` | Runtime swap the main data config (`{ schema, bind, description? }`). Tools pick up new bind/schema immediately, no rebuild. Clears snapshots & resets optimistic-lock hash. |
+| `getData()` | `() => DataConfig \| undefined` | Read current main data config (reflects runtime `setData`). `undefined` if `dataOps` disabled. |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
 
@@ -33,7 +32,7 @@ const addTool = defineTool({
 createChatSdk({ tools: [addTool], /* llm, ... */ }).mount()
 ```
 
-`handler` receives validated args; return a string (or structured result stringified). Errors via `toolError({ path, code, message })`.
+`handler` receives validated args; return a string (or structured result stringified). Errors via `toolError({ code, message })`.
 
 ## defineSkill (progressive disclosure)
 
@@ -68,44 +67,42 @@ Spread into options for common scenarios.
 import { createChatSdk, systemPromptHelpers } from 'page-agent-sdk'
 
 createChatSdk({
-  systemPrompt: `你是页面助手。\n${systemPromptHelpers.reliableWriteRules}`,
+  systemPrompt: `你是 JSON 操作助手。\n${systemPromptHelpers.reliableWriteRules}`,
   llm, container,
 }).mount()
 ```
 
-`reliableWriteRules` — standardized "reliable write rules": read before write (`read`), list in dynamic scenarios (`read()` no path), fields per `read({path})` (returns format hint), retry on schema-validation errors, prefer `write` with `patch` incremental edits. Recommended for any scenario involving data-slot writes.
+`reliableWriteRules` — standardized "reliable write rules": read before write (`read`), fields per `read({jsonPath})` (returns format hint), retry on schema-validation errors, prefer `write` with `patch` incremental edits. Recommended for any scenario involving data writes.
 
-## Built-in data slot tools (auto-injected when `capabilities.dataSlotOps`)
+## 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`/`list`/`describe` are hidden, merged into `read`/`write`). `toolMode:'advanced'` exposes all; `toolMode:'minimal'` only `read`/`write`.
+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({path?})` lists/reads; `write({path, value?, patch?, del?})` merges set/edit/delete + auto optimistic lock + auto snapshot | simple/minimal |
-| `list_data_slots` | List declared paths + descriptions | advanced |
-| `describe_data_slot` | Show a path's schema | advanced |
-| `get_data_slot` | Read a path (or ancestor/descendant sub-paths of registered props) | advanced |
-| `get_slot_paths` | Batch-read multiple paths | simple/advanced |
-| `set_data_slot` | Write a whole path (schema-validated, scoped to registry) | advanced |
-| `edit_data_slot` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON | advanced |
-| `delete_data_slot` | Delete a path | advanced |
-| `snapshot_data_slot` | Manual snapshot | simple/advanced |
+| **`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_snapshot` | Restore (no id = most recent) | simple/advanced |
-| `query_data_slot` / `search_data_slot` | JSONPath query / full-text search | simple/advanced |
-| `eval_script` | Sandboxed script on data (for batch ops) | 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 **declared** `dataSlots` paths. 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).
+**Key rule**: `write`/`set`/`edit`/`delete` only affect **schema-declared** top-level fields (ZodObject auto-whitelist; undeclared fields hidden/denied). 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).
 
 ### write / jsonPath edit operations
 
-`write({ path, value, patch: { op, jsonPath } })` (or `write({ path, del: true })` to delete):
+`write({ value, patch: { op, jsonPath } })` (or `write({ patch: { jsonPath }, del: true })` to delete; or `write({ patches: [...] })` for batch atomic):
 - `set` — set a sub-path (or whole value when no `patch`)
 - `remove` — remove a sub-path / array element
 - `merge` — shallow-merge an object
 - `append` — append to an array
 
-Example: `write({ path: 'app.items', value: 9.9, patch: { op: 'set', jsonPath: '0.price' } })` — precise local edit, no full re-send. `value` is a JSON object (recommended) or JSON string.
+Example: `write({ value: 9.9, patch: { op: 'set', jsonPath: 'items.0.price' } })` — precise local edit, no full re-send. `value` is a JSON object (recommended) or JSON string. `patches: [{op:'set', jsonPath:'a', value:1}, {op:'append', jsonPath:'items', value:newItem}]` — batch atomic (any failure → whole batch rolled back).
 
 ## Built-in fetch tools (`capabilities.fetch`)
 
@@ -122,36 +119,37 @@ Example: `write({ path: 'app.items', value: 9.9, patch: { op: 'set', jsonPath: '
 | `tool_result` | `name, result, status` | Tool returns (`status`: `done`/`error`) |
 | `subagent` | `taskId, label, kind, name, args?, result?, status?` | Subagent tool progress (forwarded to UI, NOT into main LLM context) |
 | `done` | `content` | Agent round completes |
-| `data_slot_change` | `path, operation, value?` | A data slot was written via `write` (high-level, infers `set`/`edit`/`delete` from args) or low-level `set`/`edit`/`delete`/`restore_data_snapshot` |
+| `data_change` | `operation, value?` | Main data was written via `write` (infers `set`/`edit`/`delete` from args) or low-level `set`/`edit`/`delete`/`restore_data` |
 | `message_update` | `count` | The `messages` array changed |
 | `error` | `message` | An error occurred (abort excluded) |
 
 `approval_request` is **NOT** forwarded via `onEvent`/`hook` (UI handles it; headless integrators use a custom approval middleware listener).
 
-## `dataSlots` unified config (3.0+, declarative — schema + bind + auto field-hints)
+## `data` config (single main object — schema + bind + auto field-hints)
 
-`dataSlots` is the single entry for data-slot config — combining schema declaration + optional object direct-bind + auto field-hint injection:
+`data` is the single entry for main-data config — combining schema declaration + object direct-bind + auto field-hint injection:
 
 ```ts
-import { reactive } from 'vue'  // or any reactivity impl
-const PageSchema = z.object({ title: z.string().describe('页面标题'), count: z.number() })
+import { reactive } from 'vue'  // or any reactivity impl; plain object also works
+const PageSchema = z.object({
+  title: z.string().describe('页面标题'),
+  count: z.number().describe('计数器'),
+})
 const page = reactive({ title: '首页', count: 0 })  // reactive recommended for UI auto-refresh
 
 createChatSdk({
-  dataSlots: [
-    {
-      path: 'page',            // path on window (dot-nested supported)
-      schema: PageSchema,       // write validation + field .describe() auto-injected into systemPrompt「可操作属性」section
-      bind: page,               // optional: reactive/plain object auto-mounted to window[path] + registered as dataSlot
-    },
-  ],
+  data: {
+    schema: PageSchema,   // write validation + field .describe() auto-injected into systemPrompt「可操作数据」section + ZodObject top-level keys auto-whitelist
+    bind: page,           // reactive/plain object; tools read/write directly (no window)
+    description: '页面配置',  // optional; auto-generated if omitted
+  },
 })
 // LLM write page → page reactively updates; integrator changes page → LLM read sees it
 ```
 
-- **`bind` is an optional `dataSlots` field** (any object): reactive → auto-refresh on write (recommended for UI); plain object → write works but no auto-refresh (suitable for headless / backend; integrator uses `onEvent`/`hook` `data_slot_change` to be notified). Omit `bind` when the integrator mounts `window[path]` themselves (object already exists / dynamic registration via `addDataSlot`/`removeDataSlot` / field-whitelist read).
-- Tools `set`/`write` mutate in-place (`restoreInPlace`), compatible with reactive proxies; plain objects also write fine.
-- **Notifying the outside world of changes**: subscribe `data_slot_change` via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable) — fires after `write`/`set`/`edit`/`delete`/`restore`, with `path`/`operation`/`value`. For Vue + reactive bind, template/watch auto-react (no manual notify needed); `onEvent` can coexist for audit/analytics.
+- **`bind` is required** (any object): reactive → auto-refresh on write (recommended for UI); plain object → write works but no auto-refresh (suitable for headless / backend; integrator uses `onEvent`/`hook` `data_change` to be notified). Tools mutate in-place (`restoreInPlace`), compatible with reactive proxies; plain objects also write fine.
+- **Notifying the outside world of changes**: subscribe `data_change` via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable) — fires after `write`/`set`/`edit`/`delete`/`restore`, with `operation`/`value`. For Vue + reactive bind, template/watch auto-react (no manual notify needed); `onEvent` can coexist for audit/analytics.
+- **Runtime swap**: `sdk.setData({ schema, bind, description? })` replaces the whole config; tools pick up immediately (no rebuild). Snapshots & lock hash reset.
 
 ## Exported building blocks (for custom UIs)
 

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

@@ -7,7 +7,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
 | `llm` | `LLMConfig \| BaseChatModel` | — (required) | The model. `LLMConfig = { apiKey, baseUrl, model, temperature?, maxTokens? }` (OpenAI-compatible; DeepSeek default). Or pass any LangChain `BaseChatModel` (e.g. `ChatAnthropic`, install its peerDep). |
-| `systemPrompt` | `string` | built-in default (generic page assistant + reliable write rules) | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). If omitted, a built-in default is used (page-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it (append `systemPromptHelpers.reliableWriteRules` yourself if needed). |
+| `systemPrompt` | `string` | built-in default (JSON-operation assistant + reliable write rules) | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). If omitted, a built-in default is used (JSON-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it (append `systemPromptHelpers.reliableWriteRules` yourself if needed). |
 | `id` | `string` | random + warn | Stable agent id for multi-agent isolation & persistence. **Must pass a stable value** if you use `storage` or run multiple agents on one page. |
 | `title` / `placeholder` | `string` | — | Dialog title / input placeholder (cosmetic). |
 
@@ -17,17 +17,20 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 |---|---|---|---|
 | `container` | `string \| HTMLElement` | — | Where the built-in dialog mounts. Required when `ui !== false`. |
 | `ui` | `boolean \| 'default'` | `true` | `false` = headless (no built-in dialog; you build UI from `sdk.messages` + `sdk.send`). `'default'` = built-in `ChatDialog`. |
-| `streaming` | `boolean` | `true` | Stream tokens live. `false` = wait for full reply. Headless `sdk.send` always uses invoke (no stream events, but window/message/error still fire). |
+| `streaming` | `boolean` | `true` | Stream tokens live. `false` = wait for full reply. Headless `sdk.send` always uses invoke (no stream events, but data/message/error still fire). |
 
-## data slot operation (the core)
+## Data operation (the core)
 
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
-| `dataSlots` | `DataSlotSpec[]` | `[]` | Declare writable `window` paths + zod schemas. The agent can ONLY touch declared paths; `set`/`edit` are schema-validated. **This is the key integration step.** |
-| `maxSnapshots` | `number` | 20 | Per-path snapshot stack depth for `restore_data_snapshot`. |
-| `permissions` | `PermissionRule[]` | off | Scope whitelist (first-match-wins) for fine-grained per-path/tool rules. Default off (all declared paths writable). |
+| `data` | `DataConfig` | — | Declare the single main data object: `{ schema, bind, description? }`. `schema` = zod (write validation + field `.describe()` auto-injected into prompt + ZodObject top-level keys auto-whitelist); `bind` = reactive/plain object (tools read/write directly, no `window`); `description` = optional data purpose. **This is the key integration step.** |
+| `maxSnapshots` | `number` | 20 | Snapshot stack depth for `restore_data` (per-path snapshots auto-stored before set/edit/delete). |
+| `permissions` | `PermissionRule[]` | off | Scope whitelist (first-match-wins) for fine-grained per-jsonPath/tool rules. Default off (all schema-declared fields writable). |
+| `toolMode` | `'simple' \| 'advanced' \| 'minimal'` | `simple` | `simple` = high-level `read`/`write` + query/search/eval/snapshot (hides low-level get/set/edit/delete); `advanced` = all tools; `minimal` = only `read`/`write`. |
+| `interceptors` | `{ read?, write?, input?, output? }` | — | `read(value)` desensitize/derive (changes only what LLM sees); `write(payload, current)` transform/audit/reject (return `{error}`); `input`/`output` for message-level interception. |
+| `autoLock` | `boolean` | `true` | Auto optimistic lock: `write` compares LLM's last `read` hash with current; mismatch → `VERSION_CONFLICT` (or human resolution via `onConflict`). |
 
-`DataSlotSpec = { path: string; description: string; schema?: z.ZodType }`. `description` is shown to the AI — write it clearly so the agent knows what each path means.
+`DataConfig = { schema: z.ZodType; bind: any; description?: string }`. `bind` is any object — reactive (Vue auto-refresh) or plain (use `onEvent('data_change')` to re-render). Field `.describe()` text on `schema` is auto-extracted and injected into the system prompt so the LLM knows each field's purpose.
 
 ## Tools, skills, memory
 
@@ -44,8 +47,8 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 
 | Flag | Off when... |
 |---|---|
-| `dataSlotOps` | Pure research agent, no page edits (also drops data slot tools from subagents). |
-| `fetch` | No web fetching needed. ⚠️ turning off `dataSlotOps` also strips subagent data slot tools. |
+| `dataOps` | Pure research agent, no data edits (also drops data tools from subagents). |
+| `fetch` | No web fetching needed. ⚠️ turning off `dataOps` also strips subagent data tools. |
 | `planning` | Don't want `write_todos` planning. |
 | `skills` | Don't want progressive skill loading. |
 | `vfs` | No in-memory workspace; ⚠️ large tool results then truncate instead of offloading. |
@@ -70,7 +73,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
 | `contextPreset` | `'auto'\|'conservative'\|'aggressive'` | `auto` | `conservative` = save cost; `aggressive` = save context. `contextOptions` fine-tunes further. |
-| `contextOptions` | `object` | — | Detailed compression params (overrides preset). `false` disables compression. Key fields: `windowRounds`, `summaryThresholdRounds`, `contextWindow`, `summaryThresholdRatio`, `windowRatio`, `enableRecall`, `recallTopK`, `enableLLMSummary`, `preserveLastToolResults` (default `['describe_data_slot','list_data_slots']` — keep these tools' result summaries in the compressed summary so field descriptions survive compression; set `[]` to disable). `getRegisteredSlots` is injected internally by the SDK (from `sdk.listDataSlots`) to embed a live registry snapshot in the summary — no need to set it manually. |
+| `contextOptions` | `object` | — | Detailed compression params (overrides preset). `false` disables compression. Key fields: `windowRounds`, `summaryThresholdRounds`, `contextWindow`, `summaryThresholdRatio`, `windowRatio`, `enableRecall`, `recallTopK`, `enableLLMSummary`, `preserveLastToolResults` (default `['describe_data','read']` — keep these tools' result summaries in the compressed summary so field descriptions survive compression; set `[]` to disable). `getRegisteredData` is injected internally by the SDK (from `sdk.getData`) to embed a live data description in the summary — no need to set it manually. |
 | `summaryLlm` | `BaseChatModel \| LLMConfig` | main `llm` | Use a cheaper/faster model for summarization. |
 | `summaryTemperature` | `number` | 0.3 | Summary model temperature. |
 | `summaryMaxTokens` | `number` | 1024 | Summary output cap. |
@@ -86,7 +89,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 ## Verify (self-check before return)
 
 `capabilities.verify: true` enables. `verify: { check?, maxAttempts?, adversarial? }`:
-- `check` omitted → default `createWriteBackCheck()` (scans all writes, reads back + schema-validates; skips legitimately-rejected writes).
+- `check` omitted → default `createWriteBackCheck()` (scans all writes, reads back from `data.bind` + schema-validates; skips legitimately-rejected writes). Read-back root auto-bound to `data.bind` (adapts to `sdk.setData` runtime swap).
 - custom `check: async ({ messages, state }) => ({ ok, feedback? })` — return **actionable** feedback.
 - `adversarial: true` → after check passes, spawn a read-only "refuter" subagent (costs extra rounds; for semantically complex cases).
 - `maxAttempts` (default 2) caps self-correction loops.
@@ -97,15 +100,15 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 
 ## Checkpoint (session rollback)
 
-`checkpoint: true \| { maxCheckpoints?, auto? }` — per-round snapshot of (messages + data slots + vfs + todos). `restoreLastCheckpoint()` / LLM tool `restore_last_checkpoint` / UI button. Distinct from dataSlotOps per-path snapshots (checkpoint = whole-session rollback).
+`checkpoint: true \| { maxCheckpoints?, auto? }` — per-round snapshot of (messages + main data bind + vfs + todos). Read-back/restore auto-bound to `data.bind` via `getData` (adapts to `sdk.setData` runtime swap; in-place restore preserves reactive refs). `restoreLastCheckpoint()` / LLM tool `restore_last_checkpoint` / UI button. Distinct from dataOps per-path snapshots (checkpoint = whole-session rollback).
 
 ## Persistence (storage)
 
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
-| `storage` | `'indexed'\|'session'\|'local'\|'memory'\| StorageConfig \| false` | `false` (off) | Off by default; assign to enable. Persists messages/vfs/todos/memory (NOT window snapshots). Auto-degrades to memory if backend unavailable (private mode / quota). |
+| `storage` | `'indexed'\|'session'\|'local'\|'memory'\| StorageConfig \| false` | `false` (off) | Off by default; assign to enable. Persists messages/vfs/todos/memory (NOT `bind` — it may contain non-serializable content; store & re-inject via `sdk.setData`). Auto-degrades to memory if backend unavailable (private mode / quota). |
 | `session` | `SessionOptions` | — | Session control (resume by id, etc.). |
-| `shareContext` | `boolean` | `false` | `true` → multiple `createChatSdk` with same `id` share one `AgentCore` (same agent, multiple dialog views on a page). |
+| `shareContext` | `boolean` | `false` | `true` → multiple `createChatSdk` with same `id` share one `AgentCore` (same agent, multiple dialog views on a page; shares `data.bind` too). |
 
 ## MCP (external tools)
 

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/`).