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

视觉搜索后端改动:从前端视角逐步读懂

以 f4140a04f 为准,逐步解释取数、保存、导出、错误和测试。

A

1. 先看目标,再跟着一道题走

这次没有重写整个抓取服务。 业务变化集中在两件事:补齐历史来源,以及导出来源。 原有图片、Query 和 ROI 继续用于本次视觉搜索。

原来的能力 这次补充
485 查询会话,得到图搜输入 用消息 ID 再查 817,补三个来源字段
任务已有 penetrate 扩展信息 在其中增加 visual_search_source
导出引擎可以按路径读取字段 TCC 配置三个新导出列
飞书把普通字符串写进单元格 history_5_rounds 统一转存 JSON,单元格放链接
实时同步会更新处理游标 转存失败时返回错误,保留游标

先用一道示例题贯穿阅读。 消息 ID 为 m-demo,Query 为“这是什么猫?”。 图片 URL 为 https://example.invalid/cat.jpg,ROI 是用户选框。 这些值只用于讲解,不是真实用户数据。

Query、图片、ROI、消息IDm-demo原有输入继续执行三字段完整JSON保存到TOS下载链接485会话接口图搜输入817明细接口三个历史来源字段本次视觉搜索任务penetrate结果页来源展示CSV飞书导出历史JSON文件飞书历史列

三个字段分别装什么

字段 可以先这样理解 本次后端保证的顶层类型
image_prompt_info 历史 Prompt 与图片来源信息 JSON 对象或 null
search_query_list 历史拆 Query 信息 JSON 数组或 null
history_5_rounds 历史消息列表 JSON 数组或 null

后端在这里校验顶层对象和数组。 它没有逐项验证数组元素的业务结构。 历史消息里的 message_content 仍可保留为 JSON 字符串。

先分清三类东西

“抓取输入”用于调用目标工具。 “历史来源”用于解释这道题从哪里来。 “环境结果”是本次调用目标工具后得到的结果。 这次增加的三个字段属于历史来源。

B

2. 用 TypeScript 经验读 Go

先掌握下面这些写法,就能开始阅读此次代码。 表中的 TypeScript 是概念类比,不是逐字翻译。

Go 写法 含义 前端类比
package service 当前文件所属的包 所属模块
import (...) 引入标准库或依赖包 import 依赖
type X struct {...} 定义有固定字段的数据结构 先类比 interface 描述字段
[]X X 类型的切片 可以先类比 X[]
map[string]interface{} 字符串键、不同类型的值 Record<string, unknown>
x := value 声明变量并推断类型,之后可以重新赋值 let x = value
var x X 先声明一个 X,初始是零值 明确类型后等待赋值
nil 指针、切片、map 等的空值 先类比 null
&value 取得 value 的地址 把可被写入的目标交给函数
*p 读取指针指向的值 读取引用中的实际对象
if err != nil 检查函数返回的错误 检查失败结果,而不是依赖 catch
value, err := fn() 接收函数的两个返回值 接收 result 和 error
return value, nil 返回结果,表示没有错误 返回成功结果
defer fn() 当前函数退出前执行 类似 finally 的收尾职责

Go 的普通函数可以返回多个值。 JSON 解码、RPC 和存储请求通常都显式返回 error。 调用方需要处理或继续传递这个错误。

struct 类型在 Go 运行时仍有意义。 X{} 才是在创建一个 X 类型的值。 TypeScript 的 interface 在编译后会被移除。

for index, item := range list 用来遍历切片。 continue 跳到下一轮,append 则向切片追加元素。 看到这些写法时,可以先联系前端的循环和数组操作。

方法声明怎么读

service/visual_search_session_detail.go:20-23go
func (handler *DouBaoSessionHandler) fetchVisualSearchSourceInfo(c *context.Context, sessionIndex int, messageID string) *visualSearchSourceInfo {	info := &visualSearchSourceInfo{}	status := "ok"	imageState, searchState, historyState := "unavailable", "unavailable", "unavailable"
这一段 含义
handler *DouBaoSessionHandler 这是 DouBaoSessionHandler 的实例方法
handler 在函数内访问当前实例,作用接近 this
c *context.Context 沿用现有代码的 Context 指针参数
sessionIndex int 这条会话在本批数据中的位置,用于日志
messageID string 向 817 查询的消息标识
*visualSearchSourceInfo 返回来源结构的指针

Context 可以先类比携带 AbortSignal 的请求上下文。 它还可以携带链路标识、截止时间和其他请求信息。 这里的 *context.Context 是旧调用约定,本次没有重构它。

info := &visualSearchSourceInfo{} 创建结构并取得指针。 这个 info 从函数开始就存在。 失败时也能返回它,三个字段随后序列化为 null。

两个 JSON 函数

json.Marshal 把 Go 值编码成 JSON 字节。 它的职责接近 JSON.stringify。 json.Unmarshal 把 JSON 字节填入 Go 变量。 它的职责接近 JSON.parse,再加上目标类型约束。

Unmarshal 需要 &details,是因为它要写入 details。 字段后的 json 标签规定 JSON 名称。 Go 字段名 ImagePromptInfo 对应 JSON 名 image_prompt_info。

C

3. 第一处接入:什么时候去查 817

阅读入口是 formatVisualSearchData。 它所在的文件原来就有视觉搜索输入构造逻辑。 来源配置命中 doubao_visual_search 前缀时,使用这条路径。

步骤 原有还是新增 作用
检查会话只有一条消息 原有 沿用当前图搜样本限制
解码会话中的消息 JSON 原有 得到 Query、图片和消息 ID
没有图片就跳过 原有 不构造无图输入
miniSizeUrl 处理图片 原有 生成现有执行链需要的图片 URL
fetchVisualSearchSourceInfo 新增 查询三个历史来源字段
构造 GQuery 原有 继续使用会话消息里的图搜输入
把来源放进 penetrateMap 新增 随题目保存,而不是混进执行 Prompt

新增调用的位置

service/gpt_douyin_session.go:1003-1010go
			tmpUrl, miniSizeErr := miniSizeUrl(*c, messageTmp.ImageUrl)			if miniSizeErr != nil {				logs.CtxError(*c, "method[formatData] miniSizeUrl fail, err: %v", miniSizeErr)				continue			}			// 图片有效后再查询展示信息,避免无效图片产生额外请求。			sourceInfo := handler.fetchVisualSearchSourceInfo(c, sessionIndex, messageTmp.EncMessageID)

图片处理失败时,continue 跳过当前记录。 这条记录本来就无法形成有效图搜输入。 因此先处理图片,再查询展示信息。

参数 messageTmp.EncMessageID 来自 485 返回的那条消息。 它不是项目 ID,也不是根据 Query 文本猜出来的 ID。 sessionIndex 只用于定位批内位置。 调用参数 []string{messageID} 是一个只装着当前 ID 的切片。

485 与 817 是已有的 RPC 方法

RPC 可以先理解为后端调用另一个后端服务。 这里通过 dp.invoker.engine.QueryWithParams 调用数据平台。 API ID 用来标识数据平台的某个接口。

方法 API ID 本次的用途
getDouBaoSessionRPC 7389155172762600485 继续取得会话及原图搜输入
getDouBaoMessageInfoRPC 7387617535350391817 复用已有方法,按消息 ID 补来源

这两个 RPC 方法不是此次新写的。 新增的是图搜格式化过程中的 817 调用点。 每个有效图搜输入会串行查询一次明细。

保留原输入的具体含义

即使 817 里的 Prompt 或图片与 485 不同, GQuery 仍使用原会话的 Query、图片和 ROI。 817 返回的数据单独放到来源信息里。 本次没有把历史五轮对话追加到工具请求。

另一个删除项是 messageIdList。 旧代码只向它追加 ID,后面没有读取或使用它。 删除这段不会改变用户消息过滤规则。

D

4. 新文件:怎样解析明细、校验身份和处理失败

这个文件主要包含一个结构和两个函数。 按下面的顺序读即可。

D.1 定义要保留的三个字段

service/visual_search_session_detail.go:11-18go
const visualSearchSourcePenetrateKey = "visual_search_source"// 历史来源信息由所有抓取环境共享,字段异常返回 null,不阻断抓取。type visualSearchSourceInfo struct {	ImagePromptInfo json.RawMessage `json:"image_prompt_info"`	SearchQueryList json.RawMessage `json:"search_query_list"`	History5Rounds  json.RawMessage `json:"history_5_rounds"`}

json.RawMessage 是一段保留着 JSON 格式的字节。 这里暂时不把图片信息和历史消息拆成更多 Go 类型。 这样可以保留内层业务字符串和未知子字段。

它不是把数组变成字符串的特殊开关。 合法数组的 RawMessage 序列化后仍是 JSON 数组。 nil 的 RawMessage 序列化后是 null。

D.2 查询明细,然后核对“是不是这道题”

service/visual_search_session_detail.go:34-66go
	if messageID == "" {		status = "missing_message_id"		return info	}	resp, err := handler.getDouBaoMessageInfoRPC(c, []string{messageID})	if err != nil || resp == nil {		status = "rpc_failed"		return info	}	var details []struct {		EncMessageID string `json:"enc_message_id"`		visualSearchSourceInfo	}	if err := json.Unmarshal([]byte(resp.Data), &details); err != nil {		status = "invalid_response_json"		return info	}	// 只接收当前消息的明细,避免串题。	if len(details) != 1 {		status = "detail_count_mismatch"		return info	}	if details[0].EncMessageID != messageID {		status = "message_id_mismatch"		return info	}	info.ImagePromptInfo, imageState = normalizeVisualSearchSourceField(details[0].ImagePromptInfo, '{')	info.SearchQueryList, searchState = normalizeVisualSearchSourceField(details[0].SearchQueryList, '[')	info.History5Rounds, historyState = normalizeVisualSearchSourceField(details[0].History5Rounds, '[')	if imageState == "invalid" || searchState == "invalid" || historyState == "invalid" {		status = "partial"	}	return info
代码分支 为什么需要 结果
messageID 为空 没有可靠查询条件 不请求 817,返回空来源结构
RPC 失败或响应为空 下游没有可用结果 保留原图搜输入,来源为 null
resp.Data 不能解码 外部响应不是预期 JSON 不把坏数据挂到任务上
details 数量不是 1 这次只请求了一条消息 不随意选第一条
返回 ID 与请求不同 避免把别的消息挂到这道题 返回空来源结构
三字段归一化 每个字段有自己的类型约束 独立保留有效字段

var details []struct 表示临时定义一种数组元素结构。 其中 EncMessageID 与匿名嵌入的 visualSearchSourceInfo 并列。 JSON 解码时,三个来源字段与 enc_message_id 位于同一层。 这里没有增加 sourceInfo 之类的响应包装层。

D.3 为什么有时要解两次 JSON

先看示例中的 history_5_rounds。 817 的 Data 本身是 JSON 字符串。 其中的某个字段还可能是“装着数组 JSON 的字符串”。

817 Data 解码后的一条示例记录json
{  "enc_message_id": "m-demo",  "image_prompt_info": "{\"query\":\"这是什么猫?\"}",  "search_query_list": ["橘猫"],  "history_5_rounds": "[{\"message_content\":\"历史问题\"}]"}

第一次解码处理 Data,得到记录数组。 字段归一化再解开 image_prompt_info 和 history_5_rounds 的外层引号。 已经是原生对象或数组的字段不需要再解一次字符串。

service/visual_search_session_detail.go:70-92go
func normalizeVisualSearchSourceField(value json.RawMessage, kind byte) (json.RawMessage, string) {	value = bytes.TrimSpace(value)	if len(value) == 0 {		return nil, "missing"	}	if value[0] == '"' {		var encoded string		if err := json.Unmarshal(value, &encoded); err != nil {			return nil, "invalid"		}		value = bytes.TrimSpace([]byte(encoded))	}	if len(value) == 0 || bytes.Equal(value, []byte("null")) {		return nil, "null"	}	if !json.Valid(value) || value[0] != kind {		return nil, "invalid"	}	if kind == '{' {		return value, "object"	}	return value, "array"}
顺序 操作 可以理解为
1 TrimSpace 去掉 JSON 片段前后的空白
2 检查长度 缺失字段直接记为 missing
3 首字符是双引号时解码字符串 去掉外层 JSON 字符串编码
4 处理空值和 null 统一为不可用字段
5 json.Valid 校验解码后的片段仍是合法 JSON
6 检查首字符是对象还是数组 image 要求对象,其余两项要求数组
7 返回片段和状态 调用方同时拿到值与诊断信息

kind 参数中的 '{' 和 '[' 是字节字面量。 它们分别代表预期的对象和数组开头。 代码先确认非空,再读取 value[0]。 这里的顺序避免了空切片访问越界。

这个函数只解开字段的外层编码。 历史消息里的 message_content 如果仍是字符串,就继续保留。 它没有递归解析 block,也没有检查数组每一项的角色字段。

D.4 失败为什么不会把整个抓取任务停掉

原有图片、Query 和 ROI 已经形成有效执行输入。 这三个新增字段用于来源展示与导出。 因此此次约定允许来源不可用,同时继续创建原输入。

故障范围 最终来源
817 整体失败或消息身份不符 三字段都是 null
仅 search_query_list 类型错误 这一项为 null,其余有效字段保留
history_5_rounds 返回 [] 保留 [],不当作缺失

这里是明确约定的降级,不是把抓取执行错误都忽略。 原有取数、图片和工具执行仍有各自的失败处理。

D.5 defer 日志在哪里执行

service/visual_search_session_detail.go:24-32go
	defer func() {		log := logs.CtxInfo		if status != "ok" {			log = logs.CtxWarn		}		log(*c, "[visual_search_fetch] stage=source_info project_id=%d session_pos=%d status=%s image_prompt_info=%s image_prompt_info_bytes=%d search_query_list=%s search_query_list_bytes=%d history_5_rounds=%s history_5_rounds_bytes=%d",			handler.ProjectID, sessionIndex, status,			imageState, len(info.ImagePromptInfo), searchState, len(info.SearchQueryList), historyState, len(info.History5Rounds))	}()

defer 的闭包在函数退出前执行。 即使前面已经 return,也会打印这一次摘要。 闭包读取退出时最终的 status 和字段状态。 func() { ... } 定义匿名函数,末尾的 () 表示调用。 加上 defer 后,这次调用被安排在当前函数退出前执行。

例如 search_query_list 无效时,status 变为 partial。 日志使用 Warn,并记录三个字段的状态和字节数。 没有把完整历史正文放进这条日志。 len(RawMessage) 统计字节数,这里只是日志,不是导出长度限制。

E

5. 数据怎样保存,前端和导出又怎样读到

理解这一节时,先把 Query 与 Penetrate 分开。 它们都在 QueryInfo 中,但职责不同。

位置 内容 用途
QueryInfo.Query 原有 QueryFile 编码后的字符串 继续构造执行输入
QueryInfo.Penetrate bbox 与 visual_search_source 编码后的字符串 保存来源扩展信息

E.1 将来源挂到现有扩展信息

service/gpt_douyin_session.go:1033-1045go
			penetrateMap := map[string]interface{}{				consts.BBox:                    fmt.Sprintf("%.2f,%.2f,%.2f,%.2f", cast.ToFloat64(messageTmp.XMin), cast.ToFloat64(messageTmp.YMin), cast.ToFloat64(messageTmp.XMax), cast.ToFloat64(messageTmp.YMax)),				visualSearchSourcePenetrateKey: sourceInfo,			}			queryTmp, _ := json.Marshal(models.QueryFile{				Query:  gQuery.QueryCh,				GQuery: gQuery,			})			sessionInfoList = append(sessionInfoList, models.QueryInfo{				Query:     string(queryTmp),				Penetrate: tools.JSONMarshal(penetrateMap),			})

map[string]interface{} 在这里用于拼装一个 JSON 对象。 原来的 b_box 继续保留。 visual_search_source 是新增键,值是刚才取得的来源结构。 tools.JSONMarshal 把这个 map 编码为字符串。

把 Penetrate 解析一次后,可以看到这样的结构。

JSON.parse(task.penetrate) 的示例结果json
{  "b_box": "0.10,0.20,0.80,0.90",  "visual_search_source": {    "image_prompt_info": {"query": "这是什么猫?"},    "search_query_list": ["橘猫"],    "history_5_rounds": [{"message_content": "历史问题"}]  }}

E.2 本次复用的保存链路

CustomizeQueryList 原来就会重建 QueryInfo。 它把传入的 Penetrate 合并到最终扩展信息。 任务构造再把它放进 EvaluateTaskExtra.Penetrate。 本次没有新建一张来源表,也没有增加数据库字段。

service/gpt.go:3822-3828go
			// 人工指定透传的,比代码指定的优先级高			if queryInfo.Penetrate != "" {				json.Unmarshal([]byte(queryInfo.Penetrate), &peTmp)			}			peByte, _ := json.Marshal(peTmp)			res.Penetrate = string(peByte)

上面这段是复用的旧逻辑。 新增测试会确认:重建 QueryInfo 后,三个字段仍在。 Legacy 任务保存到 Extra,Biz 任务沿用现有 PenetrateJSON 适配。 来源能否产生,仍取决于项目实际命中的来源 Handler。

E.3 详情接口与导出看到的是不同包装层

使用方 读取路径 包装层来自哪里
结果页 JSON.parse(data.task.penetrate).visual_search_source 任务详情接口
导出引擎 task_info_penetrate.visual_search_source 导出器组装的内部数据

task_info_penetrate 不是数仓原始字段名。 它是导出器解析任务 Penetrate 后放入的内部根节点。 因此 TCC 的 data_idx 必须写完整路径。

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

三个配置项都使用已有 BaseExportEngine。 它用 gjson 按路径取值,形成导出用的字符串。 TCC 配置不是这九个 Git 文件中的 Go 代码。 配置让现有导出框架知道要读哪一列。

active_app_list 控制生成导出列时是否命中项目应用。 现有字段配置接口没有据此过滤前端选项。 所以其他项目的弹窗也能看到这些字段。

E.4 另外几处日志改动

视觉来源被加入 rawDouBaoRPCLoggingEnabled 的关闭条件。 相关 RPC 日志改为记录概要,不主动打印完整请求响应。 部分错误分支按同一策略输出错误类型。 这项策略不代表所有 SDK 或通用业务日志都会被关闭。

formatVisualSearchData 结束时新增 visual_input_ready 摘要。 它记录来源数、有效产出数和跳过数。 消息 JSON 无法解码时,也有对应的跳过原因。 这些改动用于定位取数阶段,不改变 Query 和图片。

F

6. 飞书为什么是链接,CSV 为什么仍是 JSON

这次导出改动的入口是 bitableCellValue。 它只负责把某个单元格转换成飞书需要的值。

helpers/exporter/handler_v2.go:1732-1746go
func (e *ExporterHandlerV2) bitableCellValue(ctx context.Context, appToken string, headerKeys []string, idx int, rawValue string, uploadAttachments bool) (interface{}, error) {	headerKey := safeHeaderKey(headerKeys, idx)	if uploadAttachments && headerKey == visualSearchHistoryDataIdx && strings.TrimSpace(rawValue) != "" {		return e.uploadBitableHistoryJSON(ctx, rawValue)	}	if isBitableAttachmentOverflowHeaderKey(headerKey) {		return rawValue, nil	}	if !uploadAttachments || !isBitableAttachmentHeaderKey(headerKey) {		return rawValue, nil	}	if appToken == "" {		return nil, errors.New("app token is empty")	}	return uploadBitableAttachmentCell(ctx, appToken, headerKey, rawValue)

F.1 只有三个条件同时成立才转存

条件 作用
uploadAttachments 为 true 当前在准备真实远端写入;预览路径不做上传
headerKey 精确等于 history 的完整路径 只处理这一列,不靠列标题猜字段
TrimSpace 后不为空 缺失或空白历史不上传

uploadAttachments 是原有参数名。 当前真实飞书写入入口会传 true。 它并不表示 history 已变成附件列。 历史列仍是文本列,里面放下载 URL。

这里已经没有长度判断。 短历史、长历史和 [] 都进入同一个转存方法。 image_prompt_info 与 search_query_list 保留原有 JSON 文本。

F.2 一个函数完成原文校验、上传与链接缓存

helpers/exporter/bitable_history_json.go:18-41go
func (e *ExporterHandlerV2) uploadBitableHistoryJSON(ctx context.Context, rawValue string) (string, error) {	if err := ctx.Err(); err != nil {		return "", err	}	if !json.Valid([]byte(rawValue)) {		return "", fmt.Errorf("history_5_rounds is not valid JSON")	}	digest := sha256.Sum256([]byte(rawValue))	if url, ok := e.bitableHistoryJSONURLs[digest]; ok {		return url, nil	}	// 按内容哈希生成稳定路径,重复历史复用同一文件,不改写格式或解析内层业务字符串。	key := fmt.Sprintf("crawl_exports/%d/history_5_rounds/%x.json", e.Project.Id, digest)	if err := dal.PutObject(ctx, "", key, int64(len(rawValue)), strings.NewReader(rawValue),		tos.ContentType("application/json; charset=utf-8"),		tos.ContentDisposition(`attachment; filename="history_5_rounds.json"`)); err != nil {		return "", fmt.Errorf("upload history_5_rounds JSON (%d bytes): %w", len(rawValue), err)	}	url := consts.GetTosDomain(dal.IsExistInTosClient(ctx, key)) + key	if e.bitableHistoryJSONURLs == nil {		e.bitableHistoryJSONURLs = make(map[[32]byte]string)	}	e.bitableHistoryJSONURLs[digest] = url	return url, nil

按代码顺序,一次只理解一个动作。

代码 做什么 为什么
ctx.Err() 检查任务是否已取消 已取消就不继续上传
json.Valid 校验单元格字符串是合法 JSON 导出读取数据库数据,不能生成无效 JSON 文件
sha256.Sum256 计算完整内容的摘要 给这段内容生成稳定标识
读取 bitableHistoryJSONURLs 查当前导出是否已上传该内容 重复出现时复用链接
fmt.Sprintf 生成 key 确定对象存储中的文件路径 同项目、同内容使用同一路径
dal.PutObject 把完整字符串写入 TOS 不截断历史,不改写内层字符串
拼接下载地址 取得可放入飞书的 URL 单元格保持很短
初始化并写入缓存 记住已成功上传的链接 失败时不会缓存假链接

SHA-256 是摘要,不是内容加密。 相同字节内容会得到相同摘要。 如果空格或内容变了,摘要也会变化。

文件路径示意text
crawl_exports/2768479/history_5_rounds/<内容摘要>.json

map[[32]byte]string 可以先类比 Map<内容摘要, 下载URL>。 SHA-256 的结果是 32 个字节。 map 初始可以为 nil,读取时可以正常得到“没有命中”。 写入前必须 make,因此这里有一次懒初始化。 url, ok := cache[digest] 同时读取值和是否存在。 ok 为 true 时,直接返回已有链接,不再上传。

缓存属于当前 ExporterHandlerV2。 它不是 Redis,也不是跨进程的全局缓存。 同次导出中重复的历史可以复用链接。 下一次导出仍可使用同一路径保存相同内容。

F.3 两个文件元信息有什么作用

Content-Type 指定 application/json; charset=utf-8。 Content-Disposition 指定下载文件名 history_5_rounds.json。 strings.NewReader(rawValue) 直接读取原始字符串。 这里没有再执行 JSON.stringify,把整个历史包成字符串。

文件保存的是导出器交给它的完整 JSON。 它不会下载 JSON 里面提到的图片和附件。 下载后仍可看到这些资源原来的地址。

F.4 CSV 不变的原因在于没有修改共享数据

使用原值返回TOS链接原始导出行CSV写入新建飞书recordFields历史字段转换飞书记录

bitableRecordsForRows 为飞书新建 recordFields。 链接写入这个新 map,没有覆盖原来的 e.data。 CSV 的 format2Csv 则直接读取 e.data。 它还会处理 JSON 中的逗号、双引号和换行转义。

输出位置 同一段历史的最终形式
任务详情接口 完整历史数组,位于 penetrate 字符串内
CSV 完整 JSON 文本
飞书表格 完整 JSON 文件的下载 URL
TOS 文件 转存前的完整导出 JSON
G

7. 错误怎样向上传递,为什么不能跳过一批题

G.1 Go 通常把错误当作返回值

在上传函数中,成功返回 URL 和 nil。 失败返回空字符串和 error。 调用方检查 error 后,决定继续还是退出。

fmt.Errorf 中的 %w 会包装原始错误。 外层补充“上传历史 JSON”和内容字节数。 底层原因仍然保留,可用 errors.Is 继续判断。 它的职责接近给 JavaScript Error 添加 cause。

存储上传复用了 dal.PutObject。 现有 DAL 会对同一对象路径重试,并重建读取器。 新函数没有再增加一套重试循环。

G.2 普通导出与实时同步都要拿到这个错误

单元格构造失败时,bitableRecordsForRows 继续向上返回错误。 它会补充行号、字段名和字段路径。 普通导出记录最终会进入失败状态。

实时同步原来的方法只返回 fields、records 两个值。 构建失败时返回 nil、nil,调用方无法区分原因。 这次把方法改成三个返回值。

helpers/exporter/handler_v2.go:1727-1729go
func (e *ExporterHandlerV2) ExportBitableFieldsAndRecordsForRealtime(ctx context.Context, appToken string) ([]lark_bitable.BitableField, []lark_bitable.BitableRecord, error) {	_, _, fields, records, err := e.exportBitableFieldsAndRecords(ctx, appToken, true)	return fields, records, err

第三个值就是 error。 这是包内部方法的签名变化,不是新增 HTTP 接口。 唯一的生产调用方也同步修改了接收方式。

views/download_realtime_timer.go:253-258go
	writtenRecordCount := 0	fields, records, err := handler.ExportBitableFieldsAndRecordsForRealtime(ctx, job.SpreadsheetToken)	if err != nil {		_ = jobDAL.RecordTemporaryError(ctx, job.ID, err.Error())		return err	}

这里的 := 一次接收三个值。 如果 err 非空,先记录临时错误,然后返回。 不会继续执行后面的写表和游标更新。

G.3 用五道题理解 cursor

cursor 表示实时同步已经成功处理到哪里。 假设这批准备导出第 101 至 105 题。 第 105 题的 JSON 上传失败时,这一批没有完整成功。 如果此时把 cursor 推到 105,下次就会跳过未成功的数据。

否是准备一批题目构建飞书字段构建是否成功?记录临时错误返回错误并保留游标继续写入飞书按既有成功路径更新游标

保留游标是为了下次仍能选到这批数据。 这不代表所有外部写入都有数据库事务回滚。 一批写入中发生部分成功时,仍依赖现有导出机制处理。

代码中的 _ = jobDAL.RecordTemporaryError 采用原有做法。 它忽略的是“记录临时状态”的返回值。 真正导致本批失败的 err 仍然返回给上层。

H

8. 全部九个文件、测试目的与阅读顺序

业务代码共有五个 Go 文件发生变化。 另外三个测试文件负责说明和验证约束。 还有一个 Markdown 文件记录数据契约。

文件 这次负责什么
service/gpt_douyin_session.go 在现有视觉输入流程中接入 817,附加来源并调整日志
service/visual_search_session_detail.go 定义来源结构,查询明细,核对身份,归一化三个字段
helpers/exporter/handler_v2.go 增加链接缓存,接入历史单元格转存,透传实时构建错误
helpers/exporter/bitable_history_json.go 完整 JSON 上传、内容哈希与下载链接
views/download_realtime_timer.go 接收构建错误,失败时停止推进游标
service/visual_search_session_detail_test.go 7 个测试,覆盖两阶段取数、字段边界和来源不串题
service/gpt_douyin_session_test.go 调整日志策略测试,加入视觉来源场景
helpers/exporter/bitable_history_json_test.go 7 个测试,覆盖统一链接、CSV、缓存、失败和分批写入
service/visual_search_session_detail.md 记录来源结构、降级规则和导出行为

测试不是另一套业务实现

Go 用 TestXxx(t *testing.T) 约定标识测试函数。 mockey.Mock 把外部调用换成可控的测试返回值。 例如模拟 817 返回错 ID,确认代码不会把它挂到任务上。 测试中的 example.invalid 图片和假 TOS 地址不用于生产。

测试问题 防止什么回归
两阶段取数后,图片、Query、ROI 是否相同 来源补齐意外改变执行输入
无效图片会不会仍查询 817 无用请求增加与来源错配
一题明细失败会不会丢掉其他有效题 局部故障拖垮整批
单字段异常是否只影响该字段 错误地清空其他有效来源
过滤第一张图片后,来源是否仍对应第二题 来源串题
短历史、长历史、[] 是否统一得到链接 长度分支残留
写过飞书记录后,CSV 是否仍是原文 共享数据被 URL 覆盖
相同历史是否只上传一次 重复存储请求
上传失败是否仍可重试 失败链接被误缓存
实时错误是否返回给调用方 失败被当成空结果
分批写入是否也使用链接 只改到旧导出路径

这些测试隔离了 RPC、存储和飞书接口。 它们能验证代码分支,不等于真实服务已经验收。 本会话只执行了格式和静态检查,没有运行 Go 测试。 仓库限制本地 Go 验证,不能把未执行的用例说成已通过。

回到编辑器时,按这个顺序点开

次序 从哪里开始 要看懂的事情
1 gpt_douyin_session.go:1010 在哪里增加了 817 调用
2 visual_search_session_detail.go:20 ID、响应数量和三个字段如何处理
3 visual_search_session_detail.go:70 对象、数组和编码字符串如何统一
4 gpt_douyin_session.go:1033 来源如何进入 Penetrate
5 handler_v2.go:1732 飞书哪一列需要转存
6 bitable_history_json.go:18 完整 JSON 怎样变成下载链接
7 download_realtime_timer.go:254 错误为什么必须在游标前返回
8 对应测试文件 用输入和预期检查自己的理解

页面代码片段来自当前分支的真实文件。 讲解中的 m-demo 和猫图片地址是示例数据。 代码以 f4140a04f 为准;未来修改后应重新核对行号。