page-agent-sdk 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.8.0",
+  "version": "2.9.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/references/api.md

@@ -99,7 +99,7 @@ Default `toolMode:'simple'` exposes high-level `read`/`write` + advanced query/s
 | `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 **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).
+**Key rule**: `write`/`set`/`edit`/`delete` only affect **schema-declared** fields (ZodObject auto-whitelist; undeclared fields hidden/denied). Sub-path reads are recursively projected by the sub-schema at that location (e.g. `read components.0` hides child undeclared fields). `jsonPath` is segment-by-segment validated against schema. 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); `interceptors.write`-supplied invisible fields (not in schema) are written back to bind after schema+merge (not stripped).
 
 ### write / jsonPath edit operations
 

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

@@ -265,3 +265,34 @@ sdk.inspect().skills  // reflects runtime swap (reads controller.get())
 
 **何时用**:多阶段业务流程(各阶段 skill 文档不同)、运行时按权限/角色加载不同 skill、skill 文档热更新(vfs doc 内容变化需主动失效缓存)。skills 关闭(`capabilities.skills:false`)时 `setSkills`/`invalidateSkillCache` 输出 warn 并 no-op,不抛错。
 
+## 12. Multi-agent parallel + exclusive switch (drawer hide/show)
+
+Multiple independent agents on one page (each `createChatSdk` + distinct `id`, each its own `data`/history/tools), running their own generation tasks in parallel; exclusive chatbox switching via `drawer` + `hide()`/`show()` — `hide` the old (keeps agent/history/in-flight generation), `show` the new (history resumes), no unmount, no lost conversation.
+
+```ts
+const boxA = document.createElement('div'); document.body.appendChild(boxA)
+const boxB = document.createElement('div'); document.body.appendChild(boxB)
+const boxC = document.createElement('div'); document.body.appendChild(boxC)
+
+const agents = [
+  createChatSdk({ id: 'agent-page',  container: boxA, drawer: true, storage: 'memory', llm: LLM, data: { schema: pageSchema,  bind: pageObj  }, systemPrompt: '页面构建助手…' }),
+  createChatSdk({ id: 'agent-copy',  container: boxB, drawer: true, storage: 'memory', llm: LLM, data: { schema: copySchema,  bind: copyObj  }, systemPrompt: '文案优化助手…' }),
+  createChatSdk({ id: 'agent-stats', container: boxC, drawer: true, storage: 'memory', llm: LLM, data: { schema: statsSchema, bind: statsObj }, systemPrompt: '数据分析助手…' }),
+]
+await Promise.all(agents.map(a => a.mount()))  // three independent agents ready in parallel
+agents.slice(1).forEach(a => a.hide())         // show only the first initially
+
+let active = 0
+function switchTo(i: number) {
+  agents[active].hide(); active = i; agents[i].show()  // exclusive switch, each history preserved
+}
+```
+
+**要点**:
+- 不同 `id` 隔离:各自独立 agent 实例/历史/工具/storage,互不串扰
+- 各管各 `data` 对象无冲突;多 agent 操作同一 `data` 需协调(乐观锁 `expectedHash` 或按 `jsonPath` 分区)
+- `hide()` 不卸载 vueApp/不 release agent,保留聊天历史与正在进行的生成进程;`show()` 恢复可见
+- 切换按钮若在抽屉遮罩下,需提高 `z-index`(高于遮罩 `9998` + ChatDialog `9999`)确保可点
+
+完整示例:`examples/multi-agent-demo/`。
+

package/types/index.d.ts

@@ -432,6 +432,10 @@ export interface ChatSdkOptions {
   streaming?: boolean;
   title?: string;
   placeholder?: string;
+  /** Drawer mode: ChatDialog slides in from the right + mask + close button (replaces the collapse arrow); clicking mask/close triggers unmount (with exit animation). Default false (inline, fills container). */
+  drawer?: boolean;
+  /** Drawer mode close callback: called when mask/close button clicked (default calls unmount with exit animation). Pass this to sync external mount state. */
+  onClose?: () => void;
 }
 
 export interface ChatSdk {
@@ -439,6 +443,10 @@ export interface ChatSdk {
   /** 响应式消息数组(headless 模式自建 UI 读) */
   messages: AgentMessage[];
   unmount(): void;
+  /** 抽屉模式隐藏:加 cs-hidden class,不卸载 vueApp/不 release agent —— 保留聊天历史与正在进行的生成进程;再 mount() 直接 show 恢复 */
+  hide(): void;
+  /** 抽屉模式显示:移除 cs-hidden class 恢复可见(配合 hide 使用;首次挂载用 mount) */
+  show(): void;
   send(message: string): Promise<string>;
   switchSession(sessionId?: string): Promise<string>;
   stream: (messages: AgentMessage[], onEvent: StreamHandler, signal?: AbortSignal) => Promise<string>;