发布前测试大纲（操作 Checklist）
写法：每一行都是 界面 → 操作 → 预期效果。验收时打开应用，按表逐步点选并勾选。
依据：当前已落地能力（发布线 0.6.0）；不含路线图未交付项（Connected Papers 邻域、引用图反向高亮、Vault 采纳等）。
环境：至少 macOS；发布含 Windows/Linux 时，§0 + §1 各平台各跑一遍。
数据：pnpm demo:vault / pnpm demo:vault:downloads；另备一次 Create Vault 空库。
| 标记 |
含义 |
| ☐ |
未测 |
| ✅ |
通过 |
| ❌ |
阻塞发布 |
| ⚠️ |
已知限制，非阻塞（写进 Release notes） |
| N/A |
本平台/本轮不测 |
| 项 |
值 |
| 待发版本 / tag |
|
| 测试人 / 日期 |
|
| 阻塞问题 |
|
界面代号（下文「界面」列）
| 代号 |
在哪里 |
| 欢迎页 |
未打开 Vault 时的中间栏 |
| 标题栏 |
窗口顶部菜单 / 布局按钮 |
| 左栏·树 |
左侧 Vault 文件树 |
| 左栏·Info |
选中论文时的 Paper Info |
| 中间栏 |
Dockview 工作区（Library / PDF / MD / 回收站等） |
| 右栏·Agent |
右侧 Agent 面板 |
| 右栏·References |
右侧引用卡片 + 近邻图 |
| 右栏·反链 |
编辑器状态栏反链（非引用图） |
| 设置 |
⌘, 居中浮层 |
| 命令面板 |
⌘P / ⇧⌘P |
| 任务条 |
左下角后台任务 |
| Toast |
右上角 Sonner |
| 终端 |
系统终端（CLI 项） |
0. 构建与安装（非 UI）
0.1 版本
| # |
界面 |
操作 |
预期 |
结果 |
| 0.1.1 |
仓库 / 终端 |
对比 package.json、src-tauri/tauri.conf.json、src-tauri/Cargo.toml、cli/Cargo.toml 版本 |
四者一致，且等于 tag 去掉 v |
☐ |
| 0.1.2 |
应用·设置 / About |
打开设置或关于，看版本号 |
与 tag 一致 |
☐ |
| 0.1.3 |
终端 |
运行 Release 里的 agentero --version |
与 tag 一致 |
☐ |
0.2 自动化（本机或 CI）
pnpm lint && pnpm test && pnpm build
cargo test --manifest-path src-tauri/Cargo.toml
cargo test -p agentero-core -p agentero-cli
| # |
界面 |
操作 |
预期 |
结果 |
| 0.2.1 |
终端 |
跑上列命令 |
全部通过 |
☐ |
| 0.2.2 |
GitHub Actions |
Release job 的 updater secret 校验 |
TAURI_SIGNING_PRIVATE_KEY 和密码缺失时在创建 Draft 前失败 |
☐ |
| 0.2.3 |
Draft Release |
检查 updater 资产 |
有 latest.json、各平台 updater 包与对应 .sig；latest.json 包含每个平台的 URL 和签名 |
☐ |
| 0.2.3a |
GitHub Actions / AtomGit |
配置 ATOMGIT_TOKEN，发布 Release 后检查自动触发的同步 job（或按 tag 手动 Run workflow） |
「Publish the release tag on AtomGit」步骤不因 push 被拒而失败：镜像仓库会告警 pull-mirror (image) repository 后继续；同名 tag 提交一致；说明和全部上传附件同步；每个附件回读 SHA-256 一致；重跑不重复附件；最新稳定版发布后标记 latest；预发布与补传旧稳定版为 pre 且不抢占现有 latest；缺令牌或附件失败时 job 报错 |
☐ |
| 0.2.3b |
GitHub Actions / AtomGit |
检查同步 job 的「Pin AtomGit to its overseas edge」步骤日志 |
四个域名全部 Pinned <host> -> <IP>；getent hosts 显示该 IP；上传日志的 via <host> 为 file.gitcode.com（已在固定列表内，若变成别的 OBS 域名需补进列表）；120 MB 级 AppImage 在数十秒内 Uploaded and verified，无 HTTP 502、无 Retry n/2 |
☐ |
| 0.2.4 |
GitHub Actions / 应用·设置 |
确认 AGENTERO_BUILTIN_API_KEY secret 已配且本次构建注入了它 |
缺 secret 不会让构建失败（option_env! 当未设置处理），只会静默产出没有内置 provider 的包。信号：设置 → 翻译的「Agentero 内置」可选、设置 → Agent → Embedding 的来源默认「Agentero 内置」、设置 → 版面解析的正文引擎默认「Agentero 内置」。见 release.md §内置 Provider 构建期注入 |
☐ |
0.3 安装启动
| # |
界面 |
操作 |
预期 |
结果 |
| 0.3.1 |
系统 |
安装本次产物并首次启动 |
无崩溃、无白屏；进入欢迎页。Linux 在 22.04+ 验收 |
☐ |
| 0.3.1b |
终端 |
检查产物不含 CLI（macOS：ls Agentero.app/Contents/MacOS/ | grep agentero-cli；Windows：安装目录 dir agentero-cli*） |
应无任何 agentero-cli 文件（不内置真二进制，也不再有占位 stub；#320） |
☐ |
| 0.3.2 |
欢迎页 |
不打开 Vault，空看界面 |
同一行有 Create / Open / Open remote / Migrate from Zotero + Recent 列表；无大段说明文案 |
☐ |
| 0.3.3 |
设置 → 关于 |
已安装旧版时检查已发布新版，点「安装并重启」 |
有新版提示、下载进度；重启后 About 显示新版本 |
☐ |
| 0.3.3b |
主窗口 |
应用跨多个 Release 长期驻留后点标题栏「新版本」标签 |
安装的是最新版而非驻留期间缓存的旧版（安装前 re-check；#481） |
☐ |
| 0.3.4 |
主窗口 |
启动已安装旧版 |
首屏不阻塞；有新版时只出现一个「安装并重启」Toast；无更新或离线时不弹错误 |
☐ |
| 0.3.5 |
访达（macOS） |
安装后启动一次，右键任意文件夹 → 快捷操作 |
出现 Open with Agentero；点击后打开为 Vault（运行中/未运行各测一次）；含空格/中文目录名正常；设置 → 关于 移除后菜单消失且重启不再自动恢复 |
☐ |
| 0.3.6 |
资源管理器（Windows） |
安装后右键文件夹及文件夹空白处 |
均有 Open with Agentero（Win11 在「显示更多选项」）；含空格/&/中文的目录可打开；卸载后 reg query 无 OpenWithAgentero 残留 |
☐ |
1. 五分钟冒烟（必过）
用全新空目录走通主路径；任一步 ❌ 则阻塞发布。
| # |
界面 |
操作 |
预期 |
结果 |
| 1.1 |
欢迎页 |
点 Create vault，选空文件夹 |
进入工作台；左栏出现 papers/ notes/；磁盘有 .agentero/catalog.sqlite、AGENTS.md；无根级 plans/、PAPERS.md |
☐ |
| 1.2 |
中间栏 |
观察默认中间区 |
为 Library（可空表或空状态） |
☐ |
| 1.3 |
左栏·树 |
点魔棒图标，或 ⇧⌘I |
打开魔棒弹层 |
☐ |
| 1.4 |
魔棒弹层 |
粘贴 1706.03762，确认入库 |
左下角任务条有进度；成功后左栏树展开并滚到新论文行；中间打开该 paper |
☐ |
| 1.5 |
中间栏 |
看 paper 布局 |
默认 左 PDF · 右 NOTES（左右分屏） |
☐ |
| 1.6 |
中间栏·NOTES |
在 NOTES 打几个字，等自动保存；用外部编辑器打开磁盘 NOTES.md |
磁盘内容已更新 |
☐ |
| 1.7 |
左栏·树 |
点虚拟节点 Library |
中间表有刚入库的那一行 |
☐ |
| 1.8 |
系统 |
完全退出应用再启动 |
若设置开启「恢复上次 Vault」：直接回到该库；否则欢迎页 Recent 可点回 |
☐ |
2. 欢迎页与 Vault 切换
| # |
界面 |
操作 |
预期 |
结果 |
| 2.1 |
欢迎页 |
点 Open vault，选已有 Vault（如 demo） |
文件树 + Library 加载；无崩溃 |
☐ |
| 2.2 |
欢迎页 |
点 Recent 里一条本地路径 |
打开该库 |
☐ |
| 2.3 |
欢迎页 |
在 Recent 移除一条 |
条目消失；再次打开欢迎页仍不在 |
☐ |
| 2.4 |
欢迎页 |
点一条已删除磁盘路径的 Recent |
Toast 报错；该条从列表剔除 |
☐ |
| 2.5 |
左栏·树顶栏 |
点 Vault 标题下拉 → Create vault / Open vault… |
与欢迎页同类操作，可切换库 |
☐ |
| 2.6 |
标题栏 / 菜单 |
File → New Window 或 ⌘N |
新窗口从欢迎页开始，不自动占用旧窗 Vault |
☐ |
| 2.7 |
两窗口 |
窗口 A 开库 A，窗口 B 开库 B |
互不抢 session；文件树各自独立 |
☐ |
| 2.8 |
欢迎页 |
（可选）Migrate from Zotero：先建库再选 Zotero 数据目录 |
迁移对话框可走完；Library 有条目；用户已有 NOTES 不被静默抹掉 |
☐ |
3. 左栏文件树
前置：已打开 demo 或有内容的 Vault。
| # |
界面 |
操作 |
预期 |
结果 |
| 3.1 |
左栏·树 |
刚打开库时看默认展开 |
papers/ 展开（及约定一级）；不会整库无限展开 |
☐ |
| 3.2 |
左栏·树 |
展开 papers/ 下论文行 |
标签符合设置（默认「标题 · 作者」）；磁盘文件夹名未改；无附件时无 chevron |
☐ |
| 3.2a |
左栏·树 |
打开带 {paper}/attachments/ 文件的论文行 |
有 chevron；展开后附件直接挂在论文下（不显示 attachments 桶，也不露出 source/ / marks/）；点行仍打开论文 |
☐ |
| 3.3 |
设置 → 通用 |
改 Paper 行标签 / 排序 各选一档，回看树 |
展示标签/顺序变了；磁盘路径不变 |
☐ |
| 3.4 |
左栏·树 |
在 notes/ 右键 → 新建文件，输入名回车 |
出现新 .md；中间可打开编辑 |
☐ |
| 3.5 |
左栏·树 |
右键 → 新建文件夹 |
内联命名成功；树刷新 |
☐ |
| 3.5a |
左栏·树 |
分别在重命名、新建文件/文件夹、移动面板新文件夹中用中文输入法选字，按 Enter / Escape |
Enter 只确认候选词，Escape 只取消候选词，命名输入/移动面板仍保留；组字结束后再次按 Enter 才提交，普通 Escape 仍可取消/关闭（#746） |
☐ |
| 3.5b |
左栏·树 |
树内命名确认候选词后点击外部；另测提交后立即移焦、空名称与非法名称 |
失焦提交完整名称且只提交一次；空名称取消，非法名称保留编辑；重命名未改变名称则取消 |
☐ |
| 3.6 |
左栏·树 |
⌘ 点多选若干项，再拖到 papers/ 某组织夹 |
标题栏原位切换为数量 / 移动 / 删除 / 清除；树不下移、不被遮挡；文件移入目标后树与磁盘一致 |
☐ |
| 3.6a |
左栏·树 |
多选后分别右键已选行与未选行；Shift 范围同时覆盖父夹与后代 |
已选行菜单作用于整组；未选行先收敛为单项；父夹代表其后代且批量数量不重复 |
☐ |
| 3.6b |
左栏·树 |
用 Tab 聚焦文件行，按 Space；再选中一行按 Enter；多选后按 Esc |
Space 激活行且读屏获得 aria-selected；Enter 直接进入该行内联重命名；Esc 退出选择模式，树不位移 |
☐ |
| 3.6c |
左栏·树 |
重命名一个文件，输入不带扩展名的名称（如 notes/foo.md → bar） |
出现文件夹 bar/，原文件保留后缀并改名为 bar/bar.md；双链/打开的标签跟随新路径；失败不残留空文件夹（#759） |
☐ |
| 3.7 |
左栏·树 |
选中文件，右键 在 Finder 中显示 或 ⌥⌘R |
系统访达定位到该项 |
☐ |
| 3.8 |
左栏·树 |
选中文件夹，右键 在终端中打开 或 ⌥⌘T |
系统终端 cwd = 该文件夹 |
☐ |
| 3.9 |
左栏·树 |
选中文件再 ⌥⌘T |
终端 cwd = 父目录 |
☐ |
| 3.10 |
左栏·树 |
选中文件夹，⌘← |
该文件夹折叠 |
☐ |
| 3.11 |
左栏·树 |
⇧⌘← |
折叠回默认（只留 papers/ 等约定展开） |
☐ |
| 3.12 |
中间栏 |
打开某 paper / md 后看左栏 |
树展开祖先并滚到对应行 |
☐ |
3.A 删除与回收站
| # |
界面 |
操作 |
预期 |
结果 |
| 3.A.1 |
左栏·树 |
右键某非关键文件 → 删除（或 ⌘⌫） |
无确认框、无 Undo toast；项从树消失 |
☐ |
| 3.A.2 |
左栏·树 |
点 Library 下 Recycle Bin |
中间栏打开回收站列表，可见刚删项 |
☐ |
| 3.A.3 |
中间栏·回收站 |
点 恢复 |
文件回原路径；树可见 |
☐ |
| 3.A.4 |
中间栏·回收站 |
再删一次后点 永久删除 |
项消失且无法恢复 |
☐ |
| 3.A.5 |
左栏·树 |
在 Recycle Bin 节点右键 清空 |
回收站空 |
☐ |
| 3.A.6 |
左栏·树 |
删除一篇 paper 文件夹 |
Library 对应行消失；恢复 paper 后 Library 行回来 |
☐ |
3.B 外部修改与冲突
| # |
界面 |
操作 |
预期 |
结果 |
| 3.B.1 |
中间栏·MD |
打开某 .md，不做未存编辑；用外部编辑器改磁盘同文件并保存 |
应用内编辑器自动变成磁盘内容 |
☐ |
| 3.B.2 |
中间栏·MD |
打开同文件，在应用内先改几个字（未落盘），再用外部编辑器改磁盘 |
Toast 提示冲突/重载；不静默覆盖你的未存改动 |
☐ |
| 3.B.3 |
访达 / 终端 |
在 Vault 外新建或删除一个文件 |
文件树去抖刷新后反映变化 |
☐ |
4. 中间栏工作区（Dockview）
| # |
界面 |
操作 |
预期 |
结果 |
| 4.1 |
左栏·树 |
点虚拟 Library |
中间全库表；标题栏没有单独文档 tab 条 |
☐ |
| 4.2 |
左栏·树 |
点一篇 paper |
打开 PDF|NOTES 分屏 panel |
☐ |
| 4.3 |
左栏·树 |
再点另一篇 paper |
叠进同一两栏（不强制拆出第三列）；body/NOTES 同步切换 |
☐ |
| 4.4 |
左栏·树 |
点 notes/ 下某 md、再点一张图、再点任意路径 PDF |
各打开对应 panel；切换后滚动/缩放尽量保留 |
☐ |
| 4.5 |
中间栏 |
对已打开路径的文件再点一次树 |
聚焦已有 panel，不重复开两个 |
☐ |
| 4.6 |
中间栏 |
打开设置 ⌘,，再按 ⌘W 或 Esc |
先关设置，不关文档 panel |
☐ |
| 4.7 |
中间栏 |
无弹层时连按 ⌘W |
逐个关 panel；只剩全库后再按 → 关窗口 |
☐ |
| 4.8 |
中间栏 |
开多个 panel 后 ⌥⌘→ / ⌥⌘← |
按视觉顺序循环激活 |
☐ |
| 4.9 |
左栏·树 |
单击 papers/ 下非 paper 的组织文件夹 |
仍是 Library 表，但只显示该 path 前缀下的论文（不新开 tab、不整库重拉） |
☐ |
| 4.9.1 |
左栏·树 |
组织文件夹含索引 NOTES.md，且内部有多篇 paper |
组织文件夹保持可展开；内部每篇 paper 独立显示，不被合并成父目录 |
☐ |
| 4.10 |
标题栏 Layout |
开关 NOTES 相关项 / 快捷键 |
NOTES 显示或隐藏符合菜单 |
☐ |
| 4.10a |
标题栏 Layout |
打开 PDF / NOTES 双列，在 NOTES 栏再堆多个标签；再构造三栏或四栏，点击 阅读；再次点击 阅读 |
第一次点击只显示当前活动分组并铺满工作区，左右栏收起；其它分栏和标签未关闭；再次点击恢复原多栏 / 多标签布局与栏宽；在 custom 状态下重复点同一预设也立即生效（#764） |
☐ |
| 4.11 |
中间栏 |
把 paper tab / tab group 拖过相邻 Library，再拖成上下或左右分屏；从树拖文件到边；drop / cancel 后立即在 Library、MD、PDF 正文选字 |
移动中不出现原生文字选区；多分屏网格可用；结束后正文恢复正常选择 |
☐ |
| 4.12 |
左栏 / 右栏 |
点折叠按钮；交替 ⌥⌘S / ⌘L |
侧栏折叠且保留像素宽度；两栏快捷键不「抢成互斥坏掉」 |
☐ |
| 4.13 |
系统 / 右栏 |
拖动 AI 栏宽度后开关右栏、切换 Agent/笔记/阅读预设、重启应用；调整并最大化主窗后重启 |
AI 栏始终恢复最后拖出的宽度；主窗尺寸、位置和最大化状态恢复 |
☐ |
| 4.14 |
全局 UI / 移动端 |
在标题栏、导航、工具栏、Library 表头、回收站行和可点击卡片上拖动或长按，再分别在 MD、PDF、Agent 回复、Plaza 文章、metadata 与输入框中选字 |
操作型 Chrome 不出现文字选区；正文、可复制值及编辑控件仍可选择和复制 |
☐ |
5. Library 与标签
| # |
界面 |
操作 |
预期 |
结果 |
| 5.1 |
左栏·树 |
点 Library |
中间表格列出 catalog 论文 |
☐ |
| 5.2 |
中间栏·Library |
点表头排序 |
行序变化 |
☐ |
| 5.3 |
中间栏·Library |
表头右键勾选列显隐；拖拽列序 |
标题列不能隐藏；刷新后列配置仍在 |
☐ |
| 5.4 |
中间栏·Library |
搜索框输入标题片段或 tag 名 |
行被过滤 |
☐ |
| 5.5 |
左栏·树 |
选中某 paper |
左下或 Info 区出现 Paper Info |
☐ |
| 5.6 |
左栏·Info |
添加 tag，选一种颜色 |
chip 出现；Library tags 列同色；重启后仍在 |
☐ |
| 5.7 |
左栏·Info |
删除某 tag |
Library 与 Info 同步消失 |
☐ |
| 5.8 |
中间栏·Library |
点 Rescan（空态或工具栏） |
盘上有、表中无的 paper 出现 |
☐ |
| 5.9 |
左栏·树 |
在 papers/ 论文库节点右键 导出论文库 |
得到可用 BibTeX |
☐ |
| 5.10 |
中间栏·Library |
对缺 PDF 的行触发批量 Download |
任务条有进度；缺的资源补齐 |
☐ |
| 5.11 |
中间栏·Library |
打开有阅读记录的 paper，回到 Library |
标题列左侧出现阅读热力条；未读论文无热力条 |
☐ |
6. 入库
6.1 魔棒（精确 ID）
| # |
界面 |
操作 |
预期 |
结果 |
| 6.1.1 |
左栏·树 |
先点选 papers/ 或某子文件夹；打开魔棒 ⇧⌘I |
弹层打开 |
☐ |
| 6.1.2 |
魔棒 |
粘贴 arXiv ID 1706.03762 入库 |
目标目录下新建论文夹；PDF 在论文根；arXiv 有 source/ TeX；有 NOTES.md 壳；catalog 有行 |
☐ |
| 6.1.3 |
魔棒 |
粘贴 arXiv URL 再入一篇 |
同上语义 |
☐ |
| 6.1.4 |
魔棒 |
粘贴一个可用 DOI |
有 catalog 行；尽量有 PDF；失败则 Toast，侧栏无常驻红条 |
☐ |
| 6.1.5 |
魔棒 |
一次粘贴多个 ID（换行/逗号） |
去重后创建对应数量的独立后台任务并并行入库；每个任务显示自己的进度；不会对每篇自动连跑精读 |
☐ |
| 6.1.6 |
魔棒 |
对已有 NOTES 的 paper 再入同一 ID |
不覆盖用户 NOTES.md |
☐ |
| 6.1.7 |
设置 → 通用 |
把 Translator URL 改成无效地址，再魔棒入库 |
Toast 失败信息可读；改回默认可恢复 |
☐ |
6.1.8 魔棒（Skill 导入）
| 编号 |
入口 |
操作 |
预期 |
状态 |
| 6.1.8.1 |
魔棒 |
粘贴 https://github.com/mattpocock/skills |
弹出候选选择窗口；确认后才下载/安装选中的 Skill |
☐ |
| 6.1.8.2 |
魔棒 |
粘贴 https://github.com/alchaincyf/nuwa-skill |
弹出候选选择窗口；不请求 Translator 论文元数据 |
☐ |
| 6.1.8.3 |
魔棒 |
粘贴 npx skills add https://github.com/anthropics/skills --skill pptx |
窗口只显示匹配的 pptx，确认后保留其附属目录 |
☐ |
| 6.1.8.4 |
Skill 选择窗口 |
点击取消或关闭 |
不写入 .agents/skills/，临时 discovery 被清理 |
☐ |
| 6.1.8.5 |
魔棒 |
重复导入同一 Skill |
选择窗口标记已安装；确认后跳过且不覆盖已有 SKILL.md |
☐ |
| 6.1.8.6 |
远程 Vault |
粘贴任一 Skill 来源 |
明确提示远程 Vault 暂不支持 Skill 导入 |
☐ |
6.2 本地 PDF
| # |
界面 |
操作 |
预期 |
结果 |
| 6.2.1 |
魔棒弹层 |
选「本地 PDF / 文件」，多选 2 个 PDF 导入 |
各生成 papers/<citekey>/，含 PDF + PAPER.md + catalog |
☐ |
| 6.2.2 |
访达 |
把外部 PDF 拖进左栏 papers/ 某组织夹 |
直接后台入库；识别和版面分析继续后台运行 |
☐ |
| 6.2.2.1 |
访达 |
把 1 个或多个 PDF 拖到中间栏 Library 表 |
出现虚线 overlay「松开以导入 PDF」；松手后直接后台入库，文件夹作用域导入到该夹 |
☐ |
| 6.2.2.2 |
中间栏·PDF 阅读器 / NOTES / 其它窗口区域 |
把一个 PDF 拖到当前阅读器，再连续拖入第二个 |
两个 PDF 都不丢失并按顺序导入；识别和版面分析继续在后台 |
☐ |
| 6.2.2.3 |
访达 |
把 PNG / .md 拖到 Library 表 |
无 overlay、不入库 |
☐ |
| 6.2.2.4 |
Linux · Files（Nautilus）+ GNOME / Wayland |
从 Files 把 PDF 分别拖到主窗口 Library、papers/ 组织夹、阅读器；再检查树内移动和 tab 重排 |
PDF 按对应目标目录各导入一次；Library 有 overlay；内部移动和 tab 拖拽正常 |
☐ |
| 6.2.3 |
同上 |
再导同名冲突 PDF |
citekey 带 -2 / -3 等后缀，不互相覆盖 |
☐ |
| 6.2.4 |
终端 + 应用 |
用安装包装的应用（非 tauri dev），先确认 PDFium 已随包：macOS ls "/Applications/Agentero.app/Contents/Frameworks/libpdfium.dylib"，Windows/Linux 查 exe 同级 pdfium/。再临时移走构建期缓存 ~/Library/Caches/pdfium-rs（Linux ~/.cache/pdfium-rs），导入一个本地 PDF |
仍生成 PAPER.md，catalog 写入 body_source；测完恢复缓存目录（回归 #303） |
☐ |
| 6.2.5 |
同上 |
把包内 PDFium 临时改名，再导入一个本地 PDF |
任务面板出现 失败 的「解析 PDF 正文」，详情含找不到 PDFium 的真实原因，而不是显示“已完成” |
☐ |
| 6.2.6 |
设置 → 版面解析 + 左栏·树 |
正文引擎选「Agentero 内置」，导入一篇无 TeX 的 PDF |
生成的 PAPER.md 是 OCR 质量正文（catalog body_source = vlm），不是静默退化成本地 liteparse 的纯文本；同时版面后端仍显示 local，PP-DocLayoutV3 仍从本地 cache 加载（内置 provider 只是正文引擎，不是版面后端） |
☐ |
6.3 补下载
| # |
界面 |
操作 |
预期 |
结果 |
| 6.3.1 |
左栏·树 |
找缺 PDF 的 paper 行，hover Download |
有原因说明 |
☐ |
| 6.3.2 |
左栏·树 |
点 Download |
任务条进度；PDF 落地；无 TeX 时生成 PAPER.md |
☐ |
6.4 Zotero Connector（可选）
前置：浏览器装官方 Zotero Connector；关掉 Zotero 桌面（端口 23119）。
| # |
界面 |
操作 |
预期 |
结果 |
| 6.4.1 |
设置 → 通用 |
打开「兼容 Zotero Connector」 |
状态为 Listening，且绑定当前 Vault |
☐ |
| 6.4.2 |
系统 |
同时开 Zotero 桌面再开开关 |
明确端口占用失败提示 |
☐ |
| 6.4.3 |
浏览器 |
打开论文页，点 Connector 保存 |
Agentero 入库；树/Library 刷新；打开或聚焦该 paper |
☐ |
| 6.4.4 |
浏览器 |
对登录墙 PDF 触发附件保存（若场景可得） |
附件进入论文目录 |
☐ |
| 6.4.5 |
设置 |
关闭开关后退出应用 |
端口释放；浏览器不再认为 Zotero 在线 |
☐ |
7. PDF / 图片 / Markdown
建议：demo vault 中的 paper PDF + assets/sample.pdf + assets/figures/*。
7.1 PDF 阅读
| # |
界面 |
操作 |
预期 |
结果 |
| 7.1.1 |
左栏·树 |
点 paper 下 PDF 或 assets/sample.pdf |
中间 blob 预览，非系统外部打开 |
☐ |
| 7.1.2 |
中间栏·PDF |
底栏改页码 / PageDown / Home |
跳页正确 |
☐ |
| 7.1.3 |
中间栏·PDF |
底部缩放滑动条、滚轮缩放 |
重渲染清晰；放大后可平移 |
☐ |
| 7.1.3a |
中间栏·PDF / NOTES 分屏 |
PDF 设为手动 125%，先慢速、再快速向左/向右来回拖动中间 divider，然后在一次快速拖动中直接松手 |
divider 与 PDF panel 边界按屏幕帧连续跟手，无输入堆积、PDF 蓝色文本选区或松手回跳；页面仅被即时裁剪/扩展，125% 保持，滚动区域与最终尺寸一致 |
☐ |
| 7.1.3b |
中间栏·PDF |
打开含 /Rotate 90 页面的 PDF（如 10_3389_fpls_2025_1611992 第 4、5 页） |
旋转页按横向页框显示；不被塞进竖向 A4 页框；翻译分屏同样正确 |
☐ |
| 7.1.3c |
中间栏·PDF / NOTES 分屏 |
打开一篇长笔记（数百个标题）与 PDF 分屏，向左/向右来回拖动中间 divider，然后在一次快速拖动中直接松手 |
divider 逐帧跟手无卡顿；拖动期间笔记布局冻结（拉宽留白 / 收窄被裁），松手后只重算一次并正好落在最终宽度上；pdf 选区、125% zoom 不受影响 |
☐ |
| 7.1.3d |
左栏·树 / 右栏 rail |
打开同一篇长笔记（并同时开着 PDF），来回拖动左侧文件树与右侧栏的 rail；再把窗口拉大 / 缩小 |
两种手势都不卡（原先完全没被门控覆盖，见 bug_fix §3.4）；松手后笔记与 PDF 都正常落到最终尺寸。注意：PDF 侧这条是接了同一手势信号，但收益未测量 |
☐ |
| 7.1.4 |
中间栏·PDF |
打开大纲，点书签 |
跳到对应位置 |
☐ |
| 7.1.5 |
中间栏·PDF |
⌘F 输入文中词 |
命中高亮；可下一条 |
☐ |
| 7.1.6 |
中间栏·论文 PDF |
点击原生 citation / 章节链接、URI 及纯文本 URL，悬停引用；开启 / 关闭全文译文后重试，并在译文上划选。若测试 PDF 包含无目标 Link，也点击检查 |
内链跳页、返回位置可用；外链只打开一次；引用预览正常；无八点选中框；译文划选和高亮编辑保留，未翻译区域的链接仍可点 |
☐ |
7.2 划词与批注
| # |
界面 |
操作 |
预期 |
结果 |
| 7.2.1 |
中间栏·PDF |
拖选一段文字 |
仅选中文字显示平滑蓝色选区 + 操作菜单（高亮 / 翻译 / 快速对话 ⌘K / 加入对话 ⌘L，无批注按钮；文字小号）+ 页右缘竖向评论入口；不出现整页 / 大块 PDF 蓝色矩形框选 |
☐ |
| 7.2.2 |
菜单 |
选 高亮 |
高亮保留；磁盘 marks/ 有记录；原始 PDF 字节不变 |
☐ |
| 7.2.3 |
页右缘 |
hover 竖向评论入口 → 移走（无输入）→ 再 hover 输入 |
hover 进入编辑；无输入移走缩回图标卡；再 hover 可输入；提交后高亮 + 常驻评论卡 |
☐ |
| 7.2.4 |
右栏·批注 |
点卡片跳转 / 编辑 / 删除 |
跳页正确；改删同步 |
☐ |
| 7.2.5 |
菜单 |
翻译 一段 |
按设置中翻译服务出结果 |
☐ |
| 7.2.6 |
菜单 |
提问（已配 Agent） |
选区旁迷你问答卡片；可发问出结果 |
☐ |
| 7.2.7 |
划词加入对话 |
划词 → 点 加入对话 或按 ⌘L / ⇧⌘A → 在 Agent 输入问题发送 |
Composer 输入框内有选区引用块且侧栏打开；发送后选区旁出现对话卡片页边针（kind: ask，非视觉批注）；悬停/点开可见本轮问答 |
☐ |
7.3 视觉批注与版面分析
| # |
界面 |
操作 |
预期 |
结果 |
| 7.3.1 |
中间栏·PDF |
按 ⌘. 框选某插图/表/算法区域，输入备注保存 |
marks/<id>.json 写入 kind: visual v2；页边针出现；可再次编辑备注 |
☐ |
| 7.3.2 |
中间栏·PDF |
框选区域后按 ⌘Enter 向 Agent 提问 |
视觉上下文进入 Agent 会话；回答后同一 mark 可续聊 |
☐ |
| 7.3.3 |
右栏·Figures |
打开带插图的 paper，点「分析」 |
列出 figure/table/algorithm/formula；点击跳转到对应位置 |
☐ |
| 7.3.4 |
中间栏·PDF |
悬停有编号公式命中框并单击 |
与插图一致：出现「单击进行批注」提示，单击打开视觉批注编辑器 |
☐ |
| 7.3.5 |
中间栏·PDF |
点工具栏 Languages 全文翻译 |
按阅读顺序分批出译文并盖在 bbox 上（非整页等齐）；再点可停止/清除；磁盘 source/layout-translate.json 有缓存 |
☐ |
| 7.3.5a |
中间栏·PDF（翻译服务=Agentero 内置） |
对一篇含公式 / URL / 引用标记的论文跑全文翻译，逐段对照原文 |
内置路径的 [[n]] 批次由 Host 拆分逐段请求再重组：译文不错位、不并段、不丢块；⟦n⟧ 占位符保护的公式 / URL / 引用在译文里原样还原，没有出现裸露的 ⟦0⟧ 或被吞掉后整段回落原文（这两点是尚未用真实 key 验证过的假设，见 ../backend/builtin-provider.md §限制与后续） |
☐ |
7.4 图片与 MD 插图
| # |
界面 |
操作 |
预期 |
结果 |
| 7.4.1 |
左栏·树 |
点 assets/figures 下 png/jpg 等 |
中间图片预览 |
☐ |
| 7.4.2 |
中间栏·MD |
打开笔记，粘贴一张图 |
磁盘 {mdDir}/assets/ 有文件；正文 ；树可见 |
☐ |
| 7.4.3 |
中间栏·MD |
单击选中图片节点 |
显示 Markdown 源码而非位图 |
☐ |
| 7.4.4 |
中间栏·MD |
删除该图片节点（且无其它引用） |
assets 文件被 GC；树刷新 |
☐ |
8. Markdown、双链
| # |
界面 |
操作 |
预期 |
结果 |
| 8.1 |
中间栏·MD |
编辑标题、列表、代码块、表格，等自动保存 |
磁盘一致；重启仍在 |
☐ |
| 8.1a |
中间栏·MD |
将鼠标停在含长行的 fenced code block 上，先上下滚轮，再横向滚动 |
上下滚轮继续滚动整篇文档；代码块可独立横向滚动 |
☐ |
| 8.2 |
设置 → Appearance |
开关 格式工具栏 |
编辑器顶栏显隐 |
☐ |
| 8.3 |
中间栏·MD |
写入 [[某已存在笔记]]，点击链接 |
跳转到目标文件 |
☐ |
| 8.4 |
中间栏·MD |
写入不存在的 [[新概念]]，走创建入口 |
可新建目标文件 |
☐ |
| 8.5 |
右栏 |
切到 Backlinks，打开被引用文件 |
上方列出反链来源 |
☐ |
| 8.6 |
右栏·References |
看卡片下方引用近邻图，点库内节点 |
打开对应论文；四级角色（本论文 / 引用 / 被引 / stub）可辨；stub 不可打开 |
☐ |
| 8.7 |
中间栏·MD |
新增/删除一条 [[链接]]，等约 1s |
状态栏反链刷新；引用图不随双链改动变化 |
☐ |
| 8.8 |
中间栏·NOTES |
对当前 paper 输入 [[@，↑↓ 选候选，tab/enter |
列出划词/视觉批注；↑ 在首项循环到末项且菜单不消失 |
☐ |
| 8.9 |
中间栏·NOTES |
面板复制批注链接并粘贴；再 ![[…@id]] |
跳转打开 PDF 到 mark；嵌入只读、可滚动，正文点击不跳转，右上角按钮跳转；视觉批注展示对话 Markdown |
☐ |
| 8.10 |
中间栏·NOTES |
嵌入位置文案 |
有大纲时为标题路径，否则「第 N 页」 |
☐ |
| 8.11 |
中间栏·NOTES |
打开含较多标题的长笔记（最好三面板同开：PDF + 笔记 + 对话），来回拖动竖直滚动条 thumb；再点 TOC 条目平滑跳转 |
thumb 逐帧跟手，无「一拖就卡」；TOC 高亮正常跟随；编辑标题 / 在标题上方插入块后高亮仍正确 |
☐ |
9. 命令面板与快捷键
| # |
界面 |
操作 |
预期 |
结果 |
| 9.1 |
任意（有 Vault） |
⌘P，输入论文标题片段 |
列表出论文；回车打开 paper |
☐ |
| 9.2 |
命令面板 |
输入笔记里有的正文关键词 |
全文命中可打开对应 md |
☐ |
| 9.3 |
任意 |
⇧⌘P 或输入 >，执行一条内置命令 |
命令生效 |
☐ |
| 9.4 |
命令面板打开时 |
再按 ⌘P 或 ⌘W |
面板关闭 |
☐ |
| 9.5 |
任意 |
⌘, |
设置浮层开关 |
☐ |
| 9.6 |
任意 |
⇧⌘I |
魔棒打开 |
☐ |
| 9.7 |
命令面板 |
⌘P，输入某论文的可见标签 |
论文列表按标签命中该 paper |
☐ |
| 9.8 |
命令面板 |
⌘P，输入某笔记/论文的 frontmatter alias |
「别名」分组命中，回车打开对应 paper / 笔记 |
☐ |
10. 设置、主题、语言
| # |
界面 |
操作 |
预期 |
结果 |
| 10.1 |
设置 |
改一项通用设置并保存，再开设置 |
值保持；多窗口应同步 |
☐ |
| 10.2 |
设置 → Appearance |
切换亮/暗 |
界面立刻变 |
☐ |
| 10.3 |
设置 → Appearance |
换一个 配色主题，再改回 default |
颜色变量变化；default 恢复内置 |
☐ |
| 10.4 |
设置 → Appearance |
改 界面缩放 80% / 150% |
全局字号缩放 |
☐ |
| 10.5 |
设置 → Appearance |
语言改 简体中文，再改 English |
菜单/设置/空状态等关键文案切换；无大片漏翻 |
☐ |
| 10.6 |
设置 → Agent |
确认 入库后自动精读 默认关 |
默认关闭 |
☐ |
| 10.7 |
设置 → Agent |
权限模式切 restricted / ask / auto |
选项保存成功（行为见 §11） |
☐ |
| 10.8 |
设置 → 翻译 |
切换 free / Agent 翻译 |
保存成功；PDF 划词翻译跟新设置 |
☐ |
| 10.8a |
设置（新装 / 删掉 settings.json 后重启） |
依次看翻译默认服务、Agent → Embedding 来源、版面解析 → 正文引擎 |
注入 key 的构建里三处默认都是「Agentero 内置」，且看不到任何 Base URL / API Key / Model 输入框；未注入 key 的构建里三处回落 tencenttransmart / 自定义 / local |
☐ |
| 10.8b |
设置 → 翻译 |
选「Agentero 内置」后在 PDF 划词翻译一段英文 |
出译文；失败时 Toast 是可读文案，不裸露 translate.no_builtin_key 标记 |
☐ |
| 10.8c |
设置 → Agent → Embedding |
已填过 Base URL / API Key / Model 的老配置升级后打开 |
来源被推断为「自定义接口」，三个输入框仍在且值未丢；没有被静默切到内置 |
☐ |
| 10.9 |
设置 → 通用 → 隐私 |
开关「本地使用记录」；再点清除 |
关闭后不再写入；清除后本地使用记录为空；与 PostHog 开关互不影响 |
☐ |
11. Agent（BYOA）
前置：本机已装并登录至少一个 ACP Agent。未安装时只测 11.0。
11.0 空状态
| # |
界面 |
操作 |
预期 |
结果 |
| 11.0.1 |
右栏·Agent |
未配置 Agent 时打开面板 |
有安装/配置指引；左栏库与 PDF 仍可用 |
☐ |
| 11.0.2 |
设置 → Agent |
本机未装 Claude/Codex/OpenCode 等预设 Agent 时，点「安装」/「安装 ACP」 |
静默执行官方 installer；安装成功后探测状态变绿 |
☐ |
| 11.0.3 |
设置 → Agent |
已装 Agent 有可用更新时，点「升级」 |
升级成功；版本号或探测状态更新 |
☐ |
11.1 对话
| # |
界面 |
操作 |
预期 |
结果 |
| 11.1.1 |
设置 → Agent |
添加预设或自定义 command，探测 |
探测成功；可选为默认 |
☐ |
| 11.1.2 |
左栏·树 |
打开一篇 paper，再打开右栏 Agent |
Composer 有当前论文 context chip（可 X 去掉） |
☐ |
| 11.1.3 |
右栏·Agent |
输入问题发送 |
流式输出；会话 cwd 为当前 Vault |
☐ |
| 11.1.4 |
右栏·Agent |
输出过程中按 Esc |
取消当前轮；已输出保留 |
☐ |
| 11.1.5 |
右栏·Agent |
Composer 输入 @，键盘选路径 |
出现可移除 path chip |
☐ |
| 11.1.6 |
左栏·树 |
拖一个文件到 Composer |
增加 path chip |
☐ |
| 11.1.7 |
右栏·Agent |
会话空闲时 hover 用户消息 → Edit → 改完重发 |
该消息之后内容丢弃，新 turn 发出 |
☐ |
| 11.1.8 |
右栏·Agent |
切换历史会话 / 加载旧会话 |
能 list 并恢复（provider 支持时） |
☐ |
| 11.1.9 |
右栏·Agent |
看回答中的 Sources（若 Agent 返回） |
展示读过的本地路径 |
☐ |
| 11.1.10 |
右栏·Agent（支持 Client terminal 的 Agent） |
依次执行 pwd、echo AGENTERO_SMOKE，再启动长命令，发送 wait_for_exit 并在等待期间读取 output、kill、release |
前两条及时返回；wait 挂起时同连接仍能处理 output / kill / release，卡片最终 completed / failed |
☐ |
| 11.1.11 |
右栏·Agent |
在工具卡 pending 时结束或取消回合，再依次接收迟到 progress、completion、progress |
回合结束后不保留永久 spinner；内容与终态按同一 toolCallId 修正原卡片，迟到 progress 不恢复 spinner，也不新增重复卡片 |
☐ |
| 11.1.12 |
Windows · 设置 → Agent |
原生 .exe 探针模拟 initialize 阻塞，等待 30 秒超时并重复探测；查看父子进程 |
探针没有新增外层 CMD；超时后目标 .exe 被回收。Pi / Custom / npm shim / Dsh 自带 launcher 的后代清理单独记录，见 cwd 边界 |
☐ |
| 11.1.13 |
Windows · Dsh |
在含空格的用户路径与 Vault 下探测、发送一轮消息 |
仅使用 Dsh 自带 launcher，不新增双层 CMD；launcher 配置与认证可读取 |
☐ |
| 11.1.14 |
macOS · Finder 启动 |
打开本地 Vault，用 Codex 精读论文；无 Vault 时执行探针 |
会话进程 cwd 为 Vault，探针为 scratch；不因继承 / 触发 Music / Desktop / Downloads 等无关 TCC 弹窗 |
☐ |
11.2 权限
| # |
界面 |
操作 |
预期 |
结果 |
| 11.2.1 |
设置 → Agent |
权限 = 每次询问；让 Agent 做需授权操作 |
弹出 Allow once / Always / Reject；拒绝则不执行 |
☐ |
| 11.2.2 |
设置 → Agent |
权限 = 自动批准；再跑同类操作 |
不弹窗，直接继续 |
☐ |
| 11.2.3 |
设置 → Agent |
权限 = 受限 |
危险操作被限制（符合产品文案） |
☐ |
11.3 工作流与精读
| # |
界面 |
操作 |
预期 |
结果 |
| 11.3.1 |
右栏·Agent（空态） |
点 Summarize / Ask library / Draft Related Work |
对当前聚焦 paper 发起对应 workflow |
☐ |
| 11.3.2 |
左栏·树 |
找资源齐全且未读 paper，点 精读图标 |
任务条 paper-reader 进度；写/更新 NOTES.md；is_read 变已读；图标消失 |
☐ |
| 11.3.3 |
设置 → Agent |
打开 入库后自动精读；魔棒再入一篇未读 |
入库/下载完成后自动精读；任务条可见 |
☐ |
| 11.3.4 |
魔棒 |
批量多 ID 入库（自动精读开着） |
不对批量每篇连跑精读 |
☐ |
| 11.3.5 |
右栏·Agent 历史 |
精读跑完后翻主对话列表 |
精读不出现在主 chat 历史 |
☐ |
12. 远程 Vault（macOS / Linux）
本轮不测远程则整节 N/A。Windows 只测 12.9。
| # |
界面 |
操作 |
预期 |
结果 |
| 12.1 |
欢迎页 |
点 Open remote…，填 host / user / 远端绝对路径，连接 |
成功则进工作台；树显示远端内容 |
☐ |
| 12.2 |
欢迎页 |
故意填错密码或路径 |
可读错误；不白屏 |
☐ |
| 12.3 |
中间栏·MD |
改远端 NOTES 并保存 |
远端磁盘更新（本机不是第二权威库） |
☐ |
| 12.4 |
中间栏·PDF |
打开远端 paper PDF |
可预览（经缓存） |
☐ |
| 12.5 |
魔棒 |
入库一篇到远程库 |
文件与 catalog 在远端 |
☐ |
| 12.6 |
欢迎页 Recent |
看远程条目 |
显示 host:path + 远程徽章；不是 remote:uuid 伪路径刷屏 |
☐ |
| 12.7 |
系统 |
退出再启动，点远程 Recent |
需重新 SSH，不能当本地路径直接打开 |
☐ |
| 12.8 |
设置 → Agent（远程会话） |
远端探测 Agent，发对话 |
Agent 在服务器跑，cwd 为远端 Vault |
☐ |
| 12.9 |
Windows 客户端 |
尝试 Open remote |
明确不支持错误，不崩溃 |
☐ |
| 12.10 |
远程会话 |
右键 Finder / 终端打开 |
禁用或明确不可用 |
☐ |
13. CLI（终端）
# 使用本机构建或 Release 二进制
agentero vault create /tmp/agentero-cli-vault
agentero --vault /tmp/agentero-cli-vault paper list --json
| # |
界面 |
操作 |
预期 |
结果 |
| 13.1 |
终端 |
agentero --version |
版本与发布一致 |
☐ |
| 13.2 |
终端 |
vault create <空目录> |
脚手架与 GUI Create 一致（含 catalog） |
☐ |
| 13.3 |
终端 |
vault list --json |
JSON 可解析；退出码 0 |
☐ |
| 13.4 |
终端 |
tree；paper list --json |
与 catalog 一致 |
☐ |
| 13.5 |
终端 |
paper tag add …；list --tag |
标签生效 |
☐ |
| 13.6 |
终端 |
import id 1706.03762（需网） |
入库成功或稳定 error.code |
☐ |
| 13.7 |
终端 |
export bib |
输出 BibTeX |
☐ |
| 13.8 |
终端 |
agentero --help |
无 agent run / paper-reader 类 BYOA 命令 |
☐ |
14. 错误与稳定性抽检
| # |
界面 |
操作 |
预期 |
结果 |
| 14.1 |
欢迎页 |
无 Vault 时强行触发需库操作（若可达） |
Toast 提示，不崩 |
☐ |
| 14.2 |
任意失败操作 |
例如删只读路径、断网下 DOI 入库 |
右上角 Toast；侧栏 header 无常驻错误条 |
☐ |
| 14.3 |
中间栏 |
连续打开 ≥5 个 panel 来回切 |
不卡死、不丢文件 |
☐ |
| 14.4 |
中间栏·PDF |
打开较大 PDF（>20MB）翻页缩放 |
可接受流畅度 |
☐ |
| 14.5 |
系统 |
断网后打开本地库，读 PDF、写 NOTES |
本地能力可用；仅网络路径失败有 Toast |
☐ |
15. 平台矩阵（勾选本轮范围）
对每个目标平台：至少跑 §0.3 + §1；核心平台再跑 §3–§7、§11。
| 能力 |
macOS |
Linux |
Windows |
| 安装启动 §0.3 |
☐ |
☐ |
☐ |
| Windows NSIS 安装器品牌图 |
N/A |
N/A |
☐ |
| 五分钟冒烟 §1 |
☐ |
☐ |
☐ |
| 文件树 + 回收站 §3 |
☐ |
☐ |
☐ |
| PDF + 划词 §7 |
☐ |
☐ |
☐ |
| Agent §11 |
☐ |
☐ |
☐ |
| Connector §6.4 |
☐ |
☐ |
☐ |
| 远程 §12 |
☐ |
☐ |
12.9 拒绝 ☐ |
| CLI §13 |
☐ |
☐ |
☐ |
| 外壳右键集成 §0.3.5/0.3.6 |
☐ |
N/A |
☐ |
16. 明确不测（写进 Release notes）
验收时不要当成缺陷：
| 项 |
说明 |
| 引用图 / Connected Papers |
路线图 0.6 未交付 |
| 魔棒关键词/自然语言候选 |
未交付 |
| 打开杂乱文件夹自动整理 |
Vault 采纳未交付 |
| 与 Zotero 桌面同时占 23119 |
端口互斥 |
| Windows 远程 Vault |
不支持 |
| 应用内填 Agent 的模型 API Key |
BYOA，不收集；Agent 的 Key 由 Agent CLI 自己持有。（翻译 / 版面 / embedding 的 BYOK Key 与构建期内置 provider 凭证是另外两条路径，见 release.md §内置 Provider 构建期注入） |
| 删除时确认框 / Undo toast |
产品设计为无确认进回收站 |
17. 签字
| 角色 |
结论（通过 / 有条件通过 / 不通过） |
日期 |
| 功能验收 |
|
|
| 安装包 |
|
|
| 最终放行 |
|
|
有条件通过须列出：⚠️ 项、issue 链接、是否写进对外说明。
附录：推荐路径顺序（约 90 分钟完整桌面）
- §0 安装 + §1 冒烟（空库）
- Open demo vault → §3 树 / 回收站 → §4 分屏 → §5 Library
- §6 魔棒 + 本地 PDF → §7 PDF 划词 → §8 双链
- §9–§10 面板与设置 → §11 Agent
- 按范围 §12 / §13 / §6.4
- §14 稳定性 → §15 矩阵勾选 → §17 签字
相关：../usage/index.md