@webskill/sdk 0.5.0 → 0.7.0

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { N as FileStat, O as ArchiveLimits, P as FileSystemProvider, _t as VerifyResult, at as SkillManifest, b as UiBridge, c as InteractionResponse, dt as SkillsLockfile, ht as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as TrustedKeyStore, s as InteractionRequest, tt as SkillInstallSource, u as LlmCompleteInput, vt as WebSkillError, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
-import { Bt as WebSkillApi, Nt as ToolResult, Ut as bridgeError, W as NetworkPolicy, b as ExternalSkillProvider, d as ApprovalScope, f as BridgeCapabilities, h as BridgeResponse, jt as ToolDefinition, ln as parseBridgeRequest, m as BridgeRequest, vt as ScriptExecutionContext, x as ExternalToolSource, yt as ScriptExecutor } from "./index-vBz_FC9w.js";
-import { S as PerceptionScope, g as PagePerceptionReader, y as PerceivedNode } from "./index-D_7ZZjkl.js";
+import { A as ArchiveLimits, F as FileStat, I as FileSystemProvider, _ as MemoryStore, _t as UnsignedPolicy, bt as WebSkillError, c as InteractionResponse, ht as TrustedKeyStore, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillsLockfile, rt as SkillInstallSource, s as InteractionRequest, st as SkillManifest, u as LlmCompleteInput, x as UiBridge, y as RenderResultRequest, yt as VerifyResult } from "./types-CcxRLdJG-DCXyw1US.js";
+import { Et as ScriptExecutor, Fn as parseBridgeRequest, Kt as ToolResult, O as ExternalSkillProvider, Tt as ScriptExecutionContext, Wt as ToolDefinition, Y as NetworkPolicy, _ as BridgeCapabilities, b as BridgeResponse, cn as WebSkillApi, f as ApprovalScope, k as ExternalToolSource, pn as bridgeError, y as BridgeRequest } from "./index-DkbABR43.js";
+import { A as PagePerceptionReader, C as PageActionRequest, I as PerceptionCaptureOptions, P as PerceivedNode, R as PerceptionResult, _ as PageActionExecutor, w as PageActionScope, y as PageActionOutcome, z as PerceptionScope } from "./index-Ba3xFtfz.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -331,14 +331,44 @@ declare function checkDictationAvailability(): DictationAvailability;
  */
 declare function startDictation(options: DictationOptions): DictationSession;
 //#endregion
+//#region src/media/compressImage.d.ts
+/** 图片压缩结果；`originalBytes`/`compressedBytes` 供 UI 显示「3.2 MB → 1.8 MB」（FR-11.3 可见性） */
+interface CompressResult {
+  blob: Blob;
+  originalBytes: number;
+  compressedBytes: number;
+  /** 是否发生过缩放（仅降质未缩放时为 false） */
+  scaled: boolean;
+  /** 实际输出所用的 JPEG 质量；未经压缩管线时为 undefined */
+  quality?: number;
+}
+/**
+ * 把图片压到字节预算内（0.6.0 FR-11.3）。
+ * 先逐级降质，仍超限则按长边逐步缩放，最多 5 轮；仍超限抛 `ATTACHMENT_TOO_LARGE`。
+ *
+ * 编码一律交给平台（`OffscreenCanvas.convertToBlob`），不手写编码器（AGENTS.md §6）。
+ * 因此本函数只能在浏览器里用，落在 `@webskill/browser` 而不是 core/runtime（AC-G6）。
+ */
+declare function compressImageToBudget(file: Blob, maxBytes: number): Promise<CompressResult>;
+//#endregion
 //#region src/dom/perception.d.ts
 interface DomPerceptionReaderOptions {
   /** 选择器求值的根；缺省 `globalThis.document` */
   document?: Document;
+  /**
+   * 可操作范围（需求 23）。缺省即**不发任何句柄**，感知结果与 0.6.0 逐字相同。
+   * 它与感知范围分开声明：可读不等于可操作（FR-23.1）。
+   */
+  actionScope?: PageActionScope;
 }
-/** DOM 遍历是同步的；比 `PagePerceptionReader` 窄，调用方无需 await @experimental */
+/** DOM 遍历是同步的；不取像时比 `PagePerceptionReader` 窄，调用方无需 await @experimental */
 interface DomPerceptionReader extends PagePerceptionReader {
   read(scope: PerceptionScope): readonly PerceivedNode[];
+  read(scope: PerceptionScope, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
+  /** 把句柄换回元素；未知或已过期的句柄返回 undefined。供执行器使用，不自建第二张表 */
+  resolve(ref: string): Element | undefined;
+  /** 元素当前是否仍在可操作范围内（执行前的第二道闸门，AC-23.3） */
+  inActionScope(element: Element): boolean;
 }
 /**
  * DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
@@ -350,6 +380,63 @@ interface DomPerceptionReader extends PagePerceptionReader {
  */
 declare function createDomPerceptionReader(options?: DomPerceptionReaderOptions): DomPerceptionReader;
 //#endregion
+//#region src/dom/pageAction.d.ts
+/**
+ * DOM 页面操作执行器（需求 23 FR-23.4）。
+ *
+ * 句柄表由 reader 持有——执行器**不自建第二张表**，否则「单次有效」会有两套过期时机。
+ */
+interface DomPageActionOptions {
+  /** 发放句柄的那个 reader；`resolve` / `inActionScope` 都从它取 */
+  reader: DomPerceptionReader;
+}
+/** DOM 操作是同步的；比 `PageActionExecutor` 窄，调用方无需 await @experimental */
+interface DomPageActionExecutor extends PageActionExecutor {
+  execute(request: PageActionRequest): PageActionOutcome;
+}
+/** @experimental */
+declare function createDomPageActionExecutor(options: DomPageActionOptions): DomPageActionExecutor;
+//#endregion
+//#region src/dom/imageCapture.d.ts
+/**
+ * 取像级别（0.6.0 FR-12.1）。裁决 D-3 已取消 L3 栅格化，只剩两级。
+ * @experimental
+ */
+type CaptureLevel = 'src' | 'canvas';
+/** @experimental */
+interface CapturedImage {
+  id: string;
+  mimeType: string;
+  /** base64，不含 `data:` 前缀 */
+  data: string;
+  level: CaptureLevel;
+  originalBytes: number;
+  /** 压缩后字节数；未压缩时与 `originalBytes` 相同 */
+  bytes: number;
+}
+/** @experimental */
+interface CaptureFailure {
+  id: string;
+  /** 必须说明是哪一级、为什么；只写 "image unavailable" 不足以让用户判断该怎么办 */
+  reason: string;
+  triedLevels: readonly CaptureLevel[];
+}
+/** @experimental */
+declare function isCaptureFailure(result: CapturedImage | CaptureFailure): result is CaptureFailure;
+/** 只有这三种标签能取像；其余元素连取像入口都不进（FR-12.1，由 T-02-15 守门） @experimental */
+declare function isCapturableElement(element: Element): boolean;
+/**
+ * 取一个元素的图像（0.6.0 FR-12.1）。
+ *
+ * 按元素类型分派，不做无意义的尝试：`<img>` 只走 L1，`<canvas>` / `<svg>` 只走 L2，
+ * 两者互不兜底。失败返回 `CaptureFailure` 而不是抛错——一张图抓不到不该让整次感知失败。
+ * @experimental
+ */
+declare function captureElementImage(element: Element, options: {
+  id: string;
+  maxBytes: number;
+}): Promise<CapturedImage | CaptureFailure>;
+//#endregion
 //#region src/host/protocol.d.ts
 /** 主线程 → Worker 的 LLM 配置；mockResponses 供 E2E/测试注入确定性 Mock */
 interface LlmClientConfig {
@@ -521,4 +608,39 @@ declare class WorkerUiBridge implements UiBridge {
   onTextDelta(runId: string, delta: string): Promise<void>;
 }
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type ConfiguredLlmClient, type DictationAvailability, type DictationOptions, type DictationSession, type DomPerceptionReader, type DomPerceptionReaderOptions, IframeWorkerLike, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, OpfsProvider, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, checkDictationAvailability, createDomPerceptionReader, createIframeWorker, createLlmClient, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+//#region src/memory/encryptedMemoryStore.d.ts
+/**
+ * 某条已读出的记忆值是否是密文信封。观测方（如 console）据此决定要不要去取密钥：
+ * 加密关着的时候不该为了读一条明文而凭空建出一把密钥。
+ * @experimental
+ */
+declare function isEncryptedMemoryValue(value: unknown): boolean;
+/**
+ * 用 AES-GCM 包装一个 MemoryStore：值加密后再交给 `inner`，读取时解密。
+ * 密钥不可用（未解锁 / 无 Web Crypto）时**拒绝读写并抛结构化错误**，
+ * 不静默降级成明文——那会让「已加密」的承诺失效而用户无从察觉。
+ *
+ * `scopes` 限定加密范围。默认全加密；宿主通常只加密存放个人数据的
+ * `user:` 作用域，把运行观测（会话参数历史、技能统计）留作明文供 console 读取。
+ * @experimental
+ */
+declare function createEncryptedMemoryStore(inner: MemoryStore, key: CryptoKey | undefined, options?: {
+  scopes?: (scope: string) => boolean;
+}): MemoryStore;
+/**
+ * 生成一把不可导出的 AES-GCM 256 密钥（FR-19.5）。不可导出意味着页面脚本
+ * 拿不到原始字节，只能通过 Web Crypto 使用它；宿主负责持久化这个句柄（如 IndexedDB）。
+ * @experimental
+ */
+declare function generateMemoryEncryptionKey(): Promise<CryptoKey>;
+/**
+ * 取（必要时生成）本地数据加密密钥并持久化在 IndexedDB（FR-19.5）。
+ * 存的是 `CryptoKey` 句柄本身而不是密钥字节：结构化克隆能存它，
+ * 而它是 non-extractable 的，页面脚本与扩展都读不出原始字节。
+ * @experimental
+ */
+declare function openMemoryEncryptionKey(name?: string): Promise<CryptoKey>;
+/** 删除本地数据加密密钥；清除画像与记录时一并调用，避免留下解不开的旧密文 @experimental */
+declare function deleteMemoryEncryptionKey(name?: string): Promise<void>;
+//#endregion
+export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, type DictationAvailability, type DictationOptions, type DictationSession, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, IframeWorkerLike, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, OpfsProvider, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };