OpenCLI Midjourney 适配器实战指南：通过已登录 Chrome 会话完成生图、动作、配额与下载

• 开发工具
• CLI
• 人工智能
• AI 应用
• 浏览器控制
• GUI 自动化

本篇指南以 docs/adapters/browser/midjourney.md 为骨架，系统讲解 OpenCLI 的 Midjourney 浏览器适配器：它复用你已登录 Chrome 的www.midjourney.com会话，通过网站 UI 或其同源 API 驱动生成、检查、变换、监控与下载，无需 Discord Bot Token 或私有 API Key。读完本篇，你将掌握opencli midjourney全命令族的安全启动流程、成本守卫、结构化模型路由、参考图与个性化、视频动作及配额解读，并了解底层实现（对应源码位于 clis/midjourney/）。

适配器概览：命令族与运行模式

Midjourney 适配器整体遵循 OpenCLI 浏览器命令的接入约定：通过 Browser Bridge 扩展 连接本机正在运行的 Chrome，复用其登录态与 Cookie。命令声明为Strategy.COOKIE（只读 API 调用，如whoami、quota、history）或Strategy.UI（需要操作页面 UI 的写操作，如generate、action），并统一声明site: 'midjourney'、domain: 'www.midjourney.com'、siteSession: 'persistent'（见 clis/midjourney/generate.js、clis/midjourney/quota.js 等命令定义）。

其中whoami的底层实现（clis/midjourney/whoami.js）只返回logged_in / site / plan / subscription_status四列，刻意不输出用户身份字段；settings（clis/midjourney/settings.js）读取的字段包括model、image_resolution、personalization、raw、speed、video_resolution、video_batch_size，并在读取后恢复设置面板的打开/关闭状态。

安全启动：先验证、再试跑、后提交

在首次提交付费任务前，建议按以下顺序做一次“安全启动”，确认登录、设置与配额都能被正常读取：

opencli midjourney login opencli midjourney whoami -f json opencli midjourney settings -f yaml opencli midjourney quota -f yaml # 只做路由与成本校验，不实际上传或提交 opencli midjourney generate "a blue ceramic teapot --ar 1:1" --dry-run -f yaml

--dry-run在 generate.js 中位于assertBudget之后、任何上传与提交之前，直接返回状态为planned的结果行，因此可以安全地验证：账号是否有生成资格（assertGenerationEntitlement）、网站当前模型/分辨率/速度设置能否支撑你的参数组合、估算分钟数是否超过--max-minutes。

两道独立成本守卫

generate与付费action操作共用两道守卫（实现见 capabilities.js 的assertBudget）：

• --max-minutes（默认2）：当本次命令的保守估算分钟数超过该值时直接拒绝；
• --reserve-minutes（默认0）：当执行后账户剩余分钟数会低于该“保留底线”时拒绝。

需要强调的是：这是安全估算而非计费承诺。账户实时数值请以quota为准，并在真实任务完成后对比estimated_minutes与observed_minutes——后者由生成前后两次读取账户 credits 并换算得到（creditsToFastMinutes，CREDITS_PER_FAST_MINUTE = 60_000）。另外，符合条件的 Relax 模式图像任务会报告0估算 Fast GPU 分钟，因为 Relax 不消耗 Fast 余额，但队列可用性与套餐规则仍然适用（见 capabilities.js 中if (speed === 'relax') perJobMinutes = 0的实现注释）。

生成图像：模型、分辨率、速度与原生参数

generate是适配器的核心写命令，一个典型调用如下：

# V8.2 Standard/SD，默认下载全部四个候选 opencli midjourney generate \ "a cobalt glass fox, studio product photography --ar 1:1" \ --model v8.2 --resolution sd --speed fast # 只提交并返回精确 job id，不等待 opencli midjourney generate "minimalist lighthouse --ar 3:2" \ --wait false --skip-download # 更高分辨率的 V8.2 批次 opencli midjourney generate "coastal observatory at dusk --ar 16:9" \ --model v8.2 --resolution hd --max-minutes 1.5

generate的完整参数表（generate.js）：

结构化模型路由与兼容性规则

支持的结构化模型为v8.2、v8.1、v7、v6.1、v6、niji7、niji6。--model auto时尊重网站当前选择的版本，除非兼容性规则要求强制路由（实现在 capabilities.js 的resolveGenerationPlan）：

• Omni Reference 将auto路由到 V7；显式指定不兼容模型时直接报错而非静默替换。
• Character Reference（--cref）与多提示词权重（--iw之外的::权重语法）通过 V6/V6.1/Niji 6 的原生提示词参数可用。
• HD 图像生成仅限 V8.1/V8.2（resolution === 'hd' && !['v8.1','v8.2'].includes(selectedModel)时抛出ArgumentError）。
• V8.1/V8.2 的 Turbo 与仅旧版支持的参数（如--quality）会在提交前被拒绝。

位置提示词可携带原生参数，如--ar、--seed、--stylize、--weird、--no、--tile以及各版本特有参数。适配器只校验能证明不安全的组合（如--sd与--hd同时出现、--niji与--v/--version并存、套餐不支持 Relax/Turbo/Stealth、多提示词权重给了非 V6 系模型等），其余提示词语法交给 Midjourney 本身裁决。

参考图与个性化：本地文件、URL 与任务引用

--image-ref、--style-ref、--omni-ref接受三种来源：

1. 本地文件：PNG/JPEG/WEBP/GIF，上限 10 MB（MAX_REFERENCE_BYTES = 10 * 1024 * 1024，见 utils.js），上传前会校验存在性、非空、扩展名与大小；
2. HTTPS 图片 URL；
3. Midjourney 任务 URL：/jobs/<uuid>?index=N，解析后转换为对应 CDN 原图地址（originalImageUrl），其中index限定0..3。

本地文件通过已登录的 Web composer 上传，并与上传响应精确关联（拦截/api/storage-upload-file响应或轮询可见图片源，见 utils.js 的uploadReferenceLibrary/uploadedStorageUrlsFromCaptures）。常用写法：

# 内容/构图参考；多文件用 JSON 数组重复该选项 opencli midjourney generate "a small robot crossing a salt flat" \ --image-ref '["pose.png","https://example.com/light.png"]' \ --image-weight 1.2 # 风格参考图或数字 Style Reference 代码 opencli midjourney generate "botanical field guide" \ --style-ref ./ink-style.png --style-weight 250 # V7 Omni Reference；auto 路由会在 routing_reason 中明确说明 opencli midjourney generate "the same character in a winter station" \ --omni-ref ./character.png --omni-weight 200 --model auto # 使用已有的 Personalization 档案或 Moodboard id opencli midjourney generate "quiet reading room" --profile <profile-or-moodboard-id>

--style-ref额外接受纯数字 Style Code（allowStyleCode: true，解析为styleCode类型）；--omni-ref只接受恰好一个引用（multiple: false），本地文件数量不符也会被拒绝。最终提示词由buildEffectivePrompt组装：URL 类引用拼接到提示词头部，结构化参数（如--v、--sd/--hd、--fast/--relax/--turbo、--repeat、--profile、--sref、--oref、--iw/--sw/--ow）仅在提示词未显式声明时追加，避免冲突。

关键安全细节：清除残留引用

每次付费生成都会先清空手动固定或上次中断遗留的 web-composer 引用（clearImagePrompts），再执行上传与提交。这样一次没有传引用参数的调用，绝不会因为继承了浏览器里隐藏的旧引用状态而“凭空”带上参考图。

创作动作与视频：rerun / vary / upscale / edit / animate / loop / extend

图像任务支持以下动作（ACTION_CHOICES，见 capabilities.js）：

rerun、rerun-hd、vary-subtle、vary-strong、upscale-subtle、upscale-creative、open-editor、animate-low、animate-high、loop-low、loop-high、cancel（活动状态时）。

视频任务支持rerun、extend-low、extend-high、cancel（活动状态时）。

opencli midjourney action <image-job> vary-subtle --index 1 opencli midjourney action <image-job> upscale-creative --index 2 opencli midjourney action <image-job> open-editor --index 1 # 启动视频，并在结束后恢复账户级视频默认设置 opencli midjourney action <image-job> animate-high --index 1 \ --prompt "slow orbit, the subject turns toward the light" \ --end-frame ./ending.png --video-resolution sd --batch-size 1 opencli midjourney action <image-job> loop-low --index 1 --batch-size 1 opencli midjourney action <video-job> extend-high --prompt "the camera rises above the skyline" # 异步提交/取消的生命周期 opencli midjourney action <image-job> animate-low --wait false --batch-size 1 opencli midjourney action <returned-video-job> cancel

动作语义上的关键约束（action.js）：

• cancel仅对queued / running / in_progress / pending状态的任务有效；其余动作要求源任务状态为completed；
• --index必须恰好选中 1..4 中的一个候选；HD 图像任务不再提供 Upscale 动作；rerun-hd仅限 V8.1/V8.2 图像任务；
• --prompt与--end-frame只适用于animate / loop / extend类动作；
• loop-*与extend-*走“手动 composer”路径（确定性更强），当携带--prompt或本地--end-frame时，animate-*同样切到手动路径；
• open-editor会校验最终 URL 是否真的落在www.midjourney.com/edit/<job-id>，否则报错。

视频设置的“读取-临时修改-恢复”机制

视频分辨率与 batch size 是账户级网站设置。适配器先要求能读到可恢复的基线（读不到就拒绝操作，避免在没有可恢复基线时擅自改动全局默认值），随后应用请求的临时值；即使准备、提交或任务关联失败，也会在finally中把设置恢复原值（restoreVideoSettings）。一旦已确认付费子任务 ID，若恢复失败仅记log.warn而不把命令标记为失败——这是为了防止“误报失败 → 用户重复付费提交”。从源码结构看，animate/loop的预估成本直接绑定--video-resolution（sd/hd）与--batch-size（1/2/4）的组合，这也解释了为什么这些设置对成本守卫如此重要。

历史、状态与下载

opencli midjourney history --limit 20 --type video --status completed opencli midjourney history --query "glass fox" -f json opencli midjourney status <job> -f yaml # 全部图像候选，带校验过的缓存复用 opencli midjourney download <image-job> --kind image --index all --output ./midjourney # 视频导出 opencli midjourney download <video-job> --kind video-raw --index 1 opencli midjourney download <video-job> --kind video-social --index 1 opencli midjourney download <video-job> --kind gif --index 1

history（history.js）支持--limit（1..100，默认 10）、--type（all/image/video）、--status（all/queued/running/completed/failed/cancelled）与大小写不敏感的--query提示词子串过滤，输出列包括job_id、parent_job_id、type、operation、model、resolution、batch_size、command与url。

download（download.js）的--kind取值为auto（默认，视频走video-raw、图像走image）、image、video-raw、video-social、gif，并做了严格的类型限制（视频任务不能下image，图像任务只能下image）。下载链路（utils.js 的downloadOriginals/downloadRawVideo/downloadRenderedVideo）具备三个工程细节：

1. 原子写入：先写.part-<pid>-<ts>临时文件，再rename到最终路径；
2. 字节级校验：用sniffMediaMime识别文件魔数（PNG/JPEG/WEBP/GIF/MP4），与期望 MIME 不符则拒绝；媒体通过浏览器上下文分块拉取（96 KB 分块 base64 传输，避免超过 daemon 消息上限）；
3. 缓存复用：已存在的非空文件只有在魔数与期望格式一致时才复用，否则视为无效并重下；--force强制重下。原图候选依次尝试 PNG → JPEG → WEBP，下载结果列包含status（cached/downloaded）、bytes、mime与url。

配额解读：Fast GPU 分钟、批次估算与趋势

Midjourney 订阅配额按Fast GPU 分钟计量，而不是固定图片张数。一个普通图像任务返回 4 张候选的网格，因此quota输出的sd_batches_remaining是批次数而非单图数。

适配器有意对守卫做向上取整的保守估算（GPU_COST_MINUTES，见 capabilities.js）：

对于全新的 200 分钟 Basic 配额，保守上限约为：约 200 个 Standard/SD 批次（约 800 个候选）、133 个 HD 批次，或 100 个 Omni 批次（若整个配额只花在该操作上）。实际消耗会有差异——rerun、变体、放大、视频、失败/被拦截任务都会改变实际总量。

quota命令本身（quota.js）返回：plan、period_end、allocated_minutes、used_minutes、remaining_minutes、used_pct、days_remaining、avg_daily_minutes、projected_exhaustion_date，以及按三类成本换算的sd_batches_remaining、hd_batches_remaining、omni_batches_remaining。其中avg_daily_minutes与projected_exhaustion_date来自本地趋势数据：每次写操作与quota调用都会把账户快照追加到~/.opencli/sites/midjourney/usage-snapshots.jsonl（utils.js 的recordQuotaSnapshot），readQuotaTrend仅取当前计费周期内的快照计算日均消耗并推算耗尽日期。这类本地监控写入失败时只记警告，绝不会把一次已完成的付费任务变成“命令失败”——那会诱发无意的重复付费。

边界与前提

已知边界

• open-editor只在 Midjourney 编辑器中打开正确图像；inpainting、outpainting、pan、zoom 与 canvas 编辑仍属于交互式编辑器工作，不是独立 CLI 命令。
• 已有的 profile/Moodboard ID 可传给--profile；但 profile 发现与 Style Explorer 浏览不是独立命令。
• describe目前只接受本地图片。
• 适配器跟随的是已登录网站的能力，Midjourney 的功能可用性可以独立于 OpenCLI 变化。请用settings、--dry-run与类型化错误来探查当前边界（例如 composer 未就绪、套餐无 Relax 权限、账号未登录等都会给出明确的CommandExecutionError/AuthRequiredError/ArgumentError）。

前置条件

• Chrome 正在运行且已安装并加载 Browser Bridge 扩展（可用opencli doctor校验扩展与 daemon 连通性，daemon 通过localhost:19825WebSocket 桥接 CLI 与 Chrome 扩展）。
• 已在www.midjourney.com登录。
• 生成需要有效的 Midjourney 订阅；只读的登录、设置、历史、状态与配额检查不会提交付费任务。

如果你需要在远端机器（CI runner、Agent 主机）运行opencli而浏览器保留在本机，可参考 Remote Orchestration 文档 的 SSH 反向隧道模式。

小结

OpenCLI 的 Midjourney 适配器把“浏览器里的人工操作”转成一组可脚本化、可审计、带成本护栏的 CLI 命令：generate负责结构化路由与参考组装，action负责全套创作动作与视频生命周期，quota与本地快照负责分钟级预算管理，download负责带字节校验的媒体落盘。理解“估算 ≠ 计费承诺”“Relax 不扣 Fast 余额”“视频设置账户级且会自动恢复”这三条原则，你就能在批量生成、Agent 编排或日常创作中安全地使用这套命令族。

• 开发工具
• CLI
• 人工智能
• AI 应用
• 浏览器控制
• GUI 自动化