历史记录与搜索

Flutter SDK 优先利用本机缓存呈现内容，并通过服务端同步补齐有权限访问的历史。分页、搜索与搜索结果定位是三个不同动作。

分页读取

final page = await sdk.messages.load(
  conversationId,
  limit: 30,
);

if (page.hasMore && page.nextCursor != null) {
  final nextPage = await sdk.messages.load(
    conversationId,
    cursor: page.nextCursor,
    limit: 30,
  );
  // 宿主按消息身份合并 page 与 nextPage，或直接使用聊天控制器。
}

sdk 是已连接实例，conversationId 来自用户可访问的会话。首次加载不传游标，从最新页读取；后续使用服务端/SDK 返回的游标，不自行从页面条数计算。

使用 MixinImChatController 时，loadInitial 负责缓存优先的首屏加载与事件归并，适合多数聊天页面。

本地搜索

final hits = await sdk.messages.search(
  '项目进度',
  conversationId: conversationId,
  limit: 30,
);

搜索范围为当前账号已同步并建立本地索引的消息，不包含服务端尚未同步到本机的历史。界面可标注“搜索本机记录”，同步后更新结果。

按会话汇总搜索结果可使用 messages.searchConversations。指定会话和消息类型时可使用空关键词浏览媒体/文件历史；普通空关键词搜索不会被解释为“搜索全部消息”。

定位上下文

final contextPage = await sdk.messages.loadAround(
  conversationId,
  targetSequence,
  before: 10,
  after: 10,
);

targetSequence 取自搜索结果、引用消息或置顶消息。目标已撤回、删除或无权访问时，结束加载并展示相应提示。

可见范围

服务端的会话水位定义当前用户可补拉的历史范围。首次入群、重新入群、退出群组和清空记录可能改变可见性；本机已有的旧数据与服务端可再次拉取的数据也不是同一个集合。

搜索与上下文定位遵循当前权限和可见水位；清空会话记录后，按更新后的历史范围同步。相关操作见消息操作，群成员变化见群组管理。