# fish-reader

**Repository Path**: xu-jingxun/fish-reader

## Basic Information

- **Project Name**: fish-reader
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fish-reader

fish-reader 是一个面向 Windows 的本地纯文本悬浮阅读器。它把 `.txt` 内容显示在透明、无边框、可缩放且可置顶的窗口中，适合把阅读窗口拖到桌面的任意位置，在处理其他工作时低调阅读。

> 当前版本已经支持滚动阅读和全局窗口操作快捷键，但**尚未实现全局“上一页 / 下一页”快捷键**。在其他应用保持焦点时快速翻页，仍属于下一步规划。

**最后更新：** 2026-08-11

## 已实现功能

- 通过系统文件选择框打开本地 `.txt` 文件，并在下次启动时恢复最后一次打开的文件
- 透明、无边框、可拖动、可缩放的悬浮窗口，默认置顶并隐藏任务栏入口
- 鼠标滚轮或滚动条阅读，显示估算行号和阅读百分比
- 全局快捷键打开文件、显示或隐藏窗口、切换点击穿透、打开设置面板
- 点击穿透、跟随鼠标、窗口贴边吸附和托盘驻留
- VSCode、IDEA、墨色、纸张四种主题，以及面板、紧凑、低调三种布局
- 可调整背景透明度、字体大小和部分全局快捷键
- 自动保存最后一次阅读位置、窗口位置和尺寸、界面设置
- 单实例运行；再次启动时会唤回已有窗口

## Windows 环境要求

- Windows 桌面环境。项目当前只以 Windows 为产品目标
- Node.js 和 npm。仓库目前没有通过 `engines` 或版本文件锁定具体 Node.js 版本

仓库暂未提供预构建安装程序或便携版，可以从源码运行，也可以在本地使用 electron-builder 打包。

## 安装与开发

```powershell
git clone https://gitee.com/xu-jingxun/fish-reader.git
cd fish-reader
npm install
npm run dev
```

`npm run dev` 通过 electron-vite 同时启动主进程、预加载脚本、渲染进程和 Electron 开发实例。已有 `package-lock.json`，在 CI 或需要严格按锁文件安装时也可以使用 `npm ci`。

## 构建与运行

```powershell
npm run build
npm start
```

`npm run build` 会先执行 Vue 与 Node 两套类型检查，再把主进程、预加载脚本和渲染进程编译到 `out/`。`npm start` 通过 electron-vite 运行已经构建的桌面应用；它不会自动构建。

需要生成未打包目录或安装包时，可以分别执行：

```powershell
npm run pack
npm run dist
```

## 项目结构

项目采用与 serial-assistant 一致的 electron-vite 三进程布局：

```text
fish-reader/
├─ src/
│  ├─ main/                 # Electron 主进程、窗口、托盘、文件与状态持久化
│  │  └─ *.test.ts          # 主进程模块测试与实现共置
│  ├─ preload/              # contextBridge 与受控 IPC 接口
│  ├─ renderer/
│  │  ├─ index.html
│  │  └─ src/               # Vue 界面、样式和组件测试
│  └─ shared/               # 三个进程共享的类型、IPC 常量和纯函数
│     └─ *.test.ts          # 共享模块测试与实现共置
├─ tests/e2e/               # 启动真实 Electron 应用的 Playwright 测试
├─ electron.vite.config.ts
├─ vitest.config.ts
├─ playwright.config.ts
├─ tsconfig.node.json
├─ tsconfig.web.json
└─ tsconfig.json            # TypeScript project references
```

构建产物统一位于 `out/main`、`out/preload` 和 `out/renderer`。除 E2E 外，测试文件放在被测模块旁边，便于功能代码与测试同步维护。

## 使用方式

1. 启动应用后，点击工具栏的文件夹图标，或按 `Ctrl+Alt+O` 选择 UTF-8 编码的 `.txt` 文件。
2. 拖动顶部工具栏移动窗口，通过窗口边缘调整大小；使用鼠标滚轮或滚动条阅读。
3. 设置面板可以切换主题、布局、置顶、自动贴边、跟随鼠标、透明度、字体大小和部分快捷键。
4. 启用点击穿透后，鼠标将无法直接操作阅读窗口；按 `Ctrl+Alt+P` 关闭点击穿透即可恢复交互。
5. 关闭窗口只会将它隐藏到系统托盘。双击托盘图标可以显示或隐藏窗口，通过托盘右键菜单可退出应用。

## 默认快捷键

以下快捷键由 Electron 注册为全局快捷键，窗口没有焦点时也可以触发。

| 操作 | 默认快捷键 | 设置面板中可修改 |
|------|------------|------------------|
| 打开本地文本 | `Ctrl+Alt+O` | 是 |
| 显示 / 隐藏窗口 | `Ctrl+Alt+H` | 否 |
| 开启 / 关闭点击穿透 | `Ctrl+Alt+P` | 是 |
| 显示 / 隐藏设置面板 | `Ctrl+Alt+S` | 是 |
| 上一页 / 下一页 | 无 | 尚未实现 |

自定义快捷键需使用 Electron 支持的 accelerator 格式。当前版本没有快捷键格式校验或注册失败提示；如果快捷键无效或已被其他程序占用，对应操作可能不会生效。

## 状态与隐私

应用运行时直接从本地磁盘读取文本。当前代码没有账号系统、遥测、内容上传或网络内容源，也不会把文本正文复制到状态文件。

状态文件会保存最后打开文件的完整路径和文件名、滚动位置与进度、窗口位置和尺寸，以及阅读器设置。在 Windows 的常见默认配置下，文件位于 `%APPDATA%\fish-reader\fish-reader\state.json`；本质路径为 Electron `userData` 目录下的 `fish-reader/state.json`。

## 测试与检查

<!-- AUTO-GENERATED: package scripts -->
| 命令 | 用途 |
|------|------|
| `npm run dev` | 通过 electron-vite 启动完整 Electron 开发环境 |
| `npm run build` | 执行类型检查并构建主进程、预加载脚本和渲染进程 |
| `npm start` | 运行 `out/` 中已经构建的 Electron 应用 |
| `npm run typecheck` | 检查 Node 进程和 Vue 渲染进程的 TypeScript 类型 |
| `npm test` | 运行 Vitest 测试并检查 80% 覆盖率阈值 |
| `npm run test:unit` | 运行 Vitest 测试，不生成覆盖率报告 |
| `npm run test:watch` | 以监听模式运行 Vitest |
| `npm run test:e2e` | 先构建，再启动真实 Electron 应用运行 Playwright E2E |
| `npm run pack` | 生成未打包的 electron-builder 应用目录 |
| `npm run dist` | 使用 electron-builder 生成分发产物 |
<!-- /AUTO-GENERATED: package scripts -->

当前 Playwright 用例会直接启动 `out/main/index.js`，验证桌面窗口、真实 preload bridge、设置面板和紧凑窗口尺寸。原生文件选择框、系统托盘和全局快捷键仍需要人工或更专门的桌面自动化测试。

## 技术栈

- Electron
- Vue 3 + TypeScript
- electron-vite + Vite
- Ant Design Vue + Lucide Icons
- Vitest + Playwright

## 当前限制与下一步

- 只支持本地 `.txt` 文件，并按 UTF-8 解码；暂不支持其他编码、EPUB、PDF、网页或剪贴板内容
- 目前通过连续滚动阅读，没有显式分页逻辑，也没有全局上一页 / 下一页快捷键
- “把文本放在桌面任意位置”当前指移动和缩放悬浮窗口；尚不能把文本嵌入任意第三方应用界面
- 只保存最后一次打开文件的会话，不是多文件书架，也不为每个文件分别维护阅读进度
- 快捷键冲突或注册失败时没有界面提示
- 仓库尚未发布预构建安装包，也没有自动更新和发布流水线；本地可以通过 electron-builder 生成分发产物
- macOS 和 Linux 不在当前支持范围内

下一步最核心的能力是增加可配置的全局上一页 / 下一页快捷键，让用户在阅读窗口未聚焦、甚至开启点击穿透时也能翻页。