Assistant

Assistant 模块通过 sessionHistory.ts 实现会话事件的远程获取与分页加载。它封装了与 Anthropic API 的会话事件接口交互，支持获取最新事件页（anchor_to_latest）和向前翻页（before_id 游标），为会话恢复（/resume）和历史浏览提供数据源。模块设计精简——仅一个文件，但它是连接本地对话状态与云端持久化的关键桥梁。

职责与设计理念

职责说明

会话历史管理与远程事件同步，连接本地对话与云端持久化

设计理念

极简即力量——一个文件、一个职责、零冗余。会话历史的复杂性被封装在分页游标协议中，调用者只需关心"最新页"和"更早页"两个语义。

架构决策

为什么用游标分页而不是 offset 分页？

使用 before_id 游标 + anchor_to_latest 锚点

会话事件是追加写入的流式数据，offset 分页在并发写入时会产生重复或遗漏。游标分页基于事件 ID 的全序关系，保证分页的一致性。

文件清单

文件名	用途
sessionHistory.ts	会话事件远程获取，支持分页游标、OAuth 认证、超时控制

使用场景

/resume 命令

从云端拉取历史会话事件，恢复中断的对话上下文

Commands.resume → Assistant.fetchLatestEvents() → 重建消息列表

向上滚动查看历史

触发 fetchOlderEvents()，按需加载更早的对话事件

UI.ScrollBox → Assistant.fetchOlderEvents(beforeId)

依赖关系

Entrypoints — 多模式入口适配器，统一 CLI/SDK/MCP 三种调用方式的启动路径
Bootstrap — 全局状态容器与会话生命周期管理，维护运行时的单一真相源

关键代码片段

会话历史分页加载

export type HistoryPage = {
  events: SDKMessage[]      // 按时间顺序排列的事件
  firstId: string | null    // 最早事件 ID → 翻页游标
  hasMore: boolean           // 是否有更早的事件
}

export async function fetchLatestEvents(
  ctx: HistoryAuthCtx, limit = 100
): Promise<HistoryPage | null> {
  return fetchPage(ctx, { limit, anchor_to_latest: true }, 'latest')
}

export async function fetchOlderEvents(
  ctx: HistoryAuthCtx, beforeId: string, limit = 100
): Promise<HistoryPage | null> {
  return fetchPage(ctx, { limit, before_id: beforeId }, 'older')
}

基于游标的分页协议：anchor_to_latest 获取最新页，before_id 向前翻页

技术笔记

security

OAuth 认证上下文

HistoryAuthCtx 封装 OAuth token 和会话 ID，每次请求自动附加认证头，token 过期时触发刷新流程。

edge-case

超时与重试

网络请求设置 30s 超时，失败时返回 null 而非抛异常，调用者通过 null 检查优雅降级。