page-agent-sdk 1.1.3 → 1.1.4

package/README.md

@@ -40,9 +40,13 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
 | 📰 **CMS ops** | "Prefix these products with 'Limited', mark under ¥100 red" | JSONPath filter + sandbox script batch edit |
 | 🖥 **Ops console** | "Raise A's threshold to 30%, turn off switch B" | Whitelist + human-confirm to edit config, read-back verify |
 | 🤖 **AI-native assistant** | "Change this chart's legend to bars" | Conversational ops on product data, no UI needed |
+| 🔬 **Research agent** | "Compare 3 solutions and recommend one" | Parallel subagents investigate each, return only conclusions |
+| 🧩 **Headless / server-side** | "Run the agent in Node.js" | `ui:false` + `storage:'memory'`, drive via `sdk.send` |
 
 > `examples/nested-demo` is a full low-code example: nested block tree + human confirm + one-click rollback.
 
+**Full end-to-end scenarios with copy-paste code** (9 cases: low-code builder / form designer / CMS batch / ops console / AI-native / research / server-side / multi-agent / MCP) live in the bundled Agent Skill at `skills/page-agent-sdk-integrate/references/use-cases.md` (also shipped in the npm package). See [Skills for AI tools](#skills-for-ai-tools-for-integrators) below to install the skill.
+
 ## 30-second quickstart
 
 ```bash

package/README.zh-CN.md

@@ -40,9 +40,13 @@
 | 📰 **CMS 运营** | 「这批商品标题加『限时』前缀、低于 100 元的标红」 | JSONPath 筛选 + 沙箱脚本批量改 |
 | 🖥 **运维配置台** | 「A 实验阈值调到 30%、关掉 B 开关」 | 白名单 + 人工确认改配置，写后读回校验 |
 | 🤖 **AI 原生助手** | 「把这张看板的图例改成柱状」 | 对话操作产品自有数据，免做 UI |
+| 🔬 **调研 agent** | 「对比 3 个方案，推荐哪个」 | 并行子 agent 各调研一个，只回结论 |
+| 🧩 **Headless / 服务端** | 「在 Node.js 里跑 agent」 | `ui:false` + `storage:'memory'`，用 `sdk.send` 驱动 |
 
 > 仓库 `examples/nested-demo` 即低代码场景完整示例：嵌套区块树 + 人工确认 + 一键回退。
 
+**完整端到端场景（含可复制代码，共 9 例：低代码搭建 / 表单设计器 / CMS 批量 / 运维配置台 / AI 原生 / 调研 / 服务端 / 多 agent / MCP）** 见随包附带的 Agent Skill：`skills/page-agent-sdk-integrate/references/use-cases.md`（npm 包内同样包含）。安装 skill 见下文[给 AI 工具使用者的 Skills](#给-ai-工具使用者的-skills集成方安装)。
+
 ## 30 秒上手
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "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,22 @@ 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 |
+
+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.
+
 ## References (read as needed)
 
 Detailed docs live in this skill's `references/` folder — load the one matching the user's question:
@@ -85,6 +101,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".
 
 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,215 @@
+# Advanced examples — custom tools, skills, subagents, MCP
+
+Detailed, copy-paste examples for the four extensibility surfaces. Read the section matching the user's need.
+
+## 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

@@ -39,8 +39,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()