bukesiyi-cli 0.1.2 → 0.3.0

package/README.md

@@ -8,9 +8,9 @@ API 调用是《不可思议》给程序用的入口：你的脚本、流水线
 
 装之前先看这几条：
 
-- **这一版只做登录这一件事**，一共三条命令：`buke login`、`buke whoami`、`buke logout`——用一把 API 密钥登录、确认它能用、把它稳妥地保存在本机。下单、查进度、下载成片这些命令现在没有，会在后续版本提供。
-- **API 调用尚未对外开通。** 现在逐个账号开通，需要联系《不可思议》的客服为账号开通（联系方式见文末「联系我们」）。没有开通的账号拿不到密钥；装了这个工具，也登录不了。
-- **密钥在网页上创建，不在这个工具里。** 已经开通的账号登录《不可思议》，在右上角头像菜单的「账号设置」里打开「API 密钥」，在那里创建、查看和吊销：<https://buke41.com/account/api-keys>。完整密钥只在创建成功的那一刻显示一次。没有开通的账号在「账号设置」里看不到这个入口。
+- **这一版能下单、查进度、下载成片**，覆盖三条产线：渲染短片（`buke shorts …`）、商品视频（`buke videos …`）和短剧（`buke drama …`），另有产品建档（`buke products …`）和余额（`buke balance`）。登录三件套（`buke login`、`buke whoami`、`buke logout`）负责把一把 API 密钥登录并稳妥地保存在本机。
+- **注册账号都能用。** 登录《不可思议》后自己创建密钥，不用另外申请；遇到问题可以联系客服（联系方式见文末「联系我们」）。
+- **密钥在网页上创建，不在这个工具里。** 账号本人登录《不可思议》，在右上角头像菜单的「账号设置」里打开「API 密钥」，在那里创建、查看和吊销：<https://buke41.com/account/api-keys>。完整密钥只在创建成功的那一刻显示一次。
 
 下面的输出例子都是用这一版实际跑出来的，对面是一个按接口约定应答的本机模拟服务；密钥、家目录、编号是演示用的占位。
 
@@ -26,7 +26,7 @@ npm install -g bukesiyi-cli
 
 ```console
 $ buke --version
-bukesiyi-cli/0.1.2
+bukesiyi-cli/0.3.0
 ```
 
 不想全局安装时，可以用 npx 临时运行，写法是 `npx bukesiyi-cli <命令>`，例如 `npx bukesiyi-cli whoami`。下面的例子都直接写 `buke`。
@@ -95,9 +95,18 @@ $ buke login bk_test_0123456789abcdef_……
 | `buke login` | 取密钥、向服务端确认它可用，然后保存到本机。密钥依次从环境变量 `BUKE_API_KEY`、标准输入、终端粘贴里取 |
 | `buke whoami` | 显示当前这把密钥是谁的、属于哪个团队、权限范围是什么、什么时候到期。设了 `BUKE_API_KEY` 就用它，否则用本机保存的 |
 | `buke logout` | 删除本机保存的密钥。不联网，也不会吊销密钥 |
+| `buke balance` | 查询账户余额：可用多少、冻着多少、已经花了多少 |
+| `buke products create / set-images / confirm-lock` | 产品建档：建一件产品、传产品图、确认外观锁（颜色、廓形、材质）。商品视频下单的前置 |
+| `buke shorts catalog / upload / quote / order / status / download / cancel` | 渲染短片：列模板、托管素材图、报价、下单、查进度、下载成片、取消 |
+| `buke videos create / status / message / confirm / download` | 商品视频：下单、查进度、给导演回话、确认开拍、下载成片 |
+| `buke drama create / status / quote / confirm / cancel / download` | 短剧：下单、查进度（查询本身会推进写稿与排版）、报价、确认开拍、取消、下载成片 |
 | `buke --version` | 显示版本 |
 | `buke --help`、`buke <命令> --help` | 显示用法 |
 
+写命令（下单、传图、确认、取消）都支持 `--idempotency-key <键>`：不给时自动生成一个并在输出里回显，网络重试时原样复用同一把，服务端按同键同内容回放、不会重复扣费。渲染短片的报价哈希与幂等键绑定：`buke shorts quote` 回的 `--quote-hash`，下单时要配同一把 `--idempotency-key` 才对得上。`buke shorts order --wait` 和 `buke videos status --wait` 会轮询到终态：成功退出 0，任务失败退出 9，到 `--timeout`（默认 600 秒）还在跑退出 8。
+
+短剧的确认开拍（`buke drama confirm`）要先取一次当前报价摆出来给人看：不加 `--yes` 只看，退出码 2；加了 `--yes` 才提交这笔布支出，并且用服务端认可的报价哈希核对，报价变过就不会扣费。`buke drama status --wait` 会在终态或停靠时停下：拿到成片退出 0；失败、取消退出 9；停在「要人处理」或「有镜没拍成、可补拍」时退出 0，输出里带原因、缺口与下一步。
+
 通用选项：
 
 | 选项 | 作用 |
@@ -167,12 +176,12 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 | 0 | 成功 | 会 |
 | 2 | 参数或用法不对 | 会 |
 | 3 | 没有登录，或者密钥、账号现在不能用 | 会 |
-| 4 | 余额不足 | 不会 |
+| 4 | 余额不足 | 会 |
 | 5 | 服务端、网络或本机出错 | 会 |
-| 6 | 报价变了 | 不会 |
-| 7 | 请求太频繁，请稍后再试 | 会 |
-| 8 | 等待超时 | 不会 |
-| 9 | 任务失败 | 不会 |
+| 6 | 报价变了 | 会 |
+| 7 | 请求太频繁，请稍后再试；或这一步还没到时候，稍后再来 | 会 |
+| 8 | 等待超时 | 会 |
+| 9 | 任务失败 | 会 |
 | 10 | 要找的东西不存在 | 会 |
 | 130 | 被 Ctrl-C 打断 | 会 |
 
@@ -184,7 +193,7 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 
 出错时，给人看的输出里有一行「（错误码 …）」；加了 `--json` 时，错误码在 `error.code` 里。错误码有两类：
 
-- `OPEN_API_` 开头的是服务端回的：请求送到了，服务端没有接受。报错的第一行是服务端的原话，写明了原因和该怎么办；这类报错带一个请求编号（`--json` 里是 `error.traceId`），联系客服时把它一起给出。退出码按上面那张表：密钥或账号现在不能用是 3，请求太频繁是 7，这个地址上没有接口是 10，服务端出错是 5。
+- `OPEN_API_` 开头的是服务端回的：请求送到了，服务端没有接受。报错的第一行是服务端的原话，写明了原因和该怎么办；这类报错带一个请求编号（`--json` 里是 `error.traceId`），联系客服时把它一起给出。退出码按上面那张表：密钥或账号现在不能用是 3，余额不足是 4，报价变了是 6，请求太频繁或这一步还没到时候是 7，这个地址上没有接口或要找的东西不存在是 10，服务端出错是 5。
 - `CLI_` 开头的是这个工具自己发现的问题：命令的写法、密钥的给法、服务地址、本机的凭据文件、网络。这一版一共有下面这些：
 
 | 错误码 | 退出码 | 怎么办 |
@@ -204,6 +213,8 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 | `CLI_TIMEOUT` | 5 | 等了 15 秒，服务端没有回完。稍后重试；总是超时就检查网络，或者中间有没有代理、防火墙拦着 |
 | `CLI_REDIRECT` | 5 | 服务器要求跳转到别处；为了不把密钥带过去，没有跟随。核对服务地址（报错的括号里是跳转指向的地方），用正确的地址重新登录 |
 | `CLI_BAD_RESPONSE` | 5 | 收到的回应不是约定的格式，多半是中间的网关或别的网站回的，括号里是 HTTP 状态码。状态码是 429 或 5xx 时稍后重试；其余的先核对服务地址，重试多半没有用 |
+| `CLI_WAIT_TIMEOUT` | 8 | `--wait` 等到时限任务还在跑，任务本身没有失败。话里带当前状态；用 `status` 再查，或加 `--timeout` 延长等待 |
+| `CLI_TASK_FAILED` | 9 | 等的那张单或那个任务到了失败的终态，话里是服务端记的原因。改好原因后重新下单（新订单、新幂等键） |
 | `CLI_INTERRUPTED` | 130 | 命令被打断了：按了 Ctrl-C，或者收到了 SIGTERM、SIGHUP（这两种的退出码是 143、129）。需要时重新运行 |
 | `CLI_INTERNAL` | 5 | 工具自己出了没有料到的错，正常使用不应该遇到。把完整的报错和运行的命令（不要带密钥）发给客服，联系方式见文末「联系我们」 |
 
@@ -212,7 +223,7 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 - **内部环境用的是自签证书**：报 `CLI_NETWORK`，冒号后面是 `DEPTH_ZERO_SELF_SIGNED_CERT` 这类证书原因。不要关掉证书校验；用 Node.js 的环境变量 `NODE_EXTRA_CA_CERTS` 指向你们的根证书文件，再运行。
 - **要走代理**：`buke` 默认不读 `HTTP_PROXY`、`HTTPS_PROXY`，设了也是直连。要走代理，再加 Node.js 自己的开关 `NODE_USE_ENV_PROXY=1`：在 Node.js 24.18 上，加了它之后发往 https 地址的请求经 `HTTPS_PROXY` 指的代理出去；在 Node.js 20.19 和 22.19 上，加了它也仍然是直连。开着这个开关时连不上或者超时，出问题的也可能是代理——报错里写的是服务地址，给人看的输出最后会多一行提示。
 
-报错说「没有这个接口」，或者回应是 HTTP 404（退出码是 10；别的网站回的 404 报 `CLI_BAD_RESPONSE`，退出码是 5），原因只有两种：还没有对外开通，或者服务地址写错了。先核对这次有没有给 `--base-url`、环境里有没有 `BUKE_BASE_URL`；地址没错，就是还没有开通，重试没有用。
+报错说「没有这个接口」，或者回应是 HTTP 404（退出码是 10；别的网站回的 404 报 `CLI_BAD_RESPONSE`，退出码是 5），原因只有两种：你连的这个服务没有打开 API 调用，或者服务地址写错了。先核对这次有没有给 `--base-url`、环境里有没有 `BUKE_BASE_URL`；地址没错，就是那个服务没有打开 API 调用，重试没有用。
 
 ## 安全须知
 
@@ -238,8 +249,8 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 ## 联系我们
 
 - 网站：<https://buke41.com>
-- 客服邮箱：<winrock.inc@outlook.com>。为账号开通、这份说明没写到的地方、用的时候遇到的问题，都可以发到这里。
+- 客服邮箱：<winrock.inc@outlook.com>。这份说明没写到的地方、用的时候遇到的问题，都可以发到这里。
 
 报问题时请带上：运行的命令、完整的报错（连同错误码；有请求编号的话一起给）、`buke --version` 的输出、大概的时间。**不要把完整密钥发过来**——要指明是哪一把，给编号前缀（形如 `bk_test_0123456789abcdef`）就够了。
 
-更完整的使用说明（鉴权是怎么做的、每条命令的输出与 JSON 字段、给脚本和 AI agent 的建议、更多的问题排查）随对外开通一起公布。
+更完整的使用说明（鉴权是怎么做的、每条命令的输出与 JSON 字段、给脚本和 AI agent 的建议、更多的问题排查）会另行公布。