Generated by Answer me with HTML 0.5.10 · 2026-11-05 21:45 · ★ Star on GitHub

视觉搜索抓取与来源展示:全栈技术方案

从创建任务到结果页与导出,贯通取数、执行、存储和展示。

A

1. 目标与改动

让视觉搜索结果页完整展示所选历史消息的 Prompt、拆 Query 和历史对话。 一份任务共享历史来源,各环境分别保存本次检索结果。 列表导出补齐三个来源字段,飞书历史统一使用 JSON 下载链接。

环节 改造前 改造后
历史取数 会话查询后直接构造图搜输入 增加消息明细查询,补充三个来源字段
任务数据 保留原有图搜输入和框坐标 在任务 penetrate 中增加 visual_search_source
结果页 从各环境产物读取,来源不统一 视觉环境统一读取任务级来源
抓取执行 按图片和选框调用目标环境工具 延续原执行输入,新增字段用于来源展示
列表导出 未提供三个来源字段的独立导出列 CSV 保留 JSON;飞书历史统一转 TOS 链接
B

2. 从提交到展示的完整链路

项目与来源参数query、图片、坐标enc_message_id三个来源字段来源与各环境结果创建页Admin创建入口历史会话查询有效图搜输入历史消息明细查询任务元信息Crawl抓取服务环境A工具环境B工具环境A产物环境B产物TOS环境结果任务详情接口结果页
页面阶段 HTTP 接口 职责
创建项目 POST /admin/label/biz/add_evaluate_project/ 保存来源和环境配置,取得 evaluate_id
提交任务 POST /admin/label/biz/create_tasks/ 按来源参数启动取数和题目创建
查看结果 GET /admin/label/get_evaluate_task_by_env/ 返回任务元信息和环境产物

图中展示数据依赖,不表示 HTTP 请求会等待全部抓取完成。

C

3. 后端:Ekko 历史取数的两个 API

两个 API 都通过 dp.invoker.engine 的 QueryWithParams 调用。 API ID 是数据接口标识,下面分别简称“会话 API”和“明细 API”。

接口 API ID 输入 返回及用途
历史会话查询 7389155172762600485 日期、数量和来源配置;指定会话时带 session_id_list 会话与 enc_message_str_list;从消息 JSON 取得 enc_message_id、query、图片和坐标
历史消息明细查询 7387617535350391817 enc_message_id_list、日期及来源配置 当前消息的明细;取 image_prompt_info、search_query_list、history_5_rounds

明细请求使用会话消息里的 enc_message_id。 不是根据 Query 文本重新搜索一条消息。 两个接口的 resp.Data 都是 JSON 字符串,先解码成记录数组。

Admin 先完成现有图片筛选,再为有效输入逐条查询明细。 明细必须只返回一条记录,且 enc_message_id 与请求一致。

数据名称 来自哪里 在本链路中的用途
GQuery.QueryMulti → TaskInfo.QueryList 会话消息里的 query 构造本次执行输入
visual_search_source.search_query_list 明细 API 展示历史拆 Query
crawl_result[i].query_list 目标工具返回的 documents 展示本次环境检索结果
搜索结果在哪里产生

会话 API 和明细 API 用于取历史数据。 Crawl 随后调用目标环境的视觉搜索工具,得到本次 documents。 当前 MCP 请求使用图片和选框,按原规则合并环境参数。 history_5_rounds 可包含历史回答和引用,但不作为本次工具结果。

D

4. 数据契约与产物归属

来源先写入 QueryInfo.Penetrate,随题目创建保存。 Legacy 路径保存到任务 Extra;Biz 路径保存到 PenetrateJSON。 任务详情统一返回 data.task.penetrate,类型仍是 JSON 字符串。

以下层级表示 JSON.parse(data.task.penetrate) 的结果。

任务 penetrate 对象
b_box两位小数的坐标文本
visual_search_source每题共享一份
  • image_prompt_info对象或 null
    • queryJSON 字符串,内容是 block 数组
    • ImageUrl历史输入图片地址
  • search_query_list字符串数组或 null
  • history_5_rounds消息数组或 null
    • 每条消息
      • enc_message_id消息标识
      • user_type1 为用户,2 为助手
      • content_type当前 block 消息为 9999
      • message_contentJSON 字符串,内容是 block 数组
数据 保存与返回方式 前端读取位置
历史来源 创建题目时保存,不依赖抓取结果回传 JSON.parse(data.task.penetrate).visual_search_source
框坐标 保留任务级 b_box JSON.parse(data.task.penetrate).b_box
环境检索结果 工具响应形成产物,沿现有链路保存到 TOS 当前环境的 crawlResult

现有产物补充逻辑还会复制任务 penetrate,并平铺其中的字段。 因此 crawl_result[i].penetrate 和 crawl_result[i].visual_search_source 可能出现副本。 来源展示只读任务级字段,不在副本之间寻找或合并数据。

来源 JSON 的保存与复制,不等于转存其中的图片或附件。 本次来源透传没有增加对这些资源的逐项下载和转存。

E

5. 前端:只改视觉环境的来源展示

生效条件是当前环境 search_config.identity === "visual"。 同题保留各环境分栏;多个视觉环境展示同一份来源。 其他环境继续走既有取值和渲染路径。

下表中的 source 指任务级 visual_search_source。

展示区域 取值 渲染方式
Prompt 正文 source.image_prompt_info.query 解析 block,复用现有渲染能力
Prompt 图片 source.image_prompt_info.ImageUrl 展示图片,沿用选框绘制
框坐标文本 task penetrate.b_box 直接展示,不从浮点坐标重新拼接
Query source.search_query_list 按原顺序展示;空值保留标题、正文留白
历史对话 source.history_5_rounds 按角色和顺序复用 ChatCore 与 block 渲染
图片参考信息 当前环境 crawlResult 继续展示本次环境的检索结果

来源适配函数统一解析字段,组件消费适配结果。 历史保留连续用户消息,不转换成 req/res 配对结构。 历史消息显示轮次;没有可复制文本时不展示复制按钮。 历史内容使用 render 回调,普通刷新保留内部展开状态。

F

6. 关键设计与异常边界

设计 处理方式 原因
任务级保存来源 一题一份,多个视觉环境共享 来源属于所选历史消息,环境结果属于本次执行
保持执行输入 仍由会话 API 的消息构造 本次补齐展示数据,不替换图搜输入
历史上下文 history_5_rounds 用于来源展示与导出 本期不把历史消息附加到搜索工具请求
后端 JSON 边界 三字段分别解开外层 JSON 编码 query 和 message_content 留给前端按 block 解析
单字段异常 该字段返回 null,保留其余字段 展示信息异常不阻断已有有效输入抓取
整份明细不可用 查询失败、数量或消息 ID 不符时,三字段为 null 不挂载身份不明的消息明细

后端是否取明细,由来源 Handler 决定。 当前分支要求 DouBaoSessionHandler 命中 doubao_visual_search 前缀。 前端是否展示来源,由环境 identity 决定。 两处条件分别控制取数与展示,不能互相替代。

日志以 stage=source_info 记录三字段状态和字节数。 stage=visual_input_ready 记录来源数、产出数和跳过数。 完整透传值从任务详情响应查看。

G

7. 抓取列表导出:字段配置与文件转存

当前导出规则

导出读取任务已保存的三个来源字段。 飞书中的 history_5_rounds 有值就转为 JSON 文件下载链接。 短历史、长历史和空数组 [] 使用同一规则。 CSV 始终保留完整 JSON,任务详情中的来源结构保持不变。 本节以 Admin 提交 f4140a04f 为准。

GET export/conf_listenameGET download_query_file_v2三字段的JSON文本保留原始字段值history_5_rounds有值下载链接其余两列保留JSON文本抓取列表导出字段配置勾选字段创建导出记录任务来源数据基础导出引擎CSV文件飞书单元格转换TOS历史JSON文件飞书历史单元格飞书其他来源单元格

页面与导出接口

接口 作用 关键参数或返回
GET /admin/label/export/conf_list 动态加载可选字段 ConfList 中的 EName、DataIdx、EngineName
GET /admin/label/download_query_file_v2/ 创建后台导出记录 evaluate_id、export_key_list、request_id、record_export=1
GET /admin/label/crawl_export/list/ 查询项目导出记录 evaluate_id、page、page_size
GET /admin/label/crawl_export/detail/ 查询一条导出进度和结果 export_job_id;成功后返回 result_url

export_key_list 是 ename 数组的 JSON 字符串。 CSV 使用 file_type_v2=0、output_format=csv。 飞书表格使用 file_type_v2=1、output_format=lark_bitable。 导出范围沿用当前的勾选题目、筛选条件和项目全量逻辑。

三个字段从哪里读取

Exporter 将任务 Extra.Penetrate 解析成 task_info_penetrate。 Biz 任务经现有投影后使用同一导出结构。 导出不重新调用会话 API 或明细 API。

ename 完整 data_idx
image_prompt_info task_info_penetrate.visual_search_source.image_prompt_info
history_5_rounds task_info_penetrate.visual_search_source.history_5_rounds
search_query_list task_info_penetrate.visual_search_source.search_query_list

三个配置项统一使用 engine_name=BaseExportEngine。 前端根据配置生成选项,不为三个字段新增顶层请求参数。

TCC 配置

在现有 conf_list 中追加三个对象,保留已有配置。 已有同名 ename 时更新原项,避免重复。 下面是 history_5_rounds 的配置示例。 其余两项按上表替换 ename、header_name 和 data_idx。

history_5_rounds 导出配置示例json
{  "ename": "history_5_rounds",  "header_name": "history_5_rounds",  "data_idx": "task_info_penetrate.visual_search_source.history_5_rounds",  "engine_name": "BaseExportEngine",  "classification_v2": "base_info",  "active_app_list": ["65766316"],  "no_need_export": false}
国内 AIDP 环境 TCC key
PPE 8875_export_ppe_v2_aidp
线上 8875_export_v2_aidp

后端先判断 AIDP 流量,再按运行环境选择配置。 active_app_list 与项目应用取交集,控制导出时是否生效。 该配置不负责在其他项目的导出弹窗中隐藏选项。

CSV 与飞书的内容契约

字段或情况 CSV 飞书表格
image_prompt_info 完整 JSON 文本 完整 JSON 文本
search_query_list 完整 JSON 文本 完整 JSON 文本
history_5_rounds 有值 完整 JSON 文本 完整 JSON 文件的 TOS 下载链接
history_5_rounds 为 [] 保留 [] 下载内容为 [] 的 JSON 文件
来源缺失、null 或空白 空值或空白 单元格留空,不上传 TOS

飞书中的历史列仍是文本字段,内容为下载 URL。 它不是飞书附件列,不需要改成附件类型。 旧任务没有来源值时,导出不会补查或自动回填。

JSON 文件如何转存

  1. 在飞书单元格构建阶段匹配完整 history 字段路径。
  2. 校验导出字符串是合法 JSON。
  3. 对完整字符串计算 SHA-256。
  4. 将完整字符串写入现有 TOS。
  5. 将下载 URL 写入飞书记录,保留导出数据原文。
历史 JSON 文件路径text
crawl_exports/<projectId>/history_5_rounds/<sha256>.json

上传设置 application/json; charset=utf-8。 Content-Disposition 指定下载文件名 history_5_rounds.json。 当前导出 Handler 缓存内容哈希与下载 URL。 同一 Handler 内的重复历史复用链接,不重复上传。 跨次导出使用稳定路径,不代表存在全局上传缓存。

“保留原文”指转存前的导出单元格字符串。 转存时不重排 JSON,不解析 message_content 内层字符串。 前面的任务解析已发生 JSON 解码与序列化。 因此不承诺与最初 Ekko 响应的空格和键顺序逐字节一致。

转存的对象只有历史 JSON 文件。 其中的图片 URL、引用和附件地址保持原值,不逐项下载资源。 CSV 写入不经过飞书单元格转换,不会被替换成链接。

异常、部署与复测

情况 行为或检查点
JSON 非法或 TOS 上传失败 返回错误;不写无效链接,不静默截断
实时同步转存失败 记录临时错误,保留游标供下次重试
PPE 配置已有新列,执行端没有对应列 核对执行日志中的 env、cluster 和实际加载的 TCC
仅部署 default 集群 还需确认对应 PPE 环境的 file 集群有可用实例
已经生成的飞书表格混有 JSON 和链接 部署新版本后重新导出;旧表格不会自动改写

单元格转换由普通导出和分批导出共用。 此前 TooLargeCell 的批次减半重试,不能解决单条历史过大。 当前历史列统一转为链接,不再依赖长度阈值。 image_prompt_info 和 search_query_list 保持现有文本规则。

H

8. 代码入口与验收

责任 代码入口
导出字段与 TCC 加载 Admin:ExportConfList、NewExportConfV2Aidp
后台导出记录与执行 Admin:createCrawlExportRecord、ExporterHandlerV2
历史 JSON 文件与飞书单元格 Admin:uploadBitableHistoryJSON、bitableCellValue
导出字段选择与 record-mode 请求 前端:useNewExportActions、createCrawlExportRecord
来源路由、会话查询及图搜输入 Admin:gpt_douyin_session.go
明细查询、身份核对、字段归一化 Admin:visual_search_session_detail.go
Query 转换与任务保存 Admin:CustomizeQueryList
工具请求和环境产物 Crawl:McpVisualSearch
视觉环境分支 前端:Search
来源适配与 block 展示 前端:visual-search-source.ts、VisualSourceContent.tsx
验收场景 预期
同题两个视觉环境与普通环境混排 视觉来源一致,各环境结果独立;普通环境保持原取值
对照明细 API 和任务详情 三字段对应同一条消息,JSON 类型与内容可追溯
图片消息、连续用户消息、带引用回答 顺序、角色和已有 block 内容正确展示
明细失败或单字段异常 有效抓取输入保留;来源字段按上述规则返回
Query 为空、折叠后刷新 Query 标题保留;历史展开状态不被普通刷新重置
三字段 CSV 导出 解析 CSV 后与任务来源 JSON 的值一致
飞书导出短历史、长历史及 [] 历史列全部为链接;下载 JSON 与导出值一致
缺失来源与重复历史 缺失值留空;同次导出重复历史复用链接
转存失败与实时同步 导出返回错误;实时游标不推进
PPE file 集群与字段配置 实际执行环境、集群和 TCC 与预期一致

前端实现已提交:8d53c03c,分支为 codex/visual-search-source-display。 已有 PPE 样本验证的是 Legacy 自动取数入口。 Biz 创建入口还需核对最终来源 Handler,并完成部署后的端到端验收。 旧任务不会自动补齐新增来源字段。

Admin 导出实现已推送:f4140a04f,分支为 codex/visual-search-two-stage-fetch。 格式和静态检查已通过,新增 Go 用例未在本地执行。 统一 TOS 规则需部署后重新导出验收,不代表已有表格已更新。