page-agent-sdk 1.1.1 → 1.1.3

package/README.md

@@ -257,26 +257,27 @@ CLAUDE.md                       # architecture + gotchas + coding conventions (a
 
 ## Skills for AI tools (for integrators)
 
-Two ready-to-use Agent Skills are bundled for integrators using Claude Code / Cursor (or any agent harness that loads `.claude/skills/` / `~/.claude/skills/`). They teach the AI how to use **this SDK** in your project:
+A ready-to-use Agent Skill is bundled for integrators using Claude Code / Cursor (or any agent harness that loads `.claude/skills/` / `~/.claude/skills/`). It teaches the AI how to use **this SDK** in your project:
 
 | Skill | When it triggers |
 |---|---|
 | `page-agent-sdk-integrate` | Embedding the SDK — choose install method, declare `windowProps` + zod schemas, configure the LLM, mount, subscribe to events (`onEvent` / `sdk.hook`), run headless, troubleshoot common pitfalls |
-| `page-agent-sdk-release` | Releasing a new version (bump → build → test → push gitee/github → npm publish → verify) — for maintainers |
 
 **Install** (pick one):
 
 ```bash
 # Option A — copy from the installed npm package
 npm i page-agent-sdk
-cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-* ~/.claude/skills/
+cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-integrate ~/.claude/skills/
 
 # Option B — download from the repo (no install needed)
-curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-*'
-mv skills/page-agent-sdk-* ~/.claude/skills/
+curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-integrate'
+mv skills/page-agent-sdk-integrate ~/.claude/skills/
 ```
 
-After install, restart your AI tool; the skills auto-trigger when you ask things like "add page-agent-sdk to my page" or "publish a new version".
+After install, restart your AI tool; the skill auto-triggers when you ask things like "add page-agent-sdk to my page".
+
+> 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

@@ -202,26 +202,27 @@ CLAUDE.md                       # 架构要点 + 约定坑 + 编码规范（agen
 
 ## 给 AI 工具使用者的 Skills（集成方安装）
 
-内置两个开箱即用的 Agent Skill，供使用 Claude Code / Cursor（或任何加载 `.claude/skills/` / `~/.claude/skills/` 的 agent 工具）的集成方使用。它们教 AI 如何在**你的项目**中使用本 SDK：
+内置一个开箱即用的 Agent Skill，供使用 Claude Code / Cursor（或任何加载 `.claude/skills/` / `~/.claude/skills/` 的 agent 工具）的集成方使用。它教 AI 如何在**你的项目**中使用本 SDK：
 
 | Skill | 触发场景 |
 |---|---|
 | `page-agent-sdk-integrate` | 集成 SDK —— 选引入方式、声明 `windowProps` + zod schema、配 LLM、挂载、订阅事件（`onEvent` / `sdk.hook`）、跑 headless、排查常见坑 |
-| `page-agent-sdk-release` | 发布新版本（bump → 构建 → 测试 → 推 gitee/github → 发 npm → 验证）—— 面向维护者 |
 
 **安装**（任选其一）：
 
 ```bash
 # 方式 A —— 从已安装的 npm 包复制
 npm i page-agent-sdk
-cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-* ~/.claude/skills/
+cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-integrate ~/.claude/skills/
 
 # 方式 B —— 从仓库下载（无需安装）
-curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-*'
-mv skills/page-agent-sdk-* ~/.claude/skills/
+curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-integrate'
+mv skills/page-agent-sdk-integrate ~/.claude/skills/
 ```
 
-安装后重启 AI 工具；当你说「把 page-agent-sdk 加到我的页面」「发布新版本」等时 skill 自动触发。
+安装后重启 AI 工具；当你说「把 page-agent-sdk 加到我的页面」等时 skill 自动触发。
+
+> 另有 `page-agent-sdk-release`（维护者发布工作流）skill 仅保留在仓库 `.claude/skills/` 供项目维护者自用，**不**通过 npm 包公开分发。
 
 ## 架构
 

package/package.json

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

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

@@ -79,7 +79,15 @@ Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_resul
 
 ## References (read as needed)
 
-- `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference (onEvent/hook/server-side/checkpoint/approval/verify/subagent/MCP)
+Detailed docs live in this skill's `references/` folder — load the one matching the user's question:
+
+- **[references/quickstart.md](references/quickstart.md)** — progressive setup from 5-line CDN to full-featured (Stages 0→6). Read when the user wants a step-by-step "from simple to complete" walkthrough.
+- **[references/options.md](references/options.md)** — every `createChatSdk` option: type, default, purpose & when to use. Read when the user asks "what does option X do" or needs to tune behavior.
+- **[references/api.md](references/api.md)** — instance methods (`mount`/`send`/`stream`/`inspect`/`switchSession`/`hook`/checkpoints), `defineTool`/`defineSkill`/`presets`, built-in window 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)** — 9 end-to-end scenarios (low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP). Read when the user wants a concrete pattern for their use case.
+
+Project-level docs (in the repo, not bundled in this skill):
+- `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference
 - `examples/<demo>/` — runnable demos (page-demo, nested-demo, subagent-demo, mcp-demo, planner-demo, toolsets-demo, human-confirm-demo)
 - `demo/plain.html` — framework-agnostic CDN integration
 - `CLAUDE.md` — internal dev guide (architecture, conventions)

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

@@ -0,0 +1,119 @@
+# API reference — instance methods, tool/skill definition, window tools, events
+
+## ChatSdk instance (`createChatSdk(...)` return)
+
+| Method / field | Signature | Purpose |
+|---|---|---|
+| `mount()` | `() => Promise<void>` | Initialize & render. Await before `send` in headless. |
+| `unmount()` | `() => void` | Tear down UI, listeners, flush storage. |
+| `messages` | `AgentMessage[]` (reactive) | The conversation. Headless reads this to render. UI shares the same array (single source). |
+| `send(message)` | `(msg: string) => Promise<string>` | Send a user message (invoke mode, no stream events). Returns final content. |
+| `stream` | `(messages, onEvent, signal?) => Promise<string>` | Low-level stream. UI uses this internally; headless can call directly for streaming. |
+| `inspect()` | `() => AgentInfo` | Inspect agent: tools/skills/windowProps/middleware/todos/mcp.servers (each tool's `source`: `builtin`/`mcp:<name>`/`user`). DebugDrawer uses this. |
+| `switchSession(id?)` | `(id?: string) => Promise<string>` | Switch session context (load or create by id). Requires `storage` enabled. |
+| `hook(handler)` | `(h: SdkEventHandler) => () => void` | Runtime event subscription (multi-listener, returns unsubscribe). Complements `onEvent`. |
+| `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
+| `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
+
+## defineTool (custom tools)
+
+```ts
+import { defineTool, z } from 'page-agent-sdk'
+
+const addTool = defineTool({
+  name: 'add',
+  description: 'Add two numbers',
+  schema: z.object({ a: z.number(), b: z.number() }),
+  handler: async ({ a, b }) => `sum: ${a + b}`,
+})
+
+createChatSdk({ tools: [addTool], /* llm, ... */ }).mount()
+```
+
+`handler` receives validated args; return a string (or structured result stringified). Errors via `toolError({ path, code, message })`.
+
+## defineSkill (progressive disclosure)
+
+```ts
+import { defineSkill } from 'page-agent-sdk'
+
+const apiSkill = defineSkill({
+  name: 'api-design',
+  description: 'REST API design conventions for this project',
+  prompt: 'Use kebab-case URLs; version under /v1; ...',
+})
+
+createChatSdk({ skills: [apiSkill], /* ... */ }).mount()
+```
+
+Skills are loaded on demand by the agent (not always in context) — saves tokens.
+
+## presets (scenario bundles)
+
+```ts
+import { createChatSdk, presets } from 'page-agent-sdk'
+
+createChatSdk({ ...presets.pageBuilder, llm, container }).mount()
+// or presets.researcher / presets.minimal
+```
+
+Spread into options for common scenarios.
+
+## Built-in window tools (auto-injected when `capabilities.windowOps`)
+
+| Tool | Purpose |
+|---|---|
+| `list_window_props` | List declared paths + descriptions |
+| `describe_window_prop` | Show a path's schema |
+| `get_window_prop` | Read a path (or ancestor/descendant sub-paths of registered props) |
+| `get_window_paths` | Batch-read multiple paths |
+| `set_window_prop` | Write a whole path (schema-validated, scoped to registry) |
+| `edit_window_prop` | Patch by `jsonPath` (set/remove/merge/append) — avoids re-sending large JSON |
+| `delete_window_prop` | Delete a path |
+| `snapshot_window_prop` | Manual snapshot |
+| `list_window_snapshots` | List snapshots |
+| `restore_window_snapshot` | Restore (no id = most recent) |
+| `query_window_prop` / `search_window_prop` | JSONPath query / full-text search |
+| `eval_window_script` | Sandboxed script on data (for batch ops) |
+
+**Key rule**: `set`/`edit`/`delete` only affect **declared** `windowProps` paths. Invalid schema → structured error, no write. `edit` writes in-place (preserves Vue reactive refs).
+
+### jsonPath edit operations
+
+`edit_window_prop({ path, jsonPath, op, value })`:
+- `set` — set a sub-path
+- `remove` — remove a sub-path / array element
+- `merge` — shallow-merge an object
+- `append` — append to an array
+
+Example: `edit_window_prop({ path: 'app.items', jsonPath: '0.price', op: 'set', value: 9.9 })` — precise local edit, no full re-send.
+
+## Built-in fetch tools (`capabilities.fetch`)
+
+`fetch_document` — GET a URL, return cleaned text (HTML→markdown, truncated, offloaded to vfs if large).
+
+## SdkEvent types (for `onEvent` / `sdk.hook`)
+
+| `type` | Payload | When |
+|---|---|---|
+| `round_start` | `round` | Each agent round begins |
+| `reasoning` | `delta` | Reasoning token (models that emit it) |
+| `text` | `delta` | Streamed text delta (stream mode only) |
+| `tool_call` | `name, args` | A tool is invoked |
+| `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 |
+| `window_prop_change` | `path, operation, value?` | A window prop was written (`operation`: `set`/`edit`/`delete`/`restore`) |
+| `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).
+
+## Exported building blocks (for custom UIs)
+
+- `ChatDialog`, `MessageContent`, `CodePreview` — Vue components
+- `useChat(opts)` — composable (streaming/retry/stop/regenerate logic)
+- `createAgent(options)` — the raw harness (if you bypass `createChatSdk`)
+- Middleware factories: `createApprovalMiddleware`, `createVerifyMiddleware`, `createWriteBackCheck`, `createSubagentMiddleware`, `createCheckpointMiddleware`, `createUsageHintsMiddleware`
+- Storage: `createSessionStore`, `createMemoryBackend`, `createWebStorageBackend`, `isQuotaError`
+- JSON helpers: `jpEval`, `searchJson`, `runSandboxedScript`, `toolError`, `zodError`

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

@@ -0,0 +1,124 @@
+# createChatSdk options — what each does & when to use
+
+Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`. Everything else is optional with sane defaults.
+
+## LLM & identity
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `llm` | `LLMConfig \| BaseChatModel` | — (required) | The model. `LLMConfig = { apiKey, baseUrl, model, temperature?, maxTokens? }` (OpenAI-compatible; DeepSeek default). Or pass any LangChain `BaseChatModel` (e.g. `ChatAnthropic`, install its peerDep). |
+| `systemPrompt` | `string` | generic page assistant | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). |
+| `id` | `string` | random + warn | Stable agent id for multi-agent isolation & persistence. **Must pass a stable value** if you use `storage` or run multiple agents on one page. |
+| `title` / `placeholder` | `string` | — | Dialog title / input placeholder (cosmetic). |
+
+## UI & mounting
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `container` | `string \| HTMLElement` | — | Where the built-in dialog mounts. Required when `ui !== false`. |
+| `ui` | `boolean \| 'default'` | `true` | `false` = headless (no built-in dialog; you build UI from `sdk.messages` + `sdk.send`). `'default'` = built-in `ChatDialog`. |
+| `streaming` | `boolean` | `true` | Stream tokens live. `false` = wait for full reply. Headless `sdk.send` always uses invoke (no stream events, but window/message/error still fire). |
+
+## window operation (the core)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `windowProps` | `WindowPropSpec[]` | `[]` | Declare writable `window` paths + zod schemas. The agent can ONLY touch declared paths; `set`/`edit` are schema-validated. **This is the key integration step.** |
+| `maxSnapshots` | `number` | 20 | Per-path snapshot stack depth for `restore_window_snapshot`. |
+| `permissions` | `PermissionRule[]` | off | Scope whitelist (first-match-wins) for fine-grained per-path/tool rules. Default off (all declared paths writable). |
+
+`WindowPropSpec = { path: string; description: string; schema?: z.ZodType }`. `description` is shown to the AI — write it clearly so the agent knows what each path means.
+
+## Tools, skills, memory
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `tools` | `Tool[]` | `[]` | Custom tools beyond built-ins. Use `defineTool({ name, description, schema, handler })`. |
+| `skills` | `SkillSpec[]` | `[]` | Progressive-disclosure skills (`defineSkill({ name, description, prompt }`) loaded on demand by the agent. |
+| `memory` | `string` | — | AGENTS.md-style persistent instructions injected into every prompt (project conventions, hard rules). |
+| `middleware` | `Middleware[]` | `[]` | Custom middleware appended after built-ins. 8 hooks: `beforeAgent`/`wrapModelCall`/`beforeModel`/`afterModel`/`wrapToolCall`/`afterAgent`/`beforeReturn` + `augmentPrompt`/`compressInput`/`tools`. For interception, instrumentation, prompt enhancement. |
+
+## Capabilities (turn built-ins on/off)
+
+`capabilities: { ... }` — default all `true` except `verify`. Set `false` to drop unused built-ins (saves tokens/size).
+
+| Flag | Off when... |
+|---|---|
+| `windowOps` | Pure research agent, no page edits (also drops window tools from subagents). |
+| `fetch` | No web fetching needed. ⚠️ turning off `windowOps` also strips subagent window tools. |
+| `planning` | Don't want `write_todos` planning. |
+| `skills` | Don't want progressive skill loading. |
+| `vfs` | No in-memory workspace; ⚠️ large tool results then truncate instead of offloading. |
+| `summarization` | No context compression; ⚠️ long sessions grow unbounded. |
+| `memory` | No persistent instructions. |
+| `subagent` | No `spawn_agent`/`spawn_agents` delegation. |
+| `verify` (reverse) | **Off by default**; `true` enables write-back self-check before the agent returns (costs tokens). |
+
+## Robustness & limits
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `maxRetries` | `number` | 2 | Model call retries on network/429/5xx (exponential backoff). 4xx & abort don't retry. |
+| `maxParallelTools` | `number` | 1 | Same-round tool concurrency. `>1` is faster but watch stateful middleware (todos counts). |
+| `maxToolRounds` | `number` | — | Cap agent tool rounds (safety against loops). |
+| `maxMemoryRounds` | `number` | 50 | In-memory dialog rounds cap; oldest compressed to a summary system message (OOM guard). `0` disables. |
+| `contextWindow` / `maxOutputTokens` | `number` | by model name | Override model context/output token limits (affects offload threshold & compression trigger). |
+| `debug` | `boolean` | `false` | Verbose logging / DebugDrawer. |
+
+## Context compression
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `contextPreset` | `'auto'\|'conservative'\|'aggressive'` | `auto` | `conservative` = save cost; `aggressive` = save context. `contextOptions` fine-tunes further. |
+| `contextOptions` | `object` | — | Detailed compression params (overrides preset). `false` disables compression. |
+| `summaryLlm` | `BaseChatModel \| LLMConfig` | main `llm` | Use a cheaper/faster model for summarization. |
+| `summaryTemperature` | `number` | 0.3 | Summary model temperature. |
+| `summaryMaxTokens` | `number` | 1024 | Summary output cap. |
+| `summaryTimeoutMs` | `number` | 15000 | On timeout, fall back to index-based summary (no failure). |
+
+## Subagent (delegation)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `subagent` | `object` | enabled | `{ enabled?, allowedTools?, systemPrompt?, temperature?, maxTokens?, skills?, llm?, maxDepth?, maxParallel? }`. `maxDepth` (1) physically cuts recursion. Subagents get a read-only tool subset (no spawn). |
+| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. |
+
+## Verify (self-check before return)
+
+`capabilities.verify: true` enables. `verify: { check?, maxAttempts?, adversarial? }`:
+- `check` omitted → default `createWriteBackCheck()` (scans all writes, reads back + schema-validates; skips legitimately-rejected writes).
+- custom `check: async ({ messages, state }) => ({ ok, feedback? })` — return **actionable** feedback.
+- `adversarial: true` → after check passes, spawn a read-only "refuter" subagent (costs extra rounds; for semantically complex cases).
+- `maxAttempts` (default 2) caps self-correction loops.
+
+## Approval (human-in-the-loop)
+
+`approval: { tools?, confirm?, ... }` — human confirms before tool execution. Default off; passing `approval` enables. Headless integrators listen for `approval_request` (NOT forwarded via `onEvent`/`hook`) to build their own confirm UI.
+
+## Checkpoint (session rollback)
+
+`checkpoint: true \| { maxCheckpoints?, auto? }` — per-round snapshot of (messages + window props + vfs + todos). `restoreLastCheckpoint()` / LLM tool `restore_last_checkpoint` / UI button. Distinct from windowOps per-path snapshots (checkpoint = whole-session rollback).
+
+## Persistence (storage)
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `storage` | `'indexed'\|'session'\|'local'\|'memory'\| StorageConfig \| false` | `false` (off) | Off by default; assign to enable. Persists messages/vfs/todos/memory (NOT window snapshots). Auto-degrades to memory if backend unavailable (private mode / quota). |
+| `session` | `SessionOptions` | — | Session control (resume by id, etc.). |
+| `shareContext` | `boolean` | `false` | `true` → multiple `createChatSdk` with same `id` share one `AgentCore` (same agent, multiple dialog views on a page). |
+
+## MCP (external tools)
+
+`mcp: [{ transport: 'http'\|'sse'\|'websocket', url, name?, requestInit? }]` — connect remote MCP servers, dynamically inject their tools (`Promise.allSettled` fault-isolated). Browser only supports remote transports (no stdio). `@modelcontextprotocol/sdk` is an optional peerDep, dynamically imported only when used.
+
+## Events
+
+| Option | Type | Default | Purpose / when |
+|---|---|---|---|
+| `onEvent` | `(e: SdkEvent) => void` | — | Constructor-time event subscription (single). Replaces polling for host-page reactivity. See [api.md](api.md) for event types. |
+
+Runtime subscription via `sdk.hook(handler) => () => void` (multi-listener, cancellable) — see [api.md](api.md).
+
+## vfs (in-memory workspace)
+
+`vfs: { initialFiles?, maxBytes? }` — `maxBytes` default 4MB; LRU-evicts oldest files on overflow. Tool results > 6000 chars auto-offload to vfs (only preview + `vfs_read`/`vfs_grep` reference kept). Disabling `capabilities.vfs` degrades to truncation.

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

@@ -0,0 +1,122 @@
+# Quickstart (progressive)
+
+From the smallest working setup to a full-featured integration. Read top-down; stop wherever your needs are met.
+
+## Stage 0 — Prerequisites
+
+- An OpenAI-compatible LLM endpoint (DeepSeek works out of the box). Get an API key.
+- Page data you want the AI to edit, placed on `window` (e.g. `window.app = { ... }`).
+
+## Stage 1 — Minimal (5 lines, CDN, no build)
+
+Drop into any HTML page. The built-in dialog mounts itself.
+
+```html
+<div id="root"></div>
+<script src="https://unpkg.com/page-agent-sdk"></script>
+<script>
+  window.app = { title: 'Hello', theme: 'light' }
+  ChatSdk.createChatSdk({
+    container: '#root',
+    llm: { apiKey: 'sk-...', baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
+    systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
+    windowProps: [
+      { path: 'app.title', description: '标题', schema: ChatSdk.z.string() },
+      { path: 'app.theme', description: '主题', schema: ChatSdk.z.enum(['light','dark']) },
+    ],
+  }).mount()
+</script>
+```
+
+Talk to it: "change theme to dark" → AI calls `set_window_prop` → `window.app.theme === 'dark'`.
+
+## Stage 2 — npm + module project
+
+```bash
+npm i page-agent-sdk zod @langchain/openai @langchain/core
+```
+
+```ts
+import { createChatSdk, z } from 'page-agent-sdk'
+import 'page-agent-sdk/style.css'
+
+window.app = { title: 'Hello', theme: 'light', items: [] }
+
+const sdk = createChatSdk({
+  container: '#root',
+  llm: { apiKey: import.meta.env.VITE_AI_API_KEY, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
+  systemPrompt: 'You are a page assistant. Read/write window.app via tools.',
+  windowProps: [
+    { path: 'app.title',  description: '标题',   schema: z.string() },
+    { path: 'app.theme',  description: '主题',   schema: z.enum(['light','dark']) },
+    { path: 'app.items',  description: '列表项', schema: z.array(z.object({ name: z.string(), price: z.number() })) },
+  ],
+}).mount()
+```
+
+## Stage 3 — React to changes (replace polling)
+
+Subscribe via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable):
+
+```ts
+const sdk = createChatSdk({
+  onEvent(e) {
+    if (e.type === 'window_prop_change') renderUI()       // host page reactive refresh
+    if (e.type === 'error') console.error(e.message)
+  },
+  // ...llm, windowProps...
+}).mount()
+
+// runtime listener (e.g. analytics), cancellable
+const off = sdk.hook((e) => { if (e.type === 'tool_call') track(e.name) })
+// off()
+```
+
+## Stage 4 — Headless (custom UI, framework-agnostic)
+
+No built-in dialog; drive the reactive `messages` array yourself.
+
+```ts
+const sdk = createChatSdk({
+  ui: false,                                  // headless
+  llm: { ... }, systemPrompt: '...', windowProps: [...],
+}).mount()
+
+// your own UI reads sdk.messages (reactive) and calls sdk.send
+await sdk.send('add a new item: name=Pen, price=3')
+```
+
+Reusable `ChatDialog` / `MessageContent` / `CodePreview` components + `useChat` composable are also exported if you want to assemble a custom UI from existing parts.
+
+## Stage 5 — Tune capabilities & safety
+
+```ts
+createChatSdk({
+  // ...llm, windowProps...
+  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_window_prop', 'edit_window_prop'] },  // 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
+}).mount()
+```
+
+## Stage 6 — Persist across refresh / multi-session
+
+```ts
+createChatSdk({
+  id: 'my-page-agent',          // STABLE id (multi-agent isolation); omit = random + warn
+  storage: 'indexed',           // persist messages/vfs/todos/memory to IndexedDB
+  // ...llm, windowProps...
+}).mount()
+
+// later, switch session:
+await sdk.switchSession('session-abc')   // load or create
+```
+
+## Next
+
+- All options: see [options.md](options.md)
+- Instance API + tool/skill definition: see [api.md](api.md)
+- End-to-end scenarios: see [use-cases.md](use-cases.md)

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

@@ -0,0 +1,200 @@
+# Use cases — end-to-end scenarios
+
+Concrete integration patterns for common scenarios. Each shows the key `windowProps` + options that matter. Adapt the LLM config to your provider.
+
+## 1. Low-code page builder
+
+A visual builder where the page is a component tree; the AI edits the tree via jsonPath patches and the canvas re-renders live.
+
+```ts
+window.page = {
+  components: [
+    { id: 'banner', type: 'banner', props: { title: 'Welcome', bg: '#1f4d3a' } },
+    { id: 'card1', type: 'card', props: { title: '新品', price: 99 } },
+  ],
+}
+
+createChatSdk({
+  container: '#chat',
+  llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat', temperature: 0.3 },
+  systemPrompt: '你是页面搭建助手。用 edit_window_prop 按 jsonPath 增量改 components,不要重传整树。',
+  windowProps: [
+    { path: 'page.components', description: '组件树',
+      schema: z.array(z.object({
+        id: z.string(), type: z.string(),
+        props: z.record(z.any()),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderCanvas() },  // canvas reactive refresh
+  checkpoint: true,                       // bad edit → one-click rollback
+  approval: { tools: ['set_window_prop', 'edit_window_prop'] },  // confirm writes
+}).mount()
+```
+
+User: "顶部 Banner 改深色、主标题加粗、加一张新品卡" → AI calls `edit_window_prop` per component.
+
+## 2. Form designer
+
+Form schema as data; AI edits field definitions, schema validation prevents malformed forms.
+
+```ts
+window.form = {
+  fields: [
+    { name: 'phone', label: '手机号', type: 'text', required: true, validation: 'none' },
+    { name: 'address', label: '地址', type: 'text', required: false, cascade: false },
+  ],
+}
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是表单设计助手。改 form.fields 的字段定义,保持 schema 合法。',
+  windowProps: [
+    { path: 'form.fields', description: '字段定义数组',
+      schema: z.array(z.object({
+        name: z.string(), label: z.string(),
+        type: z.enum(['text','number','select','date']),
+        required: z.boolean(),
+        validation: z.enum(['none','phone','email','idcard']),
+        cascade: z.boolean().optional(),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderForm() },
+}).mount()
+```
+
+User: "手机号加格式校验、地址改三级联动" → AI patches `form.fields[0].validation='phone'`, `form.fields[1].cascade=true`.
+
+## 3. CMS batch operation
+
+Bulk-edit a product list; use `eval_window_script` or `search_window_prop` + `edit_window_prop` for batch ops.
+
+```ts
+window.products = [
+  { id: 1, title: '商品A', price: 99, highlight: false },
+  { id: 2, title: '商品B', price: 150, highlight: false },
+  // ...hundreds
+]
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是运营助手。批量改 products;标题加前缀用 eval_window_script,按条件筛选用 search_window_prop。',
+  windowProps: [
+    { path: 'products', description: '商品列表',
+      schema: z.array(z.object({
+        id: z.number(), title: z.string(), price: z.number(), highlight: z.boolean(),
+      })) },
+  ],
+  onEvent(e) { if (e.type === 'window_prop_change') renderTable() },
+}).mount()
+```
+
+User: "标题加『限时』前缀、低于 100 元的标红" → AI uses `eval_window_script` for the prefix loop + `search_window_prop` to find `<100` then `edit_window_prop` to set `highlight`.
+
+## 4. Ops config console
+
+Edit experiment thresholds / feature flags with human confirmation.
+
+```ts
+window.config = {
+  expA: { threshold: 0.5, enabled: true },
+  featureB: { enabled: false },
+}
+
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是运维助手。改 config 前必须经用户确认。',
+  windowProps: [
+    { path: 'config.expA', description: '实验A',
+      schema: z.object({ threshold: z.number().min(0).max(1), enabled: z.boolean() }) },
+    { path: 'config.featureB', description: 'B开关',
+      schema: z.object({ enabled: z.boolean() }) },
+  ],
+  approval: { tools: ['set_window_prop', 'edit_window_prop'] },  // human-in-the-loop
+  checkpoint: true,
+  capabilities: { verify: true },           // write-back read + schema check
+}).mount()
+```
+
+User: "A 实验阈值调到 30%、关掉 B 开关" → AI proposes writes → user confirms → verify reads back.
+
+## 5. AI-native assistant (no page data, custom tools)
+
+The agent drives your product's own API via custom tools (no windowOps).
+
+```ts
+const lookupTool = defineTool({
+  name: 'lookup_order',
+  description: '查询订单',
+  schema: z.object({ orderId: z.string() }),
+  handler: async ({ orderId }) => JSON.stringify(await api.getOrder(orderId)),
+})
+
+createChatSdk({
+  container: '#chat',
+  llm: { ... },
+  systemPrompt: '你是订单助手。用 lookup_order 查询。',
+  tools: [lookupTool],
+  capabilities: { windowOps: false, fetch: false },   // pure custom-tool agent
+}).mount()
+```
+
+## 6. Research agent (fetch + subagents, no writes)
+
+Pure research: fetch docs, parallel subagents for multi-source investigation.
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是调研助手。多源对比用 spawn_agents 并行委派。',
+  capabilities: { windowOps: false },       // read-only, no page edits
+  subagent: { allowedTools: ['fetch_document'] },
+  contextPreset: 'conservative',             // long research sessions
+}).mount()
+```
+
+## 7. Headless server-side (Node.js)
+
+Run the agent in Node (no browser). Provide `globalThis.window` only if you enable windowOps.
+
+```ts
+// node mjs
+import { createChatSdk, z } from 'page-agent-sdk'
+
+const sdk = createChatSdk({
+  ui: false,
+  storage: 'memory',
+  llm: { apiKey, baseUrl, model },
+  systemPrompt: '...',
+  capabilities: { windowOps: false, fetch: false },
+  tools: [/* your tools */],
+})
+await sdk.mount()
+const reply = await sdk.send('do something')
+console.log(reply)
+sdk.unmount()
+```
+
+## 8. Multi-agent on one page (shared context)
+
+Two dialogs backed by one agent brain.
+
+```ts
+const a = createChatSdk({ id: 'shared', container: '#dlg-a', llm: {...}, shareContext: true, windowProps }).mount()
+const b = createChatSdk({ id: 'shared', container: '#dlg-b', llm: {...}, shareContext: true, windowProps }).mount()
+// a & b share messages/agent/vfs/todos/memory — two views of one agent
+```
+
+## 9. MCP integration (external tool servers)
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  mcp: [
+    { transport: 'http', url: 'https://my-mcp-server/mcp' },
+    { transport: 'sse',  url: 'https://another/sse' },
+  ],
+  // MCP tools auto-injected; fault-isolated (one server down doesn't break others)
+}).mount()
+```
+
+> Note: `@modelcontextprotocol/sdk` is an optional peerDep — install it only if you use `mcp`. Browser supports only remote transports (http/sse/websocket), not stdio.

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

@@ -1,44 +0,0 @@
----
-name: page-agent-sdk-release
-description: Release a new version of the page-agent-sdk npm package and push to its two git remotes (Gitee + GitHub). Use when the user wants to publish/ship a new version, bump the version, build + test before release, push to gitee/github, or follow the project's release checklist. Covers the full flow: code changes → sync zh/en docs → bump semver → build + self-test → commit → push Gitee → push GitHub → npm publish → verify.
----
-
-# Release page-agent-sdk
-
-Execute the project's release checklist end-to-end. The authoritative, detailed checklist lives in `CLAUDE.md` → "发布流程 checklist"; read that section first, then follow the steps below.
-
-## Two remotes (do NOT mix them up)
-
-| remote | URL | role |
-|---|---|---|
-| `origin` | gitee.com/whyymj/**chat-agent**.git | daily storage, keeps all granular commits |
-| `github` | github.com/whyymj/**chat-sdk**.git | official open-source, receives curated commits |
-
-Personal notes (`doc/待确认问题.md`) are gitignored — Gitee only, never GitHub.
-
-## Release checklist (in order)
-
-1. **Code**: edit `src/`, sync `types/index.d.ts` (hand-maintained), update exports in `src/core/index.ts`.
-2. **Docs (sync zh + en, never single-side)**:
-   - `README.md` (en) / `README.zh-CN.md` (zh) — features, usage, scenarios
-   - `doc/README.md` (zh) / `doc/README.en.md` (en) — doc index
-   - `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` (en) — usage guide
-   - `CLAUDE.md` — internal dev guide/architecture
-   - Keep language toggle links bidirectional.
-3. **Bump version**: `npm version patch|minor|major --no-git-tag-version` (semver: minor for new API, major for breaking, patch for fix). Never republish the same version.
-4. **Build + self-test**: `npm run build` (= `build:lib` + `build:iife`) then `npm test` (341 assertions must pass). Run `npm pack --dry-run` to confirm the tarball excludes `.env` / `src` / `examples` / notes.
-5. **Commit**: `git add -A && git commit -m "feat/fix/docs: ..."` (conventional style).
-6. **Push Gitee** (daily storage): `git push origin master`. If you just rebased and rewrote history → `git push --force-with-lease origin master` (personal repo, safe).
-7. **Push GitHub** (official): `git push github master`. If rejected as `non-fast-forward` → `git fetch github master && git pull --rebase github master` then push again.
-8. **Publish to npm**: `npm publish` (`publishConfig.registry` is locked to the official npm registry, unaffected by the machine's default private registry).
-9. **Verify**: `npm view page-agent-sdk version` (confirm latest) + a temp dir `npm i page-agent-sdk` to confirm it installs + imports.
-
-## npm credentials gotchas
-
-- Account `whyymj` has 2FA enabled. Use an **Automation Access Token** (npmjs.com → Access Tokens → Classic → Automation, bypasses OTP); write to user-level `~/.npmrc` via `npm config set //registry.npmjs.org/:_authToken <token> --location=user`. Revoke after use. Never commit tokens or store them in the project dir.
-- `npm login` / `npm whoami` require `--registry=https://registry.npmjs.org/` (machine default may be a private registry).
-
-## References
-
-- `CLAUDE.md` → "发布流程 checklist" / "双远程仓库与发布约定" / "npm 发布约定" — authoritative details.
-- `package.json` → `publishConfig`, `exports`, `files`, `peerDependencies`.