常用小工具,一开即用。
RCtools 是一个在浏览器中处理数据的工具集合,提供代码格式化、正则测试、时间计算、文本处理、密码生成、摘要校验、数值转换和益智游戏等 17 个工具。可以直接访问在线站点,也可以在本地运行或部署为静态网站。
工具计算在浏览器本地完成,输入、文件、密码和诊断记录不会由工具上传。
在线使用 · 源码仓库 · 架构说明 · 添加工具 · 文件指南
功能一览 · 快速开始 · 数据与计算 · 开发命令 · 项目结构 · 添加工具 · 部署 · 常见问题
- 快速找到工具:按名称、简介或关键词搜索,支持分类筛选和最近使用;首页按
/可聚焦搜索框。 - 独立访问与返回:每个工具拥有独立地址,支持直接打开和刷新,返回目录时保留原来的筛选条件。
- 计算可控:较重的处理交给 Web Worker,支持取消、超时和旧结果隔离;轻量工具直接计算。
- 会话内恢复输入:工具切换时恢复普通输入和选项,密码和所选文件按各自策略释放。
- 配置发现工具:新增工具放入自己的目录,通过 JSON 描述配置生成目录、视图入口和 Worker 工厂。
- 静态发布:构建生成首页与工具入口页面,发布
dist/client/即可部署。
- Node.js 22.22.0 或以上,以及 npm。
- 现代浏览器,支持 Web Worker 和 Web Crypto;复制按钮使用 Clipboard API。
- 本地浏览器测试默认使用已安装的 Chrome,CI 使用 Playwright Chromium。
源码维护在 dev 分支:
git clone --branch dev https://github.com/RainCither/RCtools.git
cd RCtools
npm ci --include=dev
npm run dev默认开发地址为 http://127.0.0.1:5173,实际端口以终端输出为准。已有项目目录时,从安装依赖开始即可。
启动前会自动校验配置并生成工具入口。开发服务器监听工具配置和约定入口的变化;非法配置会显示错误,并保留上一份合法生成文件。
npm run build
npm run preview默认预览地址为 http://127.0.0.1:4173。build 包含类型、代码规范、格式、架构、单元测试和静态产物检查;preview 服务于生成的 dist/client/。
| 数据 | 保留方式 |
|---|---|
| 普通输入与选项 | 保存在页面会话内存中,工具切换时恢复,刷新后清除。 |
| 密码规则与生成结果 | 当前密码工具实例使用,离开后不恢复。 |
| 所选文件 | 当前工具实例持有,离开或清空时释放,不进入草稿。 |
| 计算结果、错误和运行任务 | 由控制器管理,不作为输入草稿保存。 |
| 最近使用 | 浏览器本地存储,最多 3 个有效工具;存储受限时使用内存列表。 |
| 持久化内容(如游戏存档) | 独立浏览器本地存档,刷新或重新访问后恢复;存储受限时降级到页面内存并提示。 |
| 诊断记录 | 仅保留当前页面内存中的最近 500 条事件,错误界面可主动复制。 |
普通草稿的总预算为 16 MiB。保存时按使用顺序淘汰旧草稿;单份输入超额时,界面会提前提示离开后无法保留。
2048 提供移动、合并、胜利、结束及重新开始的短音效。棋盘下方可开关声音,选择随棋局保存在本地;刷新恢复时保持安静,操作后才播放。
诊断只记录任务、状态、耗时和错误编码等白名单字段,不包含输入输出、密码、文件名、异常堆栈或完整查询参数。
- 正则计算超时 2 秒,最多展示 500 条匹配。
- 其他后台任务默认超时 30 秒。
- MD5/SHA 文件输入上限为 20 MiB。
- 故障文字最多处理 2,000 个字素,并限制附加组合符和输出规模。
- 文本统计、进制和浮点转换使用 150 ms 防抖;正则使用 200 ms 防抖。
输入变化、取消或离开工具会使旧任务失效,迟到响应不会覆盖当前输入的结果。取消与超时会终止后台线程,并中止尚未完成的文件读取。
| 命令 | 用途 |
|---|---|
npm run dev |
生成工具入口并启动开发服务器。 |
npm run generate |
校验 JSON,生成目录、工具 ID 类型、视图加载器和 Worker 工厂。 |
npm run typecheck |
生成目录与路由类型,执行严格 TypeScript 检查。 |
npm run lint |
执行 ESLint 代码规范检查。 |
npm run format:check |
检查源码、配置、文档与工作流的格式。 |
npm run check:architecture |
检查分层依赖、跨工具引用和循环依赖。 |
npm test |
执行类型检查、架构检查和单元测试。 |
npm run check |
执行类型、规范、架构、格式和单元测试检查。 |
npm run build |
执行完整检查,构建并预渲染,整理和验收静态产物。 |
npm run pages:build |
与 build 相同,供 Pages 工作流使用。 |
npm run preview |
启动静态产物的本地预览服务器。 |
npm run test:e2e |
验证桌面和手机视图中的真实浏览器交互。 |
构建还会检查首页初始脚本及其静态依赖的 Gzip 总量不超过 100 KiB;工具专属解析器、压缩器和 WASM 按需加载。
本地安装 Chrome 后执行:
npm run build
npm run test:e2eCI 会先使用 npx playwright install --with-deps chromium 安装浏览器,再运行测试。浏览器用例覆盖直接访问与刷新、搜索分类、导航、草稿、后台任务、文件摘要、错误恢复及键盘操作。
截图、失败追踪和测试结果默认写入系统临时目录的 rctools-quality。QA_ARTIFACTS_DIR 可指定输出位置,QA_BASE_URL 可指定浏览器测试访问的地址。
RCtools/
├─ src/
│ ├─ app/ # 应用入口、页面路由、工具宿主与异常恢复
│ ├─ catalog/ # 分类和外链配置、目录查询
│ ├─ contracts/ # 类型、能力接口、结果、控制器及 Worker 协议
│ ├─ adapters/ # 存储、剪贴板、随机数、文件、模块和任务实现
│ ├─ bindings/react/ # React 服务注入、状态订阅与生命周期绑定
│ ├─ ui/ # 公共组件、页面外壳和 CSS Modules
│ ├─ tools/<id>/ # 各工具的配置、核心算法、控制器和界面
│ └─ generated/ # 配置派生的目录、视图加载器与 Worker 工厂
├─ public/ # 站点图标等静态资源
├─ build/ # 配置生成、架构检查与 Pages 产物整理
├─ quality/
│ ├─ unit/ # 核心算法、目录、任务生命周期和产物测试
│ └─ browser/ # 桌面与手机浏览器测试
├─ .github/workflows/ # 自动验证和 GitHub Pages 部署
├─ README.md # 项目介绍与运行入口
├─ ARCHITECTURE.md # 架构、状态、错误、日志和发布约束
├─ ADDTOOL.md # 新工具模板与接入步骤
├─ FILE_GUIDE.md # 逐文件说明、阅读顺序和配置字段介绍
└─ dist/client/ # 静态网站发布产物
| 技术 | 用途 |
|---|---|
| React 19、React Router 8 | 组件界面、路由导航和构建时预渲染。 |
| TypeScript、Valibot | 严格类型约束与工具配置校验。 |
| Vite 8、CSS Modules | 开发服务、按需分块构建与局部样式。 |
| Web Worker、Web Crypto | 后台计算与密码所需的安全随机源。 |
| Prettier、CSSO、Terser、parse5 | 代码格式化、压缩与 HTML 解析。 |
| hash-wasm | MD5 和 SHA 算法的字节摘要计算。 |
| Vitest、Playwright | 行为回归与真实浏览器验证。 |
工具以自己的目录为单位接入:
src/tools/example/
├─ tool.json # 名称、分类、搜索词、排序和草稿策略
├─ core.ts # 输入解析与算法
├─ controller.ts # 输入、动作、结果与任务生命周期
├─ view.tsx # 默认导出的 React 工具视图
├─ worker.ts # 后台计算入口,重计算时使用
└─ styles.module.css # 工具专用样式,按需添加
- 创建
src/tools/<id>/,让tool.json的id与目录名一致,并关联已有分类。 - 编写核心算法、控制器和视图,计算量较大时增加
worker.ts。 - 在
quality/unit/或quality/browser/补充对应行为与边界验证。 - 运行
npm run generate和npm run build;界面交互变化时运行浏览器测试。
生成器扫描元数据与约定入口,统一派生目录、视图加载器、Worker 工厂和预渲染路径。src/generated/ 由生成流程维护,无需手工登记每个工具。
分类编辑 src/catalog/categories.json,外链编辑 src/catalog/links.json。完整字段说明、实现模板和接入约束见 添加工具指南 与 文件指南。
执行 npm run build 后,将 整个 dist/client/ 发布到静态托管服务。首页和全部工具页的标题、简介、导航或加载占位在构建时生成,工具交互在浏览器中加载。
构建所需的 dist/server/ 是框架预渲染辅助产物,发布目录为 dist/client/。源码、依赖和生成缓存分别由项目及包管理器维护。
项目已提供 .github/workflows/deploy-pages.yml:
| 触发方式 | 构建与浏览器验证 | 部署 |
|---|---|---|
推送到 dev |
执行 | 验证成功后部署 |
面向 dev 的 Pull Request |
执行 | 不部署 |
| 手动运行工作流 | 执行 | 验证成功后部署 |
首次启用时,在仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。发布源配置可参考 GitHub 官方说明。
工作流安装依赖、构建、运行浏览器验证,再上传 dist/client/ 并交给 Pages 部署。手动运行时选择 dev 源码分支。发布采用 Actions 产物,旧 main 产物分支可保留。
| 环境变量 | 默认值 | 用途 |
|---|---|---|
PAGES_BASE_PATH |
/ |
网站访问基础路径,可设为 /RCtools,子路径配置不带末尾斜杠。 |
PAGES_CUSTOM_DOMAIN |
tool.raincither.top |
生成 CNAME 的域名,设为空字符串时不生成该文件。 |
例如,以 /RCtools/ 子路径构建且不使用自定义域名,在 PowerShell 中执行:
$env:PAGES_BASE_PATH = "/RCtools"
$env:PAGES_CUSTOM_DOMAIN = ""
npm run build这些变量在构建时生效,同时控制资源地址、路由和预渲染输出。CI 的值配置在工作流 Build static site 步骤中;变更部署地址时同步调整该处。使用自定义域名还需配置仓库 Pages 的域名设置。
每次发布生成 404.html、.nojekyll、tool-routes.json 和 build-info.json。其中构建信息记录版本、源码提交与依赖锁文件摘要,便于定位部署和按稳定源码版本重建回滚。
新增工具后没有出现在首页?
检查目录名与 ID、分类及 view.tsx 大小写和默认导出,然后执行 npm run generate。配置无效时生成器保留上一份合法结果,错误会出现在开发界面或命令输出中。
为什么切换工具后有输入,刷新后输入却消失?
普通草稿保存在页面会话内存中,导航时恢复、刷新时清除。最近使用采用浏览器本地存储,因此保留方式不同。
部署后资源丢失或直接访问工具显示 404?
确认发布的是完整 dist/client/,并且 PAGES_BASE_PATH 与实际站点路径一致。GitHub Pages 通过 Actions 部署,已知工具页拥有独立静态入口,未知地址的 404 页面会引导返回首页。
复制或后台计算失败如何处理?
界面会显示中文错误和可用的恢复操作。可以重试或刷新页面;后台计算超时时缩短输入或简化表达式。错误界面的“复制诊断信息”可用于排查。
| 文档 | 适合查看的内容 |
|---|---|
| 架构与约束 | 模块依赖、状态归属、任务生命周期、错误、日志和发布要求。 |
| 添加工具指南 | 元数据、算法、控制器、Worker 和 React 视图模板。 |
项目文本使用 UTF-8、LF 和两空格缩进;源码包含中文文件职责、主要函数和关键流程注释。依赖、生成代码、构建产物、缓存和测试报告由 .gitignore 管理。