Jan 发布质量验收全解：基于 autoqa/checklist.md 的发布前迁移、Settings 与 Hub 回归清单

2026-09-05 20:03:52作者：柏廷章Berta

本文围绕 Jan 仓库中 autoqa/checklist.md 这份发布验收清单展开，完整还原 Jan 团队在每个版本发布前（Before release）与发布后（After release）执行的验收流程：从旧版本数据迁移检查、Settings 各功能域回归、Hub 与 Threads 行为验证，到出厂重置与全新安装路径清理。读完后你可以掌握一份可直接复用的桌面 AI 客户端发布验收方法，并理解该清单如何与仓库内的自动化 E2E 测试执行器 autoqa 相互衔接。

一、清单整体结构：两个阶段 + 七个发布前功能域

autoqa/checklist.md 是 Jan 的发布质量门禁文档，全文分为两大阶段：

I. Before release（发布前）：包含 7 个功能域（A～G），覆盖数据迁移、Settings 各子项、Hub、Threads、Assistants、出厂重置以及全新安装；
II. After release（发布后）：验证线上更新器（App Updater）在真实用户侧的行为，并要求重跑 A 节迁移检查。

清单中的条目还带有三类特殊标记，理解这些标记是正确执行清单的前提：

标记	含义	示例
`[NEW]`	本版本新增的检查点	`[NEW] Change llama.cpp setting of 2 models`（为 2 个模型修改 llama.cpp 设置，验证设置迁移）
`[ENG]`	面向工程侧的深度检查（通常更耗时长或需构造特殊环境）	用含中文字符的非标准目录名作为 App Data 目录，验证模型仍能在非 ASCII 路径下加载运行
`[0.6.9]`	针对特定版本的回归项（该版本引入的行为变化）	去掉 `.gguf` 扩展名后导入模型、JSON 方式创建 MCP server、streamable-http transport

这份人工清单并非孤存在仓库里。它描述的被测对象正是 Jan 桌面应用本身，而 autoqa/README.md 描述的自动化 E2E 执行器则负责在 CI 环境自动执行部分流程（见第五节）。

二、A 节：初始更新 / 数据迁移检查（最核心的回归域）

数据迁移是桌面应用升级风险最高的环节，清单 A 节的验收目标是：更新前后的用户数据与设置应完全一致，更新不得损坏任何现有数据。

2.1 测试前置：在旧版本中刻意构造"可观察"的数据

在跑迁移测试前，必须先在一个旧版本 Jan 中完成一组有代表性的修改，保证每个数据类别更新后都能被肉眼比对出来：

将界面/主题（Interface / theme）改成与默认明显不同的样式；
保留若干聊天线程（chat threads）与若干收藏/星标线程（favourites / star threads）；
已下载 2 个模型，并在本地推理引擎 llama.cpp 下导入（import）2 个模型；
修改 MCP servers 列表，并为 MCP servers 配置若干 ENV 值；
修改 Local API Server 配置与 HTTPS proxy 配置值；
添加 2 个自定义助手（custom assistants），并用其中一个自定义助手新建一次会话；
将 App Data 数据目录改动到其他文件夹；
创建 1 个 Custom Provider（自定义远程服务商）；
禁用若干模型服务商（Disabled model providers）；
（[NEW] 项）修改 2 个模型的 llama.cpp 设置。

这套前置操作恰好覆盖了 Jan 的所有持久化数据类别：线程、助手、模型（下载/导入）、MCP、API Server、代理、服务商密钥与设置、数据目录位置。

2.2 更新后逐项比对

升级完成后，按以下顺序验证数据无损：

Threads（线程）

线程中此前使用的模型与助手应正确显示；
在线程中应能基于之前的上下文继续会话（resume chat）。

Assistants（助手）与 Settings

自定义助手列表保持存在；
Settings 中 Interface、MCP Servers、Local API Server、HTTPS Proxy 四组设置值与更新前一致。

Custom Provider 设置保持原样。

Hub 内验证

Hugging Face 模型列表正确展示；
已下载模型显示 Use 按钮而非 Download；
右上角 Downloaded 开关过滤出的已下载模型列表正确。

Settings → General

App Data 路径与更新前一致（注意这里验证的是"非默认路径也能被保留"）；
点击 Open Logs 能弹出应用日志。

Settings → Model Providers

llama.cpp 仍列出已下载模型且可正常对话；
llama.cpp 仍列出已导入模型且可正常对话；
远程服务商的 API key 仍保留，无需重新输入即可对话；
启用/禁用状态与更新前一致。

Settings → Extensions，确认四个内置扩展均存在：

Conversational、Jan Assistant、Download Manager、llama.cpp Inference Engine。

从源码结构看，这四项对应仓库 extensions/ 目录下的 conversational-extension、assistant-extension、download-extension 与 llamacpp-extension，即迁移检查最终要确认的是"扩展注册状态"在升级后未丢失。

三、B 节：Settings 全量功能回归

A 节验证"数据没丢"，B 节验证"功能还对"。这是清单中篇幅最大的部分，按 Settings 子页面逐域展开。

3.1 General

Community 各链接可用且指向正确网站；
Check for Updates 能检测到正确的最新版本；
[ENG] 创建含非标准字符（如中文）的目录，将 App Data 改到该目录后，验证模型仍能正常加载运行——这是对整条数据路径（配置、模型、日志）在非 ASCII 场景下健壮性的压力检查。

3.2 Interface

依次切换 Theme 为 Light / Dark / System（System 应跟随操作系统设置），确认所有 UI 元素对比度可读；
修改下列值 → 关闭应用 → 重新打开 → 确认修改跨会话持久化：Theme、Font Size、Window Background、App Main View、Primary、Accent、Destructive、Chat Width（改 Chat Width 时重点确认不会因此产生 UI 破损）、Code Block、Show Line Numbers；
[ENG] Interface 区域的 Reset 应恢复该区域默认值；Code Block 区域的 Reset 同理。

3.3 Model Providers

这是 B 节的核心，分三块：

Llama.cpp（本地推理）

从 Hub 下载的模型在 Models 下列出且名称正确；
可无错导入 gguf 模型，导入后名称正确；
点击 delete 后模型从列表移除；被删模型不出现在聊天输入框的可选模型中（包括曾经用过它的那些旧线程）；被删的导入模型可以再次重新导入；
开启 Auto-Unload Old Models 后同一时刻只能运行/加载 1 个模型；若开启时刻已有 2 个模型在跑，二者都会被停止。关闭该开关后允许多模型并行运行；
开启 Context Shift 后长上下文会话不应出现内存错误。清单给出了一个标准复现方法（"banana test"）：开启 fetch MCP，让本地模型抓取并总结香蕉的历史（该词条的维基百科内容非常长）；如果 Context Shift 未开启，上下文应当足够快地耗尽并报错。这实际上是把一个抽象的"上下文窗口管理"检查项落成了一个可重复执行的具体用例；
单个模型的 Jinja 聊天模板修改不得影响其他模型的模板；
每种系统应提供推荐的 llama.cpp 版本，且开箱即用；
[0.6.9] 将 gguf 文件的 .gguf 扩展名去掉后再导入，验证仍可工作。

远程服务商（Remote Model Providers）

确认 8 家内置服务商存在：OpenAI、Anthropic、Cohere、OpenRouter、Mistral、Groq、Gemini、Hugging Face；
只要在 API key 输入框中输入任意值（即使是错误 key），该服务商的模型就应出现在聊天输入框的可选下拉中；
使用有效 API key 后，选择模型对话无报错；
删除某模型后，它不再出现在 Models 列表视图与聊天输入框下拉中，且在曾使用过它的旧线程里也不可选；
手动新增模型可用，且新增模型可正常对话（测试时可以加回刚删除的模型）；
[0.6.9] 以 Custom Provider 方式配置的 Ollama 应与 Jan 正常工作。

Custom Providers（自定义服务商）

可用正确的 baseURL + API key 创建；
点击 Refresh 能拉取该服务商的模型列表；
可用自定义服务商对话；
自定义服务商可删除，且删除后在新会话中不再出现。

通用规则

被禁用的 Model Provider 不应在新线程与旧线程的聊天输入框中可选；旧线程的输入框应显示 Select Model 占位而非被禁用的模型名。

3.4 Shortcuts

确认以下快捷键组合在界面上可见且实际生效：New chat、Toggle Sidebar、Zoom In、Zoom Out、Send Message、New Line、Navigation。

3.5 Hardware

硬件页应显示：Operating System、CPU、Memory，以及（如有）GPU；
启用/禁用 GPU 后模型在两种模式下都应能正确运行；GPU 开关切换不应影响应用 UI。

3.6 MCP Servers

MCP（Model Context Protocol）服务管理是清单中条目最密集的子域，要点包括：

正确填写信息后可成功创建 MCP server；
Env 值在快速视图中以 * 掩码显示；缺少必需 Env 值时应弹出错误提示；
删除 MCP server 后无错地从列表消失；删除前该 server 会先自行禁用，删除后不出现在工具列表中；
编辑 MCP server 内容后，UI 与实际运行行为都应同步更新；
enable/disable 开关正常工作；禁用的 MCP 不出现在聊天输入框的可用工具列表中；即使被模型强行提示调用，禁用的 MCP 也不应被调用（确保不存在"幽灵 MCP server"）；
已启用的 MCP server 应在应用启动时自动启动，且其 functions 显示在可用工具列表中；
同一线程内可用一个模型调用多个已启用 MCP server 的不同工具；
权限确认机制（工具级审批）：
- Allow All MCP Tool Permissions 关闭时：每个新线程中，工具调用前都应弹出确认对话框；
- 点 Deny：工具调用不执行，工具调用结果中返回相应提示消息；
- 点 Allow Once：下一次调用该工具时仍会再次弹窗；
- 点 Always Allow：该工具在工具粒度（而非 MCP server 粒度）保留权限，不再弹窗；
- Allow All MCP Tool Permissions 开启时：工具调用不再出现任何确认弹窗；
- 弹窗出现时，Tool Parameters 明细也应一并展示；
[0.6.9] 创建 MCP 时可进入 Enter JSON configuration 粘贴 JSON 配置并保存，server 应正常工作；JSON 格式错误时该 MCP server 不应被激活；MCP server 应可通过 streamable-http transport 使用（可连接 Smithery 测试）。

3.7 Local API Server 与 HTTPS Proxy

Start Server 后可通过默认端点对话：v1/models 返回正确的模型名，v1/chat/completions 可对话；
Open Logs 展示发往服务器及服务器返回的正确查询日志；
Server Configuration 中所有参数的修改都应在 Start Server 后生效；
[0.6.9] 启动配置时，上次使用的模型也应被自动启动（用户无需先手动启动模型再启动服务器）；
[0.6.9] 向 Local API Server 发送图片应能工作（可在 Jan 中把 Local API Server 配为 Custom Provider 来自测）；
HTTPS Proxy：模型下载请求应经由代理端点发出。

四、C～E 节：Hub、Threads 与 Assistants

4.1 Hub（C 节）

点击 Download 可下载模型；下载中途可取消；
在搜索栏粘贴模型名/模型 URL 后按回车，可把 Hugging Face 模型详情加入列表；
点击列表项在 Jan 内打开 model card 并正确渲染 HTML；Show variants 区域的下载按钮与 model card HTML 内的下载按钮都可用；
[0.6.9] 基于用户硬件的模型推荐应在 Model Hub 中按预期工作。

4.2 Threads（D 节）

左侧栏行为

删除旧线程后，重启应用不复活；
修改线程标题应更新其最后修改时间，并按时间顺序在左栏重新排序；
新线程标题默认取用户的第一条消息；
星标/取消星标工作正常，星标线程进入 Favourite 区、其余留在 Recent 区；
线程搜索应基于标题与内容返回准确结果，且覆盖 Favourite 与 Recent 两个区；
Delete All 只删除 Recents 区线程；Unstar All 取消所有 Favourites 的星标并让它们回到 Recent。

线程内部行为

点击 New Chat 时：助手取上次选定的助手、模型取上次使用的模型，用户可立即开聊；
单线程多轮对话不丢上下文（前提：未启用 Context Shift）；
会话中途切换模型、切换助手（新助手设置立即生效）均正常；
点击 Regenerate 可基于已有上下文重新生成回复；
长线程可完整渲染并上下滚动；
旧线程保留上次更新/使用时的设置：助手选项与模型选项（模型/服务商已被删除或禁用时除外）；
消息内容支持文本、emoji 等多类型；模型生成的 Markdown 表格正确格式化；代码片段按 Interface → Code Block 设置格式化；
用户可编辑自己的旧消息并基于新消息重新生成答案；可 Copy 模型回复；可 Delete 用户消息或模型消息；
生成过程中显示 token 速度，最终值展示在回复下方；
IME 输入中文/日文时按 Enter 确认候选词，不应自动触发 Send（每确认一个词就发一次消息）；
[0.6.9] 附件图片后可分别用远程模型与本地模型对话；可从系统剪贴板直接向输入框粘贴图片；用户可在聊天输入框的模型选择器中收藏（favourite）模型。

4.3 Assistants（E 节）

系统始终至少存在一个默认助手 Jan；
默认 Jan 助手默认 stream = True；
用户可创建/编辑带不同参数与指令的助手；
删除默认助手后，队列表中下一个助手自动顶替为默认助手，并把其设置应用到新会话；
可在聊天窗口内（左上角）直接创建/编辑助手。

五、F～G 节：出厂重置、数据目录自愈与全新安装

F 节（"检查完其他一切之后"）是对数据层的破坏性验证，必须在确认前面功能都通过后再执行：

将 App Data 改到非默认路径；
点击 Other 中的 Reset 执行出厂重置，逐项确认：
- 全部线程被删除；
- 除默认 Jan 助手外全部助手被删除；
- App Data 路径重置回默认；
- 界面设置重置；
- 模型服务商信息全部重置（llama.cpp 设置重置、API keys 清空、全部 Custom Provider 删除）；
- MCP Servers、Local API Server、HTTPS Proxy 重置；
关闭应用后所有模型被正常卸载；
数据目录自愈：按 App Data 路径定位数据文件夹 → 手动删除整个文件夹 → 重新打开应用，所有文件夹与必要数据应被自动重建；
确认卸载流程能真正把应用从系统中移除。

G 节（全新安装）要求先按平台清干净 Jan 残留目录：

平台	需清理的目录
macOS	`~/Library/Application Support/Jan`、`~/Library/Caches/jan.ai.app`
Windows	`C:\Users<Username>\AppData\Roaming\Jan\`、`C:\Users<Username>\AppData\Local\jan.ai.app`
Linux	`~/.cache/Jan`、`~/.cache/jan.ai.app`、`~/.local/share/Jan`、`~/.local/share/jan.ai.app`

清理后确认：全新安装的 Jan 能正常启动，并对核心功能（Thread 与 Model Providers）做抽查——清单建议不必再逐条重跑整份清单，但核心链路必须通过。

六、II 节：发布后（After release）验证

发布后的检查只有三条，但指向真实用户侧行为：

App Updater 可用，用户可无问题更新到最新 release；
用户完成更新后应用会重启；
重跑 A 节（Initial update / migration Data check），确认在 live 版本上更新过程确实正确。

这与 autoqa/reportportal_handler.py 中按平台定位 Jan 日志路径的逻辑相呼应：该模块会根据进程名是否含 nightly 在 Jan 与 Jan-nightly 的日志目录间切换（Windows 为 %APPDATA%\Jan\data\logs，macOS 为 ~/Library/Application Support/Jan/data/logs，Linux 为 ~/.local/share/Jan/data/logs），说明 nightly 与正式版是两条并行的发布通道，发布后验证对两者都要覆盖。

七、清单之外：autoqa 自动化 E2E 执行器如何承接这份清单

autoqa/checklist.md 是给人执行的验收标准，而 autoqa/ 目录下的 Python 测试执行器是把这些验收动作自动化的载体，二者通过同一套 tests/ 文本用例衔接：

用例即 prompt：测试文件是放在 tests/ 目录（支持嵌套）中的 .txt 文件，文件内容本身就是给 AI Agent 的自然语言操作步骤。仓库自带的示例 autoqa/tests/new-user/1-user-start-chatting.txt 要求 Agent：打开 Hub → 找到 qwen3-0.6B → 点击 Use → 等待下载完成 → 输入消息并发送 → 等待回复，最后以 {"result": True} 或 {"result": False} 收尾。这与清单 C 节"Hub 下载并对话"的验收点一一对应。
判定逻辑：autoqa/reportportal_handler.py 的 extract_test_result_from_trajectory 会读取 Agent 轨迹最后一个 turn_ 目录里最后一个 api_call_*_response.json 的回复内容，用正则匹配 {"result": True} 判 PASSED，{"result": False} 或缺失均判 FAILED——与示例用例中"只返回纯 ASCII 的 result JSON"的约定严格对齐。
执行生命周期：autoqa/test_runner.py 中 run_single_test_with_timeout 为每个用例执行固定九步：检测并强杀残留 Jan 进程 → 启动 Jan（最大化窗口）→ 开始屏幕录制 → 构建 ComputerAgent → 启动轮次监控线程（轮询 trajectories/ 下 turn_ 目录数量，达到 max-turns 上限即强制停止并标记失败）→ 以 600 秒为兜底超时运行 Agent → 停止录制 → 可选上传 ReportPortal → 结束后一律强杀 Jan 进程，保证下一个用例从干净状态开始。
应用生命周期工具：autoqa/utils.py 提供跨平台的进程探测（is_jan_running/force_close_jan，基于 psutil）与应用启动（start_jan_app，Windows 直接 Popen、macOS 通过 open 启动 .app bundle、Linux 直接执行），并在各平台用不同方式最大化窗口（Windows 用 pygetwindow、Linux 用 wmctrl/xdotool、macOS 用 AppleScript）。
录像与上报：autoqa/screen_recorder.py 以 10fps 用 pyautogui + OpenCV 将屏幕录制成 MP4；启用 --enable-reportportal 时，每个用例的轨迹截图（.png）、API 调用 JSON、屏幕录像与 Jan 应用日志（最多 5 个、单文件 50MB 上限）都会作为附件上报到 ReportPortal，便于对失败用例做人工回放。
CI 落地：autoqa/scripts/README.md 说明 scripts/ 目录下的 cleanup / download / install / post_cleanup 脚本按平台成组，配合 autoqa/scripts/run_tests.sh 在 CI 中完成"清理旧安装 → 下载安装指定版本 → 运行 python main.py --enable-reportportal ... → 卸载清理"的完整闭环，并可通过 JAN_APP_PATH、JAN_PROCESS_NAME、IS_NIGHTLY 等环境变量切换 nightly/stable 通道——这正好支撑了清单 F、G 节"卸载残留清理 + 全新安装"在 CI 上的自动化执行。

八、如何把这份清单用起来

版本升级发布前：先按 A 节 2.1 在旧版本中构造数据，升级后按 2.2 逐项比对；再做 B～E 节功能回归；
收尾：最后执行 F 节破坏性检查（重置与数据目录自愈），再按 G 节做全新安装验证；
发布后：执行 II 节三条，并把 A 节迁移检查在 live 版本上重跑一遍；
CI 自动化：将重复性高的用例（如 Hub 下载对话）写成 tests/ 下的 .txt 用例，通过 python main.py 或 autoqa/scripts/run_tests.sh 在 CI 中执行，结果与录像自动上报；
标记管理：每新增一个版本特性，就按 [NEW] 在对应功能域追加检查点；针对特定版本行为变化的回归项沿用 [版本号] 标记（如 [0.6.9]）以便追溯。