page-agent-sdk 1.1.4 → 1.3.0

package/package.json

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

@@ -27,6 +27,8 @@ See `demo/plain.html` for a framework-agnostic importmap + esm.sh example.
 
 Put the page data on `window` (e.g. `window.app = { title, theme }`), then declare each writable path with a zod schema. The agent can ONLY touch declared paths; `set`/`edit` are schema-validated (invalid → structured error, no write).
 
+> `systemPrompt` is optional — a built-in default is used if omitted (generic page-operation assistant + `systemPromptHelpers.reliableWriteRules`: read-before-write, list in dynamic scenarios, fields per `describe`, retry on validation error, prefer incremental `edit`). Passing your own fully overrides it; append `systemPromptHelpers.reliableWriteRules` yourself if you want the rules.
+
 ```ts
 import { createChatSdk, z } from 'page-agent-sdk'
 import 'page-agent-sdk/style.css'
@@ -90,8 +92,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→10) 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)
 
@@ -100,8 +103,8 @@ Detailed docs live in this skill's `references/` folder — load the one matchin
 - **[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.
-- **[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/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 / lazy-loaded dynamic components). 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

@@ -1,6 +1,73 @@
-# 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)。
+
+**完整可运行示例**:`examples/dynamic-demo/`(dev 启动后访问 `/examples/dynamic-demo/`)—— 演示加载/卸载结构各异的组件(banner/card/stat/chart),挂载即 `addWindowProp` 注册其 schema,AI 立即可按各自 schema 操作,卸载即 `removeWindowProp`;右侧实时显示 `sdk.listWindowProps()` 反映动态增删。
+
+### 动态场景下「压缩后不丢信息」的保障(内置,无需额外配置)
+
+动态组件随时增删,长会话压缩后 LLM 可能基于过时记忆操作已卸载的组件、或不知道新组件已注册。SDK 内置两道保障:
+
+- **A. 压缩时注入注册表快照**:`summarization` 中间件压缩 older 轮次时,自动把当前 `listWindowProps()` 的 `path + description` 作为一段附进摘要 system 消息(不进压缩)。LLM 即便忘了历史 `describe`,每轮仍看得到「当前有哪些可操作 path」,不会再去操作已卸载的组件。`windowOps` 关闭时返回空,无影响。
+- **C. preserveLastToolResults**:`contextOptions.preserveLastToolResults`(默认 `['describe_window_prop','list_window_props']`)指定这些工具的步骤 `result` 在跨轮摘要时额外保留摘要片段进 summaryMsg。即便 older 轮被摘要,关键字段说明仍在摘要里,LLM 不必反复 `describe`。设为 `[]` 关闭。
+
+```ts
+// 默认即开启 A + C;如需关闭或自定义:
+createChatSdk({
+  contextOptions: {
+    preserveLastToolResults: [],  // 关闭 C(不保留工具结果摘要)
+    // getRegisteredProps 由 SDK 内部注入(来自 sdk.listWindowProps),无需手动传
+  },
+  // ...
+})
+```
+
+- **B. 写操作返回附当前可操作 path 列表**:`set`/`edit`/`delete` 成功返回末尾自动附 `(当前可操作 path: a, b, c)`,LLM 写完即知全貌,多组件批量场景减少 `list` 调用。超过 8 项或过长时只报数量,避免提示过长。
+- **D. `systemPromptHelpers.reliableWriteRules`**:导出的标准化「可靠写入规则」片段,建议拼进 `systemPrompt`:
+
+```ts
+import { systemPromptHelpers } from 'page-agent-sdk'
+createChatSdk({
+  systemPrompt: `你是页面助手。\n${systemPromptHelpers.reliableWriteRules}`,
+  // ...
+})
+```
+内容:改前先 `get` 读真实值、动态场景先 `list`、字段以 `describe` 为准、写错看校验错误重试、优先 `edit` 增量 patch。避免集成方忘了写这些元规则导致 LLM 凭记忆瞎改。
 
 ## 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. |
 
@@ -59,6 +62,19 @@ createChatSdk({ ...presets.pageBuilder, llm, container }).mount()
 
 Spread into options for common scenarios.
 
+## systemPromptHelpers (best-practice prompt snippets)
+
+```ts
+import { createChatSdk, systemPromptHelpers } from 'page-agent-sdk'
+
+createChatSdk({
+  systemPrompt: `你是页面助手。\n${systemPromptHelpers.reliableWriteRules}`,
+  llm, container,
+}).mount()
+```
+
+`reliableWriteRules` — standardized "reliable write rules": read before write (`get_window_prop`), list in dynamic scenarios, fields per `describe_window_prop`, retry on schema-validation errors, prefer `edit_window_prop` incremental patches. Recommended for any scenario involving window writes.
+
 ## Built-in window tools (auto-injected when `capabilities.windowOps`)
 
 | Tool | Purpose |

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

@@ -7,7 +7,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | 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`). |
+| `systemPrompt` | `string` | built-in default (generic page 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 (page-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it (append `systemPromptHelpers.reliableWriteRules` yourself if needed). |
 | `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). |
 
@@ -70,7 +70,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | 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. |
+| `contextOptions` | `object` | — | Detailed compression params (overrides preset). `false` disables compression. Key fields: `windowRounds`, `summaryThresholdRounds`, `contextWindow`, `summaryThresholdRatio`, `windowRatio`, `enableRecall`, `recallTopK`, `enableLLMSummary`, `preserveLastToolResults` (default `['describe_window_prop','list_window_props']` — keep these tools' result summaries in the compressed summary so field descriptions survive compression; set `[]` to disable). `getRegisteredProps` is injected internally by the SDK (from `sdk.listWindowProps`) to embed a live registry snapshot in the summary — no need to set it manually. |
 | `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. |

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

@@ -9,7 +9,7 @@ From the smallest working setup to a full-featured integration. Read top-down; s
 
 ## Stage 1 — Minimal (5 lines, CDN, no build)
 
-Drop into any HTML page. The built-in dialog mounts itself.
+Drop into any HTML page. The built-in dialog mounts itself. (`systemPrompt` is optional — a built-in default is used if omitted: a generic page-operation assistant + `systemPromptHelpers.reliableWriteRules`. Shown here explicitly for clarity.)
 
 ```html
 <div id="root"></div>
@@ -115,6 +115,38 @@ createChatSdk({
 await sdk.switchSession('session-abc')   // load or create
 ```
 
+## Stage 7 — Dynamic windowProps (lazy-loaded components)
+
+Components loaded on demand with **different schemas each** — register at mount, unregister at unmount. No need to pre-declare every possible component at `createChatSdk`. The agent picks up new registrations immediately (no rebuild); `summarization` also embeds a live registry snapshot in compressed summaries so the agent won't act on stale memory.
+
+```ts
+const sdk = createChatSdk({
+  container: '#root', llm: { ... },
+  // only the static container is pre-declared; per-component paths are dynamic
+  windowProps: [{ path: 'app.components', description: '动态组件容器(按 id 存)', schema: z.record(z.string(), z.any()) }],
+}).mount()
+
+// component mounts (lazy) → register its schema, immediately operative
+function mountComp(comp: { id: string; type: 'banner' | 'card' | 'stat' | 'chart' }) {
+  window.app.components[comp.id] = reactive(comp)
+  sdk.addWindowProp({
+    path: `app.components.${comp.id}`,
+    description: `${typeDescriptions[comp.type]}`,  // ← give the LLM field-level detail (it can't see the zod schema)
+    schema: compSchemas[comp.type],                 // ← validation guardrail
+  })
+}
+// component unmounts → unregister (snapshot stack cleaned too)
+function unmountComp(id: string) {
+  delete window.app.components[id]
+  sdk.removeWindowProp(`app.components.${id}`)
+}
+sdk.listWindowProps()  // live registry (reflects dynamic add/remove)
+```
+
+> Key points: `description` is the LLM's only source of field structure (write it in detail); `schema` is the validation guardrail (the LLM never sees it). Write operations return the current operable path list; long-session compression keeps a live registry snapshot + preserved `describe`/`list` results so the agent never loses track of dynamic components.
+
+**Full runnable demo**: `examples/dynamic-demo/` (`npm run dev` → `/examples/dynamic-demo/`).
+
 ## Next
 
 - All options: see [options.md](options.md)

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

@@ -198,3 +198,34 @@ createChatSdk({
 ```
 
 > Note: `@modelcontextprotocol/sdk` is an optional peerDep — install it only if you use `mcp`. Browser supports only remote transports (http/sse/websocket), not stdio.
+
+## 10. Lazy-loaded components with dynamic schemas (dynamic windowProps)
+
+Components loaded on demand with **different structures each** — register their schema at mount time, unregister at unmount. No need to pre-declare every possible component at `createChatSdk`.
+
+```ts
+const sdk = createChatSdk({
+  container: '#chat', llm: { ... },
+  // only the static container is pre-declared; per-component paths are dynamic
+  windowProps: [{ path: 'app.components', description: '动态组件容器', schema: z.record(z.any()) }],
+  systemPrompt: '用 list_window_props 查看当前可操作的组件 path,再按各自 schema 操作',
+}).mount()
+
+// 组件挂载(懒加载)→ 动态注册其 schema,立即对 AI 生效
+function mountComp(comp: { id: string; type: CompType }) {
+  window.app.components[comp.id] = reactive(comp)
+  sdk.addWindowProp({
+    path: `app.components.${comp.id}`,
+    description: `${comp.type} 组件`,
+    schema: compSchemas[comp.type],   // 结构各异:banner/card/stat/chart 各自 schema
+  })
+}
+// 组件卸载 → 动态移除注册(快照栈一并清理)
+function unmountComp(id: string) {
+  delete window.app.components[id]
+  sdk.removeWindowProp(`app.components.${id}`)
+}
+```
+
+**完整可运行示例**:`examples/dynamic-demo/`(`npm run dev` → `/examples/dynamic-demo/`)。
+**何时用**:可视化编辑器/低代码平台中,组件按需加载且结构各异(图表/表单/卡片 schema 各不同),无法在初始化时穷举所有组件 schema。详见 `advanced.md` §0。

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;
@@ -404,6 +422,11 @@ export declare function createSubagentMiddleware(opts: any): any;
 export declare function createVerifyMiddleware(opts: VerifyMiddlewareOptions): any;
 export declare function createWriteBackCheck(opts?: WriteBackCheckOptions): VerifyCheck;
 export declare const presets: Record<string, any>;
+/** systemPrompt 辅助片段(标准化最佳实践,拼进 systemPrompt 降低写错门槛) */
+export declare const systemPromptHelpers: {
+  /** 可靠写入规则:改前先读、动态先 list、字段以 describe 为准、写错看校验错误重试、优先增量 patch */
+  readonly reliableWriteRules: string;
+};
 export declare function createSessionStore(config?: StorageConfig): SessionStore;
 export declare function createMemoryBackend(): StorageBackend;
 export declare function createWebStorageBackend(storage: Storage): StorageBackend;