page-agent-sdk 2.9.0 → 2.9.1

package/README.md

@@ -317,6 +317,8 @@ mv skills/page-agent-sdk-integrate ~/.claude/skills/
 
 After install, restart your AI tool; the skill auto-triggers when you ask things like "add page-agent-sdk to my page".
 
+> **Don't want to install the skill?** Copy the bundled generic integration prompt template to the target project's AI: see `node_modules/page-agent-sdk/skills/page-agent-sdk-integrate/references/integration-prompt.md` (fill in `[...]` per your scenario). For a specific scenario example, see the repo's `doc/集成提示词-Vue2-低代码页面-抽屉.md`.
+
 > A second skill `page-agent-sdk-release` (release workflow for maintainers) is kept in the repo's `.claude/skills/` for project maintainers only and is **not** distributed via the npm package.
 
 ## Architecture

package/README.zh-CN.md

@@ -262,6 +262,8 @@ mv skills/page-agent-sdk-integrate ~/.claude/skills/
 
 安装后重启 AI 工具；当你说「把 page-agent-sdk 加到我的页面」等时 skill 自动触发。
 
+> **不想装 skill?** 用随包附带的通用对接提示词模板复制给对接项目的 AI：见 `node_modules/page-agent-sdk/skills/page-agent-sdk-integrate/references/integration-prompt.md`（按场景填空 `[...]` 即可）。特定场景示例见仓库 `doc/集成提示词-Vue2-低代码页面-抽屉.md`。
+
 > 另有 `page-agent-sdk-release`（维护者发布工作流）skill 仅保留在仓库 `.claude/skills/` 供项目维护者自用，**不**通过 npm 包公开分发。
 
 ## 架构

package/package.json

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