# AutoDoubao

让 Codex、Hermes Agent 和 LobsterAI 自动调用已登录的豆包网页生图，并把豆包返回的原图下载到本地。

AutoDoubao 是一个 Windows 本地 MCP 桥接服务：Agent 负责提示词和图片验收，豆包网页负责实际生图，Chrome 扩展负责可靠提交和捕获原图，MCP 服务负责任务队列、下载和文件交付。

它不调用火山方舟付费生图 API，不读取账号密码，不绕过豆包登录、验证码、安全验证或免费额度限制。

## 项目特点

- 一套 MCP 服务同时供 Codex、Hermes Agent、LobsterAI 使用。
- 支持 Streamable HTTP；旧版 Hermes 也支持 stdio 兼容代理。
- 复用用户已经登录的豆包网页和网页免费额度，不需要购买图像 API。
- 自动填写并提交提示词，检测“文字写入但没有发送”的情况并重试。
- 监听豆包生成响应中的 `image_ori_raw` / `image_raw`，下载真实原图。
- 不从页面 `<img>` 的 `src` 或 `srcset` 猜原图，避免拿到 384×216 缩略图。
- SQLite 持久化任务状态，三个客户端共用单任务浏览器锁。
- 提供可迁移的 Windows ZIP 发行包，不携带 Token、Cookie、数据库或生成图片。

## 项目简介

```text
Codex / Hermes / LobsterAI
              |
              v
   Streamable HTTP MCP :8878
              |
       SQLite 单任务队列
              |
       WebSocket 桥接 :8879
              |
       Chrome 扩展 0.2.0
          |             |
          v             v
     提交提示词     监听豆包生成响应
                        |
                        v
              image_ori_raw / image_raw
                        |
                        v
                 下载原图到本地
```

豆包页面上的 `<img width="2848" height="1600">` 可能仍然指向 384×216 的展示缩略图。AutoDoubao 读取的是生成接口返回的原图字段，而不是页面展示地址，这是项目稳定工作的关键。

## Architecture

```text
Codex -----------\
LobsterAI --------+--> Streamable HTTP MCP (127.0.0.1:8878)
Hermes --> stdio proxy -----------/                 |
                                  +--> SQLite single-job queue
                                  |
Dedicated Chrome profile --> Doubao-scoped extension --> Doubao web UI
```

## What is included

- One shared MCP service; HTTP for Codex/LobsterAI and an stdio compatibility
  proxy for older Hermes installations.
- Persistent SQLite jobs and a single browser-work lock.
- A generated token for the extension-to-service WebSocket.
- A Chrome Manifest V3 extension that temporarily attaches the debugger Network
  domain to the selected Doubao tab while a job is active. It extracts the
  original `image_ori_raw` / `image_raw` URL from the generation response.
- Safe output subdirectories below one configured root.
- Terminal handling for login, captcha, account verification, quota, and rate limits.
- Client configuration examples and Windows setup/start scripts.

## Initial setup on Windows

1. Install Python 3.11+ and `uv` if they are not already available.
2. Run:

   ```powershell
   powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
   ```

3. Create a dedicated Chrome profile for AutoDoubao.
4. In that profile, open `chrome://extensions`, enable Developer mode, choose
   **Load unpacked**, and select this repository's `extension` directory.
5. The options page opens. Paste the token printed by the setup script and save.
6. Open `https://www.doubao.com/chat/` and sign in manually.
7. Start the service:

   ```powershell
   powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1
   ```

   Or keep it running in a hidden background process:

   ```powershell
   powershell -ExecutionPolicy Bypass -File .\scripts\start-background.ps1
   # Later: powershell -ExecutionPolicy Bypass -File .\scripts\stop-background.ps1
   ```

8. Configure clients using [docs/CLIENTS.md](docs/CLIENTS.md).

## MCP tools

- `doubao_status`: service, extension, page, queue, and output status.
- `doubao_generate`: queue one prompt and return a job ID.
- `doubao_job_status`: poll status and retrieve downloaded paths.
- `doubao_cancel`: cancel a job owned by the calling agent.
- `doubao_list_jobs`: list recent jobs without returning prompt text.
- `doubao_usage`: local job/image counts; it never guesses remaining free quota.
- `doubao_setup_guide`: setup instructions available to every MCP client.

Example agent sequence:

```text
doubao_status()
doubao_generate(prompt="...", ratio="1:1", candidate_count=2,
                output_subdir="my-game/icons", agent_id="codex")
doubao_job_status(job_id="job_...")
```

## Configuration

Copy `config.example.yaml` to `config.yaml`. Important settings:

- `output_root`: every generated image is copied below this directory.
- `max_candidates_per_job`: maximum requested results per job.
- `max_jobs_per_hour`: local safety limit shared by all agents.
- `job_timeout_seconds`: upper bound for one browser job.

The generated extension token is stored in `data/extension-token.txt`. Do not
commit `config.yaml`, `data/`, downloaded output, or the token.

## Browser integration

Prompt submission is isolated in `extension/content.js`. Image acquisition does
not scrape the rendered `<img>` element because Doubao can display a small preview
behind large DOM width/height attributes. `extension/background.js` listens to the
generation response and downloads the original URL returned by Doubao. Chrome may
show a debugging notification while a job is running; the extension detaches when
the job completes, fails, times out, or is cancelled.

See [docs/SECURITY.md](docs/SECURITY.md) before enabling the extension.

For the complete Chinese design record, failed-version retrospective, pitfalls,
three-client configuration, and copy-ready agent prompts, see
[docs/AUTODOUBAO_IMPLEMENTATION_ZH.md](docs/AUTODOUBAO_IMPLEMENTATION_ZH.md).

To build or install the portable Windows MCP bundle for another machine, see
[docs/PORTABLE_PACKAGE_ZH.md](docs/PORTABLE_PACKAGE_ZH.md).