Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

22.8 KB
Raw Blame
/**
 * autoFollowIntent — auto-follow(流式贴底跟随)的解除 / 恢复判定纯函数集。
 * ---------------------------------------------------------------------------
 * 修复背景(2026-07 用户实报):流式输出期间「是否在底部」原来只有一条规则 —
 * `distanceFromBottom < 100px` 的纯距离判定。用户上滚一格滚轮(~40px)时距离
 * 仍 < 100px → 仍被判「在底」→ 下一批 token 到达,pin-to-bottom 又把 scrollTop
 * 钉回最底 → 下一格滚轮又从最底起步,永远越不过阈值。只有一次快速滚多行、在
 * 两次 pin 的间隙里瞬间离底超过 100px 才能停下自动滚动。叠加因素:pin 会短暂
 * 打开 programmaticScrollRef(rAF 后才清),流式期间 pin 几乎每帧发生,用户的
 * scroll 事件有相当比例落在该窗口内被当作程序滚动直接忽略,连参与距离判定的
 * 机会都没有。
 *
 * 修复思路:「解除跟随」与「恢复跟随」用不同的信号(VSCode 终端 / 各聊天流的
 * 通行做法):
 *  - **解除**:看用户输入意图,不看距离。wheel 上滚 / 触摸下拉 / PageUp 等
 *    只有用户能产生(程序化 scrollTop 赋值不发 wheel 事件),没有上述竞态,
 *    滚一行(哪怕一像素)立即解除,确定性响应。
 *  - **恢复**:两条互补信号,都不能只看「距底 < 100」:
 *      1. scroll 事件:距底 < threshold 且方向明确向下(防解除后紧跟的上滚
 *         scroll 把跟随立刻翻回去);
 *      2. 用户已经贴死底部(距底 ≤ REPIN_AT_BOTTOM_PX)时的向下意图
 *         (wheel / 触控上滑)。人已经在最底时继续往下滚往往不再产生
 *         scroll 事件,只靠 1 会表现为「滚到最后了,新生成却不跟」。
 *
 * 抽成纯函数为了单测覆盖 + 与 React 副作用解耦,pattern 同
 * scrollAnchoringDetect / viewportFillDetect。
 */

/**
 * 容器「真的可滚」的最小滚动余量(px)。
 * 与 viewportFillDetect.NO_SCROLL_TOLERANCE_PX 同源语义:DPR≠1 环境下
 * scrollHeight 可能比 clientHeight 大 1px 的 sub-pixel 圆整,视觉上滚不动。
 * 内容还没撑满一屏时不解除跟随 — 此时解除毫无视觉意义,却会在内容长出
 * 滚动条后表现为「不跟了」,而且因为滚不动、没有 scroll 事件,用户无法用
 * 「滚回底部」恢复跟随,等于永久失联。
 */
export const UNPIN_MIN_SCROLLABLE_PX = 1;

/**
 * 「已经贴死底部」的距离(px)。比 100px 近底阈值小一档:
 * 典型一格滚轮约 40px,停在这里说明人就在视口底,不是刚上滚一格后的残留。
 * 用于 wheel / 触控的恢复意图,以及 scroll 事件在 delta≈0 时的落地恢复。
 */
export const REPIN_AT_BOTTOM_PX = 8;

export interface WheelUnpinArgs {
  /** wheel 事件的 deltaX(水平分量,用于主轴判定) */
  deltaX: number;
  /** wheel 事件的 deltaY(负 = 向上) */
  deltaY: number;
  /** scroll 容器当前 scrollHeight */
  scrollHeight: number;
  /** scroll 容器当前 clientHeight */
  clientHeight: number;
}

/** Direction is independent of whether the current content can scroll. */
export function isUpwardWheelIntent({
  deltaX,
  deltaY,
}: Pick<WheelUnpinArgs, 'deltaX' | 'deltaY'>): boolean {
  return deltaY < 0 && Math.abs(deltaY) >= Math.abs(deltaX);
}

/**
 * wheel 事件是否构成「用户想向上滚、应解除 auto-follow」。
 *
 * 条件(全部满足):
 *  - deltaY < 0:向上;
 *  - |deltaY| >= |deltaX|:垂直是主轴。触控板在横向可滚区域(如 overflow-x 的
 *    代码块,hasNestedScrollableAncestorThatCanScrollUp 只查纵向祖先拦不住)
 *    做水平平移时常带微小的负 deltaY 抖动,不加主轴判定会被误判成上滚意图、
 *    随手一划就停掉跟随;
 *  - 容器可滚(见 UNPIN_MIN_SCROLLABLE_PX)。
 *
 * caller 还需自行排除「事件目标在嵌套可滚祖先内」(DOM 查询,不属于纯函数)。
 */
export function shouldUnpinOnWheel({
  deltaX,
  deltaY,
  scrollHeight,
  clientHeight,
}: WheelUnpinArgs): boolean {
  if (!isUpwardWheelIntent({ deltaX, deltaY })) return false;
  return scrollHeight - clientHeight > UNPIN_MIN_SCROLLABLE_PX;
}

export interface UpIntentUnpinArgs {
  /** scroll 容器当前 scrollHeight */
  scrollHeight: number;
  /** scroll 容器当前 clientHeight */
  clientHeight: number;
}

/**
 * 非 wheel 的向上意图(触摸下拉已过阈值 / PageUp 等历史导航键)是否应解除
 * auto-follow。方向语义由 caller 的事件分支保证(touchmove 下拉阈值 /
 * HISTORY_NAVIGATION_KEYS 白名单),这里只补「容器可滚」守卫。
 */
export function shouldUnpinOnUpIntent({ scrollHeight, clientHeight }: UpIntentUnpinArgs): boolean {
  return scrollHeight - clientHeight > UNPIN_MIN_SCROLLABLE_PX;
}

export interface ScrollbarDragUnpinArgs {
  /** 指针仍按在滚动容器上(滚动条拖拽中)。 */
  pointerDown: boolean;
  /** 相对按下时的 scrollTop 增量(负 = 向上)。 */
  scrollDelta: number;
  /** 方向判断死区(px)。 */
  directionDeadZonePx: number;
}

/**
 * 滚动条拖拽是否构成「用户想向上离开尾部」。
 *
 * 只认按下后的实际上移,不认单纯 mousedown:生成期间点一下滑块不该掐死跟随。
 * 流式 pin 会把 programmatic scroll 窗口几乎一直打开,handleScroll 的普通
 * 用户分支看不见这次拖拽,必须用按下态 + scrollTop 上移单独判定。
 */
export function shouldUnpinOnScrollbarDrag({
  pointerDown,
  scrollDelta,
  directionDeadZonePx,
}: ScrollbarDragUnpinArgs): boolean {
  return pointerDown && scrollDelta < -directionDeadZonePx;
}

export interface VerticalScrollbarPressArgs {
  /** mousedown 的 target 是否就是滚动容器本身。 */
  targetIsRoot: boolean;
  /** 相对滚动容器的 offsetX。 */
  offsetX: number;
  /** 滚动容器 clientWidth(不含纵向滚动条)。 */
  clientWidth: number;
}

/**
 * 这次 mousedown 是否落在纵向滚动条上。
 *
 * 滚动条生命周期不变量:
 *  - 进入拖拽:只有点到滑块/槽(target === 容器且 offsetX ≥ clientWidth);
 *    正文、链接、按钮上的按下不能进拖拽态,否则长按选字会停 pin、松手又被钉回;
 *  - 拖拽中:抑制 pin,scrollTop 上移过死区才 unpin;
 *  - 松开:若仍在跟随,补一次 pin(按住期间最后一批 token 可能已经 settle)。
 */
export function isVerticalScrollbarPress({
  targetIsRoot,
  offsetX,
  clientWidth,
}: VerticalScrollbarPressArgs): boolean {
  return targetIsRoot && offsetX >= clientWidth;
}

export interface WheelRepinArgs {
  /** wheel 事件的 deltaX(水平分量,用于主轴判定) */
  deltaX: number;
  /** wheel 事件的 deltaY(正 = 向下) */
  deltaY: number;
  /** 当前距底距离(scrollHeight - scrollTop - clientHeight) */
  distanceFromBottom: number;
}

/**
 * wheel 事件是否构成「用户已在底部、应恢复 auto-follow」。
 *
 * 与 shouldUnpinOnWheel 对称:看意图不看「能不能再滚」。人已经贴死底部时
 * 继续往下滚通常不再改变 scrollTop,handleScroll 收不到向下 delta,必须
 * 在 wheel 层恢复。距底必须 ≤ REPIN_AT_BOTTOM_PX,避免刚上滚一格(约 40px)
 * 后的回弹/惯性把跟随立刻翻回去。
 */
export function shouldRepinOnWheel({
  deltaX,
  deltaY,
  distanceFromBottom,
}: WheelRepinArgs): boolean {
  if (deltaY <= 0) return false;
  if (Math.abs(deltaY) < Math.abs(deltaX)) return false;
  return distanceFromBottom <= REPIN_AT_BOTTOM_PX;
}

export interface DownIntentRepinArgs {
  /** 当前距底距离(scrollHeight - scrollTop - clientHeight) */
  distanceFromBottom: number;
}

/**
 * 非 wheel 的向下意图(触摸上滑已过阈值)是否应恢复 auto-follow。
 * 方向语义由 caller 的事件分支保证,这里只判「已经贴死底部」。
 */
export function shouldRepinOnDownIntent({ distanceFromBottom }: DownIntentRepinArgs): boolean {
  return distanceFromBottom <= REPIN_AT_BOTTOM_PX;
}

export interface SelectTailUserMessageArgs<T extends { type: string }> {
  /** 当前有界窗口是否覆盖完整 render-item 尾部。 */
  windowCoversEnd: boolean;
  /** 当前 DOM 窗口的 render items。 */
  visibleItems: readonly T[];
  /** 内存中完整 render-item 序列。 */
  allItems: readonly T[];
  /** 从 render item 提取 user message id;非 user item 返回 null。 */
  userMessageId: (item: T | undefined) => string | null;
}

/** Walk items from the tail and return the first matching value. */
export function findLastMatching<T, U>(items: readonly T[], pick: (item: T) => U | null): U | null {
  for (let i = items.length - 1; i >= 0; i--) {
    const value = pick(items[i]);
    if (value) return value;
  }
  return null;
}

/** Walk items from the tail and return the first matching id. */
export function findLastMatchingId<T>(
  items: readonly T[],
  pickId: (item: T) => string | null,
): string | null {
  return findLastMatching(items, pickId);
}

/**
 * 选择供「新用户发送」检测的尾消息。
 *
 * bounded window 未覆盖会话末尾时,visible 尾只代表历史切片边界,可能刚好是
 * 一条旧 user message;拿它建基线会误判跳回底部或遮蔽真正的新发送。因此该态
 * 必须无条件读取内存全量的真实尾部。窗口覆盖末尾时从 visible 尾往回找最近
 * 一条 user——发送后同一帧 assistant / 工具卡已经接在后面时,只看最后一项
 * 会把本次发送漏掉,后续不再强制跟底。
 */
export function selectTailUserMessageId<T extends { type: string }>({
  windowCoversEnd,
  visibleItems,
  allItems,
  userMessageId,
}: SelectTailUserMessageArgs<T>): string | null {
  return findLastMatchingId(windowCoversEnd ? visibleItems : allItems, userMessageId);
}

export interface ResolveRenderPinArgs {
  /** A saved non-bottom viewport is currently being restored. */
  restoring: boolean;
  /** The current render introduced a new user message at the tail. */
  newUserSend: boolean;
  /**
   * The tail user message was sent from this renderer's composer (local send,
   * edit-resend, or a device-link send initiated on this desktop). User
   * messages injected by other entries (IM channels, a mobile client driving
   * the session remotely, scheduler runs) arrive over IPC with no local
   * composer intent and must not steal the viewport (#2194).
   */
  sentFromThisRenderer: boolean;
  /** Auto-follow was active before this render. */
  nearBottom: boolean;
}

export interface ResolveRenderPinDecision {
  /** Explicit sends hand ownership back to the latest-message anchor. */
  clearRestoring: boolean;
  /** Pin the scroll container to its content end in this layout pass. */
  pinToBottom: boolean;
}

export interface ResolveLastUserMessageObservationArgs {
  /** A saved non-bottom viewport is currently being restored. */
  restoring: boolean;
  /** The current render's tail user message, if any. */
  tailUserMessageId: string | null;
  /** The last tail user message already observed by the mounted stream. */
  previousTailUserMessageId: string | null;
  /**
   * Every user message id already loaded on this mount. Receding the tail to
   * any of these (rollback, rewind, remount) is not a send.
   */
  knownUserMessageIds?: ReadonlySet<string>;
}

export interface ResolveLastUserMessageObservation {
  /** Baseline to store after observing the current render. */
  baselineUserMessageId: string | null;
  /** Whether the current tail user message is a newly sent message. */
  isNewUserSend: boolean;
}

/** Collect every user message id currently present. */
export function collectKnownUserMessageIds<T>(
  items: readonly T[],
  userMessageId: (item: T) => string | null,
): Set<string> {
  const ids = new Set<string>();
  for (const item of items) {
    const id = userMessageId(item);
    if (id) ids.add(id);
  }
  return ids;
}

/**
 * A tail-user change follows as a send only when that user id is new to this
 * mount. Rollback, rewind, remount, and history hydration re-expose ids that
 * were already loaded — those only move the baseline.
 */
export function resolveLastUserMessageObservation({
  restoring,
  tailUserMessageId,
  previousTailUserMessageId,
  knownUserMessageIds,
}: ResolveLastUserMessageObservationArgs): ResolveLastUserMessageObservation {
  if (
    tailUserMessageId !== null &&
    tailUserMessageId !== previousTailUserMessageId &&
    knownUserMessageIds?.has(tailUserMessageId)
  ) {
    return { baselineUserMessageId: tailUserMessageId, isNewUserSend: false };
  }
  const baselineUserMessageId =
    restoring && previousTailUserMessageId === null && tailUserMessageId !== null
      ? tailUserMessageId
      : previousTailUserMessageId;
  return {
    baselineUserMessageId,
    isNewUserSend: tailUserMessageId !== null && tailUserMessageId !== baselineUserMessageId,
  };
}

/**
 * Resolve the render-time priority between a saved history anchor and auto-follow.
 * Reopening a session must preserve a real reading position, but a user message
 * sent from this renderer during that mounted session is an explicit request to
 * resume at the tail. A user message injected by another entry (IM channel,
 * mobile client, scheduler) carries no such intent: it follows the ordinary
 * rule — pin only while the user is still near the bottom.
 */
export function resolveRenderPinDecision({
  restoring,
  newUserSend,
  nearBottom,
  sentFromThisRenderer,
}: ResolveRenderPinArgs): ResolveRenderPinDecision {
  if (newUserSend && sentFromThisRenderer) {
    return { clearRestoring: restoring, pinToBottom: true };
  }
  if (restoring) return { clearRestoring: false, pinToBottom: false };
  return { clearRestoring: false, pinToBottom: nearBottom };
}

export interface ResolveSendWindowHandoffArgs {
  /** The current render introduced a new user message at the tail. */
  isNewUserSend: boolean;
  /** The tail user message was sent from this renderer's composer. */
  sentFromThisRenderer: boolean;
  /** The stream is currently showing an anchored (non-default-tail) window. */
  hasWindowAnchor: boolean;
  /** The current bounded window already includes the real session tail. */
  windowCoversEnd: boolean;
}

export interface ResolveSendWindowHandoff {
  /** Local send while reading an anchored window: switch back to the default tail. */
  clearWindowAnchor: boolean;
  /**
   * The current visible slice does not include the real tail, so pinning this
   * frame would land on the old slice. Wait for the next render's tail window.
   */
  deferPinToNextRender: boolean;
}

/**
 * After a local send, leave any historical render window so later assistant /
 * tool items keep auto-following the real tail.
 *
 * An anchored window that still covers the end at send time used to stop
 * following as soon as the next item moved the real tail past its bound. Local
 * sends hand off eagerly so the optimistic row is shown at the real tail; the
 * generic coverage-loss handoff below protects anchors created by auto-fill.
 * External injections must not take this eager handoff (#2194).
 */
export function resolveSendWindowHandoff({
  isNewUserSend,
  sentFromThisRenderer,
  hasWindowAnchor,
  windowCoversEnd,
}: ResolveSendWindowHandoffArgs): ResolveSendWindowHandoff {
  const clearWindowAnchor = isNewUserSend && sentFromThisRenderer && hasWindowAnchor;
  return {
    clearWindowAnchor,
    deferPinToNextRender: clearWindowAnchor && !windowCoversEnd,
  };
}

export type WindowCoverageLossAction = 'none' | 'handoff-to-tail' | 'preserve-anchor';

export interface ResolveWindowCoverageLossArgs {
  /** The stream is currently showing an anchored (non-default-tail) window. */
  hasWindowAnchor: boolean;
  /** The anchored window covered the real session tail before this render. */
  wasCoveringEnd: boolean;
  /** The anchored window still covers the real session tail after this render. */
  windowCoversEnd: boolean;
  /** Auto-follow intent before the tail item was appended. */
  wasFollowingTail: boolean;
}

/**
 * Decide how an anchored render window should react when an appended item moves
 * the real session tail beyond its bounded end.
 *
 * An automatically expanded window can still be following the tail. In that
 * case the bounded anchor is only an implementation detail, so hand it back to
 * the default tail window instead of interpreting the append as user scroll
 * intent. A user who already left the tail keeps the anchored reading window.
 */
export function resolveWindowCoverageLossAction({
  hasWindowAnchor,
  wasCoveringEnd,
  windowCoversEnd,
  wasFollowingTail,
}: ResolveWindowCoverageLossArgs): WindowCoverageLossAction {
  if (!hasWindowAnchor || !wasCoveringEnd || windowCoversEnd) return 'none';
  return wasFollowingTail ? 'handoff-to-tail' : 'preserve-anchor';
}

export interface ResolveNearBottomArgs {
  /** scroll 事件前的跟随态(isNearBottomRef) */
  wasNearBottom: boolean;
  /** 当前距底距离(scrollHeight - scrollTop - clientHeight) */
  distanceFromBottom: number;
  /** 本次 scroll 事件的 scrollTop 增量(正 = 向下) */
  scrollDelta: number;
  /** 「近底」距离阈值(px) */
  thresholdPx: number;
  /** 方向判断死区(px),增量绝对值不超过它不算方向 */
  directionDeadZonePx: number;
  /**
   * 「已经贴死底部」的距离(px)。已解除且距底不超过它、且不是上滚时恢复跟随。
   * 人滚到最底后最后一次 scroll 常为 delta≈0,只靠向下方向会永远恢复不了。
   */
  atBottomPx?: number;
}

/**
 * scroll 事件驱动的跟随态迁移(handleScroll 消费)。
 *
 *  - 距底 >= threshold 且(已解除, 或明确上滚) → false。这是滚动条拖拽
 *    等无 wheel 路径的解除兜底。**已在跟、却只是内容在下方长高**
 *    (发送后首块 assistant / 工具卡撑高、迟到的程序化 scroll 事件)
 *    不得解除 — pin / ResizeObserver 会补上。
 *  - 距底 < threshold 且原本在跟 → 保持 true。阈值带内的微小上移不在这里
 *    解除(滚动条微拖、布局收缩钳位等 scrollTop 被动上移会误伤),wheel /
 *    touch / 键盘的意图解除路径已经覆盖了真实的用户上滚。
 *  - 距底 < threshold 且原本没在跟 → 只有明确向下(delta > 死区)才恢复
 *    跟随。**不能只看距离**:意图解除后紧跟着到达的用户上滚 scroll 事件距底
 *    仍 < threshold,若无方向守卫会把刚解除的跟随立刻翻回去(修复的核心)。
 *  - 已贴死底部(距底 ≤ atBottomPx)且不是上滚(delta ≥ 0)→ 恢复。人已经在
 *    最底时最后一次 scroll 常为 delta≈0;1px 上滚解除后的 scroll 带负 delta,
 *    不会误恢复。
 */
export function resolveNearBottomOnScroll({
  wasNearBottom,
  distanceFromBottom,
  scrollDelta,
  thresholdPx,
  directionDeadZonePx,
  atBottomPx = REPIN_AT_BOTTOM_PX,
}: ResolveNearBottomArgs): boolean {
  if (distanceFromBottom >= thresholdPx) {
    if (!wasNearBottom) return false;
    return scrollDelta >= -directionDeadZonePx;
  }
  if (wasNearBottom) return true;
  if (distanceFromBottom <= atBottomPx && scrollDelta >= 0) return true;
  return scrollDelta > directionDeadZonePx;
}

export interface ResolveEffectiveNearBottomArgs {
  /** Current bounded window includes the real session tail. */
  windowCoversEnd: boolean;
  /** Distance/direction resolver result for this scroll event. */
  nowNearBottom: boolean;
  /** Follow state before this scroll event. */
  wasNearBottom: boolean;
}

/**
 * Combine slice coverage with the scroll-event follow decision.
 *
 * A historical slice scrolled to its own bottom is not the session tail, so
 * we must not *start* following there. An explicit follow (composer send /
 * jump-to-latest) already set wasNearBottom; a late scroll event while the
 * window has not yet switched back to the default tail must not cancel it.
 */
export function resolveEffectiveNearBottom({
  windowCoversEnd,
  nowNearBottom,
  wasNearBottom,
}: ResolveEffectiveNearBottomArgs): boolean {
  if (windowCoversEnd) return nowNearBottom;
  return wasNearBottom ? nowNearBottom : false;
}

/**
 * A composer send that started on session A must not pin session B after the
 * user switched routes. FadeSwitcher only remounts on the first path segment,
 * so CCAgentSessionView state survives `/cc-agent/:id` changes.
 */
export function shouldApplyFollowLatestRequest(
  sourceSessionId: string | null | undefined,
  currentSessionId: string | null | undefined,
): boolean {
  return Boolean(sourceSessionId && sourceSessionId === currentSessionId);
}

const sendFollowCancelGenerations = new Map<string, number>();

export function readSendFollowCancelGeneration(sessionId: string | null | undefined): number {
  if (!sessionId) return 0;
  return sendFollowCancelGenerations.get(sessionId) ?? 0;
}

/** User up-intent on this stream cancels a still-pending follow-latest. */
export function bumpSendFollowCancelGeneration(sessionId: string | null | undefined): void {
  if (!sessionId) return;
  sendFollowCancelGenerations.set(sessionId, (sendFollowCancelGenerations.get(sessionId) ?? 0) + 1);
}

export function shouldBumpSendFollowCancelOnScroll({
  wasNearBottom,
  effectiveNearBottom,
}: {
  wasNearBottom: boolean;
  effectiveNearBottom: boolean;
  scrollDelta: number;
  directionDeadZonePx: number;
}): boolean {
  // Only leaving the tail cancels a pending follow. Continued up-scroll while
  // already away is leftover reading inertia and must not void the next send.
  return wasNearBottom && !effectiveNearBottom;
}

export function shouldCommitFollowLatestRequest({
  sourceSessionId,
  currentSessionId,
  startGeneration,
  currentGeneration,
}: {
  sourceSessionId: string | null | undefined;
  currentSessionId: string | null | undefined;
  startGeneration: number;
  currentGeneration: number;
}): boolean {
  if (!shouldApplyFollowLatestRequest(sourceSessionId, currentSessionId)) return false;
  return startGeneration === currentGeneration;
}

const followLatestListeners = new Set<() => void>();
const followLatestRequests = new Map<string, number>();

export function subscribeFollowLatestRequests(onStoreChange: () => void): () => void {
  followLatestListeners.add(onStoreChange);
  return () => {
    followLatestListeners.delete(onStoreChange);
  };
}

export function readFollowLatestRequestKey(sessionId: string | null | undefined): number {
  if (!sessionId) return 0;
  return followLatestRequests.get(sessionId) ?? 0;
}

/** Accepted local send from any entry (composer, edit-resend) requests follow. */
export function tryRequestFollowLatest({
  sourceSessionId,
  currentSessionId,
  startGeneration,
}: {
  sourceSessionId: string | null | undefined;
  currentSessionId: string | null | undefined;
  startGeneration: number;
}): boolean {
  if (
    !shouldCommitFollowLatestRequest({
      sourceSessionId,
      currentSessionId,
      startGeneration,
      currentGeneration: readSendFollowCancelGeneration(sourceSessionId),
    })
  ) {
    return false;
  }
  if (!sourceSessionId) return false;
  followLatestRequests.set(sourceSessionId, (followLatestRequests.get(sourceSessionId) ?? 0) + 1);
  for (const listener of followLatestListeners) listener();
  return true;
}