page-agent-sdk 2.12.2 → 2.14.0

package/README.md

@@ -8,10 +8,12 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-524%20asserts-brightgreen.svg)](#self-tests)
+[![tests](https://img.shields.io/badge/self%20tests-630%20asserts-brightgreen.svg)](#self-tests)
 
 ---
 
+> 🚀 **Quick start?** → [30-second quickstart](#30-second-quickstart) · [Examples](#examples) · [Options cheat sheet](#createchatsdk-options-cheat-sheet) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)
+
 ## Who is it for
 
 **Low-code / visual builders, form & page designers, CMS, ops consoles** — anywhere "page data is structured, and you want natural language to drive it".
@@ -413,7 +415,8 @@ createChatSdk({
 // sdk.addTool(tool)             // append user tool at runtime (dedup by name)
 // sdk.removeTool(name)          // remove user tool at runtime (built-ins untouched); returns whether removed
 // sdk.setLlm(llm)               // switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider; param BaseChatModel or LLMConfig; rebind + re-resolve model caps)
-// sdk.setMemory(text)           // update 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-evaluate current memory function source (force refresh after RAG doc update); returns latest text
 // sdk.setSubagents(configs)     // replace pre-declared subagents at runtime (regenerates use_<id> delegation tools + rebind; requires subagents:[] at creation)
 // sdk.addSubagent(config)        // append pre-declared subagent at runtime
 // sdk.removeSubagent(id)        // remove pre-declared subagent at runtime; returns whether removed
@@ -425,6 +428,9 @@ After `npm run dev`, visit the corresponding page:
 
 | Example | Entry | Demonstrates |
 |---|---|---|
+| minimal-demo | `/examples/minimal-demo/` | Minimal: 5-line chat dialog, no data ops |
+| rag-demo | `/examples/rag-demo/` | RAG async docs: `memory` accepts async fn to load KB + switch/refresh |
+| headless-demo | `/examples/headless-demo/` | Headless: `ui:false` + self-built UI via `sdk.messages`/`sdk.send` |
 | page-demo | `/` | Self-bootstrapping demo: left JSON reactive page + right chat |
 | nested-demo | `/examples/nested-demo/` | Nested block tree + human confirm + checkpoint |
 | dynamic-demo | `/examples/dynamic-demo/` | Lazy-loaded components with dynamic schemas (`sdk.setData`/``) |
@@ -469,7 +475,7 @@ function switchTo(i: number) {
 ## Self-tests
 
 ```bash
-npm test            # 524 assertions (tsx, source-level; no LLM dependency)
+npm test            # 630 assertions (tsx, source-level; no LLM dependency)
 npm run test:e2e    # 210 integration assertions (node, built dist; covers APIs/options/modules/simple&complex scenes: default systemPrompt(capability overview) / dynamic register + inspect sync / inspect(tools/middleware/subagent/verify/mcp/todos/lastCompression/checkpoints reflect config) / custom tools/middleware/skills/memory injection / runtime dynamic reconfiguration(setTools/addTool/removeTool/setLlm/setMemory/setSubagents reflect) / switchSession(on/off) / shareContext on/off sharing/independent / storage backends + object config / presets(3) / checkpoint / exports complete(39+ fns/components) / util fns usable(isQuotaError/estimateTokens/jpEval/searchJson) / source=builtin / mount boundary / hook multi-listener / llm config / hide/show / error scenes)
 ```
 
@@ -526,6 +532,23 @@ The package ships three builds — pick by integration scenario:
 | UMD | `dist/page-agent-sdk.umd.cjs` | `require()` in Node/legacy bundlers | ~560 KB |
 | IIFE (all-inlined, single file) | `dist/page-agent-sdk.iife.js` | `<script src>` CDN direct include, zero config | ~1.4 MB |
 
+### Import only what you need (subpath exports)
+
+Besides the top-level `import { createChatSdk } from 'page-agent-sdk'`, three subpath entries scope your import to a single capability (the bundler tree-shakes the rest):
+
+| subpath | key exports | use case |
+|---|---|---|
+| `page-agent-sdk/storage` | `createSessionStore` / `createMemoryBackend` / `createWebStorageBackend` / `isQuotaError` | persistence layer only, no Agent |
+| `page-agent-sdk/query` | `jpEval` / `searchJson` / `runSandboxedScript` + all jsonUtils/schemaUtils pure fns | JSON query / sandbox / path helpers |
+| `page-agent-sdk/llm` | `createProxyLlm` + `ProxyLlmMode` / `ProxyLlmOptions` | proxy connection to avoid leaking apiKey |
+
+```js
+import { createSessionStore, createMemoryBackend } from 'page-agent-sdk/storage'
+import { jpEval, searchJson } from 'page-agent-sdk/query'
+```
+
+> All three subpaths currently resolve to the same dist + types (no multi-entry build yet) — clear semantics and per-entry CDN fetch; when a multi-entry build lands, your import paths won't change.
+
 `sideEffects` is set to `["**/*.css"]` only, so bundlers can tree-shake the JS when you import named symbols. Tips to keep your bundle lean:
 
 - **Headless (`ui:false`)**: skip the built-in dialog and render `agent.messages` yourself — you can avoid importing `ChatDialog`/`CodePreview` and drop the CSS (`import 'page-agent-sdk'` without `'page-agent-sdk/style.css'`).

package/README.zh-CN.md

@@ -8,10 +8,12 @@
 
 [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
 [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
-[![tests](https://img.shields.io/badge/self%20tests-524%20asserts-brightgreen.svg)](#自测)
+[![tests](https://img.shields.io/badge/self%20tests-630%20asserts-brightgreen.svg)](#自测)
 
 ---
 
+> 🚀 **快速上手?** → [30 秒上手](#30-秒上手) · [示例](#示例) · [配置项速查](#createchatsdk-配置项速查) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)
+
 ## 适合谁
 
 **低代码 / 可视化搭建平台、表单与页面设计器、CMS、智能运维台**——凡是「页面有可结构化描述的数据，希望用自然语言驱动它变化」的场景。
@@ -358,7 +360,8 @@ createChatSdk({
 // sdk.addTool(tool)             // 运行时追加用户工具(去重 by name)
 // sdk.removeTool(name)          // 运行时移除用户工具(内置不动);返回是否移除成功
 // sdk.setLlm(llm)               // 运行时切换 LLM(配额耗尽切便宜模型/复杂任务切强模型/切 provider;参数 BaseChatModel 或 LLMConfig;rebind + 重解析模型能力)
-// sdk.setMemory(text)           // 运行时更新持久指令 memory(下一轮 augmentPrompt 注入最新)
+// sdk.setMemory(source)         // 运行时更新 memory;支持 string 与同步/异步函数(异步函数后台求值,适合 RAG 加载文档)
+// sdk.refreshMemory()           // 重新求值当前 memory 函数 source(RAG 文档更新后强制刷新);返回最新文本
 // sdk.setSubagents(configs)     // 运行时替换预声明子 agent(重新生成 use_<id> 委派工具 + rebind;需创建时配 subagents:[])
 // sdk.addSubagent(config)        // 运行时追加预声明子 agent
 // sdk.removeSubagent(id)        // 运行时移除预声明子 agent;返回是否移除成功
@@ -370,6 +373,9 @@ createChatSdk({
 
 | 示例 | 入口 | 演示 |
 |---|---|---|
+| minimal-demo | `/examples/minimal-demo/` | 最简集成:5 行加 AI 对话框,无数据操作 |
+| rag-demo | `/examples/rag-demo/` | RAG 异步文档:`memory` 传异步函数加载知识库 + 切换/刷新 |
+| headless-demo | `/examples/headless-demo/` | Headless:`ui:false` + 自建 UI(`sdk.messages`/`sdk.send`) |
 | page-demo | `/` | 自举 demo：左 JSON 响应式页面 + 右对话框 |
 | nested-demo | `/examples/nested-demo/` | 嵌套区块树 + 人工确认 + checkpoint |
 | dynamic-demo | `/examples/dynamic-demo/` | 懒加载组件 + 动态注册 schema（`sdk.setData`/``） |
@@ -414,7 +420,7 @@ function switchTo(i: number) {
 ## 自测
 
 ```bash
-npm test            # 524 项断言（tsx 源码级，不依赖 LLM）
+npm test            # 630 项断言（tsx 源码级，不依赖 LLM）
 npm run test:e2e    # 210 项集成断言（node 跑构建产物 dist；覆盖各 API/配置项/功能模块/简单与复杂场景：默认 systemPrompt(含能力概述) / 动态注册与 inspect 同步 / inspect(tools/middleware/subagent/verify/mcp/todos/lastCompression/checkpoints 反映配置) / 自定义 tools/middleware/skills/memory 注入 / 运行时动态重配置(setTools/addTool/removeTool/setLlm/setMemory/setSubagents 反映) / switchSession(开/未开) / shareContext 开/关共享独立 / storage 后端+对象配置 / presets 三预设 / checkpoint / 导出项完整(39+ 函数/组件) / 工具函数可用(isQuotaError/estimateTokens/jpEval/searchJson) / source=builtin / mount 边界 / hook 多监听器 / llm 配置 / 错误场景）
 ```
 
@@ -471,6 +477,23 @@ createChatSdk({
 | UMD | `dist/page-agent-sdk.umd.cjs` | Node/老 bundler `require` | ~560 KB |
 | IIFE(全量单文件) | `dist/page-agent-sdk.iife.js` | CDN `<script>` 直引,零配置 | ~1.4 MB |
 
+### 按需引入(subpath exports)
+
+除了顶层 `import { createChatSdk } from 'page-agent-sdk'`,三个子路径入口让你只引特定能力(bundler 对未用部分 tree-shaking):
+
+| subpath | 主要导出 | 场景 |
+|---|---|---|
+| `page-agent-sdk/storage` | `createSessionStore` / `createMemoryBackend` / `createWebStorageBackend` / `isQuotaError` | 只要持久化层,不引 Agent |
+| `page-agent-sdk/query` | `jpEval` / `searchJson` / `runSandboxedScript` + jsonUtils/schemaUtils 全部纯函数 | JSON 查询 / 沙箱 / 路径操作工具集 |
+| `page-agent-sdk/llm` | `createProxyLlm` + `ProxyLlmMode` / `ProxyLlmOptions` | 防 apiKey 泄露的代理连接 |
+
+```js
+import { createSessionStore, createMemoryBackend } from 'page-agent-sdk/storage'
+import { jpEval, searchJson } from 'page-agent-sdk/query'
+```
+
+> 三个 subpath 当前指向同一份 dist + types(未拆多入口构建),语义清晰 + 便于 CDN 按入口拉取;未来切多入口构建时 import 路径零迁移。
+
 `sideEffects` 仅标记 `["**/*.css"]`,打包器可对 JS 做 tree-shaking。瘦身建议:
 
 - **headless(`ui:false`)**:不渲染内置对话框,自渲染 `agent.messages` —— 可不引 `ChatDialog`/`CodePreview`,并省略 CSS(`import 'page-agent-sdk'` 不引 `'page-agent-sdk/style.css'`)。