内容
# 级联图像
[](https://github.com/laffeyp/cascade-img/actions/workflows/ci.yml)
[](./LICENSE)
级联图像是一个视觉资产生成流程，可以由大型语言模型（LLM）运行。你通过语音或文本告诉AI助手你想要什么，它会组合提示、生成图像或视频、挑选好的图像、清理它们并存储起来。你从一个想法开始，最终得到一组连贯、相关的资产。
与其在付费生成服务上一次生成一个图像，然后在网页界面保存每个结果、下载、创建文件夹并跟踪一切，不如通过对话生成并自己管理整个过程。只需打开存储库，指向AI助手读取 [AGENTS.md](./AGENTS.md)，你的Claude就可以在MCP的指导下驱动整个过程。
当然，也有一个命令行界面（CLI），它很快就会作为一个包发布。
我们今天驱动的生成器是Midjourney——最难达到的模型，这就是为什么我们从它开始。其他后端（Flux、DALL-E、Imagen等）被构建为在相同的接口后面插入。
## 工作原理
Midjourney是一个文本到图像的生成器——你描述一幅图片（“一座山的扁平设计图标”），它就会绘制出来，是最强大的模型之一，适用于风格化、艺术指导的工作。问题在于：它没有公共API。唯一访问它的方法是通过Discord机器人，你在那里输入`/imagine <prompt>`，它会用一个2×2的网格回复，包含四个候选图像供你选择和放大到全分辨率。（它需要付费订阅——[midjourney.com](https://midjourney.com)。）如果你使用过Midjourney，这很熟悉；如果你没有，这有点难以解释。
级联图像为你自动化了整个Midjourney/Discord流程，这样你就不需要触摸Discord或自己学习提示语法。
我们将提示分成可组合的部分，你可以独立设置，每次尝试都记录为工作内存，以便下一次传递，并通过MCP服务器公开整个循环——Claude、Cursor、Cline等协议用来调用工具——这样代理可以组成、生成、策划和记录无需你的输入。
例如，你可以设置一个情绪板和一个参考图像，然后在不自己编写任何Midjourney提示的情况下，快速浏览一批资产。你扮演批评家或导演的角色——“是的，我喜欢这个”；“不，这是错误的”；“让我们回到上一个”；“把这个作为参考样式”；“这个想法怎么样”——与LLM对话而不是自己输入生成图像的命令。
一切都被记录下来。每次尝试（提示、结果、为什么被保留或丢弃）都会被记录到助手下次读取的日志中，这样它就可以在之前尝试的基础上继续，而不是重新开始。
你可以从一个想法到一个文件夹的完成、一致、有组织的资产，只需进行一次对话——比手动生成和选择选项要快得多，并且带有每个最终图像生成的书面记录。CLI和Python API可用于脚本编写和嵌入，但代理循环至少对作者来说是主要内容；[AGENTS.md](./AGENTS.md)是代理一次读取的操作指南。
## 两条路径
如果你只想通过描述图像来生成图像，你不需要阅读后面的内容——AI助手会为你设置并运行循环。如果你是技术人员或想了解更多，请跳转到[快速入门](#快速入门)，然后是[ARCHITECTURE.md](./ARCHITECTURE.md)和[AGENTS.md](./AGENTS.md)。
## 非技术人员？从这里开始
你不必是程序员，也不需要了解上述内容的含义。该工具旨在由AI助手运行，它附带了一份为此编写的逐步设置指南（[RUNBOOK.md](./RUNBOOK.md））。打开一个可以运行计算机命令的AI助手——[Claude Code](https://claude.com/claude-code)、Cursor或Cline——指向它到这个存储库，并要求它为你完成整个过程：
> 读取RUNBOOK.md并在该机器上设置级联图像，然后让我通过向您描述来生成图像。带我完成您需要做的几个步骤。
它具有完整的上下文——指南列出了每个步骤和可能出现的问题——因此它会运行命令，处理技术部分，并在出现问题时回答你的问题。两个需要你完成的步骤，Midjourney订阅和从Discord复制几个值，它也会指导你完成。
Midjourney首先被设计为首选。Midjourney没有公共API，因此通过Discord帐户驱动它实际上已经成为使用它的既定方式。它首先被解决正是由于它更复杂。完成此操作后，添加其他集成就变得更容易了。
> **上下文。** Midjourney没有公共API。通过Discord用户帐户驱动它是通过程序化访问的既定OSS模式。当然，Discord和Midjourney的使用条款禁止用户帐户自动化。
## 快速入门
**开始前，您需要：**
- **付费Midjourney订阅**（[midjourney.com](https://midjourney.com)）。
- **Discord帐户**，您可以在其中运行`/imagine`并获取网格 - 即Midjourney机器人在您的某个频道中。新的：订阅Midjourney并通过Discord使用它[通过Discord](https://docs.midjourney.com/hc/en-us/sections/32013439485197-Using-Discord)，或将MJ机器人邀请到您自己的服务器。
- **Python 3.14**（`brew install python@3.14`在macOS上）- 级联图像以最新的稳定Python为目标。
- 大约五分钟，从Discord桌面应用程序中捕获几个值（您的令牌，频道ID，`/imagine`版本和服务器ID）; [RUNBOOK.md](./RUNBOOK.md)逐步指导您。
级联图像驱动您自己的Midjourney帐户，并在您的机器上本地运行。
### 1. 获取它
```bash
git clone https://github.com/laffeyp/cascade-img
cd cascade-img/packages/python
pip install -e .
```
这会拉取依赖项并在您的`PATH`上放置三个控制台脚本 - 一个长期运行的守护进程和两个连接它的短生命周期客户端：`cascade-mj-bridge`（桥守护进程），`cascade-mcp`（MCP服务器）和`cascade-mj`（CLI）。
### 2. 配置（一次性）
级联图像通过您的Discord帐户访问Midjourney，因此您从Discord桌面应用程序中捕获几个值到`.env`中。步骤如下; [RUNBOOK.md](./RUNBOOK.md)重复这些步骤，并提供额外的故障排除信息，如果您遇到问题。
首先，将环境模板复制到您的工作目录中：
```bash
cp "$(python -c 'import cascade_img, pathlib; print(pathlib.Path(cascade_img.__path__[0]) / ".env.example")')" .env
```
**在Discord桌面应用程序中启用DevTools。** 编辑`~/Library/Application Support/discord/settings.json`（macOS），并在顶级JSON对象中添加以下内容：
```json
"DANGEROUS_ENABLE_DEVTOOLS_ONLY_ENABLE_IF_YOU_KNOW_WHAT_YOURE_DOING": true,
```
完全退出Discord（Cmd+Q，而不是关闭窗口），重新打开，然后按**Cmd+Option+I**打开DevTools。
**将每个值捕获到您的`.env`中：**
| 变量 | 如何捕获 |
| --- | --- |
| `MJ_CHANNEL_ID` | 启用Discord设置→高级→**开发者模式**，然后右键单击您的Midjourney频道→**复制频道ID**。 |
| `MJ_GUILD_ID` | 右键单击包含您的Midjourney频道的服务器→**复制服务器ID**。 |
| `MJ_IMAGINE_VERSION` | 在DevTools→**网络**中，在MJ频道中运行`/imagine`，并从`POST /api/v9/interactions`有效负载中读取`data.version`（19位）。 |
| `DISCORD_USER_TOKEN` | 在DevTools中，打开**控制台**选项卡并启用移动仿真（**Cmd+Shift+M**）。将下面的代码段粘贴到控制台中，按Enter键，然后复制它打印的令牌。 |
```javascript
const iframe = document.createElement('iframe');
console.log('Token: %c%s', 'font-size:16px;',
JSON.parse(document.body.appendChild(iframe).contentWindow.localStorage.token));
iframe.remove();
```
模板中还具有可选设置（输出目录，端口），具有默认的工作值。 一旦您的`.env`文件已填写完毕，请验证它：
```bash
cascade-mj-bridge --check-env --pretty # 验证.env并命名任何缺失的内容
```
### 3. 启动桥守护进程
```bash
cascade-mj-bridge # 长期运行; 唯一与Discord通信的进程
```
**将其留在自己的终端中运行**，并为下一步打开第二个终端。 守护进程是**服务器**; 以下的MCP服务器和CLI是**客户端**，它们通过本地HTTP连接它，而不直接与Discord通信。 它必须保持运行，因为它唯一保留了活动Discord登录（建立速度慢）并跟踪您的未完成渲染（Midjourney每个图像需要一段时间）- 停止它，连接就会断开，任何正在渲染的作业都会丢失。 客户端不保留任何状态，因此它们可以自由启动和停止。
### 4a. 从MCP主机驱动它 - 您已经在使用的AI助手应用程序（Claude Desktop，Cursor，Cline）
只需将服务器添加到主机的MCP配置中，或者只需将您的助手指向此存储库，并要求它读取 [AGENTS.md](./AGENTS.md) 并将其连接起来。 手动完成，只需添加一个条目：
```json
{
"mcpServers": {
"cascade-img": {
"command": "cascade-mcp"
}
}
}
```
您的代理获得了具有可 introspect JSON模式的20种工具：
- **生成** - `imagine`，`generate_video`，`wait`，`status`，`bridge_health`，`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`
[AGENTS.md](./AGENTS.md)是操作员指南，代理一次读取。
### 4b. 从CLI驱动
在另一个shell中，定义一个资产注册表（`asset_id`→提示部分）并生成它。 只有`subject`是必需的; `moodboard`（Midjourney情绪板代码）和`sref`（样式参考图像URL）是可选的样式控件，您将在Midjourney中首先设置它们 - 省略它们以获取纯提示：
```bash
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
```
JSON输出到stdout，`done`退出代码为0; 生成的图像位于`./generated`中。
> **验证后再依赖它。** 从`packages/python/`开始，安装开发额外功能（`pip install -e '.[dev]'`），然后运行`pytest`进行离线套件或`python tools/smoke_mcp_walk.py --env-file .env`进行实时端到端检查（启动桥和MCP服务器并测试每个工具）。
---
## 中途旅程术语
本指南中使用的Midjourney术语：
**提示** - 您发送给Midjourney的文本+标志 · **网格** - Midjourney返回的2×2个候选项集 · **象限/U1–U4** - 网格的四个单元格; “U2”表示将第二个单元格升级 · **升级** - 以完整分辨率渲染一个单元格 · **长宽比（`--ar`）** - 输出形状（1:1、16:9等） · **sref** - Midjourney应借用样式的图像 · **oref** - Midjourney应在新姿势/角度中保留的图像 · **情绪板（`--p`）** - 保存的Midjourney个性化配置文件 · **风格化（`--s`）** - Midjourney应用其自身美学的程度（越低越字面）。
---
## 与其他工具的区别
大多数Midjourney驱动程序关注于生成步骤本身 - 发送提示，返回图像。级联图像完成了这项工作：它从可重用的命名部分构建提示，裁剪和清理结果，并记录每个尝试，以便每个循环可以建立在上一个的基础上。
```python
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"],
),
# 样式和身份是可选的。moodboard是Midjourney情绪板代码，sref/oref是参考图像URL - 请先在Midjourney中设置它们。
style=StyleStack(moodboard="<your-moodboard-code>", sref="https://cdn.../style.png"),
identity=IdentityStack(oref="https://cdn.../reference.png", ow=1000),
aspect_ratio="1:1",
version="7", # V7支持oref和--q;省略版本以获取V8.1默认值
)
```
其他开源选项存在 - [erictik/midjourney-api](https://github.com/erictik/midjourney-api)（一个Node库），[novicezk/midjourney-proxy](https://github.com/novicezk/midjourney-proxy)（一个Java HTTP代理），以及几个付费的REST代理，它们通过托管的API包装相同的Discord机制。它们中的任何一个都会为您提供生成的图像。
级联图像添加了生成周围的工作：可组合的提示部分而不是原始字符串，策划工具（网格裁剪，alpha密钥，促进），追加提示日志，MCP服务器，以便LLM代理可以运行整个循环，以及具有稳定代码的结构化错误信封 - 其中一个后端接口，因此Flux，DALL-E和Imagen可以稍后插入（v0.3+）。如果您只需要发送提示并获取图像，简单的驱动程序是一个合适的选择; 级联图像用于驱动完整的迭代和策划循环，特别是来自代理。
---
## 三个控制台脚本
一个长期运行的守护进程和两个无状态客户端，它们通过本地HTTP连接 - 启动守护进程一次并保持它运行; 客户端来来去去。
- **`cascade-mj-bridge`** - 通过Discord的MJ守护进程。运行一次会话并保持运行：它保留了Discord的实时连接和您的未完成作业。
- `--check-env` - JSON配置验证，带有结构化修复。
- `--doctor` - 完整的预飞行检查（环境+Discord可达性+MCP服务器+discord.py-self导入）。
- **`cascade-mcp`** - MCP服务器。默认情况下为标准输入/输出（Claude Desktop / Cursor / Cline）; `--http <port>`适用于首选HTTP的主机。
- **`cascade-mj`** - CLI。获取一个`asset_id`和一个注册表，合成提示，触发，等待结果，并将记录写入提示日志。
所有三个都发出结构化的JSON; 所有三个都遵循相同的 `{ok, result | error: {code, remediation}}` 信封。
---
## 结构化日志记录和错误
守护进程在整个作业生命周期中发出结构化的JSON日志行，每个失败都带有稳定的错误代码（例如`DISCORD_401`，`MJ_UUID_MISSING`，`UPSCALE_BUTTON_FAILED`）- 调用者可以根据代码分支而不是解析消息。词汇表中的事件日志行目录位于[vocabulary/0.1.json](./vocabulary/0.1.json)，每个故障模式的补救措施位于[RUNBOOK.md](./RUNBOOK.md)。目录还声明了这些事件的合法顺序（哪些必须先于哪些，取决于`job_id`）及其时间段; 跟踪检查器（`cascade-trace-check`）在记录的运行中强制执行这些规则，测试套件在每次CI更改和每次实时端到端运行中都运行它。
---
## 文档
- **[RUNBOOK.md](./RUNBOOK.md)** - 安装，环境捕获，设置过程，重新连接生命周期和每个已知故障模式及其结构化错误代码和补救措施。
- **[AGENTS.md](./AGENTS.md)** - LLM操作员指南。阅读此指南，然后将级联图像交给代理。
- **[CAPABILITIES.md](./CAPABILITIES.md)** - 中途旅程功能（每个提示参数和`mj_action`，V8.1/V7版本拆分，每个功能），以及故意不连接的内容。
- **[examples/](./examples/)** - 三个简短的通用操作循环演练（生成一个图像;生成一批;生成视频）。说明性的，而不是直接复制的模板。阅读AGENTS.md后再阅读这些。
## 仓库布局
```
cascade-img/
├── packages/python/ # Python包（导入名称：cascade_img）- 产品
│ ├── src/cascade_img/ # prompt/，interfaces/，backends/，curation/，vocabulary/
│ ├── tests/ # 行为测试
│ └── tools/ # 现场烟雾测试
├── examples/ # 三个简短的通用操作循环演练
├── vocabulary/0.1.json # 镜像包的事件日志目录
└── *.md # README，ARCHITECTURE，RUNBOOK，AGENTS，AGENT_RUNDOWN，…
```
产品是`packages/python`。操作员和代理需要的所有内容都是顶级Markdown加上该包。
## 路线图
| 版本 | 标题 |
| --- | --- |
| v0.1（当前）| MJ后端（版本感知-V8.1和V7），提示合成器，策划工具（裁剪+洪水填充alpha密钥+推广），MCP服务器，AGENTS.md，提示模板，Python包。 |
| v0.2 | 更多中途旅程命令（`/describe`，`/show`，Vary Region绘图，`/blend`，`/shorten`，`/tune`，`/info`）;内部代码清理 - 将大桥模块分开并分割长摄取函数。 |
| v0.3 | TypeScript包装器;第一个API后端 - [Flux](https://bfl.ai/) 通过 [Fal](https://fal.ai/) （带有指令编辑通过 [Flux Kontext](https://bfl.ai/models/flux-kontext) ）和 [Ideogram](https://ideogram.ai/) 以实现图像内的可靠文本; Windows桥。 |
| v0.4 | 更多后端 - [Google Imagen](https://deepmind.google/models/imagen/) 和 [Recraft](https://www.recraft.ai/) （本地矢量/SVG输出）; 捆绑二进制安装路径。 |
| v0.5 | [OpenAI gpt-image](https://openai.com/api/) 和 [Stable Diffusion](https://stability.ai/stable-image) 后端。 |
| v1.0 | API在两个次要版本上稳定，三个后端投入生产 |
由于每个后端都实现了同一个接口，因此后续版本可以链接它们：在一个提供商上生成，在第二个提供商上细化或指令编辑，然后在第三个提供商上缩放或重新造型 - 将每个图像作为下一个步骤的输入。级联图像成为在提供商之间移动图像的中继，利用每个提供商的最佳功能。
HTTP接口在两个包之间是主要的边界; 更改将在两个包之间协调。
## 许可证
Apache-2.0。 见 [LICENSE](./LICENSE)。
