page-agent-sdk 2.9.0 → 2.10.0

package/package.json

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

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

@@ -21,6 +21,10 @@
 | `usage` | `TokenUsage` | Cumulative token usage `{prompt_tokens, completion_tokens, total_tokens}` (accumulated per LLM call). |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
+| `addSkill(skill)` | `(skill: { name, description, prompt \| getContent \| doc }) => void` | Add a user-created skill at runtime. Auto-merges into the skill list, persists via **independent SkillStore** (default indexedDB, separate from `storage` option), takes effect next round. Same-name overwrites. Requires `capabilities.skills` (default on) + `skillStorage` not `false` for persistence. |
+| `removeSkill(name)` | `(name: string) => void` | Remove a user-created skill by name (only user-created, not init-time skills). Removes from SkillStore. No-op if not found. |
+| `listUserSkills()` | `() => string[]` | List names of user-created skills (not init-time skills). Useful for UI panels. |
+| `getUserSkill(name)` | `(name: string) => { name, description, content } \| undefined` | Read a user-created skill's detail (for SkillPanel edit). Returns `undefined` if not found. |
 
 ## defineTool (custom tools)
 

package/skills/page-agent-sdk-integrate/references/integration-prompt.md

@@ -0,0 +1,179 @@
+# 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 (dialog.drawer:true) / headless (ui:false)]
+  dialog: {
+    drawer: true,                                // drawer mode: right slide-in + mask; close defaults to hide() preserving history
+    title: '[Business] Agent',
+    placeholder: 'Try: [example operation]',
+  },
+  // 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,
+  // 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 + `dialog.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/options.md

@@ -10,7 +10,6 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | `systemPrompt` | `string` | built-in default (JSON-operation assistant + reliable write rules) | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). If omitted, a built-in default is used (JSON-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it. |
 | `appendReliableWriteRules` | `boolean` | `true` | When `true` (default) and a custom `systemPrompt` is set, auto-append `systemPromptHelpers.reliableWriteRules` to it with a `---` separator (clearly distinguishes user content from SDK-appended write rules; avoids forgetting the write rules). Set `false` to disable. No effect when `systemPrompt` is omitted (default prompt already includes them). |
 | `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
 
@@ -19,6 +18,19 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | `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 data/message/error still fire). |
+| `dialog` | `DialogConfig` | — | Grouped dialog UI config (recommended form). See `DialogConfig` fields below. |
+
+### `DialogConfig` fields
+
+| Field | Type | Default | Purpose / when |
+|---|---|---|---|
+| `title` | `string` | — | Dialog title (cosmetic). |
+| `placeholder` | `string` | — | Input placeholder (cosmetic). |
+| `drawer` | `boolean` | `false` | Drawer mode: ChatDialog slides in from the right + mask + close button (replaces the collapse arrow). Default `false` (inline, fills container). |
+| `drawerWidth` | `number \| string` | `420` | Drawer mode width (pixels or CSS string, e.g. `500` / `'500px'` / `'40vw'`). Only effective when `drawer: true`. Inline mode width is determined by `container`. |
+| `drawerHidden` | `boolean` | `false` | Drawer mode hidden by default (not shown after `mount`; requires `sdk.show()` to display): for "click button to show chatbox" scenarios. Only effective when `drawer: true`. |
+| `inputRows` | `number` | `2` | Input box rows (visible height). `1` = single row; `2` = 2-row initial height, auto-expands up to max-height:100px; `>2` = taller initial height. |
+| `onClose` | `() => void` | — | Drawer mode close callback (called when mask/close button clicked). Default: `hide()` in drawer mode (keeps agent/history/in-flight generation), `unmount()` otherwise. Pass this to sync external mount state. |
 
 ## Data operation (the core)
 
@@ -39,6 +51,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 |---|---|---|---|
 | `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. |
+| `skillStorage` | `SkillStoreConfig \| false` | `{ backend: 'indexed' }` | **User-created skill independent persistence** (separate from `storage`). Default indexedDB (persists even when `storage: false`); `false` disables persistence (current session only). `id` manually specifies the same id to share skills across pages/agents; omit for per-agent isolation. |
 | `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. |
 
@@ -124,13 +137,28 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 
 Runtime subscription via `sdk.hook(handler) => () => void` (multi-listener, cancellable) — see [api.md](api.md).
 
-## Convenience APIs (export / import / usage)
+## Convenience APIs (export / import / usage / user skills)
 
 | API | Purpose | Notes |
 |---|---|---|
 | `sdk.exportData()` | Deep copy of main data `bind` (backup/migration) | Returns `null` if dataOps off / no data; mutating return does not affect original bind |
 | `sdk.importData(json, opts?)` | Replace `bind` entirely (in-place, preserves reactive ref) | Schema-validated by default → `{ok:false,error}` if invalid; `opts.validate:false` skips; `opts.emit:false` suppresses `data_change` |
 | `sdk.usage` | Cumulative token usage `{prompt_tokens, completion_tokens, total_tokens}` | Accumulated per LLM call; per-round detail via `onEvent('usage')` |
+| `sdk.addSkill(skill)` | Add a user-created skill at runtime | `skill: { name, description, prompt \| getContent \| doc }`. Auto-merges into the skill list, **persists via independent SkillStore** (default indexedDB, separate from `storage` option — even `storage:false` persists skills), and takes effect next round. Same-name overwrites. Requires `capabilities.skills` (default on) + `skillStorage` not `false` for persistence. |
+| `sdk.removeSkill(name)` | Remove a user-created skill by name | Only removes user-created skills (not the ones passed via `skills` option at init). Removes from SkillStore. No-op if not found. |
+| `sdk.listUserSkills()` | List names of user-created skills | Returns `string[]` (only user-created, not init-time skills). Useful for UI panels. |
+| `sdk.getUserSkill(name)` | Read a user-created skill's detail | Returns `{ name, description, content }` or `undefined` if not found. Used by SkillPanel for editing. |
+
+**User-created skills** are skills added at runtime via `sdk.addSkill` (or via the built-in `SkillPanel` UI component). They are persisted via an **independent SkillStore** (default indexedDB), **separate from the `storage` option** — even when `storage: false` (session persistence off), user skills still persist across refreshes. To **share the same set of user skills across pages/agents**, manually specify the same `skillStorage.id`:
+
+```ts
+// Page A
+createChatSdk({ id: 'agent-a', skillStorage: { id: 'shared-skills' }, ... })
+// Page B (different agent, same skill set)
+createChatSdk({ id: 'agent-b', skillStorage: { id: 'shared-skills' }, ... })
+```
+
+Without `skillStorage.id`, skills default to per-agent isolation (`agent::{agentId}`). The built-in `ChatDialog` exposes a "Skill Management" button (header) that opens `SkillPanel` — supports create, **edit** (click a skill to load into the form), and delete. Integrators can also `import { SkillPanel }` directly for custom UIs.
 
 ## vfs (in-memory workspace)
 

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

@@ -275,9 +275,9 @@ 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: '数据分析助手…' }),
+  createChatSdk({ id: 'agent-page',  container: boxA, dialog: { drawer: true }, storage: 'memory', llm: LLM, data: { schema: pageSchema,  bind: pageObj  }, systemPrompt: '页面构建助手…' }),
+  createChatSdk({ id: 'agent-copy',  container: boxB, dialog: { drawer: true }, storage: 'memory', llm: LLM, data: { schema: copySchema,  bind: copyObj  }, systemPrompt: '文案优化助手…' }),
+  createChatSdk({ id: 'agent-stats', container: boxC, dialog: { 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

package/types/index.d.ts

@@ -137,6 +137,7 @@ export interface McpServerConfig { transport: 'http' | 'sse' | 'websocket'; url:
 export declare const ChatDialog: DefineComponent<ChatDialogProps>;
 export declare const MessageContent: DefineComponent<any>;
 export declare const CodePreview: DefineComponent<any>;
+export declare const SkillPanel: DefineComponent<any>;
 export declare function useChat(opts?: any): any;
 
 // ===== 框架无关 SDK(页面内 Agent)=====
@@ -301,6 +302,15 @@ export interface StorageConfig {
   evictionWatermark?: number;
   debounceMs?: number;
 }
+/** Skill 独立持久化存储配置(与 storage 选项分离) */
+export interface SkillStoreConfig {
+  /** 存储 id(命名空间)。手动指定同一 id 即可跨页面/跨 agent 复用同一套用户 skill;不传默认按 agentId 隔离 */
+  id?: string;
+  /** 后端类型,默认 'indexed'(大容量、跨刷新);'local' 跨页持久;'session' 刷新保留关页清;'memory' 纯内存降级 */
+  backend?: StorageBackendType;
+  /** DB 命名空间,默认 'chat-sdk'(与 SessionStore 同库,不同 key 前缀) */
+  dbName?: string;
+}
 export interface SessionMeta {
   agentId: string;
   sessionId: string;
@@ -362,6 +372,8 @@ export interface ChatSdkOptions {
   appendReliableWriteRules?: boolean;
   tools?: any[];
   skills?: SkillSpec[];
+  /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
+  skillStorage?: SkillStoreConfig | false;
   memory?: string;
   data?: DataConfig;
   permissions?: PermissionRule[];
@@ -430,11 +442,19 @@ export interface ChatSdkOptions {
   onEvent?: SdkEventHandler;
   /** 流式输出(默认 true);false 时等整段回复再显示 */
   streaming?: boolean;
+  /** Dialog UI config (title/placeholder/drawer/drawerWidth/drawerHidden/inputRows/onClose grouped) */
+  dialog?: DialogConfig;
+}
+
+/** Dialog UI config (grouped form, recommended) */
+export interface DialogConfig {
   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. */
+  drawerWidth?: number | string;
+  drawerHidden?: boolean;
+  /** Input box rows (visible height); default 2 (2-row initial height, auto-expands up to max-height:100px). 1 = single row; >2 = taller. */
+  inputRows?: number;
   onClose?: () => void;
 }
 
@@ -467,6 +487,14 @@ export interface ChatSdk {
    * 清空 skill 全文缓存与本轮已加载记录,下次 load_skill 重新取最新全文(含 vfs doc)。需开启 skills(默认开)
    */
   setSkills(skills: SkillSpec[]): void;
+  /** 添加用户创建的 skill(持久化,跨刷新恢复;同名覆盖)。需开启 skills(默认开) */
+  addSkill(skill: SkillSpec): void;
+  /** 删除用户创建的 skill(仅删用户创建的,不删集成方 initialSkills)。返回是否删除成功 */
+  removeSkill(name: string): boolean;
+  /** 列出用户创建的 skill 名(仅用户创建的,不含集成方 initialSkills) */
+  listUserSkills(): string[];
+  /** 读取用户创建的 skill 详情(返回 {name, description, content};不存在返回 undefined) */
+  getUserSkill(name: string): { name: string; description: string; content: string } | undefined;
   /**
    * 清 skill 全文缓存(动态 skill 内容变化时主动失效)。不传 name 清全部;传 name 清指定。
    * 下次 load_skill 重新 getContent/readSkillDoc 取最新。需开启 skills(默认开)
@@ -545,6 +573,23 @@ export declare function createSessionStore(config?: StorageConfig): SessionStore
 export declare function createMemoryBackend(): StorageBackend;
 export declare function createWebStorageBackend(storage: Storage): StorageBackend;
 export declare function isQuotaError(err: unknown): boolean;
+/** 创建 Skill 独立持久化存储(与 storage 选项分离;默认 indexedDB,可手动指定 id 跨页复用) */
+export declare function createSkillStore(config?: SkillStoreConfig): SkillStore;
+export interface SkillStore {
+  ready: Promise<boolean>;
+  list(): Promise<PersistedSkill[]>;
+  get(name: string): Promise<PersistedSkill | undefined>;
+  put(skill: PersistedSkill): Promise<void>;
+  remove(name: string): Promise<boolean>;
+  clear(): Promise<void>;
+  dispose(): void;
+}
+/** 持久化的用户创建 skill(getContent 函数不可序列化,故 content 直接存字符串) */
+export interface PersistedSkill {
+  name: string;
+  description: string;
+  content: string;
+}
 
 // ============ 大 JSON 查询/搜索/沙箱脚本(dataSlotQuery)============
 export interface JpNode {