page-agent-sdk 2.8.0 → 2.9.1

package/package.json

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

@@ -113,6 +113,7 @@ Detailed docs live in this skill's `references/` folder — load the one matchin
 - **[references/api.md](references/api.md)** — instance methods (`mount`/`send`/`stream`/`inspect`/`switchSession`/`hook`/`setData`/`getData`/checkpoints), `defineTool`/`defineSkill`/`presets`, built-in data 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 / dynamic schema via setData). 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 schema (`sdk.setData` to swap main data at runtime)**, custom `defineTool` (with error handling + coexisting with dataOps), `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 "swap data/schema at runtime".
+- **[references/integration-prompt.md](references/integration-prompt.md)** — a generic integration prompt template to copy into the target project's AI (Cursor / Claude Code) when the skill is NOT installed there. Fill in `[...]` per scenario. Read when the user asks "give me a prompt to integrate the SDK in another project" or wants a copy-paste prompt for a teammate's AI tool.
 
 Project-level docs (in the repo, not bundled in this skill):
 - `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference

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/integration-prompt.md

@@ -0,0 +1,177 @@
+# Integration prompt template (generic)
+
+Copy this prompt into the target project's Cursor / Claude Code so its AI integrates `page-agent-sdk` following the workflow. Fill in `[...]` per your scenario.
+
+> Recommended: install the skill in the target project first (`cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-integrate ~/.claude/skills/`) — the AI auto-integrates per workflow. Use this prompt only when the skill can't be installed.
+
+---
+
+## Your task
+
+Integrate `page-agent-sdk` (npm package) into the current project to enable "[business scenario: e.g. low-code page builder / form designer / ops config console / CMS batch ops / AI-native assistant...]". The integrator declares ONE main data object; an AI agent edits it via schema-validated tools `read`/`write` incrementally, with [UI form: built-in dialog / drawer mode / headless custom UI].
+
+## Background
+
+- `page-agent-sdk` is a **framework-agnostic JS SDK** (bundles Vue 3.5 internally, no conflict with host; works with Vue2/React/vanilla/Node)
+- Core model: integrator declares **one main data object** `data: { schema, bind, description? }`; the agent reads/writes `bind` via tools (schema validation + whitelist + optimistic lock + snapshot)
+- `bind` is any reactive/plain object; tools read/write it directly, **no `window` dependency**
+- `schema` is a zod schema; field `.describe()` text is auto-injected into the systemPrompt so the LLM knows each field's purpose — no manual field descriptions needed
+- Tools: `read` (read, supports jsonPath/fields/depth projection), `write` (write, merges set/edit/delete + auto optimistic lock + auto snapshot, supports patch jsonPath increments)
+- Full docs: load the `page-agent-sdk-integrate` skill (if installed), or see `node_modules/page-agent-sdk/skills/page-agent-sdk-integrate/`
+
+## Steps
+
+### 1. Install
+
+```bash
+npm i page-agent-sdk zod @langchain/openai @langchain/core
+```
+
+### 2. Declare the main data object + schema (key step)
+
+```ts
+// dataSchema.ts
+import { z } from 'page-agent-sdk'
+
+// [Define schema per business: field names/types/shapes; field .describe() auto-injects into systemPrompt]
+export const mainSchema = z.object({
+  title: z.string().describe('Page title'),
+  items: z.array(z.object({
+    id: z.string().describe('Item id'),
+    name: z.string().describe('Name'),
+    // ... other fields
+  })).describe('List items array'),
+})
+
+export type MainData = z.infer<typeof mainSchema>
+
+// [Optional] skill content: business field/component docs for Agent load_skill on demand (saves systemPrompt tokens)
+export const builderSkillContent = `# [Business name] Skill
+
+Main data = { title, items[] }.
+
+## Fields
+- title: page title
+- items[]: list items, each = { id, name, ... }
+
+## Edit rules
+- Add/remove items: edit items array (append/splice)
+- Prefer incremental patch for single-item edits (only changed fields), avoid re-sending the whole array
+- Validation failures return structured errors; fix per hint and retry
+- jsonPath locates relative to main data root (e.g. items.0.name)`
+```
+
+### 3. Integrate the SDK
+
+```ts
+import { createChatSdk, defineSkill } from 'page-agent-sdk'
+import 'page-agent-sdk/style.css'
+import { mainSchema, builderSkillContent } from './dataSchema'
+
+// [bind: use a reactive object (Vue3 reactive / Vue2 data() return / React useState or ref.current)]
+const mainData = { title: 'Initial title', items: [] }
+
+const sdk = createChatSdk({
+  container: '#agent-root',
+  id: '[stable id, e.g. page-builder]',           // multi-agent isolation + persistence namespace
+  storage: 'memory',
+  llm: {
+    apiKey: import.meta.env.VITE_AI_API_KEY || 'YOUR_API_KEY',
+    baseUrl: 'https://api.deepseek.com/v1',    // OpenAI-compatible protocol; DeepSeek by default
+    model: 'deepseek-chat',
+    temperature: 0.3,                          // low temp recommended for large JSON ops
+  },
+  // [UI form: built-in dialog (default) / drawer mode (drawer:true) / headless (ui:false)]
+  drawer: true,                                // drawer mode: right slide-in + mask; close defaults to hide() preserving history
+  // systemPrompt: describe business + data structure; reliableWriteRules auto-appended with '---' separator (default true)
+  systemPrompt: 'You are a [business] assistant. Main data = { title, items[] }. To edit, change title or items (add/remove/edit items, adjust fields); [page/UI] updates live. See load_skill("[skill-name]") for fields.',
+  appendReliableWriteRules: true,              // default true, auto-appends reliable write rules (read-before-write, fields per describe, retry on validation error, prefer incremental patch)
+  // data single main object: schema + bind directly bound to object
+  data: { schema: mainSchema, bind: mainData, description: '[main data purpose]' },
+  // skill: business field docs, Agent load_skill on demand
+  skills: [
+    defineSkill({
+      name: '[skill-name]',
+      description: 'Edit [business] data. Use when user requests changes',
+      getContent: () => builderSkillContent,
+    }),
+  ],
+  debug: true,
+  title: '[Business] Agent',
+  placeholder: 'Try: [example operation]',
+  // onEvent: for non-reactive bind or new-property cases, use data_change to trigger re-render
+  onEvent(e) {
+    if (e.type === 'data_change') {
+      // [non-reactive bind: tick++ to force re-render; reactive bind: not needed or use for audit/联动]
+    }
+  },
+}).mount()
+
+// Drawer mode: call show() to open (hide() to close, preserves history & in-flight generation)
+// sdk.show() / sdk.hide()
+```
+
+### 4. [Optional] Page render + refresh
+
+```ts
+// Reactive bind (Vue3 reactive / Vue2 data()): Agent write → auto-reactive, no manual refresh
+// Non-reactive bind (plain object): onEvent('data_change') triggers tick, :key="tick" forces component rebuild to read latest bind
+```
+
+## Options cheat sheet
+
+| Option | Value | Purpose |
+|---|---|---|
+| `drawer` | `true` | Drawer mode: right slide-in + mask; close defaults to `hide()` |
+| `ui` | `false` | headless: no dialog, use `sdk.messages` + `send`/`stream` to build your own UI |
+| `data` | `{ schema, bind, description? }` | Main data declaration (key); `bind` directly bound |
+| `systemPrompt` | string | Business description; `reliableWriteRules` auto-appended with `---` |
+| `appendReliableWriteRules` | `true` (default) | Auto-append reliable write rules; set `false` to disable |
+| `skills` | `defineSkill[]` | Business field docs, Agent `load_skill` on demand |
+| `storage` | `'memory'`/`'local'`/... | Persistence (messages/vfs/todos/memory; **does NOT persist bind**) |
+| `llm.temperature` | `0.3` | Low temp recommended for large JSON ops |
+| `onEvent` | `(e) => {}` | Event callback; `data_change` triggers re-render |
+| `checkpoint` | `true` | Session-level rollback (per-round snapshot; one-click restore if broken) |
+| `approval` | `{ tools: ['write'] }` | Human-confirm before write ops (prevent AI mis-edits) |
+| `capabilities` | `{ dataOps:false, fetch:false, ... }` | Turn off unused built-ins to save tokens/size |
+
+## Common pitfalls
+
+1. **bind not persisted**: `storage` persists messages/vfs/todos/memory but **NOT bind**; to restore across refresh, store it yourself + `sdk.setData({ bind: restoredBind })`
+2. **DeepSeek 400 `missing field tool_call_id`**: handled internally; only relevant for custom tool plumbing (use snake_case)
+3. **`.env` `VITE_AI_SYSTEM_PROMPT` must be single-line** (dotenv doesn't support multi-line)
+4. **Large JSON incremental edit**: use `write({ value:180, patch:{ op:'set', jsonPath:'items.0.price' } })` to avoid re-sending the whole blob (truncated by max_tokens)
+5. **Schema whitelist**: `z.object` auto-enables whitelist (only declared fields exposed); `discriminatedUnion`/`record`/`lazy` non-top-level don't enable (fully open)
+6. **Vue2 new-property non-reactive**: `write` patch `set` on a new field — Vue2 `Object.defineProperty` won't react → `onEvent('data_change')` `tick++`, use `:key="tick"` to force rebuild
+7. **MCP cold-start injects 0 tools**: `vite.config.ts` `optimizeDeps.include` pre-declares SDK sub-paths; keep those entries when forking config, else first MCP page load injects nothing (reload fixes)
+
+## Verification checklist
+
+- [ ] After `npm i`, `import { createChatSdk, z } from 'page-agent-sdk'` doesn't error
+- [ ] `import 'page-agent-sdk/style.css'` styles load
+- [ ] Agent `read` sees main data structure; `write` patch edits sub-path fields
+- [ ] [Reactive bind] edits → UI reacts; [non-reactive] `data_change` → re-render
+- [ ] [Drawer mode] close then open (`show()`) → history & in-flight generation preserved
+- [ ] Schema validation failure → structured error, no write
+
+## References
+
+- `node_modules/page-agent-sdk/skills/page-agent-sdk-integrate/` (integration skill, full docs)
+  - `references/quickstart.md` (progressive setup), `references/options.md` (all options), `references/api.md` (API/tools/events)
+  - `references/use-cases.md` (10 end-to-end scenarios: low-code/form/CMS/ops/AI-native/research/server-side/multi-agent/MCP/dynamic schema)
+  - `references/advanced.md` (custom tools/skills/subagents/MCP/dynamic schema)
+- `node_modules/page-agent-sdk/dist/` (build artifacts)
+- Online: `https://esm.sh/page-agent-sdk@2.9.0` (CDN verify)
+
+## Scenario customization
+
+Per your business scenario, fill in `systemPrompt` / `skills` / `data.schema`:
+
+- **Low-code page builder**: `data` = component tree; `write` patch jsonPath incremental; `onEvent('data_change')` refresh canvas; `checkpoint` + `approval`
+- **Form designer**: `data` = field definitions (enum/required); schema validation prevents malformed forms
+- **CMS batch ops**: `eval_script` loops; `search_data` filter; `write` patch targeted edits
+- **Ops config console**: `approval:{tools:['write']}` human-confirm; `capabilities.verify:true` write-back read; `checkpoint`
+- **AI-native assistant**: `capabilities:{dataOps:false,fetch:false}` + custom `tools` (your product API)
+- **Multi-agent on one page**: same `id` + `shareContext:true` → multiple dialogs share one `AgentCore`; or independent `id`s + `drawer:true` + `hide`/`show` for exclusive switching
+- **MCP integration**: `mcp:[{transport,url}]` remote tool servers; `@modelcontextprotocol/sdk` optional peerDep
+- **Dynamic/lazy-loaded schema**: `sdk.setData({ schema, bind })` on component mount to swap main data; tools pick up immediately, no rebuild

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>;