images-press-app-web

Imported from wtwtmy/images-press-app-web (AGENTS.md). Install upstream with npx skills add wtwtmy/images-press-app-web. Copyright stays with the author.

AGENTS.md — 项目指令与状态

规则
在本次对话的每一步操作前，你必须首先重新阅读并理解整个 AGENTS.md。分析当前项目状态，并按照本文件中的计划和约束执行任务。如果需要推进项目阶段、发现新问题、调整技术决策或完成模块，必须立即更新本文件的相关内容（包括状态、任务清单、架构说明、日志等），以保持 AGENTS.md 始终反映项目最新真实情况。

1. 项目目标

制作一个优先支持 JPG/JPEG 的无损压缩图片智能软件。首版以 Web 端网页实现，用户上传图片后可下载压缩后的版本，且解码后得到的图片与原图逐像素一致。首版实际压缩 JPG/JPEG 与 PNG，并为 WebP/GIF/TIFF 等格式保留兼容识别与后续扩展入口。

2. 项目约束

• 优先考虑实现 JPG/JPEG 无损压缩，同时支持 PNG 无损压缩；其他格式首版识别并给出兼容提示。
• 界面必须简洁易用：上传 → 压缩 → 下载。
• 必须对比显示压缩前后的文件大小、节省比例。
• 核心压缩算法可选用已有的优秀开源库，但需合理集成并保证无损。
• 优先完成一个可工作的最小原型，再考虑优化和扩展。

3. 技术选型（暂定，可按需修改）

• 实现形式：前后端分离 Web 应用。后续可考虑用 Electron 或 Tauri 包装成桌面应用。
• 前端：React + TypeScript + Tailwind CSS。
• 后端：Node.js + Express + TypeScript，负责上传接收、格式识别、调用无损压缩工具、像素校验与结果返回。
• 关键库：
  • JPG/JPEG 压缩：jpegtran / MozJPEG 系工具，执行无损 Huffman 表优化、progressive 转换与元数据剥离，不重新有损编码。
  • PNG 压缩：oxipng，执行无损 PNG 优化。
  • 无损校验：使用统一解码流程比较压缩前后像素数据。
• 判断标准：最终选用能实现真正无损且压缩效果好的方案。

4. 当前项目阶段：初始化

• 确定最终技术架构（纯前端 vs 前后端分离）
• 初始化项目结构
• 选择和集成无损压缩核心库
• 实现图片上传与预览
• 实现压缩处理逻辑
• 显示压缩前后信息对比
• 实现压缩后图片下载
• 基础 UI/UX 打磨
• 测试多种图片与边界情况
• 初始化 Git 版本管理并配置忽略规则

5. 架构与设计决策

首版确定采用前后端分离 Web 架构。

• 选择后端的理由：JPG/JPEG 的真正无损压缩应使用 jpegtran / MozJPEG 系工具做系数级转码和 Huffman 表优化，不能通过浏览器 Canvas 或普通重新编码实现。PNG 无损压缩也更适合由后端调用 oxipng 等成熟二进制工具完成。后端可以统一控制格式检测、临时文件、工具调用、超时、错误处理与像素级校验。
• 前端职责：提供单页上传体验，完成图片预览、压缩状态提示、压缩前后大小与节省比例展示、压缩结果下载。首版只处理单文件，不做批量压缩。
• 后端职责：提供 POST /api/compress，接收 multipart/form-data 字段 file，支持 image/jpeg 与 image/png；对 WebP/GIF/TIFF 等格式返回明确兼容提示；默认无损模式调用无损压缩工具后比较解码像素，校验失败或无体积收益时返回原图并标记 skipped，避免输出有损或更大的结果。新增 target-size 模式作为用户显式选择的有损体积目标模式，首版目标为 1MB 内，使用 Sharp 重新编码并在响应中明确标记非无损。
• 共享契约：使用 packages/shared 管理支持格式、响应头名、状态枚举和统计类型，避免前后端接口漂移。
• 开发启动：根级 npm run dev 由 scripts/dev.mjs 统一探测可用端口并启动 API/Web。默认 API 从 API_PORT/PORT 或 4000 开始，Web 从 VITE_WEB_PORT 或 5173 开始，并通过 VITE_API_TARGET 将真实 API 地址传给 Vite 代理。

6. 进度日志

• 2026-05-10 13:55 CST：根据 JPG 优先的新要求，确定采用 React + TypeScript 前端、Node.js + Express 后端的前后端分离架构；首版支持 JPG/JPEG 与 PNG 无损压缩，其他格式先做兼容提示。
• 2026-05-10 14:20 CST：初始化 npm workspaces、apps/web、apps/api、packages/shared，实现上传、压缩、校验、结果下载与基础 UI。下一步继续补充样例图片与端到端边界测试。
• 2026-05-10 14:35 CST：尝试安装 npm 依赖但下载过程超时，升级权限请求未完成审批；当前代码已落盘但尚未完成本地依赖安装、类型检查、测试和浏览器验证。
• 2026-05-10 14:40 CST：完成静态修正：临时目录改用唯一目录、删除逻辑保持逐个明确文件处理、补充二进制包类型声明、修正前端导入与样式类名。
• 2026-05-10 14:50 CST：按要求改用 https://registry.npmmirror.com 镜像源申请运行 npm install，两次升级权限审批均超时未返回；依赖安装仍未完成。
• 2026-05-10 15:45 CST：定位安装失败原因为 oxipng-bin@^9.1.4 npm 包版本不存在，已修正为 oxipng-bin@^1.0.0；该问题不是 npm 本地缓存导致。
• 2026-05-10 15:50 CST：修正版本后再次使用 npm install --registry=https://registry.npmmirror.com，命令仍在 5 分钟后超时，且未生成 package-lock.json 或 node_modules。
• 2026-05-10 15:55 CST：新增项目级 .npmrc，默认使用 npmmirror 镜像源并延长 npm fetch 超时与重试配置，避免修改用户全局 npm 配置。
• 2026-05-10 16:10 CST：用户已成功完成 npm install 并验证 npm 缓存；生成 node_modules 与 package-lock.json。npm run typecheck、npm test、npm run build 均通过。API 监听层同进程自请求返回 200 {"ok":true}；浏览器插件连接超时，未完成截图验证。
• 2026-05-10 16:40 CST：定位上传 JPG 时 Failed to fetch 的主要原因：API 固定监听 4000 且端口占用时退出，前端仍代理到失效的 127.0.0.1:4000。新增根级开发启动器自动选择可用 API/Web 端口并同步 Vite 代理目标；API 监听错误改为清晰日志；前端网络失败提示改为“后端服务未连接或端口代理失败”。
• 2026-05-10 16:55 CST：完成验证：npm run typecheck、npm test、npm run build 均通过；npm run dev 在当前端口占用环境下自动选择 API 4001 与 Web 5175 并启动成功；使用临时端口 4100/5273 验证 Web /api/health 代理返回成功。images_raw 当前未列出可用样例，压缩上传覆盖沿用测试动态生成的 JPG/PNG。浏览器插件连接阶段仍超时，未完成截图验证。
• 2026-05-10 17:15 CST：根据 images_raw/001.jpg、002.jpg、003.png 实测优化压缩策略。修复 002.jpg 因 EXIF Orientation 被 jpegtran -copy none 剥离而触发 pixel-verification-failed 的问题：JPEG 无损流程先尝试剥元数据，若像素校验失败则自动改用保留元数据的无损输出。新增用户显式选择的 target-size 模式，JPG 使用 Sharp 重编码到 1MB 内并标记 sharp-jpeg、verification=not-run；默认仍为无损模式。实测结果：001.jpg 无损 3,830,513→3,405,029 字节，1MB 模式 1,047,871 字节；002.jpg 无损 3,060,895→2,878,061 字节且校验通过，1MB 模式 986,691 字节；003.png 无损 505,574→377,863 字节。npm run typecheck、npm test、npm run build 均通过；浏览器插件连接仍在握手阶段超时，未完成截图验证。
• 2026-05-10 17:30 CST：初始化 Git 版本管理准备工作：完善 .gitignore，排除依赖目录、构建产物、测试覆盖率、Vite 缓存、日志、环境密钥与临时文件；新增 .gitattributes 统一文本行尾并将图片样例标记为二进制；保留源码、npm 锁文件、项目配置与当前验证用样例图，确保首个提交内容可复现且不包含本地运行产物。
• 2026-05-10 17:35 CST：完成 Git 仓库初始化，主分支设为 main；已创建初始项目快照提交，并额外记录版本管理状态，当前版本库排除了依赖、构建产物和运行日志。
• 2026-05-10 17:45 CST：准备发布到 GitHub 时确认本地工作区干净且暂无 origin 远程；当前环境未安装 GitHub CLI gh，现有 GitHub 连接器不提供创建远程仓库并执行 git push 的完整能力，因此 GitHub 发布暂时阻塞，需先安装并登录 gh 或提供已创建的远程仓库地址。
• 2026-05-10 17:55 CST：已将 Git 远程 origin 配置为 https://github.com/wtwtmy/images-press-app-web.git；两次尝试 git push -u origin main 均因当前环境无法连接 GitHub 443 端口失败（一次连接重置、一次连接超时），本地仓库仍保持完整提交状态，待网络恢复后可直接重试推送。
• 2026-05-10 18:05 CST：用户已在本地终端完成 Git 与 GitHub 关联并成功执行 git push -u origin main；当前本地分支显示 main...origin/main，说明上游跟踪关系已建立。下一步通过 Codex 提交本日志并推送，验证后续由 Codex 直接推送优化代码的能力。
• 2026-05-10 18:10 CST：Codex 已成功创建验证提交 2a83311 docs: record github push verification 并执行 git push 推送到 origin/main，确认后续项目优化提交可由 Codex 在已授权网络环境下直接推送到 GitHub。

7. 注意事项

• 必须保证无损：通过解码后像素对比或校验哈希值来验证。
• 注意大文件处理，界面需有反馈（进度条/加载状态）。
• 代码中关键部分需有注释。
• 保持依赖最小化，避免过度工程。