page-agent-sdk 2.16.0 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "type": "module",
   "description": "AI agent SDK for web pages — embed a chat assistant that edits page data via schema-validated tools. A lighter, framework-agnostic alternative to CopilotKit/LangChain for in-page JSON-editing agents. Vue-bundled; works with DeepSeek, OpenAI, MCP.",
   "main": "./dist/page-agent-sdk.umd.cjs",
@@ -50,7 +50,9 @@
     "test:e2e": "node tests/e2e-integration.mjs",
     "test:exports": "node tests/exports-consistency.mjs",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:size": "node tests/size-check.mjs"
+    "test:size": "node tests/size-check.mjs",
+    "test:browser": "playwright test",
+    "test:browser:ui": "playwright test --ui"
   },
   "keywords": [
     "ai",

package/skills/adaptive-planning/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: adaptive-planning
+description: 自适应规划标准流程——判断任务复杂度决定是否先规划,规划后可选用户确认,执行中动态增量修订
+---
+
+# 自适应规划流程
+
+> 内置 skill(add-adaptive-planning)。文档化 agent 运行时的自适应规划标准流程。
+> 集成方按需挂载:`createChatSdk({ skills: [adaptivePlanningSkill] })`,或从 npm 包 `skills/adaptive-planning` 取。
+
+## 1. 判断复杂度(自适应分流)
+
+- **简单**(单字段、明确、可逆,如「标题改红色」)→ 跳过规划,直接 `read` → `write`。
+- **复杂**(多步、大改、有歧义、不可逆,如「把首页改成营销活动页」)→ 进入规划。
+
+判断由你(LLM)完成,框架不强加。拿不准时倾向于规划(复杂任务不规划的代价 > 简单任务多规划的代价)。
+
+## 2. 规划(write_todos)
+
+拆解为**可执行**步骤,每步一个明确动作(`read` 某字段 / `write` 某路径 / `query` 筛选)。首个任务标 `in_progress`。
+
+```
+write_todos({ todos: [
+  { content: '读取当前 components 结构', status: 'in_progress' },
+  { content: '给 hero 组件加标题字段', status: 'pending' },
+  { content: 'read 确认写入', status: 'pending' },
+]})
+```
+
+框架给每步自动生成稳定 id(`t-1`/`t-2`...),也可显式传语义化 id(如 `read-structure`)。
+
+## 3.(可选)用户确认
+
+若方案有歧义 / 多选 / 高风险 → `request_human_confirmation` 给选项,用户确认后再执行:
+
+```
+request_human_confirmation({ question: '活动页主色调?', options: ['红色喜庆', '蓝色科技', '金色奢华'], recommendation: '红色喜庆' })
+```
+
+## 4. 执行
+
+按清单逐步 `read` / `write`。**完成一项立即标完成**(不必重传整个清单):
+
+```
+update_todo({ id: 't-1', status: 'completed' })
+```
+
+## 5. 动态修订(执行中完善)
+
+执行中发现步骤要改 / 补 / 细分 → `update_todo` 增量改单项,不必重传整个清单:
+
+- 改描述:`update_todo({ id: 't-2', content: '给 hero 组件加标题字段 + 副标题' })`
+- 补步骤:用 `write_todos` 重传完整清单(新增项会获得新 id)
+- 拆分:把一项标 completed,用 `write_todos` 补更细的子步骤
+
+## 防死循环(框架兜底)
+
+规划阶段有轮次预算(`maxPlanRevisions`,默认 5)。**勿反复调研 / 改计划而不执行**——超限框架会回灌「规划阶段已达上限,基于当前清单开始执行」。
+
+规划充分后即开始 `write` 落地(写工具成功即退出规划阶段,预算重置)。
+
+## 何时不用本 skill
+
+- 纯查询任务(只 read 不 write):直接 read/query/search,不必规划
+- 单步明确任务:直接 write
+- 已有领域 skill(如集成方的业务 skill)指导流程时:遵循那个

package/types/index.d.ts

@@ -75,7 +75,7 @@ export type SdkEvent =
   | { type: 'conflict'; conflict: PendingConflict }
   | { type: 'session_restored'; sessionId: string; rounds: number }
   | { type: 'usage'; round: number; usage: TokenUsage; cumulative: TokenUsage }
-  | { type: 'error'; message: string };
+  | { type: 'error'; message: string; severity?: 'recoverable' | 'fatal' | 'observable'; code?: string; context?: unknown };
 
 /** token 用量(OpenAI 协议字段名) */
 export interface TokenUsage {
@@ -139,7 +139,15 @@ export interface AgentInfo {
   contextPreset: 'auto' | 'conservative' | 'aggressive' | 'complex';
   memory: string;
   middleware: string[];
-  todos: { content: string; status: string }[];
+  todos: { id: string; content: string; status: string }[];
+  /** 规划阶段防死循环状态(maxPlanRevisions 预算;planning 关闭时 inPlanning 恒 false) */
+  planPhase?: { inPlanning: boolean; rounds: number; limit: number };
+  /** 当前任务目标锚点(mission 中间件;未开启/未 capture → undefined) */
+  mission?: Mission;
+  /** 宿主动作元信息(actions 注册;集成方 save_draft/publish 等) */
+  actions?: Record<string, { description: string; hasParams: boolean }>;
+  /** 跨压缩工作记忆(workingMemory 中间件;pin 最近 read/query/search 定位 path + read hash,≤10 LRU) */
+  workingMemory?: WorkingMemory;
   subagent: SubagentInfo;
   verify?: { enabled: boolean; maxAttempts: number; adversarial: boolean };
   mcp?: { servers: { name: string; url: string; toolCount: number }[] };
@@ -345,7 +353,7 @@ export interface SessionMeta {
 export interface SessionSnapshot {
   messages: AgentMessage[];
   vfs: Record<string, { content: string; mimeType?: string; updatedAt: number }>;
-  todos: { content: string; status: 'pending' | 'in_progress' | 'completed' }[];
+  todos: { id: string; content: string; status: 'pending' | 'in_progress' | 'completed' }[];
   memory: string;
 }
 export type StorageEvent =
@@ -387,6 +395,17 @@ export interface SystemAugmentContext {
   data?: DataConfig;
 }
 
+/** 宿主动作定义:集成方注册的页面操作(保存/发布/预览/导出等),SDK 自动包成命名 tool */
+export interface ActionDef {
+  /** 动作描述(给 LLM 看) */
+  description: string;
+  /** 执行函数;接收 params schema 解析的参数,返回值序列化回灌 LLM */
+  run: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+  /** 可选参数 schema(ZodObject);不传 = 无参 tool */
+  params?: any;
+}
+/** actions 配置:动作名 → 定义(动作名即 tool 名,须合法标识符) */
+export type ActionMap = Record<string, ActionDef>;
 export interface ChatSdkOptions {
   container?: string | HTMLElement;
   /** UI:'default'(内置 ChatDialog)/ false(headless 不渲染,自建 UI) */
@@ -412,12 +431,16 @@ export interface ChatSdkOptions {
    */
   augmentSystem?: (ctx: SystemAugmentContext) => string | undefined;
   tools?: any[];
+  /** 宿主动作:集成方注册的页面操作(保存/发布/预览等),SDK 自动包成命名 tool;LLM 直接看到命名 tool */
+  actions?: ActionMap;
   skills?: SkillSpec[];
   /** 用户创建 skill 的独立持久化存储(与 storage 选项分离)。默认 `{ backend: 'indexed' }`(即使 storage:false 也持久化);`false` 关闭;`id` 手动指定同一 id 可跨页面/跨 agent 复用 */
   skillStorage?: SkillStoreConfig | false;
   /** AGENTS.md 风格持久指令。支持 string 与同步/异步函数(异步函数适合加载 RAG 文档) */
   memory?: string | (() => string | Promise<string>);
   data?: DataConfig;
+  /** 大 schema 分层披露阈值(默认 maxKeys=15/maxChars=4000;超则 systemPrompt 只注入顶层概览,深层约束查 schema_data) */
+  schemaHint?: SchemaHintOptions;
   permissions?: PermissionRule[];
   /** 自定义中间件(注入到内置中间件之后;可拦截/观察模型调用、工具、prompt) */
   middleware?: any[];
@@ -443,6 +466,8 @@ export interface ChatSdkOptions {
   maxMemoryRounds?: number;
   debug?: boolean;
   maxToolRounds?: number;
+  /** 规划阶段总轮次预算(默认 5);planning 状态下超限 → write_todos/update_todo 回灌,防"光规划不执行"死循环。与 maxIterations 正交 */
+  maxPlanRevisions?: number;
   /** 模型调用失败自动重试次数(默认 2;网络/429/5xx 重试,4xx 与 abort 不重试) */
   maxRetries?: number;
   /** 同轮工具并发上限(默认 1 串行) */
@@ -452,7 +477,7 @@ export interface ChatSdkOptions {
   /** 模型最大输出(token);顶层声明对 llm 实例场景也生效,缺省按 model 名查表 */
   maxOutputTokens?: number;
   /** 子 agent 委派(默认开启;{ enabled: false } 关闭) */
-  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean };
+  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; missionAnchor?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean; domInspect?: boolean; workingMemory?: boolean };
   subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number };
   /** 预声明子 agent 列表:每个用同主配置方式声明,自动生成 use_<id> 委派工具(与 spawn_agent 共存) */
   subagents?: SubagentConfig[];
@@ -500,6 +525,25 @@ export interface DialogConfig {
   onClose?: () => void;
 }
 
+/** 会话级任务目标锚点(mission 中间件;capture 或 setMission;revive-mission-anchor Phase 1) */
+/** 跨压缩工作记忆(workingMemory 中间件;经 augmentPrompt 每轮注入 system,天然跨压缩保留) */
+export interface WorkingMemory {
+  locatedPaths: string[];
+  lastHashes: Record<string, string>;
+}
+export interface Mission {
+  /** 一句话任务目标(必填) */
+  goal: string;
+  /** 完成标准(可选,集成方显式传入) */
+  acceptanceCriteria?: string[];
+  /** 来源 user 消息 index(自动 capture 时填) */
+  sourceMessageIdx: number;
+  /** capture/setMission 时间戳 */
+  capturedAt: number;
+  /** true=集成方显式 setMission;false=自动 capture */
+  explicit: boolean;
+}
+
 export interface ChatSdk {
   /** 渲染对话框到 container(异步:含持久化恢复);ui:false 时仅 init agent(headless)。
    *  可选传 overrideContainer(HTMLElement | 选择器字符串)覆盖创建时 options.container —— 异步绑定:创建时可省略 container,mount 时才指定 */
@@ -511,11 +555,15 @@ export interface ChatSdk {
   hide(): void;
   /** 抽屉模式显示:移除 cs-hidden class 恢复可见(配合 hide 使用;首次挂载用 mount) */
   show(): void;
-  send(message: string): Promise<string>;
+  send(message: string, options?: { mission?: Partial<Mission> }): Promise<string>;
   switchSession(sessionId?: string): Promise<string>;
   stream: (messages: AgentMessage[], onEvent: StreamHandler, signal?: AbortSignal) => Promise<string>;
   /** 检视 agent 详细信息(tools/skills/data/middleware/todos) */
   inspect(): AgentInfo;
+  /** 读取当前任务目标锚点 mission(自动 capture 或 setMission;capabilities.missionAnchor:false → undefined) */
+  getMission(): Mission | undefined;
+  /** 显式设置/覆盖 mission(传 {goal} 重设;传 {goal,criteria} 整体替换;传 {} 清空);capabilities 关时 warn 不抛 */
+  setMission(mission: Partial<Mission>): void;
   /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 主数据 + vfs + todos);需开启 checkpoint,无可用返回 false */
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */
@@ -639,6 +687,8 @@ export declare function applyPatchToClone(clone: any, op: EditOp, jsonPath: stri
 export declare function applyPatchToLive(bind: any, op: EditOp, jsonPath: string, value: unknown): void;
 export declare function restoreLive(bind: any, snapshotVal: unknown): void;
 export declare function restoreInPlace(live: Record<string, unknown> | unknown[], snapshotVal: unknown): void;
+/** 深度差异对比(对象/数组递归,叶子差异),返回 {path, from, to}[];供 diff_data / verify 自纠 / 审计复用 */
+export declare function diffObjects(a: unknown, b: unknown, prefix?: string): { path: string; from: unknown; to: unknown }[];
 // ============ schema 白名单投影纯函数(schemaUtils,refactor-module-extraction 从 dataOps 抽离)============
 export declare function getSchemaTopKeys(schema: any): string[] | null;
 export declare function isPathAllowed(jsonPath: string, schema: any | null, allowKeys: string[] | null): boolean;
@@ -646,6 +696,37 @@ export declare function unwrapSchema(schema: any): any;
 export declare function getSchemaAtPath(schema: any, jsonPath: string): any | null;
 export declare function projectBySchemaDeep(obj: unknown, schema: any | null): unknown;
 export declare function projectBySchema(obj: unknown, allowKeys: string[] | null): unknown;
+// ============ schema 约束结构化提取(expose-schema-constraints;供 systemPrompt「可操作数据」段 / read 概览 / schema_data 工具)============
+export interface SchemaNodeDesc {
+  type: string;
+  constraints?: {
+    minLength?: number; maxLength?: number; length?: number;
+    min?: number; max?: number; int?: boolean;
+    format?: string | string[];
+    values?: readonly (string | number)[];
+    value?: unknown;
+    item?: SchemaNodeDesc;
+    shape?: Record<string, SchemaNodeDesc>;
+    anyOf?: SchemaNodeDesc[];
+    valueType?: SchemaNodeDesc;
+  };
+  optional?: boolean;
+  nullable?: boolean;
+  default?: unknown;
+  description?: string;
+}
+/** 结构化提取单个 zod 节点的约束(type + 关键约束 + optional/default/nullable;zod 4 `_def`/`_zod.def` 读取) */
+export declare function describeSchemaNode(schema: any): SchemaNodeDesc;
+/** 把标量约束格式化为括号内短串(min/max/enum/format 等;shape/item/anyOf 不渲染) */
+export declare function formatConstraints(c: NonNullable<SchemaNodeDesc['constraints']>): string;
+/** 渲染单行字段标注 `- key (Type?)[约束]: description` */
+export declare function renderSchemaHint(key: string, desc: SchemaNodeDesc): string;
+/** 渲染 schema 顶层字段约束总览(非 object fallback 根节点;供 extractSchemaHint + read 概览复用) */
+export declare function renderSchemaOverview(schema: any): string;
+/** 渲染 schema 顶层字段浅概览(分层模式:只 key+type+desc,不带约束/不递归;大 schema 用,体积降) */
+export declare function renderSchemaShallow(schema: any): string;
+/** extractSchemaHint 分层阈值配置(默认 maxKeys=15/maxChars=4000;超则转顶层概览) */
+export interface SchemaHintOptions { maxKeys?: number; maxChars?: number }
 // ============ 上下文索引纯函数(contextIndex,refactor-module-extraction 期二 从 useContextManager 抽离)============
 export declare const STOP_WORDS: Set<string>;
 export declare function tokenize(text: string): string[];
@@ -672,9 +753,20 @@ export interface SdkEvents {
   hook(handler: (e: any) => void): () => void;
 }
 export declare function createSdkEvents(onEvent?: (e: any) => void): SdkEvents;
-export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean } | undefined, dataOps: any[], fetchDocs: any[]): any[];
+export declare function selectBuiltinTools(caps: { dataOps?: boolean; fetch?: boolean; domInspect?: boolean } | undefined, dataOps: any[], fetchDocs: any[], dom?: any[]): any[];
 export declare function createUsageHintsMiddleware(caps: { planning?: boolean; dataOps?: boolean; subagent?: boolean } | undefined, hasDataOps: boolean, toolMode?: 'simple' | 'advanced' | 'minimal'): any;
 export declare const fetchDocTools: any[];
+/** DOM 读取工具 get_dom(随 capabilities.domInspect 装配,opt-in) */
+export declare const domTools: any[];
+export declare const domToolsStatic: any[];
+export declare const getDomTool: any;
+/** 纯函数:DOM Element → 结构化 DomNode(可单测,与浏览器解耦) */
+export declare function domToStructure(node: Element | null, opts: { depth: number; attrs?: string[]; includeText?: boolean }): DomNode | null;
+/** 把集成方注册的 actions 转成命名 tool 数组(每个 action 一个 tool) */
+export declare function actionsToTools(actions: ActionMap): any[];
+export declare function actionsToInspectInfo(actions: ActionMap): Record<string, { description: string; hasParams: boolean }>;
+export interface DomNode { tag: string; attrs: Record<string, string>; text?: string; children?: DomNode[]; childCount?: number }
+export interface DomReadOptions { depth: number; attrs?: string[]; includeText?: boolean }
 export declare const fetchTools: any[];
 export declare function defineDataToolset(config: DataConfig, opts?: DataOpsOptions): any[];
 export declare function defineSkill(spec: SkillSpec): SkillSpec;
@@ -770,6 +862,24 @@ export declare function zodError(path: string, issues: unknown[]): string;
 export declare function jsonParseError(path: string | undefined, raw: string, err: unknown): string;
 /** 提取 zod issues 为结构化 details(每条 path/expected/received/message) */
 export declare function formatZodIssues(issues: unknown[]): unknown[];
+// ============ 统一错误模型(unify-error-model:三档 severity,各 catch 点按档路由)============
+/** 错误严重程度三档:recoverable(回灌)/ fatal(中断)/ observable(记录不中断) */
+export type ErrorSeverity = 'recoverable' | 'fatal' | 'observable';
+/** 统一错误对象(结构化,跨层传递;普通 Error 经 asAgentError 归一化) */
+export interface AgentError {
+  severity: ErrorSeverity;
+  message: string;
+  code?: string;
+  context?: unknown;
+}
+/** 错误路由:recoverable→feedback / fatal→abort / observable→log */
+export type ErrorRouting = 'feedback' | 'abort' | 'log';
+/** 路由纯函数:据 severity 决定错误如何被处理 */
+export declare function routeError(err: AgentError): ErrorRouting;
+/** 把任意错误归一化为 AgentError(已是 AgentError 不覆盖;普通 Error 用 defaultSeverity,默认 fatal) */
+export declare function asAgentError(err: unknown, defaultSeverity?: ErrorSeverity): AgentError;
+/** AgentError 便捷工厂 */
+export declare function agentError(severity: ErrorSeverity, message: string, code?: string, context?: unknown): AgentError;
 
 // === 与 src/core/index.ts 导出对齐(消费者类型完整;复杂内部类型用宽松声明,消费者主要消费工厂返回值) ===
 // 上下文压缩预设