page-agent-sdk 1.1.0 → 1.1.2

package/README.md

@@ -255,6 +255,30 @@ doc/                            # usage-guide / architecture / context-managemen
 CLAUDE.md                       # architecture + gotchas + coding conventions (agent must-read)
 ```
 
+## Skills for AI tools (for integrators)
+
+A ready-to-use Agent Skill is bundled for integrators using Claude Code / Cursor (or any agent harness that loads `.claude/skills/` / `~/.claude/skills/`). It teaches the AI how to use **this SDK** in your project:
+
+| Skill | When it triggers |
+|---|---|
+| `page-agent-sdk-integrate` | Embedding the SDK — choose install method, declare `windowProps` + zod schemas, configure the LLM, mount, subscribe to events (`onEvent` / `sdk.hook`), run headless, troubleshoot common pitfalls |
+
+**Install** (pick one):
+
+```bash
+# Option A — copy from the installed npm package
+npm i page-agent-sdk
+cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-integrate ~/.claude/skills/
+
+# Option B — download from the repo (no install needed)
+curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-integrate'
+mv skills/page-agent-sdk-integrate ~/.claude/skills/
+```
+
+After install, restart your AI tool; the skill auto-triggers when you ask things like "add page-agent-sdk to my page".
+
+> A second skill `page-agent-sdk-release` (release workflow for maintainers) is kept in the repo's `.claude/skills/` for project maintainers only and is **not** distributed via the npm package.
+
 ## Architecture
 
 ```mermaid
@@ -315,11 +339,11 @@ After `npm run dev`, visit the corresponding page:
 | Example | Entry | Demonstrates |
 |---|---|---|
 | page-demo | `/` | Self-bootstrapping demo: left JSON reactive page + right chat |
-| nested-demo | `/nested.html` | Nested block tree + human confirm + checkpoint |
-| human-confirm-demo | `/human-confirm.html` | AI proactive inquiry (multi-plan pick) + pre-write confirm |
-| planner-demo | `/planner.html` | Plan-reflect-execute (high-temp creative planner + low-temp reflector) |
-| subagent-demo | `/subagent.html` | Subagent parallel orchestration |
-| mcp-demo | `/mcp.html` | MCP remote tools (needs `npm run mcp:mock`) |
+| nested-demo | `/examples/nested-demo/` | Nested block tree + human confirm + checkpoint |
+| human-confirm-demo | `/examples/human-confirm-demo/` | AI proactive inquiry (multi-plan pick) + pre-write confirm |
+| planner-demo | `/examples/planner-demo/` | Plan-reflect-execute (high-temp creative planner + low-temp reflector) |
+| subagent-demo | `/examples/subagent-demo/` | Subagent parallel orchestration |
+| mcp-demo | `/examples/mcp-demo/` | MCP remote tools (needs `npm run mcp:mock`) |
 
 Framework-agnostic integration: `demo/plain.html` (importmap + esm.sh).
 

package/README.zh-CN.md

@@ -200,6 +200,30 @@ doc/                            # usage-guide / architecture / context-managemen
 CLAUDE.md                       # 架构要点 + 约定坑 + 编码规范（agent 必读）
 ```
 
+## 给 AI 工具使用者的 Skills（集成方安装）
+
+内置一个开箱即用的 Agent Skill，供使用 Claude Code / Cursor（或任何加载 `.claude/skills/` / `~/.claude/skills/` 的 agent 工具）的集成方使用。它教 AI 如何在**你的项目**中使用本 SDK：
+
+| Skill | 触发场景 |
+|---|---|
+| `page-agent-sdk-integrate` | 集成 SDK —— 选引入方式、声明 `windowProps` + zod schema、配 LLM、挂载、订阅事件（`onEvent` / `sdk.hook`）、跑 headless、排查常见坑 |
+
+**安装**（任选其一）：
+
+```bash
+# 方式 A —— 从已安装的 npm 包复制
+npm i page-agent-sdk
+cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-integrate ~/.claude/skills/
+
+# 方式 B —— 从仓库下载（无需安装）
+curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-integrate'
+mv skills/page-agent-sdk-integrate ~/.claude/skills/
+```
+
+安装后重启 AI 工具；当你说「把 page-agent-sdk 加到我的页面」等时 skill 自动触发。
+
+> 另有 `page-agent-sdk-release`（维护者发布工作流）skill 仅保留在仓库 `.claude/skills/` 供项目维护者自用，**不**通过 npm 包公开分发。
+
 ## 架构
 
 ```mermaid
@@ -260,11 +284,11 @@ createChatSdk({
 | 示例 | 入口 | 演示 |
 |---|---|---|
 | page-demo | `/` | 自举 demo：左 JSON 响应式页面 + 右对话框 |
-| nested-demo | `/nested.html` | 嵌套区块树 + 人工确认 + checkpoint |
-| human-confirm-demo | `/human-confirm.html` | AI 主动征询（多方案点选）+ 写前确认 |
-| planner-demo | `/planner.html` | 规划-反思-执行（高温创意 planner + 低温 reflector） |
-| subagent-demo | `/subagent.html` | 子 agent 并行编排 |
-| mcp-demo | `/mcp.html` | MCP 远程工具（需 `npm run mcp:mock`） |
+| nested-demo | `/examples/nested-demo/` | 嵌套区块树 + 人工确认 + checkpoint |
+| human-confirm-demo | `/examples/human-confirm-demo/` | AI 主动征询（多方案点选）+ 写前确认 |
+| planner-demo | `/examples/planner-demo/` | 规划-反思-执行（高温创意 planner + 低温 reflector） |
+| subagent-demo | `/examples/subagent-demo/` | 子 agent 并行编排 |
+| mcp-demo | `/examples/mcp-demo/` | MCP 远程工具（需 `npm run mcp:mock`） |
 
 框架无关集成：`demo/plain.html`（importmap + esm.sh）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "description": "框架无关的页面内 Agent JS SDK —— 以对话框形态挂载到任意网页,通过自定义 tool 读写宿主 window 属性(GET 抓文档),具备 planning/skills/虚拟工作区/快照回退/context 管理能力。Vue 打包进库,使用者无需安装 Vue。",
   "main": "./dist/page-agent-sdk.umd.cjs",
@@ -21,7 +21,8 @@
   },
   "files": [
     "dist",
-    "types"
+    "types",
+    "skills"
   ],
   "scripts": {
     "dev": "vite",

package/skills/page-agent-sdk-integrate/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: page-agent-sdk-integrate
+description: Integrate the page-agent-sdk npm package into a web app so an AI agent can read/write structured page data (window props) via schema-validated tools. Use when the user wants to add/embed the SDK, declare windowProps + zod schemas, configure the LLM, mount the chat dialog, subscribe to events (onEvent / sdk.hook), run headless (ui:false) with a custom UI, or troubleshoot common integration issues (DeepSeek 400 tool_call_id, MCP injecting 0 tools, etc).
+---
+
+# Integrate page-agent-sdk
+
+Help the user embed `page-agent-sdk` so an AI agent safely edits their page's structured JSON via tools.
+
+## Core concept
+
+The SDK is a **standardized JSON-operation agent**: the integrator declares writable `window` paths + zod schemas; the agent edits them via `set_window_prop` / `edit_window_prop` (jsonPath patches), validated by schema, scoped to the registry, with snapshot rollback. "Editing JSON" becomes structured + validatable + rollbackable, NOT free-form LLM text.
+
+## Workflow
+
+### 1. Choose install method
+
+| Method | When | How |
+|---|---|---|
+| **npm** | module project, tree-shake ok | `npm i page-agent-sdk zod @langchain/openai @langchain/core` → `import { createChatSdk, z } from 'page-agent-sdk'` |
+| **CDN · ESM** (esm.sh) | modular, small, peer auto-resolved | `import { createChatSdk, z } from 'https://esm.sh/page-agent-sdk'` |
+| **CDN · IIFE** (unpkg) | one-line, no build, ~1.4MB all-in | `<script src="https://unpkg.com/page-agent-sdk"></script>` → `ChatSdk.createChatSdk`, `ChatSdk.z` |
+
+See `demo/plain.html` for a framework-agnostic importmap + esm.sh example.
+
+### 2. Declare windowProps + schemas (the key step)
+
+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).
+
+```ts
+import { createChatSdk, z } from 'page-agent-sdk'
+import 'page-agent-sdk/style.css'
+
+window.app = { title: 'Demo', theme: 'light', items: [] }
+
+createChatSdk({
+  container: '#root',
+  llm: { apiKey, baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat' },
+  systemPrompt: 'You are a page assistant; read/write window.app via tools.',
+  windowProps: [
+    { path: 'app.title',  description: '页面标题',  schema: z.string() },
+    { path: 'app.theme',  description: '主题',      schema: z.enum(['light','dark']) },
+    { path: 'app.items', description: '列表项数组', schema: z.array(z.object({ name: z.string(), price: z.number() })) },
+  ],
+}).mount()
+```
+
+For large JSON, prefer `edit_window_prop` (jsonPath patch: set/remove/merge/append) over `set_window_prop` (whole value) — avoids re-sending the entire blob.
+
+### 3. Configure the LLM
+
+`llm` accepts an `LLMConfig` object (`{ apiKey, baseUrl, model, temperature?, maxTokens? }`) or any LangChain `BaseChatModel` instance. Default protocol is OpenAI-compatible (DeepSeek works out of the box). For large JSON edits use low temperature (~0.3).
+
+### 4. Subscribe to events (replace polling)
+
+Two complementary ways to react to SDK changes from the host page:
+
+```ts
+const sdk = createChatSdk({
+  onEvent(e) { if (e.type === 'window_prop_change') renderUI() },  // constructor-time, single
+  // ...
+}).mount()
+
+// runtime, multiple listeners, cancellable
+const off = sdk.hook((e) => { if (e.type === 'tool_call') analytics.track(e.name) })
+// off() to unsubscribe
+```
+
+Event types: `window_prop_change` / `message_update` / `tool_call` / `tool_result` / `text` / `round_start` / `done` / `error` (+ stream events in stream mode). `approval_request` is NOT forwarded (UI handles it).
+
+### 5. Headless mode (custom UI, framework-agnostic)
+
+`ui: false` → no built-in dialog; use the reactive `sdk.messages` array + `sdk.send`/`sdk.stream` to build your own UI. Reusable `ChatDialog` / `MessageContent` / `CodePreview` components and `useChat` composable are exported from the entry for custom UIs.
+
+### 6. Capabilities & presets
+
+- `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.
+
+## References (read as needed)
+
+- `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` — full options reference (onEvent/hook/server-side/checkpoint/approval/verify/subagent/MCP)
+- `examples/<demo>/` — runnable demos (page-demo, nested-demo, subagent-demo, mcp-demo, planner-demo, toolsets-demo, human-confirm-demo)
+- `demo/plain.html` — framework-agnostic CDN integration
+- `CLAUDE.md` — internal dev guide (architecture, conventions)
+
+## Common pitfalls
+
+- **DeepSeek/OpenAI 400 `missing field tool_call_id`**: `ToolMessage` must use snake_case `tool_call_id` (not camelCase). Already handled internally; only relevant if writing custom tool plumbing.
+- **ChatOpenAI params**: use `apiKey` (not `openAIApiKey`), `model` (not `modelName`); `baseUrl` goes via `configuration.baseURL`.
+- **MCP injects 0 tools on first cold visit**: `vite.config.ts` `optimizeDeps.include` pre-declares the SDK sub-paths; if you fork the config, keep those entries or the first MCP page load injects nothing (reload fixes it).
+- **`.env` `VITE_AI_SYSTEM_PROMPT` must be single-line** (dotenv doesn't support multi-line values).
+- **Server-side (Node.js)**: works with `ui:false` + `storage:'memory'` + `capabilities:{windowOps:false,fetch:false}`; `mount()`/`unmount()` guard `window`/`document` access. Provide `globalThis.window` if you enable windowOps in Node.