Imported from wtwtmy/images-press-app-web (
AGENTS.md). Install upstream withnpx 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 优化。 - 无损校验:使用统一解码流程比较压缩前后像素数据。
- JPG/JPEG 压缩:
- 判断标准:最终选用能实现真正无损且压缩效果好的方案。
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.4npm 包版本不存在,已修正为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在当前端口占用环境下自动选择 API4001与 Web5175并启动成功;使用临时端口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 CLIgh,现有 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. 注意事项
- 必须保证无损:通过解码后像素对比或校验哈希值来验证。
- 注意大文件处理,界面需有反馈(进度条/加载状态)。
- 代码中关键部分需有注释。
- 保持依赖最小化,避免过度工程。
