ZCode 超长会话的卡顿观测与缓解插件
把“卡不卡”变成可读的数字,在不改会话数据的前提下减少卡顿。
不读写 db.sqlite · 不读会话正文 · 不开 CDP · 不联网上报 · 一键还原
下面是在演示页面运行真实 observer 的截图:数据来自模拟卡顿,不含任何真实会话内容。
ZCode 桌面版超长会话卡顿的观测与缓解插件。它做两件事:
- 把"卡不卡"变成可读的数字——帧间隔、投影提交速率、主线程长任务;
- 在不修改会话数据的前提下,合并高频渲染通知,并拦住进入大历史会话时的一次性全量补拉。
所有缓解项都可以单独关闭;全部关闭后,三处宿主包装(subscribe / loadAllOlder / loadOlder 观测)会还原为原始实现,观测仍按"观测"开关运行,角标常驻(布局受限时自动隐藏)。插件不读写 db.sqlite、不改消息与会话内容、不开 CDP 端口、不联网上报。网络请求只有一类:检查更新——手动点击时请求一次公开 GitHub Releases;自动检查默认关闭,开启后 24 小时内最多一次,结果只写本机 localStorage。
社区项目,非 ZCode 官方功能。通过修改
app.asar加载,依赖客户端内部 DOM 与接口;ZCode 大版本改版可能需要适配。MIT License,按「现状」提供。
长会话卡顿通常不是单一原因。zcode-lagfix 把它们拆成三条独立指标,避免"帧率低"和"提交太频繁"混为一谈:
| 指标 | 采集方式 | 回答的问题 |
|---|---|---|
| 帧间隔 | requestAnimationFrame 相邻时间戳 |
界面看上去卡不卡 |
| 提交速率 | [data-session-id] 上 data-projection-seq 的变化 |
宿主投影提交有多频繁(负载,不是帧率) |
| 长任务 | PerformanceObserver("longtask") |
主线程被单次阻塞多久、多少次 |
插件版本演进:
- v0.1:观测与实时角标,建立采集基线。
- v0.2:投影订阅通知节流,解决流式期间高频重渲染。
- v0.3.0:状态条移到输入框上方且只在主页面显示;新增四项可逐项关闭的性能增强;日志预算与当前日志量展示;市场安装支持一键卸载。
- v0.3.1:新增滚动窗口、
loadOlder与输入延迟三项只读观测;滚动期临时隐藏消息层遮罩;角标改为常驻(删除隐藏开关);设置面板重排为 状态条 / 观测 / 性能 / 维护;「检查更新」可用(手动请求一次 GitHub Releases)。 - v0.3.2:新增多会话归因(按
sid分桶记录提交/帧、DOM、挂载 turn、滚动 P95,最多 5 个)与loadOlder最近 10 次明细(耗时/行数/触发来源);只读、默认开,不改宿主行为;/lagfix report新增对应两段。 - v0.3.3:新增侧栏开合 420ms 保护、面板常开期保护与回前台 700ms 保护,默认开、可单独关;新增
pane/refocus只读归因(开合帧 P95、面板宽度、后台时长、回前台帧 P95/合并补发数);/lagfix report新增「侧栏开合」「回前台」两段;设置面板的「!」说明统一改成「会做什么 / 不会做什么 / 代价」的大白话。 - v0.3.4:新增卡顿来源定位(只读,记录 ≥100 毫秒长帧的脚本归属与强制布局时长,回答「卡的时候到底在忙什么」);新增两项默认关闭的实验缓解——大会话翻页降频(窗口超 3000 行时上翻补页至少间隔 600ms,减少 1–2 秒长加载扎堆)与长回合渲染减负(屏幕外的消息块跳过绘制,内容不折叠不隐藏);
/lagfix report新增「卡顿来源定位」「翻页降频」两段。后端每次补页的全量过滤是 ZCode 自身成本,插件只能减少触发次数,不包装成已解决。 - v0.3.5:长帧归因补上上下文——每条 ≥100 毫秒长帧记录距上次通知、补发、滚动、消息提交的时间,并归类为节流补发 / 通知到达 / 滚动 / 其它;样本新增面板开合与「面板期合并是否生效」,报告新增来源分布。另加一项默认关闭的实验「面板常开时进一步合并」(面板期刷新下限 400ms、角标 3s);右侧预览是 Electron
<webview>,其绘制成本插件改不了,相关证据只作为上游文档,不包装成已解决。 - v0.3.6:新增默认关闭的实验「补页批量」——自动加载更早历史时,把单次请求的页大小从宿主默认 60 行提到 200 行(仍在上限内),减少同一段历史需要的加载次数。只改请求页大小,不跳过、不删除、不改变顺序;带独立开关,报告显示生效/放行次数。是否进入默认路径取决于实机 A/B,不把「少发请求」直接当成「已不卡」。
- v0.3.7:角标右侧与维护页「检查更新」行新增「有新版本」小红点;新增可选的自动检查更新(默认关闭,开启后 24 小时内最多一次,只请求公开 GitHub Releases,不自动下载/安装、不上报本机数据)。检查结果缓存在本机,跨窗口与重启后仍能看到红点;缓存版本与当前版本不一致、最新版本与当前相同或已是最新时都不显示。
- v0.3.8:日志清理加固(只删,不覆盖)。只认白名单内的插件日志;
observe-日期必须真实,运行目录本身是符号链接/非目录时整轮跳过;最近 10 分钟写入的文件不删;删前重新lstat复核并按当前大小修正预算。安装器清理临时文件也收紧为只认运行时文件名,不再误碰用户或其它插件的*.tmp-<pid>。 - v0.3.9:设置面板交互修复。点开关触发面板重建后保持原来的滚动位置,不再跳回顶部;打开面板时把键盘焦点收进面板,Tab/Shift+Tab 只在面板内循环,关闭后焦点还给原输入框;「合并刷新」还原时只还原插件自己装的那层
subscribe,宿主已替换实现时不覆盖;订阅回调异常每个页面只留一条日志;当前版本高于最新 GitHub Release 时,维护页如实显示「发布通道尚未更新」,不再误报「已是最新」。 - v0.3.10:修复「发现新版本但看不到红点」。两个更新红点的样式默认是隐藏,脚本显示时改为写明确的
inline-block;此前写空串会回落到样式的display:none,所以角标右侧和维护页「检查更新」行都看不到红点。现在检查到新版本后,两处红点都会实际显示。 - v0.4.0:新增默认关闭的实验「第三方定时器归因」——只记录单次运行 ≥50ms 的定时任务(耗时、原定间隔、回调名、调用点只留文件名与行号),用来判断卡顿是否来自外部插件的定时心跳;不改定时器时机,不读任务参数或对话内容,插件自己的定时任务不记录。「补页批量」改为自适应:窗口超过 3000 行时每页最多 120 行,连续快速上翻(间隔 <600ms)自动回到宿主默认 60 行,不跳过、不删除、不改顺序;
/lagfix report新增「第三方定时器归因」段,补页段显示生效/降回/小窗口/显式参数四类计数。 - v0.4.1:角标「有新版本」红点从指标文字与齿轮之间移到设置齿轮的右上角,像未读提醒一样贴在按钮角上;不占横向文字空间、不挡齿轮点击,维护页「检查更新」行的红点保持行内。显示条件、检查逻辑与缓存结构不变。
- v0.4.2:修正观测口径与包装器生命周期,不改默认开关、不新增缓解项。帧统计改为真正的最近 30 秒窗口(120Hz 下保留 3600 帧),角标与报告区分「窗口最长」和「attach/切会话以来最长」;
subscribe/loadAllOlder记录包装前后的身份,宿主运行期替换实现时不再误覆盖,关闭或一键还原只还原本插件那一层;翻页降频的旧包装用代际门控立即失效;定时器归因在全局定时器被替换/包裹时如实标记「归因包装已失效」,重装时包住宿主实现;报告对滚动/输入关闭态、明细代际和异常时间戳做了一致性处理。 - v0.4.3:新增默认开启的只读观测「切换会话归因」——每次切换会话记一条:切换后 2 秒内最重的一帧(P95)、之后 30 秒内的补页次数/耗时与长帧/强制布局累计,以及两侧的 DOM 与已显示轮数差值;最多保留最近 10 次,报告新增「会话切换」段并标出最重一次。修复「大会话翻页降频」在 ZCode 3.18.2 上一直不生效的触发判定(改为按最近一次滚动的时间窗识别,首调与挂载 5 秒内豁免以保护宿主冷快照补拉),放行/跳过计数新增「全天累计」口径,换会话不再清零。两天实机零生效的「补页批量」实验退役:旧设置键读取时忽略,面板不再显示该行,报告对历史日志保留计数并标注「已退役」。
- v0.4.5(当前):新增只读的「浏览器面板与回前台归因」。样本记录文档是否有前台焦点(
focus)以及当前选中的浏览器标签页里是否有 guest(webview)。browser-use标签页与人类浏览器标签页两条路径都覆盖;未选中的标签页即使仍挂载也不算,插件 UI、奖励页、预览等普通<webview>也不再误算,代码不再裸查文档里的任意<webview>。/lagfix report新增一段,把「稳定打开浏览器」「回前台 3 秒」「无焦点」分开统计,并并列宿主帧与宿主 LoAF;有切换记录时排除同窗口切换后 30 秒内候选,并明示帧 P95 是 30 秒窗口、3 秒排除窗口外仍可能含更早尖峰。实机数据里,稳定打开浏览器 4 分钟时宿主帧 P50/P95 中位为 6ms,但宿主主线程仍有 130–337ms 的 LoAF 长帧;这只能证明宿主 renderer 有长帧,不能证明来自 guest 页面内部,报告会如实标注「来源未分」。200–267ms 的宿主尖峰集中在回前台/页面加载,不是浏览器常开态。本版不新增开关、不改任何行为、不读页面 URL/标题/内容,也不声称已优化浏览器 guest。 - v0.4.4:新增默认关闭的实验「切换后大页补页」——真实会话切换后的 30 秒内,把无参补页的页大小从宿主默认 60 行提到 120 行,已载行数超过 3000 行或窗口结束即恢复;显式传参、草稿会话、30 秒外一律原样直通。不跳过、不合并、不缓存、不改会话数据,只改这一页取多少行;
/lagfix report新增该实验的「按 120 请求/按原样」计数,切换记录新增实际补页行数,便于按每 1000 行归一化 A/B。本版不处理切换瞬间的 1 秒级帧,也不声称切换已变快。
先跑一次 /lagfix report,它会打印「基线 / 问题窗口 / 恢复后」三段指标;这比只说“很卡”更容易定位。
反馈入口:
- 推荐:打开 问题模板,按提示填写。模板会要求附上:
/lagfix report的完整输出;- ZCode 版本、插件版本、操作系统;
- 复现步骤,以及卡顿发生在滚动、输入、切会话、侧栏开合还是回前台;
- 日志文件:
~/.zcode/zcode-lagfix/main.log和最近一个observe-YYYYMMDD.jsonl(可直接拖进 issue)。
- 也可以直接开 空白 issue。
日志里只有指标、设置快照、窗口 id、会话 sid 与计数、补页元数据、长帧脚本文件名、定时回调名与调用点(只留文件名与行号);不含提示词、回复、消息正文、工具参数或文件内容。提交前仍请自己过一眼,删掉不想公开的路径或用户名。
性能问题请尽量写清:
- 会话大概多长(消息数 / 历史行数);
- 从哪滚到哪、是否连续上翻;
- 哪些开关开着(尤其「切换后大页补页」「翻页降频」「长回合渲染减负」);
- 有条件的话做一轮开/关 A/B,各贴一份
/lagfix report。
想直接改代码也欢迎 PR:先读 AGENTS.md,行为改动请带测试,性能改动请附前后对比数据。
需要 ZCode 桌面版(Windows / macOS)与 Python 3.8+。不需要 Node,也不需要第三方 Python 包。
把下面整段发给 ZCode:
请安装或更新并启用 ZCode 插件:https://github.com/ck-ys/zcode-lagfix#plugin-releases
完成后在新会话里执行 /lagfix install,确认补丁已注入;成功后提醒我完全退出并重新打开 ZCode(仅关闭窗口不算),不要自动重启。
若安装失败,请说明原因;若当前会话无法执行命令,请提示我手动执行,不要跳过或声称安装成功。
安装流程:
- ZCode 从
plugin-releases渠道拉取插件并启用。 SessionStart钩子把运行时文件同步到~/.zcode/zcode-lagfix/,并幂等注入app.asar。/lagfix install可在当前会话立刻触发一次,适合修复被 ZCode 升级覆盖的注入。- 首次注入成功后必须完全退出 ZCode(含托盘)再重开;只关窗口或重开会话不算。
- 权限不足(例如 ZCode 装在
Program Files):让 ZCode 以管理员身份运行一次,或按/lagfix install输出的提示提权执行。钩子触发的失败写入~/.zcode/zcode-lagfix/hook-error.log;手动执行install.py的失败写在终端和install.log。 - ZCode 正在运行:
app.asar被占用时注入会挂起为 pending;完全退出后由值守进程自动收尾,重开即生效。 - 注入成功但状态条不出现:先看
/lagfix report的三段式诊断(未注入 / 注入了但观测器没起来 / 还没采到数据),再检查是否完全重启过。 - 以前卸载过,现在重新安装却没反应:卸载会写
~/.zcode/zcode-lagfix/.lagfix-optout,钩子看到它会跳过注入。删除该标记后重试即可(见下文「恢复使用」)。
主页面输入框上方显示:
● 流畅 每帧 18ms ⚙
- 判定词来自帧 P95 档位:极流畅 / 流畅 / 正常 / 轻微 / 卡 / 很卡;另有空闲 / 卡死 / 已暂停 / 已停。
- 颜色由面板里的黄/红阈值决定:帧 P95、"卡死"停顿、最近 30 秒峰值都套同一组阈值;超过 30 秒的历史峰值不参与,不会因为一次 788ms 永久报红。
- 状态条用 fixed 定位,每秒按输入框
getBoundingClientRect()同步坐标,不插进 React 树,避免被宿主重渲染清掉。 - 位置在输入框顶边上方,不压输入区、模型选择与发送按钮;与排队面板、额度横幅、待恢复提示、回到最新按钮相交时整体上移;上方没有余量时暂时隐藏。
- 只在主页面显示:设置页、弹窗、被浮层盖住的输入框一律排除;分屏或草稿页同时存在多个 composer 时,取最靠下的可用者。
悬停或点击状态条打开统计浮层:
- 大号帧 P95、六档颜色图例;
- 最近 18 个采集周期的柱状图;
- 峰值 / 最低 / 最新帧间隔;
- 投影提交速率与长任务次数。
点击是固定展开,点页面别处或再点一次收起;悬停 120ms 后自动展开,移开 260ms 收起。
点状态条末尾的齿轮,打开居中分类设置:
| 分类 | 内容 |
|---|---|
| 状态条 | 显示文字、信息量(简洁/详细)、警告/严重阈值 |
| 观测 | 观测开关、采集间隔 1 / 3 / 5 / 10 / 30 秒、滚动诊断、输入延迟、多会话分别统计 |
| 性能 | 合并刷新与最短刷新间隔、卡顿时自动放慢、切换会话时放慢、后台时减少刷新、大历史会话保护、滚动时去掉渐隐、侧栏与回前台保护(可逐项关闭) |
| 维护 | 日志路径与上限、当前日志量、重启 ZCode、检查更新、反馈问题、恢复默认 |
性能页每一项标题后都有圆圈「!」,点开用「会做什么 / 不会做什么 / 代价」三段说明,不写内部字段名。
设置面板的「性能」页:
角标常驻显示(v0.3.1 起删除了隐藏开关):在设置页/弹窗内、被浮层遮挡、没有可用输入框时仍会自动隐藏,这是布局避让,不是用户开关。设置入口始终可用:
- 点角标末尾的齿轮
Ctrl+Alt+L(macOS:Cmd+Alt+L)- 控制台执行
__lagfixSettings()
「检查更新」默认只在你点击时请求一次 GitHub Releases(api.github.com,https,无 token);打开「自动检查更新」后改为 24 小时内最多一次。两者都不会自动下载或安装;升级仍走下面的插件市场流程。
设置保存在 localStorage["lagfix.settings.v1"],更新检查结果单独放在 localStorage["lagfix.update.v1"];两者都只在本机,多窗口通过 storage 事件同步。主进程侧镜像设置到 ~/.zcode/zcode-lagfix/settings.json,便于排查。
宿主大约每 30ms 提交一次投影并通知所有订阅者,React 在 useSyncExternalStore 回调里整树重渲染,把主线程切碎。节流把通知合并为最多每窗口一次:
- trailing 必达,不是 debounce——持续流式时也会持续刷新;
- 只包装
subscribe(listener)这种一参调用;带 selector 的subscribeWithSelector原样放行,否则会冻结 UI; - 状态照常写入 store,只延后渲染通知,不改任何数据;
- 节流窗口按 store 实例计时,而不是按订阅——React 19 每次 commit 都会用新的内联箭头重新订阅,按订阅计时会让窗口在每次重订阅时清零;
- 找不到 store 时降级显示"待生效",并每 3 秒重试(最多 20 次);
- 关开关立即恢复即时通知;观测器自禁用时同步还原。
稳态默认窗口 120ms(面板可调 30~1000ms)。开启下面的增强后,窗口会按条件延长:
| 场景 | 最大通知间隔 |
|---|---|
| 稳态 | 120ms(面板可调) |
| 自适应窗口:帧 P95 ≥ 80ms / ≥ 150ms | 至少 200ms / 300ms(面板值更大时保持面板值) |
| 切会话后 10 秒内 | 不低于 250ms |
| 窗口在后台 | 最多 1 秒 1 次,回前台立即补一次 |
因此"渲染最多滞后 120ms"只适用于稳态。开启增强后实际窗口取 max(面板窗口, 200/300ms):面板保持默认 120ms 时,极端情况约 300ms;若用户把窗口调到 1000ms,则保持 1000ms。后台最多 1 秒。这是用可感知的延迟换取主线程先完成首屏挂载与布局。
进入或切换大历史会话时,宿主会为问题导航目录、分享目录做一次性全量补拉(loadAllOlder 分页读完再一次性换 snapshot),DOM 从几千行突然涨到上万行。v0.3 在"不动宿主数据"的前提下提供四个开关:
| 开关 | 默认 | 触发条件 | 行为 | 关掉后 |
|---|---|---|---|---|
| 自适应窗口 | 开 | 最近帧 P95 ≥ 80ms / ≥ 150ms | 通知窗口至少 200ms / 300ms(以面板值为下限),帧恢复后回落 | 只按固定窗口 |
| 切会话冷静期 | 开 | 切/新建会话后 10 秒内 | 窗口不低于 250ms,让主线程先完成首屏挂载 | 切会话立即按固定窗口 |
| 后台降频 | 开 | document.hidden |
通知最多 1 秒 1 次;回前台立即补一次 | 后台仍按前台频率通知 |
| 大历史会话保护 | 开 | 总行数 ≥ 800 且只加载了一部分 | 拦下 loadAllOlder 全量补拉,返回 not-enough-queries(宿主视为终态,不会重试风暴);分享入口点击后 15 秒内、分享弹层挂载期间自动放行 |
恢复宿主的一次性全量补拉 |
边界与取舍:
- 前三个开关只影响"什么时候通知 React 渲染";大历史会话保护影响"要不要执行一次性全量补拉"。两者都不改 store 数据、不改消息、不碰
db.sqlite。 - 大历史会话保护的代价:大历史会话里问题导航的目录只覆盖已加载部分;正常上翻分页(
loadOlder)、当前可见消息不受影响。 - 自适应窗口有 1 秒缓存,避免每次通知都重算帧统计。
- 全部关闭等价于 v0.2.3 行为;
__lagfixOff()会同时关掉节流与大历史会话保护、还原被包装的方法,并在本轮真的拦过补拉时自动补拉一次。
滚动卡顿和"进入会话时的一次性全量补拉"不是同一回事,v0.3.1 先把滚动这条链路量清楚,再提供一个可 A/B 的绘制层缓解:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 滚动诊断 | 开 | 只统计滚动后 200ms 内的帧(P95/max)、时间线 scroll 事件数、loadOlder 次数/耗时/失败、挂载 turn 数、DOM 峰值、浏览器支持时的 long-animation-frame |
collect 的 scroll 为 null,不再做额外 DOM 扫描 |
| 输入延迟 | 开 | 只统计输入框内 keydown 到下一帧的间隔(P95/max/样本数),复用现有 rAF 循环 |
collect 的 input 为 null |
| 滚动期隐藏遮罩 | 开 | 时间线滚动时给 documentElement 加 data-lagfix-scroll="1",停滚 180ms 后移除;CSS 只覆盖消息层的 mask-image |
不添加属性,滚动时遮罩保持原样 |
边界与取舍:
loadOlder只观测:不拦截、不延迟、不改返回值;scroll.p95只代表"滚动后 200ms 内的帧",不等于整段会话帧率。input.p95只能说明"按键到下一帧"变慢,不能区分是浏览器输入延迟还是主线程排队;它不修复按键卡顿。- 遮罩抑制只影响绘制,不改布局与 DOM。它的前提是宿主当前用内联
mask-image(无!important);若宿主改成!important内联写法,本项会静默失效,靠scroll.p95与人工 A/B 发现。 scroll.mismatch(anyEvents>0 && events===0)说明"有人在滚,但没命中已知时间线选择器",先跑/lagfix report判断宿主是否改版。
v0.3.1 能证明"有尖峰",但分不清尖峰来自当前会话、隐藏会话还是一次补页。v0.3.2 只补证据,不改任何渲染/补页行为:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 多会话归因 | 开 | 按 data-session-id 分桶(最多 5 个),记录每个会话的投影提交次数/速率、DOM 节点数、挂载 turn 数、滚动帧 P95、可见性与最近活跃时间;隐藏 pane 也记录并标 visible=false;占位 sid(draft/空)切成真实会话后删除占位桶 |
collect 的 sessions 为 null,不再遍历会话 pane |
loadOlder 明细 |
随滚动诊断 | 最近 10 次调用的耗时、promise 是否正常结算、调用前后 rows.window 长度、触发来源(scroll / initial / unknown);只读长度,不读分页内容。只包装主 store 实例,暂停期间不累计 |
collect 的 loadOlderDetail 为 null |
边界与取舍:
- 最多 5 个桶;发现阶段满 5 个后额外 pane 只观察不建桶,等它有真实提交/滚动才淘汰最久未活跃的旧桶,历史数字随之丢失。切会话本身不算活跃,同值 SID/seq 重写也不计数。
visible只代表 CSS/几何可见,不代表"最前台";分屏时两个 pane 可以同时为true。frames/commitRate依赖宿主继续更新data-projection-seq,且只统计值真的变化;隐藏 pane 若被宿主停止渲染,会如实显示 0,这不等于"隐藏 pane 不耗资源"。mountedTurns/dom是 pane 子树口径,固定每 60s 采样一次(新桶立即采);scroll.mountedTurns/domPeak仍是整窗口径,两者不能直接相加对比。loadOlderDetail只覆盖当前主 store 实例(主 pane),不修改共享原型;trigger是时间启发式(滚动后 2s 内 / 挂载后 5s 内的首次调用),不能证明宿主内部调用原因。- 宿主
loadOlder内部失败会打日志后正常 resolve,因此ok=true只表示"promise 正常结算";报告会把行数未变标成"无变化"。 loadOlderDetail只在变化时携带完整数组,未变化样本发[];多会话归因每个样本约增加 0.4–0.6KB。默认 50MB 日志预算下如需要更长历史,可在面板调大logMaxMB。- 本版不改变任何渲染/补页行为,不应期待帧率变化;它的价值是让 v0.3.3 的缓解项有数据依据。
手动「检查更新」只能用一次点一次,很容易忘记。v0.3.7 把检查结果缓存在本机,并在有新版本时给角标和维护页加一个小红点:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 有新版本小红点 | 随检查结果 | 缓存里的 newer=true、缓存版本等于当前版本、且最新版本与当前不同时,角标右侧与维护页「检查更新」行显示红点 |
缓存被清空或已是最新时红点消失 |
| 自动检查更新 | 关 | 开启后 ZCode 启动/窗口打开时最多检查一次;checkedAt 存在本机,24 小时内不重复。只请求公开 GitHub Releases,不自动下载/安装,不上报本机数据 |
回到只能手动点击「检查更新」;已有缓存与红点仍会展示 |
边界与取舍:
- 自动检查是显式选择:默认关闭;关闭时只有手动点击「检查更新」才会联网,打开后也只在 ZCode 打开期间按 24 小时上限检查。检查失败只影响那一行提示,不影响观测与其他开关。
- 结果写在
localStorage["lagfix.update.v1"],跨窗口与重启保留;它只含版本号、是否有新版本、release 链接与时间戳,不含会话数据。 - 红点不是「已下载」或「已安装」:插件不自动下载、不自动安装,也不会替用户重启 ZCode;升级仍走安装口令与手动重开。
- 缓存版本与当前版本不一致时红点会隐藏(例如刚升级到新版本,旧缓存还没刷新);下一次检查完成后重新判断。
__lagfixOff()会关闭自动检查、清掉更新缓存与两处红点;手动检查按钮保持可用。
v0.3.6 的「固定 200 行」实机 A/B 暴露了问题:调用次数减少,但一次前插 200 行会把滚动位置推得更远,连续上翻时跳动明显;该实验已在 v0.4.3 退役。v0.4.0 保留一项只读归因,回答「卡顿是不是外部插件的定时心跳」;v0.4.4 新增的「切换后大页补页」只作用于真实切换后的 30 秒窗口。
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 第三方定时器归因 · 实验 | 关 | 只读:定时任务单次同步运行 ≥50ms 时记一条(耗时、原定间隔、类型、回调名、调用点只留文件名与行号),最多 10 条;插件自己的定时任务不记录 | 立即还原原始 setTimeout/setInterval,样本 timer=null,明细与计数清空 |
| 切换后大页补页 · 实验 | 关 | 仅当调用方没有传参数、处于真实会话切换后的 30 秒内且已载行数 ≤3000 时,单次补页请求 120 行;窗口结束或超过 3000 行即回到宿主默认 60 行;显式传参原样放行 | 恢复宿主默认 60 行,其余行为不变 |
第三方定时器归因的边界:
- 只看同步执行耗时;异步回调(
Promise.then、宿主自己的调度器)不在范围内。 - 抓到 ≥50ms 定时器只说明有嫌疑,不等于找到卡顿根因;还要结合
/lagfix report的长帧与滚动段看时间是否对得上。 - 只留回调函数名与
文件名:行:列,不含完整路径、源码、参数或对话内容;不改变任何定时器的时机、次数与结果。 - 插件自己的定时器通过原始方法调度,不会被自己记录。
切换后大页补页的边界:
- 只改请求页大小:不跳过、不合并、不缓存、不删除任何消息,也不改变顺序;
this、Promise、异常、加载中状态全部由原方法决定。 - 120 行是折中:比宿主默认多一倍,减少调用次数;窗口只有 30 秒,切到草稿、超过 3000 行或窗口结束都会回到 60 行,避免长期改变宿主行为。
- 单次补页仍要付宿主后端全量过滤的成本,本项只减少同一段历史需要的次数,不降低单次耗时;不能写成「已解决补页卡顿」。
- 需要实机 A/B:按每 1000 行归一化后,补页调用次数下降 ≥30%,且每 1000 行补页总耗时下降 ≥20%(或滚动 P95/长任务下降 ≥10%)、2 秒切换帧不退化 >10%、顶部空白 ≤300ms、锚点漂移 ≤48px、DOM 峰值增加 ≤20%,才考虑进入默认路径;未过线保持默认关闭,若归一化调用次数也没有明显下降就退役该项。
- 与「大会话翻页降频」独立:降频先决定是否调用,本项只决定调用时的页大小;观测、降频、本项都关时
loadOlder包装卸载。
v0.3.4 能回答「卡的时候哪个脚本最贵」,但分不清是插件合并刷新、滚动、宿主提交还是预览绘制。v0.3.5 先补上下文,再用默认关闭的 O5 做一次低风险尝试:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 长帧上下文归因 | 开 | 只读:每条 ≥100ms 长帧记录距上次通知/补发/滚动/消息提交的毫秒数,并归类为 flush / notify / scroll / other;样本带本周期来源分布与 paneOpen / panelQuiet |
样本 laf.ctx=null,明细不带 src 与四个时间差 |
| 面板常开时进一步合并 · 实验 | 关 | 面板打开期间通知节流下限 300→400ms、角标定位 1.8s→3s;面板关闭后新通知回到基础间隔(默认 120ms),在途一次最多按原窗口送达 | 面板仍开且「面板常开保护」开时回到 300ms / 1.8s;面板关闭后回到基础间隔 |
边界与取舍:
notify/flush上下文依赖「合并刷新」开启;关掉合并刷新时没有插件侧通知时间戳,来源会落到scroll或other。- 归因是窗口级的,
sinceCommit只跟踪活动 pane 的投影序号;多 pane 同时提交时不能精确到某个 pane。 - O5 需要实际 A/B:长会话 + 面板打开 + 高频滑动,比较开/关的长帧数或
frameP95,下降 ≥20% 才值得保持开启;未过线就保持默认关闭。 - 右侧预览是 Electron
<webview>guest,面板内滑动的主线程/合成成本落在宿主渲染进程;插件无法接管,U1 只把证据交给上游。 - 仍只记录指标与时间差,不读消息正文、不写 store、不联网上报。
实机数据(超长会话上翻)显示:单次补页最长 2262ms、DOM 峰值 8691、3 秒内长任务 32 次。v0.3.4 先把「卡的时候到底在忙什么」量出来,再提供两项默认关闭的实验缓解:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 卡顿来源定位 | 开 | 只读记录 ≥100ms 长帧:总时长、各脚本强制布局时长之和、耗时前 5 的脚本(只记文件名,不记路径/内容),最多保留最近 10 次 | 样本 laf 为 null,不装 LoAF 观察器(滚动诊断也关时) |
| 大会话翻页降频 · 实验 | 关 | 窗口超 3000 行时,上翻触发的补页至少间隔 600ms;被跳过的触发不碰 ZCode 状态,继续滚动会自动补上 | 所有补页触发原样放行 |
| 长回合渲染减负 · 实验 | 关 | 给 documentElement 加 data-lagfix-cv="1":turn 内部行级块(不含正在生成的回合)屏外跳过绘制,滚回附近恢复;已渲染过的块高度占位不变,不扰动滚动定位 |
移除属性,绘制行为与原版完全一致 |
边界与取舍:
- 后端每次补页要先过滤整个会话投影再取一页(宿主默认 60 行;v0.4.4 起「切换后大页补页」实验只在切换后 30 秒内用 120 行,其余时间 60 行),这是 ZCode 自身成本,插件降不了单次耗时,只能减少触发次数;翻页降频不解决它,只是少撞几次。
- 翻页降频:停在触发区不再滚动时,被跳过的补页要再滚一下才会补上;快速上翻时更早的历史可能晚一点出现。
- 渲染减负:个别从未绘制过的消息块第一次滚到时位置可能轻微校正;不折叠、不隐藏任何内容,搜索与选中不受影响。
- 两项实验按 A/B 数据定去留:滚动 P95 或长任务下降 ≥20% 才值得保持开启,否则建议关闭,等 ZCode 上游优化。
- 卡顿来源定位只记脚本文件名与时间,不含会话内容、路径或参数。
右侧面板不只是"打开那一拍"贵:面板常开时仍有遮罩与重绘成本,从别的应用切回 ZCode 还会同步补发后台通知。v0.3.3 把它拆成三段,每段独立开关:
| 项 | 默认 | 行为 | 关掉后 |
|---|---|---|---|
| 侧栏与回前台统计 | 开 | 只读记录 pane.detected/open/panelPx/switches/switchP95/switchMax/guardHits 与 refocus.hiddenMs/sinceVisibleMs/p95/max/flushes/guardHits;回前台同时听 visibilitychange 与 window.focus/blur |
collect 的 pane/refocus 为 null;若保护项仍开,只保留最小开合检测 |
| 侧栏开合保护 | 开 | 开合后 420ms 内给 documentElement 加 data-lagfix-pane-switch="1":停掉 [data-panel] 的过渡、临时关消息层 mask、暂停角标定位 |
不加属性,宿主原过渡与遮罩完全不变 |
| 面板常开保护 | 开 | 面板打开期间加 data-lagfix-pane-open="1":关消息层 mask、通知窗口至少 300ms、角标定位最多 1 次/1.8s |
不加属性,节流与角标回到原规则 |
| 回前台保护 | 开 | hidden→visible 或 blur→focus 后,把后台挂起的通知合并到一个 120ms 定时器;700ms 内通知窗口至少 400ms;前 300ms 不定位角标 |
恢复同步补发,不抬下限、不跳过角标 |
边界与取舍:
- 开合保护只覆盖 420ms(200ms flex 过渡 + 220ms 重内容 settle);代价是开合从滑动变成瞬开/瞬收,不想要就关 P1。
- 面板常开期停 mask、把通知窗口抬到 300ms,聊天文字最多晚 300ms 刷新;Agent 收流、工具执行、消息落盘不受影响。
- 回前台最多晚 120ms 补状态;只延迟插件自己挂起的通知,宿主自己的首帧重绘不被拦截。
pane.detected=false表示宿主改版或当前布局没有桌面侧栏(如移动端 overlay),插件不猜选择器、也不加保护属性;先跑/lagfix report判断。- 三段都只改通知时机、绘制层属性与角标定位;不改消息、会话数据、补页返回值,不写 store。若卡顿来自预览 HTML 自身绘制或宿主其它长任务,这三段仍可能不够。
运行时目录:~/.zcode/zcode-lagfix/
| 文件 | 内容 |
|---|---|
observe-YYYYMMDD.jsonl |
每个采集周期的指标(帧、提交、长任务、堆内存、DOM 数量、滚动/输入诊断、多会话归因、loadOlder 明细、侧栏/回前台归因、设置快照) |
main.log |
主进程加载器(注入、采集泵、自禁用原因) |
inject.log |
每个窗口的注入结果 |
monitor.log |
值守进程(何时等到、为何收不了尾) |
install.log |
安装器动作与退出码 |
hook-error.log |
SessionStart 钩子异常 |
elevated-finalize.log |
管理员权限收尾(仅使用提权工具时产生) |
settings.json |
渲染端设置的只读镜像 |
日志清理只操作 ~/.zcode/zcode-lagfix/ 的直接子项,且文件名必须命中本插件白名单;observe- 的 8 位日期必须是真实日期。每次删除前用 lstat 复核「普通文件、非符号链接、路径仍在运行目录」,并跳过运行目录本身是符号链接、以及最近 10 分钟内写入的文件。符号链接、目录、用户文件、settings.json、今天正在写的 observe-*.jsonl 与未轮转的活动日志一律不删;任何异常都跳过(宁可超预算,也不误删)。
体积控制:
- 上述日志共享一个总预算,默认 50MB,面板「维护」页可改 20 / 50 / 100 / 200MB;
- 单个
observe-*.jsonl达到 5MB 自动轮转为.1; - 超出总预算时从最旧的文件开始删,当天的活动观测文件不删;
- 观测日志另有 14 天保留上限(启动时检查一次,之后每小时补查);
- 维护页实时显示当前日志量与文件数(不足 1MB 按 KB 显示),随每个采集周期刷新。
隐私边界:
- 只记录指标、窗口 id、设置快照与长帧的脚本文件名/调用点(截断,不含路径),不记录提示词、模型回复、文件内容、工具参数或数据库;
- 所有数据只写本机目录,不上传;除检查更新外不联网——手动点击时查询一次公开 GitHub Releases,开启自动检查后 24 小时内最多一次(无 token、不自动下载/安装);
- 不打开 CDP 端口,不读取
db.sqlite。
先完全退出 ZCode(含托盘 / 任务管理器确认无 ZCode.exe 与 zcode-runtime-host.exe),再执行对应命令。uninstall 会先写豁免标记占位(堵住并发的钩子/收尾重装),再剥注入行;ZCode 仍在运行时 remove 返回 failed 并撤回标记,最终状态仍是未卸载,避免"号称卸了其实还在"。
python "$HOME/.zcode/zcode-lagfix/patch_install.py" uninstall然后到 设置 → 插件 → 已安装 → zcode-lagfix → 卸载,再重开 ZCode。顺序不要反。即使不小心先卸载了插件,~/.zcode/zcode-lagfix/patch_install.py 仍然保留,完全退出 ZCode 后跑同一条 uninstall 即可清干净。
在仓库根目录执行:
python install.py remove任何一次成功卸载都会留下 ~/.zcode/zcode-lagfix/.lagfix-optout,它会让 SessionStart 钩子静默跳过注入。所以恢复顺序固定为:先删标记,再安装。
python -c "import pathlib;pathlib.Path.home().joinpath('.zcode','zcode-lagfix','.lagfix-optout').unlink(missing_ok=True)"- 插件仍在启用:执行
/lagfix install。 - 插件已从市场卸载:先在 设置 → 插件 里重新安装并启用 zcode-lagfix,再执行
/lagfix install。运行时目录里的patch_install.py install只会重新注入 asar,不会恢复插件注册、命令和钩子。
uninstall / remove 只剥 lagfix 自己的注入行,绝不影响已装的其它注入插件(如 zusage 状态条)。
仓库自带一个外部响应探针,不改 app.asar、不用退出 ZCode:
python tools/lagfix-probe.py --overlay探针仅支持 Windows(使用 Win32 消息队列);插件本体支持 Windows / macOS。
右下角出现置顶小窗,每秒显示 ZCode UI 线程的消息泵延迟。原理是向 ZCode 主窗口发送 WM_NULL 空消息并计时:UI 线程被渲染占满时消息只能排队,回得就慢。这与系统判定"窗口无响应"走同一条路径;不注入、不读窗口内容、不改任何文件。
判读:
- P50 < 20ms:流畅
- P95 20~80ms:轻微掉帧
- P95 > 80ms:明显卡顿
- 单次 > 500ms:卡死级别
方法本身有自动化验证(tests/probe_latency.py:空闲约 0.03ms vs 人为占死 UI 线程 1024ms)。
在仓库根目录执行:
python install.py安装器会:
- 复制插件到
~/.zcode/cli/plugins/cache/lagfix-marketplace/zcode-lagfix/<version>/(只保留当前版本); - 登记市场与插件,写
enabledPlugins; - 同步运行时文件到
~/.zcode/zcode-lagfix/; - 注入
app.asar。
ZCode 运行中时补丁会挂起(pending)。收尾不靠"数进程数 == 0",而是每 2 秒直接尝试 os.replace,由操作系统仲裁:Windows 不允许 rename 覆盖已被打开或映射的文件,所以"能替换"就等于"确实没人握着它"。完全退出 ZCode 后 2 秒内自动完成,再打开即生效。
查看状态:
python install.py status
python "$HOME/.zcode/zcode-lagfix/lagfix_report.py"报告按三段式诊断:未注入 / 注入了但观测器没起来 / 还没采到数据。
- 与 zusage 等注入插件共存:注入行标记
[lagfix] load failed、loader 名lagfix-main.cjs,与 zusage 的inject-main.cjs/[zusage] load failed互不匹配;锁、TMP、sidecar 文件名全部错开。 - 多插件收尾错峰:检测到其它待收尾包时主动让对方先落地(累计上限 120 秒),等不到就放弃本轮,避免让别人的补丁永久失效。
- 宿主改版:状态条依赖
.chat-composer-input-surface、[data-v4-back-to-bottom-anchor="composer-dock"]与投影 store 的内部形状;侧栏保护依赖[data-workspace-side-frame="true"]的aria-hidden和外层[data-panel]。ZCode 大版本改版后若状态条消失或pane.detected=false,先执行/lagfix report判断是注入丢了还是选择器不匹配。 - 平台:Windows 与 macOS 桌面版;Linux 桌面版未验证。
- asar 手术逐文件断言读取长度 == 节点 size;stage 写入后 flush + fsync;替换前校验源 asar 指纹(size + mtime_ns + st_dev + st_ino)。
- 替换失败挂 pending,由值守进程在 ZCode 全退后收尾;收尾遇他人替换时基于当前文件重打。
- 注册表读失败一律中止,绝不回退空结构覆盖用户插件列表;写回采用 tmp + 原子替换,并保留当日备份。
- 改后入口用
ZCode.exe --check(ELECTRON_RUN_AS_NODE)做语法自检,30 秒超时。 - 运行时宿主包装只有三处:
subscribe(只合并通知)、loadAllOlder(只在大会话且未全载时拦截)、loadOlder(默认只观测量耗时,不改参数与返回值;开启「大会话翻页降频」实验后会在大窗口内跳过 600ms 内的重复触发并返回已结算 promise;开启「切换后大页补页」实验后,只有真实会话切换后 30 秒内、无参调用且已载行数 ≤3000 才会请求 120 行,其余情况原样放行;均不碰 ZCode 状态机)。v0.3.3 起另有data-lagfix-pane-switch/data-lagfix-pane-open两个临时documentElement属性,v0.3.4 实验项再加常驻的data-lagfix-cv(仅开关开启时存在);v0.3.5 的长帧上下文归因只读时间戳、不新增包装,O5 只改通知/角标时机、不新增 DOM 属性;v0.4.0 的定时器归因在开关开启时替换setTimeout/setInterval,只计时与记录长回调,不改变时机与结果,关闭/暂停/一键还原立即恢复原引用;三条路径(关开关、自禁用、__lagfixOff())都会立即移除。 - 更新检查只允许
https://api.github.com/repos/ck-ys/zcode-lagfix/releases(重定向逐跳校验、最多 2 跳、总时限 10 秒、响应体上限 2MB),不带 token;自动检查默认关,主进程按 24 小时去重,结果只写本机localStorage,不回传任何本机数据。
在仓库根目录执行:
node --check plugins/zcode-lagfix/lagfix-main.cjs
node --check plugins/zcode-lagfix/lagfix-observe.js
python -m py_compile install.py plugins/zcode-lagfix/*.py plugins/zcode-lagfix/hooks/*.py
python tests/line_regex.py # 注入行正则与 zusage 互不误伤(11 项)
python tests/peer_gate.py # 多插件收尾礼让与上限(5 项)
python tests/smoke_asar.py # 合成 asar 夹具,byte 级验证重打包、busy 与卸载竞态(46 项,不碰真实安装目录)
python tests/install_remove.py # install.py 卸载异常边界:Ctrl+C / 占用 / 插件态写入失败 / 临时文件清理只认运行时文件名(11 项)
python tests/report_session_diag.py # 报告:会话桶/补页明细/侧栏与回前台/浏览器面板归因/卡顿归因/翻页降频/自适应补页/定时器归因/长帧来源分类/暂停回退/关闭边界/坏行(165 项)
python tests/probe_latency.py # 外部探针方法有效性:空闲 vs UI 线程占死
node tests/observe_smoke.mjs # 渲染端:可见性/角标/节流/滚动诊断/输入延迟/多会话/loadOlder/侧栏与回前台/浏览器焦点与选中 guest 标记/卡顿归因/长帧上下文/自适应补页/定时器归因/更新红点/反馈入口/翻页降频/渲染减负/面板期合并/面板滚动与焦点/还原边界/日志/一键还原(634 项)
node tests/update_check.mjs # 主进程检查更新:白名单/重定向/过滤/版本比较/体积上限/注入/自动检查去重(25 项,不联网)
node tests/log_budget.mjs # 主进程日志预算:超限删最旧/保留活动文件/14 天清理/符号链接与目录跳过/权限失败/非法日期/最小年龄/目录安全(33 项,假 fs 不写盘)自动化测试不等同于所有 Windows / macOS 实机验收;首次安装后请按上文完全重启,确认状态条出现且 /lagfix report 有数据。
- v0.4.5 后续:v0.4.4 曾把「切换瞬间微批」列为 v0.4.5 候选;实机数据显示切换到长会话后的主要成本是目标会话的补页潮(单轮最多 26 次 / 2762 行 / 5535ms),不是切换瞬间本身,因此 v0.4.5 先做只读归因,微批暂缓。下一步候选是「切换窗口内的补页节流」(例如限定自动补页频率或只在用户上翻时补),但必须先出拍板页并做「关→开→关」至少 3 轮实机 A/B;在数据过门槛前不进入默认路径。另有用户反馈「卡顿时画面跳动」,当前没有滚动偏移/锚点漂移的运行时字段,下一步先做只读归因(记录滚动容器
scrollTop异常跳变与补页前后锚点差),再决定是否做行为缓解。 - v0.4.4 后续:先按切换记录做「关→开→关」至少 3 轮实机 A/B,按每 1000 行归一化比较
loadOlderN30s、loadOlderMs30s与loadOlderRows30s;每轮必须switchPage.installed=true且applied>0,否则该轮无效并重做。门槛未过则保持默认关闭,归一化调用次数也没有明显下降就退役该项。 - v0.4.2 后续(已并入 v0.4.3):30 秒窗口与包装器 identity 的基线已随 v0.4.3 的切换归因一起建立;插件自身开销优化仍按实测数据决定。
- v0.4.0 后续:先做实机 A/B——第三方定时器归因开启后跑一段长会话,确认 ≥50ms 定时任务是否与长帧时间对得上;若是外部插件心跳,优先推动上游修(zusage v1.5.18 已修复每 100ms 深拷贝的问题),插件侧只保留观测。补页批量(O8b)已因两天实机 0 次生效于 v0.4.3 退役,不再做 A/B。
- v0.3.6 后续:固定 200 行的大页实验已被 v0.4.0 自适应方案替代;历史 A/B 数据保留在
docs/decisions/,不再继续加页大小。若「单次补页仍贵」被证实是主因,下一步应转向推动上游优化后端全量过滤,而不是继续在插件侧加码。 - v0.3.5 后续:按 P0 的来源分布决定方向——
flush高则继续评估面板期合并(O5 已默认关闭,过 20% 门槛才考虑进默认路径);other且距消息提交很近则转宿主渲染/上游证据;scroll高再评估补页降频(O3b)。 - v0.3.4 两项实验:翻页降频与长回合渲染减负仍按实机 A/B 数据决定去留——滚动 P95 或长任务下降 ≥20% 才保留在默认路径推荐里,否则永久保持默认关闭并如实标注。
- v0.4 候选:多会话策略(O7,需先证明隐藏 pane 的提交/DOM 是主因)、非活动 pane 节流(O6)、turn 内再虚拟化;都需要宿主配合或更大的渲染端改造。
- 候选:打开子智能体(Subagent)面板或多级任务时的卡顿:先量清是 DOM 规模、订阅通知还是面板挂载,再决定是否做成默认关闭的独立开关。
- 长期:宿主改版后的选择器适配;自动下载/安装(当前只做手动检查或可选的自动检查,不自动下载、不自动安装)。
MIT © 2026 ck-ys

