From 067636aa29fbd5e922597b6dd2907bf89f6ef33d Mon Sep 17 00:00:00 2001 From: yuantao Date: Fri, 30 Jan 2026 14:01:32 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=20=E5=AE=8C=E5=96=84?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84=EF=BC=8C?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20AGENTS.md=20=E5=92=8C=E6=9B=B4=E6=96=B0=20?= =?UTF-8?q?README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 398 insertions(+) create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..efb3d40 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,185 @@ +# TinyPanda 项目上下文 + +## 项目概述 + +TinyPanda 是一个基于 Electron 桌面应用框架的专业图片压缩工具，使用 Tinify API 提供高质量图片压缩服务。 + +**技术栈：** +- **Electron 32.0.0** - 跨平台桌面应用框架 +- **Tinify API** - 图片压缩服务 +- **JSZip 3.10.1** - 文件打包下载 +- **Electron Store 8.2.0** - 配置持久化 +- **原生 CSS** - Windows 11 Fluent Design 风格 UI + +**项目作者：** Pandora Studio +**项目仓库：** https://git.pandorastudio.cn/product/TinyPanda.git +**API 文档：** https://tinify.cn/developers/reference/nodejs + +## 核心功能 + +1. **批量图片压缩** - 支持队列管理，可同时处理多张图片 +2. **实时进度显示** - 显示压缩进度和状态 +3. **压缩效果对比** - 显示压缩前后大小对比及节省比例 +4. **打包下载** - 支持将所有压缩后的图片打包为 ZIP 下载 +5. **拖拽上传** - 支持拖拽图片到上传区域 +6. **自定义标题栏** - 无边框窗口，支持最小化、最大化、关闭 + +**支持的图片格式：** JPG/JPEG、PNG、WebP + +## 项目结构 + +``` +TinyPanda/ +├── src/ +│ ├── main/ +│ │ └── index.js # Electron 主进程（窗口管理、IPC 通信、文件操作） +│ └── renderer/ +│ ├── index.html # 渲染进程 HTML 结构 +│ ├── styles.css # Windows 11 Fluent Design 风格样式 +│ ├── app.js # 渲染进程逻辑（队列管理、UI 交互） +│ └── icons.js # 自定义图标 Web Component (tp-icon) +├── .env # 环境变量（TINIFY_API_KEY） +├── .gitignore +├── package.json # 项目配置和依赖 +├── package-lock.json +├── README.md # 项目说明文档 +└── brief.txt # 项目简要说明 +``` + +## 构建和运行 + +### 安装依赖 +```bash +npm install +``` + +### 开发模式运行 +```bash +npm run dev +``` + +### 打包应用 +```bash +# 仅打包 Windows 应用 +npm run build:win + +# 打包所有平台 +npm run build +``` + +### 注意事项 +- 首次运行需要在 `.env` 文件中配置 `TINIFY_API_KEY` +- 开发模式下会自动打开开发者工具（当 `NODE_ENV=development`） +- 打包后的应用会输出到 `dist` 目录 + +## 开发约定 + +### 代码风格 +- 使用 ES6+ JavaScript 语法 +- 主进程和渲染进程通过 IPC (Inter-Process Communication) 通信 +- 使用 `async/await` 处理异步操作 + +### IPC 通信协议 + +**主进程提供的 IPC 处理器：** + +| 处理器名称 | 参数 | 返回值 | 说明 | +|-----------|------|--------|------| +| `get-api-key` | 无 | `{ apiKey: string }` | 获取当前 API Key | +| `set-api-key` | `key: string` | `{ success: boolean }` | 设置 API Key | +| `validate-api-key` | `key: string` | `{ valid: boolean }` | 验证 API Key 有效性 | +| `compress-image` | `filePath: string` | `{ success: boolean, compressedData?: string, error?: string }` | 压缩单张图片 | +| `get-image-info` | `filePath: string` | `{ success: boolean, size?: number, error?: string }` | 获取图片文件信息 | +| `save-compressed-image` | `savePath: string, base64Data: string` | `{ success: boolean, error?: string }` | 保存压缩后的图片 | +| `create-zip` | `files: Array<{name: string, data: string}>` | `{ success: boolean, zipData?: string, error?: string }` | 创建 ZIP 压缩包 | +| `select-save-directory` | 无 | `{ canceled: boolean, path?: string }` | 选择保存目录 | +| `select-files` | 无 | `{ canceled: boolean, files?: string[] }` | 选择多个文件 | +| `window-minimize` | 无 | 无 | 最小化窗口 | +| `window-maximize` | 无 | 无 | 最大化/还原窗口 | +| `window-close` | 无 | 无 | 关闭窗口 | +| `window-is-maximized` | 无 | `boolean` | 获取窗口最大化状态 | + +### UI 设计规范 +- 遵循 Windows 11 Fluent Design 设计语言 +- 使用自定义 Web Component `` 渲染图标 +- 状态标签使用颜色编码： + - `status-pending` - 黄色（待处理） + - `status-processing` - 蓝色（处理中） + - `status-completed` - 绿色（已完成） + - `status-error` - 红色（错误） + +### 文件命名约定 +- 文件大小格式化函数：`formatSize(bytes)` - 返回格式化字符串（如 "1.5 MB"） +- 队列项结构： + ```javascript + { + id: number, // 唯一标识 + name: string, // 文件名 + path: string, // 文件路径 + originalSize: number, // 原始大小（字节） + compressedSize: number|null, // 压缩后大小（字节） + compressedData: string|null, // 压缩数据（Base64） + status: 'pending'|'processing'|'completed'|'error', + progress: number // 进度（0-100） + } + ``` + +### API Key 管理 +- API Key 通过 `.env` 文件或运行时设置 +- 每个账户每月有 500 次免费压缩额度 +- 验证 API Key 时，如果返回非 Credentials 错误，则认为 Key 格式正确 + +## Electron 配置 + +**窗口配置：** +- 尺寸：1200x800 +- 无边框窗口（`frame: false`） +- 支持自定义标题栏和窗口控制按钮 +- Node 集成启用（`nodeIntegration: true`） +- 上下文隔离禁用（`contextIsolation: false`） + +**打包配置：** +- App ID：`cn.pandorastudio.tinypanda` +- 产品名称：TinyPanda +- Windows 目标：NSIS 安装程序 +- 图标：`assets/icon.ico` + +## 测试建议 + +**手动测试清单：** +1. API Key 验证功能 +2. 单张图片压缩 +3. 批量图片压缩 +4. 拖拽上传功能 +5. 压缩进度显示 +6. 压缩前后大小对比 +7. 单张下载功能 +8. 打包下载功能 +9. 窗口控制（最小化、最大化、关闭） +10. 错误处理（无效 API Key、无效文件等） + +## 常见问题 + +**Q: 如何获取 Tinify API Key？** +A: 访问 https://tinify.cn/ 注册账号，免费账户每月有 500 次压缩额度。 + +**Q: 压缩失败怎么办？** +A: 检查 API Key 是否有效、网络连接是否正常、文件格式是否支持。 + +**Q: 如何修改 UI 样式？** +A: 主要样式在 `src/renderer/styles.css` 中，使用 CSS 变量定义主题色。 + +**Q: 如何添加新的图片格式支持？** +A: 修改 `src/main/index.js` 中的文件选择器过滤器，以及 Tinify 支持的格式。 + +## 贡献指南 + +如需修改代码，请遵循以下步骤： +1. 阅读现有代码，理解项目架构 +2. 保持代码风格与现有代码一致 +3. 测试修改后的功能 +4. 确保打包后应用正常运行 + +## 许可证 + +MIT License \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e779859 --- /dev/null +++ b/README.md @@ -0,0 +1,213 @@ +# TinyPanda 🐼 + +专业的图片压缩工具，基于 Electron 和 Tinify API 构建。 + +![TinyPanda Logo](assets/icon.png) + +## ✨ 功能特性 + +- ✅ **批量图片压缩** - 支持队列管理，可同时处理多张图片 +- ✅ **实时进度显示** - 显示压缩进度和状态 +- ✅ **压缩效果对比** - 显示压缩前后大小对比及节省比例 +- ✅ **打包下载** - 支持将所有压缩后的图片打包为 ZIP 下载 +- ✅ **拖拽上传** - 支持拖拽图片到上传区域 +- ✅ **美观的现代化 UI** - Windows 11 Fluent Design 风格界面 +- ✅ **自定义标题栏** - 无边框窗口设计，支持窗口控制 + +## 🖼️ 支持的图片格式 + +- JPG / JPEG +- PNG +- WebP + +## 🚀 快速开始 + +### 环境要求 + +- Node.js >= 14.0.0 +- npm >= 6.0.0 + +### 安装依赖 + +```bash +npm install +``` + +### 配置 API Key + +1. 访问 [Tinify 官网](https://tinify.cn/) 注册账号 +2. 获取您的 API Key +3. 在项目根目录创建 `.env` 文件，添加以下内容： + +```env +TINIFY_API_KEY=your_api_key_here +``` + +### 运行应用 + +```bash +npm run dev +``` + +### 打包应用 + +```bash +# 打包为 Windows 应用 +npm run build:win + +# 打包为所有平台 +npm run build +``` + +打包后的应用将输出到 `dist` 目录。 + +## 📖 使用说明 + +### 1. 验证 API Key + +- 点击右上角设置按钮 +- 输入您的 API Key +- 点击"验证"按钮确认有效性 +- 点击"保存"保存配置 + +### 2. 添加图片 + +- **方法一**：点击"选择图片"按钮选择文件 +- **方法二**：直接拖拽图片到上传区域 + +### 3. 压缩图片 + +- 添加图片后，点击"全部压缩"按钮 +- 等待所有图片压缩完成 +- 查看每张图片的压缩前后大小对比和节省比例 + +### 4. 下载结果 + +- **单张下载**：点击每张图片的"下载"按钮 +- **批量下载**：点击"打包下载"按钮，选择保存位置 + +## 🛠️ 技术栈 + +- **Electron 32.0.0** - 桌面应用框架 +- **Tinify API** - 专业图片压缩服务 +- **JSZip 3.10.1** - 文件打包 +- **Electron Store 8.2.0** - 配置持久化 +- **原生 CSS** - Windows 11 Fluent Design 风格 + +## 📁 项目结构 + +``` +TinyPanda/ +├── src/ +│ ├── main/ +│ │ └── index.js # 主进程代码（窗口管理、IPC 通信） +│ └── renderer/ +│ ├── index.html # 渲染进程 HTML +│ ├── styles.css # 样式文件 +│ ├── app.js # 渲染进程逻辑 +│ └── icons.js # 图标组件 +├── assets/ # 资源文件（图标等） +├── .env # 环境变量配置 +├── package.json # 项目配置 +└── README.md # 项目说明 +``` + +## 🔑 API Key 注意事项 + +- 每个账户每月有 **500 次**免费压缩额度 +- API Key 请妥善保管，不要泄露 +- 可以在 [Tinify 官网](https://tinify.cn/developers) 查看详细文档 +- 压缩失败时请检查 API Key 是否有效、网络连接是否正常 + +## 🎨 UI 设计 + +TinyPanda 采用 **Windows 11 Fluent Design** 设计语言，提供： + +- 流畅的动画效果 +- 半透明毛玻璃效果 +- 现代化的图标和按钮 +- 响应式的布局设计 +- 清晰的状态指示 + +## 📝 开发指南 + +### 代码风格 + +- 使用 ES6+ JavaScript 语法 +- 主进程和渲染进程通过 IPC 通信 +- 使用 `async/await` 处理异步操作 + +### IPC 通信协议 + +主进程提供以下 IPC 处理器： + +- `get-api-key` - 获取当前 API Key +- `set-api-key` - 设置 API Key +- `validate-api-key` - 验证 API Key +- `compress-image` - 压缩单张图片 +- `get-image-info` - 获取图片信息 +- `save-compressed-image` - 保存压缩后的图片 +- `create-zip` - 创建 ZIP 压缩包 +- `select-save-directory` - 选择保存目录 +- `select-files` - 选择文件 +- `window-minimize/maximize/close` - 窗口控制 + +### 添加新功能 + +1. 在 `src/main/index.js` 中添加 IPC 处理器 +2. 在 `src/renderer/app.js` 中调用相应的 IPC 方法 +3. 在 `src/renderer/index.html` 中添加 UI 元素 +4. 在 `src/renderer/styles.css` 中添加样式 + +## 🐛 常见问题 + +**Q: 压缩失败怎么办？** + +A: 请检查以下项： +- API Key 是否有效 +- 网络连接是否正常 +- 文件格式是否支持（JPG、PNG、WebP） +- 查看控制台错误信息 + +**Q: 如何获取更多压缩额度？** + +A: 访问 [Tinify 官网](https://tinify.cn/) 查看付费计划。 + +**Q: 可以离线使用吗？** + +A: 不可以，压缩功能需要连接到 Tinify API 服务器。 + +**Q: 压缩后的图片质量如何？** + +A: Tinify 使用智能压缩算法，在保持视觉质量的同时最大化压缩率，通常可以减少 50-80% 的文件大小。 + +## 🤝 贡献 + +欢迎提交 Issue 和 Pull Request！ + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 开启 Pull Request + +## 📄 许可证 + +MIT License - 详见 [LICENSE](LICENSE) 文件 + +## 👥 作者 + +**Pandora Studio** + +- 项目主页: https://git.pandorastudio.cn/product/TinyPanda.git +- 问题反馈: [Issues](https://git.pandorastudio.cn/product/TinyPanda.git/issues) + +## 🙏 致谢 + +- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架 +- [Tinify](https://tinify.cn/) - 专业图片压缩服务 +- [JSZip](https://stuk.github.io/jszip/) - JavaScript ZIP 库 + +--- + +⭐ 如果这个项目对你有帮助，请给它一个 Star！ \ No newline at end of file