page-agent-sdk 1.4.2 → 2.1.0

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

@@ -1,6 +1,6 @@
 ---
 name: page-agent-sdk-integrate
-description: Integrate the page-agent-sdk npm package into a web app so an AI agent can read/write structured page data (window props) via schema-validated tools. Use when the user wants to add/embed the SDK, declare windowProps + zod schemas, configure the LLM, mount the chat dialog, subscribe to events (onEvent / sdk.hook), run headless (ui:false) with a custom UI, or troubleshoot common integration issues (DeepSeek 400 tool_call_id, MCP injecting 0 tools, etc).
+description: Integrate the page-agent-sdk npm package into a web app so an AI agent can read/write structured page data (data slots) via schema-validated tools. Use when the user wants to add/embed the SDK, declare dataSlots + zod schemas, configure the LLM, mount the chat dialog, subscribe to events (onEvent / sdk.hook), run headless (ui:false) with a custom UI, or troubleshoot common integration issues (DeepSeek 400 tool_call_id, MCP injecting 0 tools, etc).
 ---
 
 # Integrate page-agent-sdk
@@ -9,7 +9,7 @@ Help the user embed `page-agent-sdk` so an AI agent safely edits their page's st
 
 ## Core concept
 
-The SDK is a **standardized JSON-operation agent**: the integrator declares writable `window` paths + zod schemas; the agent edits them via `set_window_prop` / `edit_window_prop` (jsonPath patches), validated by schema, scoped to the registry, with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text.
+The SDK is a **standardized JSON-operation agent**: the integrator declares writable `window` paths + zod schemas; the agent edits them via `set_data_slot` / `edit_data_slot` (jsonPath patches), validated by schema, scoped to the registry, with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text.
 
 ## Workflow
 
@@ -23,7 +23,7 @@ The SDK is a **standardized JSON-operation agent**: the integrator declares writ
 
 See `demo/plain.html` for a framework-agnostic importmap + esm.sh example.
 
-### 2. Declare windowProps + schemas (the key step)
+### 2. Declare dataSlots + schemas (the key step)
 
 Put the page data on `window` (e.g. `window.app = { title, theme }`), then declare each writable path with a zod schema. The agent can ONLY touch declared paths; `set`/`edit` are schema-validated (invalid → structured error, no write).
 
@@ -39,7 +39,7 @@ createChatSdk({
   container: '#root',
   llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
   systemPrompt: 'You are a page assistant; read/write window.app via tools.',
-  windowProps: [
+  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() })) },
@@ -47,7 +47,7 @@ createChatSdk({
 }).mount()
 ```
 
-For large JSON, prefer `edit_window_prop` (jsonPath patch: set/remove/merge/append) over `set_window_prop` (whole value) — avoids re-sending the entire blob.
+For large JSON, prefer `edit_data_slot` (jsonPath patch: set/remove/merge/append) over `set_data_slot` (whole value) — avoids re-sending the entire blob.
 
 ### 3. Configure the LLM
 
@@ -59,7 +59,7 @@ Two complementary ways to react to SDK changes from the host page:
 
 ```ts
 const sdk = createChatSdk({
-  onEvent(e) { if (e.type === 'window_prop_change') renderUI() },  // constructor-time, single
+  onEvent(e) { if (e.type === 'data_slot_change') renderUI() },  // constructor-time, single
   // ...
 }).mount()
 
@@ -68,7 +68,7 @@ const off = sdk.hook((e) => { if (e.type === 'tool_call') analytics.track(e.name
 // off() to unsubscribe
 ```
 
-Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_result` / `text` / `round_start` / `done` / `error` (+ stream events in stream mode). `approval_request` is NOT forwarded (UI handles it).
+Event types: `data_slot_change` / `message_update` / `tool_call` / `tool_result` / `text` / `round_start` / `done` / `error` (+ stream events in stream mode). `approval_request` is NOT forwarded (UI handles it).
 
 ### 5. Headless mode (custom UI, framework-agnostic)
 
@@ -76,23 +76,23 @@ Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_resul
 
 ### 6. Capabilities & presets
 
-- `capabilities: { windowOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` — turn off unused built-ins to save tokens/size. `verify` is the reverse (off by default; `capabilities.verify:true` enables write-back self-check).
+- `capabilities: { dataSlotOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` — turn off unused built-ins to save tokens/size. `verify` is the reverse (off by default; `capabilities.verify:true` enables write-back self-check).
 - `presets.pageBuilder` / `researcher` / `minimal` — spread into `createChatSdk` for common scenarios.
 
 ## Common use cases (match the user's scenario, then read [references/use-cases.md](references/use-cases.md) for full code)
 
 | Scenario | Key setup |
 |---|---|
-| **Low-code page builder** | `windowProps` = component tree; `edit_window_prop` jsonPath patches; `onEvent` → canvas refresh; `checkpoint` + `approval` |
-| **Form designer** | `windowProps` = field definitions with enum/required schemas; schema validation prevents malformed forms |
-| **CMS batch ops** | `eval_window_script` for bulk loops; `search_window_prop` to filter; `edit_window_prop` for targeted edits |
+| **Low-code page builder** | `dataSlots` = component tree; `edit_data_slot` jsonPath patches; `onEvent` → canvas refresh; `checkpoint` + `approval` |
+| **Form designer** | `dataSlots` = field definitions with enum/required schemas; schema validation prevents malformed forms |
+| **CMS batch ops** | `eval_script` for bulk loops; `search_data_slot` to filter; `edit_data_slot` for targeted edits |
 | **Ops config console** | `approval:{tools:[set,edit]}` human-confirm; `capabilities.verify:true` write-back read; `checkpoint` |
-| **AI-native assistant** | `capabilities:{windowOps:false,fetch:false}` + custom `tools` (your product API) |
-| **Research agent** | `capabilities:{windowOps:false}`; `subagent:{allowedTools:['fetch_document']}`; `contextPreset:'conservative'` |
-| **Headless / server-side** | `ui:false` + `storage:'memory'` + `capabilities:{windowOps:false,fetch:false}`; drive via `sdk.send` |
+| **AI-native assistant** | `capabilities:{dataSlotOps:false,fetch:false}` + custom `tools` (your product API) |
+| **Research agent** | `capabilities:{dataSlotOps:false}`; `subagent:{allowedTools:['fetch_document']}`; `contextPreset:'conservative'` |
+| **Headless / server-side** | `ui:false` + `storage:'memory'` + `capabilities:{dataSlotOps:false,fetch:false}`; drive via `sdk.send` |
 | **Multi-agent on one page** | same `id` + `shareContext:true` → multiple dialogs share one `AgentCore` |
 | **MCP integration** | `mcp:[{transport,url}]` remote tool servers; `@modelcontextprotocol/sdk` optional peerDep |
-| **Lazy-loaded components (dynamic schemas)** | `sdk.addWindowProp(spec)` on component mount / `removeWindowProp` on unmount; tools pick up new registrations immediately, no rebuild. See [references/advanced.md §0](references/advanced.md) |
+| **Lazy-loaded components (dynamic schemas)** | `sdk.addDataSlot(spec)` on component mount / `removeDataSlot` on unmount; tools pick up new registrations immediately, no rebuild. See [references/advanced.md §0](references/advanced.md) |
 
 When the user describes a scenario, map it to the row above and load `references/use-cases.md` for the matching numbered case (1→10) with copy-paste code. For dynamic/lazy-loaded component schemas, custom tools/skills/subagents/MCP, load [references/advanced.md](references/advanced.md).
 
@@ -102,9 +102,9 @@ Detailed docs live in this skill's `references/` folder — load the one matchin
 
 - **[references/quickstart.md](references/quickstart.md)** — progressive setup from 5-line CDN to full-featured (Stages 0→6). Read when the user wants a step-by-step "from simple to complete" walkthrough.
 - **[references/options.md](references/options.md)** — every `createChatSdk` option: type, default, purpose & when to use. Read when the user asks "what does option X do" or needs to tune behavior.
-- **[references/api.md](references/api.md)** — instance methods (`mount`/`send`/`stream`/`inspect`/`switchSession`/`hook`/checkpoints), `defineTool`/`defineSkill`/`presets`, built-in window tools, and the full `SdkEvent` type table. Read when the user asks about APIs, tools, or events.
+- **[references/api.md](references/api.md)** — instance methods (`mount`/`send`/`stream`/`inspect`/`switchSession`/`hook`/checkpoints), `defineTool`/`defineSkill`/`presets`, built-in data slot tools, and the full `SdkEvent` type table. Read when the user asks about APIs, tools, or events.
 - **[references/use-cases.md](references/use-cases.md)** — 10 end-to-end scenarios (low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP / lazy-loaded dynamic components). Read when the user wants a concrete pattern for their use case.
-- **[references/advanced.md](references/advanced.md)** — detailed examples for the extensibility surfaces: **dynamic windowProps (`sdk.addWindowProp`/`removeWindowProp` for lazy-loaded components)**, custom `defineTool` (with error handling + coexisting with windowOps), `defineSkill` (inline content + remote doc), subagents (ad-hoc `spawn_agent`/`spawn_agents` + pre-declared `subagents` → `use_<id>`), MCP (http/sse/websocket + auth + dev gotcha). Read when the user asks "how to add custom tools / skills / subagents / MCP" or "lazy-load components with different schemas".
+- **[references/advanced.md](references/advanced.md)** — detailed examples for the extensibility surfaces: **dynamic dataSlots (`sdk.addDataSlot`/`removeDataSlot` for lazy-loaded components)**, custom `defineTool` (with error handling + coexisting with dataSlotOps), `defineSkill` (inline content + remote doc), subagents (ad-hoc `spawn_agent`/`spawn_agents` + pre-declared `subagents` → `use_<id>`), MCP (http/sse/websocket + auth + dev gotcha). Read when the user asks "how to add custom tools / skills / subagents / MCP" or "lazy-load components with different schemas".
 
 Project-level docs (in the repo, not bundled in this skill):
 - `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference
@@ -118,4 +118,4 @@ Project-level docs (in the repo, not bundled in this skill):
 - **ChatOpenAI params**: use `apiKey` (not `openAIApiKey`), `model` (not `modelName`); `baseUrl` goes via `configuration.baseURL`.
 - **MCP injects 0 tools on first cold visit**: `vite.config.ts` `optimizeDeps.include` pre-declares the SDK sub-paths; if you fork the config, keep those entries or the first MCP page load injects nothing (reload fixes it).
 - **`.env` `VITE_AI_SYSTEM_PROMPT` must be single-line** (dotenv doesn't support multi-line values).
-- **Server-side (Node.js)**: works with `ui:false` + `storage:'memory'` + `capabilities:{windowOps:false,fetch:false}`; `mount()`/`unmount()` guard `window`/`document` access. Provide `globalThis.window` if you enable windowOps in Node.
+- **Server-side (Node.js)**: works with `ui:false` + `storage:'memory'` + `capabilities:{dataSlotOps:false,fetch:false}`; `mount()`/`unmount()` guard `window`/`document` access. Provide `globalThis.window` if you enable dataSlotOps in Node.

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

@@ -1,16 +1,16 @@
-# Advanced examples — custom tools, skills, subagents, MCP, dynamic windowProps
+# Advanced examples — custom tools, skills, subagents, MCP, dynamic dataSlots
 
 Detailed, copy-paste examples for the extensibility surfaces. Read the section matching the user's need.
 
-## 0. Dynamic windowProps (lazy-loaded components) — `sdk.addWindowProp` / `removeWindowProp`
+## 0. Dynamic dataSlots (lazy-loaded components) — `sdk.addDataSlot` / `removeDataSlot`
 
-When components are lazy-loaded with **different schemas each**, don't declare all `windowProps` upfront. Register them at runtime as components mount/unmount. The agent's window tools pick up new registrations immediately (no agent rebuild).
+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).
 
 ```ts
 const sdk = createChatSdk({
   container: '#chat', llm: { ... },
-  systemPrompt: '你是页面助手,按组件类型操作 window.app.components.<id>。',
-  windowProps: [
+  systemPrompt: '你是页面助手,按组件类型操作数据槽.app.components.<id>。',
+  dataSlots: [
     // statically-declared ones (always present)
     { path: 'app.config', description: '全局配置', schema: z.record(z.any()) },
   ],
@@ -18,40 +18,40 @@ const sdk = createChatSdk({
 
 // 组件懒加载时动态注册其 schema(结构各异)
 function onComponentMount(comp: { id: string; type: string; schema: z.ZodType }) {
-  sdk.addWindowProp({ path: `app.components.${comp.id}`, description: `${comp.type} 组件`, schema: comp.schema })
-  // 立即生效:AI 现在能 set/edit_window_prop 这个 path,按其 schema 校验
+  sdk.addDataSlot({ path: `app.components.${comp.id}`, description: `${comp.type} 组件`, schema: comp.schema })
+  // 立即生效:AI 现在能 set/edit_data_slot 这个 path,按其 schema 校验
 }
 
 // 组件卸载时移除(快照栈一并清理)
 function onComponentUnmount(id: string) {
-  sdk.removeWindowProp(`app.components.${id}`)
+  sdk.removeDataSlot(`app.components.${id}`)
 }
 
 // 查看当前所有注册项(反映动态增删)
-const current: WindowPropSpec[] = sdk.listWindowProps()
+const current: DataSlotSpec[] = sdk.listDataSlots()
 ```
 
 Notes:
-- `addWindowProp` 覆盖同名 path 时保留旧快照栈;按新 schema 校验。
-- 动态注册的属性**不自动纳入 checkpoint 快照**(checkpoint 的 windowPaths 在构造时固定);如需回滚动态组件,自行管理或重建。
-- `inspect().windowProps` 与 `verify`(默认 `createWriteBackCheck`)均反映动态注册的最新 schemas(verify 每次 check 实时取 `listWindowProps()`)。
-- `capabilities.windowOps:false` 时 `addWindowProp`/`removeWindowProp` 为 no-op(并 warn)。
+- `addDataSlot` 覆盖同名 path 时保留旧快照栈;按新 schema 校验。
+- 动态注册的属性**不自动纳入 checkpoint 快照**(checkpoint 的 slotPaths 在构造时固定);如需回滚动态组件,自行管理或重建。
+- `inspect().dataSlots` 与 `verify`(默认 `createWriteBackCheck`)均反映动态注册的最新 schemas(verify 每次 check 实时取 `listDataSlots()`)。
+- `capabilities.dataSlotOps:false` 时 `addDataSlot`/`removeDataSlot` 为 no-op(并 warn)。
 
-**完整可运行示例**:`examples/dynamic-demo/`(dev 启动后访问 `/examples/dynamic-demo/`)—— 演示加载/卸载结构各异的组件(banner/card/stat/chart),挂载即 `addWindowProp` 注册其 schema,AI 立即可按各自 schema 操作,卸载即 `removeWindowProp`;右侧实时显示 `sdk.listWindowProps()` 反映动态增删。
+**完整可运行示例**:`examples/dynamic-demo/`(dev 启动后访问 `/examples/dynamic-demo/`)—— 演示加载/卸载结构各异的组件(banner/card/stat/chart),挂载即 `addDataSlot` 注册其 schema,AI 立即可按各自 schema 操作,卸载即 `removeDataSlot`;右侧实时显示 `sdk.listDataSlots()` 反映动态增删。
 
 ### 动态场景下「压缩后不丢信息」的保障(内置,无需额外配置)
 
 动态组件随时增删,长会话压缩后 LLM 可能基于过时记忆操作已卸载的组件、或不知道新组件已注册。SDK 内置两道保障:
 
-- **A. 压缩时注入注册表快照**:`summarization` 中间件压缩 older 轮次时,自动把当前 `listWindowProps()` 的 `path + description` 作为一段附进摘要 system 消息(不进压缩)。LLM 即便忘了历史 `describe`,每轮仍看得到「当前有哪些可操作 path」,不会再去操作已卸载的组件。`windowOps` 关闭时返回空,无影响。
-- **C. preserveLastToolResults**:`contextOptions.preserveLastToolResults`(默认 `['describe_window_prop','list_window_props']`)指定这些工具的步骤 `result` 在跨轮摘要时额外保留摘要片段进 summaryMsg。即便 older 轮被摘要,关键字段说明仍在摘要里,LLM 不必反复 `describe`。设为 `[]` 关闭。
+- **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`。设为 `[]` 关闭。
 
 ```ts
 // 默认即开启 A + C;如需关闭或自定义:
 createChatSdk({
   contextOptions: {
     preserveLastToolResults: [],  // 关闭 C(不保留工具结果摘要)
-    // getRegisteredProps 由 SDK 内部注入(来自 sdk.listWindowProps),无需手动传
+    // getRegisteredSlots 由 SDK 内部注入(来自 sdk.listDataSlots),无需手动传
   },
   // ...
 })
@@ -71,7 +71,7 @@ createChatSdk({
 
 ## 1. Custom tools (`defineTool`)
 
-Custom tools extend the agent beyond built-in `windowOps`/`fetch`. Use them to expose your product's API to the AI.
+Custom tools extend the agent beyond built-in `dataSlotOps`/`fetch`. Use them to expose your product's API to the AI.
 
 ### Minimal
 
@@ -105,25 +105,25 @@ const updatePrice = defineTool({
 })
 ```
 
-### Coexisting with windowOps
+### Coexisting with dataSlotOps
 
-Mix custom tools with built-in window tools:
+Mix custom tools with built-in data slot tools:
 
 ```ts
 createChatSdk({
   container: '#chat', llm: { ... },
-  windowProps: [{ path: 'app.config', description: '配置', schema: z.record(z.any()) }],
-  tools: [lookupOrder, updatePrice],   // custom + built-in windowOps together
+  dataSlots: [{ path: 'app.config', description: '配置', schema: z.record(z.any()) }],
+  tools: [lookupOrder, updatePrice],   // custom + built-in dataSlotOps together
 }).mount()
 ```
 
-### Pure custom-tool agent (no windowOps)
+### Pure custom-tool agent (no dataSlotOps)
 
 ```ts
 createChatSdk({
   container: '#chat', llm: { ... },
   tools: [lookupOrder, updatePrice],
-  capabilities: { windowOps: false, fetch: false },   // drop built-ins
+  capabilities: { dataSlotOps: false, fetch: false },   // drop built-ins
 }).mount()
 ```
 
@@ -177,7 +177,7 @@ createChatSdk({
   container: '#chat', llm: { ... },
   systemPrompt: '多源对比时用 spawn_agents 并行委派。',
   subagent: {
-    allowedTools: ['fetch_document', 'get_window_prop'],  // read-only subset (no spawn → no recursion)
+    allowedTools: ['fetch_document', 'get_data_slot'],  // read-only subset (no spawn → no recursion)
     maxDepth: 1,           // physical recursion cut (default 1)
     maxParallel: 3,        // max parallel subagents in spawn_agents
     temperature: 0.2,      // subagent temperature (default inherits main)
@@ -199,13 +199,13 @@ createChatSdk({
     {
       id: 'researcher',
       description: '调研专家:搜集资料、对比方案(只读)',
-      tools: ['fetch_document', 'get_window_prop'],   // read-only
+      tools: ['fetch_document', 'get_data_slot'],   // read-only
       temperature: 0.2,
     },
     {
       id: 'reviewer',
       description: '审查专家:检查代码/配置的安全与性能问题',
-      tools: ['get_window_prop', 'search_window_prop'],
+      tools: ['get_data_slot', 'search_data_slot'],
       systemPrompt: '你是审查专家,只报告问题不改数据。',
       temperature: 0.1,
     },
@@ -270,13 +270,13 @@ createChatSdk({
   container: '#chat',
   llm: { apiKey, baseUrl, model },
   systemPrompt: '...',
-  windowProps: [{ path: 'app.data', description: '...', schema: z.record(z.any()) }],
+  dataSlots: [{ path: 'app.data', description: '...', schema: z.record(z.any()) }],
   tools: [lookupOrder, updatePrice],          // custom tools
   skills: [apiDesignSkill, brandSkill],         // progressive skills
   subagents: [{ id: 'researcher', description: '...', tools: ['fetch_document'] }],  // pre-declared
   mcp: [{ transport: 'http', url: '...' }],     // external tools
   capabilities: { verify: true },               // self-check
-  approval: { tools: ['set_window_prop'] },     // human confirm writes
+  approval: { tools: ['set_data_slot'] },     // human confirm writes
   checkpoint: true,                             // rollback
 }).mount()
 ```

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

@@ -1,4 +1,4 @@
-# API reference — instance methods, tool/skill definition, window tools, events
+# API reference — instance methods, tool/skill definition, data slot tools, events
 
 ## ChatSdk instance (`createChatSdk(...)` return)
 
@@ -9,12 +9,12 @@
 | `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/windowProps/middleware/todos/mcp.servers (each tool's `source`: `builtin`/`mcp:<name>`/`user`). DebugDrawer uses this. |
+| `inspect()` | `() => AgentInfo` | Inspect agent: tools/skills/dataSlots/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`. |
-| `addWindowProp(spec)` | `(spec: WindowPropSpec) => void` | Runtime register/override a window prop (lazy-loaded components). Takes effect immediately, no rebuild. Needs `windowOps` enabled. |
-| `removeWindowProp(path)` | `(path: string) => boolean` | Remove a registered window prop (component unmount); returns whether it existed. Clears its snapshot stack. |
-| `listWindowProps()` | `() => WindowPropSpec[]` | List currently-registered window props (reflects dynamic add/remove). |
+| `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). |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
 
@@ -73,36 +73,36 @@ createChatSdk({
 }).mount()
 ```
 
-`reliableWriteRules` — standardized "reliable write rules": read before write (`get_window_prop`), list in dynamic scenarios, fields per `describe_window_prop`, retry on schema-validation errors, prefer `edit_window_prop` incremental patches. Recommended for any scenario involving window writes.
+`reliableWriteRules` — standardized "reliable write rules": read before write (`get_data_slot`), list in dynamic scenarios, fields per `describe_data_slot`, retry on schema-validation errors, prefer `edit_data_slot` incremental patches. Recommended for any scenario involving window writes.
 
-## Built-in window tools (auto-injected when `capabilities.windowOps`)
+## Built-in data slot tools (auto-injected when `capabilities.dataSlotOps`)
 
 | Tool | Purpose |
 |---|---|
-| `list_window_props` | List declared paths + descriptions |
-| `describe_window_prop` | Show a path's schema |
-| `get_window_prop` | Read a path (or ancestor/descendant sub-paths of registered props) |
-| `get_window_paths` | Batch-read multiple paths |
-| `set_window_prop` | Write a whole path (schema-validated, scoped to registry) |
-| `edit_window_prop` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON |
-| `delete_window_prop` | Delete a path |
-| `snapshot_window_prop` | Manual snapshot |
-| `list_window_snapshots` | List snapshots |
-| `restore_window_snapshot` | Restore (no id = most recent) |
-| `query_window_prop` / `search_window_prop` | JSONPath query / full-text search |
-| `eval_window_script` | Sandboxed script on data (for batch ops) |
-
-**Key rule**: `set`/`edit`/`delete` only affect **declared** `windowProps` paths. Invalid schema → structured error, no write. `edit` writes in-place (preserves Vue reactive refs).
+| `list_data_slots` | List declared paths + descriptions |
+| `describe_data_slot` | Show a path's schema |
+| `get_data_slot` | Read a path (or ancestor/descendant sub-paths of registered props) |
+| `get_slot_paths` | Batch-read multiple paths |
+| `set_data_slot` | Write a whole path (schema-validated, scoped to registry) |
+| `edit_data_slot` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON |
+| `delete_data_slot` | Delete a path |
+| `snapshot_data_slot` | Manual snapshot |
+| `list_data_snapshots` | List snapshots |
+| `restore_data_snapshot` | Restore (no id = most recent) |
+| `query_data_slot` / `search_data_slot` | JSONPath query / full-text search |
+| `eval_script` | Sandboxed script on data (for batch ops) |
+
+**Key rule**: `set`/`edit`/`delete` only affect **declared** `dataSlots` paths. Invalid schema → structured error, no write. `edit` writes in-place (preserves Vue reactive refs).
 
 ### jsonPath edit operations
 
-`edit_window_prop({ path, jsonPath, op, value })`:
+`edit_data_slot({ path, jsonPath, op, value })`:
 - `set` — set a sub-path
 - `remove` — remove a sub-path / array element
 - `merge` — shallow-merge an object
 - `append` — append to an array
 
-Example: `edit_window_prop({ path: 'app.items', jsonPath: '0.price', op: 'set', value: 9.9 })` — precise local edit, no full re-send.
+Example: `edit_data_slot({ path: 'app.items', jsonPath: '0.price', op: 'set', value: 9.9 })` — precise local edit, no full re-send.
 
 ## Built-in fetch tools (`capabilities.fetch`)
 
@@ -119,7 +119,7 @@ Example: `edit_window_prop({ path: 'app.items', jsonPath: '0.price', op: 'set',
 | `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 |
-| `window_prop_change` | `path, operation, value?` | A window prop was written (`operation`: `set`/`edit`/`delete`/`restore`) |
+| `data_slot_change` | `path, operation, value?` | A data slot was written (`operation`: `set`/`edit`/`delete`/`restore`) |
 | `message_update` | `count` | The `messages` array changed |
 | `error` | `message` | An error occurred (abort excluded) |
 

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

@@ -19,15 +19,15 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | `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). |
 
-## window operation (the core)
+## data slot operation (the core)
 
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
-| `windowProps` | `WindowPropSpec[]` | `[]` | 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_window_snapshot`. |
+| `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). |
 
-`WindowPropSpec = { path: string; description: string; schema?: z.ZodType }`. `description` is shown to the AI — write it clearly so the agent knows what each path means.
+`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.
 
 ## Tools, skills, memory
 
@@ -44,8 +44,8 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 
 | Flag | Off when... |
 |---|---|
-| `windowOps` | Pure research agent, no page edits (also drops window tools from subagents). |
-| `fetch` | No web fetching needed. ⚠️ turning off `windowOps` also strips subagent window tools. |
+| `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. |
 | `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 +70,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_window_prop','list_window_props']` — keep these tools' result summaries in the compressed summary so field descriptions survive compression; set `[]` to disable). `getRegisteredProps` is injected internally by the SDK (from `sdk.listWindowProps`) 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_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. |
 | `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. |
@@ -97,7 +97,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 
 ## Checkpoint (session rollback)
 
-`checkpoint: true \| { maxCheckpoints?, auto? }` — per-round snapshot of (messages + window props + vfs + todos). `restoreLastCheckpoint()` / LLM tool `restore_last_checkpoint` / UI button. Distinct from windowOps per-path snapshots (checkpoint = whole-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).
 
 ## Persistence (storage)
 

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

@@ -20,7 +20,7 @@ Drop into any HTML page. The built-in dialog mounts itself. (`systemPrompt` is o
     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.',
-    windowProps: [
+    dataSlots: [
       { path: 'app.title', description: '标题', schema: ChatSdk.z.string() },
       { path: 'app.theme', description: '主题', schema: ChatSdk.z.enum(['light','dark']) },
     ],
@@ -28,7 +28,7 @@ Drop into any HTML page. The built-in dialog mounts itself. (`systemPrompt` is o
 </script>
 ```
 
-Talk to it: "change theme to dark" → AI calls `set_window_prop` → `window.app.theme === 'dark'`.
+Talk to it: "change theme to dark" → AI calls `set_data_slot` → `window.app.theme === 'dark'`.
 
 ## Stage 2 — npm + module project
 
@@ -46,7 +46,7 @@ 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.',
-  windowProps: [
+  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() })) },
@@ -61,10 +61,10 @@ Subscribe via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, ca
 ```ts
 const sdk = createChatSdk({
   onEvent(e) {
-    if (e.type === 'window_prop_change') renderUI()       // host page reactive refresh
+    if (e.type === 'data_slot_change') renderUI()       // host page reactive refresh
     if (e.type === 'error') console.error(e.message)
   },
-  // ...llm, windowProps...
+  // ...llm, dataSlots...
 }).mount()
 
 // runtime listener (e.g. analytics), cancellable
@@ -79,7 +79,7 @@ No built-in dialog; drive the reactive `messages` array yourself.
 ```ts
 const sdk = createChatSdk({
   ui: false,                                  // headless
-  llm: { ... }, systemPrompt: '...', windowProps: [...],
+  llm: { ... }, systemPrompt: '...', dataSlots: [...],
 }).mount()
 
 // your own UI reads sdk.messages (reactive) and calls sdk.send
@@ -92,10 +92,10 @@ Reusable `ChatDialog` / `MessageContent` / `CodePreview` components + `useChat`
 
 ```ts
 createChatSdk({
-  // ...llm, windowProps...
+  // ...llm, dataSlots...
   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: ['set_window_prop', 'edit_window_prop'] },  // human-confirm before writes
+  approval: { tools: ['set_data_slot', 'edit_data_slot'] },  // 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
@@ -108,14 +108,14 @@ createChatSdk({
 createChatSdk({
   id: 'my-page-agent',          // STABLE id (multi-agent isolation); omit = random + warn
   storage: 'indexed',           // persist messages/vfs/todos/memory to IndexedDB
-  // ...llm, windowProps...
+  // ...llm, dataSlots...
 }).mount()
 
 // later, switch session:
 await sdk.switchSession('session-abc')   // load or create
 ```
 
-## Stage 7 — Dynamic windowProps (lazy-loaded components)
+## Stage 7 — Dynamic dataSlots (lazy-loaded components)
 
 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.
 
@@ -123,13 +123,13 @@ Components loaded on demand with **different schemas each** — register at moun
 const sdk = createChatSdk({
   container: '#root', llm: { ... },
   // only the static container is pre-declared; per-component paths are dynamic
-  windowProps: [{ path: 'app.components', description: '动态组件容器(按 id 存)', schema: z.record(z.string(), z.any()) }],
+  dataSlots: [{ path: 'app.components', description: '动态组件容器(按 id 存)', schema: z.record(z.string(), z.any()) }],
 }).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.addWindowProp({
+  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
@@ -138,9 +138,9 @@ function mountComp(comp: { id: string; type: 'banner' | 'card' | 'stat' | 'chart
 // component unmounts → unregister (snapshot stack cleaned too)
 function unmountComp(id: string) {
   delete window.app.components[id]
-  sdk.removeWindowProp(`app.components.${id}`)
+  sdk.removeDataSlot(`app.components.${id}`)
 }
-sdk.listWindowProps()  // live registry (reflects dynamic add/remove)
+sdk.listDataSlots()  // live registry (reflects dynamic add/remove)
 ```
 
 > 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.