@webskill/chatbot 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -1,31 +1,9 @@
-import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocumentSurfaceHost, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
-import { SandboxMode, TypeScriptSupportOptions } from "@webskill/sdk/browser";
-import { CustomSurfaceActionEvent, ReactBridgeState, SpecInteractionChannel, SurfaceRegistry, UiSurfaceActionEvent } from "@webskill/sdk/ui-react";
-import { DownloadedFileConsent, DownloadedFileReader, PageActionPolicy, PagePerceptionPolicy, PerceptionPagingBudget, PerceptionRecord, SkillCandidateSink, TabWorksetPolicy, TodoItem } from "@webskill/sdk/agent";
+import { a as RuntimeRendererId, c as RuntimeQuickPrompt, d as TranslateFn, i as RuntimeLlmEntry, l as Locale, n as RuntimeConfig, o as QuickPrompt, r as RuntimeConfigStore, s as QuickPromptIconName, t as RuntimeAppearanceConfig, u as LocalizedText } from "./index-Nnkn73aD.js";
 import "react";
-import "react/jsx-runtime";
-//#region ../ui-kit/src/i18n/types.d.ts
-/** @stable */
-type Locale = 'zh' | 'en';
-/**
- * 宿主 / 用户提供的、随界面语言切换的短文案（0.13.0 分册 21 FR-21.1）。
- * SDK 自己的界面文案走 `createI18n` 字典，不用这个类型。
- * 允许只填部分语种，缺的语种由 `resolveLocalizedText` 借用已填的。
- * @experimental
- */
-type LocalizedText = Partial<Record<Locale, string>>;
-/** 单语言词条：key → 文案（支持 {name} 占位插值） */
-type LocaleMessages = Record<string, string>;
-/** 双语字典：zh/en 两个 locale 的键集必须一致（见 assertDictionaryComplete） */
-interface Dictionary {
-  en: LocaleMessages;
-  zh: LocaleMessages;
-}
-type DictionaryKey<D extends Dictionary> = keyof D['en'] & string;
-type InterpolationParams = Record<string, string | number>;
-/** t(key, params?)：查当前 locale 词条并做 {name} 插值 */
-type TranslateFn<D extends Dictionary = Dictionary> = (key: DictionaryKey<D>, params?: InterpolationParams) => string;
-//#endregion
+import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocumentSurfaceHost, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, VisionDelegate, VisionDelegateRequest, VisionDelegateResult, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
+import { SandboxMode, TypeScriptSupportOptions, WebOfficeConsent, WebOfficeHost } from "@webskill/sdk/browser";
+import { CustomSurfaceActionEvent, ReactBridgeState, SpecInteractionChannel, SurfaceRegistry, UiSurfaceActionEvent } from "@webskill/sdk/ui-react";
+import { ConsentUi, DocxDocumentReader, DownloadedFileConsent, DownloadedFileReader, PageActionPolicy, PagePerceptionPolicy, PdfDocumentReader, PerceptionPagingBudget, PerceptionRecord, SkillCandidateSink, TabWorksetPolicy, TodoItem, XlsxDocumentReader } from "@webskill/sdk/agent";
 //#region ../core/src/attachment/kind.d.ts
 /**
  * 附件类型判据与文本形态。0.14.0 分册 20 从 `@webskill/chatbot` 迁入：
@@ -74,371 +52,6 @@ interface DocumentSurfacePort {
   }): Promise<void>;
 }
 //#endregion
-//#region ../runtime/src/sandbox/bridgeProtocol.d.ts
-/**
- * 能力模式：true 直通 / false 关闭（TOOL_UNSUPPORTED）/ 'require-approval' 调用前强制授权
- * （布尔语义与现状完全兼容）
- */
-type CapabilityMode = boolean | 'require-approval';
-/** 授权粒度：'once-per-run'（默认，run 内同类能力批准一次）/ 'every-call'（每次调用都问） */
-type ApprovalScope$1 = 'once-per-run' | 'every-call';
-//#endregion
-//#region ../runtime/src/sandbox/networkPolicy.d.ts
-/**
- * 网络策略类型 + 匹配逻辑（单一来源：browser worker 经函数字符串注入、
- * node worker 直接 import，禁止各自重复实现）。
- *
- * 注意：isNetworkAllowed 会被 toString() 内嵌进浏览器 Worker bootstrap，
- * 函数体必须自包含（不引用模块内其它符号），且不得使用模板字符串/反引号。
- */
-type NetworkPolicy$1 = 'deny-all' | 'allow-all' | {
-  allow: string[];
-};
-//#endregion
-//#region ../ui-kit/src/runtime-config/quickPrompts.d.ts
-/**
- * 快捷指令可选图标名（0.12.0 分册 21）。
- * 用受控枚举而不是让宿主传组件：SDK 的图标集不进公开契约，
- * 换实现（lucide → 别的）时宿主代码不用动。
- *
- * 0.13.0 分册 17 FR-17.1：真值源从 `@webskill/chatbot` 迁到这里，
- * 让 console 的配置界面也能用同一份枚举；`@webskill/chatbot` 原样 re-export，
- * 公开面逐字不变。
- * @experimental
- */
-type QuickPromptIconName = 'chart' | 'document' | 'report' | 'search' | 'list' | 'bug' | 'test' | 'metric' | 'compare' | 'page' | 'run' | 'warn' | 'sparkles' | 'settings';
-/**
- * 带图标的快捷指令（0.12.0 分册 21）。
- * @experimental
- */
-interface QuickPrompt {
-  /**
-   * 点击后发出的文本，同时作为按钮可见文案。
-   * 0.13.0 分册 21 FR-21.1：改为按语种取值，可只填部分语种。
-   */
-  text: LocalizedText;
-  /** 缺省或取值不在枚举内时按无图标渲染 */
-  icon?: QuickPromptIconName;
-}
-/**
- * `RuntimeConfig` 里持久化的快捷指令条目（0.13.0 分册 17）。
- * 比 `QuickPrompt` 多一个稳定 `id`：列表增删改需要它做定位，
- * 用 `text` 当 key 在「两条同文案」时会塌陷。`id` 不进任何发给模型的字符串。
- * @experimental
- */
-interface RuntimeQuickPrompt {
-  id: string;
-  text: LocalizedText;
-  icon?: QuickPromptIconName;
-}
-//#endregion
-//#region ../ui-kit/src/runtime-config/types.d.ts
-/**
- * 运行环境配置模型（P2）：console Configure Tab 编辑、chatbot ChatEngine 装配应用，
- * 宿主经 RuntimeConfigStore 接线同一存储源（playground localStorage / 集成 OPFS 文件）。
- * 默认值严格对齐 SDK（AgentLoop/InteractionPolicy/executor 缺省）。
- */
-interface RuntimeLoopConfig {
-  maxTurns: number;
-  totalTimeoutMs: number;
-  toolTimeoutMs: number;
-  temperature?: number;
-  toolResultMaxBytes: number;
-  maxHistoryMessages: number;
-  /** `file` 分片的 base64 上限；超出即拒绝并说明，不截断（FR-23.4） */
-  maxDocumentBytes: number;
-  /** `document-text` 分片的字节上限；同样拒绝而不截断（FR-23.4） */
-  maxDocumentTextBytes: number;
-}
-interface RuntimeInteractionConfig {
-  missingParams: 'user' | 'llm';
-  confirmations: 'required' | 'auto-approve';
-  interactionTimeoutMs: number;
-  approvalScope: ApprovalScope$1;
-}
-type RuntimeRouterStrategy = 'progressive' | 'full-disclosure';
-/** 生命周期钩子执行策略（`HookRunnerOptions` 的可配置部分） */
-interface RuntimeHooksConfig {
-  timeoutMs: number;
-  /** true 时钩子异常终止 run；缺省隔离为 warning */
-  failOnHookError: boolean;
-}
-/** 浏览器宿主执行器档位；Node 宿主的 in-process/worker/process 由宿主侧扩展展示 */
-type RuntimeSandboxExecutor = 'auto' | 'blob-worker' | 'iframe-sandbox';
-/**
- * 用户自己声明的取数源（0.14.0 分册 19）。
- *
- * 存在的理由：从别的宿主导出的技能会声明本宿主没有的源 id，没有这一段就永远跑不起来。
- * 它不放宽任何闸门——`url` 照过 `sandbox.remoteUrl` 判定，取数照受 `capabilities.fetchData` 管，
- * 变的只是「谁来写这个地址」：宿主开发者，还是宿主的使用者。
- */
-interface RuntimeDataSourceEntry {
-  id: string;
-  /** 绝对 http(s) 地址 */
-  url: string;
-  description: string;
-}
-interface RuntimeSandboxConfig {
-  executor: RuntimeSandboxExecutor;
-  networkPolicy: NetworkPolicy$1;
-  capabilities: {
-    readReference: CapabilityMode;
-    /** 同时管 readAsset 与 readAssetBinary */
-    readAsset: CapabilityMode;
-    writeArtifact: CapabilityMode;
-    confirm: CapabilityMode;
-    /**
-     * 脚本按宿主声明的数据源取数（分册 16）。
-     * 与 `readAsset` **相反**，缺省 `false`：它会出网，缺省开等于每个技能默认拿到出站能力。
-     */
-    fetchData: CapabilityMode;
-  };
-  /**
-   * 单次取数结果的字节上限（分册 16）。超出即拒绝，**不截断**
-   * ——截断后的 JSON 解不出来，比拒绝更糟。结果回到脚本，不进模型上下文，
-   * 所以不受 `toolResultMaxBytes` 约束。
-   */
-  maxDataSourceBytes: number;
-  /**
-   * 用户声明的取数源（0.14.0 分册 19）；缺省空数组 = 只有宿主代码写死的那些。
-   * 与宿主源撞 id 时宿主的那条胜出——否则用户配置就能改写宿主的授权面。
-   */
-  dataSources: RuntimeDataSourceEntry[];
-  /**
-   * 出站 URL 准入策略（`RemoteUrlPolicy` 的可配置部分）：技能安装、MCP 端点连接
-   * 这类由宿主发起的取数都按它判定。两项都默认关，即 https-only 且拒绝内网/环回。
-   */
-  remoteUrl: RuntimeRemoteUrlConfig;
-  /** 浏览器沙箱的 TypeScript 支持；关闭时 `.ts` 脚本按 `TOOL_UNSUPPORTED` 拒绝 */
-  typescript: RuntimeTypeScriptConfig;
-  /**
-   * 读取用户下载的文件（0.14.0 分册 20）。缺省 `false`。
-   *
-   * **不放进 `capabilities`**：那张表的语义是三态 `CapabilityMode`（关 / 需批准 / 开），
-   * 而本能力的「需批准」是恒定的，放进去会凭空多出一个「开且不批准」的非法组合。
-   */
-  downloadedFiles: boolean;
-  /**
-   * 让技能脚本读用户本轮上传的文件（0.15.0 分册 17）。缺省 `false`。
-   *
-   * **不放进 `capabilities`**，理由同 `downloadedFiles`：本能力的「需批准」是恒定的。
-   * 关闭时脚本上下文里连那两个成员都不存在，而不是存在但总失败。
-   */
-  uploadFiles: boolean;
-  /**
-   * 单个上传文件交给脚本的字节上限（分册 17）。超出即拒，**不截断**
-   * ——截一半的 xlsx / 图片解不开，而脚本看不出它残缺。
-   */
-  maxUploadFileBytes: number;
-}
-/**
- * 只做类型擦除，不做类型检查。`esbuildUrl` 为绝对 http(s) 地址时按 `remoteUrl` 判定；
- * 同源相对路径与打包器 specifier 不属于出站请求，不参与判定。
- */
-interface RuntimeTypeScriptConfig {
-  enabled: boolean;
-  /** esbuild-wasm 的 JS 入口地址；enabled 时必填 */
-  esbuildUrl?: string;
-  /** esbuild.wasm 二进制地址；缺省由 esbuild 自行推导 */
-  wasmUrl?: string;
-}
-/** 与 `@webskill/core` 的 `RemoteUrlPolicy` 同形，但两个字段都是必填（配置需要确定值） */
-interface RuntimeRemoteUrlConfig {
-  allowHttp: boolean;
-  allowPrivateHosts: boolean;
-}
-/** `chrome-builtin` 走浏览器 Prompt API，无端点与密钥；其余三档是云端 HTTP 协议 */
-type RuntimeLlmProvider = 'openai-compatible' | 'anthropic' | 'google' | 'chrome-builtin';
-/**
- * 单个模型的能力声明（FR-11.4 / FR-14.2）。`image` 缺省视为 `false`：
- * 猜测支持会把图片发给纯文本模型，拿到的是 provider 的不可读报错。
- * `tools` 反过来，缺省视为 `true`：云端模型几乎都支持，默认关会把存量配置里
- * 没标能力的条目全部降级成纯对话。
- * @experimental
- */
-interface RuntimeLlmCapabilities {
-  image: boolean;
-  /** 是否支持原生工具调用；false 时 Agent 走纯对话路径 */
-  tools: boolean;
-}
-/**
- * 单个模型条目。`id` 稳定，会话记录与消息归属存的是它，用户改名不影响历史；
- * `label` 只用于展示——同一个 `model` 可能配了两个不同的 `baseUrl`（公司代理与直连），
- * 光看 `model` 区分不出来。
- */
-interface RuntimeLlmEntry {
-  id: string;
-  label: string;
-  provider: RuntimeLlmProvider;
-  baseUrl?: string;
-  apiKey?: string;
-  model: string;
-  requestTimeoutMs?: number;
-  capabilities?: RuntimeLlmCapabilities;
-  /**
-   * Anthropic extended thinking 预算（0.10.0 遗留项 #1）：仅 anthropic 条目有意义；
-   * 设置面是开关，开启写入 `DEFAULT_THINKING_BUDGET_TOKENS`。
-   * 0.10.0 #40.4：缺省（undefined）视为**开启**（按默认预算），显式关闭存 0。
-   * @experimental
-   */
-  thinkingBudgetTokens?: number;
-}
-/** 模型列表 + 默认项。`defaultId` 由 `mergeRuntimeConfigDefaults` 归一到真实存在的条目 */
-interface RuntimeLlmSelection {
-  entries: readonly RuntimeLlmEntry[];
-  defaultId?: string;
-}
-/**
- * Agent 能力开关（0.5.0）。默认值逐项经需求评审确定，不适用「新能力一律默认关」的通则。
- * `todo`：待办清单，默认**开启**——不引入新攻击面、提示词体积远小于生成式 UI catalog，
- * 且关闭时多步任务体验明显更差。
- * `skillGeneration`：技能自动生成，默认**关闭**——会把对话内容写进持久化的候选，
- * 属于新增攻击面（AC-G7 判据一）。
- * `generativeUi`：生成式 UI，默认**关闭**——catalog 描述约 14 KB 计入每次请求。
- * `uiPresets`：开放给模型的场景预设，默认全开——预设本体按需加载，
- * 只有名字与一行摘要计入请求；置空列表等于完全关闭预设。
- */
-interface RuntimeAgentCapabilitiesConfig {
-  todo: boolean;
-  skillGeneration: boolean;
-  generativeUi: boolean;
-  /** 串行委派（FR-11.8）：默认关。一句话可能展开成多个子 run，调用量对用户不可预期 */
-  delegation: boolean;
-  uiPresets: string[];
-}
-/**
- * 未签名技能的处置策略（与 core 的 `UnsignedPolicy` 同形，配置层独立命名）。
- * 默认 `'warn'` 由需求评审定下（FR-1.2）：`deny` 会让现存未签名技能立即不可用，
- * 且默认信任库为空时接受集为空；`allow` 等于策略不存在。
- */
-type UnsignedSkillPolicy = 'allow' | 'warn' | 'deny';
-interface RuntimeSecurityConfig {
-  unsignedSkills: UnsignedSkillPolicy;
-}
-/** 生成式 UI 的渲染器档位。ui-kit 不依赖 `@webskill/ui`，因此这里写字面量联合 @experimental */
-type RuntimeRendererId = 'native' | 'a2ui' | 'openui' | 'vercel';
-/**
- * 外观配置（0.6.0 FR-20.1）。0.5.x 之前外观由宿主自持并单独存一份，
- * 导致 chatbot 与 console 各看各的；纳入 `RuntimeConfig` 后两端共用同一份。
- * `dictationLang` 只对 chatbot 有意义（console 无语音输入），但同属外观段。
- * @experimental
- */
-interface RuntimeAppearanceConfig {
-  theme: 'light' | 'dark';
-  locale: Locale;
-  renderer: RuntimeRendererId;
-  dictationLang: string;
-}
-/**
- * 多模态输入配置（0.6.0 FR-11.3 / FR-11.6 / FR-12.3）。
- * `imageAttachments` 与 `pageImageCapture` 默认都关（AC-G5）：
- * 两者都会把图像随请求外发给模型提供方，属新增攻击面。
- * @experimental
- */
-/**
- * 文档投放面（0.11.0 分册 18）。
- *
- * **只有一个闸门字段**。CSP 白名单不在这里：它由 viewer 路由的**响应头**
- * 下发（FR-18.3 第 1 条），是宿主部署时调 `viewerCspHeader` 的入参；
- * 浏览器侧的运行时配置改不动已经发出去的响应头，携在这里只会是个不生效的假开关。
- */
-interface RuntimeDocumentSurfaceConfig {
-  /** 关着即没有这个投放面；开启还要求宿主额外提供一条 viewer 路由 */
-  enabled: boolean;
-}
-interface RuntimeMultimodalConfig {
-  imageAttachments: boolean;
-  /** 页面图像抓取总开关（FR-12.3）；关时感知只走纯文本路径 */
-  pageImageCapture: boolean;
-  /** 附件与取像共用 */
-  maxImageBytes: number;
-  /** 附件与取像共用 */
-  maxImagesPerMessage: number;
-  /**
-   * 页面取像时小于该面积（平方像素）的元素视作工具图标，不占名额（0.13.0 FR-20.4）。
-   * `0` 是合法值，意为关闭过滤；只作用于页面取像，不管用户上传的附件。
-   */
-  minImageArea: number;
-}
-/**
- * 用户画像配置（0.6.0 FR-19.6）。`enabled` 默认**关**（AC-G5）：
- * 开启后会把用户的提问与填写持久化到本地，属新增攻击面；
- * `encrypted` 默认**开**——它不新增采集，只决定已采集的数据怎么落盘，默认明文无正当理由。
- * chatbot 与 console 共用这一份。
- * @experimental
- */
-interface RuntimeUserProfileConfig {
-  enabled: boolean;
-  /** 画像注入系统提示的字节上限（FR-19.4） */
-  injectMaxBytes: number;
-  /** 行为记录容量上限，超出淘汰最旧（FR-19.2） */
-  recordLimit: number;
-  /** 本地存储加密（FR-19.5） */
-  encrypted: boolean;
-}
-/** @experimental */
-interface RuntimeSkillStateConfig {
-  /**
-   * 技能连续失败自动隔离阈值（0.10.0 UI-UX5 #48-12；#49-2 起默认 5），
-   * 与 governance `SkillStatePolicy` 的缺省对齐。读点在 console 的
-   * GovernanceFacade 装配处（`failureThreshold`），守卫本身不读配置。
-   */
-  quarantineThreshold: number;
-}
-/** @experimental */
-interface RuntimeConfig {
-  loop: RuntimeLoopConfig;
-  interaction: RuntimeInteractionConfig;
-  router: {
-    strategy: RuntimeRouterStrategy;
-  };
-  hooks: RuntimeHooksConfig;
-  streaming: boolean;
-  renderResult: boolean;
-  sandbox: RuntimeSandboxConfig;
-  llm: RuntimeLlmSelection;
-  agentCapabilities: RuntimeAgentCapabilitiesConfig;
-  security: RuntimeSecurityConfig;
-  appearance: RuntimeAppearanceConfig;
-  multimodal: RuntimeMultimodalConfig;
-  documentSurface: RuntimeDocumentSurfaceConfig;
-  userProfile: RuntimeUserProfileConfig;
-  skillState: RuntimeSkillStateConfig;
-  /**
-   * 快捷指令的**唯一权威**（0.13.0 分册 21 FR-21.5）。
-   * `ChatbotConfig.quickPrompts` 降级为一次性种子源，不再参与渲染判断。
-   */
-  quickPrompts: readonly RuntimeQuickPrompt[];
-  /**
-   * 宿主种子是否已注入过（FR-21.6）。
-   * 不得用 `quickPrompts.length === 0` 推断：「从未配置」与「用户删光了」都是空数组，
-   * 靠数组本身分不开——这正是 D-17-3 当年绕不过去的地方。
-   */
-  quickPromptsSeeded: boolean;
-  /** 空态与动态指令条最多展示多少条；超出的部分截断。取值 1..{@link MAX_QUICK_PROMPT_LIMIT} */
-  quickPromptLimit: number;
-  /** 被用户删掉的自动模型条目 id（FR-14.3）：删一次就不该再自己长回来 */
-  dismissedAutoEntries: readonly string[];
-}
-/** @experimental */
-interface RuntimeConfigStore {
-  /**
-   * Loads the runtime configuration. Implementations SHOULD return a complete
-   * RuntimeConfig; consumers wrap stores with `withRuntimeConfigDefaults` so partial
-   * or legacy data is normalized through `mergeRuntimeConfigDefaults` on the read
-   * path. Callers must not apply their own additional fallback merge.
-   */
-  load(): Promise<RuntimeConfig>;
-  save(config: RuntimeConfig): Promise<void>;
-  reset(): Promise<void>;
-  /**
-   * Subscribes to configuration changes; returns an unsubscribe function.
-   * Optional: stores without it degrade to the previous behaviour where hosts
-   * remount consumers after a save.
-   */
-  subscribe?(listener: () => void): () => void;
-}
-//#endregion
 //#region ../ui-kit/src/runtime-config/stores.d.ts
 /**
  * `RuntimeConfigStore` 的两个实现（0.6.0 FR-20.1）。0.5.x 之前 SDK 只有接口没有实现，
@@ -463,6 +76,71 @@ declare function createLocalStorageRuntimeConfigStore(options?: LocalStorageRunt
 /** 内存实现：测试、SSR、以及宿主明确不想持久化时使用。 @experimental */
 declare function createMemoryRuntimeConfigStore(initial?: Partial<RuntimeConfig>): RuntimeConfigStore;
 //#endregion
+//#region src/core/visionDelegate.d.ts
+/**
+ * 委派目标端点的可辨识标识；告知卡与审计都只用这三项（FR-17.6a / FR-17.7a）
+ * @experimental
+ */
+interface VisionDelegationEndpoint {
+  /** 模型条目 id */
+  readonly id: string;
+  /** 用户在 Console 里给这条起的名字 */
+  readonly label: string;
+  /** `baseUrl` 的主机名；内置档没有 baseUrl 时是 provider 名 */
+  readonly host: string;
+}
+/**
+ * 视觉委派的记忆端口（0.21.0 分册 17 · FR-17.9b）。形状照抄 `DownloadedFileConsent`：
+ * 存哪、记多久归宿主，SDK 只定接口。不注入即**每次都问**（FR-17.9c）。
+ * @experimental
+ */
+interface VisionDelegationConsent {
+  recall(endpoint: VisionDelegationEndpoint): boolean | Promise<boolean>;
+  remember(endpoint: VisionDelegationEndpoint): void | Promise<void>;
+  /**
+   * 复选框旁的文案。宿主不实现即用通用兜底串——
+   * SDK 无权替宿主宣称记住的是「这个端点」还是「所有端点」，写死会变成谎报授权范围。
+   */
+  describeScope?(endpoint: VisionDelegationEndpoint): string | undefined;
+}
+/** 装配参数；每一项都是「每次调用时重读」的取值函数，不是装配期快照 @experimental */
+interface ChatbotVisionDelegateOptions {
+  /** 每次调用时读的实时配置：选中模型与端点列表中途都可能变 */
+  config(): Promise<RuntimeConfig | undefined>;
+  /** 当前选中的模型条目 id（未选中即用默认项） */
+  selectedModelId(): string | undefined;
+  /** 选中条目的解析口径必须与主链路一致，否则「主模型看不看得了图」两处会打架 */
+  selectedEntry(config: RuntimeConfig | undefined): RuntimeLlmEntry | undefined;
+  /** 告知卡出口；引擎的 UI 桥天然满足 */
+  ui: ConsentUi;
+  consent?: VisionDelegationConsent;
+  /** 留痕出口。不注入仍然可以委派（FR-17.6b）：审计是宿主能力，不是同意条件 */
+  audit?: {
+    append(event: {
+      type: string;
+      target: string;
+      data?: Record<string, unknown>;
+    }): Promise<unknown>;
+  };
+  /** 按条目建客户端。缺省由调用方注入 `createLlmClient` */
+  createClient(entry: RuntimeLlmEntry): LlmClient;
+}
+/**
+ * 视觉委派的宿主侧实现（0.21.0 分册 17）。
+ *
+ * 三件事按顺序发生：挑端点（FR-17.2）→ 征得同意（FR-17.7）→ 一次调用认完所有图（FR-17.3a）。
+ * 在用户作出选择之前**不发出任何请求**：客户端是在同意之后才建的（FR-17.7b / AC-17.3）。
+ * @experimental
+ */
+declare class ChatbotVisionDelegate implements VisionDelegate {
+  #private;
+  constructor(options: ChatbotVisionDelegateOptions);
+  /** 新会话重新问（AC-17.4）。同意的记忆归宿主，这里不碰 */
+  forgetSessionDecision(): void;
+  applies(): Promise<boolean>;
+  describe(request: VisionDelegateRequest): Promise<VisionDelegateResult>;
+}
+//#endregion
 //#region src/core/hostAdapter.d.ts
 /**
  * 宿主装配口：chatbot 不感知环境（浏览器/Node），全部能力经此注入。
@@ -530,6 +208,27 @@ interface ChatbotHostAdapter {
    * PDF 仍然默认直传，能读的端点拿到的还是原件；不注入即没有回退能力。
    */
   pdfExtractor?: PdfTextExtractor;
+  /**
+   * 逐页读 PDF（0.21.0 分册 22）：拿页数、逐页文本、逐页图、把整页渲成图。
+   *
+   * 与 `pdfExtractor` 分开给，是因为它们回答的是两个问题：那个问「整份的文本是什么」，
+   * 这个问「第 N 页是什么」。三个 `*DocumentReader` 各自独立，缺哪个就哪种格式
+   * 明确报「本环境不支持」，不互相兜底。
+   * @experimental
+   */
+  pdfDocumentReader?: PdfDocumentReader;
+  /** docx → 块序列（`createDocxBlockReader`）；不注入即 `read_document` 读不了 Word @experimental */
+  docxDocumentReader?: DocxDocumentReader;
+  /** xlsx → 行流（`createXlsxBlockReader`）；不注入即 `read_document` 读不了 Excel @experimental */
+  xlsxDocumentReader?: XlsxDocumentReader;
+  /**
+   * 视觉委派的「不再询问」记忆端口（0.21.0 分册 17 · FR-17.9）。
+   *
+   * **不注入不等于关闭**：委派本身只要模型列表里有能看图的条目就成立，
+   * 只是每次都要弹告知卡（FR-17.9c）。本册刻意不加 Console 开关（FR-17.8）。
+   * @experimental
+   */
+  visionConsent?: VisionDelegationConsent;
   /** 文档读取留痕出口（FR-22.6）；分册 17 的 `upload.file.read` 也走这条 */
   documentAudit?: {
     append(event: {
@@ -551,6 +250,20 @@ interface ChatbotHostAdapter {
     /** 「不再询问」的记忆端口；不注入即每次都问 */
     consent?: DownloadedFileConsent;
   };
+  /**
+   * 读页内嵌的 WPS WebOffice 文档（0.21.0 分册 11~13）。
+   * **不注入即两个工具都不注册**——本册刻意不加设置开关（FR-13.8）：
+   * 能不能读取决于这一页有没有那样一份文档，那不是用户需要预先决定的事。
+   *
+   * 与 `downloads` 同一条装配规矩：宿主只交端口（枚举 / 读取 / 截屏），
+   * 授权卡出口与审计出口在引擎这一侧。
+   * @experimental
+   */
+  webOffice?: {
+    host: WebOfficeHost;
+    /** 「不再询问」的记忆端口；不注入即每次都问 */
+    consent?: WebOfficeConsent;
+  };
   /**
    * 文档投放面（0.15.0 分册 13）。宿主交出 viewer 页地址、投放前确认与审计出口，
    * 三件都在 `createDocumentSurfaceHost` 的选项里。
@@ -625,6 +338,12 @@ interface ChatEngineOptions {
   generativeUi?: boolean;
   /** 沙箱执行器替换点（测试注入 spy 断言构造参数；缺省 BrowserWorkerScriptExecutor） */
   executorFactory?: (deps: SandboxExecutorDeps) => ScriptExecutor;
+  /**
+   * 视觉委派用的客户端工厂（分册 17）。缺省 `createLlmClient`——
+   * 与主链路同一个工厂，被选中条目的 `baseUrl` / `apiKey` / `model` 原样生效（FR-17.2c）。
+   * 替换点存在只为让判据能断言「请求打到了哪个端点」（AC-17.8），不是配置项。
+   */
+  visionClientFactory?: (entry: RuntimeLlmEntry) => LlmClient;
   /**
    * 宿主声明的数据源取数入口（分册 16）。不注入即脚本上下文没有 `fetchData` 这个键。
    *
@@ -762,8 +481,14 @@ declare class ChatEngine {
   send(text: string, attachments?: readonly ChatAttachmentInput[]): Promise<void>;
   /** 附件落盘根目录（composer 附件适配器写入，send 时读回） */
   get attachmentsRoot(): string;
-  /** 取消进行中的 run（Composer Stop 按钮）；run 未找到/已结束返回 false */
-  cancel(runId: string): boolean;
+  /**
+   * 取消进行中的 run（Composer Stop 按钮）；run 未找到/已结束返回 false。
+   *
+   * 不传 runId 就取消引擎自己记着的那一个。UI 那边的 runId 是 `run-started` 事件携回去的，
+   * 而 `run-preparing` 到 `run-started` 之间是一整段无声区（队列/发现/路由）——
+   * 那段里面板已经是忙碌态、终止按钮已经在了，可 UI 手里还没 id，按下去是个空操作。
+   */
+  cancel(runId?: string): boolean;
   /**
    * 释放引擎：取消进行中的 run、退订全部事件、丢弃装配缓存。
    * 宿主重挂组件时用它收尾；只是换配置的话用 `reloadConfig()`，不要 dispose。
@@ -1055,7 +780,19 @@ interface ChatSessionListResult {
   skipped: readonly string[];
 }
 /** @stable */
-type ChatEvent = {
+type ChatEvent =
+/**
+ * 请求已受理，正在交给 runtime（分册 20 FR-20.2）。
+ *
+ * `run-started` 是从 runtime 的 `route` 生命周期事件派生的，而 route 排在
+ * 队列 / discover / listSkills / catalogFilter 之后。那一整段里任何一处慢或挂，
+ * 界面上都是同一副画面：什么都没有。本事件把那段变成一个显式状态。
+ */
+{
+  type: 'run-preparing';
+  sessionId: string;
+  queued: boolean;
+} | {
   type: 'run-started';
   runId: string;
 } | {
@@ -1112,6 +849,18 @@ type ChatEvent = {
   name: string;
   args?: string;
   errorCode?: string;
+} |
+/**
+ * 委派识图的逐张进度（分册 26 FR-26.9）。挂在 `source` 这个工具名上，
+ * 不带 callId——委派发生在工具**结果**回喂阶段，那时调用早已结束。
+ * @experimental
+ */
+{
+  type: 'vision-progress';
+  runId: string;
+  source: string;
+  done: number;
+  total: number;
 } | {
   type: 'run-completed';
   runId: string;
@@ -1120,6 +869,21 @@ type ChatEvent = {
   activeSkillNames: string[];
   /** 终止原因对应的稳定错误码（仅非正常结束时）：UI 据此分类提示，不再压平为 RUN_FAILED */
   code?: WebSkillErrorCode;
+  /**
+   * 本 run 结束时的上下文水位线（末轮输入 token，分册 20 FR-20.5）。
+   * 上游不回报 usage 时缺省——不填 0冒充「已知为零」。
+   */
+  contextTokens?: number;
+} |
+/**
+ * 历史被压缩（分册 20 FR-20.8）：只描述运行时历史的变化，会话存储里的原文不动。
+ * @experimental
+ */
+{
+  type: 'context-compacted';
+  sessionId: string;
+  removed: number;
+  kept: number;
 } | {
   type: 'todo-changed';
   runId: string;
@@ -1427,6 +1191,7 @@ declare const chatbotDictionary: {
     'tool.status.completed': string;
     'tool.status.failed': string;
     'tool.status.denied': string;
+    'tool.vision.progress': string;
     'tool.duration': string;
     'tool.args': string;
     'tool.denied.reason': string;
@@ -1473,6 +1238,7 @@ declare const chatbotDictionary: {
     'todo.status.inProgress': string;
     'todo.status.completed': string;
     'todo.delegatedTo': string;
+    'todo.dismiss': string;
     'interaction.ask.title': string;
     'interaction.confirm.title': string;
     'interaction.form.title': string;
@@ -1510,6 +1276,21 @@ declare const chatbotDictionary: {
     'interaction.downloadedFile.read': string;
     'interaction.downloadedFile.file': string;
     'interaction.downloadedFile.remember': string;
+    'interaction.webOffice.listTitle': string;
+    'interaction.webOffice.listBody': string;
+    'interaction.webOffice.readTitle': string;
+    'interaction.webOffice.readBody': string;
+    'interaction.webOffice.captureTitle': string;
+    'interaction.webOffice.captureBody': string;
+    'interaction.webOffice.claimedTypeNote': string;
+    'interaction.webOffice.rememberFallback': string;
+    'interaction.visionDelegation.title': string;
+    'interaction.visionDelegation.reason': string;
+    'interaction.visionDelegation.endpoint': string;
+    'interaction.visionDelegation.declineNote': string;
+    'interaction.visionDelegation.rememberFallback': string;
+    'interaction.visionDelegation.rememberSession': string;
+    'interaction.visionDelegation.body': string;
     'interaction.uploadFile.read': string;
     'interaction.uploadFile.file': string;
     'interaction.sandbox.readReference': string;
@@ -1586,6 +1367,12 @@ declare const chatbotDictionary: {
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
+    'attachment.storeFailed.title': string;
+    'attachment.storeFailed': string;
+    'attachment.pdfAsText': string;
+    'attachment.pdfRefused': string;
+    'attachment.pdfNoExtractor': string;
+    'attachment.textTooLong': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -1818,6 +1605,7 @@ declare const chatbotDictionary: {
     'tool.status.completed': string;
     'tool.status.failed': string;
     'tool.status.denied': string;
+    'tool.vision.progress': string;
     'tool.duration': string;
     'tool.args': string;
     'tool.denied.reason': string;
@@ -1864,6 +1652,7 @@ declare const chatbotDictionary: {
     'todo.status.inProgress': string;
     'todo.status.completed': string;
     'todo.delegatedTo': string;
+    'todo.dismiss': string;
     'interaction.ask.title': string;
     'interaction.confirm.title': string;
     'interaction.form.title': string;
@@ -1901,6 +1690,21 @@ declare const chatbotDictionary: {
     'interaction.downloadedFile.read': string;
     'interaction.downloadedFile.file': string;
     'interaction.downloadedFile.remember': string;
+    'interaction.webOffice.listTitle': string;
+    'interaction.webOffice.listBody': string;
+    'interaction.webOffice.readTitle': string;
+    'interaction.webOffice.readBody': string;
+    'interaction.webOffice.captureTitle': string;
+    'interaction.webOffice.captureBody': string;
+    'interaction.webOffice.claimedTypeNote': string;
+    'interaction.webOffice.rememberFallback': string;
+    'interaction.visionDelegation.title': string;
+    'interaction.visionDelegation.reason': string;
+    'interaction.visionDelegation.endpoint': string;
+    'interaction.visionDelegation.declineNote': string;
+    'interaction.visionDelegation.rememberFallback': string;
+    'interaction.visionDelegation.rememberSession': string;
+    'interaction.visionDelegation.body': string;
     'interaction.uploadFile.read': string;
     'interaction.uploadFile.file': string;
     'interaction.sandbox.readReference': string;
@@ -1977,6 +1781,12 @@ declare const chatbotDictionary: {
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
+    'attachment.storeFailed.title': string;
+    'attachment.storeFailed': string;
+    'attachment.pdfAsText': string;
+    'attachment.pdfRefused': string;
+    'attachment.pdfNoExtractor': string;
+    'attachment.textTooLong': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -2212,6 +2022,7 @@ declare const useT: () => TranslateFn<{
     'tool.status.completed': string;
     'tool.status.failed': string;
     'tool.status.denied': string;
+    'tool.vision.progress': string;
     'tool.duration': string;
     'tool.args': string;
     'tool.denied.reason': string;
@@ -2258,6 +2069,7 @@ declare const useT: () => TranslateFn<{
     'todo.status.inProgress': string;
     'todo.status.completed': string;
     'todo.delegatedTo': string;
+    'todo.dismiss': string;
     'interaction.ask.title': string;
     'interaction.confirm.title': string;
     'interaction.form.title': string;
@@ -2295,6 +2107,21 @@ declare const useT: () => TranslateFn<{
     'interaction.downloadedFile.read': string;
     'interaction.downloadedFile.file': string;
     'interaction.downloadedFile.remember': string;
+    'interaction.webOffice.listTitle': string;
+    'interaction.webOffice.listBody': string;
+    'interaction.webOffice.readTitle': string;
+    'interaction.webOffice.readBody': string;
+    'interaction.webOffice.captureTitle': string;
+    'interaction.webOffice.captureBody': string;
+    'interaction.webOffice.claimedTypeNote': string;
+    'interaction.webOffice.rememberFallback': string;
+    'interaction.visionDelegation.title': string;
+    'interaction.visionDelegation.reason': string;
+    'interaction.visionDelegation.endpoint': string;
+    'interaction.visionDelegation.declineNote': string;
+    'interaction.visionDelegation.rememberFallback': string;
+    'interaction.visionDelegation.rememberSession': string;
+    'interaction.visionDelegation.body': string;
     'interaction.uploadFile.read': string;
     'interaction.uploadFile.file': string;
     'interaction.sandbox.readReference': string;
@@ -2371,6 +2198,12 @@ declare const useT: () => TranslateFn<{
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
+    'attachment.storeFailed.title': string;
+    'attachment.storeFailed': string;
+    'attachment.pdfAsText': string;
+    'attachment.pdfRefused': string;
+    'attachment.pdfNoExtractor': string;
+    'attachment.textTooLong': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -2603,6 +2436,7 @@ declare const useT: () => TranslateFn<{
     'tool.status.completed': string;
     'tool.status.failed': string;
     'tool.status.denied': string;
+    'tool.vision.progress': string;
     'tool.duration': string;
     'tool.args': string;
     'tool.denied.reason': string;
@@ -2649,6 +2483,7 @@ declare const useT: () => TranslateFn<{
     'todo.status.inProgress': string;
     'todo.status.completed': string;
     'todo.delegatedTo': string;
+    'todo.dismiss': string;
     'interaction.ask.title': string;
     'interaction.confirm.title': string;
     'interaction.form.title': string;
@@ -2686,6 +2521,21 @@ declare const useT: () => TranslateFn<{
     'interaction.downloadedFile.read': string;
     'interaction.downloadedFile.file': string;
     'interaction.downloadedFile.remember': string;
+    'interaction.webOffice.listTitle': string;
+    'interaction.webOffice.listBody': string;
+    'interaction.webOffice.readTitle': string;
+    'interaction.webOffice.readBody': string;
+    'interaction.webOffice.captureTitle': string;
+    'interaction.webOffice.captureBody': string;
+    'interaction.webOffice.claimedTypeNote': string;
+    'interaction.webOffice.rememberFallback': string;
+    'interaction.visionDelegation.title': string;
+    'interaction.visionDelegation.reason': string;
+    'interaction.visionDelegation.endpoint': string;
+    'interaction.visionDelegation.declineNote': string;
+    'interaction.visionDelegation.rememberFallback': string;
+    'interaction.visionDelegation.rememberSession': string;
+    'interaction.visionDelegation.body': string;
     'interaction.uploadFile.read': string;
     'interaction.uploadFile.file': string;
     'interaction.sandbox.readReference': string;
@@ -2762,6 +2612,12 @@ declare const useT: () => TranslateFn<{
     'composer.addAttachment.imagesOff': string;
     'composer.addAttachment.modelNoImages': string;
     'attachment.imagesDropped': string;
+    'attachment.storeFailed.title': string;
+    'attachment.storeFailed': string;
+    'attachment.pdfAsText': string;
+    'attachment.pdfRefused': string;
+    'attachment.pdfNoExtractor': string;
+    'attachment.textTooLong': string;
     'composer.dictate': string;
     'composer.dictate.stop': string;
     'composer.dictate.recording': string;
@@ -3208,6 +3064,6 @@ declare function ErrorCard({ code, message, loopLimits, onOpenSettings, onDismis
  * Version of the published `@webskill/chatbot` package, injected at build time.
  * @stable
  */
-declare const CHATBOT_VERSION = "0.16.0";
+declare const CHATBOT_VERSION = "0.18.0";
 //#endregion
-export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };
+export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, ChatbotVisionDelegate, type ChatbotVisionDelegateOptions, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, type VisionDelegationConsent, type VisionDelegationEndpoint, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };