page-agent-sdk 2.1.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.1.0",
+  "version": "2.4.1",
   "type": "module",
   "description": "框架无关的页面内 Agent JS SDK —— 以对话框形态挂载到任意网页,通过自定义 tool 读写宿主预注册的数据槽(经 schema 校验 + jsonPath 增量 patch + 快照回退;GET 抓文档),具备 planning/skills/虚拟工作区/context 管理能力。Vue 打包进库,使用者无需安装 Vue。",
   "main": "./dist/page-agent-sdk.umd.cjs",

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

@@ -9,7 +9,7 @@ Help the user embed `page-agent-sdk` so an AI agent safely edits 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_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.
+The SDK is a **standardized JSON-operation agent**: the integrator declares writable `window` paths + zod schemas; the agent edits them via `read` / `write` (high-level entry, 2.2+; `write` merges set/edit/delete + auto optimistic lock + auto snapshot), validated by schema, scoped to the registry, with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text. Advanced mode (`toolMode:'advanced'`) also exposes low-level `get_data_slot`/`set_data_slot`/`edit_data_slot`/`delete_data_slot` for precise control.
 
 ## Workflow
 
@@ -47,7 +47,7 @@ createChatSdk({
 }).mount()
 ```
 
-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.
+For large JSON, prefer `write` with `patch` (jsonPath patch: set/remove/merge/append) over `write` with whole `value` — avoids re-sending the entire blob.
 
 ### 3. Configure the LLM
 
@@ -83,10 +83,10 @@ Event types: `data_slot_change` / `message_update` / `tool_call` / `tool_result`
 
 | Scenario | Key setup |
 |---|---|
-| **Low-code page builder** | `dataSlots` = component tree; `edit_data_slot` jsonPath patches; `onEvent` → canvas refresh; `checkpoint` + `approval` |
+| **Low-code page builder** | `dataSlots` = component tree; `write` patch jsonPath; `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` |
+| **CMS batch ops** | `eval_script` for bulk loops; `search_data_slot` to filter; `write` patch for targeted edits |
+| **Ops config console** | `approval:{tools:['write']}` human-confirm; `capabilities.verify:true` write-back read; `checkpoint` |
 | **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` |

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

@@ -19,7 +19,7 @@ const sdk = createChatSdk({
 // 组件懒加载时动态注册其 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 现在能 set/edit_data_slot 这个 path,按其 schema 校验
+  // 立即生效:AI 现在能 write 这个 path,按其 schema 校验
 }
 
 // 组件卸载时移除(快照栈一并清理)
@@ -177,7 +177,7 @@ createChatSdk({
   container: '#chat', llm: { ... },
   systemPrompt: '多源对比时用 spawn_agents 并行委派。',
   subagent: {
-    allowedTools: ['fetch_document', 'get_data_slot'],  // read-only subset (no spawn → no recursion)
+    allowedTools: ['fetch_document', 'read'],  // 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_data_slot'],   // read-only
+      tools: ['fetch_document', 'read'],   // read-only
       temperature: 0.2,
     },
     {
       id: 'reviewer',
       description: '审查专家:检查代码/配置的安全与性能问题',
-      tools: ['get_data_slot', 'search_data_slot'],
+      tools: ['read', 'search_data_slot'],
       systemPrompt: '你是审查专家,只报告问题不改数据。',
       temperature: 0.1,
     },
@@ -276,7 +276,7 @@ createChatSdk({
   subagents: [{ id: 'researcher', description: '...', tools: ['fetch_document'] }],  // pre-declared
   mcp: [{ transport: 'http', url: '...' }],     // external tools
   capabilities: { verify: true },               // self-check
-  approval: { tools: ['set_data_slot'] },     // human confirm writes
+  approval: { tools: ['write'] },     // human confirm writes
   checkpoint: true,                             // rollback
 }).mount()
 ```

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

@@ -73,36 +73,39 @@ createChatSdk({
 }).mount()
 ```
 
-`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.
+`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.
 
 ## Built-in data slot tools (auto-injected when `capabilities.dataSlotOps`)
 
-| Tool | Purpose |
-|---|---|
-| `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_data_slot({ path, jsonPath, op, value })`:
-- `set` — set a sub-path
+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`.
+
+| 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 |
+| `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 |
+
+**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).
+
+### write / jsonPath edit operations
+
+`write({ path, value, patch: { op, jsonPath } })` (or `write({ path, del: true })` to delete):
+- `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: `edit_data_slot({ path: 'app.items', jsonPath: '0.price', op: 'set', value: 9.9 })` — precise local edit, no full re-send.
+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.
 
 ## Built-in fetch tools (`capabilities.fetch`)
 
@@ -119,12 +122,37 @@ Example: `edit_data_slot({ path: 'app.items', jsonPath: '0.price', op: 'set', va
 | `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 (`operation`: `set`/`edit`/`delete`/`restore`) |
+| `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` |
 | `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)
+
+`dataSlots` is the single entry for data-slot config — combining schema declaration + optional 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() })
+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
+    },
+  ],
+})
+// 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.
+
 ## Exported building blocks (for custom UIs)
 
 - `ChatDialog`, `MessageContent`, `CodePreview` — Vue components

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

@@ -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_data_slot` → `window.app.theme === 'dark'`.
+Talk to it: "change theme to dark" → AI calls `write({ path:'app.theme', value:'dark' })` → `window.app.theme === 'dark'`.
 
 ## Stage 2 — npm + module project
 
@@ -95,7 +95,7 @@ createChatSdk({
   // ...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_data_slot', 'edit_data_slot'] },  // 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

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

@@ -17,7 +17,7 @@ window.page = {
 createChatSdk({
   container: '#chat',
   llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat', temperature: 0.3 },
-  systemPrompt: '你是页面搭建助手。用 edit_data_slot 按 jsonPath 增量改 components,不要重传整树。',
+  systemPrompt: '你是页面搭建助手。用 write 的 patch 按 jsonPath 增量改 components,不要重传整树。',
   dataSlots: [
     { path: 'page.components', description: '组件树',
       schema: z.array(z.object({
@@ -27,11 +27,11 @@ createChatSdk({
   ],
   onEvent(e) { if (e.type === 'data_slot_change') renderCanvas() },  // canvas reactive refresh
   checkpoint: true,                       // bad edit → one-click rollback
-  approval: { tools: ['set_data_slot', 'edit_data_slot'] },  // confirm writes
+  approval: { tools: ['write'] },  // confirm writes
 }).mount()
 ```
 
-User: "顶部 Banner 改深色、主标题加粗、加一张新品卡" → AI calls `edit_data_slot` per component.
+User: "顶部 Banner 改深色、主标题加粗、加一张新品卡" → AI calls `write` with `patch` per component.
 
 ## 2. Form designer
 
@@ -66,7 +66,7 @@ User: "手机号加格式校验、地址改三级联动" → AI patches `form.fi
 
 ## 3. CMS batch operation
 
-Bulk-edit a product list; use `eval_script` or `search_data_slot` + `edit_data_slot` for batch ops.
+Bulk-edit a product list; use `eval_script` or `search_data_slot` + `write` with `patch` for batch ops.
 
 ```ts
 window.products = [
@@ -88,7 +88,7 @@ createChatSdk({
 }).mount()
 ```
 
-User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_script` for the prefix loop + `search_data_slot` to find `<100` then `edit_data_slot` to set `highlight`.
+User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_script` for the prefix loop + `search_data_slot` to find `<100` then `write` with `patch` to set `highlight`.
 
 ## 4. Ops config console
 
@@ -109,7 +109,7 @@ createChatSdk({
     { path: 'config.featureB', description: 'B开关',
       schema: z.object({ enabled: z.boolean() }) },
   ],
-  approval: { tools: ['set_data_slot', 'edit_data_slot'] },  // human-in-the-loop
+  approval: { tools: ['write'] },  // human-in-the-loop
   checkpoint: true,
   capabilities: { verify: true },           // write-back read + schema check
 }).mount()
@@ -208,7 +208,7 @@ 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: '用 list_data_slots 查看当前可操作的组件 path,再按各自 schema 操作',
+  systemPrompt: '用 read() 查看当前可操作的组件 path,再按各自 schema 操作',
 }).mount()
 
 // 组件挂载(懒加载)→ 动态注册其 schema,立即对 AI 生效

package/types/index.d.ts

@@ -45,7 +45,7 @@ export type StreamHandler = (event: StreamEvent) => void;
 /**
  * SDK 事件(供 createChatSdk({ onEvent }) 订阅常用时机)。
  * 复用 StreamEvent(round_start/reasoning/text/tool_call/tool_result/subagent/done;approval_request 不外发)
- * + 额外时机:data_slot_change / message_update / error。
+ * + 额外时机:data_change / message_update / error。
  */
 export type SdkEvent =
   | { type: 'round_start'; round: number }
@@ -55,7 +55,7 @@ export type SdkEvent =
   | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error' }
   | { type: 'subagent'; taskId: string; label: string; kind: 'tool_call' | 'tool_result'; name: string; args?: any; result?: string; status?: 'done' | 'error' }
   | { type: 'done'; content: string }
-  | { type: 'data_slot_change'; path: string; operation: 'set' | 'edit' | 'delete' | 'restore'; value?: unknown }
+  | { type: 'data_change'; operation: 'set' | 'edit' | 'delete' | 'restore'; value?: unknown }
   | { type: 'message_update'; count: number }
   | { type: 'conflict'; conflict: PendingConflict }
   | { type: 'error'; message: string };
@@ -80,7 +80,7 @@ export interface ChatDialogProps {
 
 export interface ToolInfo { name: string; description: string; schema?: unknown; source?: string }
 export interface SkillInfo { name: string; description: string }
-export interface DataSlotInfo { path: string; description: string; schema?: unknown }
+export interface DataInfo { description?: string; schema?: unknown }
 export interface SubagentInfo {
   enabled: boolean;
   maxDepth: number;
@@ -108,7 +108,7 @@ export interface AgentInfo {
   systemPrompt: string;
   tools: ToolInfo[];
   skills: SkillInfo[];
-  dataSlots: DataSlotInfo[];
+  data?: DataInfo;
   memory: string;
   middleware: string[];
   todos: { content: string; status: string }[];
@@ -149,45 +149,49 @@ export type ChatModelLike = {
   bindTools: (tools: any[]) => any;
 };
 
-export interface DataSlotSpec {
-  /** window 上的路径,支持点号嵌套 */
-  path: string;
-  description: string;
-  /** 值的 zod schema(写入时校验) */
+export interface DataConfig {
+  /** 值的 zod schema(写入时校验);字段的 .describe() 自动提取注入 systemPrompt「可操作数据」段 */
   schema: any;
-}
-/** createDataSlotOps 选项(审计回调 / 只读探测 / 快照上限 / 字段白名单读 / 乐观锁) */
-export interface DataSlotOpsOptions {
-  onAudit?: (entry: { op: string; path: string; value?: any; detail?: string; timestamp: number }) => void;
-  allowRawRead?: boolean;
+  /** 数据源:reactive/普通对象,工具直接读写 bind(reactive 写后响应式刷新;不挂 window) */
+  bind: any;
+  /** 数据说明,供 Agent 理解用途;不传则自动生成 */
+  description?: string;
+}
+/** createDataOps 选项(审计回调 / 快照上限 / 乐观锁) */
+export interface DataOpsOptions {
+  onAudit?: (entry: { op: string; value?: any; detail?: string; timestamp: number }) => void;
   maxSnapshots?: number;
-  /**
-   * 字段白名单读模式(默认 true):仅允许读「注册 path 自身 / 其后代」,禁止读未注册的祖先,
-   * 防止 LLM 经 get_data_slot('page') 把整个大 JSON 拉进上下文。
-   * 集成方注册「可操作子路径」(如 page.theme.color / page.components)而非顶层时,默认即「LLM 只见声明字段」。
-   * 设 false 回退原行为(允许读注册 path 的祖先,即整体读)。
-   */
-  whitelist?: boolean;
   /** 乐观锁冲突人工介入回调(详见 ConflictInfo/ConflictResolution);不传则冲突时返回 VERSION_CONFLICT 错误 */
   onConflict?: (conflict: ConflictInfo) => Promise<ConflictResolution>;
   /**
-   * 自动乐观锁(默认 true):写入时若 LLM 未显式传 expectedHash,自动用「LLM 最后一次 get_data_slot 读到的 hash」作基准比对。
+   * 自动乐观锁(默认 true):写入时若 LLM 未显式传 expectedHash,自动用「LLM 最后一次 read/get 读到的 hash」作基准比对。
    * LLM 无需手动传 expectedHash 即可享受乐观锁保护;冲突走 onConflict(无 onConflict 则返回 VERSION_CONFLICT)。
    * LLM 未读过直接写(无基准记录)时跳过锁(等同不校验)。设 false 回退「不传 expectedHash = 不校验」的旧行为。
    */
   autoLock?: boolean;
+  /** 读写拦截器:read/write 透传给数据工具(脱敏/转换/审计/拒绝 LLM 读写) */
+  interceptors?: DataInterceptors;
 }
 
-/** 数据槽注册表控制器(运行时动态增删;createDataSlotOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
-export interface DataSlotOpsController {
-  /** 新增/覆盖一个属性注册项(运行时懒加载组件场景);覆盖时旧快照栈保留 */
-  add(spec: DataSlotSpec): void;
-  /** 移除一个属性注册项;返回是否确实存在并移除。快照栈一并清理 */
-  remove(path: string): boolean;
-  /** 列出当前所有注册项(反映动态增删后的最新状态) */
-  list(): DataSlotSpec[];
-  /** 是否已注册某 path */
-  has(path: string): boolean;
+/** 数据读写拦截器(集成方可脱敏/转换/审计/拒绝 LLM 的读写) */
+export interface DataInterceptors {
+  /** LLM 读时拦截:原始值 → 改写后返回给 LLM(如脱敏/派生);抛错则返回 READ_INTERCEPT 错误 */
+  read?: (value: any) => any;
+  /** LLM 写时拦截:欲写值 + 当前值 → 改写后的值,或 { error } 拒绝;抛错则拒绝 */
+  write?: (payload: any, current: any) => any | { error: string };
+}
+
+/** 工具呈现模式:simple=主推 read/write 但保留高级能力(默认)| advanced=全暴露| minimal=只 read/write */
+export type ToolMode = 'simple' | 'advanced' | 'minimal';
+
+/** 数据操作控制器(运行时替换配置;createDataOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
+export interface DataOpsController {
+  /** 读取当前配置 */
+  get(): DataConfig;
+  /** 替换主数据配置(如页面切换、schema 变更);清空快照栈与乐观锁缓存 */
+  set(config: DataConfig): void;
+  /** 仅替换 bind 引用;清空快照栈与乐观锁缓存 */
+  update(bind: any): void;
 }
 
 export interface PermissionRule {
@@ -225,7 +229,7 @@ export interface VerifyMiddlewareOptions {
 }
 /** createWriteBackCheck 选项 */
 export interface WriteBackCheckOptions {
-  /** path → zod schema(由 createChatSdk 从 dataSlots 构造注入);省略则只校验「读回非空」 */
+  /** name → zod schema(由 createChatSdk 从 data 构造注入,键 '' 代表主数据);省略则只校验「读回非空」 */
   schemas?: Record<string, any>;
   /** 读 window 的根对象(默认 globalThis.window) */
   window?: unknown;
@@ -333,15 +337,26 @@ export interface ChatSdkOptions {
   tools?: any[];
   skills?: SkillSpec[];
   memory?: string;
-  dataSlots?: DataSlotSpec[];
+  data?: DataConfig;
   permissions?: PermissionRule[];
   /** 自定义中间件(注入到内置中间件之后;可拦截/观察模型调用、工具、prompt) */
   middleware?: any[];
   vfs?: { initialFiles?: Record<string, string>; maxBytes?: number };
-  /** 每个 数据槽最多保留快照数(默认 20) */
+  /** 每个数据对象最多保留快照数(默认 20) */
   maxSnapshots?: number;
   /** 自动乐观锁(默认 true):写入时若 LLM 未传 expectedHash,自动用其最后 get 读到的 hash 比对;设 false 回退「不传 = 不校验」 */
   autoLock?: boolean;
+  /** 工具呈现模式:simple(默认,主推 read/write 但保留 query/search/eval/snapshot)| advanced(全暴露)| minimal(只 read/write) */
+  toolMode?: 'simple' | 'advanced' | 'minimal';
+  /** 读写拦截器:read/write 透传给数据工具(脱敏/转换/审计/拒绝 LLM 读写);input/output 在 agent IO 入口/出口预处理 */
+  interceptors?: {
+    read?: (value: any) => any;
+    write?: (payload: any, current: any) => any | { error: string };
+    /** agent 接收输入时拦截:send/stream 的 user message 预处理(可改写/审计) */
+    input?: (input: any) => any;
+    /** agent 产出输出时拦截:返回前 postprocess(可改写最终回复) */
+    output?: (json: any) => any;
+  };
   /** 内存中保留的对话轮数上限(默认 50);超限把最旧轮次压缩为摘要 system 消息(防 OOM);0 关闭 */
   maxMemoryRounds?: number;
   debug?: boolean;
@@ -355,7 +370,7 @@ export interface ChatSdkOptions {
   /** 模型最大输出(token);顶层声明对 llm 实例场景也生效,缺省按 model 名查表 */
   maxOutputTokens?: number;
   /** 子 agent 委派(默认开启;{ enabled: false } 关闭) */
-  capabilities?: { dataSlotOps?: boolean; fetch?: boolean; planning?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean };
+  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean };
   subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number };
   /** 预声明子 agent 列表:每个用同主配置方式声明,自动生成 use_<id> 委派工具(与 spawn_agent 共存) */
   subagents?: SubagentConfig[];
@@ -399,30 +414,27 @@ export interface ChatSdk {
   send(message: string): Promise<string>;
   switchSession(sessionId?: string): Promise<string>;
   stream: (messages: AgentMessage[], onEvent: StreamHandler, signal?: AbortSignal) => Promise<string>;
-  /** 检视 agent 详细信息(tools/skills/dataSlots/middleware/todos) */
+  /** 检视 agent 详细信息(tools/skills/data/middleware/todos) */
   inspect(): AgentInfo;
-  /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 数据槽注册项 + vfs + todos);需开启 checkpoint,无可用返回 false */
+  /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 主数据 + vfs + todos);需开启 checkpoint,无可用返回 false */
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */
   listCheckpoints(): CheckpointMeta[];
   /** 运行时订阅 SDK 事件(可多个监听器,返回取消函数);与构造时 onEvent 互补 */
   hook(handler: SdkEventHandler): () => void;
-  /** 运行时动态新增/覆盖一个 数据槽注册项(懒加载组件:组件挂载时注册其 schema);立即对 数据槽工具生效,无需重建 agent。需开启 dataSlotOps */
-  addDataSlot(spec: DataSlotSpec): void;
-  /** 运行时移除一个 数据槽注册项(组件卸载);返回是否确实存在并移除。快照栈一并清理 */
-  removeDataSlot(path: string): boolean;
-  /** 列出当前所有已注册 数据槽(反映动态增删后的最新状态) */
-  listDataSlots(): DataSlotSpec[];
+  /** 运行时替换主数据配置(如页面切换、schema 变更);立即对数据工具生效,无需重建 agent。需开启 dataOps */
+  setData(config: DataConfig): void;
+  /** 读取当前主数据配置;dataOps 关闭时返回 undefined */
+  getData(): DataConfig | undefined;
   /** 乐观锁冲突挂起状态(响应式 ref;无冲突为 null,有冲突时 UI 据此渲染冲突对话框)。headless 集成方可 watch 自建 UI */
   pendingConflict: Ref<PendingConflict | null>;
   /** 冲突解决:用户点「保留外部」(keep_external)/「强制覆盖」(overwrite)/「回退」(restore) → 收口挂起的 conflict,被挂起的工具调用继续 */
   resolveConflict(action: ConflictResolution['action']): void;
 }
 
-/** 乐观锁冲突挂起(dataSlotOps 写入时 expectedHash 不匹配,挂起等用户决定) */
+/** 乐观锁冲突挂起(dataOps 写入时 expectedHash 不匹配,挂起等用户决定) */
 export interface PendingConflict {
   id: number;
-  path: string;
   op: 'set' | 'edit' | 'delete';
   agentValue?: unknown;
   currentValue: unknown;
@@ -438,9 +450,8 @@ export type ConflictResolution =
   | { action: 'overwrite' }
   | { action: 'restore' };
 
-/** 乐观锁冲突信息(dataSlotOps onConflict 回调参数) */
+/** 乐观锁冲突信息(dataOps onConflict 回调参数) */
 export interface ConflictInfo {
-  path: string;
   op: 'set' | 'edit' | 'delete';
   agentValue?: unknown;
   currentValue: unknown;
@@ -456,12 +467,13 @@ export declare function defineTool(opts: {
   schema: any;
   handler: (args: any) => unknown | Promise<unknown>;
 }): any;
-export declare function createDataSlotOps(props: DataSlotSpec[], opts?: DataSlotOpsOptions): any[];
-export declare function selectBuiltinTools(caps: { dataSlotOps?: boolean; fetch?: boolean } | undefined, dataSlotOps: any[], fetchDocs: any[]): any[];
-export declare function createUsageHintsMiddleware(caps: { planning?: boolean; dataSlotOps?: boolean; subagent?: boolean } | undefined, hasDataSlotOps: boolean): any;
+export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
+export declare function filterByToolMode(tools: any[], mode?: 'simple' | 'advanced' | 'minimal'): any[];
+export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean } | undefined, dataOps: any[], fetchDocs: any[]): any[];
+export declare function createUsageHintsMiddleware(caps: { planning?: boolean; dataOps?: boolean; subagent?: boolean } | undefined, hasDataOps: boolean, toolMode?: 'simple' | 'advanced' | 'minimal'): any;
 export declare const fetchDocTools: any[];
 export declare const fetchTools: any[];
-export declare function defineDataSlotToolset(props: DataSlotSpec[], opts?: DataSlotOpsOptions): any[];
+export declare function defineDataToolset(config: DataConfig, opts?: DataOpsOptions): any[];
 export declare function defineSkill(spec: SkillSpec): SkillSpec;
 export declare function createAgent(options: any): any;
 /** 检测模型把工具调用写成文本(伪 XML/标签)而非标准 tool_calls 的异常格式;主循环据此回灌 feedback 自纠 */
@@ -475,6 +487,8 @@ export declare const systemPromptHelpers: {
   /** 可靠写入规则:改前先读、动态先 list、字段以 describe 为准、写错看校验错误重试、优先增量 patch */
   readonly reliableWriteRules: string;
 };
+/** 从 zod schema 提取字段说明(io 契约注入 systemPrompt 用);非 object schema 用 description 兜底 */
+export declare function extractSchemaHint(schema: any): string;
 export declare function createSessionStore(config?: StorageConfig): SessionStore;
 export declare function createMemoryBackend(): StorageBackend;
 export declare function createWebStorageBackend(storage: Storage): StorageBackend;
@@ -560,10 +574,10 @@ export declare function createSubagentsMiddleware(opts: any): any;
 export interface SubagentOptions { [k: string]: any }
 export interface SubagentLlmConfig { [k: string]: any }
 
-// checkpoint / dataSlotOps / permissions
+// checkpoint / dataOps / permissions
 export interface CheckpointDeps { [k: string]: any }
-export interface DataSlotAuditEntry { [k: string]: any }
-export interface DataSlotSnapshotEntry { [k: string]: any }
+export interface DataAuditEntry { [k: string]: any }
+export interface DataSnapshotEntry { [k: string]: any }
 export type PermissionOp = string;
 
 // vfs