page-agent-sdk 4.14.0 → 4.16.0

package/types/index.d.ts

@@ -59,6 +59,8 @@ export interface ToolStep {
   /** 工具执行耗时(毫秒,tool_result 时回填) */
   durationMs?: number;
   /** 子 agent 工具步骤(spawn 委派时展示子进度) */
+  /** 截图产出(page-screenshot;tool_result 事件富化,MessageSteps 渲染缩略图观察面) */
+  image?: { dataUri: string; thumb?: string; vfsRef?: string };
   children?: ToolStep[];
   /** 子 agent 思考过程累积(reasoning 转发;超长截尾仅留尾部);展示"在想什么" */
   subReason?: string;
@@ -133,6 +135,14 @@ export declare class ImageInputError extends Error {
  * 浏览器域 API(依赖 canvas/document);node 环境不可用。
  */
 export declare function compressImage(source: Blob, opts?: { name?: string }): Promise<AgentImage>;
+/** user 消息附带引用(page-quote 划词提问):宿主页面选中文本作为提问上下文(引用回复形态) */
+export interface MessageQuote {
+  /** 引用原文(宿主页面选中文本;捕获与 setQuote 统一截断上限 2000 字符) */
+  text: string
+  /** 来源描述(自动捕获 = 页面 title + 最近的在前标题;宿主 setQuote 可自定义) */
+  source?: string
+}
+export declare function captureSelectionQuote(doc: { getSelection?(): { isCollapsed?: boolean; anchorNode?: Node | null; toString(): string } | null; title?: string; querySelectorAll?: (selector: string) => ArrayLike<Element> }): MessageQuote | null;
 
 export interface AgentMessage {
   role: 'user' | 'assistant' | 'system';
@@ -165,7 +175,7 @@ export type StreamEvent =
   | { type: 'reasoning'; delta: string }
   | { type: 'text'; delta: string }
   | { type: 'tool_call'; name: string; args: any; id?: string }
-  | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error'; durationMs?: number; id?: string }
+  | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error'; durationMs?: number; id?: string; /** 截图产出(page-screenshot;vision 通道合成消息之外的可观察面,UI 缩略图消费) */ image?: { dataUri: string; thumb?: string; vfsRef?: string } }
   | { type: 'subagent'; taskId: string; label: string; kind: 'tool_call' | 'tool_result' | 'reasoning'; name: string; args?: any; result?: string; status?: 'done' | 'error'; delta?: string; toolCallId?: string }
   | { type: 'approval_request'; toolName: string; args: any; resolve: (approved: boolean | string) => void; hold?: () => void; preview?: ApprovalWritePreview }
   | { type: 'done'; content: string };
@@ -182,7 +192,7 @@ export type SdkEvent =
   | { type: 'reasoning'; delta: string }
   | { type: 'text'; delta: string }
   | { type: 'tool_call'; name: string; args: any; id?: string }
-  | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error'; durationMs?: number; id?: string }
+  | { type: 'tool_result'; name: string; result: string; status: 'done' | 'error'; durationMs?: number; id?: string; /** 截图产出(page-screenshot;vision 通道合成消息之外的可观察面,UI 缩略图消费) */ image?: { dataUri: string; thumb?: string; vfsRef?: string } }
   | { type: 'subagent'; taskId: string; label: string; kind: 'tool_call' | 'tool_result' | 'reasoning'; name: string; args?: any; result?: string; status?: 'done' | 'error'; delta?: string; /** 关联主循环工具调用 id(并行双委派各归各 UI step) */ toolCallId?: string }
   | { type: 'done'; content: string }
   | { type: 'data_change'; operation: 'set' | 'edit' | 'delete' | 'restore'; value?: unknown }
@@ -860,7 +870,7 @@ export interface UseChatReturn {
   /** 排队待发的任务内容(生成中再发 → 入队显示在排队区) */
   queuedTasks: Ref<string[]>;
   /** 发送(生成中再发 → 入排队区;images 需主模型多模态或 images.describe 配置,否则拒绝并 emit 结构化错误不静默丢图) */
-  sendMessage(content: string, focuses?: Focus[], images?: AgentImage[]): Promise<void>;
+  sendMessage(content: string, focuses?: Focus[], images?: AgentImage[], quote?: MessageQuote): Promise<void>;
   /** 手动撤销排队任务 */
   removeQueuedTask(idx: number): void;
   /** 清空对话(onClear 回调) */
@@ -1332,8 +1342,13 @@ export interface ChatSdkOptions {
   maxOutputTokens?: number;
   /** 图片输入配置组(image-input-vision):images.upload 上传换 URL(集成方 OSS)/ images.describe 绑定识图转述(集成方识图子 agent / 自有 vision API,非多模态主模型时转述注入) */
   images?: ImagesConfig;
+  /**
+   * 截图配置组(take_screenshot;装配条件 = capabilities.domInspect 开 && (主模型多模态 vision || images.describe 已配),
+   * 不满足不装并 warn 留痕)。默认渲染 = 内置 html-to-image;宿主 CSP 限制 SVG data URL 或需特殊裁剪时传 renderer 覆盖
+   */
+  screenshot?: { renderer?: (el: Element, opts: { width?: number; height?: number }) => Promise<string> };
   /** 子 agent 委派(默认开启;{ enabled: false } 关闭) */
-  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; missionAnchor?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean; domInspect?: boolean; inspectEnv?: boolean; draftWrite?: boolean; automation?: boolean; workingMemory?: boolean; focus?: boolean; contextInspector?: boolean; agentCompression?: boolean };/** tracing/skillHostScript/preferences/bulkGuard 已于 4.1.0 移除;残键静默忽略 */
+  capabilities?: { dataOps?: boolean; fetch?: boolean; planning?: boolean; missionAnchor?: boolean; skills?: boolean; vfs?: boolean; summarization?: boolean; memory?: boolean; subagent?: boolean; verify?: boolean; domInspect?: boolean; inspectEnv?: boolean; draftWrite?: boolean; automation?: boolean; workingMemory?: boolean; focus?: boolean; contextInspector?: boolean; agentCompression?: boolean; pageContext?: boolean };/** tracing/skillHostScript/preferences/bulkGuard 已于 4.1.0 移除;残键静默忽略 */
   subagent?: { enabled?: boolean; allowedTools?: string[]; systemPrompt?: string; temperature?: number; maxTokens?: number; skills?: SkillSpec[]; llm?: LLMConfig | ChatModelLike; maxDepth?: number; maxParallel?: number; /** 单次委派总时长毫秒(默认 1800000=30min,2026-08-28 抬升;超时 abort 子流 + recoverable 回灌;0 = 不限制) */ timeoutMs?: number; thinkingMode?: 'simple' | 'deep' };
   /** 预声明子 agent 列表:每个用同主配置方式声明,自动生成 use_<id> 委派工具(与 spawn_agent 共存) */
   subagents?: SubagentConfig[];
@@ -1389,6 +1404,10 @@ export interface DialogConfig {
   quickActions?: QuickActionItem[];
   /** 拖拽宿主元素入输入框回调(ui-quick-wins Q4 元素聚焦入口):window 捕获 dragstart 记源元素(drop 的 event.target 是输入框自身拿不到源),drop 无文件且源元素仍连文档时回调。映射 el→jsonPath→setFocus 归宿主。未声明零开销 */
   onDropElement?: (el: Element) => void;
+  /** 划词自动捕获(page-quote,默认 false):true 时打开抽屉 / 点击输入区瞬间懒捕获宿主页面(对话框外)当前选中文本挂「引用 chip」(可删),随下一条消息作为提问上下文发给 LLM。opt-in(隐私);宿主 API sdk.setQuote/clearQuote 不受此开关影响 */
+  autoQuote?: boolean;
+  /** 划词浮动菜单(page-quote 显式确认形态,默认 false):划选宿主文字浮出「❝ 引用到对话」工具条(选区上方,fixed),点击 = 挂引用 chip + 打开对话框 + 聚焦输入;点别处/滚动/Esc 消失。与 autoQuote 独立可组合 */
+  selectionMenu?: boolean;
   /** 会话导出/导入 UI 入口(ui-quick-wins Q2):历史面板底部显示「导出会话/导入会话…」(下载 .json / 选文件导入并切换)。默认 false 不显示;sdk.exportSession/importSession API 恒可用(与 UI 开关无关) */
   sessionTransfer?: boolean;
   drawer?: boolean;
@@ -1479,7 +1498,7 @@ export interface ChatSdk {
   hide(): void;
   /** 抽屉模式显示:移除 cs-hidden class 恢复可见(配合 hide 使用;首次挂载用 mount) */
   show(): void;
-  send(message: string, options?: { mission?: Partial<Mission>; maxAutoRetries?: number; /** 中断信号(fix-hang-and-feedback P1-4) */ signal?: AbortSignal; /** 附带图片(image-input-vision;≤4 张,压缩后 AgentImage;需主模型多模态 vision 或配置 images.describe,否则 send 拒绝并 emit 结构化错误 —— 不静默丢图) */ images?: AgentImage[] }): Promise<string>;
+  send(message: string, options?: { mission?: Partial<Mission>; maxAutoRetries?: number; /** 中断信号(fix-hang-and-feedback P1-4) */ signal?: AbortSignal; /** 附带图片(image-input-vision;≤4 张,压缩后 AgentImage;需主模型多模态 vision 或配置 images.describe,否则 send 拒绝并 emit 结构化错误 —— 不静默丢图) */ images?: AgentImage[]; /** 附带引用(page-quote;显式传入优先于待发引用(pendingQuote)且不消费它;文本超 2000 截断) */ quote?: MessageQuote }): Promise<string>;
   switchSession(sessionId?: string): Promise<string>;
   /** 导出会话快照(ui-quick-wins Q2):可复全 JSON 信封 { formatVersion, exportedAt, sessionId, snapshot }(含 vfs/todos/mission/focus 等 kind)。当前会话先收口内存态再读,导出的就是「恢复时能得到的真值」;跨会话导出传 sessionId 只读已持久态。storage 未开启抛错 */
   exportSession(sessionId?: string): Promise<Record<string, unknown>>;
@@ -1530,6 +1549,10 @@ export interface ChatSdk {
   removeFocus(path: string): void;
   /** 清除全部聚焦焦点(退出精修模式,恢复全量可操作范围) */
   clearFocus(): void;
+  /** 挂「待发引用」(page-quote):下一条 send 附带并消费(空文本=清除;文本归一+截2000;内置 UI autoQuote 划词捕获与此共用状态) */
+  setQuote(text: string, source?: string): void;
+  /** 清除待发引用 */
+  clearQuote(): void;
   /** 回退到最近一次正常 checkpoint(整体还原对话历史 + 主数据 + vfs + todos);需开启 checkpoint,无可用返回 false */
   restoreLastCheckpoint(): boolean;
   /** 列出可用 checkpoint(回退点);需开启 checkpoint,未开启返回空数组 */
@@ -1660,7 +1683,7 @@ export declare function buildDataPrompt(data: DataConfig | undefined, schemaHint
  * 传 systemPrompt 默认追加 reliableWriteRules(设 appendReliableWriteRules:false 关闭);不传用 DEFAULT_SYSTEM_PROMPT(已内置)。纯函数。
  * locale:'en-US' 时默认 prompt 用 DEFAULT_SYSTEM_PROMPT_EN、追加规则段用 reliableWriteRulesEn(默认 prompt 与 UI 同语言)。
  */
-export declare function buildSystemPrompt(opts: { systemPrompt?: string; appendReliableWriteRules?: boolean; locale?: DialogLocale }): string;
+export declare function buildSystemPrompt(opts: { systemPrompt?: string; appendReliableWriteRules?: boolean; locale?: DialogLocale; /** 主数据操作能力(caps.dataOps && data 声明;createChatSdk 自动传,直调缺省 true = 历史行为;false 时默认身份不再是「JSON 操作助手」且不追加写入规则) */ dataOps?: boolean; /** 页面探查能力(caps.domInspect;dataOps:false 时默认身份切「页面内容助手」) */ domInspect?: boolean; /** take_screenshot 已装配(未装不教,页面身份截图行收起) */ screenshot?: boolean }): string;
 export declare function defineTool(opts: {
   name: string;
   description: string;