page-agent-sdk 1.1.4 → 1.2.0

package/package.json

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

@@ -90,8 +90,9 @@ Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_resul
 | **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.
+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)
 
@@ -101,7 +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 four extensibility surfaces: 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".
+- **[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

@@ -1,6 +1,41 @@
-# Advanced examples — custom tools, skills, subagents, MCP
+# Advanced examples — custom tools, skills, subagents, MCP, dynamic windowProps
 
-Detailed, copy-paste examples for the four extensibility surfaces. Read the section matching the user's need.
+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`)
 

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

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;