page-agent-sdk 2.10.3 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.10.3",
+  "version": "2.12.0",
   "type": "module",
   "description": "框架无关的页面内 Agent JS SDK —— 以对话框形态挂载到任意网页,通过自定义 tool 读写宿主预注册的数据槽(经 schema 校验 + jsonPath 增量 patch + 快照回退;GET 抓文档),具备 planning/skills/虚拟工作区/context 管理能力。Vue 打包进库,使用者无需安装 Vue。",
   "main": "./dist/page-agent-sdk.umd.cjs",
@@ -28,6 +28,7 @@
     "dev": "vite",
     "mcp:mock": "tsx scripts/mcp-mock-server.ts",
     "mcp:probe": "tsx scripts/mcp-probe.ts",
+    "proxy:mock": "tsx scripts/proxy-mock-server.ts",
     "verify:probe": "tsx scripts/verify-probe.ts",
     "build": "npm run build:lib && npm run build:iife",
     "build:lib": "vite build",

package/skills/page-agent-sdk-integrate/references/advanced.md

@@ -276,3 +276,31 @@ createChatSdk({
   checkpoint: true,                             // rollback
 }).mount()
 ```
+
+## 6. Runtime dynamic reconfiguration (tools / llm / memory / subagents)
+
+Beyond `setData` / `setSkills`, you can dynamically reconfigure **tools / LLM / memory / pre-declared subagents** at runtime — zero-breakage (not calling = current behavior), no agent rebuild (preserves conversation history & middleware state). All setters trigger `infoTick++` → DebugDrawer refresh; `inspect()` reflects the latest tools/model/memory/subagent.subagents.
+
+```ts
+// 1. Tools: swap/append/remove user tools at runtime (built-ins untouched; internal rebind)
+sdk.setTools([toolA, toolB])            // replace user tool set (built-ins stay)
+sdk.addTool(toolC)                      // append (dedup by name)
+sdk.removeTool('toolA')                 // remove by name → boolean
+
+// 2. LLM: switch model at runtime (quota-exhausted→cheaper / complex task→stronger / switch provider)
+sdk.setLlm({ apiKey, baseUrl, model: 'gpt-4o' })   // LLMConfig form (constructs ChatOpenAI)
+sdk.setLlm(otherChatModel)                          // or pass a BaseChatModel instance
+// rebinds tools + re-resolves model caps (contextWindow/maxOutputTokens); summaryLlm unaffected
+
+// 3. Memory: update persistent directive at runtime (next augmentPrompt injects latest)
+sdk.setMemory('User is VIP; prefer concise answers; use incremental patch when editing.')
+sdk.setMemory('')   // clear (empty string skips injection)
+
+// 4. Subagents: runtime add/remove pre-declared subagents (requires subagents:[] at creation)
+//    Pass subagents: [] (empty array) at creation to enable the controller for dynamic add later.
+sdk.addSubagent({ id: 'translator', description: '中英互译子 agent', systemPrompt: '你是翻译助手。' })
+sdk.removeSubagent('translator')        // → boolean
+sdk.setSubagents([{ id: 'a', description: 'A' }, { id: 'b', description: 'B' }])  // replace all
+```
+
+> **Note**: `setSystemPrompt` / `setMiddleware` (runtime middleware-array swap) are not yet implemented — they touch the harness core and are deferred. Use `setData` / `setSkills` / `augmentSystem` hook to cover most dynamic system-prompt scenarios. See `doc/roadmap.md` #5.

package/skills/page-agent-sdk-integrate/references/api.md

@@ -19,6 +19,14 @@
 | `setSkills(skills)` | `(skills: SkillSpec[]) => void` | Runtime swap the entire skill list (same-name skill overwrites). Takes effect next round: the skill index section of the system prompt re-renders with the new skills; clears the skill full-text cache & in-round loaded set, so the next `load_skill` re-fetches the latest full text (incl. vfs doc). Requires skills enabled (default on). |
 | `invalidateSkillCache(name?)` | `(name?: string) => void` | Invalidate the skill full-text cache (proactive invalidation when a dynamic skill's content changes). Omit `name` to clear all; pass `name` to clear one. The next `load_skill` re-runs `getContent`/`readSkillDoc`. Requires skills enabled (default on). |
 | `usage` | `TokenUsage` | Cumulative token usage `{prompt_tokens, completion_tokens, total_tokens}` (accumulated per LLM call). |
+| `setTools(tools)` | `(tools: StructuredToolInterface[]) => void` | Runtime swap user tools (built-ins untouched; internal `rebindTools` re-binds to LLM; next round uses new set). Zero-breakage: not calling = current behavior. Supports per-permission/business-stage/A-B-test dynamic tool groups without rebuilding agent. |
+| `addTool(tool)` | `(tool: StructuredToolInterface) => void` | Append user tool at runtime (dedup by name; built-ins untouched). |
+| `removeTool(name)` | `(name: string) => boolean` | Remove user tool at runtime (built-ins untouched). Returns whether removed. |
+| `setLlm(llm)` | `(llm: BaseChatModel \| LLMConfig) => void` | Switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig` (constructs `ChatOpenAI` internally). Rebinds tools + re-resolves model caps (`contextWindow`/`maxOutputTokens`). `summaryLlm` unaffected. If new model lacks `bindTools`, tool-calling degrades (agent stays up). |
+| `setMemory(text)` | `(text: string) => void` | Update persistent memory directive at runtime (next `augmentPrompt` injects latest; `setMemory('')` clears). |
+| `setSubagents(configs)` | `(configs: SubagentConfig[]) => void` | Runtime swap pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation (else controller is null, setter warns, no throw). |
+| `addSubagent(config)` | `(config: SubagentConfig) => void` | Append pre-declared subagent at runtime (duplicate id warns & skips). Requires `subagents:[]` at creation. |
+| `removeSubagent(id)` | `(id: string) => boolean` | Remove pre-declared subagent at runtime (by id). Returns whether removed. Requires `subagents:[]` at creation. |
 | `restoreLastCheckpoint()` | `() => boolean` | Restore last good checkpoint (needs `checkpoint` enabled). |
 | `listCheckpoints()` | `() => CheckpointMeta[]` | List available checkpoints. |
 | `addSkill(skill)` | `(skill: { name, description, prompt \| getContent \| doc }) => void` | Add a user-created skill at runtime. Auto-merges into the skill list, persists via **independent SkillStore** (default indexedDB, separate from `storage` option), takes effect next round. Same-name overwrites. Requires `capabilities.skills` (default on) + `skillStorage` not `false` for persistence. |
@@ -164,6 +172,12 @@ createChatSdk({
 - **Notifying the outside world of changes**: subscribe `data_change` via `onEvent` (constructor) or `sdk.hook` (runtime, multi-listener, cancellable) — fires after `write`/`set`/`edit`/`delete`/`restore`, with `operation`/`value`. For Vue + reactive bind, template/watch auto-react (no manual notify needed); `onEvent` can coexist for audit/analytics.
 - **Runtime swap**: `sdk.setData({ schema, bind, description? })` replaces the whole config; tools pick up immediately (no rebuild). Snapshots & lock hash reset.
 - **Runtime skill swap**: `sdk.setSkills(skills)` replaces the entire skill list (same-name overwrites); the skill index section of the system prompt re-renders next round, and the skill full-text cache is cleared so the next `load_skill` re-fetches the latest content (incl. vfs doc). Use `sdk.invalidateSkillCache(name?)` to proactively invalidate the cache when a dynamic skill's content changes (without swapping the whole list).
+- **Runtime dynamic reconfiguration (zero-breakage; not calling = current behavior)**: beyond data/skills, you can also dynamically reconfigure tools / LLM / memory / subagents at runtime without rebuilding the agent:
+  - `sdk.setTools(tools)` / `addTool(tool)` / `removeTool(name)` — swap/append/remove user tools (built-ins untouched; internal `rebindTools` re-binds to LLM; next round uses new set). Use cases: per-permission tool groups, business-stage gating, A/B experiments.
+  - `sdk.setLlm(llm)` — switch LLM at runtime (quota-exhausted→cheaper model / complex task→stronger model / switch provider). Param `BaseChatModel` or `LLMConfig`. Rebinds tools + re-resolves model caps. `summaryLlm` unaffected.
+  - `sdk.setMemory(text)` — update the persistent memory directive at runtime (next `augmentPrompt` injects latest).
+  - `sdk.setSubagents(configs)` / `addSubagent(config)` / `removeSubagent(id)` — swap/append/remove pre-declared subagents (regenerates `use_<id>` delegation tools + triggers rebind). Requires `subagents:[]` at creation.
+  - All setters trigger `infoTick++` → DebugDrawer refreshes; `inspect()` reflects the latest tools/model/memory/subagent.subagents.
 
 ## Exported building blocks (for custom UIs)
 
@@ -173,3 +187,45 @@ createChatSdk({
 - Middleware factories: `createApprovalMiddleware`, `createVerifyMiddleware`, `createWriteBackCheck`, `createSubagentMiddleware`, `createCheckpointMiddleware`, `createUsageHintsMiddleware`
 - Storage: `createSessionStore`, `createMemoryBackend`, `createWebStorageBackend`, `isQuotaError`
 - JSON helpers: `jpEval`, `searchJson`, `runSandboxedScript`, `toolError`, `zodError`
+
+## Proxy connection (`createProxyLlm`) — prevent apiKey leakage
+
+Browser-direct LLM calls expose `apiKey` in DevTools. Use `createProxyLlm` to unify dev/prod access:
+
+```ts
+import { createChatSdk, createProxyLlm } from 'page-agent-sdk'
+
+// Production: proxy mode (server injects real key)
+createChatSdk({
+  llm: createProxyLlm({
+    mode: 'proxy',
+    baseUrl: '/api/llm',        // your proxy (same-origin avoids CORS)
+    userToken: getUserToken(),   // session token (server validates)
+    model: 'deepseek-chat',
+    refreshToken?: async () => ...,  // optional: refresh on 401
+    headers?: { 'X-Tenant': 'acme' }, // optional: extra headers
+  }),
+  ...
+})
+
+// Dev: direct mode (browser holds real key; dev only)
+createChatSdk({
+  llm: createProxyLlm({
+    mode: 'direct',
+    apiKey: 'sk-xxx',
+    baseUrl: 'https://api.deepseek.com/v1',
+    model: 'deepseek-chat',
+  }),
+  ...
+})
+```
+
+| | `proxy` (prod) | `direct` (dev) |
+|---|---|---|
+| apiKey | server (invisible) | browser (DevTools visible) |
+| browser holds | userToken | real apiKey |
+| token refresh | yes (401 retry) | n/a |
+| headers | supported | n/a |
+
+Server-side proxy essentials: validate userToken → inject real apiKey → forward to LLM API; handle CORS; stream SSE through; pass tool-calling fields. See `doc/usage-guide*.md` §8.6 for full guide.
+

package/skills/page-agent-sdk-integrate/references/integration-prompt.md

@@ -146,6 +146,7 @@ const sdk = createChatSdk({
 5. **Schema whitelist**: `z.object` auto-enables whitelist (only declared fields exposed); `discriminatedUnion`/`record`/`lazy` non-top-level don't enable (fully open)
 6. **Vue2 new-property non-reactive**: `write` patch `set` on a new field — Vue2 `Object.defineProperty` won't react → `onEvent('data_change')` `tick++`, use `:key="tick"` to force rebuild
 7. **MCP cold-start injects 0 tools**: `vite.config.ts` `optimizeDeps.include` pre-declares SDK sub-paths; keep those entries when forking config, else first MCP page load injects nothing (reload fixes)
+8. **apiKey leakage in production**: browser-direct LLM calls expose `apiKey` in DevTools. Use `createProxyLlm({ mode:'proxy', baseUrl:'/api/llm', userToken })` — browser holds only user token, your server injects the real key. See `references/quickstart.md` Stage 8 + `doc/usage-guide*.md` §8.6.
 
 ## Verification checklist
 
@@ -155,6 +156,8 @@ const sdk = createChatSdk({
 - [ ] [Reactive bind] edits → UI reacts; [non-reactive] `data_change` → re-render
 - [ ] [Drawer mode] close then open (`show()`) → history & in-flight generation preserved
 - [ ] Schema validation failure → structured error, no write
+- [ ] [Production] `createProxyLlm({ mode:'proxy' })` — real apiKey not in browser bundle / network tab
+- [ ] [Production] `createProxyLlm({ mode:'proxy' })` — real apiKey not in browser bundle / network tab
 
 ## References
 
@@ -177,3 +180,4 @@ Per your business scenario, fill in `systemPrompt` / `skills` / `data.schema`:
 - **Multi-agent on one page**: same `id` + `shareContext:true` → multiple dialogs share one `AgentCore`; or independent `id`s + `dialog.drawer:true` + `hide`/`show` for exclusive switching
 - **MCP integration**: `mcp:[{transport,url}]` remote tool servers; `@modelcontextprotocol/sdk` optional peerDep
 - **Dynamic/lazy-loaded schema**: `sdk.setData({ schema, bind })` on component mount to swap main data; tools pick up immediately, no rebuild
+- **Production proxy (prevent apiKey leakage)**: `createProxyLlm({ mode:'proxy', baseUrl:'/api/llm', userToken, refreshToken })` — browser holds only user token, server injects real key + forwards; dev uses `mode:'direct'` with real key. See `examples/proxy-demo/` + `npm run proxy:mock`

package/skills/page-agent-sdk-integrate/references/options.md

@@ -9,6 +9,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | `llm` | `LLMConfig \| BaseChatModel` | — (required) | The model. `LLMConfig = { apiKey, baseUrl, model, temperature?, maxTokens? }` (OpenAI-compatible; DeepSeek default). Or pass any LangChain `BaseChatModel` (e.g. `ChatAnthropic`, install its peerDep). |
 | `systemPrompt` | `string` | built-in default (JSON-operation assistant + reliable write rules) | Agent identity/instructions. Inject here, not hardcoded. Keep single-line in `.env` (`VITE_AI_SYSTEM_PROMPT`). If omitted, a built-in default is used (JSON-operation assistant + `systemPromptHelpers.reliableWriteRules`); passing your own fully overrides it. |
 | `appendReliableWriteRules` | `boolean` | `true` | When `true` (default) and a custom `systemPrompt` is set, auto-append `systemPromptHelpers.reliableWriteRules` to it with a `---` separator (clearly distinguishes user content from SDK-appended write rules; avoids forgetting the write rules). Set `false` to disable. No effect when `systemPrompt` is omitted (default prompt already includes them). |
+| `augmentSystem` | `(ctx:{state,data?}) => string \| undefined` | — | Dynamic system-prompt injection hook. Called each turn; return a string to inject as a segment, or `undefined` to skip. Callback errors degrade to skip (no crash). `ctx.data` is taken from `liveData()` each turn (auto-syncs after `setData`), so you can compute dynamic component descriptions / partial schema hints from current runtime state. Segment is placed after built-in segments (base/dataHint/usageHints/.../subagents) and before user `middleware`. Not set = current behavior (no segment). See `doc/system-prompt.md` §B6. |
 | `id` | `string` | random + warn | Stable agent id for multi-agent isolation & persistence. **Must pass a stable value** if you use `storage` or run multiple agents on one page. |
 
 ## UI & mounting
@@ -98,7 +99,7 @@ Full reference for `createChatSdk(options)`. Grouped by purpose. Required: `llm`
 | Option | Type | Default | Purpose / when |
 |---|---|---|---|
 | `subagent` | `object` | enabled | `{ enabled?, allowedTools?, systemPrompt?, temperature?, maxTokens?, skills?, llm?, maxDepth?, maxParallel? }`. `maxDepth` (1) physically cuts recursion. Subagents get a read-only tool subset (no spawn). |
-| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. |
+| `subagents` | `SubagentConfig[]` | `[]` | Pre-declared named subagents → each auto-generates a `use_<id>({ task })` delegation tool (Claude-Code style). Fixed roles (research/review) vs ad-hoc `spawn_agent`. Pass `[]` (empty array) to enable the `SubagentsController` for runtime `addSubagent`/`removeSubagent`/`setSubagents` (initial no subagents, add dynamically later). |
 
 ## Verify (self-check before return)
 

package/skills/page-agent-sdk-integrate/references/quickstart.md

@@ -147,6 +147,40 @@ sdk.getData()  // read current config
 
 **Full runnable demo**: `examples/dynamic-demo/` (`npm run dev` → `/examples/dynamic-demo/`).
 
+## Stage 8 — Production: proxy the LLM (prevent apiKey leakage)
+
+Browser-direct LLM calls expose your `apiKey` in DevTools — anyone can drain your quota. **Production must proxy through your server**: the browser holds only a user token; your server injects the real `apiKey` and forwards. Use `createProxyLlm` to unify dev (direct) and prod (proxy) without restructuring:
+
+```ts
+import { createChatSdk, createProxyLlm } from 'page-agent-sdk'
+
+// Production: proxy mode (safe — real key stays server-side)
+const sdk = createChatSdk({
+  container: '#root',
+  llm: createProxyLlm({
+    mode: 'proxy',
+    baseUrl: '/api/llm',            // your proxy (same-origin avoids CORS)
+    userToken: getUserToken(),       // session token (server validates, swaps in real key)
+    model: 'deepseek-chat',
+    refreshToken: async () => (await (await fetch('/api/refresh')).json()).token, // auto-refresh on 401
+    headers: { 'X-Tenant': 'acme' }, // optional custom headers
+  }),
+  // ...data, systemPrompt...
+}).mount()
+
+// Dev: direct mode (convenient — real key in browser; dev only)
+const sdkDev = createChatSdk({
+  container: '#root',
+  llm: createProxyLlm({
+    mode: 'direct',
+    apiKey: 'sk-...', baseUrl: 'https://api.deepseek.com/v1', model: 'deepseek-chat',
+  }),
+  // ...data, systemPrompt...
+}).mount()
+```
+
+Both modes require an **OpenAI Chat Completions compatible** endpoint (the SDK uses `ChatOpenAI` internally). The proxy must: validate `userToken` → inject real `apiKey` → forward to upstream → stream SSE through → pass `tools`/`tool_calls` through. See `doc/usage-guide*.md` §8.6 for the full guide + a Node.js proxy example, and `examples/proxy-demo/` for a runnable demo (`npm run proxy:mock` + `npm run dev` → `/examples/proxy-demo/`).
+
 ## Next
 
 - All options: see [options.md](options.md)

package/types/index.d.ts

@@ -1,6 +1,21 @@
 import { DefineComponent, Ref } from 'vue';
 export { z } from 'zod';
 
+// 代理连接模块(防 apiKey 泄露:proxy 代理模式 / direct 直连模式)
+export type ProxyLlmMode = 'proxy' | 'direct';
+export interface ProxyLlmOptions {
+  mode: ProxyLlmMode;
+  baseUrl?: string;
+  userToken?: string;
+  apiKey?: string;
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  refreshToken?: () => Promise<string>;
+  headers?: Record<string, string>;
+}
+export declare function createProxyLlm(opts: ProxyLlmOptions): import('@langchain/core/language_models/chat_models').BaseChatModel;
+
 export interface ToolStep {
   name: string;
   args?: any;
@@ -95,6 +110,8 @@ export interface SubagentInfo {
   maxDepth: number;
   maxParallel: number;
   allowedTools: string[];
+  /** 预声明子 agent 列表(动态:反映 setSubagents/addSubagent/removeSubagent 后的最新) */
+  subagents?: { id: string; description: string }[];
 }
 /** 预声明子 agent 配置(同主配置子集 + id/description;缺省继承主 agent) */
 export interface SubagentConfig {
@@ -354,6 +371,16 @@ export interface SessionOptions {
   title?: string;
 }
 
+/**
+ * augmentSystem 钩子上下文:集成方回调据此按运行时状态动态注入 system prompt 段。
+ * - `state`:harness 当前状态(messages/todos/files/skills/memory…);不含 data(data 是 createChatSdk 层概念)
+ * - `data`:当前主数据配置(每轮从 liveData() 取最新,setData 后自动同步;含 schema/bind/description)
+ */
+export interface SystemAugmentContext {
+  state: any;
+  data?: DataConfig;
+}
+
 export interface ChatSdkOptions {
   container?: string | HTMLElement;
   /** UI:'default'(内置 ChatDialog)/ false(headless 不渲染,自建 UI) */
@@ -367,9 +394,17 @@ export interface ChatSdkOptions {
   session?: SessionOptions;
   /** 共享上下文:默认 false;true 时同 id 复用同一核心(messages/agent/工作区) */
   shareContext?: boolean;
+  /** 系统提示词(base + 可操作数据段,数据段随 data 动态;不含 todos/skills/memory/augmentSystem 等运行态 augmentPrompt 段) */
   systemPrompt?: string;
   /** 自定义 systemPrompt 时是否自动追加 reliableWriteRules(默认 true,用 '---' 分隔线区分;设 false 关闭;不传 systemPrompt 用默认 prompt 时已内置,此项无效) */
   appendReliableWriteRules?: boolean;
+  /**
+   * 动态 system prompt 注入钩子:每轮 buildSystemPrompt 时调用,集成方按运行时状态(state/data)返回字符串 → 作为 system prompt 一段注入;返回 undefined → 跳过。
+   * - ctx.data 每轮从 liveData() 取最新(setData 后自动同步),可据此动态算组件说明 / 部分 schema 描述
+   * - 回调异常降级为跳过该段 + debug 日志(不崩 agent)
+   * - 段排在内置段之后、用户 middleware 之前;不配 = 完全现状行为
+   */
+  augmentSystem?: (ctx: SystemAugmentContext) => string | undefined;
   tools?: any[];
   skills?: SkillSpec[];
   /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
@@ -510,6 +545,22 @@ export interface ChatSdk {
   pendingConflict: Ref<PendingConflict | null>;
   /** 冲突解决:用户点「保留外部」(keep_external)/「强制覆盖」(overwrite)/「回退」(restore) → 收口挂起的 conflict,被挂起的工具调用继续 */
   resolveConflict(action: ConflictResolution['action']): void;
+  /** 运行时替换用户工具集(内置工具不动);立即 rebind + infoTick 刷新 */
+  setTools(tools: any[]): void;
+  /** 运行时追加用户工具(去重 by name);立即生效 */
+  addTool(tool: any): void;
+  /** 运行时移除用户工具(by name;内置不动);返回是否移除成功 */
+  removeTool(name: string): boolean;
+  /** 运行时切换 LLM(BaseChatModel 或 LLMConfig);rebind + 重解析能力 + infoTick */
+  setLlm(llm: ChatModelLike | LLMConfig): void;
+  /** 运行时更新 memory 文本;立即生效 + infoTick */
+  setMemory(text: string): void;
+  /** 运行时替换预声明子 agent 列表(重新生成委派工具 + rebind);需创建时配 subagents:[] */
+  setSubagents(configs: SubagentConfig[]): void;
+  /** 运行时追加预声明子 agent(id 重复 warn 跳过);需创建时配 subagents:[] */
+  addSubagent(config: SubagentConfig): void;
+  /** 运行时移除预声明子 agent(by id);返回是否移除成功;需创建时配 subagents:[] */
+  removeSubagent(id: string): boolean;
 }
 
 /** 乐观锁冲突挂起(dataOps 写入时 expectedHash 不匹配,挂起等用户决定) */
@@ -668,6 +719,12 @@ export interface StateUpdate { [k: string]: any }
 
 // 子 agent
 export declare function createSubagentsMiddleware(opts: any): any;
+export interface SubagentsController {
+  set(configs: SubagentConfig[]): void;
+  add(config: SubagentConfig): void;
+  remove(id: string): boolean;
+  get(): SubagentConfig[];
+}
 export interface SubagentOptions { [k: string]: any }
 export interface SubagentLlmConfig { [k: string]: any }