@zeppeli777/tools-doubao 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeppeli777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# 豆包生图中转插件（tools-doubao）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Magpie 工具插件：让**任意 Agent** 通过**你自己的豆包账号**（网页版登录态，与豆包桌面端同账号同后端）生成图片。工具经 Magpie 内置 MCP 服务器 `/mcp/magpie/tools` 注册进所有智能体，工具名为 `doubao-image-plugin_generate_image` / `doubao-image-plugin_check_login`。
+
+- **文生图**：prompt + 画幅比例（1:1 / 16:9 / 9:16 / 4:3 / 3:4 / auto）+ 模型档位（免费档 Seedream 5.0 Flash / 4.5 / 4.0）
+- **图生图**：传本地图片路径或图片 URL 作参考图
+- **多账号轮换**：登录失效自动换号；图片自动落盘并返回绝对路径
+
+原理：用豆包网页版的 `sessionid` Cookie 免签名直调豆包内部接口（优先 web `chat_ability` 新协议，失败自动降级旧 `samantha` 客户端通道；图生图固定走 samantha 通道）。逆向接口属个人自用性质，**不稳定且存在账号风控风险**，商用请走[火山引擎官方 API](https://www.volcengine.com/product/doubao)。
+
+## 安装
+
+```sh
+# 方式一：npm（推荐）
+magpie plugin add @zeppeli777/tools-doubao
+
+# 方式二：从 GitHub 本地克隆后文件夹就地加载
+git clone https://github.com/Zeppeli777/doubao-image-plugin.git
+magpie plugin add ./doubao-image-plugin
+
+magpie plugin --json   # 确认加载无 plugin: 错误
+```
+
+装完后**新开的 Agent 会话**才能看到新工具。工具名为 `doubao-image-plugin_generate_image`（npm 包安装时插件 id 取包名，为 `doubao_generate_image`）。
+
+## 登录（获取豆包登录态）
+
+任选其一：
+
+```sh
+magpie plugin login doubao-image-plugin   # 或 npm 安装后的插件 id
+node scripts/login.mjs                    # 本地克隆时；弹出二维码，手机豆包 App 扫码
+```
+
+弹出二维码 → 手机豆包 App 扫码并确认 → 登录态自动写入插件目录 `config.json`。
+
+## 配置凭证（三选一）
+
+1. **扫码登录**（见上节，推荐）
+2. **手动**：复制 `config.example.json` 为 `config.json`，填入 `sessionid`（浏览器登录 doubao.com → F12 → Application → Cookies → `https://www.doubao.com` → 复制 `sessionid`；`ttwid`、`passport_csrf_token` 可选，带上更稳）
+3. **环境变量**：`DOUBAO_ACCOUNTS="主号:sessionid=xxx,ttwid=yyy;小号:sessionid=zzz"`
+
+Cookie 有效期约 30 天，过期后重新扫码即可。多账号把 `accounts` 数组填多条，登录失效自动轮换。
+
+## 使用
+
+Agent 里直接说"用豆包画一张…"，Agent 会调用工具。手动验证不走 Magpie：
+
+```sh
+node scripts/test-protocol.mjs --check                       # 各账号登录态
+node scripts/test-protocol.mjs "一只柴犬在樱花树下" --ratio 16:9
+node scripts/test-protocol.mjs "改成赛博朋克风格" --ref 照片.jpg   # 图生图
+node scripts/test-protocol.mjs "一朵红玫瑰特写" --wm            # 文生图 + 去水印
+```
+
+生成的图默认保存在调用方工作目录的 `generated-images/`（可在 config.json 用 `outDir` 改）。
+
+## 配置项
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `accounts` | `[]` | `{name, sessionid, ttwid?, passport_csrf_token?}` 数组 |
+| `model` | `Seedream 5.0 Flash` | 默认模型档位；Pro 档需订阅，会自动回退免费档 |
+| `ratio` | `1:1` | 默认画幅比例 |
+| `channel` | `auto` | `web`=chat_ability 新协议（模型/比例精确）；`pc`=samantha 旧通道（稳定、支持图生图）；`auto`=先 web 后 pc |
+| `outDir` | 空 | 图片保存目录，空=跟随调用方工作目录 |
+| `timeoutSeconds` | `180` | 单次请求超时 |
+| `ratioHint` | `true` | web 通道把比例追加进自然语言（web 端 ratio 字段实测不生效） |
+| `removeWatermark` | `false` | 去右下角"豆包AI生成"水印（扩图裁剪法，见下） |
+| `watermarkExtend` | `"1/4"` | 去水印的扩图比例，裁剪保留 1/(1+该值) |
+
+## 去水印（扩图裁剪法）
+
+开启 `removeWatermark: true`（或调用时传 `remove_watermark: true`）后，文生图会自动多走一步：
+
+1. 正常生成图片（右下角带"豆包AI生成"标）
+2. 以该图为参考图走图生图，提示词自动追加 **"往下扩图四分之一"** —— 模型重新演绎画面，旧水印随之消失，而新一轮水印落在底部新增区域
+3. 下载扩图结果，**裁掉底部扩出部分（保留上方 80%）**，覆盖保存
+
+代价与注意：
+
+- 多花一次生成额度（一张图 = 两次生成）
+- 画面边缘会被模型重新演绎，构图略有变化
+- 扩图比例可用 `watermarkExtend` 调整（如 `"1/5"` → 保留 5/6）
+- 仅对文生图生效；图生图保留用户原图语义，不自动扩图
+- 扩图结果若非 PNG（目前实测均为 PNG）会跳过裁剪并保留原图，不会损坏文件
+
+## 故障排查
+
+| 现象 | 处理 |
+|---|---|
+| 提示登录态失效 | `sessionid` 过期（约 30 天），重新复制；多账号时会自动轮换 |
+| `710022002 / 710022004` 风控 | 等约 30 分钟冷却 / 换网络（手机热点最快）/ 浏览器过一次滑块验证 |
+| 提示需要订阅 | 免费账号只能用免费档（Seedream 5.0 Flash / 4.5 / 4.0），点名 Pro 档会自动回退 |
+| `msToken` 相关风控 | 本插件默认不带 msToken（留空最安全），无需配置 |
+| 生图很慢 | 单张通常数秒到一两分钟；超时可调大 `timeoutSeconds` |
+
+## 参考实现
+
+协议字段移植自开源抓包项目（Apache-2.0）：
+
+- [wangchuxiaoji-oss/doubao2api](https://github.com/wangchuxiaoji-oss/doubao2api) —— samantha 通道、上传两步流、SSE 解析
+- [sanshidi/doubao-web-mcp](https://glama.ai/mcp/servers/sanshidi/doubao-web-mcp) —— web chat_ability 协议笔记（2026-10-19 抓包结论）
+- [magpie-community/plugins](https://github.com/magpie-community/plugins) —— Magpie 工具插件格式样板
+
+本仓库 `reference/` 目录存有移植时对照的源码快照（已 gitignore，仅作参考，不参与运行）。

package/config.example.json

@@ -0,0 +1,18 @@
+{
+  "accounts": [
+    {
+      "name": "主号",
+      "sessionid": "粘贴 www.doubao.com F12 → Application → Cookies → sessionid 的值",
+      "ttwid": "可选，同页面 Cookie 里的 ttwid，带上更稳",
+      "passport_csrf_token": "可选，同页面 Cookie 里的 passport_csrf_token"
+    }
+  ],
+  "model": "Seedream 5.0 Flash",
+  "ratio": "1:1",
+  "channel": "auto",
+  "outDir": "",
+  "timeoutSeconds": 180,
+  "ratioHint": true,
+  "removeWatermark": false,
+  "watermarkExtend": "1/4"
+}

package/index.mjs

@@ -0,0 +1,204 @@
+// Magpie 工具插件入口：把用户自己的豆包账号（网页版登录态，与桌面端同账号同后端）
+// 暴露为所有 Agent 可用的生图工具。经 /mcp/magpie/tools 注册为 <插件>_<工具>。
+//
+// 工具：
+//   generate_image — 文生图 / 图生图（参考图），可指定比例与免费档模型
+//   check_login    — 各账号登录态自检
+//
+// 凭证配置（任选其一，优先级从高到低）：
+//   1. env DOUBAO_IMAGE_CONFIG 指向的 JSON 文件
+//   2. 本插件目录下的 config.json（参考 config.example.json）
+//   3. env DOUBAO_ACCOUNTS="主号:sessionid=xxx,ttwid=yyy;小号:sessionid=zzz"
+//   4. Magpie options（magpie plugin options tools-doubao '<json>'）
+import path from "node:path";
+import { loadConfig } from "./src/config.mjs";
+import { generate, checkLogin, FREE_MODELS, DEFAULT_MODEL, RATIOS } from "./src/client.mjs";
+import { DoubaoError } from "./src/http.mjs";
+import { downloadImage, fileStamp, fileSize } from "./src/download.mjs";
+import { qrLogin, saveQrPng, openInViewer, writeAccountToConfig } from "./src/qlogin.mjs";
+import { removeWatermarkByExtend } from "./src/watermark.mjs";
+
+// 本地文件夹加载时 Magpie 用目录名作为插件 id（工具前缀也来自它）
+const PLUGIN_ID = "doubao-image-plugin";
+
+function resolveOutDir(args, context, cfg) {
+  if (args.out_dir) return String(args.out_dir);
+  if (cfg.outDir) return String(cfg.outDir);
+  const base = context?.directory || context?.worktree || process.cwd();
+  return path.join(String(base), "generated-images");
+}
+
+function failMessage(err) {
+  if (err instanceof DoubaoError) {
+    return `豆包生图失败：${err.message}${err.hint ? `\n建议：${err.hint}` : ""}`;
+  }
+  return `豆包生图失败：${err?.message || String(err)}`;
+}
+
+export const DoubaoTools = async (input, options) => {
+  const pluginOptions = options && typeof options === "object" ? options : {};
+
+  return {
+    tool: {
+      generate_image: {
+        description:
+          "用用户自己的豆包账号生成图片（文生图/图生图，免费额度，Seedream 系列）。" +
+          "当用户想要画图、生成图片、出插画/海报/示意图，且希望走豆包（豆包桌面端/网页版同账号）时使用。" +
+          "输入画面描述 prompt（中英文皆可），可选画幅比例与模型档位；" +
+          "给出参考图 ref_images 时按参考图风格/内容出图（图生图）。" +
+          "返回已保存到本地的图片文件路径（含 Markdown 引用）。",
+        args: {
+          type: "object",
+          properties: {
+            prompt: {
+              type: "string",
+              description: "画面描述，越具体越好（主体/场景/风格/光线/构图）",
+            },
+            ratio: {
+              type: "string",
+              enum: RATIOS,
+              description: `画幅比例，默认 1:1，auto 交给豆包决定`,
+            },
+            model: {
+              type: "string",
+              description:
+                `图片模型档位，默认 ${DEFAULT_MODEL}（免费档：${FREE_MODELS.join(" / ")}）。` +
+                "Pro 档需要豆包订阅，免费账号会自动回退免费档",
+            },
+            ref_images: {
+              type: "array",
+              items: { type: "string" },
+              description: "参考图（图生图）：本地文件路径或图片 URL，可多张",
+            },
+            out_dir: {
+              type: "string",
+              description: "图片保存目录，默认当前项目下的 generated-images/",
+            },
+            remove_watermark: {
+              type: "boolean",
+              description:
+                "去除右下角“豆包AI生成”水印：生成后自动以原图为参考追加“往下扩图四分之一”再生成一次，" +
+                "并把底部扩出部分裁掉（多花一次生成额度，画面边缘会被重新演绎）。" +
+                "不传则跟随配置 removeWatermark（默认关闭）",
+            },
+          },
+          required: ["prompt"],
+        },
+        async execute(args, context) {
+          const cfg = loadConfig(pluginOptions);
+          const removeWm =
+            args.remove_watermark !== undefined
+              ? Boolean(args.remove_watermark)
+              : Boolean(cfg.removeWatermark);
+          try {
+            const genOpts = {
+              prompt: String(args.prompt || ""),
+              ratio: args.ratio,
+              model: args.model,
+              refImages: args.ref_images,
+              account: args.account,
+            };
+            const result = await generate(cfg, genOpts);
+            const dir = resolveOutDir(args, context, cfg);
+            const stamp = fileStamp();
+            const saved = [];
+            for (let i = 0; i < result.images.length; i++) {
+              const { file, bytes } = await downloadImage(
+                result.images[i].url,
+                dir,
+                `doubao-${stamp}-${i + 1}`,
+              );
+              saved.push({ file, bytes });
+            }
+            // 去水印（扩图裁剪法）：仅对文生图生效；图生图保留用户原图语义，不自动扩图
+            let wmNote = "";
+            if (removeWm && !args.ref_images?.length) {
+              for (const s of saved) {
+                try {
+                  const r = await removeWatermarkByExtend(cfg, {
+                    file: s.file,
+                    prompt: genOpts.prompt,
+                    ratio: args.ratio,
+                    account: args.account,
+                  });
+                  wmNote += `\n[去水印] 已扩图${Math.round(r.extendFrac * 100)}%并裁剪：${r.width}×${r.height}（扩图前 ${r.width}×${r.origHeight}）`;
+                } catch (err) {
+                  wmNote += `\n[去水印] 失败，已保留带水印原图：${err?.message || err}`;
+                  break;
+                }
+              }
+            }
+            for (const s of saved) s.bytes = await fileSize(s.file);
+            const lines = saved.map(
+              (s, i) => `${i + 1}. ${s.file}（${(s.bytes / 1024).toFixed(0)} KB）`,
+            );
+            return (
+              `已通过豆包生成 ${saved.length} 张图片。\n` +
+              `账号 ${result.account} · ${result.channel === "web" ? "网页通道" : "客户端通道"}${
+                result.conversationId ? ` · 会话 ${result.conversationId}` : ""
+              }${result.text ? `\n${result.text.slice(0, 200)}` : ""}${wmNote}\n` +
+              `文件：\n${lines.join("\n")}\n\n` +
+              saved.map((s, i) => `[生成图 ${i + 1}](${s.file})`).join(" · ")
+            );
+          } catch (err) {
+            return failMessage(err);
+          }
+        },
+      },
+      check_login: {
+        description:
+          "检查豆包生图插件的账号配置与登录态：列出每个配置账号是否存活。生图报登录失效/风控时先跑这个。",
+        args: { type: "object", properties: {} },
+        async execute() {
+          const cfg = loadConfig(pluginOptions);
+          if (!cfg.accounts.length) {
+            return (
+              "尚未配置任何豆包账号。请让用户运行 `node scripts/login.mjs` 扫码登录，或把 doubao.com 网页版 Cookie 里的 sessionid 写入插件目录的 " +
+              "config.json（参考 config.example.json），或设置环境变量 DOUBAO_ACCOUNTS=\"主号:sessionid=xxx\"。"
+            );
+          }
+          const statuses = await checkLogin(cfg);
+          const lines = statuses.map((s) =>
+            s.live
+              ? `✅ ${s.name} — 登录有效${s.userName ? `（${s.userName}）` : ""}${s.userId ? `，user_id=${s.userId}` : ""}`
+              : `❌ ${s.name} — 登录无效${s.error ? `（${s.error}）` : "，请重新扫码登录或更新 sessionid"}`,
+          );
+          return `豆包账号共 ${statuses.length} 个：\n${lines.join("\n")}`;
+        },
+      },
+    },
+    // 扫码登录：magpie plugin login doubao-image-plugin 时触发。
+    // 豆包没有 OAuth，采用与 doubao2api 相同的二维码扫码流：
+    // 弹出二维码图片 → 用户手机豆包 App 扫码确认 → 轮询拿到 sessionid 写入 config.json。
+    auth: {
+      provider: PLUGIN_ID,
+      methods: [
+        {
+          type: "oauth",
+          label: "豆包扫码登录",
+          authorize: async () => ({
+            url: "",
+            method: "auto",
+            instructions:
+              "将弹出豆包登录二维码（系统看图程序）。请用手机豆包 App 扫码并在手机上确认，登录态会自动写入插件 config.json。",
+            callback: async () => {
+              try {
+                const result = await qrLogin({
+                  onStatus: (stage, detail) => {
+                    if (stage === "ready" && Buffer.isBuffer(detail)) openInViewer(saveQrPng(detail));
+                  },
+                });
+                const file = writeAccountToConfig(result, "扫码登录");
+                return { type: "success", accountId: `豆包 · ${result.sessionid.slice(0, 6)}…`, configFile: file };
+              } catch (err) {
+                return { type: "failed", error: `豆包扫码登录失败：${err?.message || err}` };
+              }
+            },
+          }),
+        },
+      ],
+    },
+  };
+};
+
+export default DoubaoTools;

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@zeppeli777/tools-doubao",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Doubao (豆包) image generation relay for Magpie: text-to-image and image-to-image with the user's own Doubao web session (QR-code sign-in), served to every agent via /mcp/magpie/tools",
+  "type": "module",
+  "main": "./index.mjs",
+  "license": "MIT",
+  "author": "Zeppeli777",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zeppeli777/doubao-image-plugin.git"
+  },
+  "homepage": "https://github.com/Zeppeli777/doubao-image-plugin#readme",
+  "bugs": "https://github.com/Zeppeli777/doubao-image-plugin/issues",
+  "files": [
+    "index.mjs",
+    "src",
+    "scripts",
+    "config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "magpie",
+    "magpie-tools",
+    "magpie-plugin",
+    "opencode-plugin",
+    "mcp",
+    "doubao",
+    "seedream",
+    "image-generation",
+    "text-to-image"
+  ],
+  "magpie": {
+    "name": "豆包生图中转"
+  }
+}

package/scripts/login.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// 扫码登录：弹出豆包登录二维码（终端 ASCII + 系统看图程序），手机确认后自动把
+// 登录态写入插件目录 config.json。等价于其他反代项目的 "QR 扫码登录"。
+//   node scripts/login.mjs [--name 主号]
+import { qrLogin, qrPngToAscii, saveQrPng, openInViewer, writeAccountToConfig } from "../src/qlogin.mjs";
+
+const argv = process.argv.slice(2);
+const nameIdx = argv.indexOf("--name");
+const accountName = nameIdx >= 0 ? argv[nameIdx + 1] : "扫码登录";
+
+console.log("正在获取豆包登录二维码…");
+try {
+  const result = await qrLogin({
+    onStatus: (stage, detail) => {
+      if (stage === "ready" && Buffer.isBuffer(detail)) {
+        const file = saveQrPng(detail);
+        const opened = openInViewer(file);
+        console.log(`二维码已保存: ${file}${opened ? "（已用看图程序打开）" : "（请手动打开）"}\n`);
+        const ascii = qrPngToAscii(detail);
+        if (ascii) console.log(ascii);
+        console.log("请用手机豆包 App 扫描二维码，并在手机上确认登录…");
+      } else if (stage === "scanned") {
+        console.log("已扫码，请在手机上点「确认」…");
+      }
+    },
+  });
+  const file = writeAccountToConfig(result, accountName);
+  console.log(`\n✅ 登录成功，账号「${accountName}」已写入 ${file}`);
+  console.log(`sessionid: ${result.sessionid.slice(0, 10)}…（完整值已保存，不会打印）`);
+  console.log("现在可以直接在任意 Agent 里调用 doubao_generate_image 了。");
+} catch (err) {
+  console.error(`\n❌ 登录失败: ${err.message}`);
+  process.exit(1);
+}