# 视觉创作工具

**Repository Path**: wizardWithSword/visioncraft

## Basic Information

- **Project Name**: 视觉创作工具
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VisionCraft

> AI 图片编辑生成 Agent - 基于 ReAct 框架，支持多种生图后端

## 功能特性

- 🤖 **ReAct 驱动** - 模型自主决策，灵活应对各种图片编辑需求
- 🎨 **多后端支持** - OpenAI Dall-E / Gemini 原生 / OpenAI 兼容格式
- 🔧 **预设系统** - 可配置的预设模板，快速处理常见场景
- 📦 **多种调用方式** - Node.js 导入 / HTTP API / CLI
- 🌊 **事件驱动** - 实时进度反馈，流式输出
- 🧠 **会话管理** - 支持多会话，保持上下文

## 安装

```bash
npm install
```

## 配置

复制 `.env.example` 为 `.env` 并配置：

```bash
# LLM 配置（对话/推理）
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

# Vision 配置（识图，可复用 LLM 的配置）
VISION_API_KEY=
VISION_MODEL=gpt-4o

# OpenAI 兼容图片生成
IMAGE_API_KEY=
IMAGE_BASE_URL=https://api.openai.com/v1
IMAGE_MODEL=dall-e-3

# Gemini 生图（可选）
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.0-flash-exp
```

## 使用方式

### 1. Node.js 导入使用

```javascript
const { ImageAgent } = require('visioncraft');

// 初始化 Agent
const agent = new ImageAgent({
  llm: { apiKey: 'your-key', model: 'gpt-4o' },
  agent: { verbose: true }
});

// 监听事件
agent.on('progress', (data) => console.log('进度:', data));
agent.on('image:generated', (data) => console.log('图片生成:', data.url));

// 处理图片
const result = await agent.process({
  images: ['/path/to/image.jpg'],
  request: '把这张照片变成素描风格'
});

console.log(result.text);    // 文字说明
console.log(result.images);  // 图片 URL 数组
```

### 2. HTTP API 服务

```bash
# 启动服务
npm run server

# 或代码中启动
const { VisionCraftServer } = require('visioncraft');
const server = new VisionCraftServer({ port: 3000 });
server.start();
```

**API 端点：**

```bash
# 处理图片
POST /api/process
Content-Type: application/json

{
  "images": ["/path/to/image.jpg"],  // 或 base64
  "request": "素描风格"
}

# SSE 流式响应
POST /api/process?stream=true

# 查看可用后端
GET /api/backends

# 查看会话列表
GET /api/sessions
```

### 3. CLI 交互模式

```bash
npm start

> load d:/photo.jpg 素描风格
> load d:/product.png 换个白色背景
> backends
> quit
```

### 4. 指定生图后端

```javascript
// 单次指定后端
const result = await agent.process({
  images: ['/path/to/image.jpg'],
  request: '创意风格图片',
  options: { backend: 'gemini' }  // 'openai' | 'gemini' | 'auto'
});
```

## 预设系统

预设定义了常见的图片处理模板，位于 `presets/presets.json`：

| 预设 ID | 名称 | 触发词 |
|---------|------|--------|
| `portrait_style` | 人像风格转换 | 素描、油画、漫画 |
| `product_background` | 电商产品背景 | 换背景、产品图 |
| `scene_transfer` | 场景季节转换 | 春天、夏天、雪景 |
| `xiaohongshu` | 小红书笔记风格 | 小红书、种草 |
| `custom` | 自定义编辑 | 编辑、修改 |

### 添加自定义预设

编辑 `presets/presets.json`：

```json
{
  "id": "my_preset",
  "name": "我的预设",
  "description": "预设描述",
  "trigger_keywords": ["触发词1", "触发词2"],
  "prompt_template": "模板内容 {subject} {style}",
  "sub_presets": [
    { "name": "子选项1", "style": "风格描述1" },
    { "name": "子选项2", "style": "风格描述2" }
  ],
  "model": "dall-e-3",
  "image_params": { "size": "1024x1024", "quality": "standard" }
}
```

## 事件机制

```javascript
agent.on('start', (data) => { /* 开始处理 */ });
agent.on('progress', (data) => { /* 进度更新 */ });
agent.on('thought', (data) => { /* 模型思考过程 */ });
agent.on('tool:start', (data) => { /* 工具开始执行 */ });
agent.on('tool:result', (data) => { /* 工具执行结果 */ });
agent.on('image:analyzed', (data) => { /* 图片分析完成 */ });
agent.on('image:generated', (data) => { /* 图片生成完成 */ });
agent.on('complete', (data) => { /* 处理完成 */ });
agent.on('error', (data) => { /* 错误发生 */ });
```

## API 参考

### ImageAgent

```javascript
// 构造函数
new ImageAgent(options)

// options:
{
  llm: { apiKey, baseUrl, model },      // LLM 配置
  vision: { apiKey, baseUrl, model },   // Vision 配置
  image: { backend },                  // 图片后端偏好
  agent: { maxIterations, verbose },   // Agent 配置
  sessionId                             // 固定会话 ID
}

// 方法
agent.process(params)     // 处理图片，返回 Promise
agent.run(userInput)      // 兼容旧接口
agent.destroy()           // 销毁实例，清理资源

// 事件
agent.on(event, callback) // 监听事件
agent.off(event, callback) // 取消监听
```

### process() 参数

```javascript
{
  images: string[],     // 图片路径或 base64
  request: string,       // 用户需求描述
  sessionId?: string,    // 可选的会话 ID
  options?: {            // 可选参数
    backend?: 'openai' | 'gemini' | 'auto'
  }
}
```

### process() 返回值

```javascript
{
  text: string,          // 文字说明
  images: string[],      // 图片 URL 数组
  meta: {               // 元信息
    sessionId: string,
    backends: string[]
  }
}
```

## 支持的模型

### LLM（对话/推理）

| 服务 | baseUrl 示例 | 模型示例 |
|------|-------------|---------|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o`, `gpt-4-turbo` |
| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-max`, `qwen-plus` |
| 硅基流动 | `https://api.siliconflow.cn/v1` | `Qwen/Qwen2-72B-Instruct` |
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Ollama | `http://localhost:11434/v1` | `llama3`, `qwen2` |

### 图片生成

| 服务 | 类型 | 模型示例 |
|------|------|---------|
| OpenAI Dall-E | OpenAI 兼容 | `dall-e-3`, `dall-e-2` |
| Gemini | 原生 API | `gemini-2.0-flash-exp` |
| SiliconFlow | OpenAI 兼容 | 第三方模型 |

## 项目结构

```
visioncraft/
├── index.js              # 主入口，CLI
├── main.js               # 旧版入口（兼容）
├── package.json
├── .env.example
├── config/
│   └── settings.js       # 配置管理
├── core/
│   ├── agent.js          # ReAct Agent
│   ├── vision.js         # 识图
│   ├── imagegen.js       # OpenAI 生图
│   ├── imagegen_gemini.js # Gemini 生图
│   ├── presets.js        # 预设加载
│   ├── llm.js            # LLM 调用
│   ├── memory.js         # 记忆
│   ├── session.js        # 会话管理
│   ├── tools.js          # 工具注册
│   └── index.js          # 统一导出
├── http/
│   └── server.js         # HTTP 服务
└── presets/
    └── presets.json      # 预设配置
```

## License

MIT