@webskill/sdk 0.4.0 → 0.5.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, _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";
 //#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,121 @@ 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/dom/perception.d.ts
+interface DomPerceptionReaderOptions {
+  /** 选择器求值的根；缺省 `globalThis.document` */
+  document?: Document;
+}
+/** DOM 遍历是同步的；比 `PagePerceptionReader` 窄，调用方无需 await @experimental */
+interface DomPerceptionReader extends PagePerceptionReader {
+  read(scope: PerceptionScope): readonly PerceivedNode[];
+}
+/**
+ * DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
+ * **不含任何 HTML 标记、class、data 属性或注释**（FR-10.4）。
+ *
+ * 判定顺序是先 `include` 取子树再 `exclude` 剪枝：`exclude` 命中的元素连同
+ * 其整棵后代一起消失，而不是只去掉那一个节点。
+ * @experimental
+ */
+declare function createDomPerceptionReader(options?: DomPerceptionReaderOptions): DomPerceptionReader;
+//#endregion
 //#region src/host/protocol.d.ts
 /** 主线程 → Worker 的 LLM 配置；mockResponses 供 E2E/测试注入确定性 Mock */
 interface LlmClientConfig {
@@ -388,4 +521,4 @@ 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 };
+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 };