示例项目ScopeSwitch页面IndexMigrationPage相册里的 128 张图片并不算大真正麻烦的是“替换索引”这件事。旧索引仍在响应搜索新索引又要逐张写入如果直接清空再重建用户会得到一段确定的空窗。如果把两个 scope 当成可随意切换的数据库分区又会忽略能力升级后旧数据可能已经失效的边界。本文把这类变化拆成两种同一能力版本内的数据代际切换以及能力或模型更新触发的全量重建。前者可以做双 scope 验证后切指针后者不能承诺“瞬时回滚”只能依赖图片清单重新构建。示例中的数值是为了说明状态机而设置的演示数据不是设备实测也不代表平台性能。一、先把“升级”分成两种否则回滚是假命题textSearchImage提供初始化、插入图片、按文本搜索、删除和清理数据等能力。工程层最容易犯的错是把所有变化都叫成“索引升级”。实际上图片集合变化与底层能力更新不是同一类风险。第一类是内容代际变化。例如照片库完成一次去重路径清单从 g12 变成 g13但设备上的文搜图能力没有变化。此时可以把新图片写入album_g13继续让线上查询读取album_g12待固定探针通过后应用只切换自己的 active scope。旧 scope 暂时保留就能快速回退。第二类是能力更新。官方错误边界明确提示能力更新后需要清理数据并重新使用搜索。这里的clearData是全局动作不能假设album_g12仍保留一套兼容旧模型的向量。也就是说所谓“模型升级回滚”只能回滚应用版本、策略和图片清单再重新建索引不能把旧 scope 当成一定可用的热备。ScopeSwitch 因此把迁移模式写进清单CONTENT_GENERATION允许 g12、g13 并存切换CAPABILITY_REBUILD必须先导出路径清单再执行清理和全量重建。这个区分看似保守却能避免在故障演练时才发现旧索引已经被清掉。二、迁移清单不是进度条而是可恢复的事实本次演示任务为INDEX-CUT-0072。旧 scope 是album_g12新 scope 是album_g13输入清单包含 128 张图片。状态从G12_ACTIVE进入G13_BUILDING验证完成后到达G13_VALIDATED最后才允许POINTER_SWITCHED。页面显示的 88% 只是当前迁移进度不参与是否切换的判断。清单至少要保存任务 ID、模式、源代际、目标代际、路径摘要、总数、已插入数和失败列表。只存一个百分比无法恢复重启后你不知道 88% 对应哪 112 张图片也无法判断剩余路径是否与当前相册一致。这段代码解决什么问题。它把一次迁移定义为可序列化的代际清单并用稳定字段表达“谁有资格被切为活动索引”。typeMigrationModeCONTENT_GENERATION|CAPABILITY_REBUILDtypeMigrationStateG12_ACTIVE|G13_BUILDING|G13_VALIDATED|POINTER_SWITCHED|G12_RETIRED|FAILEDinterfaceIndexManifest{taskId:stringmode:MigrationMode sourceScope:stringtargetScope:stringpathDigest:stringtotal:numberinserted:numberfailedPaths:string[]state:MigrationState revision:number}constmanifest:IndexManifest{taskId:INDEX-CUT-0072,mode:CONTENT_GENERATION,sourceScope:album_g12,targetScope:album_g13,pathDigest:sha256:7ec1…39ad,total:128,inserted:0,failedPaths:[],state:G12_ACTIVE,revision:72}这样写的关键不是类型漂亮而是把迁移事实与 UI 状态分开。inserted每完成一张才增加failedPaths保留原始输入revision用来拒绝旧任务晚到的回调。状态只能单向推进页面重新创建后根据清单恢复而不是从进度条反推事实。容易出错的地方是把路径摘要当作安全签名。这里的 digest 只用于识别输入集合是否变化不证明文件可信。真实项目还应处理图片被移动、权限变化和路径失效若清单内容已变不能继续复用旧的 88%。三、构建新 scope 时活动查询仍然读旧代际同一能力版本内新 scope 的写入可以在不改变活动指针的情况下进行。构建器一次只处理清单中的明确路径失败项单独记录它不会在遇到一张坏图时把整个 g13 宣布完成也不会把页面上的“取消”误写成删除旧索引。这段代码解决什么问题。它把新 scope 的写入、状态推进和过期任务隔离在一个构建会话中。import{textSearchImage}fromkit.CoreVisionKitclassScopeBuilder{privategeneration:number0asyncbuild(paths:string[],draft:IndexManifest):PromiseIndexManifest{constminethis.generationconstnext:IndexManifest{...draft,inserted:0,failedPaths:[],state:G13_BUILDING}for(constpathofpaths){if(mine!this.generation){return{...next,state:FAILED}}try{awaittextSearchImage.insertImage(path,next.targetScope)next.inserted1}catch(_){next.failedPaths.push(path)}}returnnext}cancel():void{this.generation1}}generation不是平台参数而是示例项目自己的提交权。取消或重启会话后旧循环即使还返回也不能继续更新当前清单。状态由G12_ACTIVE进入G13_BUILDING但线上搜索仍根据 active scope 读取album_g12。这里没有在循环中反复init()。初始化与release()应由更上层的能力会话成对管理进入文搜图功能时初始化所有插入和搜索都结束后再释放。页面销毁只取消本页面的提交权不应在后台构建仍运行时抢先释放公共会话。演示把 128 张全部插入成功页面显示128/128若有失败验证阶段必须知道失败比例和具体路径。不要用Promise.all一口气推入大量任务并假设服务可以无限并发批量节奏应按产品数据规模和官方限制控制。四、切换前用固定探针验证而不是只看插入成功插入 128 次成功只能证明写入调用没有抛出异常不能证明搜索行为符合产品预期。ScopeSwitch 保存 6 条固定探针例如“蓝色咖啡杯”“会议白板”“夜间街景”并记录每条查询的期望图片集合。新 scope 至少要通过 6/6 探针且 top-3 与基线重合率不低于约定阈值。本批示例的 top-3 重合率为0.83。它不是质量的绝对答案只是一个发布门禁。真实项目还要按人像、文档和风景分桶避免平均值掩盖某一类完全失效。这段代码解决什么问题。它在切指针前对目标 scope 做可重复的探针验证并保留每条失败原因。interfaceProbe{query:stringexpectedPaths:string[]}interfaceProbeResult{query:stringpassed:booleanoverlap:number}asyncfunctionverifyScope(scope:string,probes:Probe[]):PromiseProbeResult[]{constreport:ProbeResult[][]for(constprobeofprobes){constfoundawaittextSearchImage.search(probe.query,scope,3)constpathsfound.map(itemitem.imagePath)consthitpaths.filter(pathprobe.expectedPaths.includes(path)).length report.push({query:probe.query,passed:hit0,overlap:hit/Math.max(1,probe.expectedPaths.length)})}returnreport}验证直接指定album_g13不会受活动指针影响。每条探针保留 query、结果路径和重合率6/6 通过后清单才从G13_BUILDING进入G13_VALIDATED。如果搜索调用失败结果不能伪装成“零命中”调用错误、空结果和质量不达标应是三种不同状态。代码中的imagePath应以当前 SDK 的ImageObject定义为准示例只展示项目所需字段。如果后续 API 定义发生变化应在适配器中一次性转换而不是让页面和脚本到处依赖原始对象。图中的 DevEco Studio 画面是与本文数据一致的演示配图不是实际 IDE 运行证据。右侧模拟器仍显示album_g12为活动代际底部 HiLog 同时记录album_g13 inserted128/128、probes6/6与overlap0.83这正是构建与服务并行存在的阶段。五、活动指针要小、原子、可校验切换动作不应复制 128 条记录也不应让 UI 自己拼 scope 名。应用只持久化一个很小的指针当前 scope、对应 revision、清单 digest 和切换时间。这里的持久化实现由项目适配器提供可以落到 Preferences 或项目已有的配置仓文章不把自建ActiveScopeStore冒充系统接口。这段代码解决什么问题。它让活动代际的提交具备 compare-and-set 语义防止两个迁移任务互相覆盖。interfaceActiveScope{scope:stringrevision:numbermanifestDigest:stringswitchedAt:string}interfaceActiveScopeStore{read():PromiseActiveScopecompareAndSet(expectedRevision:number,next:ActiveScope):Promiseboolean}asyncfunctioncommitScope(store:ActiveScopeStore,checked:IndexManifest,probesPassed:number):Promiseboolean{if(checked.state!G13_VALIDATED||probesPassed!6)returnfalsereturnstore.compareAndSet(checked.revision-1,{scope:checked.targetScope,revision:checked.revision,manifestDigest:checked.pathDigest,switchedAt:2026-10-01T11:24:0008:00})}compare-and-set 成功后查询路由从album_g12切到album_g13状态进入POINTER_SWITCHED。本例把切换操作记为 38 ms 的示例值它只描述演示流程不是设备性能承诺。失败时不覆盖新值而是重新读取活动指针确认是否已有更高 revision 提交。最危险的写法是“先更新内存再异步落盘”。进程在两步之间退出后页面看到 g13重启却回到 g12日志又无法解释。实际项目应让持久化成功成为唯一提交点内存状态从持久化结果派生。六、运行页要让用户看见正在使用哪一代切换之后IndexMigrationPage 不只显示绿色成功图标而是把任务、活动 scope、目标 scope、进度和探针结果放在同一页。这样调试人员能区分“g13 已构建”与“g13 已服务”也能确认 88% 对应的是构建进度而不是搜索质量。手机图中的时间为 11:24任务为INDEX-CUT-0072活动代际已从album_g12指向album_g13构建为128/128探针为6/6top-3 重合率为0.83。红色箭头只标出POINTER_SWITCHED因为真正决定用户查询落到哪一代的是这个提交点。运行页还应提供“验证详情”而不是提供一个无条件回滚按钮。回滚前先检查旧 scope 是否仍在保留期、当前能力版本是否变化、旧清单是否完整。只有内容代际切换且条件都满足才允许把指针重新指回 g12。七、模型更新后的回滚实质是重新构建当系统能力更新触发需要clearData的边界时g12 与 g13 的热切换模型就结束了。执行清理前ScopeSwitch 保存两样东西图片路径清单与验证探针。清理后创建新的目标代际例如album_g14重新插入并验证。旧 g12 的 scope 名可以留在历史记录里但它不再代表可查询的数据。这时页面上的“回滚到 g12”必须改写成“按 g12 清单重建”。两者耗时、可用性和风险完全不同。若产品要求搜索不中断就需要业务侧提供降级策略例如临时显示最近图片、文件名搜索或明确的维护提示而不是声称底层旧索引还能工作。clearData也不应该被普通取消按钮调用。它的破坏范围比当前任务大必须放在能力重建流程中记录前置清单、当前版本事实和确认结果。本文不提供一键清理代码正是为了防止复制示例时把全局动作放进页面级逻辑。八、退役旧 scope 之前先观察再删除内容代际切换成功后g12 仍保留一个观察窗口。ScopeSwitch 比较 g12 与 g13 的查询错误、空结果和探针漂移同时处理清单中 3 条已失效路径。只有 g13 稳定、回滚窗口结束状态才从POINTER_SWITCHED进入G12_RETIRED。退役是业务流程不等于一定调用全局清理。可以根据官方删除能力逐张移除旧代际图片也可以在数据规模允许时安排下一次维护重建。关键是任何删除都从清单驱动不能用前缀猜测路径更不能因为 scope 名里有 g12 就认定所有内容都可删。诊断页展示完整状态链G12_ACTIVE → G13_BUILDING → G13_VALIDATED → POINTER_SWITCHED → G12_RETIRED。它还列出“即时回滚可用”“能力更新后回滚需重建”两个不同结论并明确 3 条失效路径已经从退役计划中隔离。红圈用于强调回滚边界而不是装饰界面。九、把异常注入到迁移流程而不是只测成功路径这套状态机至少应覆盖四类故障。第一类是插入到第 77 张时进程退出重启后根据清单继续而不是把 77 张重复计数。第二类是探针 5/6 通过必须停在构建完成但未验证状态。第三类是另一个 revision 已经切换指针当前任务的 compare-and-set 必须失败。第四类是能力更新后出现需要清理的错误流程必须转入CAPABILITY_REBUILD禁止继续显示“可热回滚”。日志也应围绕事实组织taskId、revision、scope、inserted/total、probePassed、activeScope和错误类型。不要只输出“迁移成功”否则线上看到空结果时无法判断是构建不全、指针未切、能力已更新还是一条查询自身没有命中。1. 重启恢复要重新确认输入而不是盲目续跑迁移清单写到 88% 后应用可能被系统回收也可能因为用户撤销照片权限而暂停。再次进入页面时恢复逻辑首先重新枚举可访问路径并计算新的集合摘要。摘要仍是sha256:7ec1…39ad才说明当前输入与任务创建时一致如果摘要不同即使已插入数仍为 112也不能从第 113 项继续。路径集合变化有三种常见原因。用户删除了照片旧路径已经失效系统媒体路径发生迁移内容相同但标识变化任务运行期间又新增了图片。三种情况不能都归结为“少一张”。ScopeSwitch 的处理是冻结当前 revision记录差异集合再由策略决定创建 g14 或重算 g13。恢复动作不直接修改活动指针g12 始终保持服务能力。已写入新 scope 的记录也不能仅凭本地计数认为存在。若能力进程、存储或版本事实发生变化需要重新跑一条已知探针确认目标 scope 仍可查询。探针失败时清单退回G13_BUILDING或进入FAILED而不是继续增加 inserted。这样做会多一次查询却能阻止“本地进度很完整、实际索引已经失效”的假恢复。2. 查询路由要携带读取时的 scope切换窗口里最难追的日志往往来自一次请求跨越了指针更新请求创建时 active scope 是 g12真正执行搜索前指针已经变成 g13。如果日志只打印最终活动值排查人员会误以为结果一定来自 g13。正确做法是在请求创建时读取并冻结 scope把它与 query、sequence 一起传入适配器完成日志也打印同一值。这不是要求所有请求在切换时取消。旧请求可以正常完成但它的结果必须标明读取代际新请求从 g13 开始。若页面采用联想搜索还要继续使用 sequence 过滤过期结果索引代际与请求时序是两条正交的控制线不能用同一个数字替代。统计同样要按 scope 分组。切换后的短观察期内分别计算 g12、g13 的调用失败、空结果与耗时分布才能判断变化来自数据代际还是网络、权限和页面竞态。若所有指标混成一条曲线回滚判断会失去证据。3. 探针集也需要版本和维护责任固定探针不是写完就不动的六句话。相册结构改变后某个期望图片可能已经被用户删除产品增加文档场景后原来的风景探针也不足以代表风险。探针清单应有自己的版本、创建原因和最小覆盖说明并与索引 manifest 一起归档。探针维护要避免“为了让新版本通过而改答案”。当 g13 对一条查询的排序明显变化时先人工检查新结果是否合理再决定是模型行为变化、数据变化还是旧期望错误。修改期望必须形成新的 probe revision旧报告仍保留否则历史上的 6/6 与今天的 6/6 其实使用了两套答案却看起来完全相同。本例的0.83只用于演示 top-3 重合率。真实门禁可以同时保留至少一项绝对条件例如每条探针至少命中一个人工确认的正样本再配合分桶的相对指标。这样既不过度绑定完全相同的排序也不会让一个不错的平均数掩盖某条关键查询完全失效。4. 观测到异常时先停止退役而不是立即反切切换后出现空结果上升不一定说明 g13 索引损坏。也可能是媒体权限刚被关闭、某类路径失效、查询语言变化或 UI 把 scope 传错。自动反切若不判断原因可能把同样的问题带回 g12还会让两次指针变更互相覆盖。ScopeSwitch 的第一动作是冻结退役计划保留 g12并把当前 revision 标记为观察。只有当 g12 对同一批探针正常、g13 异常且能力版本与权限事实一致才满足快速回退条件。如果两代都失败应该进入能力诊断而不是在两个 scope 之间来回切换。这也解释了为什么“保留旧 scope”只是风险缓冲不是完整故障恢复方案。可恢复性来自清单、探针、原子指针、版本事实和降级页面共同作用。少了其中任何一项按钮上的“回滚”都可能只是在改变一个字符串。本文的128/128、6/6、0.83、38 ms与88%都是示例输入目的在于验证文图和状态机的一致性。它们不能作为真实设备性能结论。真正发布前应在目标系统版本、真实相册规模和权限条件下重新采样。十、结论可回滚的是应用决策不一定是旧向量文搜图索引迁移的核心不在“再调用一次 insert”而在于明确哪部分由系统能力负责哪部分由应用自己承诺。同一能力版本内scope 可以承担数据代际隔离固定探针和原子指针让切换可验证、可撤销能力或模型更新要求清理数据时旧向量不再是可靠的回滚资产真正可保留的是路径清单、验证集和迁移事实。ScopeSwitch 的最终状态是G12_RETIRED但这个结论只针对演示的内容代际模式。若检测到能力更新流程会停止热切换并要求重建。把这条边界写进代码和页面比给所有失败都准备一个“回滚”按钮更诚实也更容易在下一次升级时定位问题。工程上真正值得保留的不是某个 scope 名而是一套能重放的输入、能复核的探针和一次只有一个提交者的状态迁移。这样即使能力版本再次变化团队仍能解释每一步发生了什么并在明确代价后恢复服务。参考资料华为开发者论坛文搜图相关示例与说明https://developer.huawei.com/consumer/cn/forum/topic/0203220028018131387HarmonyOS Core Vision Kit 文搜图 API 参考以当前官方文档为准https://developer.huawei.com/consumer/cn/doc/harmonyos-references/