PR #151：Provider 原生会话标题成为第一类数据

buffin-ai/buffin · main...feat/provider-native-session-titles · 2026-07-20 · 自包含，读完即弃

写法说明：本文按「逐跳走读」展开——每个机制都给真实代码片段（取自分支、经裁剪，青色斜体注释为解读所加，灰色斜体是源码原注释的保留或意译），每段代码标注所在文件。每条旅程结尾有一张「排查路标」：将来出问题时，症状对应去哪个文件看哪个函数。

1TL;DR

这个 PR 让 Claude 和 Codex 生成的会话标题进入 Buffin，但不会覆盖用户自己起的名字。数据库同时保留用户覆盖值和 Provider 候选值，所有读接口只返回按优先级计算后的“有效标题”。

标题变化不进入持久化的 Agent 事件流，而是通过新的全局 sessions.deltas 临时订阅实时广播；断线后客户端靠查询失效和重取恢复一致性。

Desktop 的重命名输入现在可以清空：清空意味着移除用户覆盖，立即回落到 Provider 标题。PR 还处理了生成重试、重连竞态和编辑中的后台改名竞态。

2变更地图

按 numstat 统计共 1923 行改动，其中测试 1337 行。生产代码约 586 行，设计密度主要集中在两个 Provider runner、SessionService 和 dispatcher。

3架构一图流

关键边界是：标题属于 Session 元数据，不属于某次 run。因此 Provider 通过 AgentEventSink.publishGeneratedTitle 写入独立的 SessionService；这条路径不会追加 session.title.updated 一类持久事件。

4数据与状态先行

读行为之前先记住三个形状：数据库有两个标题槽位；API 只暴露有效标题；实时流只携带足够修补缓存的三项元数据。

title: text('title'),
generatedTitle: text('generated_title'),

titleLength: check(
  'agent_sessions_title_length',
  sql`${table.title} IS NULL OR length(${table.title}) <= 200`,
),
generatedTitleLength: check(
  'agent_sessions_generated_title_length',
  sql`${table.generatedTitle} IS NULL OR length(${table.generatedTitle}) <= 200`,
),

export type SessionDto = {
  id: string
  title: string | null // 有效值，不泄露两个底层槽位
  updatedAt: string
  // ...
}

export type SessionTitleDelta = {
  sessionId: string
  title: string | null
  updatedAt: string
}

5旅程 A：Provider 产出标题

这条旅程从一次成功回合结束开始，到 Provider 候选值进入 Session 元数据 sink 为止。Claude 是“主动生成”，Codex 是“读取 Provider 已有的 thread 名称或预览”。

A.1Claude：终态先落地，标题随后 fail-open 生成

Claude 只在真实用户回合成功完成、尚无候选、没有请求在途、且重试预算未耗尽时发请求。它先把 run.completed 交给 sink，再异步请求标题，所以标题超时或写入失败不会改写已完成回合的终态。

private titleGenerationEligible(): boolean {
  return (
    this.runContext?.kind === 'turn' &&
    !this.generatedTitleRecorded &&
    !this.titleRequestInFlight &&
    this.titleGenerationAttempts < TITLE_GENERATION_MAX_ATTEMPTS
  )
}

private startTitleGeneration(process: ClaudeProcess, description: string): void {
  this.titleRequestInFlight = true
  const attempt = ++this.titleGenerationAttempts
  const request = buildClaudeControlRequest({
    subtype: 'generate_session_title',
    description,
    persist: true,
  })
  void this.requestControl(process, request, TITLE_GENERATION_TIMEOUT_MS)
    .then(readGeneratedTitle)
    // ...成功写入；失败保持可重试
    .finally(() => { this.titleRequestInFlight = false })
}

请求描述来自当前用户输入，按 Unicode code point 截到 1000；单次等待 10 秒。空白、缺失、格式错误、超时和错误响应都不记为成功，下一次成功回合会重试，第三次后停止并记录日志。

A.2Codex：优先吃现成元数据，缺失时回读 thread

Codex 不额外让模型生成标题。它按 thread.name 优先、thread.preview 兜底，从 start、resume、name update 三类现成响应中采集；若第一次回合结束时仍没有候选，再发一次 thread/read。

private async publishThreadTitle(thread: CodexThread): Promise<void> {
  const title = nonblank(thread.name) ?? nonblank(thread.preview)
  if (title) await this.publishTitleCandidate(title)
}

private async refreshThreadTitle(): Promise<void> {
  if (!this.threadId) return
  try {
    const response = await this.requirePeer().request<CodexThreadReadResponse>(
      'thread/read',
      { threadId: this.threadId, includeTurns: false },
      this.requestTimeoutMs,
    )
    if (!this.hasProviderTitleCandidate && response.thread.id === this.threadId) {
      await this.publishThreadTitle(response.thread)
    }
  } catch (err) {
    logger.warn({ err, threadId: this.threadId }, 'Codex session title refresh failed')
  }
}

titleRefreshInFlight 只是互斥锁，不是一次性门闩：finally 会释放它。第一次 thread/read 暂时失败时，下一次 completed 回合会再次尝试。来自别的 thread 的 name update 会被 thread id 校验挡掉。

6旅程 B：持久化与实时同步

Provider 候选到达后，Daemon 先做归一化和可见性检查，再提交数据库并发布有效标题。客户端拿到 delta 后修 detail cache、刷新 list；若连接重建，则不猜丢了什么，直接让所有 Session 查询失效。

B.1写入只改候选，广播永远给有效值

Provider 字符串先 trim、把所有空白折叠成一个空格，再按 code point 截到 200。空值、相同值、归档、purge 中或已删除的 Session 都不写。成功提交后，delta 的 title 使用现有用户值优先。

const result = this.db
  .update(agentSessionsTable)
  .set({ generatedTitle, updatedAt })
  .where(and(
    eq(agentSessionsTable.id, id),
    isNull(agentSessionsTable.archivedAt),
    notPurgedSessionWhere(),
  ))
  .run()

if (result.changes !== 1) return
this.deltas.publish(SESSION_DELTA_TOPIC, {
  sessionId: id,
  title: current.title ?? generatedTitle, // 用户覆盖仍然赢
  updatedAt: toIsoTimestamp(updatedAt),
})

普通的 sessions.update 也发布同一种 delta。用户设置标题时广播用户值；Provider 在用户覆盖存在时更新候选，广播的仍是用户值；用户清空覆盖时，广播最新 Provider 候选。

B.2临时流不回放，靠 resync 修复连续性

sessions.deltas 是全局 ephemeral feed：适合轻量元数据广播，但不承诺离线期间逐条回放。每次订阅先收到 resync marker，客户端把所有 Session list 和 detail 查询标为失效，让活跃观察者重新拉真相。

export function applySessionTitleDelta(ctx, delta): Promise<void> {
  const detailKey = sessionGetQueryKey(delta.sessionId)
  if (ctx.queryClient.getQueryState(detailKey) !== undefined) {
    ctx.queryClient.setQueryData<SessionDto>(detailKey, (current) =>
      current ? { ...current, title: delta.title, updatedAt: delta.updatedAt } : current,
    )
  }
  return ctx.queryClient.invalidateQueries({ queryKey: sessionsListQueryKeyPrefix() })
}

export function resyncSessions(ctx): Promise<void> {
  return Promise.all([
    ctx.queryClient.invalidateQueries({ queryKey: sessionsListQueryKeyPrefix() }),
    ctx.queryClient.invalidateQueries({ queryKey: sessionGetQueryKeyPrefix() }),
  ]).then(() => undefined)
}

这里还有一个时间顺序保护：resync 引发的旧响应可能晚于新 delta 返回。dispatcher 用每个订阅自己的 Promise chain 严格按到达顺序执行 effect，让旧 refetch 先落，再应用新标题，避免新标题被旧响应覆盖。

7旅程 C：用户重命名与回落

用户看到的一直是有效标题。点击铅笔时，输入框同步以当前值种下草稿；输入空白并提交，会发送 title: null，表示删除覆盖，而不是把空字符串存入数据库。

function onChange(next: string) {
  dirty.current = true
  setValue(next)
}

function beginEdit() {
  dirty.current = false
  setValue(serverValue)
}

function onBlur() {
  const next = value.trim()
  if (next.length === 0) {
    if (onClear) onClear()
    else setValue(serverValue)
    return
  }
  if (next === serverValue) {
    dirty.current = false
    setValue(serverValue)
    return
  }
  onCommit(next)
}

编辑期间若 Provider 推来新标题：用户还没输入时，草稿跟随新 serverValue，blur 不会把旧标题写回；用户已经输入时，dirty 草稿保持不动，最终提交用户值。这就是第三个 commit 专门修的前后台竞态。

8心智模型补丁

9新词表

10测试与风险地图

覆盖声明：本报告基于 PR 的 3 个 commit、58 个文件和完整 diff。逐文件读取了数据库/API 形状、Daemon wiring、Claude/Codex runner、SessionService、tRPC 路由、client dispatcher、Desktop 编辑逻辑及新增/改动测试；一行式 mock/fixture 适配按接口变更归类，没有把它们当作独立设计。

buffin-ai/buffin · PR #151 · 3 commits · 58 files · +1850/−73 · 本报告为一次性理解辅助，不维护、不作为真相源。