page-agent-sdk 2.10.2 → 2.11.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 (10) hide show
  1. package/README.md +17 -14
  2. package/README.zh-CN.md +16 -13
  3. package/dist/page-agent-sdk.iife.js +122 -122
  4. package/dist/page-agent-sdk.js +3102 -3047
  5. package/dist/page-agent-sdk.umd.cjs +66 -66
  6. package/package.json +2 -1
  7. package/skills/page-agent-sdk-integrate/references/api.md +42 -0
  8. package/skills/page-agent-sdk-integrate/references/integration-prompt.md +4 -0
  9. package/skills/page-agent-sdk-integrate/references/quickstart.md +34 -0
  10. package/types/index.d.ts +15 -0
package/README.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # page-agent-sdk
2
2
 
3
- > **[English](./README.md)** · **[中文](./README.zh-CN.md)**
3
+ > **[English](https://github.com/whyymj/chat-sdk/blob/master/README.md)** · **[中文](https://github.com/whyymj/chat-sdk/blob/master/README.zh-CN.md)**
4
4
 
5
5
  > Give your web page an **AI assistant that edits the page itself**. Mount a chat dialog in one line; the AI reads/writes page data safely via schema-validated tools — "conversational" building/editing/ops.
6
6
 
7
- > **AI agent integration**: see [Agent Integration Cheat Sheet](#agent-integration-cheat-sheet-for-ai-agents) below (exports / options / extension points / built-in tools / file structure). Architecture & gotchas in [`CLAUDE.md`](./CLAUDE.md).
7
+ > **AI agent integration**: see [Agent Integration Cheat Sheet](#agent-integration-cheat-sheet-for-ai-agents) below (exports / options / extension points / built-in tools / file structure). Architecture & gotchas in [`CLAUDE.md`](https://github.com/whyymj/chat-sdk/blob/master/CLAUDE.md).
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
10
- [![license](https://img.shields.io/badge/license-ISC-blue.svg)](./LICENSE)
10
+ [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/chat-sdk/blob/master/LICENSE)
11
11
  [![tests](https://img.shields.io/badge/self%20tests-434%20asserts-brightgreen.svg)](#self-tests)
12
12
 
13
13
  ---
@@ -137,6 +137,8 @@ The core of letting AI safely edit JSON is a **three-layer decoupled split** —
137
137
  ```ts
138
138
  // entry & tool construction
139
139
  createChatSdk, defineTool, defineSkill, presets, z
140
+ // proxy connection (prevent apiKey leakage: proxy mode / direct mode)
141
+ createProxyLlm
140
142
  // harness & middleware (custom orchestration)
141
143
  createAgent, createSubagentMiddleware, createSubagentsMiddleware,
142
144
  createVerifyMiddleware, createWriteBackCheck, createApprovalMiddleware,
@@ -245,7 +247,7 @@ src/core/
245
247
  ├── composables/ # useChat / useContextManager / useMarkdown
246
248
  ├── components/ # ChatDialog / MessageContent / CodePreview / DebugDrawer
247
249
  └── types/index.ts index.ts # types / sole library entry
248
- examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo
250
+ examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo / proxy-demo
249
251
  doc/ # usage-guide / architecture / context-management / architecture-files
250
252
  CLAUDE.md # architecture + gotchas + coding conventions (agent must-read)
251
253
  ```
@@ -300,7 +302,7 @@ src/core/
300
302
  ├── composables/ # useChat / useContextManager / useMarkdown
301
303
  ├── components/ # ChatDialog / MessageContent / CodePreview / DebugDrawer
302
304
  └── types/index.ts index.ts # types / sole library entry
303
- examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo
305
+ examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo / proxy-demo
304
306
  doc/ # usage-guide / architecture / context-management / architecture-files
305
307
  CLAUDE.md # architecture + gotchas + coding conventions (agent must-read)
306
308
  ```
@@ -422,6 +424,7 @@ After `npm run dev`, visit the corresponding page:
422
424
  | mcp-demo | `/examples/mcp-demo/` | MCP remote tools (needs `npm run mcp:mock`) |
423
425
  | animation-demo | `/examples/animation-demo/` | ChatDialog enter/collapse/unmount animations + inline/drawer + hide/show |
424
426
  | multi-agent-demo | `/examples/multi-agent-demo/` | Multi-agent parallel + exclusive switch (3 independent agents, drawer hide/show keeps each history) |
427
+ | proxy-demo | `/examples/proxy-demo/` | Proxy connection to prevent apiKey leakage (browser holds only userToken, proxy injects real key; includes auto-refresh on expired token; needs `npm run proxy:mock`) |
425
428
 
426
429
  Framework-agnostic integration: `demo/plain.html` (importmap + esm.sh).
427
430
 
@@ -446,17 +449,17 @@ function switchTo(i: number) {
446
449
 
447
450
  | Doc | Contents |
448
451
  |---|---|
449
- | [Doc Index](./doc/README.en.md) | Navigation + other info sources (specs/changes/tests) |
450
- | [Usage Guide](./doc/usage-guide.en.md) | Install / options / capability deep-dive / custom middleware / FAQ |
451
- | [Architecture](./doc/architecture.md) *(Chinese)* | Layering / control flow / window-op safety flow |
452
- | [Context & Compression](./doc/context-management.md) *(Chinese)* | Context composition / 4-layer compression / flow diagrams |
453
- | [File Overview](./doc/architecture-files.md) *(Chinese)* | Per-file responsibilities / deps / data flow |
454
- | [CLAUDE.md](./CLAUDE.md) | **agent must-read** · architecture / gotchas / coding conventions |
452
+ | [Doc Index](https://github.com/whyymj/chat-sdk/blob/master/doc/README.en.md) | Navigation + other info sources (specs/changes/tests) |
453
+ | [Usage Guide](https://github.com/whyymj/chat-sdk/blob/master/doc/usage-guide.en.md) | Install / options / capability deep-dive / custom middleware / FAQ |
454
+ | [Architecture](https://github.com/whyymj/chat-sdk/blob/master/doc/architecture.md) *(Chinese)* | Layering / control flow / window-op safety flow |
455
+ | [Context & Compression](https://github.com/whyymj/chat-sdk/blob/master/doc/context-management.md) *(Chinese)* | Context composition / 4-layer compression / flow diagrams |
456
+ | [File Overview](https://github.com/whyymj/chat-sdk/blob/master/doc/architecture-files.md) *(Chinese)* | Per-file responsibilities / deps / data flow |
457
+ | [CLAUDE.md](https://github.com/whyymj/chat-sdk/blob/master/CLAUDE.md) | **agent must-read** · architecture / gotchas / coding conventions |
455
458
 
456
459
  ## Self-tests
457
460
 
458
461
  ```bash
459
- npm test # 474 assertions (tsx, source-level; no LLM dependency)
462
+ npm test # 483 assertions (tsx, source-level; no LLM dependency)
460
463
  npm run test:e2e # 173 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 / 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)
461
464
  ```
462
465
 
@@ -532,8 +535,8 @@ npm test
532
535
 
533
536
  ## Relationship to Deep Agents
534
537
 
535
- Borrows the harness idea from [Deep Agents](https://github.com/langchain-ai/deepagents) (ReAct + middleware + planning + skills + memory + context management), but implemented in-house: no LangGraph/langchain full bundle; browser-oriented (persistence via IndexedDB, not server-side DB); context via input compression + memory trim + large-result offload, rather than per-step checkpointer archival. See [Context & Compression - Differences from Deep Agents](./doc/context-management.md#七与-deep-agents-的差异).
538
+ Borrows the harness idea from [Deep Agents](https://github.com/langchain-ai/deepagents) (ReAct + middleware + planning + skills + memory + context management), but implemented in-house: no LangGraph/langchain full bundle; browser-oriented (persistence via IndexedDB, not server-side DB); context via input compression + memory trim + large-result offload, rather than per-step checkpointer archival. See [Context & Compression - Differences from Deep Agents](https://github.com/whyymj/chat-sdk/blob/master/doc/context-management.md#七与-deep-agents-的差异).
536
539
 
537
540
  ## License
538
541
 
539
- [ISC](./LICENSE)
542
+ [ISC](https://github.com/whyymj/chat-sdk/blob/master/LICENSE)
package/README.zh-CN.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # page-agent-sdk
2
2
 
3
- > **[English](./README.md)** · **[中文](./README.zh-CN.md)**
3
+ > **[English](https://github.com/whyymj/chat-sdk/blob/master/README.md)** · **[中文](https://github.com/whyymj/chat-sdk/blob/master/README.zh-CN.md)**
4
4
 
5
5
  > 给网页一个**会改页面的 AI 助手**。一行代码挂载对话框，AI 通过工具按 schema 安全读写页面数据，实现「对话式」搭建/编辑/运维。
6
6
 
7
- > **AI agent 接入**：直接看下方「[Agent 接入速查](#agent-接入速查给-ai-agent-读)」（导出 / 选项表 / 扩展点 / 内置工具 / 文件结构），架构与约定坑见 [`CLAUDE.md`](./CLAUDE.md)。
7
+ > **AI agent 接入**：直接看下方「[Agent 接入速查](#agent-接入速查给-ai-agent-读)」（导出 / 选项表 / 扩展点 / 内置工具 / 文件结构），架构与约定坑见 [`CLAUDE.md`](https://github.com/whyymj/chat-sdk/blob/master/CLAUDE.md)。
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/page-agent-sdk.svg)](https://www.npmjs.com/package/page-agent-sdk)
10
- [![license](https://img.shields.io/badge/license-ISC-blue.svg)](./LICENSE)
10
+ [![license](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/whyymj/chat-sdk/blob/master/LICENSE)
11
11
  [![tests](https://img.shields.io/badge/self%20tests-364%20asserts-brightgreen.svg)](#自测)
12
12
 
13
13
  ---
@@ -137,6 +137,8 @@ SDK 让 AI 安全改 JSON 的核心是**三层解耦配合**——各司其职
137
137
  ```ts
138
138
  // 入口与工具构造
139
139
  createChatSdk, defineTool, defineSkill, presets, z
140
+ // 代理连接(防 apiKey 泄露:proxy 代理模式 / direct 直连模式)
141
+ createProxyLlm
140
142
  // harness 与中间件(自定义编排)
141
143
  createAgent, createSubagentMiddleware, createSubagentsMiddleware,
142
144
  createVerifyMiddleware, createWriteBackCheck, createApprovalMiddleware,
@@ -245,7 +247,7 @@ src/core/
245
247
  ├── composables/ # useChat / useContextManager / useMarkdown
246
248
  ├── components/ # ChatDialog / MessageContent / CodePreview / DebugDrawer
247
249
  └── types/index.ts index.ts # 类型 / 库唯一入口
248
- examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo
250
+ examples/ # page-demo / nested-demo / dynamic-demo / human-confirm-demo / planner-demo / subagent-demo / mcp-demo / toolsets-demo / proxy-demo
249
251
  doc/ # usage-guide / architecture / context-management / architecture-files
250
252
  CLAUDE.md # 架构要点 + 约定坑 + 编码规范（agent 必读）
251
253
  ```
@@ -367,6 +369,7 @@ createChatSdk({
367
369
  | mcp-demo | `/examples/mcp-demo/` | MCP 远程工具（需 `npm run mcp:mock`） |
368
370
  | animation-demo | `/examples/animation-demo/` | ChatDialog 入场/收起/卸载动画 + inline/drawer 模式 + hide/show |
369
371
  | multi-agent-demo | `/examples/multi-agent-demo/` | 多 Agent 并行 + 互斥切换（三独立 agent，drawer hide/show 保留各自历史） |
372
+ | proxy-demo | `/examples/proxy-demo/` | 代理连接防 apiKey 泄露（浏览器只持 userToken，代理注入真实 key；含 token 过期自动刷新；需 `npm run proxy:mock`） |
370
373
 
371
374
  框架无关集成：`demo/plain.html`（importmap + esm.sh）。
372
375
 
@@ -391,17 +394,17 @@ function switchTo(i: number) {
391
394
 
392
395
  | 文档 | 内容 |
393
396
  |---|---|
394
- | [文档索引](./doc/README.md) | 各文档导航 + 其他信息源（规范/变更/自测） |
395
- | [使用手册](./doc/usage-guide.md) | 安装 / 配置项 / 能力详解 / 自定义中间件 / FAQ |
396
- | [功能架构](./doc/architecture.md) | 分层 / 控制流 / 数据操作安全流 |
397
- | [上下文与压缩](./doc/context-management.md) | 上下文组成 / 4 层压缩 / 流程图 |
398
- | [文件全览](./doc/architecture-files.md) | 逐文件职责 / 依赖 / 数据流 |
399
- | [CLAUDE.md](./CLAUDE.md) | **agent 必读** · 架构要点 / 约定坑 / 编码规范 |
397
+ | [文档索引](https://github.com/whyymj/chat-sdk/blob/master/doc/README.md) | 各文档导航 + 其他信息源（规范/变更/自测） |
398
+ | [使用手册](https://github.com/whyymj/chat-sdk/blob/master/doc/usage-guide.md) | 安装 / 配置项 / 能力详解 / 自定义中间件 / FAQ |
399
+ | [功能架构](https://github.com/whyymj/chat-sdk/blob/master/doc/architecture.md) | 分层 / 控制流 / 数据操作安全流 |
400
+ | [上下文与压缩](https://github.com/whyymj/chat-sdk/blob/master/doc/context-management.md) | 上下文组成 / 4 层压缩 / 流程图 |
401
+ | [文件全览](https://github.com/whyymj/chat-sdk/blob/master/doc/architecture-files.md) | 逐文件职责 / 依赖 / 数据流 |
402
+ | [CLAUDE.md](https://github.com/whyymj/chat-sdk/blob/master/CLAUDE.md) | **agent 必读** · 架构要点 / 约定坑 / 编码规范 |
400
403
 
401
404
  ## 自测
402
405
 
403
406
  ```bash
404
- npm test # 474 项断言（tsx 源码级，不依赖 LLM）
407
+ npm test # 483 项断言（tsx 源码级，不依赖 LLM）
405
408
  npm run test:e2e # 173 项集成断言（node 跑构建产物 dist；覆盖各 API/配置项/功能模块/简单与复杂场景：默认 systemPrompt(含能力概述) / 动态注册与 inspect 同步 / inspect(tools/middleware/subagent/verify/mcp/todos/lastCompression/checkpoints 反映配置) / 自定义 tools/middleware/skills/memory 注入 / switchSession(开/未开) / shareContext 开/关共享独立 / storage 后端+对象配置 / presets 三预设 / checkpoint / 导出项完整(39+ 函数/组件) / 工具函数可用(isQuotaError/estimateTokens/jpEval/searchJson) / source=builtin / mount 边界 / hook 多监听器 / llm 配置 / 错误场景）
406
409
  ```
407
410
 
@@ -477,8 +480,8 @@ npm test
477
480
 
478
481
  ## 与 Deep Agents 的关系
479
482
 
480
- 借鉴 [Deep Agents](https://github.com/langchain-ai/deepagents) 的 harness 思路（ReAct + 中间件 + planning + skills + memory + context 管理），但自研实现：不引 LangGraph/langchain 整包；面向浏览器端（持久化用 IndexedDB 而非服务端 DB）；上下文用输入压缩 + 内存裁剪 + 大结果 offload，而非每步 checkpointer 存档。详见 [上下文与压缩 - 与 Deep Agents 的差异](./doc/context-management.md#七与-deep-agents-的差异)。
483
+ 借鉴 [Deep Agents](https://github.com/langchain-ai/deepagents) 的 harness 思路（ReAct + 中间件 + planning + skills + memory + context 管理），但自研实现：不引 LangGraph/langchain 整包；面向浏览器端（持久化用 IndexedDB 而非服务端 DB）；上下文用输入压缩 + 内存裁剪 + 大结果 offload，而非每步 checkpointer 存档。详见 [上下文与压缩 - 与 Deep Agents 的差异](https://github.com/whyymj/chat-sdk/blob/master/doc/context-management.md#七与-deep-agents-的差异)。
481
484
 
482
485
  ## License
483
486
 
484
- [ISC](./LICENSE)
487
+ [ISC](https://github.com/whyymj/chat-sdk/blob/master/LICENSE)