@webskill/sdk 0.21.0 → 0.23.0

package/dist/{index-CYLt5u4L.d.ts → index-V76_OFj2.d.ts}

@@ -1,5 +1,5 @@
-import { I as ChatAttachmentKind, Pt as WebSkillErrorCode, Q as RemoteUrlPolicy, S as UiBridge, a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest, t as Artifact } from "./types-BvTV_05--BW8zDuEk.js";
-import { En as ToolStepReader, P as DocxTextExtractor, bn as ToolCallContext, cr as XlsxTextExtractor, dt as PdfTextExtractor, j as DataSourceInfo, z as ExternalToolSource } from "./index-DHopiH_m.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-BiZBXGm4.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-7No55dRb.js";
 //#region ../agent/dist/index.d.ts
 //#region src/todo/types.d.ts
 /** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
@@ -48,11 +48,18 @@ declare class TodoStore {
   /**
    * 更新单条。置为 `in-progress` 时其余进行中条目降级为 `pending`，
    * 每条降级各发一次 `todo.updated`，事件序列与状态变化一一对应。
+   *
+   * `options.concurrent` 由**编排器**在并发委派时传（0.23.0 分册 19 FR-19.9）：
+   * 几个子 agent 真的在同时跑，把别人降级回 `pending` 是在界面上说谎。
+   * 模型经 `manage_todo` 的写入不传它，仍维持「同时只有一条进行中」——
+   * 那条约束针对的是模型乱标（名义并行、实则一件事），不是真并发。
    */
   update(id: string, patch: {
     status?: TodoStatus;
     title?: string;
     delegatedTo?: string;
+  }, options?: {
+    concurrent?: boolean;
   }): TodoList;
   clear(): void;
 }
@@ -90,9 +97,14 @@ interface GeneratedSkillDraft {
   description: string;
   /** SKILL.md 全文，含 frontmatter */
   content: string;
+  /**
+   * 附带文件。`attachmentId` 在场即本条目的内容是**本会话已上传的那个附件的字节**，
+   * 此时 `content` 恒为空串——模型从没持有过那些字节，让它复述等于让它编（0.23.0 分册 20）。
+   */
   files?: readonly {
     path: string;
     content: string;
+    attachmentId?: string;
   }[];
   /**
    * 模型声称这个技能会执行的工具调用（分册 30 / FR-30.4）。
@@ -105,6 +117,30 @@ interface GeneratedSkillDraft {
     args?: Record<string, unknown>;
   }[];
 }
+/**
+ * 一个被指认的附件的字节与身份（0.23.0 分册 20）。
+ * 由宿主的 `SkillGeneratorOptions.resolveAttachment` 交出。
+ */
+interface SkillAttachmentBytes {
+  bytes: Uint8Array;
+  /** 上传时的原始文件名，供审核者辨认（FR-20.10） */
+  name: string;
+  contentType?: string;
+}
+/**
+ * 已物化的一份二进制：字节加上它的身份与校验信息（0.23.0 分册 20）。
+ *
+ * `sha256` 不是装饰——AC-20.1 的「逐字节相同」靠它判，
+ * 而本册要防的失败模式正是**悄悄损坏**：被 UTF-8 往返污染过的 `.xlsx`
+ * 仍能被宽容的解析器打开，却在用户手里丢数据。
+ */
+interface SkillBinaryPayload {
+  bytes: Uint8Array;
+  size: number;
+  /** 十六进制小写 */
+  sha256: string;
+  sourceName: string;
+}
 /**
  * 候选收货端口。实现由宿主注入——`@webskill/agent` 不依赖 `@webskill/governance`
  * （治理层要求宿主提供治理根与审计存储，是可选层）。
@@ -117,6 +153,11 @@ interface SkillCandidateSink {
     sessionId?: string;
     /** 用户确认的时刻（FR-9.7 要求审计能查到确认事实） */
     confirmedAt: string;
+    /**
+     * 已物化的二进制，键是 `draft.files[].path`。缺省即本次生成全是文本（0.23.0 分册 20）。
+     * 字节在这里就已经读出来了：候选必须能脱离会话附件独立存活（FR-20.6）。
+     */
+    binaries?: ReadonlyMap<string, SkillBinaryPayload>;
   }): Promise<{
     id: string;
   }>;
@@ -125,6 +166,10 @@ interface SkillCandidateSink {
 interface SkillGenerationPolicy {
   /** 单次会话内的生成次数上限，默认 3 */
   maxPerSession?: number;
+  /** 单个二进制条目的字节上限（0.23.0 分册 20 FR-20.12） */
+  maxBinaryBytes?: number;
+  /** 一个技能内所有二进制条目的字节总量上限（0.23.0 分册 20 FR-20.12） */
+  maxTotalBinaryBytes?: number;
 }
 type SkillGenerationOutcome = {
   status: 'submitted';
@@ -151,6 +196,16 @@ interface SkillGeneratorOptions {
    * 这既让本册可分步落地，也给 AC-30.14 的反向对照留了现成的造法。
    */
   steps?: ToolStepReader;
+  /**
+   * 按 id 取本会话已上传附件的字节（0.23.0 分册 20 FR-20.2）。
+   *
+   * **按 id 查而不是按路径取**是安全边界：路径入参等于给模型一条把宿主磁盘上
+   * 任意文件复制进技能包的通路；按 id 在本会话附件表里查，能被指认的集合
+   * 恰好等于「用户自己这次会话上传的东西」。查不到（含跨会话的 id）返回 `undefined`。
+   *
+   * 不注入即本宿主不支持指认附件，模型给了 `attachmentId` 也按拒绝处理。
+   */
+  resolveAttachment?: (id: string) => Promise<SkillAttachmentBytes | undefined>;
 }
 /** 生成器面向用户的文案；缺省全部为英文模板 */
 interface SkillGenerationMessages {
@@ -263,13 +318,21 @@ interface DelegationOrchestratorOptions {
   policy?: Partial<DelegationBudget>;
   /** 接上清单后委派关系在 UI 可见（FR-11.5） */
   todos?: TodoStore;
+  /**
+   * 同时在跑的子 agent 数上限（0.23.0 分册 19 FR-19.5/19.16）。
+   *
+   * 每次委派入口都会重新调用它：用户在确认卡里选的并发数是会话中途才定下来的，
+   * 装配期读一次就固化的话，那个旋钮永远停在默认值上。
+   * 缺省 1，即维持 0.22.x 之前的串行行为——只是超额的请求改为排队而不再报错。
+   */
+  concurrencyLimit?: () => number;
 }
 /**
- * 串行委派编排器（设计 03 §13–§16）。
+ * 委派编排器（设计 03 §13–§16，并发改造见 0.23.0 分册 19）。
  *
- * 严格串行由**内部互斥**保证而不是调用方自觉：并发委派会产生并发待决交互，
- * 而当前交互模型是单一待决 nonce，届时表现为「点了没反应」。
- * 放开并发必须显式改这里的守卫，不会悄悄发生。
+ * 并发放开的前提是**并行的是执行、不是提问**：待决交互仍然一次只呈现一张，
+ * 由 `ReactBridgeState` / `specInteractionChannel` 的队列保证。
+ * 若要在别处复用本编排器，那两处的排队语义是它的前置条件。
  *
  * 上下文隔离靠回值形状达成：只有 `summary` 回到父 agent，
  * 子 agent 的消息历史根本不经过本对象。
@@ -278,7 +341,7 @@ interface DelegationOrchestratorOptions {
 declare class DelegationOrchestrator {
   #private;
   constructor(options: DelegationOrchestratorOptions);
-  /** 当前正在执行的委派任务；无则 undefined */
+  /** 正在执行的委派任务之一；全部空闲则 undefined。仅供诊断 */
   get running(): string | undefined;
   delegate(request: DelegationRequest): Promise<DelegationResult>;
 }
@@ -313,10 +376,10 @@ declare function withDelegationOrigin(bridge: UiBridge, origin: InteractionOrigi
 //#endregion
 //#region src/prompts/delegation.d.ts
 /**
- * 串行委派的策略提示词（设计 03 §13）。
+ * 委派的策略提示词（设计 03 §13；并发改造见 0.23.0 分册 19）。
  *
- * 「一次只能有一个」是编排器的硬约束，这里写进提示词是为了让模型不去
- * 尝试并行委派——被拒绝的调用会浪费一轮，而不是产生并发。
+ * 并发数那两句是**建议**而非约束：真正拦住数量的是编排器的排队与宿主硬上限。
+ * 写在这里是为了让模型按任务真实需要给值，而不是一口气派出一大批。
  */
 declare const DELEGATION_SYSTEM_PROMPT: string;
 //#endregion
@@ -413,6 +476,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`）。
    * **主文档节点不带这个字段**——否则旧宿主的断言会凭空变化。
@@ -438,8 +507,23 @@ interface PerceivedNode {
    * 它的其余子节点在前一段或后一段里。缺省不带该字段。
    */
   continued?: boolean;
+  /**
+   * 此处还能往哪些方向滚（0.23.0 分册 22 FR-22.1）。只在该元素**自身**是可滚容器、
+   * 且该方向尚未到头时出现；两端都到头字段就消失。
+   *
+   * 不表达滚动量：给了数值模型就会算「还要滚几次」，而列虚拟化下 `scrollWidth`
+   * 随列的重建而变，那个算法必然算错（沿用 0.18.0 FR-10.2）。
+   *
+   * **出现该字段的节点必然带 `ref`**——标了能滚却给不出句柄，模型就处在
+   * 「知道能滚、够不着」的状态，正是 AC-G8 要禁的那种幽灵能力。
+   */
+  scrollable?: readonly ScrollDirection[];
   children?: readonly PerceivedNode[];
 }
+/** 滚动方向（0.23.0 分册 22）。感知的 `scrollable` 与动作记录的 `direction` 共用，避免两处漂移 */
+type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+/** 四个方向的规范清单；工具层校验与文案生成都从这里取，不各写一份 */
+declare const SCROLL_DIRECTIONS: readonly ScrollDirection[];
 /** 随感知一起下发的一张图像（FR-12.1） @experimental */
 interface PerceivedImage {
   /** 与 `PerceivedNode.imageId` 对应 */
@@ -1119,15 +1203,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 +1233,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;
 }
@@ -1262,9 +1352,11 @@ interface PageActionRecord {
    * 本次滚动的方向与实际位移（0.18.0 FR-10.8）；非 `scroll` 动作不带。
    * 位移要进留痕：只记「滚了」而不记「滚了多少」，事后分不出
    * 「滚到底了」与「根本没滚动」。
+   *
+   * 0.23.0 分册 22 起方向扩到四向：横向滚动记成 `down` 会让留痕说谎。
    */
   scrolled?: {
-    direction: 'down' | 'up';
+    direction: ScrollDirection;
     movedBy: number;
     atEnd: boolean;
   };
@@ -1694,6 +1786,7 @@ interface DownloadedFilePolicyOptions {
   docxExtractor?: DocxTextExtractor;
   /** xlsx → 文本。同上 */
   xlsxExtractor?: XlsxTextExtractor;
+  pptxExtractor?: PptxTextExtractor;
   /** 超阈值 PDF 的兜底抽取（AC-21.2）。同样必须与手动上传共用一个实现 */
   pdfExtractor?: PdfTextExtractor;
   /**
@@ -1774,16 +1867,16 @@ declare const DOCUMENT_READ_BUDGET: DocumentReadBudget;
 //#endregion
 //#region src/document/types.d.ts
 /**
- * 文档逐单元读取的三个端口（0.21.0 分册 22）。
+ * 文档逐单元读取的四个端口（0.21.0 分册 22；0.22.0 分册 18 添上 pptx）。
  *
  * 与既有的 `PdfTextExtractor` / `DocxTextExtractor` / `XlsxTextExtractor` 并存，不替换：
  * 那条路解决的是「这份文件太大，退而求其次给点文本」，
  * 这条路解决的是「这份文件必须读完，而且读不出字的地方要看图」。
  *
- * 三个端口**各自独立**：只接了 PDF 的宿主照样能用，另两支自动缺席（FR-22.16）。
+ * 四个端口**各自独立**：只接了 PDF 的宿主照样能用，其余几支自动缺席（FR-22.16）。
  */
 /** @experimental */
-type DocumentFormat = 'pdf' | 'docx' | 'xlsx';
+type DocumentFormat = 'pdf' | 'docx' | 'xlsx' | 'pptx';
 /**
  * 一次工具调用内打开的 PDF；生命周期不跨调用（续读靠自包含坐标，不存游标）
  * @experimental
@@ -1860,6 +1953,25 @@ 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;
@@ -1945,13 +2057,14 @@ interface DocumentToolSourceOptions {
   pdf?: PdfDocumentReader;
   docx?: DocxDocumentReader;
   xlsx?: XlsxDocumentReader;
+  pptx?: PptxDocumentReader;
   /** 每次调用重取，宿主改配置立刻生效 */
   budget?: () => DocumentReadBudget;
 }
 /**
  * 逐单元读文档，读不出字的地方出图（0.21.0 分册 22）。
  *
- * 三个端口一个都没接时 `listToolSpecs()` 返回空——模型连这个工具的存在都看不到，
+ * 四个端口一个都没接时 `listToolSpecs()` 返回空——模型连这个工具的存在都看不到，
  * 而不是看得到再被拒（AC-22.2）。
  * @experimental
  */
@@ -1968,6 +2081,13 @@ interface SpreadsheetToolSourceOptions {
    * `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>;
 }
 /**
  * 把表格导出接到既有工具协议上。
@@ -1978,4 +2098,652 @@ interface SpreadsheetToolSourceOptions {
  */
 declare function createSpreadsheetToolSource(options: SpreadsheetToolSourceOptions): ExternalToolSource;
 //#endregion
-export { DownloadedFileToolSourceOptions as $, defersImage as $n, PerceptionScope as $t, DelegationOrchestratorOptions as A, TodoList as An, PageActionRequest as At, DocumentReadMode as B, asReadMode as Bn, PagePerceptionToolSourceOptions as Bt, DataSourcePolicy as C, TabAdmission as Cn, PageActionConsent as Ct, DataSourceTransport as D, TabWorksetToolSourceOptions as Dn, PageActionPolicy as Dt, DataSourceRecord as E, TabWorksetPort as En, PageActionOutcome as Et, DocumentFileBytes as F, WorksetTab as Fn, PageActionUi as Ft, DownloadedFileConsent as G, createDownloadedFileToolSource as Gn, PdfTextQuality as Gt, DocxDocumentContent as H, clampWorksetMax as Hn, PdfDocumentHandle as Ht, DocumentFileSource as I, WorksetTabView as In, PageAuditSink as It, DownloadedFilePolicy as J, createPagePerceptionToolSource as Jn, PerceptionAuditSink as Jt, DownloadedFileEntry as K, createHttpDataSourceTransport as Kn, PerceivedImage as Kt, DocumentFormat as L, XlsxDocumentContent as Ln, PagePerceptionPolicy as Lt, DelegationResult as M, TodoStatus as Mn, PageActionScopeInput as Mt, DelegationToolSourceOptions as N, TodoStore as Nn, PageActionTarget as Nt, DelegationBudget as O, TodoEvent as On, PageActionPolicyOptions as Ot, DocumentBlock as P, TodoToolSourceOptions as Pn, PageActionToolSourceOptions as Pt, DownloadedFileRecord as Q, createTodoToolSource as Qn, PerceptionResult as Qt, DocumentImageRole as R, XlsxDocumentReader as Rn, PagePerceptionPolicyOptions as Rt, DataSourceKind as S, TODO_SYSTEM_PROMPT as Sn, PERCEPTION_SYSTEM_PROMPT as St, DataSourceProvenance as T, TabWorksetPolicyOptions as Tn, PageActionKind as Tt, DocxDocumentReader as U, createDelegationToolSource as Un, PdfDocumentReader as Ut, DocumentToolSourceOptions as V, clampDownloadWaitMs as Vn, ParentBudget as Vt, DownloadedFileAction as W, createDocumentToolSource as Wn, PdfPageImage as Wt, DownloadedFileReadResult as X, createSpreadsheetToolSource as Xn, PerceptionPagingBudget as Xt, DownloadedFilePolicyOptions as Y, createSkillGenerationToolSource as Yn, PerceptionCaptureOptions as Yt, DownloadedFileReader as Z, createTabWorksetToolSource as Zn, PerceptionRecord as Zt, DataSourceCandidatePolicy as _, SubtreeRejection as _n, PAGE_DOCUMENT_REF as _t, ActionTabWindow as a, SkillCandidateSink as an, takesImage as ar, GeneratedSkillDraft as at, DataSourceCandidateStore as b, TAB_WORKSET_MIN_MAX as bn, PERCEIVE_PAGE_TOOL as bt, DELEGATE_TASK_TOOL as c, SkillGenerationPolicy as cn, withDelegationOrigin as cr, LIST_DOWNLOADED_FILES_TOOL as ct, DOWNLOAD_WAIT_DEFAULT_MS as d, SkillGeneratorOptions as dn, NestedFrameRef as dt, PerceptionScopeInput as en, frameLabel as er, EXPORT_SPREADSHEET_TOOL as et, DOWNLOAD_WAIT_MAX_MS as f, SkillTraceEvidence as fn, OpenedPageInfo as ft, DataSourceCandidateAuditSink as g, SubAgentRunner as gn, PAGE_ACTION_TOOL as gt, DataSourceCandidate as h, SubAgentRunInput as hn, PAGE_ACTION_SYSTEM_PROMPT as ht, ActionTabWatcher as i, SKILL_GENERATION_SYSTEM_PROMPT as in, sniffDocumentFormat as ir, GENERATE_SKILL_TOOL as it, DelegationRequest as j, TodoListener as jn, PageActionScope as jt, DelegationOrchestrator as k, TodoItem as kn, PageActionRecord as kt, DELEGATION_SYSTEM_PROMPT as l, SkillGenerationToolSourceOptions as ln, LIST_PAGE_TABS_TOOL as lt, DataSourceAuditSink as m, SpreadsheetToolSourceOptions as mn, PAGE_ACTION_KINDS as mt, ActionDownloadWindow as n, READ_DOWNLOADED_FILE_TOOL as nn, isPdfTextTrustworthy as nr, FrameNote as nt, CLOSE_PAGE_TAB_TOOL as o, SkillGenerationMessages as on, toActionFrameScopes as or, HttpDataSourceOptions as ot, DOWNLOAD_WAIT_MIN_MS as p, SkillTraceEvidenceStep as pn, OpenedTabSignal as pt, DownloadedFileListing as q, createPageActionToolSource as qn, PerceivedNode as qt, ActionFrameScope as r, RenderedImage as rn, measurePdfTextQuality as rr, FrameScope as rt, ConsentUi as s, SkillGenerationOutcome as sn, toFrameScopes as sr, ImageCaptureBudget as st, ActionDownloadWatcher as t, READ_DOCUMENT_TOOL as tn, frameSteps as tr, FOCUS_PAGE_TAB_TOOL as tt, DOCUMENT_READ_BUDGET as u, SkillGenerator as un, MANAGE_TODO_TOOL as ut, DataSourceCandidatePolicyOptions as v, TAB_WORKSET_DEFAULT_MAX as vn, PDF_GARBLED_RATIO as vt, DataSourcePolicyOptions as w, TabWorksetPolicy as wn, PageActionExecutor as wt, DataSourceDef as x, TAB_WORKSET_SYSTEM_PROMPT as xn, PERCEPTION_PAGING_DEFAULTS as xt, DataSourceCandidateRecord as y, TAB_WORKSET_MAX_MAX as yn, PDF_LARGE_IMAGE_RATIO as yt, DocumentReadBudget as z, XlsxSheetContent as zn, PagePerceptionReader as zt };
+//#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 $, SkillCandidateSink as $n, createDownloadedFileToolSource as $r, PERCEPTION_PAGING_DEFAULTS as $t, DataSourceRecord as A, PerceptionAuditSink as An, TemplateToolSourceOptions as Ar, FILL_TEMPLATE_TOOL as At, DocumentFileSource as B, READ_DOCUMENT_TOOL as Bn, WorksetTabView as Br, LIST_PAGE_TABS_TOOL as Bt, DataSourceCandidateRecord as C, rangeContains as Ci, ParentBudget as Cn, TemplateCellSkeleton as Cr, DwgView as Ct, DataSourcePolicy as D, toActionFrameScopes as Di, PdfTextQuality as Dn, TemplateParagraphSkeleton as Dr, EMU_PER_TWIP as Dt, DataSourceKind as E, takesImage as Ei, PdfPageImage as En, TemplateImageResolver as Er, EMU_PER_POINT as Et, DelegationRequest as F, PerceptionScope as Fn, TodoStatus as Fr, GeneratedSkillDraft as Ft, DocumentToolSourceOptions as G, RemoteImageToolSourceOptions as Gn, XlsxTemplateFillSpec as Gr, OpenedTabSignal as Gt, DocumentImageRole as H, RemoteImageFetch as Hn, XlsxDocumentReader as Hr, MAX_DIGIT_WIDTH as Ht, DelegationResult as I, PerceptionScopeInput as In, TodoStore as Ir, HttpDataSourceOptions as It, DocxTemplateEngine as J, SKILL_GENERATION_SYSTEM_PROMPT as Jn, clampDownloadWaitMs as Jr, PAGE_ACTION_TOOL as Jt, DocxDocumentContent as K, RenderedImage as Kn, XlsxTemplateSkeleton as Kr, PAGE_ACTION_KINDS as Kt, DelegationToolSourceOptions as L, PptxDocumentContent as Ln, TodoToolSourceOptions as Lr, INSPECT_TEMPLATE_TOOL as Lt, DelegationBudget as M, PerceptionPagingBudget as Mn, TodoItem as Mr, FrameNote as Mt, DelegationOrchestrator as N, PerceptionRecord as Nn, TodoList as Nr, FrameScope as Nt, DataSourcePolicyOptions as O, toFrameScopes as Oi, PerceivedImage as On, TemplateSheetSkeleton as Or, EXPORT_SPREADSHEET_TOOL as Ot, DelegationOrchestratorOptions as P, PerceptionResult as Pn, TodoListener as Pr, GENERATE_SKILL_TOOL as Pt, DownloadedFileConsent as Q, SkillBinaryPayload as Qn, createDocumentToolSource as Qr, PERCEIVE_PAGE_TOOL as Qt, DocumentBlock as R, PptxDocumentReader as Rn, VIEW_DWG_TOOL as Rr, ImageCaptureBudget as Rt, DataSourceCandidatePolicyOptions as S, parseCellRange as Si, PagePerceptionToolSourceOptions as Sn, TabWorksetToolSourceOptions as Sr, DwgUnits as St, DataSourceDef as T, sniffDocumentFormat as Ti, PdfDocumentReader as Tn, TemplateImageBytes as Tr, EMU_PER_PIXEL as Tt, DocumentReadBudget as U, RemoteImageFetchFailure as Un, XlsxSheetContent as Ur, NestedFrameRef as Ut, DocumentFormat as V, READ_DOWNLOADED_FILE_TOOL as Vn, XlsxDocumentContent as Vr, MANAGE_TODO_TOOL as Vt, DocumentReadMode as W, RemoteImageResult as Wn, XlsxTemplateEngine as Wr, OpenedPageInfo as Wt, DocxTemplateSkeleton as X, Size as Xn, columnWidthToPixels as Xr, PDF_GARBLED_RATIO as Xt, DocxTemplateFillSpec as Y, ScrollDirection as Yn, clampWorksetMax as Yr, PAGE_DOCUMENT_REF as Yt, DownloadedFileAction as Z, SkillAttachmentBytes as Zn, createDelegationToolSource as Zr, PDF_LARGE_IMAGE_RATIO as Zt, DWG_MODEL_VIEW_ID as _, frameSteps as _i, PageImageResult as _n, TODO_SYSTEM_PROMPT as _r, DwgOmission as _t, ActionTabWindow as a, createRemoteImageToolSource as ai, PageActionPolicy as an, SkillGeneratorOptions as ar, DownloadedFileRecord as at, DataSourceCandidateAuditSink as b, measurePdfTextQuality as bi, PagePerceptionPolicyOptions as bn, TabWorksetPolicyOptions as br, DwgProjection as bt, CellAddress as c, createTabWorksetToolSource as ci, PageActionRequest as cn, SpreadsheetToolSourceOptions as cr, DwgComponent as ct, DELEGATE_TASK_TOOL as d, defersImage as di, PageActionTarget as dn, SubtreeRejection as dr, DwgEntity as dt, createDwgToolSource as ei, PERCEPTION_SYSTEM_PROMPT as en, SkillGenerationMessages as er, DownloadedFileListing as et, DELEGATION_SYSTEM_PROMPT as f, dwgPickView as fi, PageActionToolSourceOptions as fn, TAB_WORKSET_DEFAULT_MAX as fr, DwgFill as ft, DOWNLOAD_WAIT_MIN_MS as g, frameLabel as gi, PageImageFailure as gn, TEMPLATE_INSPECT_BUDGET as gr, DwgLoadedDrawing as gt, DOWNLOAD_WAIT_MAX_MS as h, formatCellAddress as hi, PageImageCapture as hn, TAB_WORKSET_SYSTEM_PROMPT as hr, DwgLayer as ht, ActionTabWatcher as i, createPagePerceptionToolSource as ii, PageActionOutcome as in, SkillGenerator as ir, DownloadedFileReader as it, DataSourceTransport as j, PerceptionCaptureOptions as jn, TodoEvent as jr, FOCUS_PAGE_TAB_TOOL as jt, DataSourceProvenance as k, withDelegationOrigin as ki, PerceivedNode as kn, TemplateTableCellSkeleton as kr, FETCH_REMOTE_IMAGE_TOOL as kt, CellRange as l, createTemplateToolSource as li, PageActionScope as ln, SubAgentRunInput as lr, DwgDocumentContent as lt, DOWNLOAD_WAIT_DEFAULT_MS as m, fitWithin as mi, PageAuditSink as mn, TAB_WORKSET_MIN_MAX as mr, DwgGeometry as mt, ActionDownloadWindow as n, createPageActionToolSource as ni, PageActionExecutor as nn, SkillGenerationPolicy as nr, DownloadedFilePolicyOptions as nt, CAPTURE_PAGE_IMAGE_TOOL as o, createSkillGenerationToolSource as oi, PageActionPolicyOptions as on, SkillTraceEvidence as or, DownloadedFileToolSourceOptions as ot, DOCUMENT_READ_BUDGET as p, dwgViewsOf as pi, PageActionUi as pn, TAB_WORKSET_MAX_MAX as pr, DwgFont as pt, DocxDocumentReader as q, SCROLL_DIRECTIONS as qn, asReadMode as qr, PAGE_ACTION_SYSTEM_PROMPT as qt, ActionFrameScope as r, createPageImageToolSource as ri, PageActionKind as rn, SkillGenerationToolSourceOptions as rr, DownloadedFileReadResult as rt, CLOSE_PAGE_TAB_TOOL as s, createSpreadsheetToolSource as si, PageActionRecord as sn, SkillTraceEvidenceStep as sr, DwgBounds as st, ActionDownloadWatcher as t, createHttpDataSourceTransport as ti, PageActionConsent as tn, SkillGenerationOutcome as tr, DownloadedFilePolicy as tt, ConsentUi as u, createTodoToolSource as ui, PageActionScopeInput as un, SubAgentRunner as ur, DwgDocumentReader as ut, DataSourceAuditSink as v, isPdfTextTrustworthy as vi, PageImageToolSourceOptions as vn, TabAdmission as vr, DwgPoint as vt, DataSourceCandidateStore as w, readImageSize as wi, PdfDocumentHandle as wn, TemplateFileSource as wr, DwgViewport as wt, DataSourceCandidatePolicy as x, parseCellAddress as xi, PagePerceptionReader as xn, TabWorksetPort as xr, DwgToolSourceOptions as xt, DataSourceCandidate as y, isRangeTopLeft as yi, PagePerceptionPolicy as yn, TabWorksetPolicy as yr, DwgProjectedDrawing as yt, DocumentFileBytes as z, PptxSlideContent as zn, WorksetTab as zr, LIST_DOWNLOADED_FILES_TOOL as zt };