# 豆包生图 MCP（doubao-image-mcp）

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/haikuotianko/doubao-image-mcp)

**官网 / 下载页：<https://haikuotianko.github.io/doubao-image-mcp/>**

把**豆包网页版**（doubao.com）的生图能力封装成本地 MCP 服务：**不需要官方 API Key**，用你自己的网页登录态直接调用，Seedream 4.0 / 4.5 / 5.0 全系可用。附带一个桌面端（Wails + WebView2），负责扫码登录、多账号管理、测试生图与排障。

> Local MCP server that exposes Doubao's web image generation as tools for Claude Desktop / Cursor / any MCP client — no API key, just your own web session.

![界面](docs/screenshot.png)

## 目录

- [它能做什么](#它能做什么)
- [环境要求](#环境要求)
- [下载](#下载)
- [版本与更新检查](#版本与更新检查)
- [安装](#安装)
- [首次使用](#首次使用)
- [接入 MCP 客户端](#接入-mcp-客户端)
- [工具参考](#工具参考)
- [多账号与自动排队](#多账号与自动排队)
- [会话复用与上下文隔离](#会话复用与上下文隔离)
- [数据位置](#数据位置)
- [排障](#排障)
- [已知限制](#已知限制)
- [跨平台说明](#跨平台说明)
- [开发](#开发)

## 它能做什么

MCP 对外提供 6 个工具：

| 工具 | 作用 |
| --- | --- |
| `doubao_image` | 文生图 / 图生图。**一次生成几张就返回几张**：本地文件路径 + CDN 链接 + 尺寸 |
| `doubao_login` | **直接从 AI 客户端弹窗扫码**：没有账号或登录态失效时调它，不用切到 GUI |
| `doubao_models` | 列出可用模型、32 种风格 key、8 种比例 |
| `doubao_ping` | 检查当前账号登录态是否有效（也能发现 IP 风控） |
| `doubao_accounts` | 账号池：列出 / 切换默认 / 启用 / 停用 / 删除，输出带昵称与忙碌状态 |
| `doubao_verify` | 被风控时打开豆包窗口，让你手动拖一次滑块验证 |

`doubao_login` 的关键点：stdio 模式下 MCP 进程同样跑在你的桌面会话里，所以它能直接开一个 WebView2 扫码窗口（最多等 3 分钟，扫完自动保存账号并校验）。**已经有可用账号时不会打扰你**，直接返回「无需登录」。mac / Linux 因为没有内置浏览器，会提示改用 `-set-session`。

几个实现上的点，用起来能感觉到：

- **无水印直链**：从 SSE 里挑 `image_raw` / `dwm3` 模板地址（手工改后缀会 400，签名覆盖整个 path，只能用服务端给的）。
- **多图全量**：服务端一次可能给 1~4 张，全部返回；结构化解析漏掉的图会从原文按图补回。
- **比例修正**：服务端经常忽略请求比例，默认用虚化背景补齐到目标比例（偏差 3% 内不动）。
- **双通道降级**：新端点 `/chat/completion` 失败自动降级到旧的 samantha 通道。

## 环境要求

- **Windows 10 / 11**：完整支持（GUI + 扫码登录），x64 / x86 / ARM64 都有预编译包。
- **macOS / Linux**：有预编译**命令行版**（MCP 功能完整），但没有 GUI、没有内置扫码登录，登录用 `-set-session` 手动导入（见[安装 → 方式三](#方式三macos--linux)）。想要 GUI 就在该平台上自己 `wails build`。
- [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)：仅 Windows 的扫码窗口需要；Win11 自带，Win10 若缺失程序会明确提示。
- 一个豆包账号（免费账号就能用 Seedream 5.0 Flash）。

## 下载

到 [Releases](../../releases/latest) 按你的平台选一个：

| 平台 | 资产 | 形态 |
| --- | --- | --- |
| Windows x64（64 位） | `…-windows-x64.zip` | GUI 完整版 |
| Windows x86（32 位） | `…-windows-x86.zip` | GUI 完整版（老机器） |
| Windows ARM64 | `…-windows-arm64.zip` | GUI 完整版 |
| macOS Apple Silicon | `…-macos-arm64-cli.zip` | 命令行版 |
| macOS Intel | `…-macos-x64-cli.zip` | 命令行版 |
| Linux x64 | `…-linux-x64-cli.zip` | 命令行版 |
| Linux ARM64 | `…-linux-arm64-cli.zip` | 命令行版 |

> **命令行版**包含 `-mcp`（stdio）、`-http`、`-set-session`、`-diagnose`、`-view` 等全部命令，只是没有图形界面。
> 每个包都是「可执行文件 + README + LICENSE」，解压即用。mac/Linux 上首次运行可能需要 `chmod +x doubao-image-mcp`。

## 版本与更新检查

**不需要任何服务器**，直接用 GitHub 的版本管理当更新源。

- GUI 启动时会静默请求一次 GitHub 的最新 Release，发现新版本就在顶部弹一条提示（「去下载」直接开浏览器，「忽略此版本」记在本地，下次发版还会提醒）。
- 界面右上角还有**「检查更新」按钮**：手动查一次，检查期间按钮显示转圈 +「检查中」且不可重复点击，结果直接显示在按钮上（有新版本 / 已是最新 / 检查失败）。
- 命令行也能查：

  ```powershell
  .\doubao-image-mcp.exe -version         # 当前版本
  .\doubao-image-mcp.exe -check-update    # 有没有新版本
  ```

原理就一句话：

```
GET https://api.github.com/repos/haikuotianko/doubao-image-mcp/releases/latest
→ 取 tag_name（如 v1.2.0）与二进制里编译进去的版本号比较
```

细节：

| 事项 | 说明 |
| --- | --- |
| 版本号来源 | 打包时用 `-ldflags "-X doubao-image-mcp/internal/version.Version=v1.2.0"` 注入；`go build` 不注入就是 `dev`，**开发版不提示更新** |
| 限流 | 未认证的 GitHub API 每小时 60 次（按 IP 计），启动查一次完全够用；超了只会「检查失败」，不影响生图 |
| 断网 / 失败 | 只写日志，不弹框打扰；GUI 与 `-mcp` 模式都不受影响 |
| 想自己改成别的更新源 | 改 `internal/update/update.go` 里的 `Repo` 常量，或换成读取仓库内静态 JSON（raw.githubusercontent.com 不限流） |

> 版本号比较规则：按 `主.次.修订` 逐段比数字（`v1.10.0` > `v1.9.0`），同号时正式版高于预发布版（`v1.4.0` > `v1.4.0-beta`）。

## 安装

### 方式一：下载 Release（推荐）

**Windows**：

1. 下载 `…-windows-x64.zip`（ARM 机器选 `windows-arm64`，32 位系统选 `windows-x86`）
2. 解压到任意目录（路径可以含中文和空格）
3. 双击 `doubao-image-mcp.exe`

程序是单文件，不需要安装。配置和账号写在 `%APPDATA%\doubao-image-mcp`，所以移动/改名 exe 不会丢账号。

**macOS / Linux（命令行版）**：

```bash
unzip doubao-image-mcp-v1.4.0-macos-arm64-cli.zip -d doubao-image-mcp
cd doubao-image-mcp && chmod +x doubao-image-mcp
./doubao-image-mcp -set-session "sessionid=…; ttwid=…"   # 整段 Cookie 直接粘，取法见下方
./doubao-image-mcp -mcp        # MCP 客户端拉起时用
```

首次从网上下载的二进制在 macOS 上可能被 Gatekeeper 拦，执行 `xattr -d com.apple.quarantine ./doubao-image-mcp` 即可。

### 方式二：从源码构建

需要 Go 1.22+、Node.js 18+、[Wails CLI](https://wails.io/docs/gettingstarted/installation)：

```powershell
go install github.com/wailsapp/wails/v2/cmd/wails@latest
git clone https://github.com/haikuotianko/doubao-image-mcp.git
cd doubao-image-mcp
wails build          # 产出 build\bin\doubao-image-mcp.exe
```

只改后端时可以 `go build ./...` 快速验证编译。

### 方式三：macOS / Linux

MCP 本体（协议客户端、工具、账号池）是纯 Go，可以直接跑；**缺的只是 Windows 那个内置扫码窗口**，所以登录改成复制一次 Cookie。

```bash
# 需要 Go 1.22+（或者直接用 Release 里的 *-cli 包）
go build -o doubao-image-mcp .

# 1) 把浏览器里的 Cookie 整段粘进来（导入时会校验登录态、抓头像昵称）
./doubao-image-mcp -set-session "sessionid=xxxx; ttwid=yyyy; ..."

# 2) 交给 MCP 客户端
./doubao-image-mcp -mcp
```

#### 怎么取 Cookie（三种都支持，任选一种）

**① 复制整段 Cookie 请求头（最省事，不用自己找 sessionid）**

1. 用浏览器打开 https://www.doubao.com 并登录
2. 按 `F12` 打开开发者工具，切到 **Network / 网络** 面板
3. 刷新页面（`F5`），在请求列表里点任意一条 `doubao.com` 的请求（比如 `chat` 或 `completion`）
4. 右侧找到 **Request Headers / 请求标头** → 复制 `cookie:` 后面那一整行
   （形如 `sessionid=7f3c…; ttwid=1%7C…; s_v_web_id=verify_…; …`）
5. 把整行粘到 `-set-session` 后面：

   ```bash
   ./doubao-image-mcp -set-session "sessionid=7f3c…; ttwid=1%7C…; s_v_web_id=verify_…"
   ```

   带不带 `Cookie:` 前缀都行，多几个无关 cookie 也没关系——程序只认它需要的那些。

**② 直接右键「Copy as cURL」**

在 Network 面板里右键任意请求 → **Copy → Copy as cURL**，把整段命令原样粘进来：

```bash
./doubao-image-mcp -set-session "curl 'https://www.doubao.com/chat/' -H 'cookie: sessionid=7f3c…; ttwid=1%7C…'"
```

程序会自动从 cURL 里把 `cookie` 头抠出来。

**③ 只复制 sessionid（最少信息）**

1. 开发者工具 → **Application / 应用** → 左侧 **Cookies** → `https://www.doubao.com`
2. 找到名为 `sessionid` 的那一行，复制 Value（通常 32 位十六进制）
3. `./doubao-image-mcp -set-session "7f3c0d5e9a2b4c6d8e0f1a2b3c4d5e6f"`

> `sessionid` 是 HttpOnly，浏览器控制台里 `document.cookie` 看不到，必须在 **Application → Cookies** 或 **Network → Request Headers** 里复制。
>
> 想用 GUI 的话，mac/Linux 上编译出的界面里「扫码登录」会变成同一个导入框，粘贴方式和上面一样。

想要 GUI 的话：

```bash
# macOS：需要 Xcode 命令行工具（xcode-select --install）
# Linux：需要 GTK/WebKit2GTK 开发包，例如 Debian/Ubuntu:
#   sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails build
```

mac/Linux 上的 GUI 里，「扫码登录」按钮会换成**手动导入 sessionid** 的输入框，其余功能（账号池、排队、测试生图、大图查看、另存）都一样。

> **未验证**：作者只有 Windows 机器，mac/Linux 只验证到「交叉编译通过」（`GOOS=darwin` / `GOOS=linux go build .` 都能出二进制）。真实运行、GUI 渲染、`open`/`xdg-open` 打开目录需要 macOS / Linux 用户帮忙验证；有问题请开 issue 附上 `-diagnose` 报告。

## 首次使用

1. 打开程序，点账号卡片右上角的 **「扫码登录」**（mac/Linux 是「导入 sessionid」）。
2. 弹出内置浏览器窗口，用豆包 App 扫码，窗口自动关闭。
3. 账号出现在列表里，带**头像 + 昵称**（登录成功后自动抓取）。
4. 在「设置」里选好输出目录（默认 `图片\doubao-image-mcp`）、默认模型/比例/风格。

**加第二个账号**：再点一次「扫码登录」。程序会先清空浏览器里的旧登录态、重新出二维码，并且把已有账号的 `sessionid` 排除在外，所以不会出现「一打开就显示已登录、第二个号扫不进去」的情况。

**排序与默认账号**：账号行可以拖动排序（顺序就是生图优先级）；「设置 → 默认账号」可以指定优先用哪个号，留空则用列表里第一个启用的账号。停用的账号不参与调度，也不会出现在两个账号下拉里。

## 接入 MCP 客户端

客户端配置里的路径**不要手抄**：GUI 的「MCP 服务」卡片会按当前机器的真实位置生成好可直接粘贴的 JSON，`doubao-image-mcp.exe -diagnose` 也会打印同一份。

### 方式一：stdio（推荐，客户端自己拉起进程）

```json
{
  "mcpServers": {
    "doubao": {
      "command": "C:\\Users\\<你>\\Downloads\\doubao-image-mcp.exe",
      "args": ["-mcp"]
    }
  }
}
```

- **Claude Desktop**：改 `%APPDATA%\Claude\claude_desktop_config.json`，重启客户端。
- **Cursor**：`Settings → MCP → Add new MCP server`，选 `command` 类型，命令填 `<路径>\doubao-image-mcp.exe -mcp`。
- **Cherry Studio / 其他**：选「stdio」传输，命令和参数同上。

`-mcp` 模式下日志写到 `%APPDATA%\doubao-image-mcp\mcp.log`，stdout 只走 JSON-RPC，不会污染协议。

### 方式二：本地 HTTP（常驻，多客户端共用）

在 GUI 里点「启动 HTTP」，或命令行：

```powershell
.\doubao-image-mcp.exe -http 127.0.0.1:8770   # 不带地址则用配置里的地址
```

客户端配置：

```json
{
  "mcpServers": {
    "doubao": {
      "type": "http",
      "url": "http://127.0.0.1:8770/mcp"
    }
  }
}
```

> ⚠️ 这个 HTTP 接口**没有鉴权**，等于「谁连上谁就能花你的额度」。默认只绑 `127.0.0.1`，不要改成 `0.0.0.0` 或局域网地址。

### 怎么确认接上了

在客户端里问一句「用 doubao_ping 看看豆包登录态」，返回 `账号 xxx 登录态正常` 就通了。返回「还没有登录任何豆包账号」说明账号不在配置里，回 GUI 扫码即可。

## 工具参考

### `doubao_image` —— 生成图片

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `prompt` | string | ✅ | 画面描述，越具体越好 |
| `ratio` | string | | `1:1` `4:3` `3:4` `16:9` `9:16` `3:2` `2:3` `auto`；留空用配置默认 |
| `model` | string | | `Seedream 5.0 Flash`（免费，推荐）/ `Seedream 4.5` / `Seedream 4.0` / `Seedream 5.0 Pro`（需订阅） |
| `style` | string | | 风格 `option_key`，32 种，用 `doubao_models` 查 |
| `ref_images` | string[] | | 本地绝对路径数组，传了就走**图生图** |
| `out_dir` | string | | 保存目录；留空用配置里的输出目录 |
| `fit_ratio` | bool | | 是否裁剪/补边到请求比例；留空跟随配置（默认开） |
| `timeout_seconds` | int | | 超时秒数，默认 180 |
| `inline` | bool | | 为 true 时把图片本体以 base64 放进 MCP 响应（体积大），默认只给路径/链接 |
| `new_chat` | bool | | 强制新建对话；默认沿用上一次的对话（见[会话复用](#会话复用与上下文隔离)） |
| `chat_id` | string | | 指定会话 id 或对话链接（`https://www.doubao.com/chat/<id>`），在该对话里继续生成 |
| `context_mode` | string | | 上下文隔离：`none` / `always` / `auto`；留空跟随配置 |

返回里除图片外还会带 **`chat_id`** 与 **`chat_url`**：这次生成落在哪个对话，点链接就能在豆包网页版里看到（就是 `https://www.doubao.com/chat/<id>`）。

返回的文本是「共 N 张：」加每张一行路径；结构化输出：

```json
{
  "prompt": "海边日落，电影感",
  "model": "Seedream 5.0 Flash",
  "ratio": "16:9",
  "channel": "ability",
  "notice": "",
  "images": [
    {
      "path": "C:\\Users\\me\\Pictures\\doubao-image-mcp\\doubao_20261106_153012_1.png",
      "url": "https://p3-flow-imagex-sign.byteimg.com/...",
      "width": 2048,
      "height": 2048,
      "format": "png"
    }
  ]
}
```

调用示例（任何 MCP 客户端替我发这个请求）：

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "doubao_image",
    "arguments": {
      "prompt": "赛博朋克风格的重庆夜景，霓虹灯、雨夜、电影感",
      "ratio": "16:9",
      "model": "Seedream 5.0 Flash",
      "style": "image_gen_style_cyberpunk"
    }
  }
}
```

图生图就是多传参考图：

```json
{
  "name": "doubao_image",
  "arguments": {
    "prompt": "把这张照片改成水彩画风格",
    "ref_images": ["C:\\Users\\me\\Pictures\\cat.jpg"],
    "ratio": "1:1"
  }
}
```

对 AI 说话就行，不用手写 JSON：

> 用 doubao_image 画一张「雪山日落，16:9，电影感」
> 用 doubao_image 把这四张图分别改成水彩风格：`C:\pics\1.jpg` …

### `doubao_models` —— 查模型 / 风格 / 比例

无参数。返回：

```json
{
  "models": [{"name": "Seedream 5.0 Flash", "sub": "专业快速（免费，推荐）", "needUpgrade": false}],
  "defaultModel": "Seedream 5.0 Flash",
  "styles": [{"key": "skill_image_styles_film", "name": "电影写真"}],
  "ratios": ["1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "auto"]
}
```

### `doubao_login` —— 直接弹窗扫码

无参数。调用后会在你桌面上弹出豆包登录窗口，用 App 扫码即可；扫完自动保存账号、校验登录态、抓头像昵称。最长等 3 分钟，客户端取消请求时窗口会关闭。

```json
{"name": "doubao_login", "arguments": {}}
```

返回：

```json
{"ok": true, "account": "doubao-1106-165733", "nickname": "hai_lucky", "message": "登录成功，已保存账号 doubao-1106-165733，昵称 hai_lucky"}
```

- 已有可用账号时**不弹窗**，直接返回「已经有可用账号 xxx，无需登录」。
- 非 Windows 平台返回提示：用 `-set-session` 手动导入。
- 也可以直接对 AI 说：「先 doubao_login 登录一下，再画一张…」

### `doubao_ping` —— 检查登录态

无参数。返回 `{ok, account, message}`。风控（`710022002` / `710022004`）和登录失效都在 `message` 里说明。

### `doubao_verify` —— 过滑块验证

无参数。生图报 `710022004`（人机验证）时调用它：会在你桌面上打开一个豆包窗口（已带上当前账号的登录态），你随便发一条消息触发滑块、拖过去、把窗口关掉，再重新调 `doubao_image` 即可。

有图形界面的版本还有按钮入口：设置里的 **「去验证（滑块）」**。

> 验证状态有有效期，且和 IP 绑定；**验证期间以及风控冷却期不要开豆包网页版**——网页版会持续请求同样的接口，相当于一直在续命风控状态，冷却时间会被拉长。

### `doubao_accounts` —— 账号池

| 参数 | 说明 |
| --- | --- |
| `action` | `list`（默认）/ `switch` / `enable` / `disable` / `remove` |
| `name` | `switch`、`enable`、`disable`、`remove` 要操作的账号名 |

返回包含 `active`（默认账号）、`waiting`（排队请求数）和账号列表：

```json
{
  "active": "doubao-1106-152143",
  "waiting": 0,
  "accounts": [
    {"name": "doubao-1106-152143", "nickname": "hai_lucky", "enabled": true, "busy": false, "active": true}
  ]
}
```

## 多账号与自动排队

生图请求（MCP 与 GUI 测试共用同一个池）按下面的规则走：

1. **默认账号优先**，其余按列表顺序，挑一个**空闲**的已启用账号；
2. 每个账号同一时刻只跑一个任务（豆包对并发不友好，容易踩风控）；
3. 全忙就**排队等待**，不会直接失败；排队数显示在顶部徽标和 `doubao_accounts` 的 `waiting` 里；
4. 一个可调度账号都没有时，明确报「没有启用中的账号」。

> 排队只在**同一个进程内**生效。stdio 模式下每个 MCP 客户端会拉起自己的进程，多个客户端之间不共享队列；要严格串行就用 HTTP 模式（一个进程服务所有客户端）。

## 会话复用与上下文隔离

默认**所有生成都放进同一个对话**（可在「设置 → 复用对话」关掉）。这样豆包网页版里不会因为每次生图多出一堆会话，也方便你回头在网页里接着聊。

规则：

1. 第一次生成时把服务端返回的会话 id（`conversation_id`）记到该账号名下；
2. 之后的生成带上它，追加到同一个对话里；
3. **找不到记录、或在这个对话里生成失败** → 自动新建一个对话重发一次，并记下新 id；
4. 每个账号各记各的，换账号就是另一个对话。

因为复用对话意味着新提示词会看到前面的图，所以多了「上下文隔离」三档（设置里可选，也可用 `context_mode` 参数临时覆盖）：

| 模式 | 实际发送的提示词 | 适用 |
| --- | --- | --- |
| `auto`（默认） | 「如果下面的生图请求与之前的内容无关，请忽略上文、只按新提示词生成；如果与之前有关联（同一主体换风格/换角度），可以沿用上文信息：」+ 提示词 | 大多数情况，让模型自己判断 |
| `always` | 「这是一次全新的生图请求，与之前生成的内容没有任何关联。请忽略上面的全部上下文，只根据下面的提示词生成图片：」+ 提示词 | 完全独立的新图 |
| `none` | 提示词原样发送 | 想要连续修改同一张图 |

想手动指定对话，把网页地址直接丢进去就行——`chat_id` 既收纯数字 id，也收 `https://www.doubao.com/chat/<id>` 这样的链接（程序会把 id 取出来）。返回里的 `chat_url` 就是这次落到的对话地址。

> 旧通道（samantha 兜底、图生图）不返回会话 id，这种情况程序会清掉本地记录，下次重新建对话，避免往一个已经不对的对话里发。

## 数据位置

| 内容 | 路径 |
| --- | --- |
| 配置与账号 | `%APPDATA%\doubao-image-mcp\config.json`（**里面有明文 cookie，别外传**） |
| WebView2 登录态 | `%APPDATA%\doubao-image-mcp\webview` |
| 运行日志 | `%APPDATA%\doubao-image-mcp\app.log`（超过 2MB 滚成 `app.log.1`） |
| stdio 日志 | `%APPDATA%\doubao-image-mcp\mcp.log` |
| 默认输出 | `%USERPROFILE%\Pictures\doubao-image-mcp` |

## 排障

### 扫码窗口白屏 / 打不开

登录窗口是原生 WebView2，出问题基本是运行时、代理或网络三类。程序会把这些情况写进窗口和日志：

1. 加载失败时窗口里直接显示原因（连不上服务器 / DNS 失败 / 代理要认证 / 渲染进程崩溃），不再是白屏。
2. 页面「加载成功但整页空白」（老 WebView2 运行时跑不动豆包前端）会被探针识别并提示。
3. 跑一次自检，把报告发回来：

   ```powershell
   .\doubao-image-mcp.exe -diagnose
   ```

   报告落在 `%APPDATA%\doubao-image-mcp\diag-<时间>.txt`，含 Windows 版本、WebView2 运行时版本、配置目录可写性、代理设置、DNS/TCP/HTTPS 连通性，以及按当前机器路径生成好的 stdio 配置。

### 其它命令行开关

```powershell
.\doubao-image-mcp.exe -login                  # 只开登录窗口（日志写 app.log）
.\doubao-image-mcp.exe -login -login-url about:blank   # 换个地址，验证窗口本身是否正常
.\doubao-image-mcp.exe -view                   # 用默认账号的会话开浏览器窗口
.\doubao-image-mcp.exe -diagnose               # 环境自检
.\doubao-image-mcp.exe -version                # 打印当前版本
.\doubao-image-mcp.exe -check-update           # 查 GitHub 上有没有新版本
```

### 生成失败

| 现象 | 原因与处理 |
| --- | --- |
| 「当前账号无该模型的创作额度」 | 免费额度用完了，换模型或换账号 |
| 错误码 `710022002` / `710022004` | IP 级风控。先点「去验证」手动过滑块；不行就等约 30 分钟冷却、换网络（手机热点最快）。**冷却期间别开豆包网页版**，否则会一直触发风控、冷却被无限续期 |
| 图生图返回 `710020702`「系统错误」 | 旧通道脆弱，先用文生图或换账号稍后重试 |
| 返回「没有启用中的账号」 | 账号被停用了，去 GUI 打开开关 |

## 已知限制

- 走的是**网页版接口**，属于逆向实现，没有官方保证；豆包改接口就可能失效。
- 免费账号有额度限制。
- 图生图（`ref_images`）走旧的 samantha 通道，比文生图脆弱。
- 服务端有时忽略请求的比例；默认的 `fit_ratio` 会用虚化背景补齐，关掉就保留原图。
- **仅 Windows**（见下）。

## 跨平台说明

MCP 主体是纯 Go（`internal/doubao` 协议客户端、`internal/mcpserver` 工具定义、`internal/accountpool` 调度、`internal/config` 持久化），因此 **7 个平台的包都是同一份代码编出来的**：

| 目标 | 产物 | 构建方式 |
| --- | --- | --- |
| windows/amd64、windows/386、windows/arm64 | PE（GUI 完整） | `wails build -platform windows/<arch>` |
| darwin/arm64、darwin/amd64 | Mach-O（命令行） | `GOOS=darwin GOARCH=… CGO_ENABLED=0 go build` |
| linux/amd64、linux/arm64 | ELF（命令行） | `GOOS=linux GOARCH=… CGO_ENABLED=0 go build` |

一键打完所有包：

```powershell
powershell -File scripts\build-release.ps1 -Version v1.4.0
```

发版后官网的下载列表要跟着更新（官网读的是仓库里的静态 `docs/latest.json`，不实时查 GitHub API，避免 60 次/小时的限流）：

```powershell
powershell -File scripts\update-latest.ps1            # 取最新 Release
powershell -File scripts\update-latest.ps1 -Tag v1.4.0 # 或指定版本
git add docs/latest.json && git commit -m "docs: 更新 latest.json" && git push
```

**为什么 mac/Linux 没有 GUI 包**：Wails 的图形界面要 cgo（mac 用 WKWebView，Linux 用 WebKitGTK），而 cgo 无法在 Windows 上交叉编译，`wails build -platform darwin/arm64` 会直接告警 `Crosscompiling to Mac not currently supported`。所以这两个平台发的是纯 Go 的命令行版——MCP 功能完整，只是没有窗口。想要 GUI 就在对应平台上跑一次 `wails build`。

平台差异被收敛到三处，都用构建标签分开了：

| 位置 | Windows | macOS / Linux |
| --- | --- | --- |
| `internal/loginwin/window_windows.go` | Win32 窗口 + WebView2，扫码登录 | `stub_other.go`：返回「当前平台没有内置扫码登录」，界面换成手动导入 sessionid |
| `diagnose.go` + `diagnose_windows.go` / `diagnose_other.go` | 读注册表拿系统版本与 IE 代理 | 用 `runtime.GOOS` + 环境变量 |
| `reveal_windows.go` / `reveal_other.go` | `explorer /select` | `open -R`（mac）/ `xdg-open`（Linux） |

**现状**：

- macOS / Linux 上 MCP 功能齐全（生成、多图、账号池、排队、`-set-session` 导入登录态）。
- 没有内置扫码窗口——`sessionid` 是 HttpOnly，只能从浏览器里手动取；这属于「用起来麻烦一点」，不是「不能用」。
- GUI 也能编译（`wails build`），但作者只有 Windows 环境，**GUI 在 mac/Linux 上的实际渲染与交互未经我验证**。如果你跑了，欢迎把结果/截图开 issue 反馈。

想补上原生扫码登录的话，路径是：mac 用 `WKWebView` + `WKHTTPCookieStore` 取 cookie，Linux 用 WebKitGTK 的 `CookieManager`；接口已经按 `Options`/`Window`/`WaitLogin` 抽好，加一个 `window_darwin.go` 即可，不需要动上层。

## 开发

```powershell
wails build        # 产出 build\bin\doubao-image-mcp.exe
wails dev          # 热重载
go build ./...     # 只编译后端
go test ./internal/...   # 账号池 / 配置的单元测试
```

交叉编译自检（不需要 Mac 也能确认平台代码没断）：

```bash
GOOS=darwin  GOARCH=arm64 go build -o /tmp/mac .
GOOS=linux   GOARCH=amd64 go build -o /tmp/linux .
```

代码结构：

```
main.go                  启动模式（GUI / -mcp / -http / -diagnose / -login / -view）
diagnose.go              环境自检报告
app.go                   Wails 绑定：设置、账号、扫码登录、测试生图、图片另存、落盘日志
internal/config          配置与账号持久化（账号池顺序、启用状态、昵称头像）
internal/accountpool     账号调度：按优先级取空闲账号，全忙排队
internal/doubao          豆包协议客户端（SSE 解析、多图归并、图生图、上传、比例修正、资料抓取）
internal/loginwin        原生 Win32 + WebView2 登录窗口（取 HttpOnly cookie、错误页、空白探针）
internal/mcpserver       MCP 工具定义（stdio / streamable HTTP）
internal/update          GitHub Releases 版本检查与版本号比较（不需要自建服务器）
internal/version         构建时用 -ldflags 注入的版本号
frontend/                Vanilla JS + vite
```

调试小技巧：设 `DOUBAO_MCP_DUMP_SSE=<文件路径>` 会把这次生成的原始 SSE 写到该文件，方便服务端改结构时对齐字段。

## 许可证与免责

[MIT](LICENSE)。软件按「现状」提供，不附带任何明示或暗示的担保。

> ⚠️ **非官方项目**：这里调用的是豆包**网页版**接口，属于逆向实现，随时可能因服务端调整而失效。仅供个人学习与自用，请遵守豆包用户协议；请不要用它批量刷额度、对外提供服务或分发他人账号。