内容
# naba
一款用于AI图像生成的独立CLI（单个Rust二进制文件），支持多个提供商 — **谷歌Gemini**、**OpenRouter** 和 **AWS Bedrock**。从命令行生成、编辑和转换图像。
**网站：** [naba.ysapp.net](https://naba.ysapp.net) — 文档、使用示例和输出示例，以及一行命令的快速安装。
## 安装
`naba` 是一个独立的、自包含的二进制文件 — 无需运行时环境，无需依赖。
### 厂商安装（来自 `naba.ysapp.net`）
该网站提供 `install.sh` 脚本，因此首次安装只需执行：
```bash
curl --proto '=https' --tlsv1.2 -LsSf https://naba.ysapp.net/install.sh | sh
```
GitHub Releases 仍然是所有二进制文件的规范来源。
### Homebrew（macOS 和 Linux）
如果您已经在使用 Homebrew，那么可以使用 tap — 但 Homebrew 安装不会通过 `naba self update` 自动更新；升级需要通过 `brew upgrade`:
```bash
brew install dixson3/tap/naba
brew upgrade naba # 后续更新
```
### Cargo
```bash
cargo install --git https://github.com/dixson3/naba
```
### 从源代码构建
```bash
git clone https://github.com/dixson3/naba.git
cd naba
cargo build --release # 二进制文件位于 target/release/naba
# 可选地，将此构建添加到您的 PATH 中作为“from-build”安装（~/.local/bin）：
./target/release/naba self install --from-build
```
## 自我更新
`naba self` 管理二进制文件本身。它仅在 **厂商** 安装（上述 `curl | sh` 安装程序）时自动更新；Homebrew 安装会被拒绝，并指向 `brew upgrade naba`，而从源代码构建或未知安装需要 `--force`。
```bash
naba self update # 获取最新版本，验证 sha256，替换当前文件
naba self update --check # 报告是否有更新可用；不更改任何内容
naba self update --json # 机器可读的信封（状态/源/当前/最新）
naba self install --from-build # 将正在运行的构建记录为 from-build 安装
naba self uninstall # 删除 from-build 标记（--force 也会删除二进制文件）
```
成功的 `self update` 也会刷新已安装的工具技能（`naba skills upgrade`），除非您传递 `--binary-only`。`version` 和 `doctor` 为厂商安装打印限流的“更新可用”提示。
您可以设置 `NABA_NO_UPDATE_CHECK=1`（或在 `CI` 中运行）来禁用它。
## 设置
为使用的提供商设置 API 密钥：
```bash
export GEMINI_API_KEY=<您的密钥> # 谷歌 Gemini
export OPENROUTER_API_KEY=<您的密钥> # OpenRouter
export AWS_BEARER_TOKEN_BEDROCK=<您的令牌> # AWS Bedrock（api-key 承载路径）
```
您也可以将每个提供商的密钥保存到配置文件（存储在 `config.yaml` 中）：
```bash
naba config set gemini.api-key <您的密钥>
naba config set openrouter.api-key <您的密钥>
naba config set bedrock.api-key <您的令牌>
```
**API 密钥解析** 对所有提供商都是统一的 — 优先级最高的是内联 `providers.<provider>.api-key`，其次是 `providers.<provider>.api-key-envvar` 命名的环境变量，然后是提供商的常规环境变量（`GEMINI_API_KEY` / `OPENROUTER_API_KEY` / `AWS_BEARER_TOKEN_BEDROCK`）。
参见 [提供商](#providers) 了解 `naba` 在存在一个或多个密钥时如何选择提供商。
## 提供商
`naba` 通过其注册的提供商路由每个图像命令（`generate`、`edit`、`restore` 以及复合命令）：
| 提供商 | 常规密钥环境变量 | 默认模型 | 端点 |
|:---------|:-------------------------|:--------------|:---------|
| `gemini` | `GEMINI_API_KEY` | `gemini-3.1-flash-image` | `{base}/models/{model}:generateContent` |
| `openrouter` | `OPENROUTER_API_KEY` | `google/gemini-3.1-flash-image-preview` | `POST /api/v1/images` |
| `bedrock` | `AWS_BEARER_TOKEN_BEDROCK` | `amazon.nova-canvas-v1:0` | `POST {base}/model/{modelId}/invoke` |
从 CLI 发现提供商和模型：
```bash
naba provider # 列出提供商 + 凭证状态（* 表示默认）
naba provider --json # 机器可读的 {status, data} 信封
naba models --provider bedrock # 列出提供商的模型（需要可解析的密钥）
```
使用全局 `--provider` 标志或 `default-provider` 配置密钥选择提供商：
```bash
naba generate "一个红色的苹果" --provider gemini
naba generate "一个红色的苹果" --provider bedrock
naba config set default-provider gemini # 固定默认提供商
```
### 提供商解析优先级
当您不传递 `--provider` 时，`naba` 按以下顺序解析提供商：
1. **CLI** `--provider`
2. **配置** `default-provider` 密钥
3. **环境密钥自动检测** — 在具有可解析凭证的提供商中，**最新** 的注册顺序提供商（`gemini` → `openrouter` → `bedrock`）获胜
4. **内置回退** — gemini（缺少密钥错误在调用时出现）
### 多密钥重定向（预期行为）
自动检测扫描注册顺序和 **最新** 具有凭证的提供商获胜。因此，如果同时设置了 `GEMINI_API_KEY` 和 `OPENROUTER_API_KEY` **且** 没有配置 `default-provider`，自动检测解析为 **OpenRouter**；添加 Bedrock 凭证，它重定向到 **Bedrock**。这是预期的优先级结果，而不是错误。
> **要保持不变，当设置多个密钥时，请在配置中固定提供商** — 配置优先于自动检测：
>
> ```bash
> naba config set default-provider gemini
> ```
### AWS Bedrock 身份验证
Bedrock 支持 **两者** 一个 api-key 承载令牌（`AWS_BEARER_TOKEN_BEDROCK` / `bedrock.api-key`，作为 `Authorization: Bearer` 发送）**和** AWS 配置文件 / SigV4 路径（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` [+ `AWS_SESSION_TOKEN`]，或 `~/.aws/credentials` 中的命名 `AWS_PROFILE`）。
`naba` 优先使用承载令牌（如果解析），否则使用 SigV4 签名。区域默认为 `us-east-1`，按以下顺序解析（优先级最高）：
1. `AWS_REGION`
2. `AWS_DEFAULT_REGION`
3. 内置默认值 (`us-east-1`)
### `--model` 需要 `--provider`
裸 `--model` 在 CLI 上是模糊的，因此 `--model` **没有** `--provider` 是一个使用错误（退出 2）。
始终将它们配对：
```bash
naba generate "英雄" --provider openrouter --model google/gemini-3.1-flash-image-preview
```
此规则是 **仅限 CLI 标志**：配置 `model` **没有** 配置 `provider` 是可以的 — 配置模型由自动检测/配置解析的提供商限定。
## 模型和定价
**Gemini** 默认使用 **`gemini-3.1-flash-image`** （Nano Banana 2）— 当前的 GA 图像模型，针对成本和延迟进行了优化。提供更高质量的层级， **`gemini-3-pro-image`** （Nano Banana Pro），适用于最终/英雄资产。
> **所有 Gemini 图像模型都需要付费（启用计费）层级 — 无免费层级。** Pro 的成本约为 flash 的 2–3.5 倍/图像，因此 flash 是默认的；仅当需要其质量时才选择 pro。
按调用或在配置中选择模型：
```bash
naba generate "英雄横幅" --quality high # 别名：high -> gemini-3-pro-image
naba generate "英雄横幅" --quality fast # 别名：fast -> gemini-3.1-flash-image（默认）
naba generate "英雄横幅" --provider gemini --model gemini-3-pro-image # 原始模型 ID（优先级最高）
```
对于 Gemini，模型按以下顺序解析（优先级最高）：
1. `--model`（CLI 标志）
2. `--quality`（CLI 标志）
3. 配置 `model`
4. 配置 `quality`
5. 内置默认值
现有的配置（例如 `model: gemini-2.5-flash-image`）保持不变。
### `--quality` 语义因提供商而异
`fast`/`high` 词汇是跨提供商的表面，但每个提供商对其解释不同：
- **Gemini** — `--quality` 选择一个 **模型层级**：`fast` → `gemini-3.1-flash-image`，`high` → `gemini-3-pro-image`。任何其他值都是使用错误。显式 `--model` 覆盖 `--quality`。
- **OpenRouter / Bedrock** — `--quality` 作为 **原生请求参数** 传递；它 **不** 切换模型。模型独立选择（ `--model` / 配置 `<provider>.model` / 默认）。因此 `--provider openrouter --quality high` 保留解析的 slug 并发送 `quality: high`。
`openrouter/auto`（和裸 `auto`）是纯文本路由器，**不能** 生成图像 — `naba` 早期拒绝它并出现使用错误。
## 用法
### 生成图像
```bash
naba generate "一个红色的苹果放在白色背景上"
naba generate "山景" --style watercolor
naba generate "城市天际线" -n 4 --style pixel-art
naba generate "抽象艺术" -v lighting -v color-palette -o art.png
naba generate "广阔的视野" --aspect 16:9 --resolution 2K
```
**宽高比和分辨率。** `--aspect` 和 `--resolution` 设置 Gemini 的 `imageConfig`，并在所有生成命令（`generate`、`edit`、`restore`、`pattern`、`diagram`、`story`）上可用。有效的 `--aspect`：`1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9`。有效的 `--resolution`：`512, 1K, 2K, 4K`（大写 `K`）。无效值在 API 调用前被拒绝。`icon --size` 是 **画布像素** — 与 `imageConfig` 的 `imageSize` 是不同的概念，不变。
### 编辑图像
```bash
naba edit photo.png "使天空更加戏剧化"
naba edit portrait.jpg "添加帽子" -o portrait-hat.png
```
### 恢复/增强图像
```bash
naba restore old-photo.jpg
naba restore blurry.png "锐化和改善颜色"
```
### 生成图标
```bash
naba icon "一个音乐符号" --size 64 --size 256 --size 512
naba icon "火箭船" --style flat --background white --corners sharp
```
### 生成图案
```bash
naba pattern "热带叶子" --style floral --colors colorful
naba pattern "电路板" --style tech --density dense --colors mono
```
### 生成故事
```bash
naba story "一只猫的魔法森林之旅" --steps 6
naba story "日出到日落" --steps 4 --transition dramatic
```
### 生成图表
```bash
naba diagram "用户身份验证流程" --type flowchart
naba diagram "微服务架构" --type architecture --complexity comprehensive
naba diagram "博客数据库架构" --type database --style clean
```
### 配置
配置是 **嵌套和按提供商划分的**：一个 `default_provider`，一个 `providers` 映射（每个条目 `{model, api-key?, api-key-envvar?}`），和顶级图像默认值。
```bash
naba config set default-provider gemini # 默认提供商（gemini, openrouter, bedrock）
naba config set gemini.api-key <密钥> # 提供商的内联 api-key
naba config set gemini.model gemini-3-pro-image # 提供商的默认模型（或：config set quality high）
naba config set gemini.api-key-envvar MY_KEY # 提供商的自定义密钥环境变量
naba config set aspect 16:9 # 默认 imageConfig 宽高比
naba config set resolution 2K # 默认 imageConfig 分辨率
naba config get gemini.model
naba config get gemini.model --json # 机器可读的信封
```
配置键：`default-provider`、`<provider>.model`、`<provider>.api-key`、`<provider>.api-key-envvar`（提供商 ∈ `gemini`、`openrouter`、`bedrock`）、`default_output_dir`、`aspect`、`resolution`、`quality`。每个调用的标志覆盖配置；配置中，提供商的 `model` 优先于 `quality`，而 `default-provider` 优先于环境密钥自动检测（参见 [提供商](#providers)）。遗平的扁平键 `api_key`（→ `gemini.api-key`）、`model`（→ 默认提供商的模型）和 `provider`（→ `default-provider`）仍然作为别名被接受。
完整的 `config.yaml`:
```yaml
default_provider: gemini
providers:
gemini:
model: gemini-3-pro-image
api-key: <内联密钥>
openrouter:
api-key-envvar: MY_OR_KEY
bedrock:
model: amazon.nova-canvas-v1:0
aspect: "16:9"
resolution: 2K
```
**配置自动迁移。** 旧的 **扁平** 配置（顶级 `api_key` / `model` / `provider`）自动迁移到嵌套模式：`naba` 在首次加载时写入 `config.yaml.bak` 备份，然后重写文档（`api_key` → `providers.gemini.api-key`，`model` → 默认提供商的块，`provider` → `default_provider`）。它是幂等的，并且对空/缺失/格式错误的输入宽容；结构重写会丢弃 YAML 注释（通过 `.bak` 备份缓解）。
### MCP 服务器
`naba mcp` 启动一个基于 stdio 的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，该服务器向诸如 Claude Desktop 和 Cursor 等 AI 助手公开所有 8 个图像工具，以及懒加载的 `skill://` 资源作为工具的使用指南。
MCP 是您如何给 **桌面** 助手 — 无法运行 shell 命令的助手 — 提供 `naba` 的一流访问权限：它直接通过协议调用 `naba` 的工具，并获得结构化结果，而无需涉及终端。它是 [Agent Skills](#agent-skills) 的对应部分（shell out 到 CLI 用于具有 shell 的编码代理）; 两个驱动相同的提供商/选择器/输出管道，因此您可以从任意方式获得相同的图像 — 差异纯粹是助手如何访问 `naba`。
**Claude Desktop 配置** — 添加到您的 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"naba": {
"command": "naba",
"args": ["mcp"],
"env": {
"GEMINI_API_KEY": "<您的密钥>",
"OPENROUTER_API_KEY": "<您的密钥>",
"AWS_BEARER_TOKEN_BEDROCK": "<您的令牌>",
"NABA_OUTPUT_DIR": "/path/to/output"
}
}
}
}
```
设置 `NABA_OUTPUT_DIR` 是推荐的 — 它告诉 `naba` 在哪里写入生成的图像。没有它，图像默认保存到 `~/.local/share/naba/images`。
**可用工具：
| 工具 | 描述 |
|:-----|:------------|
| `generate_image` | 从文本提示生成图像 |
| `edit_image` | 根据文本提示编辑现有图像 |
| `restore_image` | 恢复或增强现有图像 |
| `generate_icon` | 生成多个尺寸的应用图标 |
| `generate_pattern` | 生成无缝图案和纹理 |
| `generate_story` | 生成一个图像序列，讲述视觉故事 |
| `generate_diagram` | 生成技术图表和流程图 |
| `list_images` | 列出输出目录中的最近生成的图像 |
生成工具接受 `aspect`、`resolution` 和 `quality` 参数（匹配 CLI）；`generate_icon` 接受 `quality`。当 `count`/`steps`/`sizes` > 1 时，相同的 `imageConfig` 适用于调用中的每个图像。
**技能作为资源（延迟加载）。** 服务器还通过 `skill://` 资源提供 **MCP 作者的使用指南** - 为 MCP 工具（工具名称、参数、 `NABA_OUTPUT_DIR`、`file://` 结果）编写，不适用于 `/naba` CLI 文档。 `resources/list` 廉价地将其枚举为 `skill://naba/<rel>` URIs（路径仅限 - 没有正文）以及紧凑的 `skill://naba` 索引；`resources/read` 按需提供文件内容（`skill://naba/<rel>`）或生成的索引（`skill://naba`）。每个生成工具的描述都指向 `skill://naba`。参见网站 [MCP 页面](https://naba.ysapp.net/mcp/).
**手动测试** - 验证服务器响应 MCP 初始化握手：
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}' | naba mcp
```
## 代理技能
**技能** 教会 AI 编程代理一种新的能力 — 少量指令加上代理代表您运行的命令。`naba` 的技能将 *"制作一个火箭船的应用程序图标"* 转换为正确的 `naba` 调用，这样您就可以在不离开对话或记忆 CLI 标志的情况下获得 `naba` 的图像。
`naba` 配备了一个 **单一** 技能，该技能将整个 CLI 封装为一个带有子命令的斜杠命令：`/naba <子命令>`（例如 `/naba generate`、`/naba edit`、`/naba icon` 等）。它安装到您使用的 **代理框架** 中 — [Claude Code](https://claude.com/claude-code) 是默认和正在运行的示例，但 opencode、pi、codex 和可移植的 `agents` 布局也支持（参见下面的 [框架](#框架)）。技能文件在编译时 **嵌入到 `naba` 二进制文件中**，并使用 `naba skills install` 安装，因此安装是离线的，并且始终与版本匹配 — 没有市场插件和单独的安装脚本。
> **更喜欢无法运行 shell 命令的桌面助手** （Claude Desktop、Cursor）？请改用 [MCP 服务器](#mcp-server) — 它通过协议公开相同的图像管道，因此助手无需终端即可调用 `naba` 的工具。
> **先决条件：** 技能会调用 `naba` CLI，因此 **`naba` 二进制文件必须安装并在 PATH 中** （参见 [安装](#安装)）并且设置了提供商 API 密钥 — `GEMINI_API_KEY`、`OPENROUTER_API_KEY` 和/或 `AWS_BEARER_TOKEN_BEDROCK` （参见 [设置](#设置) 和 [提供商](#提供商)）。`naba skills install` 始终写入技能文件；技能在二进制文件在 PATH 中之前是惰性的。
> **重大更改（plan-002 → plan-003）：** 以前的 10 个独立技能（`/naba-generate`、`/naba-edit` 等）合并为一个 `/naba <子命令>` 技能，并且旧的 shell/python 安装脚本被 `naba skills` 替换。那些旧的每个命令的技能 **不** 嵌入在二进制文件中，因此 `naba skills` 无法删除它们。如果您在以前的版本中安装了它们，请手动删除它们：
>
> ```bash
> rm -rf ~/.claude/skills/naba-* # 用户/克劳德范围；根据 --surface 代理或项目范围调整路径
> ```
>
> 然后使用 `naba skills install` 安装合并的技能。
> **从 Go 构建（切换后）升级：** `naba` 现在是一个单一的 **Rust** 二进制文件（计划-004）。切换时嵌入的技能内容发生了变化，因此二进制文件计算的完整性哈希值与任何以前安装的（Go 构建的）`naba` 编写的哈希值不同。在安装 Rust 二进制文件后，运行 **`naba skills upgrade`** 一次，以从新的嵌入内容中重写已安装的技能树：
>
> ```bash
> naba skills upgrade
> ```
>
> 在您执行此操作之前，`naba skills status` 和 `naba doctor` 将报告已安装的副本为 **过时** （`installed copy is outdated vs this binary (run: naba skills upgrade)` ）— 该指导会自动显示，因此除了运行升级之外，不需要采取任何操作。
### 安装技能
```bash
naba skills install # 默认：claude-code 框架，用户范围 -> ~/.claude/skills
naba skills install --dry-run # 显示将要写入的内容，不更改任何内容
naba skills install --scope project # 安装到 <git-root>/.claude/skills 而不是
naba skills install --harness opencode # 安装到 ~/.config/opencode/skills
naba skills install --harness claude-code --harness pi # 可重复：一次安装多个框架
naba skills install --target DIR # 安装到明确的目录
naba skills upgrade # 刷新每个以前安装的目标
naba skills remove # 再次删除 naba 技能
naba skills status # 报告最新/完整/未修改
```
技能树在编译时嵌入到二进制文件中，因此 `naba skills` 离线工作，并且始终与二进制文件的版本匹配。在 `install`/`upgrade` 时，它会在部署的 `SKILL.md` 中写入一个隐藏的完整性标记（`<!-- naba-skills: v=<version> tree=<sha256> -->`）；`status` 和 `naba doctor` 使用该标记确认安装是当前、完整和未修改的。存储库源 `skills/naba/SKILL.md` 保持无标记。每个动词也接受 `--json` 以获取机器可读的 `{status, data}` 信封。
### 框架
相同的嵌入式技能树安装到多个代理 **框架**，每个框架都有其特有的技能路径。使用 `--harness <name>` 选择一个；该标志是 **可重复的**，因此一次 `install` 可以针对多个框架：
| 框架 | 项目范围路径 | 用户范围路径 |
|:--------|:-------------------|:----------------|
| **claude-code** （默认） | `<root>/.claude/skills` | `~/.claude/skills` |
| **opencode** | `<root>/.opencode/skills` | `~/.config/opencode/skills` |
| **pi** | `<root>/.pi/skills` | `~/.pi/agent/skills` |
| **codex** | `<root>/.agents/skills` | `~/.agents/skills` |
| **agents** （可移植） | `<root>/.agents/skills` | `~/.agents/skills` |
可移植的 **`agents`** 框架写入通用 `.agents/skills` 位置，opencode、pi 和 codex 都读取它 — 是一种一次性覆盖多个通用框架的方法。 `--scope` 选择每个框架安装的 `<root>` （**用户** = `$HOME`，默认；**项目** = git 根目录，否则为当前目录）； `--target DIR` 完全覆盖范围和框架。 `naba skills upgrade` 刷新您以前安装的所有目标（在安装收据中跟踪），并在出错时继续 — 因此，多框架安装可以通过一次调用保持同步。
> 旧的 `--surface claude|agents` 标志仍然作为已弃用的隐藏别名（`claude` → `claude-code`，`agents` → `agents`）并打印弃用通知。优先使用 `--harness`。
### 健康检查
`naba doctor` 验证您的环境，如果任何检查失败，则退出非零：
```bash
naba doctor # 检查技能安装、API 密钥、模型、配置
naba doctor --json # 结构化输出
naba doctor --harness agents # 检查 agents 框架安装
```
它报告：已安装技能并与此二进制文件匹配（存在完整性标记，最新、完整、未修改）；有效的提供商的 API 密钥存在（它解析有效的提供商 — CLI `--provider`，否则配置 `provider`，否则环境密钥自动检测 — 然后检查该提供商的密钥）；密钥实时有效（廉价的 `models.list` 调用，无图像成本）；配置的模型可达；配置可解析；以及二进制文件版本。
### 技能门控预检
`naba skills preflight --json` 是一个快速的 **离线** 门控， `/naba` 技能在触发时运行（`naba doctor` 是完整的、涉及网络的扫描；预检是轻量级的每次调用检查）：
```bash
naba skills preflight --json
```
它报告三个轴： **身份验证** （有效的提供商的密钥存在 — 无网络调用），**技能** （已安装的技能树与此二进制文件匹配），以及 **二进制** — 一个三状态 `up_to_date | update_available | unknown`。二进制轴读取离线更新检查缓存；缓存丢失/过时时为 `unknown` 且 **非阻塞** （全新安装始终通过）。整体状态为 `ok`，除非身份验证或技能失败（`auth_missing` / `skills_outdated`）；门控在非 `ok` 状态时退出非零。
### 隐式触发
您很少自己输入 `/naba`。技能的描述告诉代理在您的请求与图像任务匹配时 **自动触发** — 即使是普通语言。以下任何一项都会触发正确的子命令，无需斜杠命令：
- "制作一个白色背景的红色苹果图像" → `generate`
- "删除 logo.png 的背景" → `edit`
- "锐化和降噪这张旧照片" → `restore`
- "一个 256 和 512 的火箭船应用程序图标" → `icon`
- "无缝的电路板纹理" → `pattern`
- "绘制身份验证流程图" → `diagram`
技能 **跳过** 请求可编辑的图表源（d2/mermaid 文本）— `naba diagram` 生成渲染的图像，而不是可编辑的源。显式 `/naba <子命令>` 调用始终有效，也是您想要特定子命令时的可靠触发器。
### 子命令
调用为 `/naba <子命令> [参数]`；运行 `/naba help` 以打印调度表。
| 子命令 | 目的 |
|:-----------|:--------|
| `/naba generate` | 从文本提示生成图像 |
| `/naba edit` | 使用文本指令编辑现有图像 |
| `/naba restore` | 恢复或增强现有图像 |
| `/naba icon` | 生成应用程序图标（可选多尺寸） |
| `/naba pattern` | 生成无缝图案和纹理 |
| `/naba diagram` | 生成技术图表图像 |
| `/naba story` | 生成顺序图像系列 |
| `/naba storyboard` | 复合：故事序列 + 每帧编辑 |
| `/naba batch` | 复合：协调多个 `naba` 调用（图标套件、资产管道） |
| `/naba brand-kit` | 复合：图标 + 图案 + 英雄图像集 |
七个内联子命令直接运行单个 `naba` CLI 调用；三个复合体（`storyboard`、`batch`、`brand-kit`）调度一个运行多调用循环并返回紧凑摘要的子代理。共享指南、反模式和全局标志表在 `skills/naba/SKILL.md` 中生活。
## 全局标志
| 标志 | 描述 |
|:-----|:------------|
| `--json` | 输出结构化 JSON（自动启用管道输出） |
| `-o, --output` | 输出文件路径 |
| `-q, --quiet` | 禁止进度输出 |
| `-m, --model` | 覆盖模型（需要 CLI 上的 `--provider`） |
| `--provider` | 提供商：`gemini`、`openrouter` 或 `bedrock` （参见 [提供商](#提供商)） |
| `--no-input` | 禁用交互式提示 |
生成命令还接受 `--aspect`、`--resolution` （imageConfig） 和 `--quality` （每个提供商 — 参见 [模型和定价](#models--pricing)）；参见 [生成图像](#generate-images) 部分。
## 输出格式
提供商返回实际图像格式（Gemini 返回 **JPEG**；OpenRouter 的 `/api/v1/images` 返回 **PNG**）。`naba` 以匹配的扩展名写入文件：如果您的 `-o` 路径使用不同的扩展名（例如 `-o hero.png` 对抗 JPEG 响应），`naba` 会在磁盘上纠正它（`hero.jpg`），在标准错误上发出警告，并在 JSON 中报告两种格式（`requested_format` / `actual_format`），以便您可以决定是否需要生成后转换。
## JSON 输出
当使用 `--json` （或输出到管道）时，输出包括：
```json
{
"path": "/absolute/path/to/image.jpg",
"command": "generate",
"prompt": "a red apple",
"elapsed_ms": 3200,
"params": {
"style": "watercolor",
"aspect": "16:9",
"resolution": "2K"
},
"requested_format": "png",
"actual_format": "jpeg"
}
```
`requested_format` 仅在 `-o` 隐含格式时出现；`actual_format` 反映响应 mimeType。当扩展名被纠正时，它们会有所不同。
## 退出代码
| 代码 | 含义 |
|:-----|:--------|
| 0 | 成功 |
| 1 | 一般错误 |
| 2 | 用法错误 |
| 3 | 身份验证错误 |
| 4 | 速率限制超过 |
| 5 | API 错误 |
| 10 | 文件 I/O 错误 |
## 贡献
欢迎贡献 — 包括 AI 辅助的贡献（`naba` 本身就是使用 AI 代理构建的）。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解项目如何构建、每个更改必须经过的本地验证门控、如何提出问题以及 AI 辅助贡献政策。请同时阅读 [行为准则](CODE_OF_CONDUCT.md)；根据 [安全政策](SECURITY.md)，请私下报告安全问题。
## 许可证
MIT - 参见 [LICENSE](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器