Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import {
DEFAULT_NEAR_BOTTOM_THRESHOLD,
historyPrefetchThreshold,
isNearMessageListBottom,
type MessageScrollMetrics,
} from '@cindy/maker-shared/message-window';
import type {
MobileMessageRenderItem,
MobileWorkChildItem,
} from '@/session/messageRenderModel';
import type { NormalizedRemoteMessage } from '@/session/messageNormalize';
export {
DEFAULT_NEAR_BOTTOM_THRESHOLD,
DEFAULT_LOAD_EARLIER_THRESHOLD,
buildMessageLoadEarlierAction,
buildSearchLoadEarlierAction,
evaluateMessageWindowUpdate,
isNearMessageListBottom,
isNearMessageListTop,
shouldAutoFollowMessages,
shouldShowNewMessageIndicator,
type MessageLoadEarlierActionPresentation,
type MessageScrollMetrics,
type MessageWindowChangeKind,
type MessageWindowUpdateDecision,
} from '@cindy/maker-shared/message-window';
export const MOBILE_MESSAGE_LIST_BOTTOM_PADDING = 132;
export const MOBILE_NEAR_BOTTOM_THRESHOLD =
DEFAULT_NEAR_BOTTOM_THRESHOLD + MOBILE_MESSAGE_LIST_BOTTOM_PADDING;
export function mobileMessageListBottomPadding(bottomOverlayHeight?: number, contentBottomInset?: number): number {
// An inline interaction replaces the composer; an explicit inset must not
// retain the fallback space reserved for that now-hidden composer.
if (typeof contentBottomInset === 'number' && Number.isFinite(contentBottomInset)) {
return Math.max(0, Math.ceil(contentBottomInset));
}
if (typeof bottomOverlayHeight !== 'number' || !Number.isFinite(bottomOverlayHeight)) {
return MOBILE_MESSAGE_LIST_BOTTOM_PADDING;
}
return Math.max(MOBILE_MESSAGE_LIST_BOTTOM_PADDING, Math.ceil(bottomOverlayHeight));
}
export function mobileMessageListNearBottomThreshold(bottomOverlayHeight?: number): number {
return DEFAULT_NEAR_BOTTOM_THRESHOLD + mobileMessageListBottomPadding(bottomOverlayHeight);
}
export function isNearMobileMessageListBottom(
metrics: MessageScrollMetrics,
bottomOverlayHeight?: number,
): boolean {
return isNearMessageListBottom(metrics, mobileMessageListNearBottomThreshold(bottomOverlayHeight));
}
export function mobileMessageListEndOffset(metrics: MessageScrollMetrics): number {
return Math.max(0, metrics.contentHeight - metrics.viewportHeight);
}
// ── 贴底跟随的解除 / 恢复判定(对齐桌面版 autoFollowIntent 语义)──
// 修复背景(桌面版同源 bug 的手机版变体):近底判定原来是纯距离阈值
// (≥228px),流式期间内容增长会触发 handleContentSize 的 scrollToEnd 与
// LegendList 内置 maintainScrollAtEnd。用户慢速小幅上滑(未超过阈值)松手后,
// 距底仍在阈值带内 → 仍被判「近底」→ 下一帧内容增长又被拽回最底。触摸惯性
// 大多一次就滑出阈值,所以比桌面版难触发,但结构性竞态相同。
// 修复:「解除」看手势意图(拖动中向上位移超过死区,只有用户能产生),
// 「恢复」要求 scroll 方向明确向下——否则解除后紧跟着的上滑 scroll 事件
// (距底仍在阈值带内)会把刚解除的跟随立刻翻回去。
// 恢复的距离只认「真正到底」(MOBILE_FOLLOW_REPIN_END_TOLERANCE),不用 228px
// 的近底阈值带:停在距底两三行时,手指微调或抬手那一下常有几 px 的向下位移,
// 会被当成「滑回底部」恢复跟随,松手后的落底校验随即把列表拽到最新。
/**
* 拖动解除跟随的累计位移死区(px)。手指按住不动也有 ±2-3px 抖动,取 8px
* 与桌面版 touch 意图阈值(TOUCH_HISTORY_INTENT_THRESHOLD_PX)同源;
* 真实的「上滑一行」轻松超过它,解除仍然是「一滑即停」的体感。
*/
export const MOBILE_FOLLOW_UNPIN_DRAG_DEAD_ZONE = 8;
/**
* 恢复跟随的单事件方向死区(px)。scroll 事件的 offsetY 是浮点布局值,
* 1px 内的增量不算「明确向下」。
*/
export const MOBILE_FOLLOW_REPIN_DIRECTION_DEAD_ZONE = 1;
/**
* 已解除跟随时,恢复跟随允许的距底容差(px,相对内容末端 offset)。底部留白
* 已计入 contentHeight,到达末端即最后一条消息完整露出;容差约一行字,
* 吸收亚像素与回弹误差,但停在距底两三行处不会被判为「回到底部」。
*/
export const MOBILE_FOLLOW_REPIN_END_TOLERANCE = 24;
/** 容器「真的可滚」的最小内容富余(px),亚像素圆整内视为不可滚。 */
const MOBILE_FOLLOW_MIN_SCROLLABLE_PX = 1;
export interface MobileFollowUnpinInput {
/** 当前处于用户拖动手势中(onScrollBeginDrag ~ onScrollEndDrag)。 */
dragging: boolean;
/** 本次拖动起点的 contentOffset.y;非拖动期为 null。 */
dragStartOffsetY: number | null;
/** 当前滚动 metrics。 */
metrics: MessageScrollMetrics;
}
/**
* 用户拖动是否构成「想向上回看、应解除贴底跟随」。
*
* 条件(全部满足):
* - 处于拖动手势中:拖动期间的 offset 变化只可能由用户产生(原生层在活跃
* 手势期基本忽略程序化 scrollTo),不会误伤程序化贴底/补偿滚动;
* - 相对拖动起点累计向上超过死区:按住不动的抖动不算;
* - 内容可滚:未撑满一屏时解除毫无视觉意义,却会在内容长出滚动区后表现为
* 「不跟了」且无法用「滑回底部」恢复。
*/
export function shouldUnpinMobileFollowOnDrag(input: MobileFollowUnpinInput): boolean {
if (!input.dragging || input.dragStartOffsetY === null) return false;
const { contentHeight, offsetY, viewportHeight } = input.metrics;
if (contentHeight - viewportHeight <= MOBILE_FOLLOW_MIN_SCROLLABLE_PX) return false;
return offsetY < input.dragStartOffsetY - MOBILE_FOLLOW_UNPIN_DRAG_DEAD_ZONE;
}
export interface MobileNearBottomResolveInput {
/** scroll 事件前的跟随态(nearBottomRef)。 */
wasNearBottom: boolean;
/** 当前滚动 metrics。 */
metrics: MessageScrollMetrics;
/** 本次 scroll 事件的 offsetY 增量(正 = 向内容末端)。 */
scrollDelta: number;
/** 底部浮层高度(近底阈值随之放大,同 isNearMobileMessageListBottom)。 */
bottomOverlayHeight?: number;
/**
* Whether the event was emitted while an imperative list scroll is settling.
* Native list implementations can report a transient offset before the
* commanded end position is applied; that event must not cancel auto-follow.
*/
programmaticScrollInFlight?: boolean;
}
/**
* scroll 事件驱动的近底/跟随态迁移(handleScroll 消费)。
*
* - 命令式滚动 settling → 保持原跟随态,不把瞬时 offset 当成用户上翻;
* - 内容未撑满一屏 → true(与 isNearMessageListBottom 同口径);
* - 距底超出阈值且(已解除, 或明确上滑) → false(滚动条/拖动离底的兜底)。
* 已在跟、只是内容在下方长高导致距底越线时保持跟随 — 发送后首块
* assistant / 工具卡撑高不得把跟随掐死;
* - 阈值带内且原本在跟 → 保持 true(贴底期间程序化 scrollToEnd 产生的
* 向下增量、以及被动微小位移都不改变状态);
* - 已解除 → 仅「明确向下」(增量 > 死区)且真正到底(距末端 ≤
* MOBILE_FOLLOW_REPIN_END_TOLERANCE)才恢复跟随。**不能只看距离**:拖动解除后
* 同一手势内继续到达的上滑 scroll 事件仍可能贴近末端,无方向守卫会立即翻回
* 跟随;**也不能用近底阈值带**:停在距底几行处的手指微调/抬手位移会误恢复。
*/
export function resolveMobileNearBottomOnScroll(input: MobileNearBottomResolveInput): boolean {
if (input.programmaticScrollInFlight) return input.wasNearBottom;
const { contentHeight, offsetY, viewportHeight } = input.metrics;
if (contentHeight <= viewportHeight) return true;
if (!input.wasNearBottom) {
return input.scrollDelta > MOBILE_FOLLOW_REPIN_DIRECTION_DEAD_ZONE
&& mobileMessageListEndOffset(input.metrics) - offsetY <= MOBILE_FOLLOW_REPIN_END_TOLERANCE;
}
if (isNearMobileMessageListBottom(input.metrics, input.bottomOverlayHeight)) return true;
return input.scrollDelta >= -MOBILE_FOLLOW_REPIN_DIRECTION_DEAD_ZONE;
}
export interface MobileHistoryBrowseIntentInput {
/** The reader explicitly requested or dragged into older history. */
historyBrowseIntent: boolean;
/** A finger drag or its native momentum currently owns the viewport. */
userControllingScroll: boolean;
}
/**
* Keep history browsing authoritative across app/native anchor corrections.
*
* A completed prepend can emit one more positive-offset scroll event when MVCP is re-enabled.
* Without this guard that programmatic event looks like a downward user gesture and silently
* re-pins a live session to the tail. Only an active drag/momentum may recover follow from an
* explicit history-browse intent; the jump-to-latest path clears the intent separately.
*/
export function shouldPreserveMobileHistoryBrowseIntent(
input: MobileHistoryBrowseIntentInput,
): boolean {
return input.historyBrowseIntent && !input.userControllingScroll;
}
// ── 贴底跟随的 contentSize 补滚护栏(振荡断路器)──
// 背景(bug:冷开会话消息区空白 + 无 loading + 返回键无响应,杀 App 才恢复):
// handleContentSize 的「贴底且内容长高 → 命令式 scrollToEnd」补偿,与 LegendList
// 内置 alignItemsAtEnd / maintainScrollAtEnd / mVCP(size:true)叠在同一条布局流上。
// 初始窗口里若存在测量高度不稳定的 item(异步媒体回填、字体回退重排、WebView 块
// 高度结算等),每次重测都会触发 onContentSizeChange → scrollToEnd → 再次锚定/
// 重测……命令式滚动不经 React state,「Maximum update depth」守卫不介入,回调
// 洪泛把 JS 线程打满:首帧(header)已提交、消息区停在半布局态、SyncingMessages
// 的延迟显形 timer 与一切 Pressable 全部失活。
// 护栏语义(evaluateMobileFollowEndContentSizePin):
// - 高度死区:与上次已补滚高度差在死区内(浮点/舍入噪声、同值重复回调)→ 跳过;
// - 振荡断路:跳闸信号是「高度方向翻转」而**不是**补滚频率——合法路径(冷开分批
// 渲染、流式逐行增长、媒体回填)的 contentHeight 单调递增,无论多快都不该被
// 限流(内置 maintainScrollAtEnd 对「大块一帧撑高」恰恰不兜底:它的 0.12×视口
// 距底闸在 rAF 里二次核验,单帧大增长直接被甩出阈值放弃跟随——这正是本手动
// 补滚存在的理由,review P1);病理重测环的特征是 A/B 往返振荡,滚动窗口内
// 方向翻转次数到达上限即打开断路器一段时间,期间不再手动 scrollToEnd;
// - 断路到期自动闭合;翻转计数在断路期间继续记账(不重新跳闸、不延长断路),
// 上游若仍在振荡,断路一闭合就会立刻再次跳闸,净效果是把无界洪泛钳制成
// 「每个断路周期最多一轮」的有界节奏;
// - 跳闸返回 suppressionStarted,调用方据此安排断路到期后的 one-shot 贴底清账
// (断路窗内错过的最终高度可能停在半空,且之后再无 contentSize 事件来纠正);
// 首次跳闸另返回 trippedNow,供上层打一条诊断告警(每列表实例一次,防刷屏)。
/**
* 补滚高度死区(px):与基准高度差 ≤ 此值视为噪声。与 MOBILE_ANCHOR_VERIFY_TOLERANCE
* 同源取 2px——小于任何真实的内容增长(一行文字 ≥ 20px),大于 Fabric 布局舍入抖动。
* 补滚判定基准是 lastPinnedHeight(不随被吞事件漂移,缓慢累积增长最终能逃逸死区);
* 方向观察基准是 lastObservedHeight(死区内的噪声不构成方向信号,不制造假翻转)。
*/
export const MOBILE_FOLLOW_END_PIN_HEIGHT_DEAD_ZONE = 2;
/** 振荡统计的滚动窗口(ms)。 */
export const MOBILE_FOLLOW_END_PIN_WINDOW_MS = 1000;
/**
* 窗口内允许的方向翻转次数上限。合法场景的翻转极稀:流式单调增 = 0 次;用户折叠
* 长消息 / rewind 整窗替换 = 1~2 次;LegendList 冷开 estimated→measured 向下修正
* ≈ 1 次。病理振荡环是每帧一次翻转(~60/s),100ms 便可越线。取 6:两侧安全边际
* 都在 2 倍以上。
*/
export const MOBILE_FOLLOW_END_PIN_MAX_REVERSALS_PER_WINDOW = 6;
/** 断路器打开时长(ms):给 LegendList 内置锚定一个不被外部滚动干扰的收敛窗口。 */
export const MOBILE_FOLLOW_END_PIN_SUPPRESS_MS = 2000;
/**
* 护栏状态:由 MessageRenderer 以 ref 持有,evaluate 原地更新(受控可变,滚动热路径
* 不为每次评估重建状态对象;reversalTimestamps 长度有界于窗口内事件数)。会话切换
* (scrollResetKey)与用户主动跳底(明确的重锚意图)时用工厂重建。
*/
export interface MobileFollowEndPinState {
/** 上次实际补滚时的 contentHeight;0 = 本实例尚未补滚过(首次必放行)。 */
lastPinnedHeight: number;
/** 上次越过死区的观察高度(方向翻转检测基准);0 = 尚无观察。 */
lastObservedHeight: number;
/** 上次观察到的高度变化方向;0 = 尚无方向。 */
lastDirection: 1 | -1 | 0;
/** 滚动窗口内的方向翻转时间戳(evaluate 内按窗口过滤)。 */
reversalTimestamps: number[];
/** 断路器打开截止时刻(epoch ms);0 = 闭合。 */
suppressedUntil: number;
/** 本实例是否跳闸过(诊断告警只报第一次)。 */
hasTripped: boolean;
}
export function createMobileFollowEndPinState(): MobileFollowEndPinState {
return {
lastPinnedHeight: 0,
lastObservedHeight: 0,
lastDirection: 0,
reversalTimestamps: [],
suppressedUntil: 0,
hasTripped: false,
};
}
export interface MobileFollowEndPinDecision {
/** 允许本次命令式 scrollToEnd。 */
shouldScroll: boolean;
/** 本次评估打开了断路器(调用方安排断路到期后的 one-shot 贴底清账)。 */
suppressionStarted: boolean;
/** 本次评估触发本实例首次跳闸(上层据此打一条诊断告警)。 */
trippedNow: boolean;
}
/**
* 「贴底补滚是否放行」判定。调用方已确认业务前置条件(贴底跟随中、内容超一屏、
* 非 load-earlier),这里只做护栏:方向翻转记账与跳闸 → 断路检查 → 死区去噪。
* 高度收缩(rewind / 删消息 / 用户折叠)本身不受限——收缩只是一次方向观察,
* 随后的补滚照常放行,只有窗口内反复往返才构成振荡。
*/
export function evaluateMobileFollowEndContentSizePin(
state: MobileFollowEndPinState,
input: { now: number; contentHeight: number },
): MobileFollowEndPinDecision {
const { now, contentHeight } = input;
let suppressionStarted = false;
let trippedNow = false;
// 方向观察在断路检查之前:断路期间振荡照常记账,窗口不清零,断路一闭合、
// 上游仍在抖时首个翻转就能重新跳闸(而不是重新积累一整轮)。
const observedDelta = contentHeight - state.lastObservedHeight;
if (Math.abs(observedDelta) > MOBILE_FOLLOW_END_PIN_HEIGHT_DEAD_ZONE) {
const direction: 1 | -1 = observedDelta > 0 ? 1 : -1;
if (state.lastDirection !== 0 && direction !== state.lastDirection) {
const windowStart = now - MOBILE_FOLLOW_END_PIN_WINDOW_MS;
state.reversalTimestamps = state.reversalTimestamps.filter((at) => at > windowStart);
state.reversalTimestamps.push(now);
if (
state.reversalTimestamps.length >= MOBILE_FOLLOW_END_PIN_MAX_REVERSALS_PER_WINDOW
&& state.suppressedUntil <= now
) {
state.suppressedUntil = now + MOBILE_FOLLOW_END_PIN_SUPPRESS_MS;
suppressionStarted = true;
trippedNow = !state.hasTripped;
state.hasTripped = true;
}
}
state.lastDirection = direction;
state.lastObservedHeight = contentHeight;
}
if (state.suppressedUntil > now) {
return { shouldScroll: false, suppressionStarted, trippedNow };
}
if (Math.abs(contentHeight - state.lastPinnedHeight) <= MOBILE_FOLLOW_END_PIN_HEIGHT_DEAD_ZONE) {
return { shouldScroll: false, suppressionStarted: false, trippedNow: false };
}
state.lastPinnedHeight = contentHeight;
return { shouldScroll: true, suppressionStarted: false, trippedNow: false };
}
/**
* 贴底锚定校验的判定容差:contentSize / offset 都是浮点布局值,亚像素误差不算落空。
* 取 2px:小于任何真实遮挡(一行文字 ≥ 20px),大于 Fabric 布局的舍入抖动。
*/
export const MOBILE_ANCHOR_VERIFY_TOLERANCE = 2;
/**
* 校验补滚上限:每次补滚目标幂等(同一 end offset),多滚无视觉副作用,上限只为防
* 目标不可达(如 metrics 偏大被原生截停)时空转。6 次 × 双帧 ≈ 200ms 内收敛。
*/
export const MOBILE_ANCHOR_VERIFY_MAX_ATTEMPTS = 6;
/**
* 校验等待上限(独立于补滚预算):列表布局还在结算 / metrics 未就绪时环只等不滚,等待
* 不消耗补滚额度——否则连续的行身份 / size 调整会先把 6 次补滚预算烧光,布局安静后
* 反而没额度补滚,遮挡残留(review P1)。双帧一轮约 33ms,75 轮约 2.5s;超过该
* 上限说明布局持续变化或状态异常,结束环交给后续 contentSize 事件继续跟随。
*/
export const MOBILE_ANCHOR_VERIFY_MAX_WAIT_ROUNDS = 75;
/**
* LegendList 没有公开“本轮行坐标 / native size 调整已完成”信号。行身份 / size 变化后
* 保留一个短安静窗:期间 verifier 只等待;连续流式测量会延长窗口,但仍受上面的 2.5s
* 总等待预算约束。120ms 约 7 帧,覆盖 JS commit、native layout 与滚动回传的常见链路。
*/
export const MOBILE_MVCP_SETTLE_QUIET_MS = 120;
export function mobileMvcpSettleDeadline(previousDeadline: number, now: number): number {
return Math.max(previousDeadline, now + MOBILE_MVCP_SETTLE_QUIET_MS);
}
export function isMobileMvcpSettling(now: number, settleAt: number): boolean {
return now < settleAt;
}
/**
* 只在行身份变化时续 mVCP 安静窗。流式更新会反复换 `items` 数组引用、但 key 不变;
* 若按数组引用续窗,verifier 会在整轮生成期间一直 wait,直到 2.5s 预算耗尽。
*/
export function mobileMessageListKeysSignature(keys: readonly string[]): string {
return keys.join('\0');
}
export interface MobileAnchorVerifyInput {
attempts: number;
listVisible: boolean;
metrics: MessageScrollMetrics;
preserveVisibleContentPosition: boolean;
stickToLatest: boolean;
/** Finger drag / native momentum owns the viewport, including iOS overscroll bounce. */
userControllingScroll: boolean;
waitRounds: number;
}
export type MobileAnchorVerifyAction =
/** 已贴底(或用户已接管滚动),校验结束。 */
| 'settled'
/** 未贴底且允许补滚:重发一次落底 scrollToOffset 后继续校验。 */
| 'retry'
/** 暂不能判定/不能滚(mVCP 还开着、metrics 未就绪):下一轮再校验。 */
| 'wait'
/** 重试预算耗尽,放弃(交给后续 contentSize / layout 事件的常规跟随)。 */
| 'give-up';
/**
* 贴底锚定校验判定(纯函数,供 MessageRenderer 的 verify 环使用)。
*
* 背景:贴底跟随的落底 scrollToOffset 存在两类静默落空——
* (a) 行坐标或 size 锚定尚在结算的帧里执行,被后续布局调整吸收/抵消;
* (b) 落底一刻 scrollMetricsRef 里的 contentHeight / viewportHeight 是陈旧值,目标
* offset 偏短或内容收缩后偏长,且之后再无 contentSize / layout 事件来纠正。
* 偏短会把最新消息留在 composer 后面,偏长会把消息顶上去并留下尾部空白。
* 用户没有控制滚动时,校验 offset 与真实末端的双向距离,未到位则带上限补滚。
*/
export function evaluateMobileAnchorVerify(input: MobileAnchorVerifyInput): MobileAnchorVerifyAction {
if (!input.stickToLatest || !input.listVisible) return 'settled';
// 行坐标 / size 锚定仍在 settle 窗口:此刻补滚可能被后续布局吸收,下一轮再判。
// 等待走独立预算,不消耗补滚额度。
const { contentHeight, offsetY, viewportHeight } = input.metrics;
if (input.userControllingScroll || input.preserveVisibleContentPosition || contentHeight <= 0 || viewportHeight <= 0) {
return input.waitRounds >= MOBILE_ANCHOR_VERIFY_MAX_WAIT_ROUNDS ? 'give-up' : 'wait';
}
// 不足一屏时也必须回到 0;原生测量收缩后残留的正 offset 不是有效的贴底位置。
const endOffset = mobileMessageListEndOffset(input.metrics);
if (Math.abs(offsetY - endOffset) <= MOBILE_ANCHOR_VERIFY_TOLERANCE) return 'settled';
if (input.attempts >= MOBILE_ANCHOR_VERIFY_MAX_ATTEMPTS) return 'give-up';
return 'retry';
}
/** 顶部让位后额外的呼吸间距:第一条消息与工具栏 hairline 分隔线之间留一点空隙。 */
const MOBILE_MESSAGE_LIST_TOP_GAP = 8;
/**
* 顶部 chrome(绝对定位的半透明工具栏)高度 → 列表内容顶部让位。
* chrome 浮在列表之上,不让位的话滚到历史最顶端时第一条消息永远被工具栏盖住、再也滑不出来;
* 让位只加在内容起点,滚动途中内容仍从工具栏下方穿过,半透明效果不变(与 bottomOverlayHeight 同款模式)。
*/
export function mobileMessageListTopPadding(topOverlayHeight?: number): number {
if (typeof topOverlayHeight !== 'number' || !Number.isFinite(topOverlayHeight) || topOverlayHeight <= 0) {
return 0;
}
return Math.ceil(topOverlayHeight) + MOBILE_MESSAGE_LIST_TOP_GAP;
}
export interface MobileTopPaddingCompensationInput {
previousTopPadding: number;
nextTopPadding: number;
offsetY: number;
stickToLatest: boolean;
preserveVisibleContentPosition: boolean;
listVisible: boolean;
}
/**
* 顶部让位(paddingTop)在阅读中途变化时的 offset 补偿目标(review P2)。
* 场景:chrome 实高会因连接横幅出现/消失而变,paddingTop 随之突变;稳态阅读时 mVCP 未开启,
* contentSize 变化走 skip 分支、contentOffset 不动,可见内容会整体跳 padding delta。
* 返回补偿后的目标 offset;返回 null 表示不需要补偿:
* - 贴底跟随中(stickToLatest):contentSize follow 分支自会重锚到底;
* - preserve 窗口开着(load-earlier / open-settle):mVCP 正锚着首个可见 cell,会自行吸收上方位移,
* 再手动补偿会双重位移;
* - 列表未揭开:揭开路径自己定位;
* - 停在最顶(offset<=0):让位本来就该把内容推下来给横幅腾位,补偿反而会把第一条消息藏回横幅下。
*/
export function mobileTopPaddingCompensationOffset(input: MobileTopPaddingCompensationInput): number | null {
const delta = input.nextTopPadding - input.previousTopPadding;
if (delta === 0) return null;
if (input.stickToLatest || input.preserveVisibleContentPosition || !input.listVisible) return null;
if (input.offsetY <= 0) return null;
return Math.max(0, input.offsetY + delta);
}
/**
* 「加载更早」预取触发距离:离顶还有约两屏时就开始拉上一页,而不是撞到顶(旧默认 96px)才拉。
* 目标是无感翻页——用户滑到旧内容顶端之前,更早的消息已经 prepend 完毕,浏览像连续对话一样;
* 同时触发时刻锚点(首个可见消息 cell)远离接缝,应用层视口补偿也最稳定。
* 视口高度未知(布局前)时退回旧默认,不凭空放大。
* 不会级联连拉:每页 80 条消息的高度远超两屏,prepend 落地后手动锚定会顶高 offsetY、立即脱离阈值。
* 边界假设(review P2):上一行成立的前提是页均高度 > 两屏,即平均每条 > viewportHeight/40
* (典型视口 844px 约 21px/条,低于单行气泡的最小实高)。理论上整页全是极短消息才可能连拉一页,
* 且有 loadingEarlier 门禁串行化,最坏是多拉一页,不会失控循环。
*/
export function mobileLoadEarlierPrefetchThreshold(viewportHeight: number): number {
return historyPrefetchThreshold(viewportHeight);
}
export interface MobileAutoLoadEarlierDecisionInput {
/** 「加载更早」动作当前不可点(加载中)。 */
actionDisabled: boolean;
/** 「加载更早」入口可见(hasOlderMessages 且列表非空)。 */
actionVisible: boolean;
/** 列表当前贴在内容末端(LegendList getState().isAtEnd,含应用层 prepend 补偿后的记账)。 */
atEnd: boolean;
/** 列表当前也贴在内容开头;与 atEnd 同时成立才说明内容未撑满视口。 */
atStart: boolean;
/** 当前最旧的历史游标;调用方没有游标时退回首个渲染项 key。 */
progressKey: string | null;
/** 冷开补齐预算尚有余额;仍需 atStart + atEnd 确认视口未填满。 */
initialAutoFillAllowed: boolean;
/** 上一次自动触发时的历史游标;相同说明上次尝试无进展(失败/重复页),不再自动重试。 */
lastAttemptedProgressKey: string | null;
/** 列表处于近顶预取区(LegendList getState().isNearStart,阈值 = onStartReachedThreshold × 视口)。 */
nearStart: boolean;
/** 用户产生过真实上翻意图(拖动 / 上跳导航);冷开初始布局不算。 */
userScrolledForOlder: boolean;
}
/**
* 「自动加载更早」的电平触发判定(纯函数,MessageRenderer 每个可能改变结果的时机都重新评估)。
*
* 背景(bug:停在顶部但更早消息永远不自动加载):LegendList 的 onStartReached 是**边沿触发**——
* 触发过一次后,要么滚离顶部超过 threshold × 1.3(迟滞)再回来、要么阈值内发生 data 变化,才会再发。
* 而 handleStartReached 里有一组业务 guard(用户没拖动过 / 正在加载 / hasOlderMessages 未就绪),
* guard 不满足时这次边沿被直接吞掉;之后 guard 条件就绪,却再也等不到下一个边沿:
* - 短加载窗口(内容总高 < ~3.6 屏)冷开时列表底部就落在近顶阈值内,边沿在用户拖动前就被消费,
* 用户之后永远滚不出 1.3 × 阈值的复位区 → 永久哑火(实机高频复现的截图场景);
* - 上一页在途时到达顶部(disabled guard 吞边沿),加载完成后停在顶部无任何重评估 → 哑火。
* 修复:把判定改成电平语义——nearStart / atEnd 直接读 LegendList getState() 的实时账
* (它的 scroll 记账会接收应用层 prepend 锚点补偿,app 侧 onScroll 的原生 offsetY 在提交瞬间不可信),
* 并在 scroll 事件、onStartReached、eligibility 变化(加载结束/入口点亮/首项变化)时都重新评估。
*
* 防失控:
* - 用户浏览态 atEnd 时不触发:贴底跟流不因自动预取被关掉 end-pin;只有冷开有界补齐
* 允许短窗口同时 nearStart + atEnd 时拉取;
* - progressKey 去重:一次尝试后必须看到历史游标变化(真有 prepend)才允许下一次,
* 加载失败或拉回重复页(host cursor 未命中返回最新页)不会无限重试;用户重新拖动时清除,
* 保证手势永远能重新驱动一次尝试。
*/
export function shouldAutoLoadEarlier(input: MobileAutoLoadEarlierDecisionInput): boolean {
if (
!input.userScrolledForOlder
&& (!input.initialAutoFillAllowed || !input.atStart || !input.atEnd)
) return false;
if (!input.actionVisible || input.actionDisabled) return false;
if (!input.nearStart) return false;
// A short window can be both atStart and atEnd. After an explicit upward drag, allow it to
// request the previous page; only suppress user-driven prefetch when a longer list is still
// pinned at the latest edge without also being at the history edge.
if (input.atEnd && input.userScrolledForOlder && !input.atStart) return false;
if (!input.progressKey) return false;
return input.lastAttemptedProgressKey !== input.progressKey;
}
export function findMobileRenderItemKeyByClientId(
items: readonly MobileMessageRenderItem[],
clientId: string | null | undefined,
): string | null {
if (!clientId) return null;
for (const item of items) {
const key = findClientIdInRenderItem(item, clientId, item.key);
if (key) return key;
}
return null;
}
function findClientIdInRenderItem(
item: MobileMessageRenderItem | MobileWorkChildItem,
clientId: string,
scrollTargetKey: string,
): string | null {
if (item.type === 'message' && mobileMessageClientId(item.message) === clientId) {
return scrollTargetKey;
}
if (item.type === 'thinking' && mobileMessageClientId(item.message) === clientId) {
return scrollTargetKey;
}
if (item.type === 'tool_group') {
return item.tools.some((tool) => (tool.source.clientId || tool.source.id || tool.key) === clientId)
? scrollTargetKey
: null;
}
if (item.type === 'agent_task') {
const tool = item.toolCall;
return tool && (tool.source.clientId || tool.source.id || tool.key) === clientId ? scrollTargetKey : null;
}
if (item.type === 'work_group') {
for (const child of item.children) {
const key = findClientIdInRenderItem(child, clientId, scrollTargetKey);
if (key) return key;
}
}
if (item.type === 'subagent_group') {
for (const child of item.childItems) {
const key = findClientIdInRenderItem(child, clientId, scrollTargetKey);
if (key) return key;
}
}
return null;
}
function mobileMessageClientId(message: NormalizedRemoteMessage): string {
return message.source.clientId || message.source.id || message.key;
}