Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* viewportFillDetect — 修复"短 session 滚动死锁"的触发判定纯函数集。
* ---------------------------------------------------------------------------
* 修复背景: MessageStream 的 scroll 容器是 `h-full`(撑满视口),contentRef
* 在内容很少时高度 < 容器,scrollHeight === clientHeight,scrollbar 不出现 →
* `handleScroll` 里"距顶 < 50px → expandWindow / onLoadMore"的分支永远不触发
* → 内存里 render-window 之外的更老 render-item 扩不进 DOM,DB 里更老的历史
* 也拉不进来 (典型 case: 渲染单元少、单 item 短,contentH ~500px << 视口 1354px)。
*
* 这个模块抽出 caller (MessageStream useLayoutEffect) 二段式编排所需的纯函数:
* - shouldAutoExpandRenderWindow: Stage 1 — 内存里有未显示的 render-item 就
* 扩 render-window
* - shouldAutoLoadMoreHistory: Stage 2 — render-window 已覆盖全部 render-item,
* 再 IPC 拉 DB
* - decideAutoFillAction: 编排两段, 返回最终 action enum 给 caller switch
*
* ── 度量轴说明 ──
* 本 helper 接收的 `scrollHeight` / `clientHeight` 是像素,`windowAtTop` /
* `hasMoreMessages` / `isLoadingMore` 是布尔状态 — 全部与"消息条数"还是
* "渲染单元数"无关。caller 在 render-item 轴下喂入这些参数(windowAtTop =
* `visibleRenderItems.length === allRenderItems.length`),helper 内部逻辑零改动。
*
* 抽成纯函数为了:
* - 单测覆盖各种 (scrollH, clientH, windowAtTop, hasMore, loading, attempt) 组合
* - 决策逻辑清晰,与 React effect 的副作用解耦
* - 跟 scrollAnchoringDetect 同样的 pattern,方便维护
*/
/**
* 自动拉取的最大尝试次数(per MessageStream mount)。
* 防御退化场景: DB 里几千条消息但渲染单元密度极低(例如几乎全是被丢弃的
* orphan tool_result / ask_user / AskUserQuestion / ExitPlanMode,或者一个已完成
* 长 turn 折叠成少量 work_group)的会话,每次拉 50 条 contentH 几乎不增长,会一直
* 命中条件无限循环。MAX_AUTO_LOAD_ATTEMPTS=5 ≈ 250 条历史后还撑不满 viewport
* 就停手,避免打开会话时自动烧太多本地 IPC / 远程隧道往返。
*
* 选 5 的依据: 自动补载只负责首屏自愈,不是无上限地替用户翻历史。若 250 条
* 仍不够撑出滚动区域,MessageStream 会在用户明确向上滚动 / 翻页时走
* decideUserIntentFillAction 继续加载,不会再被这个自动预算卡死。
*
* 注: 渲染窗口下移到 render-item 轴后,以前"末尾窗口全 orphan → 拉再多也
* 还是空 items → 命中 cap 才停"的恶性退化已经消除(orphan 在 buildRenderItems
* Pass 2 就被丢弃,不会出现在 allRenderItems 末尾)。本 cap 仍保留作为最后
* 一道防线。
*/
export const MAX_AUTO_LOAD_ATTEMPTS = 5;
/**
* scrollHeight === clientHeight 的判等容差(px)。
*
* 严格 `!==` 在 DPR=1 的环境下没问题(scrollHeight / clientHeight 都是整数)。
* 但 Windows 缩放 125%/150% / Retina 等 DPR≠1 环境下,sub-pixel 取整可能让
* `scrollHeight = clientHeight + 1`(差 1 像素)。此时:
* - 用户视觉上滚不动(1px 差异 thumb 都拉不出)
* - 严格判等会判 "≠" → auto-fill 不触发 → 死锁原态复发
* 所以判据放宽到 `|delta| <= NO_SCROLL_TOLERANCE_PX`,1px 内仍视为"不可滚"。
*
* 选 1 的依据: sub-pixel 圆整最大 1px(浏览器 layout 引擎规范);取 2+ 会让
* "本来 scrollH 比 clientH 高一点点(用户能看到 thumb)的场景"被错误地当作
* 死锁去 auto-fill,不必要。
*/
export const NO_SCROLL_TOLERANCE_PX = 1;
/**
* 「贴顶」判定阈值(px)——与 MessageStream handleScroll 的"距顶 < 50px 触发
* 后续加载"用同一个值,两处判定必须一致:handleScroll 靠 scroll 事件在
* *穿过*这个区间时触发,decideUserIntentFillAction 靠 wheel/touch/键盘意图在
* *停在*这个区间时触发,合起来才覆盖"到顶后继续上滚"的完整路径。
*/
export const TOP_HISTORY_TRIGGER_PX = 50;
export interface ViewportFillCheckArgs {
/** scroll 容器当前的 scrollHeight */
scrollHeight: number;
/** scroll 容器当前的 clientHeight (视口高度) */
clientHeight: number;
/** DB 里是否还有更老的消息可以拉 */
hasMoreMessages: boolean;
/** 是否正在拉取上一批(防止重入) */
isLoadingMore: boolean;
/** 当前 mount 已经触发了多少次自动拉取 */
attemptCount: number;
/** 上限,默认 MAX_AUTO_LOAD_ATTEMPTS */
maxAttempts?: number;
}
/**
* 判断是否应该主动触发 onLoadMore 把 viewport 装满。
*
* 触发条件 (全部满足才返回 true):
* - scrollHeight === clientHeight: 容器没有可滚动空间(用户无法手动触发)
* - hasMoreMessages: DB 里确实还有可拉的更老消息
* - !isLoadingMore: 上一次拉取已结束(防止 IPC 重入)
* - attemptCount < maxAttempts: 没超过退化保护上限
*
* 不触发的语义:
* - 容器有滚动空间 → 用户可手动滚到顶触发原生 onLoadMore,不需要自动
* - 没有更多历史 → 拉了也是空,白浪费 IPC
* - 正在加载 → 等当前批回来后再判
* - 超上限 → 退化场景,让用户接管
*/
export function shouldAutoLoadMoreHistory({
scrollHeight,
clientHeight,
hasMoreMessages,
isLoadingMore,
attemptCount,
maxAttempts = MAX_AUTO_LOAD_ATTEMPTS,
}: ViewportFillCheckArgs): boolean {
// sub-pixel 容差: 见 NO_SCROLL_TOLERANCE_PX 说明。Math.abs 防御 scrollH<clientH
// 的异常输入(实际 DOM 不会出现, 但测试 stub / 边界 case 防一手)。
if (Math.abs(scrollHeight - clientHeight) > NO_SCROLL_TOLERANCE_PX) return false;
if (!hasMoreMessages) return false;
if (isLoadingMore) return false;
if (attemptCount >= maxAttempts) return false;
return true;
}
export interface ExpandWindowCheckArgs {
/** scroll 容器当前的 scrollHeight */
scrollHeight: number;
/** scroll 容器当前的 clientHeight */
clientHeight: number;
/** 当前 render-window 是否已经覆盖内存里所有 render-item
* (true = visibleRenderItems.length === allRenderItems.length) */
windowAtTop: boolean;
}
/**
* 判断是否应该主动调 expandWindow 把 render-window 往前(更早)扩。
*
* 背景: MessageStream 用 RENDER_WINDOW_INITIAL_ITEMS=80 限制初始渲染量(切大
* session 不卡)。当 onLoadMore 把更老消息 prepend 进 messages 数组、
* buildRenderItems 重算让 allRenderItems 增长时,如果 firstVisibleItemKey
* 锚点没动,visibleRenderItems 的 slice 边界把新 prepend 出来的 render-item
* 切在外面 → DOM 不渲染 → contentH 不增长 → scrollH 永远 === clientH → 死锁。
*
* 触发条件 (全部满足才返回 true):
* - scrollHeight === clientHeight: viewport 没滚动 (用户也滚不出 onLoadMore)
* - !windowAtTop: render-window 还没覆盖内存全部 → 内存里有可显示的 item、却没显示
*
* 与 shouldAutoLoadMoreHistory 的关系: caller (MessageStream) 应该**先**判
* expand (无 IPC、纯前端),expand 不出滚动条再判 load (IPC、计 attempt)。
* mirror handleScroll 里 "二段式加载" 注释段的同款逻辑(`!windowAtTop` →
* expand, 否则 onLoadMore)。
*
* 不计入 MAX_AUTO_LOAD_ATTEMPTS: expand 是纯前端操作不打 IPC。
*
* ── 终止性 ──
* Stage 1 (本函数) 单步无独立 cap。单次 messages 快照下,expandWindow
* 的 `currentStartIdx <= 0 return` 给出下界。完整循环里 Stage 2 (onLoadMore)
* 每次 prepend ~50 条让 allRenderItems.length 单调增长,Stage 1 才能继续 expand;
* Stage 2 的 MAX_AUTO_LOAD_ATTEMPTS 给整段循环上界。
*
* 渲染窗口下移到 render-item 轴后,每次 Stage 1 expand 至少多吸收一个 item
* (orphan / ask_user / AskUserQuestion / ExitPlanMode 全部在 buildRenderItems
* Pass 2 就被丢弃,不会"扩了 N 条 message 却多 0 个 item"),不再有以前以
* 消息条数切窗时的恶性退化。Stage 1 单步纯本地,误循环代价远低于 Stage 2,
* 当前不给 Stage 1 独立 cap;若未来重构改了上述假设(例如 build 内引入新的
* 异步副作用),优先给 Stage 1 加 `MAX_AUTO_EXPAND_ATTEMPTS` 而不是依赖 Stage 2。
*/
export function shouldAutoExpandRenderWindow({
scrollHeight,
clientHeight,
windowAtTop,
}: ExpandWindowCheckArgs): boolean {
// sub-pixel 容差: 见 NO_SCROLL_TOLERANCE_PX 说明。Math.abs 防御 scrollH<clientH
// 的异常输入(实际 DOM 不会出现, 但测试 stub / 边界 case 防一手)。
if (Math.abs(scrollHeight - clientHeight) > NO_SCROLL_TOLERANCE_PX) return false;
if (windowAtTop) return false;
return true;
}
/**
* 二段式决策的最终输出。caller (MessageStream) 直接 switch 这个 enum 决定走 expand
* 还是 load。'none' = 不做任何 IPC/DOM 操作。
*/
export type AutoFillAction = 'none' | 'expand-window' | 'load-from-db';
export interface AutoFillDecisionArgs {
scrollHeight: number;
clientHeight: number;
windowAtTop: boolean;
hasMoreMessages: boolean;
isLoadingMore: boolean;
attemptCount: number;
maxAttempts?: number;
}
export type UserIntentFillDecisionArgs = Omit<
AutoFillDecisionArgs,
'attemptCount' | 'maxAttempts'
> & {
/** scroll 容器当前的 scrollTop(判定"停在顶部"用) */
scrollTop: number;
/** Explicit upward input can prefetch before reaching the history boundary. */
triggerDistancePx?: number;
};
/**
* MessageStream 自动拉历史的二段式决策编排函数。
*
* caller (MessageStream useLayoutEffect) 用单点 switch 调它,根据返回的 action
* 走对应副作用 (expandWindow / onLoadMore)。这样把"先 expand 再 load"的核心
* 逻辑显式化为一个纯函数,可单测,而不是散在 React effect body 里靠 if/return
* 链表达。
*
* ── 为什么独立成 helper 而不是让 caller 各调两个 helper ──
* 如果 caller 直接调 shouldAutoLoadMoreHistory 而漏掉 expand 检查 (二段式
* 写错成单段式), helper 各自的 unit test 仍然全绿但组合是错的 — onLoadMore
* prepend 回来的更老消息会被 render-window slice 切掉, 实际触发若干次空 IPC
* 而 contentH 不增长的死锁。把组合逻辑也抽成纯函数 + 测试,可在不依赖 React
* 集成测试的前提下捕获顺序错误 / 未来重构时的回归。
*
* ── 优先级 ──
* 1. 'expand-window' 优先于 'load-from-db' — expand 是纯前端 (无 IPC、即时)、
* 且 prepend 进来的更老消息只有先扩 render-window 才进 DOM,跳过 expand
* 直接 load 会让 DB 拉回的内容看不见,scrollH 不增长,死锁。
* 2. 任意一个 helper 返回 false → 走下一阶段。
* 3. 两个都 false → 'none'。
*/
export function decideAutoFillAction({
scrollHeight,
clientHeight,
windowAtTop,
hasMoreMessages,
isLoadingMore,
attemptCount,
maxAttempts,
}: AutoFillDecisionArgs): AutoFillAction {
if (shouldAutoExpandRenderWindow({ scrollHeight, clientHeight, windowAtTop })) {
return 'expand-window';
}
if (
shouldAutoLoadMoreHistory({
scrollHeight,
clientHeight,
hasMoreMessages,
isLoadingMore,
attemptCount,
maxAttempts,
})
) {
return 'load-from-db';
}
return 'none';
}
/**
* 用户明确向上滚动 / 翻页时的兜底。两类场景在这里接住(共同点:都不会再产生
* scroll 事件,handleScroll 帮不上忙):
*
* 1. **容器不可滚**(scrollHeight ≈ clientHeight)——短 session 死锁原案。
* 2. **容器可滚,但已停在顶部 TOP_HISTORY_TRIGGER_PX 内**——快速滚到顶时穿过
* 触发区的 scroll 事件可能因上一次加载 in-flight 被 handleScroll 的
* isLoadingMore 守卫吃掉,等加载完用户已停在 scrollTop=0;此后 wheel 上滚
* 不再产生 scroll 事件,若不在这里接住,用户必须"往下滚一下再往上"才能
* 继续翻页(2026-07 用户实报)。
*
* 判定与 handleScroll 的"距顶 < 50px"分支同口径:先 expand(纯本地)后 load
* (IPC);不受 MAX_AUTO_LOAD_ATTEMPTS 限制——自动预算耗尽后,用户继续表达
* "我要看更早历史"就应该继续加载,不能要求切走再切回来重置 mount-local 计数器。
*/
export function decideUserIntentFillAction({
scrollTop,
scrollHeight,
clientHeight,
windowAtTop,
hasMoreMessages,
isLoadingMore,
triggerDistancePx = TOP_HISTORY_TRIGGER_PX,
}: UserIntentFillDecisionArgs): AutoFillAction {
const unscrollable = Math.abs(scrollHeight - clientHeight) <= NO_SCROLL_TOLERANCE_PX;
const parkedNearTop = scrollTop < triggerDistancePx;
if (!unscrollable && !parkedNearTop) return 'none';
// expand 优先于 load,原因同 decideAutoFillAction 的「优先级」注释;expand 不看
// isLoadingMore(纯本地扩窗与 in-flight IPC 不冲突,与既有语义一致)。
if (!windowAtTop) return 'expand-window';
if (hasMoreMessages && !isLoadingMore) return 'load-from-db';
return 'none';
}