page-agent-sdk 1.1.0 → 1.1.1

package/README.md

@@ -255,6 +255,29 @@ doc/                            # usage-guide / architecture / context-managemen
 CLAUDE.md                       # architecture + gotchas + coding conventions (agent must-read)
 ```
 
+## Skills for AI tools (for integrators)
+
+Two ready-to-use Agent Skills are bundled for integrators using Claude Code / Cursor (or any agent harness that loads `.claude/skills/` / `~/.claude/skills/`). They teach 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 |
+| `page-agent-sdk-release` | Releasing a new version (bump → build → test → push gitee/github → npm publish → verify) — for maintainers |
+
+**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-* ~/.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-*'
+mv skills/page-agent-sdk-* ~/.claude/skills/
+```
+
+After install, restart your AI tool; the skills auto-trigger when you ask things like "add page-agent-sdk to my page" or "publish a new version".
+
 ## Architecture
 
 ```mermaid
@@ -315,11 +338,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,29 @@ 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、排查常见坑 |
+| `page-agent-sdk-release` | 发布新版本（bump → 构建 → 测试 → 推 gitee/github → 发 npm → 验证）—— 面向维护者 |
+
+**安装**（任选其一）：
+
+```bash
+# 方式 A —— 从已安装的 npm 包复制
+npm i page-agent-sdk
+cp -R node_modules/page-agent-sdk/skills/page-agent-sdk-* ~/.claude/skills/
+
+# 方式 B —— 从仓库下载（无需安装）
+curl -L https://github.com/whyymj/chat-sdk/tarball/master | tar xz --strip-components=1 --wildcards '*/skills/page-agent-sdk-*'
+mv skills/page-agent-sdk-* ~/.claude/skills/
+```
+
+安装后重启 AI 工具；当你说「把 page-agent-sdk 加到我的页面」「发布新版本」等时 skill 自动触发。
+
 ## 架构
 
 ```mermaid
@@ -260,11 +283,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.1",
   "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.

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

@@ -0,0 +1,44 @@
+---
+name: page-agent-sdk-release
+description: Release a new version of the page-agent-sdk npm package and push to its two git remotes (Gitee + GitHub). Use when the user wants to publish/ship a new version, bump the version, build + test before release, push to gitee/github, or follow the project's release checklist. Covers the full flow: code changes → sync zh/en docs → bump semver → build + self-test → commit → push Gitee → push GitHub → npm publish → verify.
+---
+
+# Release page-agent-sdk
+
+Execute the project's release checklist end-to-end. The authoritative, detailed checklist lives in `CLAUDE.md` → "发布流程 checklist"; read that section first, then follow the steps below.
+
+## Two remotes (do NOT mix them up)
+
+| remote | URL | role |
+|---|---|---|
+| `origin` | gitee.com/whyymj/**chat-agent**.git | daily storage, keeps all granular commits |
+| `github` | github.com/whyymj/**chat-sdk**.git | official open-source, receives curated commits |
+
+Personal notes (`doc/待确认问题.md`) are gitignored — Gitee only, never GitHub.
+
+## Release checklist (in order)
+
+1. **Code**: edit `src/`, sync `types/index.d.ts` (hand-maintained), update exports in `src/core/index.ts`.
+2. **Docs (sync zh + en, never single-side)**:
+   - `README.md` (en) / `README.zh-CN.md` (zh) — features, usage, scenarios
+   - `doc/README.md` (zh) / `doc/README.en.md` (en) — doc index
+   - `doc/usage-guide.md` (zh) / `doc/usage-guide.en.md` (en) — usage guide
+   - `CLAUDE.md` — internal dev guide/architecture
+   - Keep language toggle links bidirectional.
+3. **Bump version**: `npm version patch|minor|major --no-git-tag-version` (semver: minor for new API, major for breaking, patch for fix). Never republish the same version.
+4. **Build + self-test**: `npm run build` (= `build:lib` + `build:iife`) then `npm test` (341 assertions must pass). Run `npm pack --dry-run` to confirm the tarball excludes `.env` / `src` / `examples` / notes.
+5. **Commit**: `git add -A && git commit -m "feat/fix/docs: ..."` (conventional style).
+6. **Push Gitee** (daily storage): `git push origin master`. If you just rebased and rewrote history → `git push --force-with-lease origin master` (personal repo, safe).
+7. **Push GitHub** (official): `git push github master`. If rejected as `non-fast-forward` → `git fetch github master && git pull --rebase github master` then push again.
+8. **Publish to npm**: `npm publish` (`publishConfig.registry` is locked to the official npm registry, unaffected by the machine's default private registry).
+9. **Verify**: `npm view page-agent-sdk version` (confirm latest) + a temp dir `npm i page-agent-sdk` to confirm it installs + imports.
+
+## npm credentials gotchas
+
+- Account `whyymj` has 2FA enabled. Use an **Automation Access Token** (npmjs.com → Access Tokens → Classic → Automation, bypasses OTP); write to user-level `~/.npmrc` via `npm config set //registry.npmjs.org/:_authToken <token> --location=user`. Revoke after use. Never commit tokens or store them in the project dir.
+- `npm login` / `npm whoami` require `--registry=https://registry.npmjs.org/` (machine default may be a private registry).
+
+## References
+
+- `CLAUDE.md` → "发布流程 checklist" / "双远程仓库与发布约定" / "npm 发布约定" — authoritative details.
+- `package.json` → `publishConfig`, `exports`, `files`, `peerDependencies`.