cascade-img

通过对话而非手动操作生成 Midjourney 图像。你描述想要的效果；AI 助手会编写提示词、发送请求、通过视觉能力检查图像网格、裁剪出最佳象限、进行优化，并记录有效的方法。

You: "I need a flat-design mountain icon, centered, simple shapes, transparent background"

Agent: reads prompt log → composes prompt from parts → fires imagine →
       waits → inspects 2x2 grid with vision → picks best quadrant →
       crops it → removes background → saves → logs what worked

cascade-img 是一个包含 23 个工具的 MCP 服务，可接入 Claude、Cursor、Codex 或任何支持 MCP 的工具。Midjourney 是首个后端；Flux、DALL-E 和 Imagen 已列入路线图。此外还提供 CLI。

不懂编程？ 打开一个能运行命令的 AI 助手（Claude Code、Cursor 或 Cline），将它指向此代码库，然后告诉它：“阅读 RUNBOOK.md 并在这台机器上配置 cascade-img，然后让我只需描述图像就能生成图像。” 它会处理技术部分。你只需要订阅 Midjourney，并从 Discord 复制几个值。

---

快速开始

你需要： 一个付费 Midjourney 订阅、一个在某个频道中有 MJ 机器人的 Discord 账号，以及 Python 3.12 或更新版本。

pip install cascade-img

或者从源码安装：

git clone https://github.com/laffeyp/cascade-img
cd cascade-img/packages/python
pip install -e .

这会在你的 PATH 中添加三个用于运行 cascade-img 的命令：cascade-mj-bridge（守护进程）、cascade-mcp（MCP 服务）和 cascade-mj（CLI）。安装还会添加第四个命令 cascade-trace-check——一个诊断验证器（不属于生成流程），用于重放记录的事件日志，并根据词汇表中声明的事件顺序和时序规则进行检查。

配置——你需要从 Discord 桌面应用获取四个值（频道 ID、服务器 ID、imagine 版本和用户令牌）。大约需要五分钟。RUNBOOK.md 会逐步介绍每个值的获取方法。

cp "$(python -c 'import cascade_img, pathlib; print(pathlib.Path(cascade_img.__path__[0]) / ".env.example")')" .env
# Fill in the four values per RUNBOOK.md, then validate:
cascade-mj-bridge --check-env --pretty

启动守护进程——在一个终端中启动，然后从另一个终端连接：

cascade-mj-bridge          # leave running — holds the Discord connection

连接你的 AI 助手——添加到 MCP 配置中（Claude Desktop、Cursor、Cline）：

{
  "mcpServers": {
    "cascade-img": {
      "command": "cascade-mcp"
    }
  }
}

或者将你的助手指向此代码库，并让它阅读 AGENTS.md——它会帮你配置好一切。

或者使用 CLI：

echo '{
  "mountain-icon": {
    "subject": "a flat-design icon of a mountain, centered, simple shapes",
    "aspect_ratio": "1:1"
  }
}' > assets.json

cascade-mj mountain-icon --registry assets.json --upscale all --pretty

---

23 个工具

类别	工具	功能
引导入门	cascade_guide	一次调用即可返回完整操作手册，涵盖工作循环、每个工具以及故障→操作对照表。请先调用它；阅读前，生成和整理工具均不可用。
生成	imagine、generate_video、wait、status、bridge_health、mj_action	编写并发送提示词、轮询结果、检查守护进程健康状态，以及触发 Midjourney 操作（放大、变体、平移）
补上进度	channel_recent、adopt_message	查看用户在 Discord 中手动完成的操作，并将其结果纳入工作流——纳入的消息会成为普通任务，由整理工具和 mj_action 处理
构图	compose_prompt、compose_video	根据结构化组成部分构建提示词——主体、情绪板、风格参考、纵横比、负面提示词，而非自由文本
整理	crop_grid、alpha_key、auto_trim、palette_quantize、contact_sheet、sprite_sheet、score_grid、video_filmstrip、loop_seam_delta、promote	从网格中提取象限、移除背景、裁去空白区域、制作精灵图、使用视觉能力为结果评分，并将优胜结果提升为最终输出
工作记忆	log_append、read_prompt_log	仅追加的提示词日志，Agent 会在每次运行前读取——记录尝试过什么、哪些有效、哪些无效。内容会在不同会话间保留。

每次调用都会返回 {ok, result} 或 {ok: false, error: {code, remediation}}。请根据稳定的 code 分支判断，而不是根据消息内容。完整工具参考请见 AGENTS.md。

---

有何不同

其他开源 Midjourney 工具专注于生成步骤——发送提示词，然后返回图像。cascade-img 则负责处理周边工作：

• 基于视觉能力的自主整理——Agent 检查自己的输出，并挑选最佳象限
• 结构化提示词构建——提示词由各个部分构成（主体、风格、身份、约束），而非原始字符串
• 工作记忆——仅追加的日志会在不同会话间保留；每次运行都会读取之前的记录
• 整理工作流——裁切网格、移除背景、制作精灵图，并将优胜结果提升为最终输出
• 原生支持 MCP——23 个工具，可接入 Claude、Cursor、Codex 或任何支持 MCP 的应用
• 可插拔后端——目前支持 Midjourney，路线图中还包括 Flux/DALL-E/Imagen

---

工作原理

一个守护进程，两个无状态客户端，全部通过本地 HTTP 通信：

• cascade-mj-bridge — 守护进程。唯一与 Discord 通信的进程。保持实时连接并跟踪正在执行的任务。必须持续运行。
• cascade-mcp — MCP 服务。默认使用 Stdio（Claude Desktop / Cursor / Cline）；通过 --http <port> 使用 HTTP。无状态——可随时启动和停止。
• cascade-mj — 命令行工具。接收资源 ID 和注册表，组合提示词，发起任务、等待完成并写入日志。

提示词由结构化部分组合而成，而不是作为原始字符串编写：

from cascade_img.prompt.composer import PromptComposer, Subject, StyleStack, IdentityStack

prompt = PromptComposer().compose(
    Subject(
        text="a flat-design icon of a mountain",
        constraints=["centered", "simple shapes", "transparent background"],
    ),
    # Both optional. moodboard is a Midjourney personalization code;
    # sref/oref are reference-image URLs you'd set up in MJ first.
    style=StyleStack(moodboard="abc123def", sref="https://cdn.example.com/style.png"),
    identity=IdentityStack(oref="https://cdn.example.com/ref.png", ow=1000),
    aspect_ratio="1:1",
    version="7",
)

这三个入口点都会输出结构化 JSON，并采用相同的 {ok, result | error: {code, remediation}} 封装。每个失败都带有稳定的错误代码（例如 DISCORD_401、MJ_UUID_MISSING、UPSCALE_BUTTON_FAILED）和机器可读的补救措施——因此调用方根据代码而不是消息进行分支处理。日志事件和错误代码的完整目录见 vocabulary/0.1.json，并且跟踪检查器（cascade-trace-check）会检查已记录运行中的事件顺序。

Midjourney 术语

prompt — 发送给 Midjourney 的文本和标志。grid — 每个提示词返回的 2x2 四候选图组。quadrant / U1-U4 — 四个单元格；“U2”表示放大第二个单元格。upscale — 将一个单元格渲染为全分辨率。aspect ratio（--ar） — 输出比例。sref — 用于借鉴其风格的图像。oref — 用于在不同姿势间保持其主体身份的图像。moodboard（--p） — 已保存的个性化配置。stylize（--s） — MJ 应用自身美学风格的强度。

---

文档

文档	内容
AGENTS.md	面向大模型操作人员的指南。将 cascade-img 交给 Agent 时请阅读。
RUNBOOK.md	安装、环境捕获、设置、重连生命周期，以及所有故障模式的错误代码和修复方法。
CAPABILITIES.md	cascade-img 驱动的所有 Midjourney 功能——提示词参数、mj_actions、V8.1/V7 的区别。
ARCHITECTURE.md	内部架构和设计决策。
examples/	三个操作演示：单张图像、批处理、视频。请先阅读 AGENTS.md。
CHANGELOG.md	版本发布历史。

---

路线图

版本	内容
v0.1（当前）	MJ 后端（V8.1 + V7）、提示词组合器、筛选工具、MCP 服务、命令行工具、提示词日志
v0.2	频道追赶 + 消息采纳——已合并到 main：channel_recent 和 adopt_message 让 Agent 可以查看用户在 Discord 中手动执行的操作并据此处理（设计文档）；待实现：更多 MJ 命令（/describe、/blend、局部重绘 Vary Region、/tune）、对已采纳网格的追溯式 U 按钮操作、内部重构
v0.3	TypeScript 封装；首批 API 后端——通过 Fal 使用 Flux，以及 Flux Kontext、Ideogram
v0.4	Google Imagen、Recraft（原生矢量/SVG）
v0.5	OpenAI gpt-image、Stable Diffusion
v1.0	API 稳定，至少三个后端投入生产

每个后端都实现同一接口，因此后续版本可以将它们串联起来——在一个服务提供商上生成，在第二个服务提供商上精修（例如 Flux Kontext），再在第三个服务提供商上放大。

---

仓库目录结构

cascade-img/
├── packages/python/        # the Python package (cascade_img)
│   ├── src/cascade_img/    #   prompt/, interfaces/, backends/, curation/, vocabulary/
│   ├── tests/              #   behavior tests
│   └── tools/              #   live smoke walk
├── examples/               # three walkthroughs of the operating loop
├── vocabulary/0.1.json     # event log-line catalog
└── *.md                    # README, ARCHITECTURE, RUNBOOK, AGENTS, CAPABILITIES, ...

---

免责声明

此工具通过 Discord 用户账号自动使用 Midjourney。此功能需要付费的 Midjourney 订阅。Discord 和 Midjourney 的服务条款都禁止自动化操作用户账号。这与所有开源 MJ 工具使用的机制相同（midjourney-proxy、midjourney-api 等）——Midjourney 没有公开 API。使用风险自负。

后端接口可插拔——Flux、DALL-E 和 Imagen 已列入路线图。

许可证

Apache-2.0。请参阅 LICENSE。