page-agent-sdk 2.9.1 → 2.10.0

package/package.json

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

@@ -81,8 +81,12 @@ const sdk = createChatSdk({
     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
+  // [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)
@@ -97,8 +101,6 @@ const sdk = createChatSdk({
     }),
   ],
   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') {
@@ -172,6 +174,6 @@ Per your business scenario, fill in `systemPrompt` / `skills` / `data.schema`:
 - **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
+- **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 {