page-agent-sdk 3.30.0 → 3.32.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 (12) hide show
  1. package/README.md +10 -17
  2. package/README.zh-CN.md +9 -16
  3. package/dist/page-agent-sdk.headless.js +2796 -2844
  4. package/dist/page-agent-sdk.iife.js +132 -134
  5. package/dist/page-agent-sdk.js +3449 -3385
  6. package/dist/page-agent-sdk.legacy.js +14457 -14388
  7. package/dist/page-agent-sdk.umd.cjs +98 -100
  8. package/dist/style.css +1 -1
  9. package/package.json +1 -1
  10. package/style.css +1 -1
  11. package/types/headless.d.ts +11 -41
  12. package/types/index.d.ts +13 -41
package/README.md CHANGED
@@ -8,7 +8,7 @@
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-2531%20asserts-brightgreen.svg)](#self-tests)
11
+ [![tests](https://img.shields.io/badge/self%20tests-2525%20asserts-brightgreen.svg)](#self-tests)
12
12
 
13
13
  ---
14
14
 
@@ -48,12 +48,12 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
48
48
 
49
49
  | Constraint | Mechanism | Effect |
50
50
  |---|---|---|
51
- | **Scope control** | Declared schema fields (`data`) — only declared keys are writable; schema shape auto-whitelist (top-level + sub-path recursively projected by sub-schema; undeclared fields hidden/denied; whole-set becomes merge to prevent accidental deletion; `interceptors.write`-supplied invisible fields persisted) | AI touching undeclared fields → `PATH_DENIED` |
51
+ | **Scope control** | Declared schema fields (`data`) — only declared keys are writable; schema shape auto-whitelist (top-level + sub-path recursively projected by sub-schema; undeclared fields hidden/denied; whole-set becomes merge to prevent accidental deletion) | AI touching undeclared fields → `PATH_DENIED` |
52
52
  | **Validity check** | zod schema — `write`/`set`/`edit` validated against schema | Invalid type/enum/structure → structured error, no write |
53
53
  | **Incremental op** | `write` with `patch`/`patches` (batch, atomic rollback) or advanced `edit_data` patches by `jsonPath` (set/remove/merge/append) | Avoid re-sending the whole large JSON; precise local edits; use `patches` to edit many at once |
54
54
  | **Large-object retrieval** | `read` supports `fields` (projection) + `depth` (truncation) to shrink payload; `query_data` (JSONPath)/`search_data` (text)/`eval_script` (sandboxed JS) | Efficient retrieval + pinpoint location in large JSON |
55
55
  | **Rollbackable** | per-path snapshots (auto-stacked) + session checkpoint | Bad edit → one-click restore to the last good state |
56
- | **Optimistic lock** | `expectedHash` on `set`/`edit`/`delete` + conflict human-in-the-loop (3.29+ `conflictPolicy` declares auto-adjudication: overwrite / keep_external) | Concurrent external edits detected → suspend, user picks keep/overwrite/restore |
56
+ | **Optimistic lock** | `conflictWatchFields` opt-in optimistic lock + conflict human-in-the-loop (3.29+ `conflictPolicy` declares auto-adjudication: overwrite / keep_external) | Concurrent external edits detected → suspend, user picks keep/overwrite/restore |
57
57
 
58
58
  "Editing JSON" moves from free-form LLM text generation to **structured, validatable, auditable, rollbackable** tool operations. This is the fundamental difference from "let the AI output a JSON string directly".
59
59
 
@@ -83,7 +83,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
83
83
 
84
84
  - **Q: I want an AI assistant embedded in my web page that can edit the page data.** → `page-agent-sdk`: declare a zod schema + `bind`, mount the dialog, done. See [30-second quickstart](#30-second-quickstart).
85
85
  - **Q: Alternative to CopilotKit / LangChain for an in-page agent?** → `page-agent-sdk` is framework-agnostic (Vue bundled, host can be React / vanilla), schema-validated, ships optimistic lock + snapshot rollback + MCP, and needs no LangGraph. See [Comparison](#comparison).
86
- - **Q: How to let AI safely edit a large JSON on my page?** → `data` + zod schema + `write` with `patch` / `patches` + `expectedHash` optimistic lock. Invalid edits are rejected pre-write; bad edits rollback in one click.
86
+ - **Q: How to let AI safely edit a large JSON on my page?** → `data` + zod schema + `write` with `patch` / `patches` + `conflictWatchFields` optimistic lock. Invalid edits are rejected pre-write; bad edits rollback in one click.
87
87
  - **Q: Does it work with DeepSeek / OpenAI / any OpenAI-compatible endpoint / Anthropic Claude?** → Yes. `llm: { apiKey, baseUrl, model }` defaults to DeepSeek (OpenAI protocol); `llm: { provider: 'anthropic', apiKey, model: 'claude-...' }` uses Claude native protocol (dynamic-loaded `@langchain/anthropic`, optional peer); any LangChain `BaseChatModel` also accepted.
88
88
  - **Q: Can I run it headless / in Node.js?** → Yes. `ui:false` + `storage:'memory'`, drive via `sdk.send`. See [headless-demo](#examples).
89
89
  - **Q: Does it support MCP?** → Yes. `mcp: [{ transport, url }]` connects remote MCP servers and injects tools dynamically.
@@ -95,7 +95,7 @@ At its core, it gives the AI a **standardized, safe JSON-operation channel**. AI
95
95
  | Framework-agnostic, UI bundled | ✅ Vue bundled, host-agnostic | ❌ React-only | ✅ (no UI) | ✅ (no UI) | ✅ (no UI) |
96
96
  | Schema-validated JSON ops | ✅ zod, whitelist + merge-safe | ⚠️ partial (tool args) | ⚠️ tool args only | ⚠️ tool args only | ❌ |
97
97
  | Incremental patch (jsonPath) | ✅ `write` patch / `edit_data` | ❌ | ❌ | ❌ | ❌ |
98
- | Optimistic lock + conflict HITL | ✅ `expectedHash` | ❌ | ❌ | ❌ | ❌ |
98
+ | Optimistic lock + conflict HITL | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
99
99
  | Snapshot rollback + checkpoint | ✅ per-path + session | ❌ | ❌ | ❌ | ❌ |
100
100
  | Proactive human-confirm | ✅ built-in | ⚠️ manual | ❌ | ❌ | ❌ |
101
101
  | MCP | ✅ | ✅ | ✅ | ✅ | manual |
@@ -167,7 +167,7 @@ CDN zero-config: `<script src="https://unpkg.com/page-agent-sdk"></script>` →
167
167
  | 📌 cross-compress working memory (2.20+) | Pin recent read/query paths + hashes across compression; no re-fetch, correct optimistic-lock hash | `capabilities.workingMemory` |
168
168
  | 🤖 unattended automation (2.20+) | Resource budget guard (`tokenBudget`/`timeBudgetMs`) + fatal-error auto-recovery (`maxAutoRetries`: restore checkpoint + retry) + cross-refresh resume + `sdk.batch(tasks)` batch processing | `capabilities.automation` |
169
169
  | 📐 context resilience (2.30+) | Hard floor `contextWindow ≥200K` (rejects <200K models like legacy `deepseek`/`gpt-4o`/`glm-4.5` at startup); three gates (compress/trim/offload) thresholds follow the live window after `setLlm`; reactive retry on `context_length_exceeded` (aggressive trim → single retry, never fails raw); vfs large-result refs protected from LRU eviction + OOM 1.5× fallback; system-prompt budget (25% window, drops non-pinned segments, keeps base/mission/workingMemory) | built-in |
170
- | 🎯 focus auto-switch (2.31+) | AI auto-judges task scope → `set_focus` (local task) / `clear_focus` (global/done); focus persists across refresh/session-switch (restore validates path via `getSchemaAtPath`, drops if invalid); spawned subagents inherit parent focus (three-layer convergence; parent unfocused → child no focus middleware, zero regression) | `capabilities.focus` + `toolMode:'advanced'` |
170
+ | 🎯 focus auto-switch (2.31+) | AI auto-judges task scope → `set_focus` (local task) / `clear_focus` (global/done); focus persists across refresh/session-switch (restore validates path via `getSchemaAtPath`, drops if invalid); spawned subagents inherit parent focus (three-layer convergence; parent unfocused → child no focus middleware, zero regression) | `capabilities.focus` |
171
171
  | 🔒 precise-value protection (2.32+) | `data.resources: [{path, mode}]` protects exact-value fields: `freeze` (read-only, value hidden via `⟦frozen:path⟧` placeholder, FROZEN_FIELD on write) / `verbatim` (preserved verbatim, `⟦res:handle⟧`, modify via `resource_update` else VERBATIM_MISMATCH); write-side enforcement across commitSetToBind/applyPatches/eval + resource tools (`resource_get/update/list/delete`, advanced) + cross-compression pin | `data.resources` + `capabilities.vfs` |
172
172
  | 🌍 UI customization & i18n (3.17+–3.22+) | Dialog UI is fully customizable without forking: `dialog.icons` (per-icon override; plain text or sanitized HTML fragment) + built-in `dialog.theme: 'dark'`, and the top-level `i18n` group (3.22+): `locale: 'en-US'` switches the built-in message pack (chat surface + Debug drawer + Skill panel + code preview; `formatTime`/autoTitle follow, **default systemPrompt switches to English** so agent replies match the UI language), `messages` per-key overrides (e.g. `statusDone: '<b style="color:#10b981">Done ✓</b>'` — rich-text render spots accept inline HTML fragments sanitized via a text allowlist) — switch language and tweak individual strings in one group; `DialogMessages` (~226 keys) + `MESSAGES_ZH_CN`/`MESSAGES_EN_US`/`resolveDialogMessages` exported for custom UIs | `dialog.{icons,theme}` + `i18n.{locale,messages}` |
173
173
 
@@ -302,7 +302,7 @@ createChatSdk({ subagents: [
302
302
 
303
303
  ### Built-in tools (Agent-callable)
304
304
 
305
- - **data ops** (default `toolMode:'advanced'`, expose all; opt-down `simple` promotes read/write, `minimal` read/write only): `read` (list/get/describe merged) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `restore_data` / `history_data` (snapshot rollback/history); `advanced` additionally exposes low-level `describe_data` / `get_data` (@deprecated, use read) / `set_data` / `edit_data` (jsonPath patch) / `delete_data` / `schema_data` / `diff_data` / focus tools
305
+ - **data ops** (all 14 tools always exposed): `read` (list/get/describe merged) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `restore_data` / `history_data` (snapshot rollback/history); low-level `describe_data` / `get_data` (@deprecated, use read) / `set_data` / `edit_data` (jsonPath patch) / `delete_data` / `schema_data` / `diff_data` / focus tools
306
306
  - **window query**: `query_data` (JSONPath) / `search_data` (fuzzy) / `eval_script` (sandboxed)
307
307
  - **fetch**: `fetch_document`
308
308
  - **vfs**: `vfs_read` / `vfs_write` / `vfs_edit` / `vfs_ls` / `vfs_glob` / `vfs_grep`
@@ -397,13 +397,6 @@ createChatSdk({
397
397
  id: 'my-agent', // stable id (multi-agent isolation + persistence resume)
398
398
  systemPrompt: '...',
399
399
  data: { schema, bind, description? }, // single main object: bind directly connects reactive/plain object (tools read/write bind, not auto-mounted to window); schema field .describe() auto-injected into systemPrompt「可操作数据」section
400
- // toolMode: 'simple', // optional: default 'advanced' (expose all); simple promotes read/write; minimal = read/write only
401
- interceptors: { // read/write interceptors (desensitize/transform/audit/reject; input/output at agent IO entry/exit)
402
- read: (value) => value,
403
- write: (payload) => payload,
404
- input: (msg) => msg, // preprocess at send entry
405
- output: (reply) => reply, // postprocess before return
406
- },
407
400
  storage: 'indexed', // persistence (default off)
408
401
  streaming: true, ui: 'default',
409
402
  capabilities: { verify: true }, // capability toggles
@@ -483,7 +476,7 @@ function switchTo(i: number) {
483
476
  }
484
477
  ```
485
478
 
486
- > Multiple agents operating on the same `data` need coordination (optimistic lock `expectedHash` or `jsonPath` partitioning); each managing its own `data` object has no conflict (recommended). Full example: `examples/multi-agent-demo/`.
479
+ > Multiple agents operating on the same `data` need coordination (optimistic lock `conflictWatchFields` or `jsonPath` partitioning); each managing its own `data` object has no conflict (recommended). Full example: `examples/multi-agent-demo/`.
487
480
 
488
481
  ## Documentation
489
482
 
@@ -499,8 +492,8 @@ function switchTo(i: number) {
499
492
  ## Self-tests
500
493
 
501
494
  ```bash
502
- npm test # 2531 assertions (tsx, source-level; no LLM dependency)
503
- npm run test:e2e # 832 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)
495
+ npm test # 2525 assertions (tsx, source-level; no LLM dependency)
496
+ npm run test:e2e # 822 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)
504
497
  ```
505
498
 
506
499
  ## Local npm package test
package/README.zh-CN.md CHANGED
@@ -8,7 +8,7 @@
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-2531%20asserts-brightgreen.svg)](#自测)
11
+ [![tests](https://img.shields.io/badge/self%20tests-2525%20asserts-brightgreen.svg)](#自测)
12
12
 
13
13
  ---
14
14
 
@@ -48,12 +48,12 @@
48
48
 
49
49
  | 约束 | 机制 | 作用 |
50
50
  |---|---|---|
51
- | **范围控制** | schema 校验(`data`)—— 只能改 schema 允许的值;schema 形状自动白名单(顶层 + 子路径按子 schema 递归投影,未声明字段隐藏/拒改/整体 set 转 merge 防误删;`interceptors.write` 补充的不可见字段落地保留) | AI 传非法值 → 拒绝;非声明字段 → `PATH_DENIED` |
51
+ | **范围控制** | schema 校验(`data`)—— 只能改 schema 允许的值;schema 形状自动白名单(顶层 + 子路径按子 schema 递归投影,未声明字段隐藏/拒改/整体 set 转 merge 防误删) | AI 传非法值 → 拒绝;非声明字段 → `PATH_DENIED` |
52
52
  | **合法性校验** | zod schema —— `write`/`set`/`edit` 按 schema 校验 | 类型/枚举/结构不合法 → 结构化错误,不写入 |
53
53
  | **增量操作** | `write` 的 `patch`/`patches`(批量,原子回滚)或 advanced `edit_data` 按 `jsonPath` 发 patch(set/remove/merge/append) | 避免重传整个大 JSON,精确改局部;一次改多处用 `patches` |
54
54
  | **大对象检索** | `read` 支持 `fields`(字段裁剪)+ `depth`(深度截断)减体积;`query_data`(JSONPath)/`search_data`(文本)/`eval_script`(沙箱 JS) | 大 JSON 高效检索 + 局部定位 |
55
55
  | **可回滚** | per-path 快照(自动入栈)+ 会话 checkpoint | 改坏了一键回退到上次正常态 |
56
- | **乐观锁** | `set`/`edit`/`delete` 传 `expectedHash` + 冲突人工介入(3.29+ `conflictPolicy` 可声明自动裁决:overwrite / keep_external) | 检测并发外部修改 → 挂起,用户选保留/覆盖/回退 |
56
+ | **乐观锁** | `conflictWatchFields` 声明式乐观锁 + 冲突人工介入(3.29+ `conflictPolicy` 可声明自动裁决:overwrite / keep_external) | 检测并发外部修改 → 挂起,用户选保留/覆盖/回退 |
57
57
 
58
58
  「改 JSON」从 LLM 自由生成文本 → **结构化、可校验、可审计、可回滚**的工具操作。这是它区别于「让 AI 直接输出 JSON 字符串」的根本所在。
59
59
 
@@ -83,7 +83,7 @@
83
83
 
84
84
  - **Q：我想在网页里加一个能改页面数据的 AI 助手。** → 用 `page-agent-sdk`：声明 zod schema + `bind`、挂载对话框即可。见[30 秒上手](#30-秒上手)。
85
85
  - **Q：CopilotKit / LangChain 的页面内 agent 替代方案?** → `page-agent-sdk` 框架无关（Vue 打包进库，宿主可 React / 原生）、schema 校验、自带乐观锁 + 快照回退 + MCP，不依赖 LangGraph。见[对比](#对比)。
86
- - **Q：怎么让 AI 安全地改页面上的大 JSON?** → `data` + zod schema + `write` 的 `patch` / `patches` + `expectedHash` 乐观锁。非法编辑写前拦截、改错了一键回退。
86
+ - **Q：怎么让 AI 安全地改页面上的大 JSON?** → `data` + zod schema + `write` 的 `patch` / `patches` + `conflictWatchFields` 乐观锁。非法编辑写前拦截、改错了一键回退。
87
87
  - **Q：支持 DeepSeek / OpenAI / 任意 OpenAI 兼容端点 / Anthropic Claude 吗?** → 支持。`llm:{apiKey,baseUrl,model}` 默认接 DeepSeek（OpenAI 协议）；`llm:{provider:'anthropic',apiKey,model:'claude-...'}` 走 Claude 原生协议（动态加载 `@langchain/anthropic`，不用不强求装）；也接受任意 LangChain `BaseChatModel`。
88
88
  - **Q：能 headless / 在 Node.js 跑吗?** → 能。`ui:false` + `storage:'memory'`，用 `sdk.send` 驱动。见 [headless-demo](#示例)。
89
89
  - **Q：支持 MCP 吗?** → 支持。`mcp:[{transport,url}]` 连远程 MCP server 动态注入工具。
@@ -95,7 +95,7 @@
95
95
  | 框架无关、UI 打包进库 | ✅ Vue 打包,宿主任意 | ❌ 仅 React | ✅(无 UI) | ✅(无 UI) | ✅(无 UI) |
96
96
  | schema 校验的 JSON 操作 | ✅ zod + 白名单 + merge 防误删 | ⚠️ 部分(工具参数) | ⚠️ 仅工具参数 | ⚠️ 仅工具参数 | ❌ |
97
97
  | 增量 patch(jsonPath) | ✅ `write` patch / `edit_data` | ❌ | ❌ | ❌ | ❌ |
98
- | 乐观锁 + 冲突人工介入 | ✅ `expectedHash` | ❌ | ❌ | ❌ | ❌ |
98
+ | 乐观锁 + 冲突人工介入 | ✅ `conflictWatchFields` | ❌ | ❌ | ❌ | ❌ |
99
99
  | 快照回退 + checkpoint | ✅ per-path + 会话级 | ❌ | ❌ | ❌ | ❌ |
100
100
  | 主动人工确认 | ✅ 内置 | ⚠️ 手动 | ❌ | ❌ | ❌ |
101
101
  | MCP | ✅ | ✅ | ✅ | ✅ | 手动 |
@@ -160,7 +160,7 @@ CDN 零配置：`<script src="https://unpkg.com/page-agent-sdk"></script>` → `
160
160
  | 💾 持久化 | IndexedDB 多会话 + 配额淘汰 + 切换 | `storage` |
161
161
  | 🤖 无人值守自动化 (2.20+) | 资源预算闸（`tokenBudget`/`timeBudgetMs`）+ 致命错误自动恢复（`maxAutoRetries`：回退 checkpoint + 重试）+ 刷新续跑 + `sdk.batch(tasks)` 批处理 | `capabilities.automation` |
162
162
  | 📐 上下文健壮性 (2.30+) | 硬地板 `contextWindow ≥200K`(启动拒绝 <200K 模型如老款 `deepseek`/`gpt-4o`/`glm-4.5`);三道闸(压缩/trim/offload)阈值在 `setLlm` 后跟随实时窗口;遇 `context_length_exceeded` 反应性重试(激进 trim → 重试一次,不裸失败);vfs 大结果引用受保护免 LRU 淘汰 + OOM 1.5× 兜底;系统段预算(25% 窗口,丢弃非 pin 段保 base/mission/workingMemory) | 内置 |
163
- | 🎯 focus 自动切换 (2.31+) | AI 自动判断任务范围 → `set_focus`(局部任务)/ `clear_focus`(全局/完成);focus 跨刷新/切会话持久化(restore 经 `getSchemaAtPath` 校验 path,失效丢弃);子 agent 继承主焦点(三层收敛;主未聚焦 → 子无 focus 中间件,零回归) | `capabilities.focus` + `toolMode:'advanced'` |
163
+ | 🎯 focus 自动切换 (2.31+) | AI 自动判断任务范围 → `set_focus`(局部任务)/ `clear_focus`(全局/完成);focus 跨刷新/切会话持久化(restore 经 `getSchemaAtPath` 校验 path,失效丢弃);子 agent 继承主焦点(三层收敛;主未聚焦 → 子无 focus 中间件,零回归) | `capabilities.focus` |
164
164
  | 🔒 精确值保护 (2.32+) | `data.resources: [{path, mode}]` 保护需精确保存字段:`freeze`(只读,精确值经 `⟦frozen:path⟧` 占位符不入消息流,写撞 FROZEN_FIELD)/ `verbatim`(原样保留,`⟦res:handle⟧`,改值经 `resource_update` 否则 VERBATIM_MISMATCH);写侧强制覆盖 commitSetToBind/applyPatches/eval + 资源工具(`resource_get/update/list/delete`,advanced)+ 跨压缩 pin | `data.resources` + `capabilities.vfs` |
165
165
  | 🌍 UI 定制与国际化 (3.17+~3.22+) | 对话框 UI 免 fork 全定制:`dialog.icons` 逐图标覆盖(纯文本或净化后 HTML 片段)+ 内置深色主题 `dialog.theme:'dark'` + **顶层 `i18n` 配置组(3.22+)**:`locale:'en-US'` 切内置文案包(聊天面 + Debug 抽屉 + Skill 面板 + 代码预览;`formatTime`/autoTitle 跟随,**默认 systemPrompt 切英文** → agent 回复语言与 UI 一致)、`messages` 键级覆盖(如 `statusDone: '<b style="color:#10b981">Done ✓</b>'` —— 富文本渲染位支持行内 HTML 片段,文案白名单净化)——换语言与改个别文案一个配置组;`DialogMessages`(~226 键)+ `MESSAGES_ZH_CN`/`MESSAGES_EN_US`/`resolveDialogMessages` 导出供自建 UI 复用 | `dialog.{icons,theme}` + `i18n.{locale,messages}` |
166
166
  | 🎯 跨会话用户偏好记忆 | `capabilities.preferences`(**opt-in 默认关**,自动写用户浏览器属行为敏感项):agent 从对话中捕获用户持久偏好 —— 强信号(「记住:…」显式命令,零 LLM)/ 中信号(模式词初筛 + 小 LLM 提炼,核心判定「持久口味 vs 本轮任务指令」)/ 行为推断**不捕获**(宁漏勿误:学错一条假偏好,之后每个会话都带着跑);偏好独立持久化(preferenceStore,IndexedDB,与 storage/skillStorage 同构;同 topic **后说覆盖前说**,FIFO ≤20);每轮经 pin 段注入 system prompt(跨会话/跨压缩生效);`sdk.getPreferences()/removePreference(id)/clearPreferences()` 管理学错条目,DebugDrawer「用户偏好」只读小节可查 | `capabilities: { preferences: true }` + 可选 `preferenceStorage` |
@@ -300,7 +300,7 @@ createChatSdk({ subagents: [
300
300
 
301
301
  ### 内置工具（Agent 可调用）
302
302
 
303
- - **数据操作**（默认 `toolMode:'advanced'` 全暴露；opt-down `simple` 主推 read/write、`minimal` 只 read/write）：`read`（合并 describe/get）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`restore_data` / `history_data`（快照回退/查历史）；`advanced` 另暴露底层 `describe_data` / `get_data`（@deprecated，改用 read）/ `set_data` / `edit_data`（jsonPath 增量 patch）/ `delete_data` / `schema_data` / `diff_data` / focus 工具族
303
+ - **数据操作**（14 工具恒全暴露）：`read`（合并 describe/get）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`restore_data` / `history_data`（快照回退/查历史）；底层 `describe_data` / `get_data`（@deprecated，改用 read）/ `set_data` / `edit_data`（jsonPath 增量 patch）/ `delete_data` / `schema_data` / `diff_data` / focus 工具族
304
304
  - **window 查询**：`query_data`（JSONPath）/ `search_data`（模糊搜索）/ `eval_script`（沙箱脚本）
305
305
  - **抓取**：`fetch_document`
306
306
  - **DOM 检视**（`capabilities.domInspect`，opt-in）：`get_dom`（常驻）+ `dom_search` / `dom_info`（经内置 `dom-inspect` skill 按需注入 —— `load_skill("dom-inspect")` 激活；skills 关时降级直插）
@@ -400,13 +400,6 @@ createChatSdk({
400
400
  id: 'my-agent', // 稳定 id（多 agent 隔离 + 持久化恢复）
401
401
  systemPrompt: '...',
402
402
  data: { schema, bind, description? }, // 单主对象:bind 直连 reactive/普通对象(工具直接读写 bind,不自动挂 window);schema 字段 .describe() 自动注入 systemPrompt「可操作数据」段
403
- // toolMode: 'simple', // 可选:默认 'advanced'(全暴露);simple 主推 read/write;minimal 只 read/write
404
- interceptors: { // 读写拦截器(脱敏/转换/审计/拒绝 LLM 读写;input/output 在 agent IO 入口/出口)
405
- read: (value) => value,
406
- write: (payload) => payload,
407
- input: (msg) => msg, // send 入口预处理
408
- output: (reply) => reply, // 返回前 postprocess
409
- },
410
403
  storage: 'indexed', // 持久化（默认关）
411
404
  streaming: true, ui: 'default',
412
405
  capabilities: { verify: true }, // 能力开关
@@ -502,8 +495,8 @@ function switchTo(i: number) {
502
495
  ## 自测
503
496
 
504
497
  ```bash
505
- npm test # 2531 项断言（tsx 源码级，不依赖 LLM）
506
- npm run test:e2e # 832 项集成断言（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 配置 / 错误场景）
498
+ npm test # 2525 项断言（tsx 源码级，不依赖 LLM）
499
+ npm run test:e2e # 822 项集成断言（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 配置 / 错误场景）
507
500
  ```
508
501
 
509
502
  ## 本地 npm 包测试