> 2026-09-30：录音目录的搜索、排序及本人置顶已改为保持后端统一目录顺序，分页每次 50 人。下文前端全量扫描是旧版实现记录；当前实现与验证范围见 [统一目录对接](speaker-directory-integration-2026-09-30.md)。

# 已识别说话人排序

## 交互

- 搜索框右侧提供「经常出现」「最近出现」；默认经常出现。
- 经常出现：出现天数降序，同天数按最近时间降序。
- 最近出现：最近时间降序，同时间按出现天数降序。
- 完全相同的统计按名称自然序和稳定引用排序；未知或失效统计不冒充 0 天。
- 全部、已标记、未标记共用规则，全部不再把已标记固定排在前面。后续本人置顶：账号确认归属的本人在全部／已标记筛选内优先，其余仍遵循排序；搜索和未标记筛选不额外插入本人。
- 选择按账号保存在当前 Web 源的 localStorage，不承诺跨端同步；筛选、搜索不重置选择。

## 数据和分页

已标记使用正式全历史 presence 统计。未标记目录额外透传已有的 appearanceDays、latestAtMillis 数值，禁止解析展示文案来排序。

现有 Audio 未标记接口固定按 day_count、total_speech_duration_ms、last_seen_at 排序，无 sort 参数。插件串行读取列表元数据，不读取音频或逐人详情；补齐后才具有完整排序覆盖。读取中、失败、投影未就绪和游标版本变化均明确标识不完整；旧版本游标重启一次，取消或账号切换后忽略晚到结果。

单次自动遍历最多 40 页、2,000 个未标记候选，与 Host 当前候选引用容量对齐。到达边界而仍有更多数据时保留「列表尚未完整」提示，不宣称全量排名。显示每批 100 行只是渲染限制，搜索和排序仍覆盖所有已加载记录。

2026-09-28 补充共享读缓存：录音页入口与名单页共用分页和完整快照；失败保留已读取页面，限流退避后续读，不因反复进入页面从头发起全部请求。完整名单保留五分钟后后台更新，标记后失效重读。详见 `recognized-speaker-entry-and-visits.md`。

## 后端后续能力

大于上述边界或希望避免扫描全部元数据时，需要 Audio 列表正式提供服务端排序：frequent = day_count DESC、latest_day_end_at DESC、candidate_id ASC；recent = latest_day_end_at DESC、day_count DESC、candidate_id ASC。游标应绑定账号、投影版本、筛选及排序规则；切换排序不得复用旧游标。若提供统一的已标记/未标记轻量索引，可直接支持混合全局分页。当前插件没有发送未经支持的 sort 参数，也没有修改 Audio 服务。

## 验证范围

排序比较、本机记忆、全量元数据遍历、跨页最新人物、混合分类、搜索、分批渲染、游标失效、刷新竞争、取消、失败和读取上限均有自动测试。8 个相关测试文件共 154 项通过，类型检查、构建和差异检查通过。

2026-09-28 在固定 3100 独立 Web 预览验证：两种排序均切换实际名单；已标记和未标记按统计混合排列；筛选、搜索可配合排序；刷新并重新进入后保留「最近出现」选择。测试后恢复「全部＋经常出现」并清空搜索。当前账号分批加载结束后，加载及不完整提示均消失；大名单的加载等待仍依赖现有固定顺序分页接口，不能据此承诺首屏即获得完整最近排名。仅进行只读列表检查，未修改录音或说话人标记。