[0xFANGO]

合并前置（已满足）

@marswave/listenhub-sdk@0.0.22 已发布。提交 a160814 已把 CLI 的 pnpm-lock.yaml 同步到该版本；pnpm install --frozen-lockfile、pnpm ready 与 pnpm build 均已通过。精确 head CI 已成功：run 32655205447。

目标

marswaveai/listenhub-ralph#728 素材流水线的步骤二：agent 按 CSV 逐行批量生成 Labnana 素材。2026-08-22 拍板放弃 ego-browser 网页操作（每张图要多轮 DOM 交互，labnana 的下拉选项只在展开态存在于 DOM、跨轮次选择器必然失效，批量不可用），改用 CLI。

改了什么

新 labnana 命令组

listenhub labnana image create   # --prompt --reference(可重复) --model --aspect-ratio
                                 # --size --quality -n --public --no-wait --timeout -j
listenhub labnana image list     # --scope me|public
listenhub labnana image get <id>
listenhub labnana video create   # 参数面与 listenhub video create 一致

不复用 listenhub image：二者同后端但不同路由（v1/images vs /v1/banana/images）、参考图上限与独有入参都不同，混进一个命令会让 --model / --reference 的语义分叉。

-n = 客户端并行扇出

后端 POST /v1/banana/images 没有张数入参，网页端的「N 张」本身就是 n 个并行请求共享一个 batchId（Featured/Trending 据此折叠分组）。CLI 复刻这个语义：生成一个 batchId、发 N 个并行请求、全部带同一个值。

• -n 1 不带 batchId，与网页端单图生成逐字一致。
• 上限 10：非订阅用户后端 IP 限流是 10 次 / 10 分钟，再往上一定撞限流，与其把限流错误当常态不如先在客户端挡住。
• 撞限流的分片按失败计并报出（区分 rate limited 与其它错误），命令以非零码退出，已成功的 id 仍然打印——CSV 回写要得到部分成功的结果。
• -n 1 时错误原样抛给 handleError，保留既有退出码语义（2=auth、3=timeout）。
• 参考图只上传一次，N 个请求复用同一批 URL。

技术债 2：域名表去重

_shared/domain.ts 的 BASE_URLS 改为读 SDK 导出的 DOMAIN_BASE_URLS，删掉重复表与那条 ponytail: 注释（它的升级路径写的就是「SDK 发版后改为从 SDK 导出的映射读取」）。

技术债 3：删除 --reference-url

与 --reference 语义重叠的隐藏兼容项（.hideHelp()、空描述、两个 README 都没写）。核对无外部调用方：本工作区 9 个仓库 + marswaveai/skills（确实在用 listenhub image create）全量 grep reference-url|referenceUrl 零命中。

视频侧：createVideo 加一个 surface 参数切换路由，复用同一份参数构造，不复制第二份 schema。

验证

项	结果
npx vp check（fmt + lint + 类型）	✅ All 85 files are correctly formatted / Found no warnings, lint errors, or type errors in 75 files
npx vp test run	✅ Test Files 11 passed，Tests 94 passed（新增 5 条）
npx vp pack + node dist/cli.mjs --help	✅ 构建通过，labnana 出现在命令表
SDK lockfile	✅ pnpm install --frozen-lockfile 解析 @marswave/listenhub-sdk@0.0.22
本地补充验证	✅ pnpm ready：85 files check 通过、94 tests passed；pnpm build 通过
精确 head CI	✅ run 32655205447（head a16081480d635fad6fd4b3daa92d5f4093fecde6）

新增 tests/labnana.test.ts：n>1 发 n 个请求且共享同一 batchId、n=1 不带 batchId、撞限流的分片被报出且以非零码退出、越界 -n 与超过 14 张参考图先在客户端拒绝（不静默截断）。

tests/openapi/client.test.ts 的 SDK mock 从「只提供 OpenAPIClient」改成 importOriginal 展开——domain.ts 现在还会从 SDK 读 DOMAIN_BASE_URLS，原写法会让它变成隐形的 undefined。这是补强 mock，不是放松断言。

config show 前后输出对比（技术债 2 的验收）

同一份 XDG_CONFIG_HOME，改动前后各跑三种域设置，diff 完全一致：

--- default (auto) ---
Domain:           auto
Commands:         https://api.listenhub.ai/api (default)
openapi commands: https://api.marswave.ai/openapi (default)
--- pinned app ---
Domain:           app
Commands:         https://api.listenhub.app/api (pinned)
openapi commands: https://api.listenhub.app/openapi (pinned)
--- pinned default ---
Domain:           default
Commands:         https://api.listenhub.ai/api (pinned)
openapi commands: https://api.marswave.ai/openapi (pinned)

image create --help 回归（技术债 3 的验收）

--reference-url 已不出现（本来 .hideHelp() 也不出现），--reference 与其余参数逐字不变。既有 listenhub image create 的行为未改动。

还没跑的

真实跑通 labnana image create -n 2 拿到两个 imageId 属于 issue 验收，但会真实消耗 fangge@marswave.ai 的积分，且需要人先做一次 listenhub auth login（云端容器没有登录态）。SDK 发版后由人触发一次真实批次验证。同理，「现有 OAuth token 对 /v1/banana/* 是否直接生效」这条 issue Risk：代码侧已确认后端只有一个 router 与一个鉴权闸，banana controller 与其它 controller 一起被 glob 进同一份列表（src/controller/index.ts:52-63），token 覆盖是结构性的；但没有真实请求验证过。

实现期假设

1. -n 上限 10，理由如上；没有实测数据支撑这个具体数字。
2. 保留 SDK 默认的 429 重试（2 次，ky 退避），没有为扇出调低 maxRetries。issue 写的是「沿用后端既有 IP/用户限流，撞限流按失败计并报出」，重试后仍失败才计失败，符合这条。
3. labnana video 只做了 create，没有 get/list——Contract 列的命令面就是这些。--no-wait 提交视频后目前没有对应的查询子命令，需要的话再加。
4. 依赖声明用 >=0.0.22 <0.1.0 而不是钉死某个版本：本 PR 不能知道 SDK 实际会发成哪个号（版本号交给发版流程），这个区间表达的是「含 banana 与 DOMAIN_BASE_URLS 的那一版及之后」。

风险判定

scripts/route-gates.py 参考信号：risk=high、reasons=["auth","money"]、nonDowngradable=false、nonDowngradableFiles=[]。

判定：快车道（覆盖参考信号）。 本次新增提交仅将已发布 SDK 写入 lockfile；完整 diff 中的 auth / money 命中来自 CLI 命令与 SDK 类型文本，不修改鉴权、扣费、结算、补偿或回填代码。全部本地验证已通过，变更不影响既有 listenhub image 命令。

Staging

命中 issue 白名单例外第 3 条：scripts/staging-git.sh 没有 listenhub-cli 的 staging 分支映射，本仓不发 staging。

🤖 Generated with Claude Code

https://claude.ai/code/session_011PmBrtFBVUwG3bFaQzrBJ4

---

Generated by Claude Code

发布修订（当前）

本节覆盖此前指向 a160814 的发布前置与精确 CI：CLI 版本已从 0.0.19 升为未占用的 0.0.20，当前 head 为 5cbb9c82363d9dc2649ac2f579187ca58131f5bf。pnpm install --frozen-lockfile、pnpm ready（85 files / 94 tests）和 pnpm build 均通过；精确 head CI run 32655610197 已成功。

此次补充提交仅上调 npm 发布版本，不改变 CLI 功能或 SDK 锁定版本。