# Eh-FixelFlow

**Repository Path**: MISSMYSEIF/Eh-FixelFlow

## Basic Information

- **Project Name**: Eh-FixelFlow
- **Description**: Eh-PixelFlow 是一款AI原生、零系统污染、插件化扩展的下一代轻量化创作引擎。它摒弃了传统图像编辑器“工具堆叠+AI插件”的陈旧范式，以“意图驱动、过程可视、跨媒介流转”为核心交互哲学，为独立创作者、AI艺术家及轻量级设计团队提供一套解压即用、卸载无痕、能力无限延伸的创作操作系统。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# PixelFlow

**零污染 · AI 原生图像编辑器**

[![License: MIT](https://img.shields.io/badge/License-MIT-22d3ee.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-a3e635.svg)](docs/getting-started/01-环境准备.md)
[![Stack](https://img.shields.io/badge/stack-Tauri%202%20%2B%20React%2018%20%2B%20Rust-f472b6.svg)](docs/architecture/01-总体架构.md)
[![Database](https://img.shields.io/badge/database-SQLite%20%7C%20MySQL%20%7C%20PostgreSQL-fbbf24.svg)](docs/guides/01-数据库指南.md)
[![Docs](https://img.shields.io/badge/docs-中文%20%2B%20English-818cf8.svg)](docs/README.md)

</div>

---

## 简介

PixelFlow 是一款**零污染**的 AI 原生图像编辑器：所有数据 100% 保存在程序自己的目录里，删除文件夹即完全卸载；所有 AI 流量经 Rust 代理转发，**API Key 永远不出后端进程**。基于 Tauri 2 + React 18 + Rust 构建，核心包体积控制在 50MB 以内。

> **默认管理员账号：`admin` / `admin123`**（首次登录后请立即修改密码）

## 特性

| 特性 | 说明 |
| --- | --- |
| **零污染便携** | 根目录唯一真理，安装版/便携版/开发版行为完全一致，不写任何系统目录 |
| **多数据库** | 默认 SQLite 零配置；一键切换 MySQL / MariaDB / PostgreSQL，业务代码零改动 |
| **本地账户体系** | PBKDF2-SHA256 口令哈希、令牌会话、失败锁定、全量审计事件 |
| **会话门禁** | 除 3 条公开命令外全部要求会话令牌，未登录界面零后端能力 |
| **三轨 AI 接入** | OpenAI 兼容 / Anthropic / 本地 ONNX，内置 10 个服务商模板 |
| **Key 安全** | AES-256-GCM 加密存储，Rust 内动态注入请求头，前端零接触；上游错误体回显凭据时自动脱敏 |
| **Key 保险库** | 可选启用：主密钥由账户口令经 PBKDF2（60 万轮）派生，仅拷走 `config/` 不再能解密 |
| **文件闸门** | SafePathResolver jail 校验：防遍历、防逃逸、防符号链接越界 |
| **可迁移配置** | 模型配置导出/导入（不含任何 Key 材料），换机器不用重填 10 个模板 |
| **可交付作品** | 画布离屏重绘导出 PNG/JPEG/WebP（1x–4x），先落程序目录再可选系统另存 |
| **寄出作品** | 经**本机** SMTP 中继发信，画布当场编码为附件，还可再加本地文件（中文名按 RFC 2231 编码，不会退化成 `attachment.bin`）；凭据只存在于 `config/mail.json`，插件与界面都读不到（[指南](docs/guides/09-邮件中继与消息出入.md)） |
| **流式对话** | 三轨模型统一入口的流式路径（边写边出、可中止、候选失败在首字节前自动降级） |
| **渲染期隔离** | 每个面板独立错误边界：第三方组件抛错只隔离该页签，不会白屏、不影响未保存的画布 |
| **会话存档** | 全量/差量快照、分支、恢复 |
| **三层测试** | Rust 单元 + 前端 vitest + Python 端到端（真实数据） |
| **一键开发** | Windows `start.bat` / `stop.bat`，双击即用 |

## 架构总览

```mermaid
flowchart TB
    subgraph Frontend["前端 React + TypeScript"]
        UI["界面组件"]
        API["lib/api/* 类型安全 IPC 客户端"]
    end
    subgraph Backend["Rust 后端 Tauri 2"]
        CMDS["commands/* 命令层"]
        PATH["SafePathResolver 文件闸门"]
        DB["数据库层<br/>SQLite 默认 · MySQL/PG 可选"]
        AUTH["认证<br/>PBKDF2 + 令牌"]
        PROXY["AI HTTP 代理<br/>同源白名单 + Key 注入"]
        MODELS["模型配置<br/>AES-256-GCM"]
        SESS["会话存档"]
        PLUG["插件 jail"]
        PORTABLE["portable 根目录初始化"]
    end
    UI --> API -->|"invoke"| CMDS
    CMDS --> PATH & DB & AUTH & MODELS & SESS & PLUG
    PROXY -->|HTTPS| CLOUD["OpenAI / Anthropic / SiliconFlow / ..."]
    PORTABLE -.约束全部 IO.-> Backend
```

## 快速开始

### 环境要求

Node.js ≥ 22.22.2 · Rust ≥ 1.80 · Git（详见 [环境准备](docs/getting-started/01-环境准备.md)）

### 安装与启动

```bash
git clone <your-repo-url> pixelflow
cd pixelflow

npm ci                 # 安装前端依赖
npm run tauri dev      # 启动开发环境（首次编译 Rust 需数分钟）
```

启动后在登录界面输入 **`admin` / `admin123`**（首次登录会提示修改初始口令，可跳过）。

### Windows 一键脚本

```bat
start.bat   :: 一键启动（自动检查工具链、安装依赖、固定数据目录）
stop.bat    :: 一键暂停（结束进程树 + 清理端口残留，不删数据）
```

macOS / Linux 用等价的 `npm start` / `npm run stop`（见 [快速开始](docs/getting-started/02-快速开始.md)）。

### 构建与测试

```bash
npm run build          # 前端产物（cargo 编译前必须执行）
npm run build:cross    # 跨平台打包（安装包；NSIS 模板仅 Windows 宿主可产出）
npm run portable       # 制作免安装便携包（zip）
npm run size           # 核心包体积门禁（单产物 ≤ 50MB）

npm test               # 前端测试
PIXELFLOW_TEST_AUTOBUILD=1 pytest tests/ -v   # Python 端到端（真实 SQLite + 自动编译 CLI）

# Rust：清单在 src-tauri/，必须先 npm run build 产出 dist/
cd src-tauri && cargo test --locked
```

> `cargo` 相关命令一律在 `src-tauri/` 下执行。在仓库根直接跑裸 `cargo test`
> 会报 `could not find Cargo.toml`。

**跑一轮完整门禁**（门禁的唯一执行路径；推送不跑流水线，不需要装 Rust / webkit2gtk）：

```bash
./scripts/ci/docker-ci.sh --fast   # 提交前：前端 + Rust + Python 三层
./scripts/ci/docker-ci.sh          # 发版前：再加 release 体积门禁
```

详见 [本地 Docker CI](docs/guides/08-本地-Docker-CI.md)。

## 数据库

默认 SQLite（`<程序根目录>/data/pixelflow.db`），**开箱即用**。切换数据库只需编辑 `config/db.json`：

```json
{ "driver": "postgres", "postgres": { "host": "127.0.0.1", "port": 5432, "database": "pixelflow", "user": "postgres", "password": "***" } }
```

也支持环境变量 `PIXELFLOW_DB_URL` / `PIXELFLOW_DB_DRIVER`（CI/测试场景）。详见 [数据库指南](docs/guides/01-数据库指南.md)。

## 第三方 AI 接入

内置 10 个服务商模板（OpenAI、Anthropic、SiliconFlow、OpenRouter、DeepSeek、Moonshot、智谱 GLM、阿里百炼、火山方舟、Ollama），**不写一行代码即可接入任意 OpenAI 兼容服务**：

```bash
pixelflow-cli models add --id sf --name "SiliconFlow" --track openai_compat \
  --base-url https://api.siliconflow.cn --model-id Qwen/Qwen-Image --api-key sk-xxx
pixelflow-cli models test --id sf     # 真实连通性验证
```

新增服务商、流式调用、本地 ONNX 推理的完整教程见 [第三方 AI 对接开发教程](docs/guides/03-第三方AI对接开发教程.md)。

## 目录结构

```
pixelflow/
├── docs/                   # 文档中心（大厂标准：教程 / 架构 / 指南）
├── scripts/                # 图标生成 / 便携包制作
├── src/                    # React 前端（lib/api 与 Rust 命令一一对应）
├── src-tauri/              # Rust 后端（db / auth / http_proxy / paths / ...）
├── tests/                  # Python 测试体系（真实数据）
├── start.bat / stop.bat    # Windows 一键启动 / 暂停
├── README.md / README.en.md
└── LICENSE                 # MIT
```

## 文档

完整文档（架构、数据库、认证、AI 对接、测试、贡献）见 **[文档中心](docs/README.md)**。
English documentation: [README.en.md](README.en.md)。

## 贡献

欢迎提交 Issue 与 PR！请先阅读 [贡献指南](docs/contributing/01-贡献指南.md)（Conventional Commits + 三层测试全绿）。

## 许可证

[MIT License](LICENSE) © 2026 PixelFlow Contributors