page-agent-sdk 2.0.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.0.0",
+  "version": "2.4.0",
   "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

@@ -152,11 +152,14 @@ export type ChatModelLike = {
 export interface DataSlotSpec {
   /** window 上的路径,支持点号嵌套 */
   path: string;
-  description: string;
-  /** 值的 zod schema(写入时校验) */
+  /** 属性说明,供 Agent 理解用途;若传了 bind 且未传 description,自动生成 `${path}(bind 直连)` */
+  description?: string;
+  /** 值的 zod schema(写入时校验);字段的 .describe() 自动提取注入 systemPrompt「可操作属性」段 */
   schema: any;
+  /** 可选:传 reactive/普通对象,自动挂 window[path] = bind(reactive 写后响应式刷新;普通对象可写但不响应) */
+  bind?: any;
 }
-/** createDataSlotOps 选项(审计回调 / 只读探测 / 快照上限 / 字段白名单读) */
+/** createDataSlotOps 选项(审计回调 / 只读探测 / 快照上限 / 字段白名单读 / 乐观锁) */
 export interface DataSlotOpsOptions {
   onAudit?: (entry: { op: string; path: string; value?: any; detail?: string; timestamp: number }) => void;
   allowRawRead?: boolean;
@@ -168,8 +171,29 @@ export interface DataSlotOpsOptions {
    * 设 false 回退原行为(允许读注册 path 的祖先,即整体读)。
    */
   whitelist?: boolean;
+  /** 乐观锁冲突人工介入回调(详见 ConflictInfo/ConflictResolution);不传则冲突时返回 VERSION_CONFLICT 错误 */
+  onConflict?: (conflict: ConflictInfo) => Promise<ConflictResolution>;
+  /**
+   * 自动乐观锁(默认 true):写入时若 LLM 未显式传 expectedHash,自动用「LLM 最后一次 get_data_slot 读到的 hash」作基准比对。
+   * LLM 无需手动传 expectedHash 即可享受乐观锁保护;冲突走 onConflict(无 onConflict 则返回 VERSION_CONFLICT)。
+   * LLM 未读过直接写(无基准记录)时跳过锁(等同不校验)。设 false 回退「不传 expectedHash = 不校验」的旧行为。
+   */
+  autoLock?: boolean;
+  /** 读写拦截器:read/write 透传给数据槽工具(脱敏/转换/审计/拒绝 LLM 读写) */
+  interceptors?: DataSlotInterceptors;
 }
 
+/** 数据槽读写拦截器(集成方可脱敏/转换/审计/拒绝 LLM 的读写) */
+export interface DataSlotInterceptors {
+  /** LLM 读时拦截:path + 原始值 → 改写后返回给 LLM(如脱敏/派生);抛错则返回 READ_INTERCEPT 错误 */
+  read?: (path: string, value: any) => any;
+  /** LLM 写时拦截:path + 欲写值 + 当前值 → 改写后的值,或 { error } 拒绝;抛错则拒绝 */
+  write?: (path: string, payload: any, current: any) => any | { error: string };
+}
+
+/** 工具呈现模式:simple=主推 read/write 但保留高级能力(默认)| advanced=全暴露| minimal=只 read/write */
+export type ToolMode = 'simple' | 'advanced' | 'minimal';
+
 /** 数据槽注册表控制器(运行时动态增删;createDataSlotOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
 export interface DataSlotOpsController {
   /** 新增/覆盖一个属性注册项(运行时懒加载组件场景);覆盖时旧快照栈保留 */
@@ -332,6 +356,19 @@ export interface ChatSdkOptions {
   vfs?: { initialFiles?: Record<string, string>; maxBytes?: number };
   /** 每个 数据槽最多保留快照数(默认 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?: (path: string, value: any) => any;
+    write?: (path: string, 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;
@@ -447,6 +484,7 @@ export declare function defineTool(opts: {
   handler: (args: any) => unknown | Promise<unknown>;
 }): any;
 export declare function createDataSlotOps(props: DataSlotSpec[], opts?: DataSlotOpsOptions): any[];
+export declare function filterByToolMode(tools: any[], mode?: 'simple' | 'advanced' | 'minimal'): 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 const fetchDocTools: any[];
@@ -465,6 +503,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;