eSearch 开发指南:基于 Electron + electron-vite 的跨平台识屏工具源码结构解析 eSearch 开发指南基于 Electron electron-vite 的跨平台识屏工具源码结构解析【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch导读本文是 eSearch 开源项目仓库根目录 AGENTS.md的完整开发指南面向希望理解或参与该项目开发的工程师与研究者。eSearch 是一个基于 Electron 的跨平台桌面应用覆盖截屏、离线 OCR、搜索、翻译、贴图、屏幕翻译、以图搜图、滚动截屏、录屏等能力。读完本文你将掌握 eSearch 的技术栈与常用命令、多页面渲染进程的目录结构、基于dkh-ui的界面开发方式、类型安全的进程间通信IPC机制、设置项的新增流程以及一套完整的国际化翻译工作流。一、项目概述与技术栈1.1 项目定位根据 AGENTS.md 的描述eSearch 是一个基于 Electron 的跨平台桌面应用功能涵盖截屏截图、OCR文字识别、搜索、翻译、贴图、屏幕翻译、以图搜图、滚动截屏、录屏。从 package.json 可见其作者自述为「识屏 · 搜索」当前仓库版本为 15.5.1许可证为 GPL-3.0包管理器固定为pnpm10.17.0。1.2 技术栈清单AGENTS.md 明确列出的技术栈为框架Electron electron-vite主进程打包由 electron-vite 驱动参见 electron.vite.config.ts语言TypeScript含src/ShareTypes.d.ts这类全局共享类型声明包管理器pnpm仓库同时提供pnpm-workspace.yaml与pnpm-lock.yaml代码规范Biome同时承担 lint 与 format测试Vitest仓库中存在src/renderer/lib/isDeepStrictEqual.test.ts与src/renderer/screenShot/test/waylandShot.test.ts等测试文件从 package.json 的 dependencies 可以看到支撑各功能的核心依赖这些与 AGENTS.md 描述的功能一一对应功能领域关键依赖说明截屏node-screenshots、xushengfeng/...平台原生依赖提供跨平台截屏能力optionalDependencies 中为 win/darwin/linux 各架构准备了预编译产物OCResearch-ocr、onnxruntime-node、esearch-seg离线 OCR 推理与图像分割翻译xtranslator多种翻译引擎接入录屏/视频mediabunny、gifenc视频处理与 GIF 编码界面dkh-ui、fabric、erase2d/fabricUI 组件库与画布编辑图片/视频编辑器其他hotkeys-js快捷键、uiohook-napi全局鼠标键盘钩子、qr-scanner-wechat二维码、picture_match以图搜图支撑快捷键、屏幕翻译取词等二、常用命令与构建流程AGENTS.md 给出了最核心的五条命令。结合 package.json 中的 scripts可整理出完整的命令矩阵# 安装依赖使用 pnpm pnpm install # 开发模式electron-vite dev带 HMR pnpm run dev # 构建electron-vite build产物输出到 out/ pnpm run build # 预览构建产物 pnpm run start # 打包electron-builder 生成安装包-p never 表示不上传 pnpm run distpackage.json 中还有几条 AGENTS.md 未列出但同样常用的脚本属于「开发流程」环节的补充# 打包但不生成安装器electron-builder --dir用于本地快速验证 pnpm run pack # 类型检查基于 tsconfig 的 project build--noEmit --force 强制执行全量检查 pnpm run typecheck # 代码格式化Biome 直接写回 src/ 目录 pnpm run format # 代码检查Biome check 校验 src/lint 格式 pnpm run lint # 强格式化Biome check --write会自动整理 import 顺序 pnpm run fix # 打包体积分析electron-vite preview --mode analyze pnpm run ana # UI 测试使用独立的 electron.vite.config_test.ts 配置 pnpm run uitest需要特别说明的是dist与pack都依赖electron-builder的 electron-builder.config.js 配置文件且dist与pack会先执行build。开发者模式还支持命令行参数-d、环境变量ESEARCH_DEV或设置项dev自动开启见 src/main/main.ts。三、项目结构主进程与多页面渲染进程3.1 总体布局AGENTS.md 将项目结构分为三块src/main/Electron 主进程、src/renderer/渲染进程内含多个功能页面、src/ShareTypes.d.ts共享类型定义。此外仓库根目录还有lib/供主进程与渲染进程共用的公共库与assets/Logo、图标、桌面文件等资源。从 electron.vite.config.ts 的rollupOptions.input可以看到渲染进程实际是一个多页面应用MPA共注册了 12 个 HTML 入口editor、clip、setting、ding、recorder、recorderTip、browser_bg、translator、translate、photoEditor、videoEditor、aiVision。这与 AGENTS.md 列出的页面一一对应。3.2 主进程src/main/src/main/main.tsElectron 主进程入口package.json 的main字段指向./out/main/main.js。该文件承担窗口创建、全局快捷键注册、系统托盘、用户数据路径解析支持--userData参数、preload_config文件以及portable便携目录、Store 初始化等职责。3.3 渲染进程功能页面src/renderer/按 AGENTS.md 的划分目录功能说明aiVision/AI 识图作为主页面editor的子页面clip/截屏截图窗口逻辑editor/主页面应用的聚合主界面ding/贴图屏幕贴图同时承载贴图翻译setting/设置设置窗口photoEditor/高级图片编辑独立图片编辑器recorder/普通录屏基础屏幕录制recorderTip/录屏覆盖层显示倒计时、结束提示等浮层translate/翻译展示不同翻译器结果作为主页面的子页面translator/屏幕翻译屏幕区域实时翻译videoEditor/高级录屏含鼠标跟踪、视频编辑root/界面样式定义全局样式与主题ocr/OCR 相关离线/在线 OCR 引擎封装screenShot/截屏库跨平台截屏实现含 Wayland 适配此外 AGENTS.md 还提及lib/属于「杂项公共功能」目录。结合仓库源码lib/实际是主进程与渲染进程共享的关键基础设施包括lib/ipc.ts进程间通信的类型安全封装详见下文第四节lib/store/设置存储store.ts、parse.ts、renderStore.ts实现基于点路径的读写与类型推导lib/translate/国际化翻译工具链source.json原始文本、各语言 JSON、tool.js命令行工具lib/key.ts、lib/time_format.ts、lib/utils.ts等工具模块3.4 共享类型src/ShareTypes.d.tssrc/ShareTypes.d.ts是整个项目的类型中枢定义了setting全部设置项的树状结构、功能工具枚举、MainWinType、translateWinType、DingStart、DingResize等类型。主进程、渲染进程与lib/store都从它导入类型例如 lib/store/store.ts 与 src/renderer/setting/setting.ts 均import type { setting }。新增设置项的第一步就是在该文件中扩展setting类型详见第五节。四、开发流程规范格式、类型与检查AGENTS.md 明确规定了质量门槛ts 修改都需要 biome 格式化pnpm run format和 ts 类型检查pnpm run typecheck还要pnpm run lint新文件可以pnpm run fix进行更强格式化和引入重排。从 biome.json 可以看到具体规则indentStyle: space、indentWidth: 4缩进为 4 空格organizeImports开启即fix会重排 importlinter 启用 recommended 规则集并额外开启了useDateNow、useValidForDirection两条错误级规则同时关闭了noNonNullAssertion允许非空断言。也就是说日常修改pnpm run format格式化→pnpm run typecheck类型→pnpm run lint静态检查新增文件改用pnpm run fix一步完成格式化 import 排序五、界面开发dkh-ui 与单文件页面AGENTS.md 指出界面开发采用dkh-ui创建、修改 DOM 与 CSS且「单 ts 文件覆盖界面绘制」——每个页面是一个 TS 文件配合对应的 HTML 入口如setting.tssetting.html页面逻辑不依赖框架组件树。dkh-ui已作为正式依赖声明在 package.json版本^0.14.2。以设置页 src/renderer/setting/setting.ts 为例其导入了一整套 UI 构建函数import { ele, input, select, textarea, radioGroup, dynamicList, ... } from dkh-ui;AGENTS.md 还特别提醒「如果修改文本需要修改翻译」——所有面向用户的文案都必须走国际化流程见第七节否则会在控制台出现翻译缺失的提示。六、进程交互lib/ipc.ts 的类型安全通信AGENTS.md 对进程交互的描述是页面与主进程交互lib/ipc.ts添加了类型约束所有消息都登记在Message变量上。这实际上是本项目中设计最精巧的基础设施之一值得深入讲解。6.1 Message 类型契约lib/ipc.ts 定义了Message类型——一个以消息名为键、以函数签名为值的映射表。每个键对应一种消息参数类型和返回值类型都在这里声明。例如type Message { clip_show: () void; // 无参、无返回值 clip_save: (ext: string) string; // 返回保存路径同步 clip_ding: (img: string, type: translate | ding, rect: { w: number; h: number; x: number; y: number }) void; hotkey: ((type: 快捷键, name: keyof setting[快捷键], key: string) boolean) | ((type: 快捷键2, name: 功能, key: string) boolean); // ... 共约 60 条消息 };借助ParametersMessage[K]、ReturnTypeMessage[K]等内置工具类型底层 API 的参数与返回值类型全部由Message推导从而保证主进程与渲染进程两端签名严格一致。6.2 四个方向的通信 APIlib/ipc.ts导出的核心函数及其语义如下函数方向语义mainSend(webContents, key, data)主进程 → 指定页面向某个WebContents发送消息renderOn(key, callback)页面接收页面注册监听等待主进程消息renderSend(key, data)页面 → 主进程页面发送异步消息renderSendSync(key, data)页面 → 主进程同步等待主进程返回用于获取路径、设置值等mainOn(key, callback)主进程接收主进程注册监听callback 可同步或异步返回结果mainOnReflect(key, callback)渲染进程间中转主进程将消息转发给 callback 返回的一组WebContents实现页面间广播从源码实现看lib/ipc.ts两端统一监听名为ipc的通道消息以(key, data)二元组传递renderSendSync走ipcRenderer.sendSync主进程侧通过设置event.returnValue回传结果。mainOnReflect专门用于「渲染进程之间的通信主进程起中转作用」的场景并借助VoidKeysMessage类型约束只允许转发无返回值的消息。6.3 与设置存储的关系主进程在 src/main/main.ts 中另注册了store通道支持get / set / path / getAll / setAll五种操作。渲染进程侧的封装见 lib/store/renderStore.tsstore.get使用sendSync同步读取store.set使用异步send写入。这是下一节「添加设置」的底层通道。七、添加设置项的完整流程AGENTS.md 给出的最小流程是在src/ShareTypes.d.ts的setting变量中添加设置项再用store.get(a.b.c)/store.set(a.b.c, v)读写。项目的 设置文档 进一步细化了这一流程可总结为以下五步7.1 第一步扩展类型定义在 src/ShareTypes.d.ts 的setting类型中新增字段。设置项以点路径组织如语言.语言、快捷键.截屏。类型定义是整个链路的地基——lib/store会从setting推导出SettingPath与GetValue// lib/store/renderStore.ts 中的核心类型推导 type PathsT T extends object ? { [K in keyof T]-?: ${K} | JoinK, PathsT[K] }[keyof T] : never; type SettingPath Pathssetting; type GetValueT, P extends string ...; // 递归解析出路径对应的值类型renderStore.ts注释中明确写着「使用类型映射和条件类型来解析路径」。这意味着store.get(a.b.c)的路径和返回类型在编译期就是受检的——写错路径名或类型会直接报类型错误。7.2 第二步在设置页面添加 UI在 src/renderer/setting/setting.ts 中为设置项创建el渲染函数返回的元素应使用dkh-ui创建且sv设置值、gv获取值的类型要与设置类型匹配。设置文档列出的常用 UI 构件构件用途xNumber数值输入xSwitch开关gv类型兼容booleanxColor颜色选择xPath路径选择xSecret密文/密钥输入xFont字体选择sortList可排序列表dialogB对话框按钮xGroup仅用于排版布局类似 flexbox设置文档特别提醒元素onchange事件要能触发否则修改不会被记录。7.3 第三步注册到设置 key在setting.ts的main中把新设置项添加进设置的 key 集合并可通过bind修改某些项后触发其他项页面更新、bindF触发具体函数、bindF2哪些项更新后触发「重启应用」提示等机制挂接联动行为。7.4 第四步读写设置读写设置推荐使用getSet而不是直接store.get如需写值尽量使用setSet而不是store.set。getSet/setSet封装在setting.ts内部会结合oldStore/nowStore快照见 src/renderer/setting/setting.ts来跟踪设置记忆与变更。底层存储实现可参考 lib/store/store.ts配置保存在userData/config.jsonconfigPath由主进程在 src/main/main.ts 中传入get未命中时会回退到默认值getAll通过deepMerge将用户数据与默认数据合并。7.5 第五步翻译文案设置项的名称、描述等一切新增文本都要走翻译流程第七节。AGENTS.md 与设置文档均强调「添加、修改、删除文字都要触发翻译流程」。八、国际化与翻译工作流翻译是 eSearch 开发中贯穿始终的一环。AGENTS.md 给出的起点是在lib/translate/source.json中添加[原始中文]:然后执行node lib/translate/tool.js -u为文本创建 id。完整工作流记录在 翻译文档可以拆解为以下环节8.1 生成待翻译 CSV# 输出英文语言的待翻译 csv包含未翻译/未跟进的新增文本 node lib/translate/tool.js -l en # en.csv abc,你好世界,-l lang指定目标语言en、es、fr、ru、eo、ar、zh-HANT等对应 lib/translate 目录下的各语言 JSON-a输出全部文字。翻译文档特别提示若原有翻译存在不足需要修改用-a若只是跟进新增文本eSearch 某些文字已修改而翻译未修改不要加-a以聚焦增量-e同时输出中英文对照便于译者参考abc,你好世界,Hello World,8.2 编辑与保存编辑 csv 时将第三列目标语言翻译补全lib/translate/readme.md甚至给出了可直接复制的 AI Prompt「以下是 csv 文件把第二列翻译成 en 并复制到第三列」。完成编辑后导入node lib/translate/tool.js -i en.csv保存时tool.js会把翻译结果写回对应语言的 JSON 文件如en.json。注意只有在source.json里定义的文字才能被翻译若界面存在无法翻译的文字说明该页面未国际化需要反馈 bug 并指明位置。8.3 标记翻译进度srcCommit / finishIdtool.js定义了srcCommit变量见 lib/translate/tool.js借助 git 的 diff 能力跟踪翻译进度每个语言记录其翻译所基于的source.json的 commit idid翻译完某个 id 后将其加入该语言的finishId数组再次输出 csv 时会忽略它从而专注于未翻译/刚修改的文本全部翻译完成后将srcCommit的id改为latestSrcId即git log -n 1输出的source.json最新 commit并清空finishId8.4 开发者控制台提示翻译文档还定义了运行期的可视化反馈若source.json没有定义的语言文本控制台会以红色 字体和背景输出若定义了但未翻译则以蓝色 输出。这为运行时排查遗漏的国际化文本提供了直接线索。8.5 运行期翻译运行期的文案替换由 lib/translate/translate.ts 承担主进程在 src/main/main.ts 中导入t翻译函数、lan当前语言、getLans可用语言列表渲染进程的 src/renderer/lib/translate.ts 同样提供相应能力。source.json中的中文原文即各语言翻译的 key 来源。九、常见开发场景速查综合 AGENTS.md 与上述源码分析可将常见开发任务归纳为一张速查表任务入口/步骤关键文件修改界面或功能用dkh-ui创建 DOM单 ts 文件覆盖绘制修改文本必须走翻译src/renderer/editor/editor.ts、src/renderer/*/*.ts页面与主进程通信在Message中登记名称/参数/返回值两端用mainSend/mainOn、renderOn/renderSend/renderSendSynclib/ipc.ts页面间通信用mainOnReflect让主进程向多个页面广播lib/ipc.ts新增设置项①ShareTypes.d.ts扩展setting→ ②setting.ts添加 UI → ③main注册 key → ④ 用getSet/setSet读写 → ⑤ 翻译src/ShareTypes.d.ts、src/renderer/setting/setting.ts、设置文档修改/新增文案source.json加原文:→node lib/translate/tool.js -u生成 id → csv 翻译 →-i导入lib/translate/source.json、lib/translate/tool.js、翻译文档代码质量把关pnpm run format→pnpm run typecheck→pnpm run lint新文件用pnpm run fixbiome.json、tsconfig.json本地运行与打包pnpm run dev/pnpm run build/pnpm run start/pnpm run distpackage.json、electron.vite.config.ts十、小结eSearch 是一个「以识屏为核心、多能力聚合」的 Electron 桌面应用。从 AGENTS.md 这份开发指南可以看出其工程化的关键设计多页面渲染架构主进程 12 个功能页面electron.vite.config.ts每页一个 TS 入口、一套 HTML类型即契约Messagelib/ipc.ts与setting/SettingPathsrc/ShareTypes.d.ts、lib/store/renderStore.ts分别在 IPC 与设置存储层面提供编译期校验统一质量门槛Biomeformat lint import 整理与tsc --noEmit类型检查是每次改动的必选项国际化内建到流程一切文案修改都必须同步走source.json→tool.js→ 各语言 JSON 的翻译链路。对于想要深入参与项目的开发者建议按「设置项新增 → IPC 消息扩展 → 翻译文本提交」的最小闭环先做一次完整实践即可快速熟悉项目从类型到运行时的全链路随后再按需深入截屏src/renderer/screenShot、OCRsrc/renderer/ocr、录屏src/renderer/videoEditor等具体功能模块。【免费下载链接】eSearch截屏 离线OCR 搜索翻译 以图搜图 贴图 录屏 万向滚动截屏 屏幕翻译 Screenshot Offline OCR Search Translate Search for picture Paste the picture on the screen Screen recorder Omnidirectional scrolling screenshot Screen translator 支持Windows Linux macOS项目地址: https://gitcode.com/GitHub_Trending/es/eSearch创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考