Readest 多端仓库验证清单（Verification Done-Conditions）完全指南

桌面应用跨平台前端【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址https://gitcode.com/gh_mirrors/re/readest点击查看免费下载本文面向在 Readest 开源仓库中提交代码的开发者与 AI AgentReadest 是一个横跨Next.js/React Web 前端、Tauri/Rust 桌面后端、KOReader Lua 插件koplugin以及独立 Rust 工具 cratelocalsend-bin的多技术栈 monorepo。在标记任何工作为“完成”之前apps/readest-app/.claude/rules/verification.md定义了一份按变更范围条件化执行的验证清单——读完本文你将掌握 Web 单元测试、TypeScript/Biome 静态检查、LuaJIT 语法校验与 busted 单测、Rust fmt/clippy/test 的完整命令矩阵、其背后的脚本实现、适用的环境前提以及它们在 CI 流水线 中的对应关系。一、为什么需要一份“验证清单”Readest 仓库package.json 中名为readest/monorepo并非单一语言项目而是至少包含四类差异极大的技术栈技术栈位置工具链Web / Next.js 前端apps/readest-app/srcpnpm、vitest、TypeScript、BiomeTauri / Rust 桌面后端apps/readest-app/src-tauriCargo、rustfmt、clippyKOReader Lua 插件apps/readest.kopluginLuaJIT、busted独立 Rust 工具 crateapps/readest.koplugin/native/localsend-binCargo独立于 src-tauri 工作区一份“一刀切”的全量验证既不现实也不高效纯前端改动跑完整 Rust 编译、纯 Lua 改动触发 tsc 全量检查都会浪费大量时间。因此verification.md的核心设计思想是按变更范围条件化执行all applicable checks must pass——只有“适用applicable”的检查必须通过且每种检查都标注了触发条件。这份清单同时是人工提交与 CI 双轨执行的“完成标准done-conditions”本地提交前按清单逐项核对pull-request.yml 中的rust_lint、koplugin_rust_lint、test_extensions、test_web_app、build_web_app等 job 则用dorny/paths-filter做同样的路径过滤实现 CI 与本地验证行为一致。二、验证清单总览以下为 verification.md 定义的完整 7 项检查#命令覆盖内容触发条件1pnpm test单元测试vitest始终2pnpm lintBiome tsc仅 Web始终3pnpm lint:luapnpm test:luakoplugin LuaJIT 语法检查 busted 单元测试spec 目录仅 koplugin Lua 文件变更未安装 luajit/busted 时软跳过4pnpm fmt:checkRust 格式检查仅src-tauri/变更5pnpm clippy:checkRust lint仅src-tauri/变更6pnpm test:rustRust 单元测试cargo test -p Readest --lib仅src-tauri/变更CI 的rust_lintjob 中同样运行7cargo fmt --checkcargo clippy --all-targets -- -D warningscargo testkoplugin 独立 LocalSend helper 二进制 crate仅apps/readest.koplugin/native/变更CI 的koplugin_rust_lintjob 中同样运行三、Web 层验证单元测试与静态检查第 1、2 项3.1pnpm test—— vitest 单元测试在仓库根目录执行pnpm test实际通过 pnpm workspace filter 转发到 app 包// package.json根 test: pnpm --filter readest/readest-app test, lint: pnpm --filter readest/readest-app lint, lint:lua: pnpm --filter readest/readest-app lint:lua, test:lua: pnpm --filter readest/readest-app test:lua, fmt:check: pnpm --filter readest/readest-app fmt:check, clippy:check: pnpm --filter readest/readest-app clippy:check真正的 vitest 启动命令在 apps/readest-app/package.json 中test: dotenv -e .env -e .env.test.local -- vitestdotenv-cli负责注入测试环境变量.env与.env.test.local随后调用 vitest。测试运行时的关键配置位于 vitest.config.mtsenvironment: jsdom在 jsdom 中运行适配 React 组件与 DOM 相关测试setupFiles: [./vitest.setup.ts]统一测试初始化通过exclude与主单元套件划清边界Playwright Web E2Ee2e/**、*.browser.test.ts(x)、Tauri/WebDriver 测试*.tauri.test.ts、Android 设备 E2E*.android.test.ts都不属于本命令范围分别由test:e2e:web、test:tauri、test:android负责。测试源码分布在 src/tests下约数百个用例含foliate-*.test.ts系列格式解析测试、paragraph-mode.test.tsx 等组件测试并用fast-check属性测试覆盖部分复杂逻辑。CI 中该套件被拆成两个并行分片vitest --shard1/2与--shard2/2以缩短耗时。3.2pnpm lint—— Biome tsclint: tsc --noEmit biome lint .这条命令串联两道检查是 Web 侧的唯一静态校验入口tsc --noEmit严格 TypeScript 类型检查。仓库的 TypeScript 规则 要求禁用any用unknown、精确类型或泛型、开启 strict 模式、目标 ES2022并以_前缀允许未使用变量。biome lint .Biome 的 lint 规则基于根目录 biome.json 配置。注意验证清单中注明该命令web only——它不覆盖 Lua 与 Rust 代码这两部分有各自的专用命令。CI 的build_web_appjob 还额外执行pnpm format:checkBiome 格式检查本地可运行根脚本pnpm format:check提前自检。四、KOReader 插件koplugin的 Lua 验证第 3 项koplugin 是 Readest 的 KOReader 端实现位于 apps/readest.koplugin由大量.lua源文件构成如 readest_syncclient.lua、library 子目录 等。它需要两条命令配合lint:lua: node ../readest.koplugin/scripts/lint-koplugin.mjs, test:lua: node ../readest.koplugin/scripts/test-koplugin.mjslint:lua通过 lint-koplugin.mjs 对全部 Lua 源码做LuaJIT 语法检查并非静态分析而是确保语法可被 LuaJIT 解析test:lua通过 test-koplugin.mjs 运行busted 单元测试测试代码位于 spec 目录包括syncauth_spec.lua、syncannotations_spec.lua、main_open_spec.lua、library/下的 LibraryStore 测试等。该检查的两个重要特性仅当 koplugin Lua 文件变更时执行改动 Web 或 Rust 代码时无需关心 Lua 语法软跳过soft-skip当本机未安装luajit/busted时这两条命令允许跳过不会阻塞工作收尾。CI 中则不同——test_extensions job 检测到 koplugin 变更后会安装luajit luarocks libsqlite3-dev并通过luarocks --lua-version5.1 install busted lsqlite3complete固定 Lua 5.1/LuaJIT 兼容版本补全环境后强制运行。五、src-tauri Rust 后端的三角验证第 4、5、6 项当改动触及apps/readest-app/src-tauri/时需要依次通过格式、lint、单测三道关卡fmt:check: cargo fmt -p Readest --check, clippy:check: cargo clippy -p Readest --no-deps -- -D warnings, test:rust: cargo test -p Readest --libfmt:checkcargo fmt -p Readest --check仅检查不自动格式化包名Readest来自 src-tauri/Cargo.toml 的[package] name Readestclippy:checkcargo clippy -p Readest --no-deps -- -D warnings只 lint 本项目 crate 而不检查依赖--no-deps并把所有 warning 升级为 error-D warningstest:rustcargo test -p Readest --lib运行readestlib库的单元测试该 crate 同时产出staticlib/cdylib/lib三种库形态。CI 对照rust_lintjobpull-request.yml 中的rust_lintjob 与此完全同构先用dorny/paths-filter检测apps/readest-app/src-tauri/**是否变更若变更则安装 stable 工具链含rustfmt, clippy、安装 WebKitGTK 等系统依赖然后依次执行cargo fmt --check、cargo clippy -p Readest --no-deps -- -D warnings、cargo test -p Readest --lib。未变更时该 job 仍然运行但跳过全部步骤并报告成功作为 required check 保持绿色。六、localsend-bin 独立 crate 的验证第 7 项第 7 项容易被忽略但它是验证清单中非常特殊的一条cargo fmt --checkcargo clippy --all-targets -- -D warningscargo testinapps/readest.koplugin/native/localsend-binlocalsend-bin 是 koplugin 内置的LocalSend 独立辅助二进制crate。它的特殊性在于不属于 src-tauri 的 Cargo workspace虽然都是 Rust但src-tauri/的fmt/clippy/test命令-p Readest对它完全不生效必须在该目录内单独执行clippy 参数不同这里使用--all-targets覆盖 bin/lib/tests 全部 target而 src-tauri 使用--no-deps测试更完整直接cargo test默认 workspace/包级全部测试。CI 中对应koplugin_rust_lintjob同样以apps/readest.koplugin/native/**为过滤条件安装工具链后在localsend-bin目录依次执行上述三条命令。七、条件化执行一套清单如何服务四类改动综合全清单可以归纳出按改动类型的验证矩阵改动类型必须通过的检查仅 Web / TS / React1pnpm test 2pnpm lintkoplugin Lua1 2 3lint:lua、test:luasrc-tauri Rust1 2 4 5 6localsend-bin Rust1 2 7跨栈混合改动上述所有适用项在 verification.md 的语境中“all applicable checks must pass”意味着至少第 1、2 项永远执行其余按变更路径叠加。这与仓库的 Test-First 规则先写失败测试 → 复现 → 修复 → 全量pnpm test回归形成完整闭环测试先行保证正确性验证清单保证收尾质量。八、本地执行环境与前提由于验证命令直接调用各工具链本地运行前需确保环境满足Node.js 24 pnpm根 package.json 声明packageManager: pnpm11.1.1CI 的build_web_app/test_web_appjob 均使用node-version: 24Rust stable 工具链需包含rustfmt与clippy组件rustup component add rustfmt clippysrc-tauri/Cargo.toml 声明rust-version 1.90并依赖 WebKitGTK 等系统库LuaJIT busted可选仅当需要真正执行第 3 项时安装未安装时该检查软跳过。典型工作流在仓库根目录pnpm install # 安装 workspace 依赖 pnpm test # Web 单元测试始终 pnpm lint # tsc Biome始终 # 若改动了 src-tauri/ pnpm fmt:check pnpm clippy:check pnpm test:rust # 若改动了 apps/readest.koplugin/ pnpm lint:lua pnpm test:lua # 若改动了 apps/readest.koplugin/native/ cd apps/readest.koplugin/native/localsend-bin 2/dev/null; \ cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test结语verification.md 本质上是 Readest 多端仓库的质量收尾契约它用 7 条命令把 vitest、tsc、Biome、LuaJIT/busted、cargo fmt/clippy/test 组织成一张按变更路径触发的检查矩阵并与 pull-request.yml 的rust_lint、koplugin_rust_lint、test_extensions等 job 一一对应。对开发者而言理解“何时必须跑哪条命令”比记住全部命令更重要——这份清单给出的答案正是永远跑pnpm test与pnpm lint再按你改动的技术栈叠加对应检查即可在本地复现 CI 的全部完成条件。赞分享桌面应用跨平台前端【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址https://gitcode.com/gh_mirrors/re/readest点击查看免费下载相关推荐Tokei如何数出Markdown和HTML里的代码多语言嵌入统计机制实战拆解Tokei如何数出Markdown和HTML里的代码多语言嵌入统计机制实战拆解 Tokei 是一款用 Rust 编写的高效代码统计工具它能在目录中快速数出每CLI开发工具Firefox iOS 仓库的 Xcode 版本升级指南完整清单、文件改动与验证实践Firefox iOS 仓库的 Xcode 版本升级指南完整清单、文件改动与验证实践 导读 本文档原文见 docs/xcode update.md http移动开发前端Java Swing界面美化神器BeautyEye支持Windows与跨平台的双版本对比Java Swing界面美化神器BeautyEye支持Windows与跨平台的双版本对比 BeautyEye是一款强大的Java Swing跨平台外观组件库上一篇FabTools 开源项目教程下一篇Sioyek PDF 阅读器实用指南学术论文里不用来回翻找的 5 个方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考