page-agent-sdk 2.12.2 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.12.2",
+  "version": "2.14.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.",
   "main": "./dist/page-agent-sdk.umd.cjs",
@@ -17,6 +17,18 @@
       "import": "./dist/page-agent-sdk.js",
       "require": "./dist/page-agent-sdk.umd.cjs"
     },
+    "./storage": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/page-agent-sdk.js"
+    },
+    "./query": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/page-agent-sdk.js"
+    },
+    "./llm": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/page-agent-sdk.js"
+    },
     "./style.css": "./dist/page-agent-sdk.css"
   },
   "files": [
@@ -76,6 +88,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@playwright/test": "^1.62.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",

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

@@ -296,6 +296,20 @@ sdk.setLlm(otherChatModel)                          // or pass a BaseChatModel i
 sdk.setMemory('User is VIP; prefer concise answers; use incremental patch when editing.')
 sdk.setMemory('')   // clear (empty string skips injection)
 
+// 3.5 Memory async function source (RAG): load knowledge base doc asynchronously
+//     - Async fn evaluated in background on first beforeAgent, cached afterwards
+//     - refreshMemory() forces re-evaluation (e.g. after KB doc updated)
+createChatSdk({
+  memory: async () => await fetch('/kb/faq.md').then((r) => r.text()),
+  /* ... */
+})
+sdk.setMemory(async () => await fetch('/kb/faq-v2.md').then((r) => r.text()))  // switch KB
+await sdk.refreshMemory()   // force re-fetch after KB doc updated
+// Sync fn reads runtime variable (cached on first eval; refresh to re-evaluate)
+let lang = 'zh'
+sdk.setMemory(() => `请用${lang}回答。`)
+lang = 'en'; await sdk.refreshMemory()  // re-evaluate with new lang
+
 // 4. Subagents: runtime add/remove pre-declared subagents (requires subagents:[] at creation)
 //    Pass subagents: [] (empty array) at creation to enable the controller for dynamic add later.
 sdk.addSubagent({ id: 'translator', description: '中英互译子 agent', systemPrompt: '你是翻译助手。' })

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

@@ -23,7 +23,8 @@
 | `addTool(tool)` | `(tool: StructuredToolInterface) => void` | Append user tool at runtime (dedup by name; built-ins untouched). |
 | `removeTool(name)` | `(name: string) => boolean` | Remove user tool at runtime (built-ins untouched). Returns whether removed. |
 | `setLlm(llm)` | `(llm: BaseChatModel \| LLMConfig) => void` | Switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig` (constructs `ChatOpenAI` internally). Rebinds tools + re-resolves model caps (`contextWindow`/`maxOutputTokens`). `summaryLlm` unaffected. If new model lacks `bindTools`, tool-calling degrades (agent stays up). |
-| `setMemory(text)` | `(text: string) => void` | Update persistent memory directive at runtime (next `augmentPrompt` injects latest; `setMemory('')` clears). |
+| `setMemory(source)` | `(source: string \| (() => string \| Promise<string>)) => void` | Update memory at runtime. Supports `string` and sync/async function (async fn evaluated in background, fits RAG doc loading). `setMemory('')` clears. |
+| `refreshMemory()` | `() => Promise<string>` | Re-evaluate current memory function source (force refresh after RAG doc update). String source returns current value. |
 | `setSubagents(configs)` | `(configs: SubagentConfig[]) => void` | Runtime swap pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation (else controller is null, setter warns, no throw). |
 | `addSubagent(config)` | `(config: SubagentConfig) => void` | Append pre-declared subagent at runtime (duplicate id warns & skips). Requires `subagents:[]` at creation. |
 | `removeSubagent(id)` | `(id: string) => boolean` | Remove pre-declared subagent at runtime (by id). Returns whether removed. Requires `subagents:[]` at creation. |
@@ -175,7 +176,7 @@ createChatSdk({
 - **Runtime dynamic reconfiguration (zero-breakage; not calling = current behavior)**: beyond data/skills, you can also dynamically reconfigure tools / LLM / memory / subagents at runtime without rebuilding the agent:
   - `sdk.setTools(tools)` / `addTool(tool)` / `removeTool(name)` — swap/append/remove user tools (built-ins untouched; internal `rebindTools` re-binds to LLM; next round uses new set). Use cases: per-permission tool groups, business-stage gating, A/B experiments.
   - `sdk.setLlm(llm)` — switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig`. Rebinds tools + re-resolves model caps. `summaryLlm` unaffected.
-  - `sdk.setMemory(text)` — update the persistent memory directive at runtime (next `augmentPrompt` injects latest).
+  - `sdk.setMemory(source)` — update memory at runtime; supports `string` and sync/async function (async fn evaluated in background, fits RAG doc loading). `sdk.refreshMemory()` re-evaluates the current function source (force refresh after RAG doc update).
   - `sdk.setSubagents(configs)` / `addSubagent(config)` / `removeSubagent(id)` — swap/append/remove pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation.
   - All setters trigger `infoTick++` → DebugDrawer refreshes; `inspect()` reflects the latest tools/model/memory/subagent.subagents.
 

package/types/index.d.ts

@@ -413,7 +413,8 @@ export interface ChatSdkOptions {
   skills?: SkillSpec[];
   /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
   skillStorage?: SkillStoreConfig | false;
-  memory?: string;
+  /** AGENTS.md 风格持久指令。支持 string 与同步/异步函数(异步函数适合加载 RAG 文档) */
+  memory?: string | (() => string | Promise<string>);
   data?: DataConfig;
   permissions?: PermissionRule[];
   /** 自定义中间件(注入到内置中间件之后;可拦截/观察模型调用、工具、prompt) */
@@ -559,8 +560,10 @@ export interface ChatSdk {
   removeTool(name: string): boolean;
   /** 运行时切换 LLM(BaseChatModel 或 LLMConfig);rebind + 重解析能力 + infoTick */
   setLlm(llm: ChatModelLike | LLMConfig): void;
-  /** 运行时更新 memory 文本;立即生效 + infoTick */
-  setMemory(text: string): void;
+  /** 运行时更新 memory;支持 string 与同步/异步函数(异步函数后台求值,下一轮 beforeAgent 前就绪) */
+  setMemory(source: string | (() => string | Promise<string>)): void;
+  /** 重新求值当前 memory 函数 source(RAG 文档更新后强制刷新);返回最新文本 */
+  refreshMemory(): Promise<string>;
   /** 运行时替换预声明子 agent 列表(重新生成委派工具 + rebind);需创建时配 subagents:[] */
   setSubagents(configs: SubagentConfig[]): void;
   /** 运行时追加预声明子 agent(id 重复 warn 跳过);需创建时配 subagents:[] */
@@ -598,6 +601,16 @@ export interface ConflictInfo {
 }
 
 export declare function createChatSdk(options: ChatSdkOptions): ChatSdk;
+// ============ system prompt 构建(promptBuilder,refactor-module-extraction 从 createChatSdk 抽离)============
+/** 默认 systemPrompt(用户未传 systemPrompt 时用);含身份 + 能力概述 + 可靠写入规则 */
+export declare const DEFAULT_SYSTEM_PROMPT: string;
+/** 拼接「可操作数据」段(从 data schema .describe() 自动提取注入) */
+export declare function buildDataPrompt(data: DataConfig | undefined): string;
+/**
+ * 统一 systemPrompt base 段入口:处理 appendReliableWriteRules 分支 + '---' 分割线。
+ * 传 systemPrompt 默认追加 reliableWriteRules(设 appendReliableWriteRules:false 关闭);不传用 DEFAULT_SYSTEM_PROMPT(已内置)。纯函数。
+ */
+export declare function buildSystemPrompt(opts: { systemPrompt?: string; appendReliableWriteRules?: boolean }): string;
 export declare function defineTool(opts: {
   name: string;
   description: string;
@@ -606,6 +619,57 @@ export declare function defineTool(opts: {
 }): any;
 export declare function createDataOps(config: DataConfig, opts?: DataOpsOptions): any[];
 export declare function filterByToolMode(tools: any[], mode?: 'simple' | 'advanced' | 'minimal'): any[];
+// ============ 通用 JSON 操作纯函数(jsonUtils,refactor-module-extraction 从 dataOps 抽离;零依赖,经 ./query subpath 按需引入)============
+export type EditOp = 'set' | 'remove' | 'merge' | 'append';
+export declare const UNSAFE_KEYS: Set<string>;
+export declare function isUnsafePath(path: string): boolean;
+export declare function safeMerge(target: Record<string, any>, src: unknown): void;
+export declare function getByPath(obj: unknown, path: string): unknown;
+export declare function setByPath(obj: unknown, path: string, value: unknown): void;
+export declare function deleteByPath(obj: unknown, path: string): boolean;
+export declare function deepClone<T>(v: T): T;
+export declare function maybeParseValue(v: unknown): { parsed?: unknown; parseError?: unknown };
+export declare function projectFields(obj: unknown, fields: string[]): unknown;
+export declare function limitDepth(obj: unknown, depth: number): unknown;
+export declare function safeStringify(value: unknown, maxLen?: number): string;
+export declare function hashValue(value: unknown): string;
+export declare function applyPatchToClone(clone: any, op: EditOp, jsonPath: string, value: unknown): string | null;
+export declare function applyPatchToLive(bind: any, op: EditOp, jsonPath: string, value: unknown): void;
+export declare function restoreLive(bind: any, snapshotVal: unknown): void;
+export declare function restoreInPlace(live: Record<string, unknown> | unknown[], snapshotVal: unknown): void;
+// ============ schema 白名单投影纯函数(schemaUtils,refactor-module-extraction 从 dataOps 抽离)============
+export declare function getSchemaTopKeys(schema: any): string[] | null;
+export declare function isPathAllowed(jsonPath: string, schema: any | null, allowKeys: string[] | null): boolean;
+export declare function unwrapSchema(schema: any): any;
+export declare function getSchemaAtPath(schema: any, jsonPath: string): any | null;
+export declare function projectBySchemaDeep(obj: unknown, schema: any | null): unknown;
+export declare function projectBySchema(obj: unknown, allowKeys: string[] | null): unknown;
+// ============ 上下文索引纯函数(contextIndex,refactor-module-extraction 期二 从 useContextManager 抽离)============
+export declare const STOP_WORDS: Set<string>;
+export declare function tokenize(text: string): string[];
+export declare function estimateMessageTokens(m: any): number;
+export declare function estimateRoundTokens(r: any): number;
+export declare function indexSummarize(older: any[], preserve?: Set<string>): string;
+export declare function recallRounds(older: any[], query: string, topK: number): any[];
+// ============ LLM 解析(llmResolver,refactor-module-extraction 期二 从 createChatSdk 抽离)============
+export declare function isChatModel(v: unknown): boolean;
+export declare function resolveLlm(options: any): { modelCaps: any; summaryLlmInvoke: ((prompt: string) => Promise<string>) | undefined };
+// ============ 乐观锁冲突管理器(conflictManager,refactor-module-extraction 期二 从 createChatSdk 抽离)============
+export interface ConflictManager {
+  pendingConflict: import('vue').Ref<any | null>;
+  set(info: any): Promise<any>;
+  resolve(action: any): void;
+}
+export declare function createConflictManager(getEmit?: () => (((e: any) => void) | undefined)): ConflictManager;
+// ============ 配置解析 + 事件系统(optionsResolver/events,refactor-module-extraction 期三)============
+export declare function resolveStorage(storage: any): any | null;
+export declare function resolveDialogConfig(opts: any): any;
+export interface SdkEvents {
+  listeners: Set<(e: any) => void>;
+  emit: (e: any) => void;
+  hook(handler: (e: any) => void): () => void;
+}
+export declare function createSdkEvents(onEvent?: (e: any) => void): SdkEvents;
 export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean } | undefined, dataOps: any[], fetchDocs: any[]): any[];
 export declare function createUsageHintsMiddleware(caps: { planning?: boolean; dataOps?: boolean; subagent?: boolean } | undefined, hasDataOps: boolean, toolMode?: 'simple' | 'advanced' | 'minimal'): any;
 export declare const fetchDocTools: any[];
@@ -618,6 +682,8 @@ export declare function detectGarbledToolCall(content: string): boolean;
 export declare function createSubagentMiddleware(opts: any): any;
 export declare function createVerifyMiddleware(opts: VerifyMiddlewareOptions): any;
 export declare function createWriteBackCheck(opts?: WriteBackCheckOptions): VerifyCheck;
+export declare function createMemoryMiddleware(memory?: string | (() => string | Promise<string>)): any;
+export type MemorySource = string | (() => string | Promise<string>);
 export declare const presets: Record<string, any>;
 /** systemPrompt 辅助片段(标准化最佳实践,拼进 systemPrompt 降低写错门槛) */
 export declare const systemPromptHelpers: {