page-agent-sdk 2.10.2 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.10.2",
+  "version": "2.11.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/api.md

@@ -173,3 +173,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/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;