# 图纸检索返回对象

以下按服务端 JSON 对象展开，不以当前Go SDK较窄类型代替。标注可省略字段时，保留null与空数组的区别。

## DrawingSearchResponse

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `drawings` | object[] | 按来源聚合的返回列表，空结果[]。 |
| `count` | integer | 本次返回条数，无分页总数含义。 |
| `match_mode` | string | exact/semantic，部分早期空结果可省略。 空值时可省略。 |
| `diagnostics` | object | |

## DrawingSearchResult

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `source_file_id` | string | 来源文件标识，用于聚合与溯源。 |
| `drawing_number` | string | 业务图号，精确模式返回时与drawing_id分开。 空值时可省略。 |
| `drawing_id` | string | CAD/图纸标识，可能回退为来源ID，不用它替代source_file_id。 |
| `score` | number | 当次排序得分，不保证跨模式/通道等价或代表概率。 |
| `best_hit` | object | 最佳命中；使用下表命中对象。 |
| `supporting_hits` | object[]或null | 补充命中，语义最多3条；精确结果可能为null，语义无补充时[]。 |
| `external_source_uri` | string 或 null | 来源 URI。未加载来源信息时省略；已加载但没有 URI 时为 null。 |
| `visual_manifest_file_id` | string 或 null | 清单 ID。未加载来源信息时省略；已加载但没有清单时为 null。 |
| `provenance_status` | string | 已加载来源时的ready或legacy_unmigrated。 空值时可省略。 |
| `gaps` | string[]或 null | 缺口列表，含义见来源对象。未加载时省略；已加载且无缺口时，当前实现可返回 null。 |
| `pages` | object[]或 null | 完整页面列表。未加载时省略；已加载且没有页面时，当前实现可返回 null。 |
| `default_version` | boolean | 仅 true 标记 keep_versions 结果中的当前版本；false 时省略。不能由字段省略推断知识库没有当前版本。 |

## DrawingSearchHit

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object_id` | string | 召回对象ID。 空值时可省略。 |
| `object_kind` | string | 对象类别。 空值时可省略。 |
| `retrieval_level` | string | 召回层级，如整页/区域，按返回值处理。 空值时可省略。 |
| `retrieval_channel` | string | 召回通道标识。 空值时可省略。 |
| `retrieval_scope` | string | 召回范围标记。 空值时可省略。 |
| `source_file_id` | string | 来源文件标识，用于聚合与溯源。 |
| `drawing_id` | string | CAD/图纸标识，可能回退为来源ID，不用它替代source_file_id。 空值时可省略。 |
| `image_file_id` | string | 局部或对象图片ID。 空值时可省略。 |
| `page_image_file_id` | string | 已登记的页面图片文件ID。 空值时可省略。 |
| `page_number` | integer | 关联正页码。 空值时可省略。 |
| `bbox` | number[] | 边界框坐标，结合coordinate_space解释，不假定总是归一化。 空值时可省略。 |
| `score` | number | 当次排序得分，不保证跨模式/通道等价或代表概率。 |
| `content` | string | 命中内容。 空值时可省略。 |
| `modality` | string | 命中模态。 空值时可省略。 |
| `reason` | string | 命中理由标记。 空值时可省略。 |
| `channel` | string | 命中通道。 空值时可省略。 |
| `text_id` | string | 文本证据ID。 空值时可省略。 |
| `text_kind` | string | 文本种类，如dimension/technical_requirement。 空值时可省略。 |
| `canonical_text` | string | 规范化证据文本。 空值时可省略。 |
| `recognition_status` | string | 识别状态，按返回值判断，不由缺少推recognized。 空值时可省略。 |
| `status_reasons` | string[] | 识别状态的原因标记。 空值时可省略。 |
| `coordinate_space` | string | 坐标空间，如source_page_px。 空值时可省略。 |
| `source_refs` | object[] | 可回查OCR/VLM来源指针对象。 空值时可省略。 |
| `structured_refs` | string[] | 关联结构化记录标识。 空值时可省略。 |
| `dimension_candidate` | object | 提取的尺寸观察候选，不等于已核准工程事实。 空值时可省略。 |

## DrawingSearchSourceRef

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `artifact` | string | 来源产物标识。 空值时可省略。 |
| `json_pointer` | string | 产物内JSON Pointer。 空值时可省略。 |
| `method` | string | 提取方式，如crop_ocr。 空值时可省略。 |

## DrawingSearchDimensionCandidate

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text_id` | string | 文本证据ID。 空值时可省略。 |
| `region_id` | string | 关联区域ID。 空值时可省略。 |
| `attr_label` | string | 属性名称。 空值时可省略。 |
| `geometry_role` | string | 几何角色标记。 空值时可省略。 |
| `nominal` | number | 候选名义数值。未设置时省略，0 也是有效返回值。 |
| `tol_text` | string | 原始公差文本。 空值时可省略。 |
| `value_min` | number | 候选下界。未设置时省略，0 也是有效返回值。 |
| `value_max` | number | 候选上界。未设置时省略，0 也是有效返回值。 |
| `unit` | string | 候选单位。 空值时可省略。 |
| `raw_text` | string | 原始尺寸文本。 空值时可省略。 |
| `authority` | string | 提取权威/候选标记，仍需结合来源核对。 空值时可省略。 |

## DrawingSearchPage

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `page_number` | integer | 关联正页码。 |
| `page_image_file_id` | string | 已登记的页面图片文件ID。 |
| `preview_url` | string | 受鉴权的同环境相对API路径。 |

## DrawingSearchDiagnostics

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `total_ms` | integer | |
| `plan_ms` | integer | |
| `embed_ms` | integer | 空值时可省略。 |
| `text_retrieve_ms` | integer | 空值时可省略。 |
| `image_retrieve_ms` | integer | 空值时可省略。 |
| `merge_ms` | integer | |
| `aggregate_ms` | integer | |
| `channels` | string[] | |
| `candidate_hit_count` | integer | 合并候选命中数。 |
| `unique_drawing_count` | integer | 候选中的不同来源图纸数，不是全库总数。 |
| `result_count` | integer | 本次结果数量。 |
| `identifier_route_used` | boolean | 是否尝试编号相关召回，不等于exact模式。 |
| `extracted_identifiers` | string[] | 从query提取的编号提示。 空值时可省略。 |
| `identifier_hit_count` | integer | 编号相关命中数。 |
| `identifier_filename_hit_count` | integer | 文件名编号命中数。 |
| `identifier_l1_hit_count` | integer | 文本层编号命中数。 |
| `vector_hit_count` | integer | 向量相关命中计数。 |

检索附加来源对象会复制gaps/pages，空slice可编码为null；它们不是独立溯源对象返回的[]。CLI还可能进一步省略。不要把null、[]和未返回合并解释。
