免费开源的AI软件首启动 FirstRunSetup向导背后做了什么
第一次打开察元AI 桌面单机版会看到一个向导界面，三四屏走完才进主界面。这个向导叫 FirstRunSetup，是 chayuan-desktop 的首启动初始化流程。看似简单的几步选择，背后做了不少事。这一篇拆开讲一下。
向导第一屏：欢迎页。展示产品名称、版本号、AGPL-3.0 许可声明、品牌标识保留要求。这一屏的实际作用是给新用户一个明确的产品身份，同时把许可信息显式呈现，避免后期用户做二次分发时不知道许可范围。这一屏过去会写一份配置标记到 CHAYUAN_ROOT/data/firstrun.json，标志已经接受过条款。
第二屏：选数据目录。这是整个向导的核心一步。CHAYUAN_ROOT 决定后续所有数据的家。向导默认推荐当前用户目录下的一个 chayuan-desktop 子目录，比如 Windows 上的 %APPDATA%、macOS 上的 ~/Library/Application Support、Linux 上的 ~/.local/share。你可以改成任何有读写权限的目录。一旦选定，Tauri 主进程会把这个路径写到自己的配置文件里，下次启动时会通过环境变量注入给 sidecar。
第三屏：模型权重预下载。chayuan-desktop 默认携带了几个本地模型权重的下载入口：嵌入模型 bge-m3-onnx 约 600M，OCR 模型 RapidOCR 约 100M，重排模型 bce-reranker-base 约 300M。这一步会问你要不要预下载。如果是有外网环境，建议预下载，等模型权重在 CHAYUAN_ROOT/models 落好之后再进主界面。如果是无外网环境，跳过这一步，再手动把权重文件拷到对应目录。
第四屏：sidecar 启动确认。Tauri 主进程会问你允不允许它拉起后端 sidecar 子进程。这一步在 macOS 上特别重要，因为系统会弹出一个权限请求弹窗。同意之后 Tauri 通过 spawn API 起 chayuan-server 子进程，注入 CHAYUAN_ROOT 环境变量、监听 127.0.0.1:62581。健康探针通过之后向导退出，主界面打开。
向导背后的几个细节。一是 CHAYUAN_ROOT_IGNORE_STATE 这个环境变量。仓库最近的提交里加了一段，让 Tauri 注入的 data_dir 真的生效，避免 sidecar 用上了系统默认目录而不是用户选的目录。这个细节直接影响首启动的数据存放正确性。
二是健康探针。Tauri 起 sidecar 之后不会立刻进主界面，而是循环 GET 一个 /health 接口，等到返回 200 才放行。如果 30 秒内没起来，会直接报错让用户重试。早期版本的探针逻辑比较粗糙，后来改成多次重试加可配置间隔，启动体感稳定很多。
三是首启动唯一性。如果 firstrun.json 已经存在，向导会跳过直接进主界面。这意味着 CHAYUAN_ROOT 一旦定下来不容易改。要换数据目录，要么先删掉 firstrun.json 重走向导（但旧目录数据要手动迁移），要么改 Tauri 配置让它指向新目录。
向导跑完之后用户可以做什么。第一，进设置确认 CHAYUAN_ROOT 路径正确；第二，配第一个模型供应商；第三，建第一个知识库；第四，发第一句对话。这四步走完才算真正上手。
国产化支持下的几个变体。麒麟、UOS 上向导整体一致，但模型权重下载默认推荐从内网镜像拉，避免出域。openKylin 上 Tauri 主进程的窗口图标偶尔会被桌面环境忽略，向导界面跑起来不影响。loongarch64 架构上向导本身跟 x86_64 没差，但 sidecar 启动的依赖检查会多一步，对应的发行包里 PyInstaller 打的是龙芯架构二进制。
WPS AI 插件 chayuan-wps 没有自己的 FirstRunSetup，它把首启动配置完全交给桌面单机版，加载项侧只负责连后端。这种角色分工让两边的初始化责任清晰，不会出现两个产品互相抢配置的问题。
FirstRunSetup 是 免费开源的AI软件 第一次跟用户握手的环节。把这一关做得简洁、稳定、可重入，就少了一大批装机第一天的支持工单。