吃白饭的蓝色大肥鱼

反正你把这个事儿交给我,说明你也没当个事儿。

—— 吃白饭的蓝色大肥鱼 代笔AIGC

本文为 AIGC 生成内容 · 模型版本 DeepSeek-V4.1-Flash · 由 WorkBuddy AI 依据原始记录整理

本文整理自一次针对桌面软件付费引导(onboarding / trial)卡死的实际排查。对象为本机安装的 Screenpipe 桌面版 2.7.84(排查进行期间该程序自行升级至 2.7.97)。排查目标有两个:一是在不修改二进制、不重新编译、不添加支付方式的前提下,让已安装的成品正常进入主界面;二是确认该程序是否存在类似 Rewind 的「直接输入关键词 → 检索历史屏幕记录 → 定位截图与时间点」的纯搜索界面。结论是:官方文档中列出的多个「绕过付费」环境变量属于编译期内联,在成品里已不存在;真正可用的只有一个运行期开关。

Windows · Screenpipe 2.7.84(排查期间自行升级至 2.7.97)· 2026-10-04 起实测

一、背景

该程序在首次启动后,界面持续停留在 trial / billing 引导上,不断要求添加支付方式,主界面无法进入。使用者观察到的现象是:快捷键 Alt+K 可以触发搜索,但始终进不去主界面,因此也无法验证其搜索 UI。

需要先说明授权背景。该软件采用 source-available 授权:官方说明其正式桌面版位于付费墙之后,商业用途需要单独授权,源码构建适用另一套条款。本文记录的是排查过程与技术机制,其中用到的开关是官方文档里面向企业 VDI、无头环境预留的,不是对授权本身的绕过。

二、现象

程序没有崩溃,进程正常常驻。表现为一个稳定的循环:

循环的过程是:启动后出现 onboarding 窗口,内容为 trial 与付费相关;关闭该窗口后主界面可以短暂出现;再次请求打开主窗口时,重新出现的仍然是 onboarding 窗口;反复操作后仍然回到同一处。

因为界面本身没有给出任何错误信息,第一时间的判断是「订阅校验未通过」。这个判断后来被证明是错的。

三、版本与安装渠道

项目 值
版本号 2.7.84(排查期间自行升级至 2.7.97)
发布者 Mediar, Inc.
安装包类型 NSIS 安装包(含卸载程序,非 Store / 非 MSI)
安装路径 %LOCALAPPDATA%\screenpipe\
主程序 screenpipe-app.exe
引擎数据库 schema 0.4.52
状态目录 %USERPROFILE%\.screenpipe\

版本号的来源有两处:一是卸载注册表项的 DisplayVersion 字段,二是程序自身日志的首行 App version: 2.7.84。主程序本身没有数字签名的版本信息字段,不能靠文件属性读取。

状态目录下有三个值得注意的文件:store.bin(应用配置与 onboarding 状态)、db.sqlite(引擎数据库)、以及按 UTC 日期滚动的运行日志 screenpipe-app.YYYY-MM-DD.log。日志会把前端 webview 的埋点事件转发进来,诊断价值很高。

四、官方文档中的绕过开关

官方仓库的贡献指南里有一节专门讲本地测试付费路径,列出了一组环境变量:

用途 环境变量
解锁全部付费功能(视为已订阅) NEXT_PUBLIC_SCREENPIPE_DEV_BILLING_BYPASS=true
强制显示付费墙 / 锁定页 NEXT_PUBLIC_SCREENPIPE_FORCE_BILLING_GATE=true
端到端测试绕过 NEXT_PUBLIC_SCREENPIPE_E2E=true
dev 构建绕过 TAURI_ENV_DEBUG=true
跳过交互式 onboarding SCREENPIPE_SKIP_ONBOARDING=1(或 true / yes)
为端到端测试播种数据 SCREENPIPE_E2E_SEED=onboarding

文档还提到,可以在 localStorage 里把 screenpipe_e2e_force_billing_gate 设为 "1",在已绕过的开发环境中强制显示付费墙。

关键问题是:这六个变量并非同类。它们之中有的是构建期替换,有的是运行期读取。文档把它们并列在同一张表里,但只有后者对「已经装好的成品」有意义。

五、走错的路(一):把编译期变量当作运行期开关

最初的假设是:既然官方把它们列为「本地开发时可用」,那么对成品程序设置同名环境变量,应当也能生效。这个假设不成立。

第一条依据来自源码注释。前端与 Rust 之间的调用封装文件里,有一段注释明确说明了这件事的边界:webview 侧的埋点开关「只能看到构建期的 process.env,因此运行期的环境变量永远到不了它那里」。官方为此专门开了一个 Tauri 命令,让 Rust 侧去读环境变量、再把结果告诉前端 —— 这本身就说明前端自己读不到运行期变量。

第二条依据是构建机制本身。NEXT_PUBLIC_ 这个前缀的语义,就是在构建阶段把 process.env.XXX 原地替换成字符串字面量。替换完成后,相应的条件分支会被压缩工具作为死代码删除。也就是说,成品代码里已经不存在这个判断了 —— 无论设置什么环境变量,都没有分支可以影响它。

所以判定一个变量属于哪一类,标准不是「文档里有没有写」,而是「成品里还有没有这个字符串」。

六、二进制取证

对成品主程序做原始字节扫描。2.7.84 的主程序为 176,469,048 字节,结果如下:

字符串 是否存在于成品
SCREENPIPE_SKIP_ONBOARDING 存在
TAURI_ENV_DEBUG 存在
SCREENPIPE_E2E_SEED 存在
NEXT_PUBLIC_SCREENPIPE_DEV_BILLING_BYPASS 不存在
NEXT_PUBLIC_SCREENPIPE_FORCE_BILLING_GATE 不存在
NEXT_PUBLIC_SCREENPIPE_E2E 不存在
screenpipe_e2e_force_billing_gate 不存在

三个 NEXT_PUBLIC_ 变量全部缺失,与「编译期内联」的判断完全一致。这也是为什么它们在这台机器上从未生效。

扫描本身很简单,不需要任何反编译工具,把文件当字节流读即可:

targets = [b"SCREENPIPE_SKIP_ONBOARDING",
           b"NEXT_PUBLIC_SCREENPIPE_DEV_BILLING_BYPASS",
           b"NEXT_PUBLIC_SCREENPIPE_FORCE_BILLING_GATE"]
blob = open(exe_path, "rb").read()
for t in targets:
    print(t.decode(), t in blob)

程序升级到 2.7.97 之后复核,分布不变:SCREENPIPE_SKIP_ONBOARDING 仍在,三个 NEXT_PUBLIC_ 变量仍然不在。

七、走错的路(二):命令行参数

第二个方向是尝试命令行参数,例如 --help、--skip-onboarding、--debug、--no-billing 之类。

实测这条路走不通。这是一个 Tauri 图形程序,主程序不解析命令行参数;仓库里确实存在命令行参数,但它们属于另一个 CLI 子命令(record 接受 --port 与 --data-dir),与本体的启动无关。在这一方向上继续尝试没有意义。

八、根因:onboarding 卡在 plan 步骤,主窗口被改道

检查本地状态文件后,问题定位清楚了。状态目录下的 store.bin 是一份明文 JSON(程序自身还维护 .last-good 与 .last-good.prev 两级快照)。其中 onboarding 节点的内容为:

{
  "onboarding": {
    "isCompleted": false,
    "completedAt": null,
    "currentStep": "plan",
    "trialActivationFreshInstall": true
  }
}

同一文件里的用户节点显示 app_entitled=false、subscription_plan="none"、billing_plan="none"。

与此对应的是源码里主窗口的路由判定:

ShowRewindWindow::Main => {
    if !onboarding_store.is_completed {
        return ShowRewindWindow::Onboarding.show(app);
    }

也就是说:只要 isCompleted 为 false,任何「打开主窗口」的请求都会被静默改道到 onboarding 窗口。日志里能直接看到这次改道:

show_main_window called

show_main_window succeeded, window label: onboarding

程序并没有做订阅校验,也没有报错,而是把主窗口一直让给了 onboarding。这就解释了「关闭一次能短暂看到主界面、再点又回到引导页」的循环。

至于为什么会卡在 plan 这一步,前端源码里有一段注释直接描述了该失效模式:plan 是最后一张引导页,在没有取得令牌的情况下自动推进到该页会把使用者困在 onboarding 里 —— 该页无法打开托管结账(它渲染的是「请先登录」),而流程一旦存在下一张幻灯片就不再调用「完成 onboarding」。注释的原话是:跳过登录的人会永远停在 /onboarding。

与之一致的还有两条日志。首次启动、尚未登录时出现:

Skipping server auto-start: screenpipe account access required

以及一条实验分组事件,其中 fallback_variant="control"、outcome="continue_setup" —— 该分组本应继续初始化,但持久化的步骤已经落到 plan,流程没有继续。

这里需要区分另一件事:日志里还出现过 403 与「云端模型在当前国家或地区不可用」的提示。那是云端模型的地域限制,与本次的 onboarding 拦截是两回事,不应混为一谈。

九、解决:两个可逆方案

既然阻塞点是 isCompleted 为 false,那么让 onboarding 被标记为完成即可。有两条路。

方案一:使用官方运行时开关(推荐)

SCREENPIPE_SKIP_ONBOARDING 由 Rust 侧在启动时用读取环境变量的方式取得,取值 1 / true / yes,大小写不敏感。源码注释说明它的用途是「企业 VDI、无头容器、MDM 预置部署,以及任何交互式 onboarding 无法完成的环境」,置位后启动时会把 onboarding 标记为完成,使程序落到主视图。

fn should_skip_onboarding() -> bool {
    std::env::var("SCREENPIPE_SKIP_ONBOARDING")
        .ok()
        .map(|s| matches!(s.trim().to_lowercase().as_str(), "1" | "true" | "yes"))
        .unwrap_or(false)
}

它同时起两个作用:一是启动时把 isCompleted 写为 true;二是作为守卫,短路 trial-activation 那条付费墙的发射逻辑。

[System.Environment]::SetEnvironmentVariable('SCREENPIPE_SKIP_ONBOARDING','1','User')
$env:SCREENPIPE_SKIP_ONBOARDING = "1"
Start-Process "$env:LOCALAPPDATA\screenpipe\screenpipe-app.exe"

回滚方式:把该用户级变量删除即可。

[System.Environment]::SetEnvironmentVariable('SCREENPIPE_SKIP_ONBOARDING',$null,'User')

方案二:修改状态文件

把 onboarding.isCompleted 置为 true,并删除 currentStep。

Copy-Item "$env:USERPROFILE\.screenpipe\store.bin" `
          "$env:USERPROFILE\.screenpipe\store.bin.bak" -Force
Get-Process screenpipe-app -ErrorAction SilentlyContinue | Stop-Process -Force

$p = "$env:USERPROFILE\.screenpipe\store.bin"
$j = Get-Content $p -Raw | ConvertFrom-Json
$j.onboarding.isCompleted = $true
$j.onboarding.completedAt = (Get-Date).ToUniversalTime().ToString("o")
$j.onboarding.PSObject.Properties.Remove('currentStep')
$j | ConvertTo-Json -Depth 20 | Set-Content $p -Encoding UTF8

为什么必须连 currentStep 一起删掉:负责标记完成的方法只写入 isCompleted 与 completedAt,并不清空 currentStep;而另一处判定会读取 currentStep 的取值来决定是否处于试验流程中,删掉它才能让该判定落空。

回滚方式:恢复备份文件即可。程序自身维护的两级快照也可以作为额外保险。

十、怎么验证

四条判据,都可以直接观察:

判据 预期结果
启动日志 出现 SCREENPIPE_SKIP_ONBOARDING: onboarding marked complete(仅方案一)
窗口标签 为 home,路由为 /home
是否仍有改道 不再出现 show_main_window succeeded, window label: onboarding
状态文件 onboarding.isCompleted 为 true

实际观察到的日志是:

SCREENPIPE_SKIP_ONBOARDING: onboarding marked complete

installed WebView2 process-failure handler label=home

十一、顺带确认:搜索框是本地 FTS5 关键词检索

排查的第二个目标 —— 是否存在「直接输入关键词、检索历史屏幕记录」的纯搜索界面 —— 结论是存在,而且不依赖大模型。

(1)快捷键 Alt+K,即设置项 search_shortcut 的默认值;macOS 上为 Control+Super+K。

(2)触发后创建一个独立窗口:窗口标签为 search,路由为 /search。

(3)形态为顶部居中、始终置顶的浮动搜索条,尺寸 680×80,纵向位置在屏幕高度约 22% 处。

(4)前端组件为搜索弹层,配合一个专门的关键词检索状态管理模块。

(5)检索走本地 SQLite 的 FTS5 全文索引。源码注释有两处佐证:一处说明关键词建议只取「已被 FTS 索引」的数据;另一处说明输入至少 3 个字符才开始查询,以避免无谓的 FTS 查询。

(6)另有一条不经过界面的旁路:本地引擎暴露的检索接口,形如 GET http://localhost:3030/search?q=关键词&content_type=ocr。

有一个需要如实说明的观察:在拦截尚未解除的那段时间,搜索窗口实际上已经被创建过(日志中窗口标签 search 出现过 4 次)。当时它能否返回结果,本次未做验证。

十二、可复用结论

(1)带 NEXT_PUBLIC_ 前缀的环境变量是构建期替换,不是运行期开关。对已经构建好的成品设置它们不会生效。判断依据应当是「成品里还有没有这个字符串」,而不是「文档里有没有写」。

(2)区分一个环境变量属于构建期还是运行期,最快的办法是直接扫描二进制。由 Rust 侧在运行时读取的名字会作为字符串保留;被前端构建内联的名字不会。

(3)Tauri 图形程序通常不解析命令行参数。排查这类程序时,不必在 CLI 参数上耗费时间。

(4)「付费墙」与「状态机卡死」表现相似但成因不同。本例中程序并未做订阅校验,而是 onboarding 未完成导致主窗口被改道。定位方法是看状态文件与窗口路由日志,而不是看界面文案 —— 界面文案会把人引向错误的方向。

(5)当状态文件是明文 JSON、且程序自身维护多级快照时,改动风险低、回滚容易。相比之下,二进制补丁既不可逆也不必要。

十三、尚无定论的部分

(1)登录与拦截的关系未做分离实验。首次启动时程序处于未登录状态,并出现 account access required;随后通过深链完成登录,服务端得以启动。但登录之后,主窗口仍然被改道到 onboarding(show_main_window succeeded, window label: onboarding 出现在登录之后)。因此可以确认的是「登录不足以解除改道」,但「未登录是否必然触发拦截」未单独验证。

(2)方案二在 2.7.84 上未单独实测。当时两个方案是先后施加的,无法把效果完全分离。方案二在 2.7.97 上验证通过(不设环境变量启动,窗口标签为 home)。两个版本之间是否存在差异,未验证。

(3)2.7.97 的判定条件未逐行比对。该版本中相关字符串的分布与 2.7.84 一致,但试验分组是否仍然存在、判定条件是否变化,未做源码层面的逐行比对。

(4)文档提到的 localStorage 键未验证。screenpipe_e2e_force_billing_gate 在 2.7.84 与 2.7.97 的成品中均未找到,故未做验证。


文中结论均标注了依据来源(源码、二进制扫描或运行日志),未作推测性补充;无定论之处已在正文中注明。
为保护隐私,涉及的账号口令、访问令牌、机器标识、本机绝对路径与私有服务地址均已脱敏或省略。
文中提及的软件名称与商标归其各自所有者所有。该软件采用 source-available 授权,正式桌面版位于付费墙之后;本文记录的 SCREENPIPE_SKIP_ONBOARDING 是官方文档中面向企业 VDI 与无头环境预留的开关,商业使用仍需遵循其授权条款。
文首表情包取自梗鲸图库(aigengtu.com)#148;「DeepSeek娘」为社区二创,与官方无关 —— 原形象是画师上善无形的 OC「溟月」(CC BY-NC-SA 4.0),女仆装设计出自 B 站 UP 主 ZipZipPipe。


Dreams are the seedlings of realities.