@webskill/sdk 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/agent.d.ts +3 -3
  2. package/dist/agent.js +466 -66
  3. package/dist/{approval-BnLLCOG0.js → approval-CBPnGPIm.js} +57 -4
  4. package/dist/browser.d.ts +214 -7
  5. package/dist/browser.js +487 -47
  6. package/dist/{eventTypes-Y07N8IAC.js → eventTypes-CwciaqCU.js} +23 -0
  7. package/dist/governance.d.ts +26 -3
  8. package/dist/governance.js +1 -1
  9. package/dist/{index-CQYo4tcT.d.ts → index-1sQZ4VBN.d.ts} +324 -16
  10. package/dist/{index-Oc3H89TJ.d.ts → index-BDyXe-a5.d.ts} +1 -1
  11. package/dist/{index-CU2md8R1.d.ts → index-CaLsVI-m.d.ts} +7 -2
  12. package/dist/index.d.ts +3 -3
  13. package/dist/index.js +3 -3
  14. package/dist/mcp.d.ts +2 -2
  15. package/dist/{miniChart-owdCdaw-.js → miniChart-lauNtZu8.js} +2 -7
  16. package/dist/node.d.ts +3 -3
  17. package/dist/node.js +14 -8
  18. package/dist/{openUiLibrary-CY_ADoe0.js → openUiLibrary-BJtCG5B1.js} +1 -1
  19. package/dist/{openUiSpecLang-DuOCdw9G.js → openUiSpecLang-B4QQ9Tfo.js} +4 -3
  20. package/dist/{skillVersionStore-B24Jjjry-C4zomhMZ.d.ts → skillVersionStore-B24Jjjry-v2CCU0Xo.d.ts} +1 -1
  21. package/dist/testing.d.ts +1 -1
  22. package/dist/{types-C3V6lAeO-BIf7UB2e.d.ts → types-Btpdd1y--BcxQ10Fa.d.ts} +20 -3
  23. package/dist/{types-TUydnxaj.js → types-BuacBov_.js} +14 -3
  24. package/dist/ui-react.d.ts +9 -3
  25. package/dist/ui-react.js +15 -4
  26. package/dist/ui-vue.d.ts +1 -1
  27. package/dist/ui-vue.js +2 -2
  28. package/dist/ui.d.ts +3 -3
  29. package/dist/ui.js +4 -4
  30. package/dist/{webSkillApi-DOOyz2G5.js → webSkillApi-Ce2OO5S5.js} +1 -1
  31. package/dist/{webskillLitCatalog-DSqVFQjK.js → webskillLitCatalog-BBkQjKuN.js} +2 -2
  32. package/package.json +1 -1
@@ -1051,6 +1051,7 @@ const DATA_SOURCE_PROVENANCE_NOTE = {
1051
1051
  };
1052
1052
  /** 分片是不是 PDF;mime 允许带参数与大小写差异,与 FR-11.1 的判定同口径 */
1053
1053
  const isPdfPart = (part) => part.type === "file" && part.mimeType.split(";")[0]?.trim().toLowerCase() === SUPPORTED_DOCUMENT_MIME.pdf;
1054
+ const isImagePart = (part) => part.type === "image";
1054
1055
  /**
1055
1056
  * LLM 客户端在 HTTP 失败时放进 `details` 的状态码(FR-22.2)。
1056
1057
  * 判不出来返回 undefined——网络层异常没有状态码,回退对它没有意义。
@@ -1227,6 +1228,7 @@ var AgentLoop = class {
1227
1228
  externalToolSources: /* @__PURE__ */ new Map(),
1228
1229
  withheldTools: /* @__PURE__ */ new Set(),
1229
1230
  pdfFallbackDone: false,
1231
+ imageFallbackDone: false,
1230
1232
  integrityVerdicts: /* @__PURE__ */ new Map(),
1231
1233
  toolTimeoutMs: this.#config.toolTimeoutMs,
1232
1234
  now,
@@ -1441,8 +1443,12 @@ var AgentLoop = class {
1441
1443
  turn--;
1442
1444
  continue;
1443
1445
  }
1446
+ if (this.#dropRejectedImages(state, e)) {
1447
+ turn--;
1448
+ continue;
1449
+ }
1444
1450
  const code = e instanceof WebSkillError && LLM_TURN_CODES.has(e.code) ? e.code : "LLM_REQUEST_FAILED";
1445
- const hint = state.pdfFallbackDone ? " The attached PDF was re-sent as extracted text after the endpoint rejected the original file, and that attempt failed as well." : messages.some((message) => message.content.some(isPdfPart)) ? " This turn attached a document; the selected model may not accept document input. Try another model, or link a Word or text file instead." : "";
1451
+ const hint = state.pdfFallbackDone ? " The attached PDF was re-sent as extracted text after the endpoint rejected the original file, and that attempt failed as well." : messages.some((message) => message.content.some(isPdfPart)) ? " This turn attached a document; the selected model may not accept document input. Try another model, or link a Word or text file instead." : state.imageFallbackDone ? " The images were dropped after the endpoint rejected them, and the retry failed as well." : "";
1446
1452
  return finish("failed", "llm-error", `${messageOf(e)}${hint}`, code);
1447
1453
  }
1448
1454
  if (response.thinking !== void 0 && response.thinking !== "") {
@@ -1678,6 +1684,7 @@ var AgentLoop = class {
1678
1684
  externalToolSources: /* @__PURE__ */ new Map(),
1679
1685
  withheldTools: /* @__PURE__ */ new Set(),
1680
1686
  pdfFallbackDone: false,
1687
+ imageFallbackDone: false,
1681
1688
  integrityVerdicts: /* @__PURE__ */ new Map(),
1682
1689
  toolTimeoutMs: snapshot.config.toolTimeoutMs,
1683
1690
  now,
@@ -2745,6 +2752,44 @@ var AgentLoop = class {
2745
2752
  });
2746
2753
  return converted > 0;
2747
2754
  }
2755
+ /**
2756
+ * 端点拒收本轮携带的图片后,把 image 分片换成一条说明让本轮可以重发(分册 15 FR-15.1)。
2757
+ * 返回 true 表示已改写、调用方应重试本轮。
2758
+ *
2759
+ * **不去解析端点指了哪一张**:`.messages[64].image[1]` 这类指针是提供方私有的,
2760
+ * 而重试预算只有一次——留一张没换的,重发还是被同一个端点拒。
2761
+ * 判据与 PDF 回退同口径:本轮真的带了图这个**事实**,不是猜错误文案。
2762
+ *
2763
+ * 图是感知结果的补充,结构化大纲仍在上下文里,去掉图这一轮仍然做得下去;
2764
+ * 而现状是一张解不开的图把整次扇出—汇聚打死。
2765
+ */
2766
+ #dropRejectedImages(state, cause) {
2767
+ if (state.imageFallbackDone) return false;
2768
+ const status = httpStatusOf(cause);
2769
+ if (status === void 0 || status < 400 || status >= 500) return false;
2770
+ if (!state.messages.some((message) => message.content.some(isImagePart))) return false;
2771
+ state.imageFallbackDone = true;
2772
+ let dropped = 0;
2773
+ for (const message of state.messages) {
2774
+ const kept = message.content.filter((part) => !isImagePart(part));
2775
+ const removed = message.content.length - kept.length;
2776
+ if (removed === 0) continue;
2777
+ dropped += removed;
2778
+ kept.push({
2779
+ type: "text",
2780
+ text: `${removed === 1 ? "An image" : `${removed} images`} attached here could not be read by this endpoint and ${removed === 1 ? "was" : "were"} removed. Work from the text description instead, and say so if the answer depends on what ${removed === 1 ? "the picture shows" : "the pictures show"}.`
2781
+ });
2782
+ message.content = kept;
2783
+ }
2784
+ state.trace.record("run.warning", {
2785
+ message: `The endpoint rejected this turn with HTTP ${status} while it carried ${dropped} image(s); they were dropped and the turn was retried. Original error: ${messageOf(cause)}`,
2786
+ data: {
2787
+ dropped,
2788
+ status
2789
+ }
2790
+ });
2791
+ return dropped > 0;
2792
+ }
2748
2793
  /** 单个 PDF 分片 → 文本;包装形态与 chatEngine 的附件标签同口径(FR-22.3 / FR-22.4) */
2749
2794
  async #pdfAsText(state, part, extract) {
2750
2795
  const name = part.name ?? "document.pdf";
@@ -3255,12 +3300,20 @@ var AgentLoop = class {
3255
3300
  }
3256
3301
  try {
3257
3302
  return await this.#interact(state, {
3258
- type: "confirm",
3303
+ type: "authorize",
3259
3304
  id: this.#nextInteractionId(state),
3305
+ capability: "readUploadFile",
3260
3306
  message: `Let skill "${skillName}" read the file you uploaded: ${file.name} (${file.contentType}, ${file.size} bytes)?`,
3261
- defaultValue: false
3307
+ details: {
3308
+ skill: skillName,
3309
+ file: {
3310
+ name: file.name,
3311
+ contentType: file.contentType,
3312
+ size: file.size
3313
+ }
3314
+ }
3262
3315
  }, {
3263
- kind: "confirm",
3316
+ kind: "authorize",
3264
3317
  uploadFile: file.id
3265
3318
  }) === true;
3266
3319
  } catch (e) {
package/dist/browser.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { Ct as SkillsLockfile, Et as TrustedKeyStore, H as FileStat, Mt as WebSkillError, N as ArchiveLimits, S as UiBridge, U as FileSystemProvider, _t as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as VerifyResult, kt as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore } from "./types-C3V6lAeO-BIf7UB2e.js";
2
- import { Kt as ScriptExecutionContext, M as DocumentSurfaceHost, R as ExternalSkillProvider, S as BridgeResponse, Un as WebSkillApi, Yn as bridgeError, ct as NetworkPolicy, gn as ToolDefinition, m as ApprovalScope, ot as LinkedDocumentReader, qt as ScriptExecutor, x as BridgeRequest, y as BridgeCapabilities, yn as ToolResult, yr as parseBridgeRequest, z as ExternalToolSource } from "./index-Oc3H89TJ.js";
3
- import { Ct as PerceptionCaptureOptions, Et as PerceptionResult, J as NestedFrameRef, Ot as PerceptionScopeInput, _t as PagePerceptionReader, ct as PageActionRequest, dt as PageActionTarget, ht as PagePerceptionPolicy, it as PageActionOutcome, nt as PageActionExecutor, ut as PageActionScopeInput, xt as PerceivedNode } from "./index-CQYo4tcT.js";
1
+ import { Ct as SkillsLockfile, Et as TrustedKeyStore, H as FileStat, Mt as WebSkillError, N as ArchiveLimits, S as UiBridge, U as FileSystemProvider, _t as SkillManifest, b as RenderResultRequest, c as InteractionResponse, jt as VerifyResult, kt as UnsignedPolicy, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillInstallSource, s as InteractionRequest, u as LlmCompleteInput, v as MemoryStore } from "./types-Btpdd1y--BcxQ10Fa.js";
2
+ import { Kt as ScriptExecutionContext, M as DocumentSurfaceHost, R as ExternalSkillProvider, S as BridgeResponse, Un as WebSkillApi, Yn as bridgeError, ct as NetworkPolicy, gn as ToolDefinition, m as ApprovalScope, ot as LinkedDocumentReader, qt as ScriptExecutor, x as BridgeRequest, y as BridgeCapabilities, yn as ToolResult, yr as parseBridgeRequest, z as ExternalToolSource } from "./index-BDyXe-a5.js";
3
+ import { $ as NestedFrameRef, Ct as PagePerceptionPolicy, It as PerceptionScopeInput, Pt as PerceptionResult, Tt as PagePerceptionReader, Xt as SubtreeRejection, ft as PageActionOutcome, gt as PageActionRequest, jt as PerceptionCaptureOptions, kt as PerceivedNode, ut as PageActionExecutor, vt as PageActionScopeInput, yt as PageActionTarget } from "./index-1sQZ4VBN.js";
4
4
  //#region ../browser/dist/index.d.ts
5
5
  //#region src/fs/featureDetection.d.ts
6
6
  /** 检测当前环境是否可用 OPFS(navigator.storage.getDirectory) */
@@ -382,6 +382,78 @@ declare function checkDictationAvailability(): DictationAvailability;
382
382
  */
383
383
  declare function startDictation(options: DictationOptions): DictationSession;
384
384
  //#endregion
385
+ //#region src/media/camera.d.ts
386
+ /**
387
+ * 摄像头的可用性(分册 14 FR-14.2),口径与 `checkDictationAvailability` 一致:
388
+ * 按钮必须在**渲染期**就知道自己能不能用,不允许「点了才失败」。
389
+ * @experimental
390
+ */
391
+ type CameraAvailability = {
392
+ available: true;
393
+ } | {
394
+ available: false;
395
+ reason: 'api-missing' | 'insecure-context';
396
+ };
397
+ /** @experimental */
398
+ interface CameraOptions {
399
+ /**
400
+ * 期望的最长边像素(FR-14.3)。只是 `ideal`:约束写成 `exact` 时,
401
+ * 任何拿不到该分辨率的设备会直接 `OverconstrainedError`,等于把相机关死。
402
+ */
403
+ maxDimension?: number;
404
+ /** 优先使用的摄像头;同样只作偏好,设备没有对应朝向时浏览器会给别的 */
405
+ facingMode?: 'user' | 'environment';
406
+ }
407
+ /** 一次取景会话的句柄;`close()` 后轨道全部停止,指示灯随之熄灭 @experimental */
408
+ interface CameraSession {
409
+ readonly stream: MediaStream;
410
+ /** 轨道实际生效的分辨率;浏览器给不到 ideal 时与请求值不同 */
411
+ resolution(): {
412
+ width: number;
413
+ height: number;
414
+ };
415
+ close(): void;
416
+ }
417
+ /** @experimental */
418
+ interface CapturePhotoOptions {
419
+ /** 输出文件名;缺省由调用时刻生成 */
420
+ fileName?: string;
421
+ /** 输出 MIME;缺省 `image/jpeg`(同分辨率下比 PNG 小一个量级) */
422
+ type?: string;
423
+ /** JPEG/WebP 质量,0~1;缺省 0.92 */
424
+ quality?: number;
425
+ }
426
+ /**
427
+ * 默认最长边:宿主要「最大分辨率」,给一个远超当前消费级摄像头的 ideal 让浏览器自己贴顶
428
+ * @experimental
429
+ */
430
+ declare const DEFAULT_CAMERA_MAX_DIMENSION = 5000;
431
+ /**
432
+ * 渲染期调用(FR-14.2):不可用时按钮置灰并说明原因。
433
+ *
434
+ * 顺序与语音一致——`getUserMedia` 压根不存在时谈安全上下文没有意义;
435
+ * API 在但站点是 http,取流一定会被浏览器拒绝,这条原因用户能自己解决。
436
+ * @experimental
437
+ */
438
+ declare function checkCameraAvailability(): CameraAvailability;
439
+ /**
440
+ * 打开摄像头取景(FR-14.1)。
441
+ *
442
+ * **只能由用户手势调用**(FR-14.4)。设计上的保证是它不进工具列表:
443
+ * agent 拿不到「打开摄像头」这个动作,因此不存在自主开摄像头的路径。
444
+ * @experimental
445
+ */
446
+ declare function openCamera(options?: CameraOptions): Promise<CameraSession>;
447
+ /**
448
+ * 把取景元素的**当前一帧**编码成文件(FR-14.5)。
449
+ *
450
+ * 尺寸取 `videoWidth`/`videoHeight`(轨道原生分辨率),不取 CSS 尺寸——
451
+ * 预览区被布局缩到 320px 宽,照着画出来的就是 320px 的照片。
452
+ * 编码交给平台的 canvas,不手写编码器(AGENTS.md §6)。
453
+ * @experimental
454
+ */
455
+ declare function capturePhoto(video: HTMLVideoElement, options?: CapturePhotoOptions): Promise<File>;
456
+ //#endregion
385
457
  //#region src/media/compressImage.d.ts
386
458
  /** 图片压缩结果;`originalBytes`/`compressedBytes` 供 UI 显示「3.2 MB → 1.8 MB」(FR-11.3 可见性) */
387
459
  interface CompressResult {
@@ -418,6 +490,12 @@ interface RoleHint {
418
490
  }
419
491
  //#endregion
420
492
  //#region src/dom/perception.d.ts
493
+ /**
494
+ * 句柄的用途(分册 14 §6.1)。`anchor` 只能做 `perceive_page` 的子树根,
495
+ * 拿去 `act_on_page` 一律被拒——否则放宽读的范围会顺带放宽写的范围。
496
+ * @experimental
497
+ */
498
+ type HandleKind = 'action' | 'anchor';
421
499
  interface DomPerceptionReaderOptions {
422
500
  /** 选择器求值的根;缺省 `globalThis.document` */
423
501
  document?: Document;
@@ -456,8 +534,12 @@ interface DomPerceptionReaderOptions {
456
534
  interface DomPerceptionReader extends PagePerceptionReader {
457
535
  read(scope: PerceptionScopeInput): readonly PerceivedNode[];
458
536
  read(scope: PerceptionScopeInput, capture: PerceptionCaptureOptions): Promise<PerceptionResult>;
537
+ /** 子树续读(分册 14):只能缩小范围,拒绝以返回值而非抛错表达 */
538
+ readSubtree(scope: PerceptionScopeInput, ref: string, capture?: PerceptionCaptureOptions): Promise<PerceptionResult | SubtreeRejection>;
459
539
  /** 把句柄换回元素;未知或已过期的句柄返回 undefined。供执行器使用,不自建第二张表 */
460
540
  resolve(ref: string): Element | undefined;
541
+ /** 句柄的用途;`anchor` 只能做子树根,执行器据此拒掉写动作(分册 14 §6.1) */
542
+ handleKindOf(ref: string): HandleKind | undefined;
461
543
  /** 句柄所属的帧;主文档目标返回 undefined(FR-24.6 的确认卡措辞与审计据此区分) */
462
544
  frameOf(ref: string): string | undefined;
463
545
  /** 操作前的活动模态快照;与操作后做差集即「本次新打开的模态」(FR-25.6) */
@@ -496,6 +578,11 @@ interface DomPageActionOptions {
496
578
  * 不注入即 `attach` 一律按「用户取消」处理 —— Agent 永远传不进本地路径。
497
579
  */
498
580
  pickFiles?: () => Promise<readonly File[] | undefined>;
581
+ /**
582
+ * `back` 作用的文档;缺省 `globalThis.document`。
583
+ * 其余动作不用它——它们的文档从元素自带的 `ownerDocument` 取,跨帧时才不会拿错。
584
+ */
585
+ document?: Document;
499
586
  }
500
587
  /**
501
588
  * @experimental
@@ -537,6 +624,11 @@ type PageAgentReply = {
537
624
  type: 'perceive-result';
538
625
  result: PerceptionResult;
539
626
  targets: readonly PageAgentTargetEntry[];
627
+ /**
628
+ * 这批句柄属于哪个文档(分册 11 / FR-11.1)。**可选**是有意的:
629
+ * 0.15.0 的页面侧处理器不会回它,此时 reader 退回单分片,行为逐字不变。
630
+ */
631
+ document?: PageDocumentIdentity;
540
632
  } | {
541
633
  type: 'execute-result';
542
634
  outcome: PageActionOutcome;
@@ -545,6 +637,18 @@ type PageAgentReply = {
545
637
  code: string;
546
638
  message: string;
547
639
  };
640
+ /**
641
+ * 文档标识(分册 11 / FR-11.1)。
642
+ *
643
+ * `key` 是**不透明**的:SDK 只拿它做相等比较与分片,不解析、不从中还原地址。
644
+ * `url` / `title` 只用于确认卡与留痕的可读性,不参与任何判定。
645
+ * @experimental
646
+ */
647
+ interface PageDocumentIdentity {
648
+ key: string;
649
+ url?: string;
650
+ title?: string;
651
+ }
548
652
  /**
549
653
  * 感知期随结果一并回传的句柄描述表(D-13-3);**不进模型上下文**。
550
654
  *
@@ -562,22 +666,119 @@ interface PageAgentTargetEntry {
562
666
  }
563
667
  //#endregion
564
668
  //#region src/remote/registry.d.ts
669
+ /**
670
+ * 句柄解析结果(0.16.0 分册 11 / FR-11.6)。
671
+ *
672
+ * 三种失败必须可区分:「不在当前这一页」「那一页已经变了」「从没见过」——
673
+ * 它们对模型的下一步要求完全不同,压成一个 `undefined` 就只能让它盲试。
674
+ * @experimental
675
+ */
676
+ type TargetResolution = {
677
+ status: 'ok';
678
+ target: PageActionTarget;
679
+ } |
680
+ /** 认识,但它属于另一个还活着的页面 */
681
+ {
682
+ status: 'unfocused';
683
+ } |
684
+ /** 认识过,但它那一页已经变了或被丢弃了 */
685
+ {
686
+ status: 'expired';
687
+ } |
688
+ /** 从没见过(含上一轮 run 的句柄) */
689
+ {
690
+ status: 'unknown';
691
+ };
565
692
  /**
566
693
  * 感知期写入、执行期读取的句柄描述表(分册 13 / FR-13.3)。
567
694
  *
568
695
  * 由**宿主创建并同时交给 reader 和 executor**——两者共享同一个实例是本册的装配前提。
569
696
  * 工厂单独导出就是为了让这件事在宿主代码里显式可见,
570
697
  * 而不是藏在某个工厂内部让人以为「自己会连上」。
698
+ *
699
+ * 0.16.0 起按**文档**分片(分册 11 / D-11-1(d)):分片键是一个不透明串,
700
+ * 「标签页」只是宿主给它的一种解释——本包不认识标签页,也不该认识(AC-G8)。
571
701
  * @experimental
572
702
  */
573
703
  interface RemoteTargetRegistry {
574
- /** 用新一批条目**整体替换**旧表 */
575
- replace(entries: readonly PageAgentTargetEntry[]): void;
704
+ /**
705
+ * 用新一批条目**整体替换**该文档分片的旧表,并把焦点移到它。
706
+ * `document` 缺省即单分片形态,行为与 0.15.0 逐字一致。
707
+ */
708
+ replace(entries: readonly PageAgentTargetEntry[], document?: PageDocumentIdentity): void;
709
+ /** 只查当前焦点分片。语义与 0.15.0 一致,既有调用点不必改 */
576
710
  get(ref: string): PageActionTarget | undefined;
711
+ /** `get` 的可诊断版本;`get` 保留是因为 `PageActionExecutor.describe` 的同步契约不能动 */
712
+ resolve(ref: string): TargetResolution;
713
+ /** 把后续的 `get` / `resolve` 指向该分片;分片不存在时焦点仍然移过去(其 `get` 全落空) */
714
+ focus(shard: string): void;
715
+ readonly focused: string | undefined;
716
+ /** 焦点分片的文档标识;用于留痕与确认卡文案,**不参与**任何判定 */
717
+ describePage(): PageDocumentIdentity | undefined;
718
+ /** 该分片失效(文档变了 / 标签页关了)。**不影响其它分片**(FR-11.3 / AC-11.5) */
719
+ drop(shard: string): void;
720
+ /** run 结束时清空(FR-11.4)。它只丢句柄,**不关闭任何标签页**——那是用户的浏览器 */
721
+ clear(): void;
722
+ /** 当前焦点分片的条目数;单分片下与 0.15.0 同值 */
577
723
  readonly size: number;
724
+ readonly shardCount: number;
578
725
  }
726
+ /**
727
+ * 分片数的防泄漏软上限(分册 11 / DV-2)。
728
+ *
729
+ * 它**不是** FR-11.5 那个容量闸门:那一条管的是「同时有几个**标签页**可操作」,
730
+ * 触顶硬拒绝,落在 `TabWorksetPolicy`。这里管的是同一个标签页里连续跳页攒下的历史分片,
731
+ * 那些本来就该失效,按最久未使用逐出即可,逐出不构成对模型的拒绝。
732
+ * 软上限必须宽于 `TAB_WORKSET_MAX_MAX`(分册 18),否则工作集里**还活着**的页
733
+ * 会因为别的页新发分片而被逐出;64 = 天花板 32 × 每页两代历史。
734
+ */
735
+ declare const SHARD_SOFT_LIMIT = 64;
736
+ /**
737
+ * 把解析结果翻译成给模型看的补充说明(分册 11 / FR-11.6);
738
+ * 接到 `PageActionPolicyOptions.diagnose` 上即可:
739
+ *
740
+ * ```ts
741
+ * diagnose: (ref) => explainResolution(targets.resolve(ref))
742
+ * ```
743
+ *
744
+ * `unknown` 返回 `undefined` 而不是自己拼一句:让 policy 落回它的缺省文案,
745
+ * 于是 AC-11.3 要求的「与 0.15.0 逐字相同」是**构造性**成立的,
746
+ * 而不是靠两个文件里的字符串抄得一样。
747
+ * @experimental
748
+ */
749
+ declare function explainResolution(resolution: TargetResolution): string | undefined;
579
750
  /** @experimental */
580
- declare function createRemoteTargetRegistry(): RemoteTargetRegistry;
751
+ interface RemoteTargetRegistryOptions {
752
+ /** 分片数软上限;缺省 `SHARD_SOFT_LIMIT`。小于 1 的值按 1 处理 */
753
+ maxShards?: number;
754
+ }
755
+ /** @experimental */
756
+ declare function createRemoteTargetRegistry(options?: RemoteTargetRegistryOptions): RemoteTargetRegistry;
757
+ //#endregion
758
+ //#region src/remote/documentIdentity.d.ts
759
+ /**
760
+ * 文档标识(0.16.0 分册 11 · FR-11.1)。
761
+ *
762
+ * 它有且只有两个消费者,且**必须是同一个函数**:
763
+ * ① 感知回复里的 `document.key`,决定这批句柄进哪个分片;
764
+ * ② `PageActionOutcome.navigated`,执行前后各取一次。
765
+ * 两处各写一套判定,就会出现「操作说导航了、分片说没换」的不一致(AC-11.4 / AC-13.4 验的就是这个)。
766
+ */
767
+ /** `Window` 的最小切面;取这个而不是 `Window` 是为了让本模块在无 DOM 的测试里也能跑 */
768
+ interface DocumentLocationView {
769
+ readonly location: {
770
+ readonly href: string;
771
+ };
772
+ }
773
+ /**
774
+ * `instance` + 当前地址。真导航换 `instance`,帧内路由(SPA)换 `href`,
775
+ * 两类都被这一个串覆盖——靠 origin 比对识别不出后者。
776
+ *
777
+ * `href` 含 hash 是有意的:纯 hash 跳转在很多站点上会换掉整块内容,
778
+ * 判成换文档是安全侧的选择(代价是多感知一次;漏判没有便宜的补救)。
779
+ * @experimental
780
+ */
781
+ declare function documentKey(view: DocumentLocationView | null | undefined): string | undefined;
581
782
  //#endregion
582
783
  //#region src/remote/reader.d.ts
583
784
  /** @experimental */
@@ -587,6 +788,12 @@ interface RemotePerceptionReaderOptions {
587
788
  targets: RemoteTargetRegistry;
588
789
  /** 单次感知超时毫秒;缺省 10000 */
589
790
  timeoutMs?: number;
791
+ /**
792
+ * 刚读到的是哪个文档(分册 11)。宿主据此维护「标签页 → 分片」的归属,
793
+ * 页面自己跳走时才知道该丢哪个分片。**SDK 不替宿主记这层映射**——
794
+ * 那需要标签页概念,而本包不认识标签页(AC-G8)。
795
+ */
796
+ onDocument?: (document: PageDocumentIdentity) => void;
590
797
  }
591
798
  /**
592
799
  * 跨上下文的页面感知(分册 13 / FR-13.2)。
@@ -1381,4 +1588,4 @@ declare function watchBlockedResources(host: ViewerBlockedHost, notice: ViewerBl
1381
1588
  /** 提示文案的单一来源;判据直接引用,不各写一份字面量 */
1382
1589
  declare function blockedMessage(origins: readonly string[]): string;
1383
1590
  //#endregion
1384
- export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, WORKER_BOOTSTRAP_SOURCE, type WindowLike, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };
1591
+ export { type BlockedEventLike, type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CameraAvailability, type CameraOptions, type CameraSession, type CaptureFailure, type CaptureLevel, type CapturePhotoOptions, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, DEFAULT_CAMERA_MAX_DIMENSION, DEFAULT_FRAME_BUDGET, DEFAULT_MAX_VIEWER_PAYLOAD_BYTES, DOCUMENT_SURFACE_AUDIT_EVENT, DOCX_UNEXTRACTED, type DictationAvailability, type DictationOptions, type DictationSession, type DocumentLocationView, type DocumentSurfaceAudit, type DocumentSurfaceOptions, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, type FetchLinkedDocumentOptions, type FrameBudget, type FrameDelivery, type FrameDispatcher, type FrameResolveContext, type FrameRouter, type FrameRouterOptions, HOST_PORT_MATRIX, type HandleKind, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, type IframeSandboxOptions, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, type OpenDocumentInput, OpfsProvider, type PageAgentHandler, type PageAgentHandlerOptions, type PageAgentReply, type PageAgentRequest, type PageAgentTargetEntry, type PageAgentTransport, type PageDocumentIdentity, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type RemotePageActionExecutorOptions, type RemotePerceptionReaderOptions, type RemoteTargetRegistry, type RemoteTargetRegistryOptions, type RoleHint, SANDBOX_PAGE_SCRIPT_SOURCE, SHARD_SOFT_LIMIT, type SandboxMode, type SerializedError, type TargetResolution, TsTranspiler, type TypeScriptSupportOptions, VIEWER_SANDBOX_TOKENS, type ViewerBlockedHost, type ViewerBlockedNotice, type ViewerBlockedResult, type ViewerCspOptions, type ViewerDocument, type ViewerShellHost, type ViewerShellMount, type ViewerShellResult, WORKER_BOOTSTRAP_SOURCE, type WindowLike, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, XLSX_UNEXTRACTED, blockedMessage, bridgeError, captureElementImage, capturePhoto, checkCameraAvailability, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDocumentSurfaceHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createFetchLinkedDocumentReader, createFrameRouter, createIframeWorker, createLlmClient, createPageAgentHandler, createRemotePageActionExecutor, createRemotePerceptionReader, createRemoteTargetRegistry, deleteMemoryEncryptionKey, documentKey, explainResolution, extractDocxText, extractXlsxText, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openCamera, openDocumentSurface, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startViewerShell, startWorkerRuntimeHost, viewerCspHeader, watchBlockedResources };