page-agent-sdk 2.15.0 → 2.16.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "type": "module",
-  "description": "Browser-native AI agent SDK: chat dialog + ReAct tool-calling + schema-validated JSON ops. Vue bundled, framework-agnostic. Works with DeepSeek/OpenAI/MCP.",
+  "description": "AI agent SDK for web pages — embed a chat assistant that edits page data via schema-validated tools. A lighter, framework-agnostic alternative to CopilotKit/LangChain for in-page JSON-editing agents. Vue-bundled; works with DeepSeek, OpenAI, MCP.",
   "main": "./dist/page-agent-sdk.umd.cjs",
   "module": "./dist/page-agent-sdk.js",
   "types": "./types/index.d.ts",
@@ -55,21 +55,41 @@
   "keywords": [
     "ai",
     "agent",
+    "ai-agent",
+    "agent-sdk",
     "llm",
     "chatbot",
     "chat-dialog",
+    "chat-sdk",
     "tool-calling",
+    "function-calling",
     "react-agent",
+    "browser-agent",
+    "in-page-agent",
+    "conversational-editor",
+    "ai-json-editor",
+    "json-editor",
+    "json-patch",
+    "schema-validation",
+    "human-in-the-loop",
     "sdk",
     "browser",
-    "json-editor",
     "low-code",
+    "low-code-builder",
+    "no-code",
+    "visual-builder",
     "page-builder",
     "deepseek",
     "openai",
     "langchain",
+    "langchain-alternative",
+    "langgraph",
+    "langgraph-alternative",
+    "copilotkit",
     "mcp",
-    "schema-validation",
+    "model-context-protocol",
+    "vue",
+    "react",
     "zod"
   ],
   "author": "武浩",

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

@@ -128,6 +128,35 @@ Example: `write({ value: 9.9, patch: { op: 'set', jsonPath: 'items.0.price' } })
 
 `fetch_document` — GET a URL, return cleaned text (HTML→markdown, truncated, offloaded to vfs if large).
 
+## Built-in vfs tools (`capabilities.vfs`, default on)
+
+The virtual file workspace holds tool-result offloads (>6000 chars), agent/integrator drafts, and user files. 2.16.0+ partitions it into three independent LRU pools (`large_results/*` / `drafts/*` / `userFiles`), so offloaded results can't evict drafts or user files.
+
+| Tool | Signature | Purpose |
+|---|---|---|
+| `vfs_read` | `({ path }) => string` | Read a file (path may be returned by a prior offload). |
+| `vfs_write` | `({ path, content, jsonString? }) => meta` | Write/overwrite a file. `jsonString:true` (2.16.0+) validates `content` is valid JSON before writing (invalid → `VFS_JSON_INVALID`, not written). |
+| `vfs_grep` | `({ pattern, paths? }) => matches` | Grep across workspace files. |
+| `vfs_json_read` (2.16.0+) | `({ path, jsonPath? }) => json\|string` | Read a JSON subtree from a vfs file via jsonPath (omit for the whole file). Returns `VFS_JSON_INVALID` if the file isn't valid JSON; `VFS_PATH_NOT_FOUND` if jsonPath doesn't exist. |
+| `vfs_json_patch` (2.16.0+) | `({ path, patches: [{op:'set'\|'remove'\|'merge'\|'append', jsonPath, value?}] }) => meta` | Atomic jsonPath patch inside a vfs file. Applied on a clone; any patch failure → `PATCH_FAILED`, original file unchanged. Avoids re-sending large JSON (delta only). |
+
+## Context compression presets (`contextPreset`)
+
+`contextPreset` is a one-line knob over the `summarization` middleware (ratio-based); `contextOptions` overrides individual fields.
+
+| Preset | When | Profile |
+|---|---|---|
+| `auto` (default) | General chat | window 0.4 / threshold 0.5 / recall Top-3 / LLM summary |
+| `conservative` | Big models / cost | window 0.5 / threshold 0.7 / recall Top-2 / index summary (no LLM) |
+| `aggressive` | Small models / save context | window 0.3 / threshold 0.3 / recall Top-5 |
+| `complex` (2.16.0+) | Multi-step complex tasks / large JSON / long workflows | windowRatio 0.6 / summaryThresholdRatio 0.7 / recall Top-5 / LLM summary; `preserveLastToolResults` defaults to `['describe_data','read','query_data','search_data']` |
+
+```ts
+createChatSdk({ contextPreset: 'complex', contextOptions: { recallTopK: 8 } })
+```
+
+`inspect().contextPreset` (2.16.0+) exposes the effective preset.
+
 ## SdkEvent types (for `onEvent` / `sdk.hook`)
 
 | `type` | Payload | When |

package/types/index.d.ts

@@ -135,6 +135,8 @@ export interface AgentInfo {
   tools: ToolInfo[];
   skills: SkillInfo[];
   data?: DataInfo;
+  /** 当前上下文压缩预设(默认 auto;complex 为多步复杂任务/大 JSON 场景) */
+  contextPreset: 'auto' | 'conservative' | 'aggressive' | 'complex';
   memory: string;
   middleware: string[];
   todos: { content: string; status: string }[];
@@ -464,8 +466,8 @@ export interface ChatSdkOptions {
   mcp?: McpServerConfig[];
   /** 上下文压缩配置(false 关闭;默认 LLM 摘要,失败回退索引摘要) */
   contextOptions?: any;
-  /** 上下文压缩预设档位(默认 'auto'):auto / conservative / aggressive;提供合理默认,contextOptions 细参可覆盖 */
-  contextPreset?: 'auto' | 'conservative' | 'aggressive';
+  /** 上下文压缩预设档位(默认 'auto'):auto / conservative / aggressive / complex(多步复杂任务/大 JSON);提供合理默认,contextOptions 细参可覆盖 */
+  contextPreset?: 'auto' | 'conservative' | 'aggressive' | 'complex';
   /** 摘要压缩专用 LLM(BaseChatModel 实例或 LLMConfig);不传则默认用主 agent 模型(llm) */
   summaryLlm?: any;
   /** 摘要 LLM 温度(默认 0.3) */