page-agent-sdk 3.26.0 → 3.27.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 (11) hide show
  1. package/README.md +35 -69
  2. package/README.zh-CN.md +35 -12
  3. package/dist/page-agent-sdk.headless.js +3 -2
  4. package/dist/page-agent-sdk.iife.js +143 -143
  5. package/dist/page-agent-sdk.js +3286 -1817
  6. package/dist/page-agent-sdk.legacy.js +15673 -14204
  7. package/dist/page-agent-sdk.umd.cjs +53 -53
  8. package/dist/style.css +10 -1
  9. package/package.json +2 -1
  10. package/style.css +10 -1
  11. package/types/index.d.ts +16 -0
package/README.md CHANGED
@@ -8,11 +8,33 @@
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-2428%20asserts-brightgreen.svg)](#self-tests)
11
+ [![tests](https://img.shields.io/badge/self%20tests-2437%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-兼容端点)
15
+ > 🚀 **Quick start?** → [30-second quickstart](#30-second-quickstart) · [Examples](#examples) · [Options cheat sheet](#createchatsdk-options-cheat-sheet) · [Usage map](#usage-map-task--where)
16
+
17
+ ## Usage map (task → where)
18
+
19
+ Starting point for both humans and AI agents (Claude Code / Cursor): find the feature you need, follow the link. Details live in sub-docs — [doc/](https://github.com/whyymj/page-agent-sdk/blob/master/doc/README.en.md) index.
20
+
21
+ | I want to… | See |
22
+ |---|---|
23
+ | Just add an AI chat box (no data ops) | [30-second quickstart](#30-second-quickstart) · `examples/minimal-demo` |
24
+ | AI edits my page data (schema + bind) | [Design: three-layer split](#design-the-schema--systemprompt--skill-three-layer-split) · [usage-guide §6.1](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md#61-data-ops-single-main-object--let-the-agent-edit-your-json) |
25
+ | Custom tools / skills / memory / middleware | [Extension points](#extension-points) · [usage-guide §6.2–6.4, §7](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) |
26
+ | Connect LLM (DeepSeek/OpenAI-compatible/Claude/proxy, no apiKey leak) | [Configuration](#configuration) · [usage-guide §8.6 Proxy](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) · `examples/proxy-demo` |
27
+ | Headless / Node.js (own UI, no dialog) | [Bundle size & tree-shaking](#bundle-size--tree-shaking) (headless subpath) · `examples/headless-demo`, `examples/customize-demo` |
28
+ | Old bundler (webpack ≤4 / vue-cli 2-3) | [Bundle size & tree-shaking](#bundle-size--tree-shaking) (legacy subpath, es2017 all-inlined) |
29
+ | HTML/code components (AI writes page blocks) | [Capability packs](#createchatsdk-options-cheat-sheet) (`createHtmlSubagent`, auto-registered 3.9+) · `examples/html-page-demo`, `examples/complex-demo` |
30
+ | RAG / MCP tools | [Capability packs](#createchatsdk-options-cheat-sheet) (`createRagSubagent`, `mcp`) · `examples/rag-demo` |
31
+ | Customize UI (theme / icons / i18n / button labels) | [`DialogConfig` fields](#dialogconfig-fields) · [usage-guide §6.15](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md#615-ui-customization--i18n-icons--theme--language--message-overrides-317321) · `examples/i18n-demo` |
32
+ | Sessions / persistence (IndexedDB) | [options cheat sheet](#createchatsdk-options-cheat-sheet) (`storage`/`session`) · `examples/session-history-demo` |
33
+ | Long conversations / big JSON (context & compression) | [usage-guide §6.8](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) · [context-management doc](https://github.com/whyymj/page-agent-sdk/blob/master/doc/context-management.md) |
34
+ | Events / audit / token usage | [Configuration](#configuration) (`onEvent`/`onAudit`/`sdk.usage`) · [usage-guide §6.9](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) |
35
+ | Unattended automation / batch / budget | [options cheat sheet](#createchatsdk-options-cheat-sheet) (`capabilities.automation`, `sdk.batch`) · [usage-guide automation section](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) |
36
+ | Debug (prompts / tool IO / context) | `debug: true` + built-in DebugDrawer · `sdk.inspect()` / `sdk.debugLogs` / `sdk.inspectContext()` |
37
+ | Everything, full API | [Agent Integration Cheat Sheet](#agent-integration-cheat-sheet-for-ai-agents) · [usage-guide](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.en.md) · [doc index](https://github.com/whyymj/page-agent-sdk/blob/master/doc/README.en.md) |
16
38
 
17
39
  ## Who is it for
18
40
 
@@ -80,7 +102,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
80
102
  | Subagents | ✅ | ❌ | ✅ (manual) | ✅ | manual |
81
103
  | Context compression | ✅ 4-layer built-in | ❌ | ❌ | ✅ checkpointer | ❌ |
82
104
  | In-browser persistence | ✅ IndexedDB | ❌ | ❌ | ❌ | ❌ |
83
- | Bundle | ~620 KB ESM / 1.4 MB IIFE | React dep | large | large | none |
105
+ | Bundle | ~963 KB ESM / 2.0 MB IIFE | React dep | large | large | none |
84
106
 
85
107
  > Nuance: CopilotKit is a great choice if you're already on React and want a polished AI-chat UI with backend actions; LangChain / LangGraph are general-purpose agent orchestration (server-side strong). `page-agent-sdk` specifically targets **in-page, schema-validated, rollbackable JSON editing** — that niche is its differentiation.
86
108
 
@@ -251,64 +273,8 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
251
273
  | `onClose` | `() => void` | Drawer mode close callback (default `hide`; pass to override and sync external mount state) |
252
274
  | `theme` | `'light' \| 'dark'` · default `'dark'` | Built-in theme (dark = Ark design palette); fully customizable via `--cs-*` on an ancestor |
253
275
  | `i18n` | `I18nOptions` | **Top-level i18n group (3.22+; replaces `dialog.locale`/`dialog.messages`)**: `locale` switches the built-in message pack — chat surface + Debug drawer + Skill panel + CodePreview; `formatTime` (12h/24h), autoTitle, and the **default systemPrompt** follow (`en-US` → English `DEFAULT_SYSTEM_PROMPT_EN` with a "Respond in English" anchor, so agent replies match the UI language; a custom `systemPrompt` is untouched, but the auto-appended `reliableWriteRules` segment switches to English). `messages` = per-key overrides (priority over the locale pack, e.g. `statusDone: '<b style="color:#10b981">Done ✓</b>'` — values may be inline HTML fragments on rich-text render spots, sanitized via a text allowlist). Full key list (~226 keys) in `DialogMessages` |
254
- | `icons` | `Partial<DialogIcons>` | **Icon customization**: partial override of default emojis (`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️; `assistantAvatar`/`userAvatar` default to built-in SVG, pass a text glyph to replace). Values: plain text (emoji/char) **or an HTML fragment** (starting with `<`, e.g. inline `<svg>`/`<img>` — sanitized via a DOMPurify icon allowlist; event attributes/dangerous protocols stripped); empty string hides the icon; unset keys keep defaults |
255
-
256
- ### Extension points
257
-
258
- ```ts
259
- // ① Custom tool
260
- const myTool = defineTool({ name: 'do_x', description: '...', schema: z.object({...}), handler: (args) => 'result' })
261
- createChatSdk({ tools: [myTool], /*...*/ })
262
-
263
- // ② Custom skill (progressive disclosure: load_skill fetches details on demand)
264
- const mySkill = defineSkill({ name: 'style_guide', description: 'Brand color spec', body: 'Primary #1f4d3a…' })
265
- // Dynamic skill (skill-external-scripts): exec runs a script on load → inject live data; tools attaches callable tools
266
- // defineSkill({ name: 'orders', getContent: () => 'spec…', exec: { code: '...', context: 'sandbox' }, tools: [() => orderQueryTool] })
267
- createChatSdk({ skills: [mySkill], /*...*/ })
268
-
269
- // ③ Custom middleware (8 hooks: beforeAgent/wrapModelCall/beforeModel/afterModel/wrapToolCall/afterAgent/beforeReturn + augmentPrompt/compressInput/tools)
270
- const mw: Middleware = { name: 'telemetry', afterModel: async (ctx, next) => { await next(ctx); console.log('round done') } }
271
- createChatSdk({ middleware: [mw], /*...*/ })
272
-
273
- // ④ Pre-declared subagents (planner-reflector-executor fixed roles)
274
- createChatSdk({ subagents: [
275
- { id: 'planner', description: 'Creative planner', temperature: 0.9, systemPrompt: '…' },
276
- { id: 'reflector', description: 'Reflective reviewer', temperature: 0.3, systemPrompt: '…' },
277
- ], /*...*/ })
278
- ```
279
-
280
- ### Built-in tools (Agent-callable)
281
-
282
- - **data ops** (default `toolMode:'simple'`): `read` (list/get/describe merged) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `toolMode:'advanced'` also exposes low-level `describe_data` / `get_data` (@deprecated, use read) / `set_data` / `edit_data` (jsonPath patch) / `delete_data` / `restore_data` / `history_data` (with list mode) / `diff_data`
283
- - **window query**: `query_data` (JSONPath) / `search_data` (fuzzy) / `eval_script` (sandboxed)
284
- - **fetch**: `fetch_document`
285
- - **vfs**: `vfs_read` / `vfs_write` / `vfs_edit` / `vfs_ls` / `vfs_glob` / `vfs_grep`
286
- - **planning/skills**: `write_todos` / `define_skill` / `load_skill` (skill can carry `exec` to run a script on load injecting live data + `tools` for repeatedly-callable tools; `exec.context:'host'` requires `capabilities.skillHostScript:true`)
287
- - **human confirm**: `request_human_confirmation` (proactive inquiry, default on)
288
- - **subagents**: `spawn_agent` / `spawn_agents` / `use_<id>` (pre-declared)
289
- - **checkpoint**: `restore_last_checkpoint` / `list_checkpoints`
290
-
291
- ### File structure
292
-
293
- ```
294
- src/core/
295
- ├── sdk/createChatSdk.ts # imperative entry (assembles harness + tools + middleware)
296
- │ sdk/defineTool.ts presets.ts contextPreset.ts
297
- ├── harness/ # in-house ReAct harness (middleware-driven)
298
- │ createAgent.ts middleware.ts state.ts
299
- │ todos.ts skills.ts memory.ts summarization.ts retry.ts
300
- │ subagent.ts verify.ts approval.ts humanConfirm.ts checkpoint.ts
301
- │ permissions.ts usageHints.ts
302
- ├── tools/ # dataOps (schema validation + incremental edit + snapshot + whitelist) / dataSlotQuery / fetchDoc
303
- ├── backends/ # vfs (memory) / storage (IndexedDB + multi-backend + quota eviction)
304
- ├── mcp/client.ts # remote MCP tool integration
305
- ├── composables/ # useChat / useContextManager / useMarkdown
306
- ├── components/ # ChatDialog / MessageContent / CodePreview / DebugDrawer
307
- └── types/index.ts index.ts # types / sole library entry
308
- examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / toolsets-demo / proxy-demo
309
- doc/ # usage-guide / architecture / context-management / architecture-files
310
- CLAUDE.md # architecture + gotchas + coding conventions (agent must-read)
311
- ```
276
+ | `icons` | `Partial<DialogIcons>` | **Icon customization**: partial override of default emojis (`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️; `assistantAvatar`/`userAvatar`/`send` and the header-button keys `newSession`/`history`/`more`/`close` default to built-in SVG — pass emoji/char/HTML fragment to replace; history delete button `sessionDelete` defaults to ✕ text). Values: plain text (emoji/char) **or an HTML fragment** (starting with `<`, e.g. inline `<svg>`/`<img>` — sanitized via a DOMPurify icon allowlist; event attributes/dangerous protocols stripped); empty string hides the icon (button keys treat it as unset, prevents an empty button); unset keys keep defaults |
277
+ | `headerLabels` | `boolean` · default `true` | **Adaptive header-button text labels**: when wide enough (header content ≥440px ≈ dialog ≥472px with default padding), "New chat / History / More" show text+icon; narrower widths fall back to icon-only (close stays icon-only; pure CSS container queries, old browsers gracefully degrade to icon-only); `false` = always icon-only. Button text = i18n `newSession`/`history`/`more` keys (overridable via `i18n.messages`), icons = the four same-named `dialog.icons` keys |
312
278
 
313
279
  ### Extension points
314
280
 
@@ -533,8 +499,8 @@ function switchTo(i: number) {
533
499
  ## Self-tests
534
500
 
535
501
  ```bash
536
- npm test # 2428 assertions (tsx, source-level; no LLM dependency)
537
- npm run test:e2e # 764 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)
502
+ npm test # 2437 assertions (tsx, source-level; no LLM dependency)
503
+ npm run test:e2e # 769 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)
538
504
  ```
539
505
 
540
506
  ## Local npm package test
@@ -586,11 +552,11 @@ The package ships three builds — pick by integration scenario:
586
552
 
587
553
  | Build | File | When to use | Approx. size |
588
554
  |---|---|---|---|
589
- | ESM (bundled, peer external) | `dist/page-agent-sdk.js` | `import` via npm or esm.sh — recommended for module hosts | ~620 KB |
590
- | UMD | `dist/page-agent-sdk.umd.cjs` | `require()` in Node/legacy bundlers | ~560 KB |
591
- | IIFE (all-inlined, single file) | `dist/page-agent-sdk.iife.js` | `<script src>` CDN direct include, zero config | ~1.4 MB |
592
- | **headless ESM** (no UI layer) | `dist/page-agent-sdk.headless.js` | `page-agent-sdk/headless` — pure core for `ui:false` custom UI | **~325 KB** |
593
- | **legacy ESM** (es2017, all-inlined) | `dist/page-agent-sdk.legacy.js` | `page-agent-sdk/legacy` — **webpack ≤4 / vue-cli 2-3 hosts**: `await import('page-agent-sdk/legacy')` lazy chunk, zero transpile/peers | **~2.9 MB** |
555
+ | ESM (bundled, peer external) | `dist/page-agent-sdk.js` | `import` via npm or esm.sh — recommended for module hosts | ~963 KB |
556
+ | UMD | `dist/page-agent-sdk.umd.cjs` | `require()` in Node/legacy bundlers | ~762 KB |
557
+ | IIFE (all-inlined, single file) | `dist/page-agent-sdk.iife.js` | `<script src>` CDN direct include, zero config | ~2.0 MB |
558
+ | **headless ESM** (no UI layer) | `dist/page-agent-sdk.headless.js` | `page-agent-sdk/headless` — pure core for `ui:false` custom UI | **~446 KB** |
559
+ | **legacy ESM** (es2017, all-inlined) | `dist/page-agent-sdk.legacy.js` | `page-agent-sdk/legacy` — **webpack ≤4 / vue-cli 2-3 hosts**: `await import('page-agent-sdk/legacy')` lazy chunk, zero transpile/peers | **~3.0 MB** |
594
560
 
595
561
  ### Import only what you need (subpath exports)
596
562
 
@@ -612,7 +578,7 @@ import { jpEval, searchJson } from 'page-agent-sdk/query'
612
578
 
613
579
  `sideEffects` is set to `["**/*.css"]` only, so bundlers can tree-shake the JS when you import named symbols. Tips to keep your bundle lean:
614
580
 
615
- - **Headless (`ui:false`)**: skip the built-in dialog and render `agent.messages` yourself. For the leanest bundle, import from the **headless subpath** — `import { createChatSdk } from 'page-agent-sdk/headless'` (~325 KB ESM vs ~789 KB main; drops marked/highlight.js/dompurify/ChatDialog you never use at runtime). Same `createChatSdk(options): ChatSdk` signature; pair with `ui:false`. From the main package you can also avoid importing `ChatDialog`/`CodePreview` and drop the CSS (`import 'page-agent-sdk'` without `'page-agent-sdk/style.css'`). **Persistence pitfall**: `sdk.stream` does NOT auto-persist (built-in `useChat` calls `afterRound` via `onPersist`); in a self-built dialog call `sdk.afterRound()` after each turn, otherwise `switchSession` won't restore messages. **Reuse the built-in DebugDrawer** (main package only): `import { DebugDrawer }` — pure-props (`logs=sdk.debugLogs`, `getInfo=()=>sdk.inspect()`, `infoTick=sdk.infoTick`), mount it in your own UI without needing ChatDialog.
581
+ - **Headless (`ui:false`)**: skip the built-in dialog and render `agent.messages` yourself. For the leanest bundle, import from the **headless subpath** — `import { createChatSdk } from 'page-agent-sdk/headless'` (~446 KB ESM vs ~963 KB main; drops marked/highlight.js/dompurify/ChatDialog you never use at runtime). Same `createChatSdk(options): ChatSdk` signature; pair with `ui:false`. From the main package you can also avoid importing `ChatDialog`/`CodePreview` and drop the CSS (`import 'page-agent-sdk'` without `'page-agent-sdk/style.css'`). **Persistence pitfall**: `sdk.stream` does NOT auto-persist (built-in `useChat` calls `afterRound` via `onPersist`); in a self-built dialog call `sdk.afterRound()` after each turn, otherwise `switchSession` won't restore messages. **Reuse the built-in DebugDrawer** (main package only): `import { DebugDrawer }` — pure-props (`logs=sdk.debugLogs`, `getInfo=()=>sdk.inspect()`, `infoTick=sdk.infoTick`), mount it in your own UI without needing ChatDialog.
616
582
  - **Disable unused capabilities**: `capabilities:{ dataOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` — removes the corresponding tool schemas and middleware from the agent prompt (saves tokens, not bytes).
617
583
  - **CDN via esm.sh**: `import { createChatSdk } from 'https://esm.sh/page-agent-sdk'` — peer deps (`zod`, `@langchain/*`) are resolved and deduped by esm.sh automatically; smallest for module scenarios.
618
584
  - **IIFE only for zero-config**: the all-inlined single file is convenient but heaviest; prefer ESM when the host supports modules.
package/README.zh-CN.md CHANGED
@@ -8,11 +8,33 @@
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-2428%20asserts-brightgreen.svg)](#自测)
11
+ [![tests](https://img.shields.io/badge/self%20tests-2437%20asserts-brightgreen.svg)](#自测)
12
12
 
13
13
  ---
14
14
 
15
- > 🚀 **快速上手?** → [30 秒上手](#30-秒上手) · [示例](#示例) · [配置项速查](#createchatsdk-配置项速查) · [LLM 连接](#llm-连接直连--代理--openai-兼容端点)
15
+ > 🚀 **快速上手?** → [30 秒上手](#30-秒上手) · [示例](#示例) · [配置项速查](#createchatsdk-配置项速查) · [用法地图](#用法地图任务--去哪找)
16
+
17
+ ## 用法地图(任务 → 去哪找)
18
+
19
+ 人类与 AI 代理(Claude Code / Cursor)的单入口:按要做的功能找对应文档。详细说明在子文档 [`doc/`](https://github.com/whyymj/page-agent-sdk/blob/master/doc/README.md)(索引)。
20
+
21
+ | 我想… | 去哪 |
22
+ |---|---|
23
+ | 只加个 AI 对话框(不操作数据) | [30 秒上手](#30-秒上手) · `examples/minimal-demo` |
24
+ | AI 读写页面数据(schema + bind) | [三层配合设计](#设计思路schema--systemprompt--skill-三层配合) · [usage-guide §6.1](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md#61-数据操作单主对象让-agent-改你的-json) |
25
+ | 自定义工具 / skill / memory / 中间件 | [扩展点](#扩展点) · [usage-guide §6.2-6.4、§7](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) |
26
+ | 接 LLM(DeepSeek/OpenAI 兼容/Claude/代理防泄 key) | [配置](#配置) · [usage-guide §8.6 代理](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) · `examples/proxy-demo` |
27
+ | Headless / Node.js(自建 UI) | [体积与按需引入](#体积与按需引入)(headless 子路径)· `examples/headless-demo`、`examples/customize-demo` |
28
+ | 老构建链(webpack ≤4 / vue-cli 2-3) | [体积与按需引入](#体积与按需引入)(legacy 子路径,es2017 全量打包) |
29
+ | HTML/代码组件(AI 生成页面块) | [能力包](#createchatsdk-配置项速查)(`createHtmlSubagent`,3.9+ 自动装配)· `examples/html-page-demo`、`examples/complex-demo` |
30
+ | RAG / MCP 工具 | [能力包](#createchatsdk-配置项速查)(`createRagSubagent`、`mcp`)· `examples/rag-demo` |
31
+ | 定制 UI(主题 / 图标 / 国际化 / 按钮文字标签) | [`DialogConfig` 字段表](#dialogconfig-字段) · [usage-guide §6.15](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md#615-ui-定制与国际化图标--主题--语言--文案覆盖317321) · `examples/i18n-demo` |
32
+ | 会话 / 持久化(IndexedDB) | [配置项速查](#createchatsdk-配置项速查)(`storage`/`session`)· `examples/session-history-demo` |
33
+ | 长对话 / 大 JSON(上下文与压缩) | [usage-guide §6.8](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) · [context-management 文档](https://github.com/whyymj/page-agent-sdk/blob/master/doc/context-management.md) |
34
+ | 事件 / 审计 / token 用量 | [配置](#配置)(`onEvent`/`onAudit`/`sdk.usage`)· [usage-guide §6.9](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) |
35
+ | 无人值守自动化 / 批处理 / 预算 | [配置项速查](#createchatsdk-配置项速查)(`capabilities.automation`、`sdk.batch`)· [usage-guide 自动化节](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) |
36
+ | 调试(提示词 / 工具 IO / 上下文构成) | `debug: true` + 内置 DebugDrawer · `sdk.inspect()` / `sdk.debugLogs` / `sdk.inspectContext()` |
37
+ | 全量 API / 逐项深挖 | [Agent 接入速查](#agent-接入速查给-ai-agent-读) · [usage-guide](https://github.com/whyymj/page-agent-sdk/blob/master/doc/usage-guide.md) · [doc 索引](https://github.com/whyymj/page-agent-sdk/blob/master/doc/README.md) |
16
38
 
17
39
  ## 适合谁
18
40
 
@@ -80,7 +102,7 @@
80
102
  | 子 agent | ✅ | ❌ | ✅(手动) | ✅ | 手动 |
81
103
  | 上下文压缩 | ✅ 4 层内置 | ❌ | ❌ | ✅ checkpointer | ❌ |
82
104
  | 浏览器内持久化 | ✅ IndexedDB | ❌ | ❌ | ❌ | ❌ |
83
- | 体积 | ~620KB ESM / 1.4MB IIFE | 依赖 React | 大 | 大 | 无 |
105
+ | 体积 | ~963KB ESM / 2.0MB IIFE | 依赖 React | 大 | 大 | 无 |
84
106
 
85
107
  > 补充：CopilotKit 适合已在 React 生态、想要现成 AI 聊天 UI + 后端 action 的场景；LangChain / LangGraph 是通用 agent 编排（服务端强）。`page-agent-sdk` 专攻**页面内、schema 校验、可回退的 JSON 编辑**——这个细分定位是它的差异点。
86
108
 
@@ -247,7 +269,8 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
247
269
  | `onClose` | `() => void` | 抽屉模式关闭回调(默认 `hide`;传此选项覆盖默认,便于同步外部挂载状态) |
248
270
  | `theme` | `'light' \| 'dark'` · 默认 `'dark'` | 内置主题(dark = 方舟设计稿深色紫调);亦可祖先覆盖 `--cs-*` 完全自定义 |
249
271
  | `i18n` | `I18nOptions` | **顶层国际化配置组(3.22+;原 `dialog.locale`/`dialog.messages` 两键合并至此)**:`locale` 切换内置文案包 —— 聊天面 + Debug 抽屉 + Skill 面板 + 代码预览;`formatTime`(12h/24h)、autoTitle 与**默认 systemPrompt** 跟随(`en-US` → 英文版 `DEFAULT_SYSTEM_PROMPT_EN` 含 "Respond in English" 语言锚,agent 回复语言与 UI 一致;自定义 `systemPrompt` 不受影响,但其自动追加的 `reliableWriteRules` 段切英文)。`messages` = 键级覆盖(优先于 locale 包,如 `statusDone: '<b style="color:#10b981">完成</b>'` —— 富文本渲染位的值支持行内 HTML 片段,文案白名单净化);完整键清单(~226 键)见 `DialogMessages` |
250
- | `icons` | `Partial<DialogIcons>` | **图标自定义**:局部覆盖默认 emoji(`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️;`assistantAvatar`/`userAvatar` 缺省 = 内置 SVG,传文本字形替换)。值为纯文本(emoji/字符)或 **HTML 片段**(以 `<` 开头,如内联 `<svg>`/`<img>`,经 DOMPurify 图标白名单净化,事件属性/危险协议剥除);空串 = 隐藏该图标;未传键用默认 |
272
+ | `icons` | `Partial<DialogIcons>` | **图标自定义**:局部覆盖默认 emoji(`header` 🤖 / `subagent` 🤖 / `subagentProgress` 🧬 / `empty` 💬 / `focus` 🎯 / `queued` 📋 / `queuedEdit` ✏️ / `recommend` 💡 / `conflict` ⚠️;`assistantAvatar`/`userAvatar`/`send` 与顶部按钮四键 `newSession`/`history`/`more`/`close` 缺省 = 内置 SVG,传 emoji/字符/HTML 片段替换;历史删除按钮 `sessionDelete` 缺省 = ✕ 文本)。值为纯文本(emoji/字符)或 **HTML 片段**(以 `<` 开头,如内联 `<svg>`/`<img>`,经 DOMPurify 图标白名单净化,事件属性/危险协议剥除);空串 = 隐藏该图标(按钮键视为未传,防空按钮);未传键用默认 |
273
+ | `headerLabels` | `boolean` · 默认 `true` | **顶部按钮自适应文字标签**:宽度足够(头部内容区 ≥440px,默认 padding 下 ≈ 对话框 ≥472px)时「新建会话/历史记录/更多」展示文字+图标,更窄自动回退纯图标(关闭钮恒纯图标;纯 CSS 容器查询,旧浏览器优雅降级为纯图标);`false` 恒纯图标。按钮文字走 i18n `newSession`/`history`/`more` 键(`i18n.messages` 键级覆盖生效),图标走 `dialog.icons` 同名四键 |
251
274
 
252
275
  ### 扩展点
253
276
 
@@ -479,8 +502,8 @@ function switchTo(i: number) {
479
502
  ## 自测
480
503
 
481
504
  ```bash
482
- npm test # 2428 项断言（tsx 源码级，不依赖 LLM）
483
- npm run test:e2e # 764 项集成断言（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 配置 / 错误场景）
505
+ npm test # 2437 项断言（tsx 源码级，不依赖 LLM）
506
+ npm run test:e2e # 769 项集成断言（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 配置 / 错误场景）
484
507
  ```
485
508
 
486
509
  ## 本地 npm 包测试
@@ -532,11 +555,11 @@ createChatSdk({
532
555
 
533
556
  | 产物 | 文件 | 适用场景 | 大小 |
534
557
  |---|---|---|---|
535
- | ESM(peer 外置) | `dist/page-agent-sdk.js` | npm 或 esm.sh `import`,模块化宿主推荐 | ~620 KB |
536
- | UMD | `dist/page-agent-sdk.umd.cjs` | Node/老 bundler `require` | ~560 KB |
537
- | IIFE(全量单文件) | `dist/page-agent-sdk.iife.js` | CDN `<script>` 直引,零配置 | ~1.4 MB |
538
- | **headless ESM**(无 UI 层) | `dist/page-agent-sdk.headless.js` | `page-agent-sdk/headless` —— `ui:false` 自建 UI 纯核心 | **~325 KB** |
539
- | **legacy ESM**(es2017 全量打包) | `dist/page-agent-sdk.legacy.js` | `page-agent-sdk/legacy` —— **webpack ≤4 / vue-cli 2-3 老构建链宿主**:`await import('page-agent-sdk/legacy')` 懒加载 chunk,零 transpile/零 peer | **~2.9 MB** |
558
+ | ESM(peer 外置) | `dist/page-agent-sdk.js` | npm 或 esm.sh `import`,模块化宿主推荐 | ~963 KB |
559
+ | UMD | `dist/page-agent-sdk.umd.cjs` | Node/老 bundler `require` | ~762 KB |
560
+ | IIFE(全量单文件) | `dist/page-agent-sdk.iife.js` | CDN `<script>` 直引,零配置 | ~2.0 MB |
561
+ | **headless ESM**(无 UI 层) | `dist/page-agent-sdk.headless.js` | `page-agent-sdk/headless` —— `ui:false` 自建 UI 纯核心 | **~446 KB** |
562
+ | **legacy ESM**(es2017 全量打包) | `dist/page-agent-sdk.legacy.js` | `page-agent-sdk/legacy` —— **webpack ≤4 / vue-cli 2-3 老构建链宿主**:`await import('page-agent-sdk/legacy')` 懒加载 chunk,零 transpile/零 peer | **~3.0 MB** |
540
563
 
541
564
  ### 按需引入(subpath exports)
542
565
 
@@ -558,7 +581,7 @@ import { jpEval, searchJson } from 'page-agent-sdk/query'
558
581
 
559
582
  `sideEffects` 仅标记 `["**/*.css"]`,打包器可对 JS 做 tree-shaking。瘦身建议:
560
583
 
561
- - **headless(`ui:false`)**:不渲染内置对话框,自渲染 `agent.messages`。要最精简 bundle,从 **headless 子路径** 引入 —— `import { createChatSdk } from 'page-agent-sdk/headless'`(ESM ~325KB vs 主包 ~789KB;去掉运行时从不使用的 marked/highlight.js/dompurify/ChatDialog)。`createChatSdk(options): ChatSdk` 签名不变,配 `ui:false` 用。从主包引入也可不引 `ChatDialog`/`CodePreview` 并省略 CSS(`import 'page-agent-sdk'` 不引 `'page-agent-sdk/style.css'`)。**持久化坑**:`sdk.stream` 不自动落盘(内置 useChat 经 onPersist 调 afterRound);自建对话框每轮后需手动 `sdk.afterRound()`,否则 `switchSession` 切回丢消息。**复用内置 DebugDrawer**(仅主包):`import { DebugDrawer }`(纯 props:`logs=sdk.debugLogs` / `getInfo=()=>sdk.inspect()` / `infoTick=sdk.infoTick`),在自己的 UI 里挂载,无需 ChatDialog。
584
+ - **headless(`ui:false`)**:不渲染内置对话框,自渲染 `agent.messages`。要最精简 bundle,从 **headless 子路径** 引入 —— `import { createChatSdk } from 'page-agent-sdk/headless'`(ESM ~446KB vs 主包 ~963KB;去掉运行时从不使用的 marked/highlight.js/dompurify/ChatDialog)。`createChatSdk(options): ChatSdk` 签名不变,配 `ui:false` 用。从主包引入也可不引 `ChatDialog`/`CodePreview` 并省略 CSS(`import 'page-agent-sdk'` 不引 `'page-agent-sdk/style.css'`)。**持久化坑**:`sdk.stream` 不自动落盘(内置 useChat 经 onPersist 调 afterRound);自建对话框每轮后需手动 `sdk.afterRound()`,否则 `switchSession` 切回丢消息。**复用内置 DebugDrawer**(仅主包):`import { DebugDrawer }`(纯 props:`logs=sdk.debugLogs` / `getInfo=()=>sdk.inspect()` / `infoTick=sdk.infoTick`),在自己的 UI 里挂载,无需 ChatDialog。
562
585
  - **关闭无用能力**:`capabilities:{ dataOps:false, fetch:false, planning:false, skills:false, vfs:false, summarization:false, memory:false, subagent:false }` —— 移除对应工具 schema 与中间件(省 token,非字节)。
563
586
  - **CDN 用 esm.sh**:`import { createChatSdk } from 'https://esm.sh/page-agent-sdk'` —— peer(`zod`、`@langchain/*`)由 esm.sh 自动解析去重,模块场景最小。
564
587
  - **IIFE 仅用于零配置**:全量单文件方便但最重,宿主支持模块时优先 ESM。
package/dist/page-agent-sdk.headless.js CHANGED
@@ -3040,7 +3040,8 @@ function Yi(e, t) {
3040
3040
  } else if (n && (n._def?.type === "union" || n._def?.type === "discriminatedUnion" || Array.isArray(n.options))) {
3041
3041
  let t = r.slice(e).join("."), i = (n.options ?? []).map((e) => Yi(e, t)).filter((e) => e != null);
3042
3042
  return i.length ? i[0] : null;
3043
- } else return null;
3043
+ } else if (n && n._def?.type === "record") n = n._def.valueType;
3044
+ else if (!(n && (n._def?.type === "any" || n._def?.type === "unknown"))) return null;
3044
3045
  }
3045
3046
  return n ?? null;
3046
3047
  }
@@ -12190,7 +12191,7 @@ function vf(e) {
12190
12191
  let n = e[r];
12191
12192
  typeof n == "string" && (t[r] = n);
12192
12193
  }
12193
- return e.assistantAvatar && (t.assistantAvatar = e.assistantAvatar), e.userAvatar && (t.userAvatar = e.userAvatar), e.send && (t.send = e.send), t;
12194
+ return e.assistantAvatar && (t.assistantAvatar = e.assistantAvatar), e.userAvatar && (t.userAvatar = e.userAvatar), e.send && (t.send = e.send), e.newSession && (t.newSession = e.newSession), e.history && (t.history = e.history), e.more && (t.more = e.more), e.close && (t.close = e.close), e.sessionDelete && (t.sessionDelete = e.sessionDelete), t;
12194
12195
  }
12195
12196
  //#endregion
12196
12197
  //#region src/core/components/messages.ts