@webskill/sdk 0.4.0 → 0.6.0

package/dist/browser.d.ts

@@ -1,5 +1,6 @@
-import { D as ArchiveLimits, M as FileStat, N as FileSystemProvider, a as InteractionPolicy, c as LlmClient, et as SkillInstallSource, f as LlmResponse, gt as VerifyResult, it as SkillManifest, o as InteractionRequest, p as LlmStreamEvent, s as InteractionResponse, ut as SkillsLockfile, v as RenderResultRequest, y as UiBridge } from "./types-7Wcg--Vh-1YlQ4jF9.js";
-import { Dt as ToolDefinition, It as WebSkillApi, V as NetworkPolicy, b as ExternalSkillProvider, d as ApprovalScope, f as BridgeCapabilities, gt as ScriptExecutor, h as BridgeResponse, ht as ScriptExecutionContext, kt as ToolResult, m as BridgeRequest, tn as parseBridgeRequest, x as ExternalToolSource, zt as bridgeError } from "./index-DLfR2Y6I.js";
+import { N as FileStat, O as ArchiveLimits, P as FileSystemProvider, _ as MemoryStore, _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-4pg-qp_I-Gq63X8Oa.js";
+import { Ct as ScriptExecutionContext, D as ExternalSkillProvider, J as NetworkPolicy, Mn as parseBridgeRequest, O as ExternalToolSource, Ut as ToolResult, Vt as ToolDefinition, _ as BridgeCapabilities, an as WebSkillApi, b as BridgeResponse, f as ApprovalScope, un as bridgeError, wt as ScriptExecutor, y as BridgeRequest } from "./index-C-KFAZoF.js";
+import { C as PerceptionCaptureOptions, E as PerceptionScope, T as PerceptionResult, _ as PagePerceptionReader, x as PerceivedNode } from "./index-BuTpBMzr.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -69,7 +70,7 @@ declare class TsTranspiler {
     options: TypeScriptSupportOptions;
     cacheDir?: string;
   });
-  /** 返回 JS 源码；转译失败 → TOOL_EXECUTION_FAILED（带 esbuild 诊断） */
+  /** 返回 JS 源码；转译器不可用 → TS_TRANSPILER_UNAVAILABLE，语法错 → TS_TRANSPILE_FAILED */
   transpile(scriptPath: string, source: string): Promise<string>;
 }
 //#endregion
@@ -90,6 +91,23 @@ declare class BrowserSkillManager {
     archiveLimits?: ArchiveLimits;
     /** install/uninstall 成功后的变更回调（宿主接线缓存失效，如 WebSkillRuntime.invalidate） */
     onChanged?: () => void;
+    /**
+     * 供应链信任，与 Node 侧 `SkillManager` 同形状。未注入时仍然验签，
+     * 只是信任库为空：未签名包按 `unsigned` 处置，带不受信公钥的包装不上。
+     */
+    signature?: {
+      trustedKeys?: TrustedKeyStore;
+      /**
+       * 未签名包的处置，默认 `warn`。收成 `deny` 必须同时注入 `trustedKeys`：
+       * 空信任库 + deny 的接受集为空，任何包都装不上。
+       */
+      unsigned?: UnsignedPolicy;
+    };
+    /** 安装期告警（当前仅未签名放行）；宿主接线日志/UI */
+    onWarning?: (warning: {
+      skill: string;
+      message: string;
+    }) => void;
   });
   install(source: SkillInstallSource, options?: {
     expectedSha256?: string;
@@ -217,6 +235,182 @@ declare function installWebSkillNavigator(config: {
   };
 }): WebSkillApi;
 //#endregion
+//#region src/llm/chromeBuiltinClient.d.ts
+/**
+ * Chrome 内置模型（Prompt API）的可用性。`reason` 直接进 UI 文案——
+ * FR-4.7 要求「选之前就知道为什么不能选」，所以不可用必须带具体原因。
+ */
+type ChromeBuiltinAvailability = {
+  available: true;
+} | {
+  available: false;
+  reason: 'api-missing' | 'model-not-ready' | 'unsupported-browser';
+};
+/**
+ * 进入模型配置界面时调用（FR-4.7）：不可用时给出具体原因，禁止「选了之后才失败」。
+ * 模型还在下载也算不可用——这一轮对话等不到它。
+ */
+declare function probeChromeBuiltinAvailability(): Promise<ChromeBuiltinAvailability>;
+/**
+ * 浏览器内置模型客户端（Prompt API）。**不支持工具调用**——`input.tools` 被忽略，
+ * 模型只会产出文本，因此技能里的脚本步骤在这一档跑不起来（FR-4.8 要求 UI 标注该限制）。
+ * @experimental
+ */
+declare class ChromeBuiltinLlmClient implements LlmClient {
+  #private;
+  constructor(options?: {
+    temperature?: number;
+  });
+  complete(input: LlmCompleteInput): Promise<LlmResponse>;
+  stream(input: LlmCompleteInput): AsyncIterable<LlmStreamEvent>;
+  checkAvailability(): Promise<boolean>;
+}
+//#endregion
+//#region src/llm/createLlmClient.d.ts
+/**
+ * 构造客户端所需的最小配置。刻意声明成结构而不是 import `@webskill/ui-kit` 的
+ * `RuntimeLlmEntry`：ui-kit 是 React 层，运行时包不该反向依赖它。两者结构兼容。
+ */
+interface LlmEntryConfig {
+  provider: 'openai-compatible' | 'anthropic' | 'google' | 'chrome-builtin';
+  baseUrl?: string;
+  apiKey?: string;
+  model: string;
+  requestTimeoutMs?: number;
+}
+/** 四档客户端都能自查可达性，所以工厂的返回类型直接把探测能力算进契约 */
+type ConfiguredLlmClient = LlmClient & {
+  checkAvailability(): Promise<boolean>;
+};
+/**
+ * 配置 → `LlmClient`。收在 SDK 里是为了让下游只跟 `RuntimeConfigStore` 打交道，
+ * 不必自己维护「provider → client 类」的映射（设计 04 §5）。
+ */
+declare function createLlmClient(config: LlmEntryConfig): ConfiguredLlmClient;
+//#endregion
+//#region src/media/dictation.d.ts
+/**
+ * 语音识别的可用性（FR-7.2）。`reason` 直接进 UI 文案：
+ * 按钮必须在**渲染期**就知道自己能不能用，不允许「点了才失败」。
+ * @experimental
+ */
+type DictationAvailability = {
+  available: true;
+} | {
+  available: false;
+  reason: 'api-missing' | 'insecure-context';
+};
+/** 一次录音的句柄；`stop()` 后不再回调任何结果（FR-7.5） @experimental */
+interface DictationSession {
+  stop(): void;
+}
+/** @experimental */
+interface DictationOptions {
+  /** BCP-47 识别语言（FR-7.7），例如 `en-US` / `zh-CN` */
+  lang: string;
+  /** 尚未定稿的片段，用于录音中的实时回显（FR-7.4） */
+  onInterim(text: string): void;
+  /** 定稿片段；同一次录音可能触发多次 */
+  onFinal(text: string): void;
+  onError(error: WebSkillError): void;
+}
+/**
+ * 渲染期调用（FR-7.2）：不可用时按钮置灰并说明原因，禁止呈现为可用后才失败。
+ *
+ * 顺序是刻意的——构造器都不存在时谈安全上下文没有意义；
+ * 构造器在但站点是 http，识别一定会被浏览器拒绝，这条原因用户能自己解决。
+ * @experimental
+ */
+declare function checkDictationAvailability(): DictationAvailability;
+/**
+ * 开始一次语音识别（FR-7.1）。
+ *
+ * **只能由用户手势调用**（FR-7.3）。设计上的保证是它不进工具列表：
+ * agent 拿不到「开始录音」这个动作，因此不存在自主开麦的路径。
+ * @experimental
+ */
+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;
+}
+/** DOM 遍历是同步的；不取像时比 `PagePerceptionReader` 窄，调用方无需 await @experimental */
+interface DomPerceptionReader extends PagePerceptionReader {
+  read(scope: PerceptionScope): readonly PerceivedNode[];
+  read(scope: PerceptionScope, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
+}
+/**
+ * DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
+ * **不含任何 HTML 标记、class、data 属性或注释**（FR-10.4）。
+ *
+ * 判定顺序是先 `include` 取子树再 `exclude` 剪枝：`exclude` 命中的元素连同
+ * 其整棵后代一起消失，而不是只去掉那一个节点。
+ * @experimental
+ */
+declare function createDomPerceptionReader(options?: DomPerceptionReaderOptions): DomPerceptionReader;
+//#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 {
@@ -388,4 +582,39 @@ declare class WorkerUiBridge implements UiBridge {
   onTextDelta(runId: string, delta: string): Promise<void>;
 }
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, IframeWorkerLike, type LlmClientConfig, 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, createIframeWorker, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, 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 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, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };