文字搜图的结果页很容易出现一种看似无害的变化：输入同一句话，候选图并没有真正换一批，只是排序算法调整了先后顺序。开发者看见的是几张卡片互换位置，埋点系统却可能连续收到“新卡片曝光”；若列表项身份又跟着索引变化，用户点开的详情、选中状态与已经记录的曝光就会发生错位。

本篇把问题限定在结果渲染之前的业务数据契约：先清掉同批重复和过期查询，再用稳定ID表达卡片身份，随后把排序变化与曝光计数分开处理。界面可参考ArkUI Repeat的循环渲染机制，但下面的八条候选与六次曝光全部来自应用自定义固定输入，没有进行真实文本向量检索、模型推理或HarmonyOS设备上的滚动测量。

一、不要把“第几张”当成“哪一张”

设想用户搜索“雨后石桥”，候选P01至P06先按一个分数版本显示。稍后本地重排规则决定把P03放到第一位，P01第二，P06第三，P02第四，剩余两张依次后移。六张图都还是那六张图，但六个列表位置全部改变。只用index当key的方案，很容易把位置身份错当作业务身份，造成子组件更新与埋点口径同时失真。

这不是把Repeat理解成“可以让列表跑得更快”就能解决的。视图组件需要一个稳定的item key，曝光系统还需要一个独立的收据键。前者处理渲染节点对应关系，后者回答同一次查询中某张候选是否已经被记录过。两者名字可以都包含ID，却不能因此合并成一个全局计数器，否则重复查询和同一查询的反复滑动会被混为一谈。

固定任务号是REP-1011-32，数据集bridge_hits_08，搜索词为“雨后石桥”，业务查询代次queryEpoch=3。八个原始候选里只有六个可以进入排序：H07重复引用P02，H08属于已经结束的旧查询代次2。最终保留六张候选，拒绝两条，状态REORDER_PARTIAL。这里的PARTIAL是自定义业务状态，不是ArkUI或文搜图SDK的系统枚举。

二、平台层面的Repeat究竟保证什么

华为ArkUI Repeat指南明确区分非虚拟滚动与virtualScroll两种模式。前者适合短列表全部渲染，后者服务于较长列表的按需创建与复用；Repeat从API 12开始提供，相关V2写法不应随意与V1状态装饰器混用。指南还解释.key()如何决定节点身份，并建议使用数据项自身唯一且稳定的ID，不推荐在数据移动时直接使用索引。

这里说的“稳定”不是永远不变，而是在同一业务对象未改变身份时不因为排序位置变化而改变。P03从第三项移到第一项，其key依旧是P03；若图片内容版本真的换了，业务需要明确更新内容或采用包含版本的身份策略，不能为了追求复用而忽略内容变化。渲染层稳定键和业务数据版本必须分别管理，这比死记一个API参数更重要。

Repeat也不会自动替埋点系统决定“看过一次”的定义。它管理节点创建、更新、复用与销毁，并不天然知道某次曝光应该按一次会话、一个查询还是一天去重。所有曝光收据规则都是本文额外定义。官方文档可以支持选择Repeat和key的理由，但不能被引用来声称我们的收据模型得到系统保证。

三、从八个候选到六个可信输入

本地夹具bridge_hits_08采用八条记录，每条有ref、图片业务ID与查询代次。H01到H06分别指向P01至P06，代次均为3。H07仍指向P02且代次3，所以在同批内判为DUPLICATE_ID。H08指向P07，但来自代次2，所以在任何排序操作之前先被判为STALE_QUERY。

检查顺序是一个具体工程决策。先判断代次，再判断同批ID重复，可以保证旧查询数据不会污染当前唯一性集合。如果先把旧候选写进seen，再发现它已经过期，后面真正的当前代次同ID记录可能被错误标成重复。当前夹具没有构造这样一组并发极端情况，但顺序仍应正确，因为实际搜索输入经常来自多个异步来源。

校验层输出六个唯一ID和两个拒绝原因。此时不应该立刻触发UI“已展示六张”的埋点：数据通过只是允许进入列表，真正曝光还需要可见性证据与收据策略。反过来，UI若因为缓存复用暂时没有新建节点，也不意味着用户没有再次看到它。只有明确区分输入合法、渲染存在和业务曝光三件事，后面才能正确分析日志。

四、第一段代码：过期代次在去重之前挡住

先处理候选身份。代码不依赖HarmonyOS设备能力，用普通JavaScript在Node.js中建立一个确定的入口规则。每条记录的去留与原因可重复计算，便于检查“改变判断顺序是否会影响结果”。源码使用数组和Set，但业务含义是查询代次门禁与同批唯一性，而不是推荐系统排名算法。

export function normalizeCandidates(raw, activeEpoch) {
  const ids = new Set();
  const accepted = [];
  const rejected = [];
  for (const item of raw) {
    let reason = null;
    if (item.epoch !== activeEpoch) reason = 'STALE_QUERY';
    else if (ids.has(item.id)) reason = 'DUPLICATE_ID';
    if (reason !== null) {
      rejected.push({ ref: item.ref, id: item.id, reason });
      continue;
    }
    ids.add(item.id);
    accepted.push(item);
  }
  return { accepted, rejected };
}

对本次固定输入，该函数会得到六条accepted、两条rejected，且拒绝原因分别出现一次。这里没有通过写死H07/H08来制造结果，规则对同结构的新输入也成立。真正项目中还要检验ID是否为空、查询来源是否可信、时间戳和结果版本是否可比较；这段示例只呈现本轮关心的两类分支，不声称完成所有安全输入校验。

异步生命周期方面，搜索框每次产生新的查询应提升epoch，旧请求响应即使成功返回也不能覆盖当前列表。取消网络请求有助于节省资源，却不能替代代次检查，因为取消指令可能晚于实际完成回调。正是这种“取消与结果到达不是同一原子事件”的边界，使STALE_QUERY有必要成为独立原因，而不是简单丢掉一条日志。

五、排序前后是六次位置移动，零次身份更换

初始顺序锁定为[P01,P02,P03,P04,P05,P06]。重排后顺序为[P03,P01,P06,P02,P04,P05]。每个ID都在原来的集合里，重排结果没有新增照片、没有删除照片，但按位置比较时六个位置全部不同。这个“移动六处”的数字能帮助复核逻辑，而不能拿来推断ArkUI真正创建了六个新节点。

在UI优化讨论里经常混淆“数据变化”和“节点变化”。数据层排序确实改变了全部索引；如果稳定key正确，框架可以据此辨别业务项的持续身份。究竟更新、移动、复用或销毁多少节点，还取决于当前Repeat模式、可见范围、缓存池与实际框架实现，不能仅凭数学数组比较就宣称滑动帧率提高了多少。

本篇把数据契约写得足够清楚：before和after必须各含六个互异ID，且集合完全相同；任何缺失、重复、意外新增都应阻断排序发布。特别是来自异步重排的结果，可能与当前搜索代次不匹配，即使ID集合一致也不能直接应用。生产里要把queryEpoch同时带入排序输入与输出。

六、第二段代码：给Repeat一个业务稳定键

候选通过门禁后，页面才能将其交给渲染层。下面的ArkTS是精简的页面结构示意，使用Repeat配合List，把photo.id作为key，而不是index。它说明“正确的key来自业务ID”的接入位置。数据获取、图片URI权限及异步加载不在此片段中，不能把它视为已经编译通过的完整HarmonyOS项目。

@ObservedV2
class PhotoHit {
  readonly id: string;
  @Trace title: string;
  constructor(id: string, title: string) {
    this.id = id;
    this.title = title;
  }
}

@Entry
@ComponentV2
struct SearchResultsPage {
  @Local hits: PhotoHit[] = [];
  build() {
    List() {
      Repeat<PhotoHit>(this.hits)
        .each((item) => {
          ListItem() {
            Text(item.item.title)
          }
        })
        .key((hit: PhotoHit) => hit.id)
        .virtualScroll()
    }
  }
}

这段代码选择V2状态装饰器，是为了避免把Repeat的虚拟滚动与旧的V1示例随意拼接。移植时需要根据目标SDK实际检查类型签名、编译器要求和容器组合限制；特别是多层子组件参数传递、RepeatItem更新和ListItem边界，不应只凭一张IDE示意图就认定正确。本文保留这一框架级调用，是为了把数据身份与平台能力的分界讲清楚，而不是伪造一次设备运行。

对于只有六张候选的本地演示，non-virtualScroll其实可能更简单。选择virtualScroll的理由，是把示例扩展方向放在真实相册长列表；但真实项目是否值得使用，应通过列表规模、启动开销、滚动帧率与内存实际测量决定。不能把“用了virtualScroll”当成性能结论，更不能把我们的曝光收据模型算作框架自动提供的功能。

七、IDE截图里的日志要足够诚实

与正文配套的开发图应该出现SemanticReceiptDesk、SearchResultsPage.ets、ExposureAuditPage.ets、model/HitIdentityGate.ets与fixtures/bridge_hits_08.json。中间显示Repeat稳定key或过滤规则，最右模拟器展示“雨后石桥”的六张候选，底部HiLog显示八条输入、六项通过、两项阻断。这是一张工程示意图，不是DevEco真实运行截图，也没有做设备滑动性能测试。

约定的日志字段可以为REP-1011-32 raw=8 accepted=6 blocked=2、REP-1011-32 duplicate=1 stale=1 moved=6、REP-1011-32 exposureNew=4 exposureIgnored=2。如果图片上的搜索词、任务号、代次或状态与正文不一致，就应重新生成那张图，而不是把文章数字改成图片产生的随机值。配图服务于证据展示，不应该反过来篡改数据契约。

当前固定时间为2026年10月11日06:41，演示手机电量91%。这些数字没有什么技术意义，但它们能够暴露素材是否跨批次误用。尤其在连续自动创作场景里，旧批次的PST、INK或REL任务ID若混入本轮截图，会比错别字更严重，因为读者将无法对应代码和日志的真正对象。

八、曝光收据不能直接绑到索引

重排完成后，当前视口中可见的四项依次是P03,P01,P06,P02。假设曝光事件序列是P03,P01,P06,P02,P01,P03，总共收到六次事件，但新增的唯一曝光收据只有四份，后两次属于同一查询下的重复通知。这里的“重复”来自本文自建业务规则，并非Repeat框架认为子组件重复。

如果把收据键设置为index=0..3，P03从第三位置搬到第一位置就可能被当作新曝光，P01和P06也有类似风险。反过来，如果只按图片ID做一个永不失效的全局Set，用户第二天再搜索相同图片又永远不会被记为新曝光，统计口径也会失真。因此收据应至少包含查询会话标识与候选ID，必要时增加可见时长门槛和列表实例标识。

本例把去重作用域固定为queryEpoch=3内的单次查询，exposureNew=4、exposureIgnored=2。这只是对事件流做幂等处理，不代表四张卡片在物理屏幕上真正停留了足够久。曝光阈值、遮挡判断、后台状态和页面切出等条件属于真实埋点接入阶段，本文没有给它们编造一个“已实测”的结果。

九、第三段代码：用收据键拒绝重复曝光

下面单独给出收据模型，刻意不与Repeat组件直接耦合。这样无论以后换成Grid、WaterFlow，甚至在大屏上改成双栏图片墙，曝光语义都不会跟着UI容器改动。收据键由查询代次和图片ID构成，未通过候选门禁的ID不能创建收据。

export class ExposureReceipts {
  constructor(queryEpoch, allowedIds) {
    this.queryEpoch = queryEpoch;
    this.allowed = new Set(allowedIds);
    this.receipts = new Set();
  }
  accept(eventEpoch, photoId) {
    if (eventEpoch !== this.queryEpoch) return 'STALE_EXPOSURE';
    if (!this.allowed.has(photoId)) return 'UNKNOWN_PHOTO';
    const key = `${eventEpoch}:${photoId}`;
    if (this.receipts.has(key)) return 'DUPLICATE_EXPOSURE';
    this.receipts.add(key);
    return 'NEW_EXPOSURE';
  }
  count() { return this.receipts.size; }
}

六次固定事件重放后count()为4，最后两个事件得到DUPLICATE_EXPOSURE。如果业务改成按10秒可见窗口去重，键和过期策略自然需要调整；本文没有擅自把它写成通用规范。生产中还要考虑收据落盘失败、上报重试以及服务端幂等；前端Set只能控制进程内重复，不保证跨进程恢复或分布式的一次且仅一次。

关于释放，当前收据对象应在查询会话结束后清理，防止长期搜索导致Set不断增长。查询代次切换时先拒绝旧事件，再初始化下一份收据集合，可以避免晚到曝光窜入新查询。如果页面销毁后异步观察回调仍会被触发，就需要在页面生命周期中撤销监听，并让回调检查当前会话有效性；仅移除UI节点不意味着外部上报任务会自动停止。

十、把两个拒绝原因留在用户看得懂的位置

对用户来说，重复候选被去掉通常是好事，不一定需要大红色弹窗。更合理的主页面是展示六张有效图片、搜索词“雨后石桥”以及“数据已整理”的状态。若业务确实处在调试模式，可在底部提示“8个候选中去除2条异常”，点击再进入完整原因页。这样主界面保留使用价值，又不掩盖内部发生过的输入拦截。

本地演示终态命名为REORDER_PARTIAL，意味着六张候选可演示，但原始批次包含两条需要记录的拒绝。它不意味着搜索服务不可用，也不意味着真实图像检索失败。在正式产品里，是否将这类输入异常对用户可见，应考虑误导风险、可恢复程度和服务质量要求。调试标签与用户文案最好分层，否则会让业务运营把开发字段当成产品故障。

主界面配图应展示新的六张排序结果，而不是原始输入顺序。六张照片只是模拟素材，不需要冒充真实语义相似度模型输出。配图还应该明确FIXTURE_ONLY、RepeatRuntime NOT_RUN、ImageSearch NOT_RUN，避免读者把静态结果图理解成某款设备上的真实推理速度与准确度证明。

十一、诊断页要区分“输入脏”和“重复曝光”

这两类重复常被合在一个统计框里。H07是同批输入重复P02：它在排序之前被拒绝，影响的是候选集合。后面曝光序列中的P01与P03重复则是列表展示之后的幂等事件：它们没有改变候选集合，只改变重复上报次数。一个发生在数据入口，一个发生在用户可见事件，两者不能共享同一个duplicateCount而不加来源标识。

诊断页至少应显示raw=8、accepted=6、blocked=2、DUPLICATE_ID=1、STALE_QUERY=1，以及moved=6、exposureNew=4、exposureIgnored=2。建议再显示两个稳定序列，证明ID集合没有改变。若把位置变化数误写成重新渲染数，就已经越出了当前业务夹具的证据范围。

需要注意的是，图片中的诊断日志只能是“预期示意”，不能标成真实HiLog。计划时间线可写06:41:11 LOAD 8、06:41:12 BLOCK H07、06:41:13 BLOCK H08、06:41:14 REORDER 6、06:41:15 RECEIPTS 4/2、06:41:16 REORDER_PARTIAL。一旦接入系统，应保留真正事件时间而不是沿用这些固定值，尤其要把查询代次写进每条日志，避免晚到事件造成因果反转。

十二、排序算法不应该碰触曝光已收据

一个容易写出的反例是“每次重排后先清空曝光Set”。这样用户只是看到同样六张图换了位置，后台却会把已有的曝光重新记一次。另一个反例是“按索引保留曝光”，它会把位置上的新ID错认为已经曝光。这两种方案看起来对称，实际上都把身份层与位置层混成了一件事。

我们选用的策略是：同一查询内重排只更改排列序列，不重置收据集合；更换查询代次才建立新的收据作用域。业务上如果支持切换分类标签，而同一句话在多个标签页里有不同的统计要求，还需要把分类维度加入收据键。这些都是产品决策，应让埋点定义先行，而不是等UI代码上线后再从日志倒推。

还要防止“新结果只改标题不改ID”的伪稳定。如果同一个P03突然指向另一张图片，而ID未变，Repeat可能继续复用同一身份对应的节点；这时暴露出的不是框架错误，而是业务主键设计错误。真正的图片版本应有可追踪标识，必要时在项目元数据里定义photoId+revision作为候选对象身份，同时控制曝光去重是按逻辑图片还是按具体版本执行。

十三、端侧性能指标必须另设实验

这份演示没有测量FPS、节点缓存命中率或页面首帧时间，所以不能说“Repeat比LazyForEach快30%”。华为官方指南解释了Repeat对列表节点复用的机制以及缓存行为，但真实收益受数据量、模板复杂度、图片解码策略和滚动方式影响。六张候选只是为了把身份问题看得清楚，与真实千张相册列表的性能压力相距甚远。

要做严谨的性能实验，应先固定设备、系统版本、屏幕形态、图片尺寸与缓存策略，再分别记录首次呈现、连续快速滚动、排序重排和页面切换的Trace。曝光事件统计也应在独立通道收集，避免埋点上报本身影响渲染。若希望证明“稳定key减少无谓重建”，需要真实的节点创建/更新计数，而不是用moved=6去冒充。

某些多形态场景还会在折叠屏展开后从一列变两列。此时排序ID仍应稳定，但可见范围会变化；曝光收据策略是按同一次查询去重，还是允许展开后新增曝光，要经过产品确认。ArkUI的布局能力不自动帮我们做业务收据决定，数据层保留这个边界，才能在以后改Grid布局时避免整个埋点链路重写。

十四、异常恢复要从查询代次开始

真实文本搜图常发生网络响应乱序：请求A先发后到，请求B后发先到；用户已经输入新的词，旧结果却在较晚时刻回来。如果视图层仅按“最近完成”的响应替换数组，就会出现旧候选和新搜索词同时显示。当前STALE_QUERY门禁的意义，正是阻断这种违背用户意图的替换，而不是提高搜索准确率。

恢复策略应当明确：旧代次数据丢弃并记诊断，不自动创建曝光收据；当前代次的部分合法结果可以按产品策略继续展示，但必须将拒绝原因保存在调试台账。若全部候选都被拒绝，应提供空态与重试入口，而不是显示之前查询的图片冒充本次结果。涉及本地缓存时，缓存键也要包括查询条件、索引版本和授权范围，避免跨账号混用媒体结果。

如果页面在曝光上报进行中销毁，网络请求能否取消、收据能否持久化、失败后如何重试都要另外设计。本文只是同步固定输入层的规则模型，无法证明后台调度或网络一次性投递效果。尤其不能因为Node.js单进程Set返回DUPLICATE_EXPOSURE，就声称真正的客户端与服务端已经建立“恰好一次”的分布式语义。

十五、为什么这轮与之前的文搜图文章不同

此前与文搜图相关的内容可能聚焦语义筛选、索引修复、孤儿引用或结果缓存。本篇没有重写向量相似度计算，也没有再讨论RelationalStore跨表引用；它把工程问题锁定在“排序重排造成位置变化，稳定业务ID如何进入Repeat，并且曝光收据如何免于重复记录”。技术切点从检索内容正确性转向渲染身份与业务事件一致性。

对应DemoSemanticReceiptDesk不复用之前RefSnapshotGate的数据结构，也不声称相同的UI截图能够证明两个不同结论。这里的关键验证路径是固定候选的代次过滤、集合保持、位置变动计数与六次曝光事件幂等，而不是数据库事务提交或资源孤儿清理。即便都与图片有关，工程边界、故障机制和完成条件是不同的。

下一步若要真正集成，应先在目标HarmonyOS项目里确认Repeat和状态装饰器的实际编译结果，再把真实搜索响应适配到唯一ID集合，最后通过列表可见性监听生成曝光事件，分别验证节点变化与业务收据变化。每一步都需要可核查记录；只有完成这一条链，才可以把“数学上六张图没有换”升级成“真实设备上展示与统计没有错位”。

十六、结果、风险与资料

本地Node.js固定输入重放得到的结果是：八条原始候选中六条保留、两条拒绝；拒绝原因分别是DUPLICATE_ID和STALE_QUERY各一次；初始与重排的六个ID集合一致，位置变化六处；六次模拟曝光中四份新收据、两次重复被忽略。最终业务状态REORDER_PARTIAL。这些数字属于规则验证，不是搜索准确率、用户行为统计或ArkUI实际渲染记录。

官方参考：华为《Repeat：可复用的循环渲染》，https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/arkts-new-rendering-control-repeat-V13；华为《组件复用迁移》，更新时间2026-07-03，https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/arkts-v1-v2-migration-reusable。官方资料用于确认Repeat模式、稳定键建议和V1/V2边界；本文收据类、代次门禁与固定数据均属应用自定义实现。

本轮未进行真实HarmonyOS文本搜图推理、图库访问权限申请、设备滚动曝光采集或DevEco完整编译。开发图与手机图即使可读，也只代表规划中的业务界面，不是独立于代码测试的运行证据。工程上值得保留的结论不是“某组件一定最快”，而是先定义唯一身份，再讨论位置与节点；先定义曝光作用域，再讨论重复事件。这两条边界守住，结果排序才能放心演进。