page-agent-sdk 1.0.2 → 1.1.1

package/package.json

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

package/types/index.d.ts

@@ -42,6 +42,25 @@ export type StreamEvent =
 
 export type StreamHandler = (event: StreamEvent) => void;
 
+/**
+ * SDK 事件(供 createChatSdk({ onEvent }) 订阅常用时机)。
+ * 复用 StreamEvent(round_start/reasoning/text/tool_call/tool_result/subagent/done;approval_request 不外发)
+ * + 额外时机:window_prop_change / message_update / error。
+ */
+export type SdkEvent =
+  | { type: 'round_start'; round: number }
+  | { type: 'reasoning'; delta: string }
+  | { type: 'text'; delta: string }
+  | { type: 'tool_call'; name: string; args: any }
+  | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error' }
+  | { type: 'subagent'; taskId: string; label: string; kind: 'tool_call' | 'tool_result'; name: string; args?: any; result?: string; status?: 'done' | 'error' }
+  | { type: 'done'; content: string }
+  | { type: 'window_prop_change'; path: string; operation: 'set' | 'edit' | 'delete' | 'restore'; value?: unknown }
+  | { type: 'message_update'; count: number }
+  | { type: 'error'; message: string };
+
+export type SdkEventHandler = (event: SdkEvent) => void;
+
 /** 调试日志(与 harness/createAgent 的 DebugLog 一致) */
 export interface DebugLog {
   timestamp: number;
@@ -336,6 +355,12 @@ export interface ChatSdkOptions {
   summaryMaxTokens?: number;
   /** 摘要 LLM 超时毫秒(默认 15000;超时回退索引摘要) */
   summaryTimeoutMs?: number;
+  /**
+   * SDK 事件回调:订阅常用时机(window 属性变化 / 消息更新 / 工具调用 / 流式文本 / 轮次 / 错误)。
+   * UI 与 headless 模式均生效;用于外部联动(宿主页面响应式刷新、埋点、日志),替代轮询。
+   * approval_request 不外发(UI 已处理)。
+   */
+  onEvent?: SdkEventHandler;
   /** 流式输出(默认 true);false 时等整段回复再显示 */
   streaming?: boolean;
   title?: string;
@@ -356,6 +381,8 @@ export interface ChatSdk {
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */
   listCheckpoints(): CheckpointMeta[];
+  /** 运行时订阅 SDK 事件(可多个监听器,返回取消函数);与构造时 onEvent 互补 */
+  hook(handler: SdkEventHandler): () => void;
 }
 
 export declare function createChatSdk(options: ChatSdkOptions): ChatSdk;