📚 MVP 电子书阅读器 (AI 辅助开发实践)

English | 简体中文

💡 写在前面的话 (致面试官)：
这是我的第一个 AI 辅助开发项目。作为一个学习型项目，我的核心目标不仅是“写代码”，而是学习如何与 AI 协作、如何定义产品、以及如何控制 AI 的行为边界。
在这个项目中，我深刻体会到了 AI 时代开发模式的转变：从“敲代码”转变为“写文档、定规范、做架构”。我通过编写 PRODUCT.md 来驱动需求，通过设计 AGENTS.md 来约束 AI，最终实现了产品从 v1.0 到 v2.0 的架构跃迁。

轻量级桌面端 MVP 电子书阅读器，专注简洁无干扰的阅读体验。支持 TXT / EPUB 双格式导入与 60fps 硬件加速翻页，对标现代极简美学，支持多套主题一键换肤。

🚀 我的 AI 开发实践心得

本项目最大的亮点在于其 AI-Native 的工程化管理模式。在开发过程中，我并没有盲目地让 AI 自由生成代码，而是通过建立严谨的文档体系来掌控全局：

1. 需求驱动：用 PRODUCT.md 定义产品

在项目初期，我学习到 AI 需要明确的上下文和目标。我编写了 PRODUCT.md（产品需求白皮书），详细定义了核心功能、交互流程和 UI 细节。这让 AI 在后续开发中始终保持在正确的业务轨道上，避免了“发散式”的错误生成。

2. 行为约束：用 AGENTS.md 解决上下文丢失

在多轮对话后，我遇到了 AI 开发常见的“失忆”和“代码打架”问题。为此，我制定了项目的“最高法律”——AGENTS.md。

• 强制启动协议：要求 AI 每次接手必须先读取最新进度。
• 零上下文丢失：要求 AI 将每次临时决策立刻落盘到文档，不再依赖单次会话记忆。
• 收尾固化：每次开发结束前，强制 AI 总结并写入带时间戳的交接清单。 这套机制极大地提升了与 AI 协作的稳定性和代码的一致性。

3. 技术掌控：理解 TECH_DESIGN.md 与重构

在产品从 1.0 迭代到 2.0 时，经历了底层的彻底重构（例如引入 CSS 多列虚拟引擎、实现跨格式解析）。我通过维护 TECH_DESIGN.md（技术架构文档），强制自己去理解每一项架构决策（ADR）背后的逻辑，确保我始终是项目的“掌控者”而非“代码搬运工”。

---

📈 产品演进与效果预览

在明确了需求和规范后，产品迎来了跨越式的迭代。

v1.0 阶段：核心链路跑通

早期实现了基础的 TXT 读取和三栏式布局，验证了基础逻辑。

(图：1.0 经典三栏，基础的纸墨风格)

v2.0 阶段：架构重构与体验飞跃 (对标现代阅读器)

在 v2.0 中，我重构了整个底层架构，加入了 EPUB 支持，并在设计上追求极简与沉浸感。

v2.0 书架与换肤面板	v2.0 沉浸式双页阅读
真封面与毛玻璃 UI：重写了书架逻辑，自动提取书籍封面。实现了 Aa 悬浮面板，支持 4 套主题与字号无级调节。	纸质书般的沉浸感：实现了单/双栏一键切换，中央加入仿书脊阴影，配合 60fps 的 GPU 翻页动画，体验大幅提升。

---

💻 核心功能特性 (v2.0)

• 格式支持：TXT 智能切章（支持 UTF-8 / GBK），EPUB 原书目录树解析与真封面提取。
• 高保真阅读体验：
  • 基于 CSS 多列引擎 + GPU 硬件加速的顺滑翻页。
  • 纸墨美学设计，支持跨章滑入动画、中央书脊阴影。
  • Aa 物理级控制面板（米白/青绿/燕麦/夜间 四套主题）。
• 数据安全与极致性能：
  • 主进程直写 userData/library.json，原子写盘，不依赖 localStorage。
  • 自定义 reader:// 协议懒加载资源，突破超大文件性能瓶颈。
  • 进度 300ms 节流落盘，关闭重开精准恢复。

📁 工程目录结构

├── build/                # 打包资源
├── src/                  # 源码目录
│   ├── main/             # Electron 主进程 (数据中心 + IPC + reader:// 协议)
│   ├── preload/          # 预加载脚本 (contextBridge 安全隔离)
│   ├── renderer/         # 渲染进程 (Vue 3 核心 UI 层)
│   └── core/             # 核心纯逻辑层 (跨格式解析 / 切片引擎)
├── demo-book/            # 本地测试书库
├── AGENTS.md             # ⭐️ AI Agent 最高行为与协作准则
├── PROGRESS.md           # ⭐️ 最高动态事实来源 (迭代进度)
├── PRODUCT.md            # ⭐️ 产品需求白皮书
├── TECH_DESIGN.md        # ⭐️ 技术架构与决策白皮书 (ADR)
├── CONTRACT_TEST.md      # ⭐️ 接口契约规范
└── package.json          # 依赖配置

(注：带 ⭐️ 的文档为本项目的核心 AI 协作管理矩阵)

🛠 技术栈

模块	技术选型
桌面基座	Electron 33 (严格开启沙箱与上下文隔离)
UI 框架	Vue 3 (SFC + <script setup>)
构建工具	electron-vite 构建 + electron-builder 打包
文本渲染	CSS Multi-column 虚拟分列 + GPU translateX 翻页
数据与 IO	主进程直写 JSON + Node fs (渲染层受限访问)

🚀 快速启动

环境要求：Node.js 22+ (开发环境已验证 v22.23.2), npm 10+ / pnpm

# 方式 1: Windows 用户, 一键启动
# 双击项目根目录下的 `启动.cmd`，自动编译并运行

# 方式 2: 终端手动启动
npm install           # 安装依赖 (首次)
npm run dev           # 启动开发模式 (含热更新)
npm run build         # 构建生产环境产物到 out/
pnpm dist             # 打包 Windows 安装程序 (到 dist/ 目录)

📝 许可证

本项目采用 MIT License 许可协议。