@webskill/sdk 0.20.0 → 0.22.0

package/dist/{index-DQ3-6GFu.d.ts → index-CjwdZQOS.d.ts}

@@ -1,5 +1,5 @@
-import { I as ChatAttachmentKind, Nt as WebSkillErrorCode, S as UiBridge, Z as RemoteUrlPolicy, a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest } from "./types-Btpdd1y--BcxQ10Fa.js";
-import { Kn as XlsxTextExtractor, P as DocxTextExtractor, bn as ToolStepReader, j as DataSourceInfo, z as ExternalToolSource } from "./index-BDyXe-a5.js";
+import { L as ChatAttachmentKind, Rt as WebSkillErrorCode, S as UiBridge, a as InteractionOrigin, c as InteractionResponse, nt as RemoteUrlPolicy, s as InteractionRequest, t as Artifact } from "./types-CpDRZ0rA-BM5FI9oN.js";
+import { B as ExternalToolSource, F as DocxTextExtractor, Fn as ToolStepReader, M as DataSourceInfo, kn as ToolCallContext, mt as PptxTextExtractor, pt as PdfTextExtractor, vr as XlsxTextExtractor, xn as SpreadsheetImageBytes } from "./index-YPd8ZSEa.js";
 //#region ../agent/dist/index.d.ts
 //#region src/todo/types.d.ts
 /** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
@@ -413,6 +413,12 @@ interface PerceivedNode {
    * 「页面变了不能点到别的东西」由执行前的实时校验承担，不由句柄寿命承担。
    */
   ref?: string;
+  /**
+   * 该节点的像素可读（0.22.0 FR-12.1）——`IMG` / `CANVAS` / `SVG` 三类。
+   * 只在 `ref` 存在时出现；模型据它判哪些句柄能交给 `capture_page_image`，
+   * 而不是靠猜元素类型先对 `<div>` 试一次。
+   */
+  capturable?: true;
   /**
    * 该节点来自哪个帧（FR-24.4），取值是帧路径的展示串（`frameLabel`）。
    * **主文档节点不带这个字段**——否则旧宿主的断言会凭空变化。
@@ -1119,15 +1125,19 @@ type PageActionScopeInput = PageActionScope | {
  */
 declare function toActionFrameScopes(scope: PageActionScopeInput): readonly ActionFrameScope[];
 /**
- * 本版的操作集（FR-25.1 / 0.16.0 FR-13.6 / 0.18.0 FR-10.1）。拖拽仍不在内（D64）；
+ * 本版的操作集（FR-25.1 / 0.16.0 FR-13.6 / 0.18.0 FR-10.1 / 0.22.0 FR-17.1）。
  * 导航只有 `back` 一个，且它**不接受地址**——可达面被浏览器历史封死（SC-1）。
  *
- * `select`/`set`/`attach`/`scroll` 与既有几个走**同一条** policy 路径，
+ * `drag` 只表达**起点与终点**，没有中途轨迹（0.22.0 FR-17.6 裁定，D64 就此撤销）：
+ * 轨迹是实现细节不是意图，能画任意路径等于架空 AC-23.2，而且滑块验证码要的正是轨迹——
+ * 表达不了轨迹，这个动作就天然做不了人机验证绕过。
+ *
+ * 这些动作与既有几个走**同一条** policy 路径，
  * 范围白名单、逐次确认、审计三条硬约束因此天然覆盖到它们——
  * 前提是新动作不绕过 policy 直调执行器（AC-25.4 守这一点）。
  * @experimental
  */
-declare const PAGE_ACTION_KINDS: readonly ["click", "fill", "submit", "select", "set", "attach", "scroll", "back"];
+declare const PAGE_ACTION_KINDS: readonly ["click", "fill", "submit", "select", "set", "attach", "scroll", "hover", "drag", "back"];
 type PageActionKind = (typeof PAGE_ACTION_KINDS)[number];
 /**
  * `back` 的目标占位（0.16.0 分册 13 §4.1）。
@@ -1145,8 +1155,10 @@ interface PageActionRequest {
   action: PageActionKind;
   /**
    * `fill` 填入的文本；`select` 要选中的选项可访问名；
-   * `set` 的目标态（`'true'` | `'false'`）；`scroll` 的方向（`'down'` | `'up'`）。
-   * `attach` 不用它——文件**始终由用户在确认卡里选**，Agent 传不进本地路径（FR-25.5）。
+   * `set` 的目标态（`'true'` | `'false'`）；`scroll` 的方向（`'down'` | `'up'`）；
+   * `drag` 的**终点句柄**（另一个 ref，FR-17.4）。
+   * `hover` 与 `attach` 不用它——后者的文件**始终由用户在确认卡里选**，
+   * Agent 传不进本地路径（FR-25.5）。
    */
   value?: string;
 }
@@ -1694,6 +1706,14 @@ interface DownloadedFilePolicyOptions {
   docxExtractor?: DocxTextExtractor;
   /** xlsx → 文本。同上 */
   xlsxExtractor?: XlsxTextExtractor;
+  pptxExtractor?: PptxTextExtractor;
+  /** 超阈值 PDF 的兜底抽取（AC-21.2）。同样必须与手动上传共用一个实现 */
+  pdfExtractor?: PdfTextExtractor;
+  /**
+   * PDF 原件直传的字节上限，量的是 base64 编码后的长度，与上传侧 `loop.maxDocumentBytes` 同源。
+   * 每次读取，设置改完立刻生效；缺省即**不设限**（保持 0.14.0 的直传行为）。
+   */
+  maxDocumentBytes?(): number;
   now?(): string;
 }
 /**
@@ -1712,6 +1732,18 @@ declare class DownloadedFilePolicy {
   get records(): readonly DownloadedFileRecord[];
   list(): Promise<readonly DownloadedFileListing[]>;
   read(id: string): Promise<DownloadedFileReadResult>;
+  /**
+   * 取原始字节，不做形态化（0.21.0 分册 22 · FR-22.4）。
+   *
+   * 授权卡、审计留痕与 `read()` 完全一致——逐单元读文档要的是字节本身，
+   * 但绝不能因此绕过策略：那等于给「读用户本机磁盘」开第二个没有授权的入口。
+   * @experimental
+   */
+  readBytes(id: string): Promise<{
+    entry: DownloadedFileEntry;
+    contentType: string;
+    bytes: Uint8Array;
+  }>;
 }
 //#endregion
 //#region src/downloads/toolSource.d.ts
@@ -1729,4 +1761,909 @@ interface DownloadedFileToolSourceOptions {
  */
 declare function createDownloadedFileToolSource(options: DownloadedFileToolSourceOptions): ExternalToolSource;
 //#endregion
-export { NestedFrameRef as $, TAB_WORKSET_MIN_MAX as $t, DelegationRequest as A, withDelegationOrigin as An, PerceptionAuditSink as At, DownloadedFileReader as B, SkillGenerationMessages as Bt, DataSourcePolicyOptions as C, createSkillGenerationToolSource as Cn, PagePerceptionPolicy as Ct, DelegationBudget as D, frameSteps as Dn, ParentBudget as Dt, DataSourceTransport as E, frameLabel as En, PagePerceptionToolSourceOptions as Et, DownloadedFileEntry as F, PerceptionScope as Ft, FrameScope as G, SkillGeneratorOptions as Gt, DownloadedFileToolSourceOptions as H, SkillGenerationPolicy as Ht, DownloadedFileListing as I, PerceptionScopeInput as It, HttpDataSourceOptions as J, SubAgentRunInput as Jt, GENERATE_SKILL_TOOL as K, SkillTraceEvidence as Kt, DownloadedFilePolicy as L, READ_DOWNLOADED_FILE_TOOL as Lt, DelegationToolSourceOptions as M, PerceptionPagingBudget as Mt, DownloadedFileAction as N, PerceptionRecord as Nt, DelegationOrchestrator as O, toActionFrameScopes as On, PerceivedImage as Ot, DownloadedFileConsent as P, PerceptionResult as Pt, MANAGE_TODO_TOOL as Q, TAB_WORKSET_MAX_MAX as Qt, DownloadedFilePolicyOptions as R, SKILL_GENERATION_SYSTEM_PROMPT as Rt, DataSourcePolicy as S, createPagePerceptionToolSource as Sn, PageAuditSink as St, DataSourceRecord as T, createTodoToolSource as Tn, PagePerceptionReader as Tt, FOCUS_PAGE_TAB_TOOL as U, SkillGenerationToolSourceOptions as Ut, DownloadedFileRecord as V, SkillGenerationOutcome as Vt, FrameNote as W, SkillGenerator as Wt, LIST_DOWNLOADED_FILES_TOOL as X, SubtreeRejection as Xt, ImageCaptureBudget as Y, SubAgentRunner as Yt, LIST_PAGE_TABS_TOOL as Z, TAB_WORKSET_DEFAULT_MAX as Zt, DataSourceCandidatePolicyOptions as _, clampWorksetMax as _n, PageActionScope as _t, ActionTabWindow as a, TabWorksetPort as an, PAGE_DOCUMENT_REF as at, DataSourceDef as b, createHttpDataSourceTransport as bn, PageActionToolSourceOptions as bt, DELEGATE_TASK_TOOL as c, TodoItem as cn, PERCEPTION_SYSTEM_PROMPT as ct, DOWNLOAD_WAIT_MAX_MS as d, TodoStatus as dn, PageActionKind as dt, TAB_WORKSET_SYSTEM_PROMPT as en, OpenedPageInfo as et, DOWNLOAD_WAIT_MIN_MS as f, TodoStore as fn, PageActionOutcome as ft, DataSourceCandidatePolicy as g, clampDownloadWaitMs as gn, PageActionRequest as gt, DataSourceCandidateAuditSink as h, WorksetTabView as hn, PageActionRecord as ht, ActionTabWatcher as i, TabWorksetPolicyOptions as in, PAGE_ACTION_TOOL as it, DelegationResult as j, PerceptionCaptureOptions as jt, DelegationOrchestratorOptions as k, toFrameScopes as kn, PerceivedNode as kt, DELEGATION_SYSTEM_PROMPT as l, TodoList as ln, PageActionConsent as lt, DataSourceCandidate as m, WorksetTab as mn, PageActionPolicyOptions as mt, ActionDownloadWindow as n, TabAdmission as nn, PAGE_ACTION_KINDS as nt, CLOSE_PAGE_TAB_TOOL as o, TabWorksetToolSourceOptions as on, PERCEIVE_PAGE_TOOL as ot, DataSourceAuditSink as p, TodoToolSourceOptions as pn, PageActionPolicy as pt, GeneratedSkillDraft as q, SkillTraceEvidenceStep as qt, ActionFrameScope as r, TabWorksetPolicy as rn, PAGE_ACTION_SYSTEM_PROMPT as rt, ConsentUi as s, TodoEvent as sn, PERCEPTION_PAGING_DEFAULTS as st, ActionDownloadWatcher as t, TODO_SYSTEM_PROMPT as tn, OpenedTabSignal as tt, DOWNLOAD_WAIT_DEFAULT_MS as u, TodoListener as un, PageActionExecutor as ut, DataSourceCandidateRecord as v, createDelegationToolSource as vn, PageActionScopeInput as vt, DataSourceProvenance as w, createTabWorksetToolSource as wn, PagePerceptionPolicyOptions as wt, DataSourceKind as x, createPageActionToolSource as xn, PageActionUi as xt, DataSourceCandidateStore as y, createDownloadedFileToolSource as yn, PageActionTarget as yt, DownloadedFileReadResult as z, SkillCandidateSink as zt };
+//#region src/document/budget.d.ts
+/**
+ * 单次 `read_document` 调用的批量预算（0.21.0 分册 22 · 设计 §6）。
+ *
+ * **整份文档没有上限**——只要还有单元没读，返回值就带 `next`（FR-22.3）。
+ * 这里限的只是「一次调用投多少」，那是请求体的物理约束，不是策略。
+ * @experimental
+ */
+interface DocumentReadBudget {
+  /**
+   * 一次调用最多带回多少字符的文本。与感知分页同口径（约 24K token），
+   * 显著小于 `loop.toolResultMaxBytes`（缺省 256 KB）——文本走 tool 消息，是受预算的分片。
+   */
+  textChars: number;
+  /**
+   * 一次调用最多投几张图。图不受 `toolResultMaxBytes` 管（只受每分片 `maxDocumentBytes`），
+   * 但一次投八张已经是几 MB 的请求体；八这个数也与视觉委派的超时口径相配
+   * （委派预算是 `toolTimeoutMs × 张数`，缺省 10 分钟 × 8）。
+   */
+  visionImages: number;
+}
+/** @experimental */
+declare const DOCUMENT_READ_BUDGET: DocumentReadBudget;
+//#endregion
+//#region src/document/types.d.ts
+/**
+ * 文档逐单元读取的四个端口（0.21.0 分册 22；0.22.0 分册 18 添上 pptx）。
+ *
+ * 与既有的 `PdfTextExtractor` / `DocxTextExtractor` / `XlsxTextExtractor` 并存，不替换：
+ * 那条路解决的是「这份文件太大，退而求其次给点文本」，
+ * 这条路解决的是「这份文件必须读完，而且读不出字的地方要看图」。
+ *
+ * 四个端口**各自独立**：只接了 PDF 的宿主照样能用，其余几支自动缺席（FR-22.16）。
+ */
+/** @experimental */
+type DocumentFormat = 'pdf' | 'docx' | 'xlsx' | 'pptx';
+/**
+ * 一次工具调用内打开的 PDF；生命周期不跨调用（续读靠自包含坐标，不存游标）
+ * @experimental
+ */
+interface PdfDocumentHandle {
+  readonly pageCount: number;
+  /** 该页文本层；没有文本层时返回空串，由可信度判定决定要不要转视觉 */
+  text(page: number): Promise<string>;
+  /** 该页图像对象占页面面积的比例。只给比例不给像素：15% 的判定不需要图像数据 */
+  images(page: number): Promise<readonly PdfPageImage[]>;
+  /** 整页渲染；`data` 是 base64，直接就是 image 分片要的形态 */
+  render(page: number): Promise<RenderedImage>;
+  close(): Promise<void>;
+}
+/** @experimental */
+interface PdfPageImage {
+  /** 占页面面积的比例，0~1 */
+  areaRatio: number;
+}
+/** @experimental */
+interface RenderedImage {
+  mimeType: string;
+  data: string;
+}
+/**
+ * PDF → 页（宿主注入 pdfjs）。不注入即 PDF 这一支不存在。
+ * @experimental
+ */
+interface PdfDocumentReader {
+  open(bytes: Uint8Array): Promise<PdfDocumentHandle>;
+}
+/**
+ * 文档拆出来的一块。图片块给的是**已经过阈值筛选**的图——
+ * 阈值判定要读 `wp:extent` / `xdr:twoCellAnchor` 这些格式细节，只能落在端口实现里。
+ * @experimental
+ */
+type DocumentBlock = {
+  kind: 'text';
+  text: string;
+} | {
+  kind: 'image';
+  mimeType: string;
+  data: string;
+} | {
+  kind: 'skipped';
+  reason: 'unsupported-format';
+  format: string;
+};
+/**
+ * docx → 块序列。docx **没有页**（分页是 Word 排版时算的，文件里没有），
+ * 所以给的是按文档真实顺序排好的块，坐标是块序号。
+ * @experimental
+ */
+interface DocxDocumentReader {
+  read(bytes: Uint8Array): Promise<DocxDocumentContent>;
+}
+/** @experimental */
+interface DocxDocumentContent {
+  blocks: readonly DocumentBlock[];
+}
+/**
+ * xlsx → 逐表的行序列。图按 `xdr:twoCellAnchor` 的锚点行号插进行流。
+ * @experimental
+ */
+interface XlsxDocumentReader {
+  read(bytes: Uint8Array): Promise<XlsxDocumentContent>;
+}
+/** @experimental */
+interface XlsxDocumentContent {
+  sheets: readonly XlsxSheetContent[];
+}
+/** @experimental */
+interface XlsxSheetContent {
+  name: string;
+  rows: readonly DocumentBlock[];
+}
+/**
+ * pptx → 逐页的块序列。幻灯片**真有页**（不像 docx 的分页是排版算出来的），
+ * 所以坐标是「第几页的第几块」。
+ *
+ * 给的是页上写了什么、插了哪几张图，**不是页面渲染图**：
+ * OOXML 包里没有渲染好的页面，浏览器里也没有 pptx 渲染器。要版式只能退到截屏。
+ * @experimental
+ */
+interface PptxDocumentReader {
+  read(bytes: Uint8Array): Promise<PptxDocumentContent>;
+}
+/** @experimental */
+interface PptxDocumentContent {
+  slides: readonly PptxSlideContent[];
+}
+/** @experimental */
+interface PptxSlideContent {
+  blocks: readonly DocumentBlock[];
+}
+/** 一份可读文档的字节及其来源标识 @experimental */
+interface DocumentFileBytes {
+  name: string;
+  bytes: Uint8Array;
+}
+/**
+ * 按标识取字节。装配方组合两个来源：当前 run 的附件、下载列表（经授权卡）。
+ * 找不到返回 `undefined`，由工具层归因，不静默当空文档。
+ * @experimental
+ */
+interface DocumentFileSource {
+  read(id: string): Promise<DocumentFileBytes | undefined>;
+}
+//#endregion
+//#region src/document/format.d.ts
+/**
+ * 格式以字节为准，文件名只作次要线索：改扩展名不该改变我们如何解析它。
+ * 认不出返回 `undefined`，由调用方归因。
+ * @experimental
+ */
+declare function sniffDocumentFormat(bytes: Uint8Array, name?: string): DocumentFormat | undefined;
+//#endregion
+//#region src/document/pdfQuality.d.ts
+/**
+ * 「这一页抽出来的是不是乱码」的判定（0.21.0 分册 22 · FR-22.2）。
+ *
+ * 判定必须是纯函数：它决定一页走文本还是走渲染，而渲染要烧一次多模态请求。
+ * 靠人眼看一遍不叫判据。
+ */
+/** 坏字符占可打印字符的比例超过它即判文本层不可信 @experimental */
+declare const PDF_GARBLED_RATIO = 0.2;
+/** @experimental */
+interface PdfTextQuality {
+  /** 参与判定的可打印字符数（不含空白） */
+  printable: number;
+  /** 其中的坏字符数 */
+  garbled: number;
+  /** 文本层是否可信；不可信意味着该页要转视觉 */
+  trustworthy: boolean;
+}
+/**
+ * 空白页一律判不可信：它要么是扫描页、要么什么都没有，
+ * 两种情况都该让模型自己看一眼，而不是把一页空气交上去。
+ * @experimental
+ */
+declare function measurePdfTextQuality(text: string): PdfTextQuality;
+/** `measurePdfTextQuality(text).trustworthy` 的简写 @experimental */
+declare function isPdfTextTrustworthy(text: string): boolean;
+//#endregion
+//#region src/document/deferral.d.ts
+/**
+ * 「这张图现在取不取」的唯一判据（0.21.0 分册 26 · FR-26.1）。
+ *
+ * 附件侧（`read_document`）与在线侧（`read_weboffice_document`）共用这一个函数，
+ * 而不是各写一遍 `if`：FR-26.4 要的是同口径，不是碰巧同结论。
+ * @experimental
+ */
+/** @experimental */
+type DocumentReadMode = 'auto' | 'vision' | 'images';
+/**
+ * 图在这一个单元里的地位。
+ *
+ * - `content`：该处文本读不出来（扫描页、纯图块），图**不可替代**，跳过等于这一段空白。
+ * - `illustration`：正文已经读得到，图是补充。
+ * @experimental
+ */
+type DocumentImageRole = 'content' | 'illustration';
+/** @experimental */
+declare function takesImage(mode: DocumentReadMode, role: DocumentImageRole): boolean;
+/** 本次没取、但回头取得到的图（进返回值的 `deferred`） @experimental */
+declare function defersImage(mode: DocumentReadMode, role: DocumentImageRole): boolean;
+/** 入参里的 `mode` 只认这三个字面量，其余一律当 `auto` @experimental */
+declare function asReadMode(raw: unknown): DocumentReadMode;
+//#endregion
+//#region src/document/toolSource.d.ts
+/** @experimental */
+declare const READ_DOCUMENT_TOOL = "read_document";
+/** 大图的门槛：低于它的是页眉 logo、印章、项目符号，投它们等于白烧一次多模态请求 @experimental */
+declare const PDF_LARGE_IMAGE_RATIO = 0.15;
+/** @experimental */
+interface DocumentToolSourceOptions {
+  files: DocumentFileSource;
+  pdf?: PdfDocumentReader;
+  docx?: DocxDocumentReader;
+  xlsx?: XlsxDocumentReader;
+  pptx?: PptxDocumentReader;
+  /** 每次调用重取，宿主改配置立刻生效 */
+  budget?: () => DocumentReadBudget;
+}
+/**
+ * 逐单元读文档，读不出字的地方出图（0.21.0 分册 22）。
+ *
+ * 四个端口一个都没接时 `listToolSpecs()` 返回空——模型连这个工具的存在都看不到，
+ * 而不是看得到再被拒（AC-22.2）。
+ * @experimental
+ */
+declare function createDocumentToolSource(options: DocumentToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/spreadsheet/toolSource.d.ts
+declare const EXPORT_SPREADSHEET_TOOL = "export_spreadsheet";
+interface SpreadsheetToolSourceOptions {
+  /**
+   * 落产物的出口。**不注入即整条通路不存在**：`listToolSpecs()` 返回空数组，
+   * 模型连这个工具的存在都看不到，而不是看得到再被拒。
+   *
+   * 带 `context` 是因为产物属于某一次 run：宿主要拿 `runId` 才能写到对的地方。
+   * `AgentLoop` 调外部工具时总是传它（`agentLoop.ts` 的 `source.call(…, { runId })`）。
+   */
+  writeArtifact?: (path: string, bytes: Uint8Array, mimeType: string, context?: ToolCallContext) => Promise<Artifact>;
+  /**
+   * 图片引用 → 字节。不注入时 `images` 整个字段不进入参 schema，提示词里也不提图——
+   * 与 `writeArtifact` 同一条口径：宿主给不了的能力，模型就不该看得到。
+   *
+   * 解析本身不在这一层：引用能指向本会话哪些东西是宿主的事，工具源知道了就多一份路径面。
+   */
+  resolveImage?: (ref: string, context?: ToolCallContext) => Promise<SpreadsheetImageBytes | undefined>;
+}
+/**
+ * 把表格导出接到既有工具协议上。
+ *
+ * 做成 `ExternalToolSource` 而不是 `AgentLoop` 的内置数组（DV-4）：本工具需要
+ * `argCaptureTrust` 与 `captureArgs` 两个钩子，内置数组里没有这两个概念。
+ * @experimental
+ */
+declare function createSpreadsheetToolSource(options: SpreadsheetToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/template/geometry.d.ts
+/**
+ * A1 地址与 OOXML 几何换算（0.22.0 分册 42 · 设计 43 §1.6）。
+ *
+ * 环境无关，`@webskill/agent` 里可直接单测——几何算错的后果是图溢出单元格，
+ * 而那只有人肉打开文件才看得见，所以这一层的覆盖要密。
+ */
+/** 1 px 的 EMU 数（96 DPI） */
+declare const EMU_PER_PIXEL = 9525;
+/** 1 磅的 EMU 数 */
+declare const EMU_PER_POINT = 12700;
+/** 1 twip 的 EMU 数 */
+declare const EMU_PER_TWIP = 635;
+/** 默认字体的最大数字宽度，Excel 列宽换算基准 */
+declare const MAX_DIGIT_WIDTH = 7;
+interface CellAddress {
+  /** 0 基 */
+  readonly column: number;
+  /** 0 基 */
+  readonly row: number;
+}
+/** @throws WebSkillError 语法不合法 */
+declare function parseCellAddress(address: string): CellAddress;
+declare function formatCellAddress({ column, row }: CellAddress): string;
+interface CellRange {
+  readonly start: CellAddress;
+  readonly end: CellAddress;
+}
+/** @throws WebSkillError 语法不合法 */
+declare function parseCellRange(range: string): CellRange;
+declare function isRangeTopLeft(range: CellRange, address: CellAddress): boolean;
+declare function rangeContains(range: CellRange, address: CellAddress): boolean;
+/** Excel 的列宽单位是字符数，换算成像素（设计 43 §1.6 实测 MDW=7） */
+declare function columnWidthToPixels(width: number): number;
+interface Size {
+  readonly width: number;
+  readonly height: number;
+}
+/**
+ * 等比缩放进框：宽高同时约束、**取两个比例里的小者**。
+ *
+ * FR-42.11 与 FR-42.19 是同一条口径——xlsx 的合并区和 docx 声明了 `trHeight` 的
+ * 表格行都这么算。框的某一边为 0（未声明高度）时那一边不参与约束。
+ */
+declare function fitWithin(natural: Size, box: Size): Size;
+/** PNG / JPEG 的像素尺寸。读文件头，不解码整张图。 */
+declare function readImageSize(bytes: Uint8Array): Size | undefined;
+//#endregion
+//#region src/template/types.d.ts
+/**
+ * 模板改写的端口契约（0.22.0 分册 42 · 设计 43 §2）。
+ *
+ * 真正拆装 OOXML 的实现在 `@webskill/browser`（要 `DOMParser`），
+ * 这里只声明形状——`@webskill/core` / `@webskill/agent` 保持环境无关。
+ * @experimental
+ */
+/** @experimental */
+interface TemplateCellSkeleton {
+  readonly address: string;
+  readonly text: string;
+  /** 在则这格由模板算出，不得填 */
+  readonly formula?: string;
+}
+/** @experimental */
+interface TemplateSheetSkeleton {
+  readonly name: string;
+  readonly range: string;
+  readonly cells: readonly TemplateCellSkeleton[];
+  readonly merges: readonly string[];
+  readonly columnWidths: readonly number[];
+}
+/** @experimental */
+interface XlsxTemplateSkeleton {
+  readonly sheets: readonly TemplateSheetSkeleton[];
+}
+/** @experimental */
+interface TemplateParagraphSkeleton {
+  readonly index: number;
+  readonly text: string;
+}
+/** @experimental */
+interface TemplateTableCellSkeleton {
+  readonly table: number;
+  readonly row: number;
+  readonly column: number;
+  readonly text: string;
+  readonly gridSpan?: number;
+  readonly vMerge?: string;
+}
+/** @experimental */
+interface DocxTemplateSkeleton {
+  readonly paragraphs: readonly TemplateParagraphSkeleton[];
+  readonly cells: readonly TemplateTableCellSkeleton[];
+}
+/** @experimental */
+interface TemplateImageBytes {
+  readonly bytes: Uint8Array;
+  readonly extension: string;
+  readonly contentType: string;
+}
+/** @experimental */
+interface XlsxTemplateFillSpec {
+  readonly rows?: readonly {
+    sheet?: string;
+    at: number;
+    count: number;
+    copyStyleFrom?: number;
+  }[];
+  readonly cells?: readonly {
+    sheet?: string;
+    address: string;
+    value: string;
+  }[];
+  readonly images?: readonly ({
+    sheet?: string;
+    address: string;
+  } & TemplateImageBytes)[];
+}
+/** @experimental */
+interface DocxTemplateFillSpec {
+  readonly texts?: readonly {
+    paragraph?: number;
+    table?: number;
+    row?: number;
+    column?: number;
+    value: string;
+  }[];
+  readonly images?: readonly ({
+    paragraph?: number;
+    table?: number;
+    row?: number;
+    column?: number;
+  } & TemplateImageBytes)[];
+}
+/** @experimental */
+interface XlsxTemplateEngine {
+  read(bytes: Uint8Array): Promise<XlsxTemplateSkeleton>;
+  fill(bytes: Uint8Array, spec: XlsxTemplateFillSpec): Promise<Uint8Array>;
+}
+/** @experimental */
+interface DocxTemplateEngine {
+  read(bytes: Uint8Array): Promise<DocxTemplateSkeleton>;
+  fill(bytes: Uint8Array, spec: DocxTemplateFillSpec): Promise<Uint8Array>;
+}
+/** 模板字节的来源，与 `read_document` 同一个出口 @experimental */
+interface TemplateFileSource {
+  read(id: string, context?: ToolCallContext): Promise<{
+    name: string;
+    bytes: Uint8Array;
+  } | undefined>;
+}
+/** @experimental */
+type TemplateImageResolver = (ref: string, context?: ToolCallContext) => Promise<TemplateImageBytes | undefined>;
+//#endregion
+//#region src/template/toolSource.d.ts
+/** @experimental */
+declare const INSPECT_TEMPLATE_TOOL = "inspect_template";
+/** @experimental */
+declare const FILL_TEMPLATE_TOOL = "fill_template";
+/**
+ * 骨架预算。模板不是文档，格子数是有限的（实测四份模板 32～56 个），
+ * 但没人能保证用户不传一份两千行的台账进来——超了就截断并明说截了。
+ * @experimental
+ */
+declare const TEMPLATE_INSPECT_BUDGET: {
+  readonly cells: 400;
+  readonly chars: 20000;
+};
+/** @experimental */
+interface TemplateToolSourceOptions {
+  /** 模板字节的来源，与 `read_document` 共用一个出口 */
+  files: TemplateFileSource;
+  xlsx?: XlsxTemplateEngine;
+  docx?: DocxTemplateEngine;
+  /** 落产物的出口。**不注入即整条通路不存在**：`fill_template` 不出现在工具清单里 */
+  writeArtifact?: (path: string, bytes: Uint8Array, mimeType: string, context?: ToolCallContext) => Promise<Artifact>;
+  /** 图片引用 → 字节。不注入时 `images` 整个字段不进入参 schema，提示词里也不提图 */
+  resolveImage?: TemplateImageResolver;
+  /** 每次调用重取，宿主改配置立刻生效 */
+  budget?: () => {
+    cells: number;
+    chars: number;
+  };
+  /**
+   * 宿主多认的取件号形式，追加到 `template` 的描述后面（例如「在线文档用 `weboffice:<handle>`」）。
+   * 不给就不提——模型不该学会一个这台机器上读不到的号。
+   */
+  idHint?: string;
+}
+/**
+ * 照着模板出文件（0.22.0 分册 42）。
+ *
+ * 两个工具而不是一个：模型得先看见模板的坐标，才谈得上决定往哪儿写。
+ * 合成一个工具就只剩两条路——要么让模型盲填，要么每次把整份骨架塞进填值的返回里。
+ * @experimental
+ */
+declare function createTemplateToolSource(options: TemplateToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/pageImage/toolSource.d.ts
+declare const CAPTURE_PAGE_IMAGE_TOOL = "capture_page_image";
+/** 取像成功：只有引用与事实，**没有字节**（FR-12.2 / AC-G4） @experimental */
+interface PageImageCapture {
+  /** 形如 `artifact:page-image-1.png`，可直接写进 `AuthoredModel` 图片块的 `ref`（FR-12.7） */
+  artifact: string;
+  width: number;
+  height: number;
+  bytes: number;
+}
+/** 取像失败。`reason` 原样来自 `CaptureFailure`，不得二次包装或缩写（FR-12.4） @experimental */
+interface PageImageFailure {
+  reason: string;
+  triedLevels?: readonly string[];
+}
+/** @experimental */
+type PageImageResult = PageImageCapture | PageImageFailure;
+/** @experimental */
+interface PageImageToolSourceOptions {
+  /**
+   * 取像 + 落产物的出口。**不注入即整条通路不存在**：`listToolSpecs()` 返回空数组，
+   * 模型连这个工具的存在都看不到。纯 Web 宿主拿不到宿主页面的 DOM，
+   * 于是在那些宿主上这个工具根本不出现，而不是出现了每次都失败。
+   *
+   * 授权也在这一层：读页面内容已有授权面，本工具必须落进去，不新开第二个入口（FR-12.5）。
+   */
+  capture?: (input: {
+    ref: string;
+    note?: string;
+  }, context?: ToolCallContext) => Promise<PageImageResult>;
+}
+/**
+ * 页面取像工具（0.22.0 分册 12）。
+ *
+ * 与 `export_spreadsheet` 同一套 `ExternalToolSource` 范式（FR-12.1），
+ * 不另造第二套注册机制。
+ * @experimental
+ */
+declare function createPageImageToolSource(options: PageImageToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/remoteImage/toolSource.d.ts
+declare const FETCH_REMOTE_IMAGE_TOOL = "fetch_remote_image";
+/**
+ * 抓取成功。默认只有引用与事实，**没有字节**（与 `capture_page_image` 同一条约束，AC-G4）；
+ * 只有模型显式要求看图时宿主才填 `mimeType` / `data`（FR-21.11）。
+ * @experimental
+ */
+interface RemoteImageFetch {
+  /** 形如 `artifact:remote-image-1.png`，可直接写进 `AuthoredModel` 图片块的 `ref` */
+  artifact: string;
+  width: number;
+  height: number;
+  bytes: number;
+  /** base64 图像数据，仅当入参 `describe` 为真时提供 */
+  data?: string;
+  /** 与 `data` 同进同出 */
+  mimeType?: string;
+}
+/**
+ * 抓取失败。`reason` 原样来自 `fetchRemoteImage`，不得二次包装（FR-13.4）。
+ * `kind` 是分类，模型据此决定换 URL、重试还是放弃。
+ * @experimental
+ */
+interface RemoteImageFetchFailure {
+  reason: string;
+  kind?: string;
+}
+/** @experimental */
+type RemoteImageResult = RemoteImageFetch | RemoteImageFetchFailure;
+/** @experimental */
+interface RemoteImageToolSourceOptions {
+  /**
+   * 抓取 + 落产物的出口。**不注入即整条通路不存在**：`listToolSpecs()` 返回空数组。
+   * 纯 Web 宿主受同源策略限制抓不到跨域字节（设计 14 §1），
+   * 在那些宿主上这个工具不出现，而不是出现了每次都失败。
+   *
+   * 授权在这一层，且必须发生在**发请求之前**（AC-13.5）。
+   * `describe` 为真时额外把字节回出来给模型看，抓取仍只发生一次（FR-21.11）。
+   */
+  fetchImage?: (input: {
+    url: string;
+    note?: string;
+    describe?: boolean;
+  }, context?: ToolCallContext) => Promise<RemoteImageResult>;
+}
+/**
+ * 外链图片抓取工具（0.22.0 分册 13）。
+ *
+ * 与 `capture_page_image` 同一套范式：模型给出来源、宿主拿字节、回给模型的只有引用。
+ * 三种图片来源（上传、页面、外链）因此在技能那一侧长得一模一样（AC-G1）。
+ * @experimental
+ */
+declare function createRemoteImageToolSource(options: RemoteImageToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/dwg/types.d.ts
+/**
+ * DWG 图纸的端口与几何模型（0.22.0 分册 19）。
+ *
+ * 本文件只声明**形状**：agent 包不解析 DWG，解析由宿主注入
+ * （扩展侧用 `@node-projects/acad-ts`）。与 pptx 端口同构。
+ *
+ * 几何模型的设计前提来自对三份真实图纸的实测（见分册 19 §2.3）：
+ * - 块引用必须在实现侧展开并烘焙变换：`2D.dwg` 顶层只有 1129 个实体，
+ *   展开后是 6044 个；不展开投放出来的是一张近乎空白的图。
+ * - 实体一律带 `handle`，它是 diff 的主键（实测 16613/16618 稳定）。
+ * - 只建模二维图元：图纸自带的三维实体是 ACIS，浏览器里镶嵌不了。
+ */
+/** 二维点。DWG 内部是三维点，二维图元把 Z 丢掉——投放面按 Z 分层，不需要逐点 Z */
+interface DwgPoint {
+  readonly x: number;
+  readonly y: number;
+}
+/** 轴对齐包围盒；相机与自适应缩放都要它 */
+interface DwgBounds {
+  readonly minX: number;
+  readonly minY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+}
+/**
+ * 可绘制的二维图元。
+ *
+ * 归一到这几种形状，是为了让投放面**不必认识 DWG 实体类型**：
+ * Hatch 的边界、Polyline2D、LwPolyline 都塌成折线，Ellipse 与 Arc 各自保留参数式
+ * 表达（塌成折线会在放大时露出棱角，而 CAD 图纸恰恰是要放大看的）。
+ */
+type DwgGeometry = {
+  readonly kind: 'polyline';
+  readonly points: readonly DwgPoint[];
+  readonly closed: boolean;
+} | {
+  readonly kind: 'circle';
+  readonly center: DwgPoint;
+  readonly radius: number;
+} | {
+  readonly kind: 'arc';
+  readonly center: DwgPoint;
+  readonly radius: number;
+  /** 弧度，逆时针；acad-ts 给的就是弧度，不在端口上换算成角度徒增一次转换 */
+  readonly startAngle: number;
+  readonly endAngle: number;
+} | {
+  readonly kind: 'ellipse';
+  readonly center: DwgPoint;
+  /** 长轴端点相对中心的偏移；短轴由 `ratio` 导出，与 DWG 的表示一致 */
+  readonly majorAxis: DwgPoint;
+  readonly ratio: number;
+  readonly startAngle: number;
+  readonly endAngle: number;
+} | {
+  readonly kind: 'point';
+  readonly at: DwgPoint;
+} | {
+  readonly kind: 'text';
+  readonly at: DwgPoint;
+  /** 已剥离 MText 格式控制码的纯文本（`{\fSimSun|b0|i0|c134|p2;餐厅}` → `餐厅`） */
+  readonly text: string;
+  readonly height: number;
+  /** 弧度 */
+  readonly rotation: number;
+  /**
+   * `at` 这个点落在文字的哪个位置（0.22.0 分册 25 FR-25.1）。
+   *
+   * 对齐是文字**几何的固有属性**而非渲染偏好：实测 `大堂立面图.dwg` 的 178 个
+   * MTEXT 里有 96 个是 MiddleCenter，不带这两个字段的话每个接入方都得自己去猜，
+   * 猜错的后果就是文字整体偏出半个字高加半个字宽、溢到方框和圆圈外面。
+   * 省略时按 `left` / `baseline`，即分册 24 的既有行为。
+   */
+  readonly anchorX?: 'left' | 'center' | 'right';
+  readonly anchorY?: 'top' | 'middle' | 'baseline' | 'bottom';
+  /** MText 的换行宽度（世界单位）；缺省或为 0 表示不折行 */
+  readonly wrapWidth?: number;
+  /**
+   * 图纸指定的字体（0.22.0 分册 28 FR-28.5）。
+   *
+   * 字号一直来自 `height`，字体族却无处可取，于是每个接入方只能硬写一个。
+   * 实测 `2D.dwg` 的 462 条文字里，129 条走 SHX 笔画字体、74 条走 `simhei.ttf`、
+   * 223 条走 `arial.ttf`——全部画成同一个无衬线体与原图相去甚远。
+   * 样式缺失或字段为空时省略。
+   */
+  readonly font?: DwgFont;
+};
+/**
+ * 文字样式指定的字体（0.22.0 分册 28 FR-28.5）。
+ *
+ * 拉丁字体与 CJK 大字体是**两个独立的槽**，可以不同
+ * （实测样式 `TH-STYLE2` 是 `th-rmc` + `th-chnc`），因此不能合并成一个字段。
+ */
+interface DwgFont {
+  /** 主字体文件名，如 `simhei.ttf` / `th-rmc`；样式未指定时省略 */
+  readonly file?: string;
+  /** CJK 大字体文件名，如 `th-chnc`；只有 SHX 样式才有 */
+  readonly bigFile?: string;
+  /** 宽度因子；1 或缺省表示不横向缩放 */
+  readonly widthFactor?: number;
+}
+/**
+ * 填充（0.22.0 分册 23 FR-23.3）。
+ *
+ * 分册 19 只取了填充的**边界**，于是真实图纸里 218 个 HATCH 全变成了空轮廓。
+ * 填充单独建模而不是塑成几何，是因为它**不进指纹**：
+ * 一个图案填充展开后可达 6358 条线段，让它们各自成为一条差异记录，
+ * 明细表会被淢没到不可用（FR-23.3 注 / AC-23.4）。
+ */
+type DwgFill = {
+  /** 实心填充。多个环按奇偶规则填，带岛的图案才不会把洞填死 */
+  readonly kind: 'solid';
+  readonly loops: readonly (readonly DwgPoint[])[];
+  /**
+   * 环的组合规则（0.22.0 分册 28 FR-28.4）。缺省视同 `'evenodd'`。
+   *
+   * 宽多段线铺出的带面是一组互相重叠的四边形的**并集**，奇偶规则会把
+   * 转角的重叠处异或成洞（实测转角处一行被切成 `5 / 9 / 5` 三截）；
+   * 而 HATCH 的环是带岛的**区域**，必须继续用奇偶规则，否则天井会被填实。
+   */
+  readonly rule?: 'evenodd' | 'nonzero';
+} | {
+  /** 图案填充：`Hatch.explodePattern()` 展开后的线段，四个一组 `x1,y1,x2,y2` */
+  readonly kind: 'pattern';
+  readonly segments: readonly number[];
+} | {
+  /** 遮罩（WIPEOUT）：按边界填背景色。这就是它的语义，不是「不支持」 */
+  readonly kind: 'mask';
+  readonly loops: readonly (readonly DwgPoint[])[];
+};
+/**
+ * 一个可绘制的实体。
+ *
+ * `handle` 是 DWG 自带的标识，由实现侧产出；消费方不反向解析几何。
+ */
+interface DwgEntity {
+  /** DWG 句柄，十六进制字符串。实测在同源另存间稳定 */
+  readonly handle: string;
+  /** 原始实体类型名，如 `Line` / `LwPolyline` / `MText` */
+  readonly kind: string;
+  readonly layer: string;
+  readonly geometry: DwgGeometry | undefined;
+  /** 块属性（ATTRIB）的 tag→value；无属性时为 undefined */
+  readonly attributes?: Readonly<Record<string, string>>;
+  /** 实体色 `#rrggbb`；缺省（ByLayer）时省略，由渲染层回落图层色 */
+  readonly color?: string;
+  readonly fill?: DwgFill;
+  /** 线型的 dash 模式，**世界单位**（绘制时再乘镜头缩放）；省略即实线 */
+  readonly dash?: readonly number[];
+  /**
+   * 线宽，单位 0.01 mm（0.22.0 分册 25 FR-25.3）。
+   *
+   * `ByLayer` / `ByBlock` / `Default` 这三种间接值已在解析期解开，拿到的就是实际值；
+   * 解不出来时省略。实测这张图的线宽跨越 `5`(0.05 mm) 到 `50`(0.50 mm) 共十倍，
+   * 不带它就只能把图框、云线与细标注线一律画成同一种粗细。
+   */
+  readonly lineWeight?: number;
+}
+/**
+ * 图纸空间里的一个视口（FR-23.2）。
+ *
+ * 它把模型空间的一块区域按相似变换画进图纸上的一个矩形窗口。
+ * 实测 `大堂立面图.dwg` 的 Layout1 有 6 个视口，其中 5 个是 50:1 的立面窗口，
+ * 它们同时也是一份现成的模型空间分区表（分册 23 §2.2）。
+ */
+interface DwgViewport {
+  /** 图纸空间里的窗口中心与尺寸 */
+  readonly center: DwgPoint;
+  readonly width: number;
+  readonly height: number;
+  /** 窗口里看到的模型空间中心与高度；缩放比 = `height / viewHeight` */
+  readonly viewCenter: DwgPoint;
+  readonly viewHeight: number;
+  /** 视图扭角，弧度 */
+  readonly twistAngle: number;
+  /** 视口级冻结的图层。本图为空，但不实现就是一个会在别的图纸上炸的洞 */
+  readonly frozenLayers: readonly string[];
+}
+/**
+ * 图纸上的一个「物件」：一次块引用（0.22.0 分册 37 FR-37.1）。
+ *
+ * 门、窗、家具、洁具、消防栓在图纸里几乎全是以 `INSERT` 存在的，
+ * 块名就是图纸作者亲手声明的「这是一个物件」。解析时块被展开成几何（为了画出来），
+ * 这份清单是展开的同时另收的一份，**不影响渲染**（FR-37.4）。
+ * @experimental
+ */
+interface DwgComponent {
+  /** 块名。动态块变体已回查源块取真名（FR-37.3） */
+  readonly block: string;
+  /** 插入点，世界坐标（嵌套块已烘焙过外层变换） */
+  readonly at: DwgPoint;
+  /** 旋转角，弧度 */
+  readonly rotation: number;
+  readonly scaleX: number;
+  readonly scaleY: number;
+  readonly layer: string;
+  /** `ATTRIB` 的 tag→value；一个都没有时省略 */
+  readonly attributes?: Readonly<Record<string, string>>;
+}
+/**
+ * 一个可切换的视图（FR-23.1）：模型空间或一张图纸。
+ *
+ * `id` 用 Layout 名（`Model` / `Layout1`）而不用句柄或序号：
+ * 两份图纸的**同名** Layout 才是业务上「同一张图纸」，对比靠它配对（FR-23.7）。
+ */
+interface DwgView {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: 'model' | 'layout';
+  readonly entities: readonly DwgEntity[];
+  readonly bounds: DwgBounds;
+  /**
+   * 图纸**自己声明**的范围（0.22.0 分册 29 FR-29.4）。
+   *
+   * 图纸空间取打印窗口（`plotType` 为「窗口」时才有），模型空间取 `$EXTMIN` / `$EXTMAX`。
+   * 与量出来的 `bounds` 并存而不替代：实测 `大堂平面图.dwg` 的模型空间实体盒是
+   * 4.79e10 × 1.89e10，而 `$EXTMIN`/`$EXTMAX` 只有 7.93e8 × 1.09e9——
+   * 差出来的 60 倍是 1311 个原始插入点就在 −3.6e10 的属性，两个数同时在场才看得出来。
+   *
+   * 声明不出来（`plotType` 不是窗口、数值非有限、宽高退化为 0）时省略。
+   */
+  readonly extent?: DwgBounds;
+  readonly viewports: readonly DwgViewport[];
+  /**
+   * 本视图里的构件清单（FR-37.1）。字段缺失是合法状态：
+   * 宿主自己实现的解析器可以不产出它，那时「对比差异」不出现。
+   */
+  readonly components?: readonly DwgComponent[];
+}
+interface DwgLayer {
+  readonly name: string;
+  /** `#rrggbb`；实现侧把 DWG 的索引色解析成实际颜色 */
+  readonly color: string;
+  readonly visible: boolean;
+}
+/**
+ * 图纸坐标的量纲（0.22.0 FR-31.12），取自图头的 `INSUNITS`。
+ *
+ * `'unitless'` 是图纸自己说不知道，**不是**「默认毫米」：
+ * 猜错一次就是 1000 倍，而且不会有任何提示。
+ */
+type DwgUnits = 'mm' | 'cm' | 'm' | 'km' | 'in' | 'ft' | 'yd' | 'mi' | 'unitless';
+/** 解析结果。一份图纸拉平成实体数组 + 图层表 + 元信息 */
+interface DwgDocumentContent {
+  /** 文件格式版本，如 `AC1021` */
+  readonly version: string;
+  readonly layers: readonly DwgLayer[];
+  /** 模型空间视图的实体（= `views` 里 `kind==='model'` 那一项的别名） */
+  readonly entities: readonly DwgEntity[];
+  readonly bounds: DwgBounds;
+  /** 坐标的量纲（FR-31.12）。字段缺失与 `'unitless'` 同义：量出来的数没有单位 */
+  readonly units?: DwgUnits;
+  /**
+   * 所有可切换的视图（FR-23.1）：模型空间 + 每一张图纸。
+   * 空 Layout 也列在这里——隐了会让用户以为图纸里没有这张表（FR-23.2）。
+   *
+   * 可选是为了给不产出图纸空间的解析实现留退路（宿主自己实现 `DwgDocumentReader`
+   * 也是允许的）；取用一律走 `dwgViewsOf`，它会补一个模型空间视图。
+   */
+  readonly views?: readonly DwgView[];
+  /** 模型空间视图的构件清单（= `views` 里 `kind==='model'` 那一项的别名） */
+  readonly components?: readonly DwgComponent[];
+  /**
+   * 无法原样呈现的内容，必须显式上报而不是静默丢弃（FR-19.7 / FR-23.6）。
+   * 包括两类：完全没画的（ACIS）与降级画的（图案近似、线型退回实线）。
+   */
+  readonly omissions: readonly DwgOmission[];
+}
+interface DwgOmission {
+  readonly kind: string;
+  readonly count: number;
+  readonly reason: 'acis-not-tessellated' | 'unsupported-entity' | 'pattern-approximated' | 'pattern-too-dense' | 'linetype-unavailable';
+  /**
+   * `dropped` = 完全没画；`degraded` = 画了，但不是原样。
+   *
+   * 分册 19 只上报前一类，于是界面上那句「只有 2 个图元不受支持」
+   * 遮住了「218 个填充被降级了」——这比画不出来更有害（FR-23.6）。
+   */
+  readonly severity: 'dropped' | 'degraded';
+}
+/** 宿主注入的解析实现 */
+interface DwgDocumentReader {
+  read(bytes: Uint8Array): Promise<DwgDocumentContent>;
+}
+//#endregion
+//#region src/dwg/toolSource.d.ts
+declare const VIEW_DWG_TOOL = "view_dwg";
+/**
+ * `load()` 的另一种返回形态：连文件名一起给（0.22.0 FR-31.1）。
+ *
+ * 图纸到模型手里只有取件号（见 `SYSTEM_PROMPT`），所以 `file` 入参不是文件名；
+ * 真名只有解析取件号的那一侧知道，这是它交出来的唯一通道。 @experimental
+ */
+interface DwgLoadedDrawing {
+  readonly document: DwgDocumentContent;
+  readonly name?: string;
+}
+/** 宿主注入的解析与投放出口 @experimental */
+interface DwgToolSourceOptions {
+  /**
+   * 把一个文件引用读成几何模型。**不注入即整条通路不存在**——
+   * `listToolSpecs()` 返回空数组，模型看不到这个工具（AC-34.3）。
+   *
+   * 只返回 `DwgDocumentContent` 的宿主行为不变；带上 `name` 才能让投放面显示文件名。
+   */
+  load?: (file: string, context?: ToolCallContext) => Promise<DwgDocumentContent | DwgLoadedDrawing>;
+  /** 投放到查看器。同样由宿主实现：agent 包不认识 `documentSurface` */
+  project?: (input: DwgProjection, context?: ToolCallContext) => Promise<void>;
+}
+/** 投放载荷里的一份图纸 @experimental */
+interface DwgProjectedDrawing {
+  /** 模型传进来的取件号。进告知卡与审计，是**数据来源描述**，不是文件名 */
+  readonly title: string;
+  /** 给人看的文件名（FR-31.2）。宿主的 `load()` 没给名字时为 `undefined` */
+  readonly fileName?: string;
+  readonly document: DwgDocumentContent;
+}
+/**
+ * 投放载荷。几何走这里去查看器，**不进模型上下文**。
+ *
+ * 单份与双份同形（§4.2）：只看一份时 `drawings` 就是一元素数组。
+ * 留一条「单份专用」旁路会让两条渲染路径各自演化。数组顺序就是初始叠放顺序，第一项在上。
+ * @experimental
+ */
+interface DwgProjection {
+  readonly drawings: readonly DwgProjectedDrawing[];
+}
+/**
+ * DWG 查看工具（0.22.0 分册 19，分册 34 收敛为单工具）。
+ *
+ * 与 `capture_page_image` 同一套 `ExternalToolSource` 范式。
+ * 解析与投放都由宿主注入：本包不认识 `.dwg` 字节，也不认识 `documentSurface`。
+ * @experimental
+ */
+declare function createDwgToolSource(options: DwgToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/dwg/views.d.ts
+/**
+ * 视图取用（0.22.0 分册 23 FR-23.5 / FR-23.7）。
+ *
+ * 单独成文件是因为 diff、导出、投放面三边都要用同一套「哪些视图、按什么配对」，
+ * 各写一份迟早会在某一边把空布局漏掉。
+ */
+/** 模型空间视图的固定 id。两份图纸靠它配对 */
+declare const DWG_MODEL_VIEW_ID = "Model";
+/**
+ * 文档的视图列表。
+ *
+ * 分册 23 之前解析出的文档没有 `views`，给它补一个模型空间视图：
+ * 那时的 `entities` 本来就是模型空间的全部内容，语义对得上。
+ */
+declare function dwgViewsOf(doc: DwgDocumentContent): readonly DwgView[];
+/** 按 id 取视图；取不到就退回第一个，而不是什么都没有 */
+declare function dwgPickView(doc: DwgDocumentContent, viewId: string | undefined): DwgView;
+//#endregion
+export { DownloadedFileEntry as $, SkillGenerationToolSourceOptions as $n, createPageImageToolSource as $r, PERCEPTION_PAGING_DEFAULTS as $t, DataSourceRecord as A, PerceptionAuditSink as An, TodoListener as Ar, FILL_TEMPLATE_TOOL as At, DocumentFileSource as B, READ_DOCUMENT_TOOL as Bn, XlsxTemplateEngine as Br, LIST_PAGE_TABS_TOOL as Bt, DataSourceCandidateRecord as C, toActionFrameScopes as Ci, ParentBudget as Cn, TemplateParagraphSkeleton as Cr, DwgView as Ct, DataSourcePolicy as D, PdfTextQuality as Dn, TodoEvent as Dr, EMU_PER_TWIP as Dt, DataSourceKind as E, PdfPageImage as En, TemplateToolSourceOptions as Er, EMU_PER_POINT as Et, DelegationRequest as F, PerceptionScope as Fn, WorksetTab as Fr, GeneratedSkillDraft as Ft, DocumentToolSourceOptions as G, RemoteImageToolSourceOptions as Gn, clampWorksetMax as Gr, OpenedTabSignal as Gt, DocumentImageRole as H, RemoteImageFetch as Hn, XlsxTemplateSkeleton as Hr, MAX_DIGIT_WIDTH as Ht, DelegationResult as I, PerceptionScopeInput as In, WorksetTabView as Ir, HttpDataSourceOptions as It, DocxTemplateEngine as J, Size as Jn, createDocumentToolSource as Jr, PAGE_ACTION_TOOL as Jt, DocxDocumentContent as K, RenderedImage as Kn, columnWidthToPixels as Kr, PAGE_ACTION_KINDS as Kt, DelegationToolSourceOptions as L, PptxDocumentContent as Ln, XlsxDocumentContent as Lr, INSPECT_TEMPLATE_TOOL as Lt, DelegationBudget as M, PerceptionPagingBudget as Mn, TodoStore as Mr, FrameNote as Mt, DelegationOrchestrator as N, PerceptionRecord as Nn, TodoToolSourceOptions as Nr, FrameScope as Nt, DataSourcePolicyOptions as O, PerceivedImage as On, TodoItem as Or, EXPORT_SPREADSHEET_TOOL as Ot, DelegationOrchestratorOptions as P, PerceptionResult as Pn, VIEW_DWG_TOOL as Pr, GENERATE_SKILL_TOOL as Pt, DownloadedFileConsent as Q, SkillGenerationPolicy as Qn, createPageActionToolSource as Qr, PERCEIVE_PAGE_TOOL as Qt, DocumentBlock as R, PptxDocumentReader as Rn, XlsxDocumentReader as Rr, ImageCaptureBudget as Rt, DataSourceCandidatePolicyOptions as S, takesImage as Si, PagePerceptionToolSourceOptions as Sn, TemplateImageResolver as Sr, DwgUnits as St, DataSourceDef as T, withDelegationOrigin as Ti, PdfDocumentReader as Tn, TemplateTableCellSkeleton as Tr, EMU_PER_PIXEL as Tt, DocumentReadBudget as U, RemoteImageFetchFailure as Un, asReadMode as Ur, NestedFrameRef as Ut, DocumentFormat as V, READ_DOWNLOADED_FILE_TOOL as Vn, XlsxTemplateFillSpec as Vr, MANAGE_TODO_TOOL as Vt, DocumentReadMode as W, RemoteImageResult as Wn, clampDownloadWaitMs as Wr, OpenedPageInfo as Wt, DocxTemplateSkeleton as X, SkillGenerationMessages as Xn, createDwgToolSource as Xr, PDF_GARBLED_RATIO as Xt, DocxTemplateFillSpec as Y, SkillCandidateSink as Yn, createDownloadedFileToolSource as Yr, PAGE_DOCUMENT_REF as Yt, DownloadedFileAction as Z, SkillGenerationOutcome as Zn, createHttpDataSourceTransport as Zr, PDF_LARGE_IMAGE_RATIO as Zt, DWG_MODEL_VIEW_ID as _, parseCellAddress as _i, PageImageResult as _n, TabWorksetPort as _r, DwgOmission as _t, ActionTabWindow as a, createTemplateToolSource as ai, PageActionPolicy as an, SubAgentRunInput as ar, DownloadedFileRecord as at, DataSourceCandidateAuditSink as b, readImageSize as bi, PagePerceptionPolicyOptions as bn, TemplateFileSource as br, DwgProjection as bt, CellAddress as c, dwgPickView as ci, PageActionRequest as cn, TAB_WORKSET_DEFAULT_MAX as cr, DwgComponent as ct, DELEGATE_TASK_TOOL as d, formatCellAddress as di, PageActionTarget as dn, TAB_WORKSET_SYSTEM_PROMPT as dr, DwgEntity as dt, createPagePerceptionToolSource as ei, PERCEPTION_SYSTEM_PROMPT as en, SkillGenerator as er, DownloadedFileListing as et, DELEGATION_SYSTEM_PROMPT as f, frameLabel as fi, PageActionToolSourceOptions as fn, TEMPLATE_INSPECT_BUDGET as fr, DwgFill as ft, DOWNLOAD_WAIT_MIN_MS as g, measurePdfTextQuality as gi, PageImageFailure as gn, TabWorksetPolicyOptions as gr, DwgLoadedDrawing as gt, DOWNLOAD_WAIT_MAX_MS as h, isRangeTopLeft as hi, PageImageCapture as hn, TabWorksetPolicy as hr, DwgLayer as ht, ActionTabWatcher as i, createTabWorksetToolSource as ii, PageActionOutcome as in, SpreadsheetToolSourceOptions as ir, DownloadedFileReader as it, DataSourceTransport as j, PerceptionCaptureOptions as jn, TodoStatus as jr, FOCUS_PAGE_TAB_TOOL as jt, DataSourceProvenance as k, PerceivedNode as kn, TodoList as kr, FETCH_REMOTE_IMAGE_TOOL as kt, CellRange as l, dwgViewsOf as li, PageActionScope as ln, TAB_WORKSET_MAX_MAX as lr, DwgDocumentContent as lt, DOWNLOAD_WAIT_DEFAULT_MS as m, isPdfTextTrustworthy as mi, PageAuditSink as mn, TabAdmission as mr, DwgGeometry as mt, ActionDownloadWindow as n, createSkillGenerationToolSource as ni, PageActionExecutor as nn, SkillTraceEvidence as nr, DownloadedFilePolicyOptions as nt, CAPTURE_PAGE_IMAGE_TOOL as o, createTodoToolSource as oi, PageActionPolicyOptions as on, SubAgentRunner as or, DownloadedFileToolSourceOptions as ot, DOCUMENT_READ_BUDGET as p, frameSteps as pi, PageActionUi as pn, TODO_SYSTEM_PROMPT as pr, DwgFont as pt, DocxDocumentReader as q, SKILL_GENERATION_SYSTEM_PROMPT as qn, createDelegationToolSource as qr, PAGE_ACTION_SYSTEM_PROMPT as qt, ActionFrameScope as r, createSpreadsheetToolSource as ri, PageActionKind as rn, SkillTraceEvidenceStep as rr, DownloadedFileReadResult as rt, CLOSE_PAGE_TAB_TOOL as s, defersImage as si, PageActionRecord as sn, SubtreeRejection as sr, DwgBounds as st, ActionDownloadWatcher as t, createRemoteImageToolSource as ti, PageActionConsent as tn, SkillGeneratorOptions as tr, DownloadedFilePolicy as tt, ConsentUi as u, fitWithin as ui, PageActionScopeInput as un, TAB_WORKSET_MIN_MAX as ur, DwgDocumentReader as ut, DataSourceAuditSink as v, parseCellRange as vi, PageImageToolSourceOptions as vn, TabWorksetToolSourceOptions as vr, DwgPoint as vt, DataSourceCandidateStore as w, toFrameScopes as wi, PdfDocumentHandle as wn, TemplateSheetSkeleton as wr, DwgViewport as wt, DataSourceCandidatePolicy as x, sniffDocumentFormat as xi, PagePerceptionReader as xn, TemplateImageBytes as xr, DwgToolSourceOptions as xt, DataSourceCandidate as y, rangeContains as yi, PagePerceptionPolicy as yn, TemplateCellSkeleton as yr, DwgProjectedDrawing as yt, DocumentFileBytes as z, PptxSlideContent as zn, XlsxSheetContent as zr, LIST_DOWNLOADED_FILES_TOOL as zt };