mjpic 1.0.0

package/.trae/documents/mjpic-prd.md

@@ -0,0 +1,111 @@
+## 1. 产品概述
+
+mjpic（敏捷图片）是一个网页版图片处理工具，通过npm包形式分发，用户可通过命令行安装并在本地启动web服务进行图片处理。主要解决用户在不同操作系统上快速进行图片基础编辑的需求，无需安装复杂的桌面软件。
+
+目标用户：需要在本地进行简单图片处理的设计师、开发者、普通用户。产品定位为轻量级、跨平台的图片处理解决方案。
+
+## 2. 核心功能
+
+### 2.1 用户角色
+
+本产品为单用户本地应用，无需用户注册和登录系统。
+
+### 2.2 功能模块
+
+mjpic包含以下核心页面：
+
+1. **主编辑页面**：图片显示区域、工具栏、文件操作菜单
+2. **文件选择页面**：本地文件选择器（系统原生）
+
+### 2.3 页面详情
+
+| 页面名称  | 模块名称    | 功能描述                                      |
+| ----- | ------- | ----------------------------------------- |
+| 主编辑页面 | 图片显示区   | 加载并显示jpg、png、webp格式图片，支持拖拽打开文件            |
+| 主编辑页面 | 图像增强工具栏 | 自动美化、一键补光、自动白平衡                           |
+| 主编辑页面 | 手动调整工具栏 | 亮度、对比度、饱和度、清晰度调节滑块                        |
+| 主编辑页面 | 尺寸设置工具  | 预设尺寸（3840px、850px、600px、450px），保持比例自动调节高度 |
+| 主编辑页面 | 裁剪工具    | 预设比例裁剪（1:1、3:2、4:3、9:16、16:9）             |
+| 主编辑页面 | 旋转工具    | 左/右旋转、精细旋转（±0.5度）、拉水平线校正                  |
+| 主编辑页面 | 边框工具    | 添加简单边框、纹理边框，支持边框宽度和颜色调整                   |
+| 主编辑页面 | 基础工具栏   | 放大、缩小、移动、撤销、重做                            |
+| 主编辑页面 | 文件菜单    | 打开文件、保存（覆盖原文件）、另存为（选择新路径）                 |
+| 主编辑页面 | 状态栏     | 显示当前图片尺寸、缩放比例、文件路径                        |
+
+## 3. 核心流程
+
+用户操作流程：
+
+1. 命令行启动：用户通过`mjpic`命令启动本地web服务
+2. 打开图片：通过文件选择器或拖拽方式打开本地图片文件
+3. 图像增强：使用一键自动美化、补光、白平衡等智能功能
+4. 手动调整：通过滑块调节亮度、对比度、饱和度、清晰度
+5. 尺寸设置：选择预设尺寸或自定义尺寸，保持比例调整
+6. 裁剪操作：选择预设比例进行精确裁剪
+7. 旋转校正：使用快速旋转或精细旋转，支持拉水平线校正
+8. 边框添加：选择边框样式、宽度和颜色
+9. 保存输出：选择保存覆盖原文件或另存为新文件
+
+```mermaid
+graph TD
+    A[命令行启动 mjpic] --> B[浏览器打开主编辑页面]
+    B --> C[选择或拖拽打开图片]
+    C --> D[图片显示在编辑区]
+    D --> E{选择编辑功能}
+    E --> F[图像增强: 自动美化/补光/白平衡]
+    E --> G[手动调整: 亮度/对比度/饱和度/清晰度]
+    E --> H[尺寸设置: 预设尺寸/保持比例]
+    E --> I[裁剪: 预设比例裁剪]
+    E --> J[旋转: 快速/精细/水平校正]
+    E --> K[边框: 样式/宽度/颜色]
+    F --> L[实时预览效果]
+    G --> L
+    H --> L
+    I --> L
+    J --> L
+    K --> L
+    L --> M[保存或另存为]
+    M --> N[覆盖原文件或保存新文件]
+```
+
+## 4. 用户界面设计
+
+### 4.1 设计风格
+
+* **主色调**：深灰色（#2D3748）为主背景，蓝色（#3182CE）为强调色
+
+* **按钮样式**：扁平化设计，圆角矩形，hover状态有明显颜色变化
+
+* **字体**：系统默认字体，主要文字14-16px，标题18-24px
+
+* **布局风格**：左侧工具栏+中央图片编辑区+顶部菜单栏的经典布局
+
+* **图标风格**：简洁的线性图标，使用开源图标库
+
+### 4.2 页面设计概述
+
+| 页面名称  | 模块名称    | UI元素                                                             |
+| ----- | ------- | ---------------------------------------------------------------- |
+| 主编辑页面 | 顶部菜单栏   | 文件菜单（打开、保存、另存为）、编辑菜单（撤销、重做）、视图选项，深色背景，高度48px                     |
+| 主编辑页面 | 左侧工具栏   | 分组图标按钮：增强（魔法棒）、调整（滑块）、尺寸（标尺）、裁剪（虚线框）、旋转（箭头）、边框（方形），宽度60px，图标28px |
+| 主编辑页面 | 右侧调整面板  | 根据选中工具显示对应控制面板：滑块控件、预设按钮、数值输入框，宽度280px                           |
+| 主编辑页面 | 中央编辑区   | 画布区域显示图片，支持拖拽、缩放操作，背景为棋盘格透明背景，显示网格线辅助线                           |
+| 主编辑页面 | 底部状态栏   | 显示图片信息（尺寸、格式、缩放比例、当前操作），高度28px，文字12px                            |
+| 主编辑页面 | 顶部快捷工具栏 | 常用操作按钮：自动美化、撤销、重做、放大、缩小，高度36px                                   |
+
+### 4.3 响应式设计
+
+桌面优先设计，主要适配1024x768及以上分辨率。支持窗口大小调整时图片编辑区域自动适配。
+
+### 4.4 性能要求
+
+* 图片加载：单张图片加载时间不超过2秒（10MB以内文件）
+
+* 编辑操作：实时预览，响应时间不超过100ms（基础调整），复杂算法不超过500ms
+
+* 内存占用：处理单张图片时内存占用不超过500MB
+
+* 批量处理：支持撤销/重做栈深度不少于20步
+
+* 算法性能：自动美化等复杂算法采用Web Worker异步处理
+

package/.trae/documents/mjpic-technical-architecture.md

@@ -0,0 +1,234 @@
+## 1. 架构设计
+
+```mermaid
+graph TD
+    A[用户命令行] --> B[Node.js CLI服务]
+    B --> C[静态文件服务器]
+    C --> D[React前端应用]
+    D --> E[Canvas API]
+    E --> F[本地文件系统]
+    
+    subgraph "CLI层"
+        B
+    end
+    
+    subgraph "服务层"
+        C
+    end
+    
+    subgraph "前端层"
+        D
+        E
+    end
+    
+    subgraph "数据层"
+        F
+    end
+```
+
+## 2. 技术描述
+
+* **前端**: React\@18 + TypeScript + Vite + TailwindCSS
+  - **Canvas操作库**: konva.js\@9 或 fabric.js\@5（用于复杂图像变换）
+  - **图像算法库**: 
+    - canvas-filters\@1（图像滤镜算法）
+    - color-blend\@3（颜色空间转换）
+    - histogram-js\@1（直方图分析）
+
+* **初始化工具**: vite-init
+
+* **后端**: Node.js\@18 + Commander.js（CLI工具）
+
+* **图片处理**: Canvas API（浏览器端）+ Sharp（Node.js端，可选）+ 自定义图像算法
+  - 图像增强：自动色阶算法、直方图均衡化
+  - 一键补光：伽马校正+阴影高光恢复
+  - 自动白平衡：灰度世界算法+色温估计
+  - 清晰度调节：USM锐化算法（Unsharp Mask）
+  - 尺寸调整：Lanczos重采样算法
+  - 旋转校正：霍夫变换检测水平线
+
+* **包管理**: npm包分发，支持全局安装
+
+## 3. 路由定义
+
+| 路由    | 用途               |
+| ----- | ---------------- |
+| /     | 主编辑页面，图片处理主界面    |
+| /open | 文件选择接口，返回选择的图片文件 |
+| /save | 保存文件接口，处理图片保存请求  |
+
+## 4. CLI命令定义
+
+### 4.1 核心命令
+
+启动服务命令
+
+```
+mjpic [options]
+```
+
+参数：
+
+| 参数名称      | 参数类型    | 是否必需  | 描述               |
+| --------- | ------- | ----- | ---------------- |
+| --port    | number  | false | 服务端口，默认3000      |
+| --host    | string  | false | 服务主机，默认localhost |
+| --version | boolean | false | 显示版本号            |
+
+## 5. 服务器架构
+
+```mermaid
+graph TD
+    A[CLI命令解析] --> B[静态文件服务]
+    B --> C[API路由处理]
+    C --> D[文件I/O操作]
+    D --> E[响应返回]
+    
+    subgraph "服务器架构"
+        A
+        B
+        C
+        D
+    end
+```
+
+## 6. 数据模型
+
+### 6.1 图片处理配置模型
+
+```typescript
+interface ImageConfig {
+  rotation: number;        // 旋转角度（支持0.5度精度）
+  scale: number;           // 缩放比例
+  brightness: number;      // 亮度调节（-100到+100）
+  contrast: number;        // 对比度调节（-100到+100）
+  saturation: number;      // 饱和度调节（-100到+100）
+  sharpness: number;       // 清晰度调节（0到100）
+  enhancements: {
+    autoEnhance: boolean;   // 自动美化
+    fillLight: boolean;   // 一键补光
+    autoWhiteBalance: boolean; // 自动白平衡
+  };
+  resize?: {
+    width: number;        // 目标宽度
+    height?: number;      // 目标高度（可选，保持比例时自动计算）
+    maintainAspectRatio: boolean; // 保持宽高比
+  };
+  crop?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    aspectRatio?: string; // 预设比例：'1:1' | '3:2' | '4:3' | '9:16' | '16:9'
+  };
+  border?: {
+    width: number;
+    color: string;
+    style: 'solid' | 'texture';
+  };
+  straighten?: {
+    angle: number;        // 水平校正角度
+    line?: {             // 用户绘制的水平线
+      x1: number;
+      y1: number;
+      x2: number;
+      y2: number;
+    };
+  };
+}
+
+interface ProcessedImage {
+  originalPath: string;
+  currentConfig: ImageConfig;
+  previewData: string;     // base64预览数据
+}
+```
+
+### 6.2 支持的文件格式
+
+* **输入格式**: JPG/JPEG、PNG、WEBP、BMP、GIF（静态）
+
+* **输出格式**: JPG、PNG、WEBP
+
+* **最大文件大小**: 50MB
+
+* **最大图片尺寸**: 8000x8000像素
+
+## 7. 跨平台兼容性
+
+### 7.1 支持的操作系统
+
+* macOS (Intel x86\_64)
+
+* macOS (Apple Silicon)
+
+* Windows (x64)
+
+* Linux (x64, ARM64)
+
+* 银河麒麟 (ARM64架构)
+
+### 7.2 Node.js版本要求
+
+* 最低版本：Node.js 16.0.0
+
+* 推荐版本：Node.js 18.0.0 或更高
+
+### 7.3 原生依赖处理
+
+使用纯JavaScript实现，避免原生C++扩展，确保跨平台兼容性。图片处理主要依赖：
+
+* 前端：Canvas API、原生File API
+
+* 后端：fs模块、path模块（Node.js内置）
+
+## 8. 性能优化
+
+### 8.1 图像处理性能优化
+- **Web Worker**: 复杂图像算法在Web Worker中执行，避免阻塞主线程
+- **Canvas缓存**: 对中间处理结果进行缓存，支持快速撤销/重做
+- **渐进式处理**: 大图片采用分块处理，先显示低分辨率预览
+- **GPU加速**: 使用WebGL进行矩阵运算加速（可选）
+
+### 8.2 算法实现细节
+- **自动美化**: 基于直方图均衡化和自动色阶调整
+- **一键补光**: 使用伽马校正结合阴影/高光恢复算法
+- **自动白平衡**: 灰度世界算法配合色温估计
+- **USM锐化**: Unsharp Mask算法，可调节半径、强度、阈值
+- **水平线检测**: 使用霍夫变换检测直线，支持用户交互绘制
+
+### 8.3 内存管理
+- **图片分块**: 处理大图片时采用分块策略，控制内存使用
+- **对象池**: 重用Canvas对象和ImageData，减少GC压力
+- **及时释放**: 处理完成后及时释放大对象引用
+
+## 9. 构建和打包配置
+
+### 8.1 package.json关键配置
+
+```json
+{
+  "name": "mjpic",
+  "version": "1.0.0",
+  "description": "敏捷图片 - 跨平台图片处理工具",
+  "main": "dist/cli.js",
+  "bin": {
+    "mjpic": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "assets/"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}
+```
+
+### 8.2 构建流程
+
+1. 前端构建：Vite打包React应用为静态文件
+2. CLI构建：TypeScript编译Node.js代码
+3. 资源合并：将静态文件嵌入到CLI包中
+4. 发布：发布到npm registry
+

package/README.md

@@ -0,0 +1,57 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default tseslint.config({
+  extends: [
+    // Remove ...tseslint.configs.recommended and replace with this
+    ...tseslint.configs.recommendedTypeChecked,
+    // Alternatively, use this for stricter rules
+    ...tseslint.configs.strictTypeChecked,
+    // Optionally, add this for stylistic rules
+    ...tseslint.configs.stylisticTypeChecked,
+  ],
+  languageOptions: {
+    // other options...
+    parserOptions: {
+      project: ['./tsconfig.node.json', './tsconfig.app.json'],
+      tsconfigRootDir: import.meta.dirname,
+    },
+  },
+})
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default tseslint.config({
+  extends: [
+    // other configs...
+    // Enable lint rules for React
+    reactX.configs['recommended-typescript'],
+    // Enable lint rules for React DOM
+    reactDom.configs.recommended,
+  ],
+  languageOptions: {
+    // other options...
+    parserOptions: {
+      project: ['./tsconfig.node.json', './tsconfig.app.json'],
+      tsconfigRootDir: import.meta.dirname,
+    },
+  },
+})
+```

package/api/app.ts

@@ -0,0 +1,60 @@
+/**
+ * This is a API server
+ */
+
+import express, {
+  type Request,
+  type Response,
+  type NextFunction,
+} from 'express'
+import cors from 'cors'
+import path from 'path'
+import dotenv from 'dotenv'
+import { fileURLToPath } from 'url'
+import authRoutes from './routes/auth.js'
+import imageRoutes from './routes/image.js'
+
+// for esm mode
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// load env
+dotenv.config()
+
+const app: express.Application = express()
+
+app.use(cors())
+app.use(express.json({ limit: '50mb' }))
+app.use(express.urlencoded({ extended: true, limit: '50mb' }))
+
+/**
+ * API Routes
+ */
+app.use('/api/auth', authRoutes)
+app.use('/api/image', imageRoutes)
+
+/**
+ * health
+ */
+app.use(
+  '/api/health',
+  (req: Request, res: Response, next: NextFunction): void => {
+    res.status(200).json({
+      success: true,
+      message: 'ok',
+    })
+  },
+)
+
+/**
+ * error handler middleware
+ */
+app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
+  res.status(500).json({
+    success: false,
+    error: 'Server internal error',
+  })
+})
+
+export default app
+

package/api/cli.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import express from 'express';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import open from 'open';
+import app from './app.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+program
+  .name('mjpic')
+  .description('Agile Image Processing Tool')
+  .version('1.0.0')
+  .option('-p, --port <number>', 'server port', '3000')
+  .option('--host <string>', 'server host', 'localhost')
+  .argument('[file]', 'image file to open')
+  .action(async (file, options) => {
+    const port = parseInt(options.port, 10);
+    const host = options.host;
+
+    if (file) {
+      const absPath = path.resolve(file);
+      console.log(`Opening file: ${absPath}`);
+      
+      app.get('/api/current-image', (req, res) => {
+        res.json({ path: absPath });
+      });
+
+      app.get('/api/image-content', (req, res) => {
+        res.sendFile(absPath);
+      });
+    }
+
+    // Serve static files
+    // In production (dist), client is in ../client
+    const clientPath = path.join(__dirname, '../client');
+    
+    app.use(express.static(clientPath));
+
+    // API 404 handler - Ensure API requests don't fall through to index.html
+    app.use('/api/*', (req, res) => {
+      res.status(404).json({ success: false, error: 'API not found' });
+    });
+
+    // SPA fallback
+    app.get('*', (req, res) => {
+      res.sendFile(path.join(clientPath, 'index.html'));
+    });
+
+    app.listen(port, host, () => {
+      const url = `http://${host}:${port}`;
+      console.log(`mjpic is running at ${url}`);
+      open(url);
+    });
+  });
+
+program.parse();

package/api/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Vercel deploy entry handler, for serverless deployment, please don't modify this file
+ */
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import app from './app.js';
+
+/**
+ * 404 handler
+ */
+app.use((req, res) => {
+  res.status(404).json({
+    success: false,
+    error: 'API not found',
+  });
+});
+
+export default function handler(req: VercelRequest, res: VercelResponse) {
+  return app(req, res);
+}

package/api/routes/auth.ts

@@ -0,0 +1,33 @@
+/**
+ * This is a user authentication API route demo.
+ * Handle user registration, login, token management, etc.
+ */
+import { Router, type Request, type Response } from 'express'
+
+const router = Router()
+
+/**
+ * User Login
+ * POST /api/auth/register
+ */
+router.post('/register', async (req: Request, res: Response): Promise<void> => {
+  // TODO: Implement register logic
+})
+
+/**
+ * User Login
+ * POST /api/auth/login
+ */
+router.post('/login', async (req: Request, res: Response): Promise<void> => {
+  // TODO: Implement login logic
+})
+
+/**
+ * User Logout
+ * POST /api/auth/logout
+ */
+router.post('/logout', async (req: Request, res: Response): Promise<void> => {
+  // TODO: Implement logout logic
+})
+
+export default router

package/api/routes/image.ts

@@ -0,0 +1,27 @@
+import { Router } from 'express';
+import fs from 'fs/promises';
+import path from 'path';
+
+const router = Router();
+
+router.post('/save', async (req, res) => {
+  try {
+    const { filePath, data } = req.body;
+    if (!filePath || !data) {
+      return res.status(400).json({ success: false, error: 'Missing filePath or data' });
+    }
+
+    // data is data:image/png;base64,....
+    const base64Data = data.replace(/^data:image\/\w+;base64,/, "");
+    const buffer = Buffer.from(base64Data, 'base64');
+
+    await fs.writeFile(filePath, buffer);
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Save error:', error);
+    res.status(500).json({ success: false, error: 'Failed to save file' });
+  }
+});
+
+export default router;

package/api/server.ts

@@ -0,0 +1,45 @@
+/**
+ * local server entry file, for local development
+ */
+import app from './app.js';
+import { type Request, type Response } from 'express';
+
+/**
+ * 404 handler
+ */
+app.use((req: Request, res: Response) => {
+  res.status(404).json({
+    success: false,
+    error: 'API not found',
+  });
+});
+
+/**
+ * start server with port
+ */
+const PORT = process.env.PORT || 3002;
+
+const server = app.listen(PORT, () => {
+  console.log(`Server ready on port ${PORT}`);
+});
+
+/**
+ * close server
+ */
+process.on('SIGTERM', () => {
+  console.log('SIGTERM signal received');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+
+process.on('SIGINT', () => {
+  console.log('SIGINT signal received');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+
+export default app;

package/dist/cli/app.js

@@ -0,0 +1,43 @@
+/**
+ * This is a API server
+ */
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import authRoutes from './routes/auth.js';
+import imageRoutes from './routes/image.js';
+// for esm mode
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// load env
+dotenv.config();
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: '50mb' }));
+app.use(express.urlencoded({ extended: true, limit: '50mb' }));
+/**
+ * API Routes
+ */
+app.use('/api/auth', authRoutes);
+app.use('/api/image', imageRoutes);
+/**
+ * health
+ */
+app.use('/api/health', (req, res, next) => {
+    res.status(200).json({
+        success: true,
+        message: 'ok',
+    });
+});
+/**
+ * error handler middleware
+ */
+app.use((error, req, res, next) => {
+    res.status(500).json({
+        success: false,
+        error: 'Server internal error',
+    });
+});
+export default app;