imgrelay 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -150
- package/dist/index.mjs +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,191 +1,105 @@
|
|
|
1
1
|
# ImgRelay
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
在 Codex 中用自然语言调用第三方中转站生成图片，保存并展示原图。
|
|
4
|
+
配置一次供应商、密钥和默认模型，即可在不同项目中复用。
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
ImgRelay 由 CLI 和 Codex Skill 组成：CLI 负责配置、请求和文件保存，Skill 负责理解需求、
|
|
7
|
+
准备提示词和呈现结果。目前支持 OpenAI Images 兼容接口的文生图。
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## 快速上手
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
### 1. 安装 CLI 和 Skill
|
|
12
|
+
|
|
13
|
+
需要 Node.js 22.20+（22.x）或 24.x。在终端运行：
|
|
12
14
|
|
|
13
15
|
```bash
|
|
14
16
|
npm install -g imgrelay
|
|
15
|
-
npx skills add bingwu-devkit/imgrelay --skill imgrelay
|
|
17
|
+
npx skills add bingwu-devkit/imgrelay --skill imgrelay
|
|
16
18
|
```
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
两者分开安装：npm 安装提供 `imgrelay` 命令，Skills CLI 安装 Skill。
|
|
21
|
+
按 Skills CLI 的提示选择 Codex、安装范围和安装方式。
|
|
22
|
+
|
|
23
|
+
### 2. 配置中转站
|
|
24
|
+
|
|
25
|
+
在交互终端中运行，`relay` 是你为供应商取的名称：
|
|
19
26
|
|
|
20
27
|
```bash
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
npx skills add ./skills --skill imgrelay --agent codex --global --copy
|
|
28
|
+
imgrelay provider add relay
|
|
29
|
+
imgrelay provider use relay
|
|
30
|
+
imgrelay doctor --provider relay
|
|
25
31
|
```
|
|
26
32
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
33
|
+
按提示输入 API 基础地址、API Key 并选择默认模型；地址通常形如
|
|
34
|
+
`https://relay.example/v1`。密钥隐藏输入，模型列表不可用时可以手动填写模型 ID。
|
|
35
|
+
完成交互后统一保存配置，这个流程不会生成图片。
|
|
30
36
|
|
|
31
|
-
|
|
32
|
-
查询失败时可手动填入模型 ID，配置流程不生成图片：
|
|
37
|
+
使用 Cubence 时，可以用预设创建配置并设为默认：
|
|
33
38
|
|
|
34
39
|
```bash
|
|
35
|
-
imgrelay provider add cubence --preset cubence
|
|
36
|
-
imgrelay provider use cubence
|
|
37
|
-
imgrelay doctor --provider cubence
|
|
40
|
+
imgrelay provider add cubence --preset cubence --default
|
|
38
41
|
```
|
|
39
42
|
|
|
40
|
-
|
|
43
|
+
配置保存在用户主目录的 `~/.imgrelay/`，跨项目复用。API Key 明文存储在 `config.json`，
|
|
44
|
+
请通过上述交互命令输入密钥，无需发给 Codex。`doctor` 检查配置和模型接口；
|
|
45
|
+
检查成功不代表所有生成参数都可用。
|
|
41
46
|
|
|
42
|
-
|
|
43
|
-
imgrelay provider edit cubence
|
|
44
|
-
```
|
|
47
|
+
### 3. 在 Codex 中生成图片
|
|
45
48
|
|
|
46
|
-
|
|
47
|
-
不要求以 `sk-` 开头；删除供应商会一并移除其密钥。
|
|
48
|
-
非交互命令可修改已有供应商的其他参数或显式清除密钥：
|
|
49
|
+
进入要保存图片的项目，向 Codex 发出请求，例如：
|
|
49
50
|
|
|
50
|
-
```
|
|
51
|
-
imgrelay
|
|
52
|
-
|
|
51
|
+
```text
|
|
52
|
+
$imgrelay 生成一张戴宇航员头盔的猫，用作博客封面，横版。
|
|
53
|
+
|
|
54
|
+
用 imgrelay 的 relay 供应商生成两张极简风格的森林插画，保存到 ./images。
|
|
55
|
+
|
|
56
|
+
用 imgrelay 生图，提示词请原样使用：一只橘猫趴在窗边，午后自然光。
|
|
53
57
|
```
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
Skill 使用你指定的供应商、模型和参数，未指定时沿用本机默认配置。
|
|
60
|
+
对于简短需求，Codex 会围绕用途补足提示词；明确要求原样使用时保留原文。
|
|
61
|
+
生成后展示已保存的图片，并说明供应商、请求模型和保存位置。
|
|
56
62
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
| `provider add <名称>` | 添加供应商；可显式选择 `--preset cubence` |
|
|
60
|
-
| `provider list` | 列出摘要及默认项 |
|
|
61
|
-
| `provider show <名称>` | 查看脱敏配置 |
|
|
62
|
-
| `provider edit <名称>` | 修改配置与凭据，`--clear-key` 清除凭据 |
|
|
63
|
-
| `provider use <名称>` | 设置默认供应商 |
|
|
64
|
-
| `provider remove <名称>` | 移除供应商及配置中保存的密钥 |
|
|
65
|
-
| `models [--provider 名称] [--refresh]` | 查询模型或查看 15 分钟缓存 |
|
|
66
|
-
| `doctor [--provider 名称]` | 检查配置、鉴权和模型查询，不生成图片 |
|
|
67
|
-
| `generate` | 生成并保存图片及记录 |
|
|
63
|
+
默认输出在当前工作目录的 `output/imagegen/`，包含原图和生成记录。
|
|
64
|
+
也可以在请求中指定目录或文件名。
|
|
68
65
|
|
|
69
|
-
|
|
70
|
-
JSON 模式禁用交互，标准输出仅包含一个最终 JSON，进度在标准错误。
|
|
66
|
+
## 直接使用 CLI
|
|
71
67
|
|
|
72
|
-
|
|
68
|
+
不通过 Codex 也可以生成图片：
|
|
73
69
|
|
|
74
70
|
```bash
|
|
75
71
|
imgrelay generate --prompt "一只戴宇航员头盔的猫"
|
|
76
|
-
imgrelay generate --prompt "
|
|
77
|
-
imgrelay generate --prompt "
|
|
78
|
-
imgrelay generate --prompt "一只戴宇航员头盔的猫" --output-dir ./images --filename cat.png --timeout 600
|
|
72
|
+
imgrelay generate --provider relay --prompt "极简风格的森林插画" --n 2 --json
|
|
73
|
+
imgrelay generate --prompt "一只橘猫趴在窗边" --output-dir ./images --filename cat.png
|
|
79
74
|
```
|
|
80
75
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
单次参数覆盖不会改动持久配置。参数值按“命令 → 供应商默认 → 工具默认”合并；
|
|
85
|
-
工具仅默认数量为 1，不强制尺寸、质量或格式。未知模型允许调用，模型列表缺失不阻断生成。
|
|
86
|
-
|
|
87
|
-
图片保留原始字节；Base64 优先于 URL，图片下载及重定向不带 API Key。
|
|
88
|
-
记录实际格式、尺寸和字节数。默认文件名包含 UUID 和序号；自定义文件名的扩展名按实际格式，
|
|
89
|
-
多图追加序号。默认不覆盖文件，显式 `--overwrite` 才允许覆盖。
|
|
90
|
-
|
|
91
|
-
默认生成超时为 600 秒；只读请求最多重试一次，生成 POST 不自动重试。
|
|
92
|
-
超时或断网意味着结果未知，上游可能仍在生成。不会自动换模型、降参数或拆成多次付费请求。
|
|
93
|
-
每张图片最多 32 MiB，上游 JSON 最多 128 MiB；某项失败后继续保存其他结果。
|
|
94
|
-
|
|
95
|
-
## 中转站兼容配置
|
|
96
|
-
|
|
97
|
-
同协议中转站通过 `provider add` 接入，不新增品牌客户端。
|
|
98
|
-
Base URL 支持主机地址、`/v1`、自定义前缀及标准完整生成 URL，并集中处理路径拼接。
|
|
99
|
-
`doctor` 展示最终地址；认证模型接口成功只证明模型查询可用，不证明生成及全部参数可用。
|
|
100
|
-
|
|
101
|
-
`provider add/edit` 还支持 `--generation-path`、`--models-path`、默认生成参数、
|
|
102
|
-
`--timeout` 和 `--capabilities-file`。端点覆盖仅接受路径，不能更换主机。
|
|
103
|
-
能力覆盖文件是按模型 ID 索引的 JSON：
|
|
104
|
-
|
|
105
|
-
```json
|
|
106
|
-
{
|
|
107
|
-
"vendor-model": {
|
|
108
|
-
"source": "provider_override",
|
|
109
|
-
"parameters": {
|
|
110
|
-
"n": { "min": 1, "max": 1 },
|
|
111
|
-
"quality": { "values": ["high"] },
|
|
112
|
-
"outputFormat": { "values": ["png", "webp"] },
|
|
113
|
-
"responseFormat": { "supported": false }
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
}
|
|
117
|
-
```
|
|
76
|
+
本次参数覆盖不会修改默认配置。CLI 原样发送 `--prompt`，不自动改写提示词。
|
|
77
|
+
尺寸、质量和格式是否可用取决于模型与供应商；完整选项见 `imgrelay generate --help`。
|
|
118
78
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
`IMGRELAY_CONFIG_DIR` 可覆盖目录，相对路径基于当前工作目录解析。
|
|
128
|
-
|
|
129
|
-
供应商配置与明文 API Key 集中保存在版本 1 的 `config.json`，模型缓存保存在同目录的
|
|
130
|
-
`models-cache.json`。文件使用系统默认权限，不做加密、专用 ACL 或权限校验。
|
|
131
|
-
隐藏输入的密钥保存在供应商的 `apiKey` 字段。配置结构例如：
|
|
132
|
-
|
|
133
|
-
```json
|
|
134
|
-
{
|
|
135
|
-
"schemaVersion": 1,
|
|
136
|
-
"defaultProvider": "relay",
|
|
137
|
-
"providers": {
|
|
138
|
-
"relay": {
|
|
139
|
-
"protocol": "openai-images",
|
|
140
|
-
"baseUrl": "https://relay.example/v1",
|
|
141
|
-
"apiKey": "your-api-key",
|
|
142
|
-
"defaultModel": "vendor-model"
|
|
143
|
-
}
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
```
|
|
79
|
+
| 常用命令 | 用途 |
|
|
80
|
+
| ---------------------------------- | ------------------------------ |
|
|
81
|
+
| `imgrelay provider list` | 查看供应商和默认项 |
|
|
82
|
+
| `imgrelay provider show relay` | 查看供应商的脱敏配置 |
|
|
83
|
+
| `imgrelay provider edit relay` | 修改配置或通过隐藏输入更新密钥 |
|
|
84
|
+
| `imgrelay provider use relay` | 切换默认供应商 |
|
|
85
|
+
| `imgrelay models --provider relay` | 查询模型列表，支持 `--refresh` |
|
|
86
|
+
| `imgrelay doctor --provider relay` | 检查配置和模型接口，不生成图片 |
|
|
147
87
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
原始 Base64 或带访问凭据的下载链接。图片和生成记录默认保存在当前工作目录的
|
|
151
|
-
`output/imagegen/`，可通过 `--output-dir` 指定。
|
|
152
|
-
生成记录含提示词及请求参数，应按本机文件管理方式处理。
|
|
153
|
-
|
|
154
|
-
JSON 外层固定为 `schemaVersion`、`command`、`status`、`data`、`error`。
|
|
155
|
-
生成结果的 `data.images` 包含本地路径、实际格式/尺寸/字节数，另有请求模型、上游报告模型
|
|
156
|
-
（仅在返回时）、失败项、用量和 `recordPath`。使用 `error.category` 判断失败类型。
|
|
157
|
-
请求提交前保存记录，单项保存失败保留其他图片，记录保存失败仍返回已保存路径。
|
|
158
|
-
`data.endpoint` 是本次实际生成地址，`data.capabilityEvidence` 保留已知模型与供应商覆盖的
|
|
159
|
-
来源及已有验证时间；未知能力显示为空，不从一次成功调用推断其他能力。
|
|
160
|
-
|
|
161
|
-
| 退出码 | 含义 |
|
|
162
|
-
| ------ | ------------------------------------ |
|
|
163
|
-
| 0 | 成功 |
|
|
164
|
-
| 1 | 内部错误 |
|
|
165
|
-
| 2 | 输入、配置、凭据或本地能力校验错误 |
|
|
166
|
-
| 3 | 上游错误、无效图片响应或生成结果未知 |
|
|
167
|
-
| 4 | 图片或记录保存失败 |
|
|
168
|
-
| 5 | 部分图片成功 |
|
|
169
|
-
| 130 | 用户中断；不能保证取消上游请求 |
|
|
170
|
-
|
|
171
|
-
## 验证与发布
|
|
88
|
+
命令支持 `--help` 和 `--json`。JSON 模式关闭交互，标准输出只有一个最终 JSON，
|
|
89
|
+
进度输出到标准错误；新增供应商或更新密钥时使用不带 `--json` 的交互命令。
|
|
172
90
|
|
|
173
|
-
|
|
174
|
-
pnpm check
|
|
175
|
-
node scripts/package-smoke.mjs
|
|
176
|
-
```
|
|
91
|
+
## 使用须知
|
|
177
92
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
93
|
+
- 图片按原始字节保存，默认不覆盖已有文件；需要覆盖时显式使用 `--overwrite`。
|
|
94
|
+
- 生成默认等待 600 秒。超时或断网后，上游可能仍在生成；工具不会自动重提、换模型或补单。
|
|
95
|
+
- 部分图片失败时仍保留已保存的结果；非零退出码不一定意味着没有图片。
|
|
96
|
+
- 模型列表不可用时仍可手动指定模型；图片编辑及非 OpenAI Images 协议目前不支持。
|
|
181
97
|
|
|
182
|
-
|
|
183
|
-
默认关闭自动发布；配置 npm Trusted Publisher 后才设置仓库变量 `ENABLE_RELEASE=true`。
|
|
98
|
+
## 详细文档
|
|
184
99
|
|
|
185
|
-
|
|
186
|
-
[
|
|
187
|
-
[兼容性参考](https://github.com/bingwu-devkit/imgrelay/blob/main/docs/provider-compatibility-design.md)。
|
|
100
|
+
- [CLI 参考](https://github.com/bingwu-devkit/imgrelay/blob/main/docs/cli-reference.md)：完整命令、兼容配置、存储方式、JSON 结果与退出码。
|
|
101
|
+
- [开发与发布](https://github.com/bingwu-devkit/imgrelay/blob/main/docs/development.md)：源码运行、验证、打包和发布流程。
|
|
188
102
|
|
|
189
103
|
## 许可证
|
|
190
104
|
|
|
191
|
-
[MIT](./LICENSE.md)
|
|
105
|
+
[MIT](./LICENSE.md)。
|
package/dist/index.mjs
CHANGED
package/package.json
CHANGED