page-agent-sdk 2.12.2 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +9 -3
  2. package/README.zh-CN.md +9 -3
  3. package/dist/page-agent-sdk.iife.js +69 -69
  4. package/dist/page-agent-sdk.js +25 -9
  5. package/dist/page-agent-sdk.umd.cjs +3 -3
  6. package/package.json +1 -1
  7. package/skills/page-agent-sdk-integrate/references/advanced.md +14 -0
  8. package/skills/page-agent-sdk-integrate/references/api.md +3 -2
  9. package/types/index.d.ts +8 -3
package/README.md CHANGED
@@ -8,10 +8,12 @@
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
10
10
  [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
11
- [![tests](https://img.shields.io/badge/self%20tests-524%20asserts-brightgreen.svg)](#self-tests)
11
+ [![tests](https://img.shields.io/badge/self%20tests-537%20asserts-brightgreen.svg)](#self-tests)
12
12
 
13
13
  ---
14
14
 
15
+ > 🚀 **Quick start?** → [30-second quickstart](#30-second-quickstart) · [Examples](#examples) · [Options cheat sheet](#createchatsdk-options-cheat-sheet) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)
16
+
15
17
  ## Who is it for
16
18
 
17
19
  **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({
413
415
  // sdk.addTool(tool) // append user tool at runtime (dedup by name)
414
416
  // sdk.removeTool(name) // remove user tool at runtime (built-ins untouched); returns whether removed
415
417
  // 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)
416
- // sdk.setMemory(text) // update persistent memory directive at runtime (next augmentPrompt injects latest)
418
+ // sdk.setMemory(source) // update memory at runtime; supports string and sync/async function (async fn evaluated in background, fits RAG doc loading)
419
+ // sdk.refreshMemory() // re-evaluate current memory function source (force refresh after RAG doc update); returns latest text
417
420
  // sdk.setSubagents(configs) // replace pre-declared subagents at runtime (regenerates use_<id> delegation tools + rebind; requires subagents:[] at creation)
418
421
  // sdk.addSubagent(config) // append pre-declared subagent at runtime
419
422
  // sdk.removeSubagent(id) // remove pre-declared subagent at runtime; returns whether removed
@@ -425,6 +428,9 @@ After `npm run dev`, visit the corresponding page:
425
428
 
426
429
  | Example | Entry | Demonstrates |
427
430
  |---|---|---|
431
+ | minimal-demo | `/examples/minimal-demo/` | Minimal: 5-line chat dialog, no data ops |
432
+ | rag-demo | `/examples/rag-demo/` | RAG async docs: `memory` accepts async fn to load KB + switch/refresh |
433
+ | headless-demo | `/examples/headless-demo/` | Headless: `ui:false` + self-built UI via `sdk.messages`/`sdk.send` |
428
434
  | page-demo | `/` | Self-bootstrapping demo: left JSON reactive page + right chat |
429
435
  | nested-demo | `/examples/nested-demo/` | Nested block tree + human confirm + checkpoint |
430
436
  | dynamic-demo | `/examples/dynamic-demo/` | Lazy-loaded components with dynamic schemas (`sdk.setData`/``) |
@@ -469,7 +475,7 @@ function switchTo(i: number) {
469
475
  ## Self-tests
470
476
 
471
477
  ```bash
472
- npm test # 524 assertions (tsx, source-level; no LLM dependency)
478
+ npm test # 537 assertions (tsx, source-level; no LLM dependency)
473
479
  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)
474
480
  ```
475
481
 
package/README.zh-CN.md CHANGED
@@ -8,10 +8,12 @@
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
10
10
  [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/page-agent-sdk/blob/master/LICENSE)
11
- [![tests](https://img.shields.io/badge/self%20tests-524%20asserts-brightgreen.svg)](#自测)
11
+ [![tests](https://img.shields.io/badge/self%20tests-537%20asserts-brightgreen.svg)](#自测)
12
12
 
13
13
  ---
14
14
 
15
+ > 🚀 **快速上手?** → [30 秒上手](#30-秒上手) · [示例](#示例) · [配置项速查](#createchatsdk-配置项速查) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)
16
+
15
17
  ## 适合谁
16
18
 
17
19
  **低代码 / 可视化搭建平台、表单与页面设计器、CMS、智能运维台**——凡是「页面有可结构化描述的数据，希望用自然语言驱动它变化」的场景。
@@ -358,7 +360,8 @@ createChatSdk({
358
360
  // sdk.addTool(tool) // 运行时追加用户工具(去重 by name)
359
361
  // sdk.removeTool(name) // 运行时移除用户工具(内置不动);返回是否移除成功
360
362
  // sdk.setLlm(llm) // 运行时切换 LLM(配额耗尽切便宜模型/复杂任务切强模型/切 provider;参数 BaseChatModel 或 LLMConfig;rebind + 重解析模型能力)
361
- // sdk.setMemory(text) // 运行时更新持久指令 memory(下一轮 augmentPrompt 注入最新)
363
+ // sdk.setMemory(source) // 运行时更新 memory;支持 string 与同步/异步函数(异步函数后台求值,适合 RAG 加载文档)
364
+ // sdk.refreshMemory() // 重新求值当前 memory 函数 source(RAG 文档更新后强制刷新);返回最新文本
362
365
  // sdk.setSubagents(configs) // 运行时替换预声明子 agent(重新生成 use_<id> 委派工具 + rebind;需创建时配 subagents:[])
363
366
  // sdk.addSubagent(config) // 运行时追加预声明子 agent
364
367
  // sdk.removeSubagent(id) // 运行时移除预声明子 agent;返回是否移除成功
@@ -370,6 +373,9 @@ createChatSdk({
370
373
 
371
374
  | 示例 | 入口 | 演示 |
372
375
  |---|---|---|
376
+ | minimal-demo | `/examples/minimal-demo/` | 最简集成:5 行加 AI 对话框,无数据操作 |
377
+ | rag-demo | `/examples/rag-demo/` | RAG 异步文档:`memory` 传异步函数加载知识库 + 切换/刷新 |
378
+ | headless-demo | `/examples/headless-demo/` | Headless:`ui:false` + 自建 UI(`sdk.messages`/`sdk.send`) |
373
379
  | page-demo | `/` | 自举 demo：左 JSON 响应式页面 + 右对话框 |
374
380
  | nested-demo | `/examples/nested-demo/` | 嵌套区块树 + 人工确认 + checkpoint |
375
381
  | dynamic-demo | `/examples/dynamic-demo/` | 懒加载组件 + 动态注册 schema（`sdk.setData`/``） |
@@ -414,7 +420,7 @@ function switchTo(i: number) {
414
420
  ## 自测
415
421
 
416
422
  ```bash
417
- npm test # 524 项断言（tsx 源码级，不依赖 LLM）
423
+ npm test # 537 项断言（tsx 源码级，不依赖 LLM）
418
424
  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 配置 / 错误场景）
419
425
  ```
420
426