北极星生图 · 使用指南
两个能力：生图（generate）、编辑图（edit）。配套 task 续查、retry 补齐。
一条命令进去，一行 JSON 出来，所有等待都发生在脚本进程里——不需要分多轮去查任务状态。
> 命令路径说明：下文所有命令都以 python "$SKILL_PATH/scripts/bjx_image.py" 开头，$SKILL_PATH 指本技能所在目录（市场安装默认是 ~/.workbuddy/skills/polaris-image）。若 $SKILL_PATH 未定义，先执行 SKILL_PATH=~/.workbuddy/skills/polaris-image 即可。
一、首次配置
本技能不自带生图服务，需要自备 API Key。
还没有 Key 的话，向技能提供方索取——本技能不发放 Key、不代管账号，也不提供注册或购买入口。
拿到 Key 后跑一次：
python "$SKILL_PATH/scripts/bjx_image.py" init --api-key <你的KEY>
写入 ~/.baizhi/config.json，并顺带验证 Key 是否可用。成功返回：
{"ok":true,"config":"C:/Users/xxx/.baizhi/config.json","api_key":"sk-abc...wxyz","verified":true}
verified 为 false 时说明 Key 不可用（无效、过期或无权限），重新要一个即可，不用改代码。
不想写文件也可以：环境变量 BAIZHI_API_KEY，或每条命令加 --api-key。
> 升级版本不会影响这里已配置的 Key——配置存在用户目录，不在技能目录里。
二、生成图片
python "$SKILL_PATH/scripts/bjx_image.py" generate \
--prompt "竖版招聘海报，深蓝渐变星空，金色北极星，下方两位职场人" \
--ratio 2:3 --count 1 \
--out ./output
返回：
{"ok":true,"kind":"generate","elapsed_s":78.3,
"task_ids":["task_1c52..."],
"files":["C:\\...\\output\\20261102-160158_generate_2x3_01.png"],
"images":[{"file":"...","bytes":1786454,"w":1024,"h":1536}],
"errors":[]}
直接读 files 里的路径去展示或交付，不要再去查任务状态。
三、编辑图片
# 本地图，自动上传
python "$SKILL_PATH/scripts/bjx_image.py" edit --image ./cover.png --prompt "改成赛博朋克海报风格"
# 公网图，跳过上传
python "$SKILL_PATH/scripts/bjx_image.py" edit --image https://example.com/a.png --prompt "换成水彩"
# 多张参考图
python "$SKILL_PATH/scripts/bjx_image.py" edit --image a.png b.png --prompt "把图1的商品放进图2的场景"
edit 的参考图必须是公网可读地址，本地文件由脚本先申请上传凭证再 PUT 上传，用户无需关心。
四、参数
| 参数 | 说明 | 默认 |
|---|---|---|
--prompt |
提示词，必填 | — |
--ratio |
比例，原样透传不校验 | 服务端默认 |
--count |
张数，1–4 走一个任务，>4 自动拆多个任务 | 1 |
--seed |
随机种子，复现同一张图用 | 随机 |
--out |
输出目录 | ~/Downloads/polaris-images |
--timeout |
单任务超时秒数 | 300 |
--stagger |
多任务提交间隔秒数，别设 0 | 4 |
--dry-run |
只打印请求体，不实际生成 | 关 |
--proxy |
代理地址，如 http://127.0.0.1:7890。不填则直连，忽略系统代理环境变量 |
直连 |
比例该怎么选
9 种全部实测可用，直接按用途挑：
| 用途 | 比例 | 实际尺寸 |
|---|---|---|
| 海报（竖） | 2:3 |
1024×1536 |
| 人像（竖） | 3:4 |
1086×1448 |
| 故事 / 手机全屏 | 9:16 |
— |
| 正方形 | 1:1 |
1254×1254 |
| 演示文稿 | 4:3 |
— |
| 照片打印 | 3:2 |
1536×1024 |
| 宽屏 | 16:9 |
— |
| 电影感（超宽） | 21:9 |
1914×822 |
| 横幅 | 5:2 |
1983×793 |
传了奇怪的值会返回 payload_error，改参数重试即可，放心试。
五、失败怎么处理
| 返回的 status | 含义 | 正确动作 |
|---|---|---|
completed |
已出图并落盘 | 读 files |
timeout |
超时了，任务还在后台跑 | task --task-id <id> 续查，不要重新生成 |
failed |
后端明确失败 | retry --task-id <id>，比重新生成省 |
python "$SKILL_PATH/scripts/bjx_image.py" task --task-id task_xxx # 续查 + 自动下载
python "$SKILL_PATH/scripts/bjx_image.py" retry --task-id task_xxx # 只补缺的那几张
失败时 stdout 会直接给一行 resume 提示，照着跑即可。
超时后绝对不要重新提交。 任务 ID 已写进 ~/.baizhi/registry.jsonl，续查不会重跑一次。
六、报错对照
| error | 原因 | 处理 |
|---|---|---|
no_api_key |
没配置 | 向提供方索取 Key，然后跑 init |
unauthorized |
Key 无效、过期或无权限 | 检查或更换 Key |
payload_error |
参数无效 / 参考图读不到 | 改参数重试 |
not_found |
task_id 不存在 | 核对 registry.jsonl |
provider_error |
上游超时/不可用 | retry |
upload_failed |
本地图上传失败 | 检查文件与格式 |
network_error |
网络不通或代理失效 | 见下一节 |
download_failed |
图片下载失败 | 检查网络，再 task --task-id 续查 |
七、网络与代理
脚本默认直连，不读系统代理环境变量。 这是刻意设计的。
Windows / macOS 上常见的 http_proxy、https_proxy，可能是运维工具或代理软件卸载后残留的失效地址。Python 默认会照着它走，结果是所有请求超时，报错只有一句 WinError 10060——非常容易被误判成 Key 失效或者服务端挂了。
遇到这种情况，报错会直接告诉你怎么判断：
network_error: <urlopen error [WinError 10060] 由于连接方在一段时间后没有正确答复...>
（已忽略系统代理（http_proxy=http://127.0.0.1:52581）直连。若本机必须经代理上网，
请设 BAIZHI_PROXY=<代理地址> 或加 --proxy）
| 现象 | 含义 | 处理 |
|---|---|---|
| 提示「已忽略系统代理」但仍然失败 | 真的是网络不通 | 查 DNS / 防火墙 / 换网络 |
| 本机必须经代理才能上网 | — | --proxy http://127.0.0.1:7890 或设 BAIZHI_PROXY |
| 日志出现「经代理访问：xxx」并失败 | 你指定的代理本身不通 | 去掉 --proxy 回直连 |
优先级：--proxy > 环境变量 BAIZHI_PROXY > 直连。
八、怎么确认走的是本技能
同一台机器上如果还装了别的生图技能，模型可能选了别家，报错就来自别家——那些报错跟本技能无关，处理方式也不同。三条辨识：
- 成功：单行 JSON，含
"ok": true和files（本地文件路径） - 失败：单行 JSON，含
"ok": false、error、message - 不会出现
Submit failed (code 3203)这类英文前缀，也不会停下来等y/n输入
看到英文报错、或里面提到别的域名、ak_ 开头的 Key，就不是本技能。让用户点名"用北极星生图"再跑一次即可。
九、注意
- 别突发提交。 实测同时发 5 个任务会挂 3 个，错峰 4 秒则全部成功。用
--count 4一次出 4 张，比发 4 个任务安全得多。 - 最高约 157 万像素（2:3 出 1024×1536），印刷级尺寸需自行放大。
- 中文长标题容易糊，控制在 5 字以内成功率最高；海报文字建议后期加。
- 觉得慢或不确定参数，先用
--dry-run看请求体，不会实际生成。
