# drawthings_app
**Repository Path**: jinpeng0804/drawthings_app
## Basic Information
- **Project Name**: drawthings_app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 绘境 · DrawThings
**Draw Things HTTP API 的 Flutter 客户端 —— 文生图 / 图生图，覆盖全部 81 个参数**
---
> 一句话：一个美观、开箱即用、覆盖 Draw Things HTTP Server 全部能力的跨端 APP（安卓 + 鸿蒙）。
> 服务端兼容 Automatic1111 (A1111) Stable Diffusion WebUI API 的一个**子集**——只实现了 `txt2img` / `img2img` 两个生成端点 + `GET /` 查询端点，并遵守其**严格字段校验**。
## 📖 目录
- [✨ 功能特性](#-功能特性)
- [🖼️ 界面预览](#️-界面预览)
- [🧱 技术栈](#-技术栈)
- [📁 工程结构](#-工程结构)
- [✅ 环境要求](#-环境要求)
- [🚀 快速开始](#-快速开始)
- [⚙️ 配置与推荐默认值](#️-配置与推荐默认值)
- [🧩 API 参数覆盖（共 81 个）](#-api-参数覆盖共-81-个)
- [📦 构建发布](#-构建发布)
- [⚠️ 注意事项与已知坑](#️-注意事项与已知坑)
- [🗺️ 路线图](#️-路线图)
- [📄 许可证](#-许可证)
---
## ✨ 功能特性
- **双模式**：文生图（txt2img）/ 图生图（img2img）一键切换
- 图生图自动读取输入图真实尺寸并填入宽高，避免 `init_images` 尺寸不匹配报错；改尺寸时自动缩放输入图
- **全参数覆盖**：主界面放核心参数，**增强设置**页用「声明式 schema」覆盖剩余全部参数（按 12 个分类折叠，勾选才发送，杜绝 422）
- **LoRA / ControlNet 列表编辑器**：可视化增删改，权重滑块即时调节
- **严格校验安全**：只发送「有意义的字段」（非空、勾选、布尔为 true），其余用服务端默认 → 永不触发 `422 Unrecognized keys`
- **可靠性**（依据 API 手册 §8）：每次请求前 `GET /` 预热、`Connection: close` 短连接、指数退避重试（仅网络错误）、600s 超时、422 不重试并显示具体原因
- **历史画廊**：生成结果自动落盘，全屏预览（缩放 / 保存到相册 / 分享 / 复用参数 / 复制种子）
- **Material 3 深色主题**：渐变品牌色、圆角卡片、流畅动效；可切换深 / 浅色
- **设置持久化**：服务端地址、超时、重试、主题、上次配置全部本地保存，开箱即用
## 🖼️ 界面预览
| 创作（文生图） | 增强设置（schema 驱动） | 历史画廊 |
|:---:|:---:|:---:|
| 生成按钮 + 结果置顶，下方为提示词与参数 | 12 类参数折叠，勾选即发送 | 缩略图网格，长按复用参数 |
| 负向提示词默认展开，3 个清空按钮 | LoRA / ControlNet 可视化编辑 | 全屏查看 / 保存 / 分享 |
> 主色为紫蓝渐变（`#8B5CF6 → #6366F1 → #22D3EE`），暗色背景 `#0F0F14`。
## 🧱 技术栈
| 层 | 选型 |
|----|------|
| 框架 | Flutter（Android 用官方 3.44；鸿蒙用 OpenHarmony-SIG 移植版 3.35.7）|
| 语言 | Dart 3.9+ |
| 状态管理 | `provider`（纯 Dart，跨端友好）|
| 网络 | `dio`（纯 Dart；预热 + 重试 + 422 处理）|
| 图像 | `image`（isolate 内读尺寸 / 缩放）、`photo_view`（缩放预览）|
| 平台插件 | `image_picker`、`shared_preferences`、`path_provider`、`saver_gallery`（相册）、`share_plus`（分享）|
| 设计 | Material 3，自定义主题 |
> 跨端原则：核心逻辑全为纯 Dart；相册保存等平台能力做了单一可替换封装，便于鸿蒙后续替换。
## 📁 工程结构
```
drawthings_app/
├── lib/
│ ├── main.dart # 入口、主题、Provider 装配
│ ├── main_scaffold.dart # 底部导航（创作 / 历史 / 设置）
│ ├── config/defaults.dart # 推荐默认值、预设、服务端默认快照
│ ├── models/
│ │ ├── generation_config.dart # 生成配置（核心+高级+LoRA/Control），严格校验安全序列化
│ │ ├── param_schema.dart # 增强参数的声明式 schema（驱动 UI）
│ │ ├── enums.dart # sampler(20) / seed_mode(4) / compression(4) 等
│ │ ├── lora.dart control.dart # LoRA / ControlNet 结构与可观察列表
│ │ ├── app_settings.dart # 服务端 / 超时 / 重试 / 主题
│ │ └── generation_result.dart # 结果与历史记录
│ ├── services/
│ │ ├── draw_things_api.dart # dio 客户端：预热 + 重试 + 422 + 取消
│ │ ├── image_utils.dart # isolate 读尺寸 / 缩放（图生图尺寸匹配）
│ │ └── storage_service.dart # 设置/配置/历史持久化 + 相册保存
│ ├── state/ # settings / generation / history 三个 Provider
│ ├── screens/ # generate / enhanced_settings / history / settings / result_viewer
│ ├── widgets/ # common（渐变按钮/卡片/滑块）param_field init_image_picker
│ └── theme/app_theme.dart
├── android/ # Android 平台（Kotlin，已配 release）
├── ohos/ # 鸿蒙平台（ArkTS/ets，工程已生成）
├── pubspec.yaml
└── README.md
```
## ✅ 环境要求
**通用**
- Flutter SDK（见下「快速开始」分端说明）
- 连接到一台运行中的 Draw Things HTTP Server（默认 `http://100.111.39.111:7860`，可在 APP 内改）
**Android 构建**
- Flutter 3.44+（Dart 3.9+）
- Android SDK：`compileSdk 36`、Build-Tools `36.1.0`、NDK `28.2.13676358`
- JDK 17
**鸿蒙构建**
- OpenHarmony-SIG 的 Flutter 移植版（分支 `oh-3.35.7-release`）
- DevEco Studio 6.x + HarmonyOS SDK（API 22）
- AGC 调试签名（华为账号）—— 见 [构建发布](#-构建发布)
## 🚀 快速开始
### 1. 克隆
```bash
git clone git@gitee.com:jinpeng0804/drawthings_app.git
cd drawthings_app
```
### 2. 安装依赖
```bash
flutter pub get
```
> 若处于国内网络环境，建议配置镜像：
> ```bash
> export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
> export PUB_HOSTED_URL=https://pub.flutter-io.cn
> ```
### 3. 运行（Android）
```bash
flutter run # 连接安卓真机/模拟器
```
首次启动在「设置」页填入你的 Draw Things 服务端地址（或保持默认），点顶部状态测试连通即可出图。
## ⚙️ 配置与推荐默认值
开箱即用——以下为 APP 预填的推荐值（均可在界面修改；「高级」项留空即用服务端默认，仅勾选才发送）：
| 参数 | 推荐值 | 说明 |
|------|--------|------|
| 宽 × 高 | **1024 × 1024** | SDXL 原生，与服务端一致 |
| 步数 steps | **25** | 推荐 20–30（服务端默认 16） |
| 引导度 guidance (CFG) | **7.0** | 常用 4–8（服务端默认 5） |
| 采样器 sampler | **DPM++ 2M AYS** | 与服务端一致，通用首选 |
| 种子 seed | **-1（随机）** | 固定可复现 |
| 种子模式 seed_mode | **Scale Alike** | 与服务端一致 |
| 模型 model | **留空** | 用服务端当前模型 |
| 负向提示词 | **留空** | 提供「通用/写实人像/动漫/场景」预设一键填 |
| 批次 / 每批 | **1 / 1** | |
| 重绘强度 strength（图生图）| **0.7** | 0.3–0.5 轻改 / 0.6–0.75 中 / 0.8–1 重绘 |
| 面部修复 restore_faces | **关** | ⚠️ 见注意事项 |
| 高级参数（66+）| **默认不发送** | 用服务端默认；勾选某项才发送其推荐值 |
| 网络：超时 / 预热超时 / 重试 / 短连接 | **600s / 20s / 4 次 / 开** | 依据 API 手册 §8 |
## 🧩 API 参数覆盖（共 81 个）
完整对齐 Draw Things HTTP API 全部参数，分组在「增强设置」页：
`基础核心` · `图生图高级` · `采样质量/风格` · `SDXL/高分辨率` · `文本编码器分离` · `视频(SVD)` · `分块解码/扩散` · `Flux/SD3调度` · `加速(TeaCache/Causal)` · `放大/画质` · `LoRA` · `ControlNet` · `restore_faces`
枚举精确匹配（大小写敏感）：`sampler`（20 个）、`seed_mode`（4 个）、`compression_artifacts`（4 个）、LoRA mode、ControlNet importance。
## 📦 构建发布
### Android（release APK）
```bash
flutter build apk --release
# 产物：build/app/outputs/flutter-apk/app-release.apk
```
> 默认用 debug 签名打包 release。如需上架，请配置自己的签名 keystore。
### HarmonyOS（hap）
鸿蒙 hap 需 OpenHarmony-SIG 的 Flutter 移植版，且**调试 / 发布签名必须由华为 AGC（华为账号）签发**：
1. 用 [openharmony-sig/flutter_flutter](https://gitcode.com/openharmony-sig/flutter_flutter)（分支 `oh-3.35.7-release`）替换标准 Flutter；
2. DevEco Studio 打开 `ohos/` → `File → Project Structure → Signing Configs` → 勾选 **Automatically generate signature**；
3. `flutter build hap --release`（用鸿蒙版 Flutter）。
> 详细鸿蒙构建注意事项见 [⚠️ 注意事项](#️-注意事项与已知坑)。
## ⚠️ 注意事项与已知坑
- **`restore_faces` 默认关闭**：Draw Things 服务端在 `restore_faces=true` 时会执行一句未做空判断的 `availableSpecifications[0]`（HTTPAPIServer.swift），当服务端无对应配置时**数组越界导致服务端崩溃**。APP 因此默认不发送该字段；如确需面部修复，请先确认服务端不会因此崩溃再手动开启。
- **严格字段校验**：服务端对未知字段会返回 `422`。本 APP 只发送手册列出的字段，且高级参数需勾选才发送，避免报错。
- **服务端串行**：Draw Things 一次只处理一个生成任务；请勿并发轰炸（APP 已禁用生成期间的按钮 + 实现重试退避）。
- **Windows 工程路径**：须放在**纯 ASCII 路径**下（如 `C:\drawthings_app`），否则 Dart AOT（`gen_snapshot`）会因中文路径乱码失败。
- **鸿蒙签名不可纯命令行完成**：`hap` 的 profile 必须由 AGC 签发（含开发者 ID、注册设备 UDID、华为可信证书链），自签名 profile 无法装机。详见鸿蒙构建步骤。
- **国内网络**：Flutter/Dart 引擎、pub 包、Gradle、NDK 等若直连受限，请使用对应国内镜像（pub/引擎见上；Gradle 用阿里云、NDK/平台用腾讯云镜像）。
## 🗺️ 路线图
- [x] 安卓 release APK
- [x] 鸿蒙工程与构建流水线（签名待 AGC）
- [ ] 鸿蒙端原生插件适配（相册保存 / 选图 / 分享 的 OHOS 实现）
- [ ] 生成进度反馈（服务端无 progress 端点，暂用计时器）
- [ ] 批量任务队列 UI
## 📄 许可证
MIT License —— 详见 [LICENSE](LICENSE)。
---
基于 [Draw Things](https://drawthings.ai) HTTP API 构建 · 服务端兼容 A1111 API 子集