page-agent-sdk 1.1.3 → 1.2.0

package/package.json

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

@@ -77,6 +77,23 @@ Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_resul
 - `capabilities: { windowOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` — turn off unused built-ins to save tokens/size. `verify` is the reverse (off by default; `capabilities.verify:true` enables write-back self-check).
 - `presets.pageBuilder` / `researcher` / `minimal` — spread into `createChatSdk` for common scenarios.
 
+## Common use cases (match the user's scenario, then read [references/use-cases.md](references/use-cases.md) for full code)
+
+| Scenario | Key setup |
+|---|---|
+| **Low-code page builder** | `windowProps` = component tree; `edit_window_prop` jsonPath patches; `onEvent` → canvas refresh; `checkpoint` + `approval` |
+| **Form designer** | `windowProps` = field definitions with enum/required schemas; schema validation prevents malformed forms |
+| **CMS batch ops** | `eval_window_script` for bulk loops; `search_window_prop` to filter; `edit_window_prop` for targeted edits |
+| **Ops config console** | `approval:{tools:[set,edit]}` human-confirm; `capabilities.verify:true` write-back read; `checkpoint` |
+| **AI-native assistant** | `capabilities:{windowOps:false,fetch:false}` + custom `tools` (your product API) |
+| **Research agent** | `capabilities:{windowOps:false}`; `subagent:{allowedTools:['fetch_document']}`; `contextPreset:'conservative'` |
+| **Headless / server-side** | `ui:false` + `storage:'memory'` + `capabilities:{windowOps:false,fetch:false}`; drive via `sdk.send` |
+| **Multi-agent on one page** | same `id` + `shareContext:true` → multiple dialogs share one `AgentCore` |
+| **MCP integration** | `mcp:[{transport,url}]` remote tool servers; `@modelcontextprotocol/sdk` optional peerDep |
+| **Lazy-loaded components (dynamic schemas)** | `sdk.addWindowProp(spec)` on component mount / `removeWindowProp` on unmount; tools pick up new registrations immediately, no rebuild. See [references/advanced.md §0](references/advanced.md) |
+
+When the user describes a scenario, map it to the row above and load `references/use-cases.md` for the matching numbered case (1→9) with copy-paste code. For dynamic/lazy-loaded component schemas, custom tools/skills/subagents/MCP, load [references/advanced.md](references/advanced.md).
+
 ## References (read as needed)
 
 Detailed docs live in this skill's `references/` folder — load the one matching the user's question:
@@ -85,6 +102,7 @@ Detailed docs live in this skill's `references/` folder — load the one matchin
 - **[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.
+- **[references/advanced.md](references/advanced.md)** — detailed examples for the extensibility surfaces: **dynamic windowProps (`sdk.addWindowProp`/`removeWindowProp` for lazy-loaded components)**, custom `defineTool` (with error handling + coexisting with windowOps), `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 "lazy-load components with different schemas".
 
 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/advanced.md

@@ -0,0 +1,250 @@
+# Advanced examples — custom tools, skills, subagents, MCP, dynamic windowProps
+
+Detailed, copy-paste examples for the extensibility surfaces. Read the section matching the user's need.
+
+## 0. Dynamic windowProps (lazy-loaded components) — `sdk.addWindowProp` / `removeWindowProp`
+
+When components are lazy-loaded with **different schemas each**, don't declare all `windowProps` upfront. Register them at runtime as components mount/unmount. The agent's window tools pick up new registrations immediately (no agent rebuild).
+
+```ts
+const sdk = createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '你是页面助手,按组件类型操作 window.app.components.<id>。',
+  windowProps: [
+    // statically-declared ones (always present)
+    { path: 'app.config', description: '全局配置', schema: z.record(z.any()) },
+  ],
+}).mount()
+
+// 组件懒加载时动态注册其 schema(结构各异)
+function onComponentMount(comp: { id: string; type: string; schema: z.ZodType }) {
+  sdk.addWindowProp({ path: `app.components.${comp.id}`, description: `${comp.type} 组件`, schema: comp.schema })
+  // 立即生效:AI 现在能 set/edit_window_prop 这个 path,按其 schema 校验
+}
+
+// 组件卸载时移除(快照栈一并清理)
+function onComponentUnmount(id: string) {
+  sdk.removeWindowProp(`app.components.${id}`)
+}
+
+// 查看当前所有注册项(反映动态增删)
+const current: WindowPropSpec[] = sdk.listWindowProps()
+```
+
+Notes:
+- `addWindowProp` 覆盖同名 path 时保留旧快照栈;按新 schema 校验。
+- 动态注册的属性**不自动纳入 checkpoint 快照**(checkpoint 的 windowPaths 在构造时固定);如需回滚动态组件,自行管理或重建。
+- `inspect().windowProps` 与 `verify`(默认 `createWriteBackCheck`)均反映动态注册的最新 schemas(verify 每次 check 实时取 `listWindowProps()`)。
+- `capabilities.windowOps:false` 时 `addWindowProp`/`removeWindowProp` 为 no-op(并 warn)。
+
+## 1. Custom tools (`defineTool`)
+
+Custom tools extend the agent beyond built-in `windowOps`/`fetch`. Use them to expose your product's API to the AI.
+
+### Minimal
+
+```ts
+import { createChatSdk, defineTool, z } from 'page-agent-sdk'
+
+const lookupOrder = defineTool({
+  name: 'lookup_order',
+  description: '查询订单 by id',
+  schema: z.object({ orderId: z.string() }),
+  handler: async ({ orderId }) => JSON.stringify(await api.getOrder(orderId)),
+})
+```
+
+### With error handling
+
+Return structured errors via `toolError` so the AI can react:
+
+```ts
+import { defineTool, toolError, z } from 'page-agent-sdk'
+
+const updatePrice = defineTool({
+  name: 'update_price',
+  description: '更新商品价格',
+  schema: z.object({ sku: z.string(), price: z.number().positive() }),
+  handler: async ({ sku, price }) => {
+    const ok = await api.setPrice(sku, price)
+    if (!ok) return toolError({ path: sku, code: 'NOT_FOUND', message: `SKU ${sku} 不存在` })
+    return `已更新 ${sku} 价格为 ${price}`
+  },
+})
+```
+
+### Coexisting with windowOps
+
+Mix custom tools with built-in window tools:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  windowProps: [{ path: 'app.config', description: '配置', schema: z.record(z.any()) }],
+  tools: [lookupOrder, updatePrice],   // custom + built-in windowOps together
+}).mount()
+```
+
+### Pure custom-tool agent (no windowOps)
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  tools: [lookupOrder, updatePrice],
+  capabilities: { windowOps: false, fetch: false },   // drop built-ins
+}).mount()
+```
+
+## 2. Skills (`defineSkill`) — progressive disclosure
+
+Skills are **loaded on demand** by the agent (not always in context) → saves tokens. The agent sees an index of `name`+`description`, calls `load_skill` to pull the full content when needed.
+
+### Inline content skill
+
+```ts
+import { createChatSdk, defineSkill } from 'page-agent-sdk'
+
+const apiDesignSkill = defineSkill({
+  name: 'api-design',
+  description: '本项目 REST API 设计规范(何时用:设计/评审新接口)',
+  getContent: () => `
+- URL 用 kebab-case,统一 /v1 前缀
+- 列表接口必须分页(page+pageSize)
+- 错误返回 { code, message, data: null }
+- 写操作记审计日志
+`,
+})
+
+createChatSdk({ container: '#chat', llm: { ... }, skills: [apiDesignSkill] }).mount()
+```
+
+### Remote doc skill (auto-fetched + cached to vfs)
+
+```ts
+const brandSkill = defineSkill({
+  name: 'brand-guide',
+  description: '品牌视觉规范(何时用:涉及 UI/文案/配色)',
+  doc: 'https://my-wiki/brand.md',   // SDK fetches + caches to vfs; large docs stay out of context
+})
+
+createChatSdk({ container: '#chat', llm: { ... }, skills: [brandSkill] }).mount()
+```
+
+> `SkillSpec = { name, description, doc?, getContent? }`. `doc` (http(s):// or `vfs://path`) takes precedence over `getContent`. Write `description` as "what it is + when to use" so the agent knows when to load it.
+
+## 3. Subagents — ad-hoc spawn vs pre-declared
+
+Subagents run isolated sub-tasks; **only their final conclusion** returns to the main context (saves tokens). Two flavors coexist.
+
+### 3a. Ad-hoc `spawn_agent` / `spawn_agents` (default enabled)
+
+The main agent decides when to delegate via `spawn_agent` (one) / `spawn_agents` (parallel). Configure the subagent tool subset:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '多源对比时用 spawn_agents 并行委派。',
+  subagent: {
+    allowedTools: ['fetch_document', 'get_window_prop'],  // read-only subset (no spawn → no recursion)
+    maxDepth: 1,           // physical recursion cut (default 1)
+    maxParallel: 3,        // max parallel subagents in spawn_agents
+    temperature: 0.2,      // subagent temperature (default inherits main)
+  },
+}).mount()
+```
+
+User: "对比 A/B/C 三个方案" → main agent calls `spawn_agents` with 3 tasks → 3 subagents research in parallel → only conclusions return.
+
+### 3b. Pre-declared named subagents (`subagents`) — Claude-Code style
+
+Declare fixed roles; each auto-generates a `use_<id>({ task })` delegation tool. The main agent sees the tool description and knows who to delegate to:
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  systemPrompt: '复杂任务委派给专家子 agent。',
+  subagents: [
+    {
+      id: 'researcher',
+      description: '调研专家:搜集资料、对比方案(只读)',
+      tools: ['fetch_document', 'get_window_prop'],   // read-only
+      temperature: 0.2,
+    },
+    {
+      id: 'reviewer',
+      description: '审查专家:检查代码/配置的安全与性能问题',
+      tools: ['get_window_prop', 'search_window_prop'],
+      systemPrompt: '你是审查专家,只报告问题不改数据。',
+      temperature: 0.1,
+    },
+  ],
+}).mount()
+```
+
+Now the main agent has `use_researcher({ task })` and `use_reviewer({ task })` tools. Each subagent inherits main config where omitted (`llm`, `maxTokens`, `skills`...).
+
+> Pre-declared = fixed roles (research/review); ad-hoc `spawn` = temporary free delegation. Both can coexist. `maxDepth` (default 1) physically cuts recursion: at depth+1 ≥ maxDepth, subagents get no spawn tools.
+
+## 4. MCP (external tool servers)
+
+Connect remote MCP servers; their tools auto-inject into the agent. `Promise.allSettled` → one server down doesn't break others.
+
+### HTTP (StreamableHTTP) — recommended
+
+```ts
+createChatSdk({
+  container: '#chat', llm: { ... },
+  mcp: [
+    { transport: 'http', url: 'https://my-mcp-server/mcp', name: 'my-tools' },
+  ],
+}).mount()
+```
+
+### SSE / WebSocket
+
+```ts
+mcp: [
+  { transport: 'sse',       url: 'https://another/sse' },
+  { transport: 'websocket', url: 'wss://ws-server/mcp' },
+]
+```
+
+### With request init (auth headers)
+
+```ts
+mcp: [
+  {
+    transport: 'http', url: 'https://my-mcp/mcp',
+    requestInit: { headers: { Authorization: `Bearer ${token}` } },
+  },
+]
+```
+
+### Notes
+
+- `@modelcontextprotocol/sdk` is an **optional peerDep** — install it only if you use `mcp`. It's dynamically imported (zero cost when unused).
+- Browser supports **only remote transports** (http/sse/websocket), not stdio.
+- MCP `inputSchema` (JSON Schema) is passed directly to LangChain `tool()` — no conversion.
+- `inspect().mcp.servers` lists connected servers; each tool's `source` shows `mcp:<name>`.
+
+### Dev gotcha
+
+If you fork `vite.config.ts`, keep `optimizeDeps.include` pre-declaring the SDK sub-paths (`/client`, `/client/streamableHttp.js`, `/client/sse.js`, `/client/websocket.js`). Otherwise the **first cold visit** to an MCP page injects 0 tools (reload fixes it). The default config already has these.
+
+## 5. Combining everything
+
+```ts
+createChatSdk({
+  container: '#chat',
+  llm: { apiKey, baseUrl, model },
+  systemPrompt: '...',
+  windowProps: [{ path: 'app.data', description: '...', schema: z.record(z.any()) }],
+  tools: [lookupOrder, updatePrice],          // custom tools
+  skills: [apiDesignSkill, brandSkill],         // progressive skills
+  subagents: [{ id: 'researcher', description: '...', tools: ['fetch_document'] }],  // pre-declared
+  mcp: [{ transport: 'http', url: '...' }],     // external tools
+  capabilities: { verify: true },               // self-check
+  approval: { tools: ['set_window_prop'] },     // human confirm writes
+  checkpoint: true,                             // rollback
+}).mount()
+```

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

@@ -12,6 +12,9 @@
 | `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`. |
+| `addWindowProp(spec)` | `(spec: WindowPropSpec) => void` | Runtime register/override a window prop (lazy-loaded components). Takes effect immediately, no rebuild. Needs `windowOps` enabled. |
+| `removeWindowProp(path)` | `(path: string) => boolean` | Remove a registered window prop (component unmount); returns whether it existed. Clears its snapshot stack. |
+| `listWindowProps()` | `() => WindowPropSpec[]` | List currently-registered window props (reflects dynamic add/remove). |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
 
@@ -39,8 +42,8 @@ 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; ...',
+  description: 'REST API design conventions for this project (load when designing/reviewing APIs)',
+  getContent: () => 'Use kebab-case URLs; version under /v1; ...',   // or `doc: 'https://...'` for remote
 })
 
 createChatSdk({ skills: [apiSkill], /* ... */ }).mount()

package/types/index.d.ts

@@ -168,6 +168,18 @@ export interface WindowOpsOptions {
   whitelist?: boolean;
 }
 
+/** window 属性注册表控制器(运行时动态增删;createWindowOps 返回的工具数组上以不可枚举属性 `controller` 挂载) */
+export interface WindowOpsController {
+  /** 新增/覆盖一个属性注册项(运行时懒加载组件场景);覆盖时旧快照栈保留 */
+  add(spec: WindowPropSpec): void;
+  /** 移除一个属性注册项;返回是否确实存在并移除。快照栈一并清理 */
+  remove(path: string): boolean;
+  /** 列出当前所有注册项(反映动态增删后的最新状态) */
+  list(): WindowPropSpec[];
+  /** 是否已注册某 path */
+  has(path: string): boolean;
+}
+
 export interface PermissionRule {
   operations: ('read' | 'write')[];
   scopes: string[];
@@ -383,6 +395,12 @@ export interface ChatSdk {
   listCheckpoints(): CheckpointMeta[];
   /** 运行时订阅 SDK 事件(可多个监听器,返回取消函数);与构造时 onEvent 互补 */
   hook(handler: SdkEventHandler): () => void;
+  /** 运行时动态新增/覆盖一个 window 属性注册项(懒加载组件:组件挂载时注册其 schema);立即对 window 工具生效,无需重建 agent。需开启 windowOps */
+  addWindowProp(spec: WindowPropSpec): void;
+  /** 运行时移除一个 window 属性注册项(组件卸载);返回是否确实存在并移除。快照栈一并清理 */
+  removeWindowProp(path: string): boolean;
+  /** 列出当前所有已注册 window 属性(反映动态增删后的最新状态) */
+  listWindowProps(): WindowPropSpec[];
 }
 
 export declare function createChatSdk(options: ChatSdkOptions): ChatSdk;