bukesiyi-cli 0.4.0 → 0.6.0

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.
Files changed (3) hide show
  1. package/README.md +93 -8
  2. package/dist/main.js +2097 -162
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,14 +1,79 @@
1
1
  # bukesiyi-cli
2
2
 
3
- 《不可思议》(<https://buke41.com>)开放 API 的命令行客户端,命令名为 `buke`。支持交互式终端、脚本、CI 流水线和 AI agent 调用。
3
+ 《不可思议》(<https://buke41.com>)的命令行客户端,命令名为 `buke`。制作自动化使用 API 密钥;网页功能使用独立的真实登录会话。支持交互式终端、脚本、CI 流水线和 AI agent 调用。
4
4
 
5
5
  ## 支持范围与接入条件
6
6
 
7
- - 支持 API 凭据管理、产品和素材管理、余额查询,以及渲染短片、商品视频、短剧和图文的创作、确认与交付。
7
+ - 支持 API 凭据管理、产品和素材管理、余额查询,以及模板短片、商品视频、短剧和图文的创作、确认与交付。
8
8
  - 注册账号无需单独申请 API 访问资格。调用要求 API 服务启用、密钥有效,且账号在密钥所属团队具有制作权限。
9
9
  - 密钥由账号本人在[API 密钥页面](https://buke41.com/account/api-keys)创建、查看和吊销。完整密钥仅在创建成功时显示一次。
10
10
  - 示例使用演示凭据、路径和编号。执行时替换为当前环境配置;程序应解析 JSON 字段,不应逐字匹配中文输出。
11
11
 
12
+ ## 网页功能与制作扩展
13
+
14
+ `buke videos --help`、`buke drama --help`、`buke graphic --help`、`buke series --help` 列出制作扩展:停止导演、恢复未完成步骤、素材缺口、文稿版本比较与恢复、角色声音、动作参考、字幕及系列大纲。写操作需 `--yes`,并保留服务端给出的版本、报价和确认身份;不自动接受变化后的报价。
15
+
16
+ 完整网页操作通过真实网页登录,沿用原账号权限、工作区和业务规则;API 密钥不能替代网页会话。余额充值、后台管理和网页已关闭的产品入口不提供。会员购买、续费、升级及退款沿原网页合同;会员支付操作会先确认订单类型,拒绝充值订单。
17
+
18
+ ```sh
19
+ buke web login --username your-account
20
+ buke web whoami --json
21
+ buke web operations --json
22
+ buke web operations --group delivery --json
23
+ buke web call account.getAgentSettings --json
24
+ buke web call account.updateAgentSettings --data director-settings.json --yes --json
25
+ printf '%s\n' '{"kind":"episode","sourceId":"project-example"}' | buke web call delivery.list --query - --json
26
+ buke web logout
27
+ ```
28
+
29
+ `delivery.list` 需要 `kind` 和 `sourceId`,示例中的项目编号要换成自己的短剧项目编号。
30
+
31
+ 登录密码使用隐藏终端输入、管道或 `BUKE_PASSWORD`,不写命令参数。`web operations --json` 返回固定操作编号、方法、路径、正文类型和适用限制。路径参数通过 `--params` JSON 文件提供,查询条件用 `--query`,正文用 `--data`;原文件上传用 `--file`,`multipart` 表单用 `--files` 指定真实字段名(如 `{"mask":"./mask.png"}`,单文件也可用 `--file`,按目录自动选择字段名);单文件按目录策略限制:图片 15 MiB、文档 30 MiB、允许音视频的附件 90 MiB、短剧配音录音 20 MiB、语音转文字 2 MiB、蒙版 4 MiB;表单总量最多 256 MiB。业务头用 `--headers <JSON文件>`,仅允许目录声明的字段(如录音的 `X-Script-Fingerprint`),不能覆盖认证或工作区。下载用 `--out <新文件>`,已有文件不会覆盖。签发 API 密钥、分享链接和下载凭证必须指定 `--out`;真实响应只写入权限为 0600 的文件,终端输出脱敏结果。
32
+
33
+ 网页写操作保留 `webRecovery` 与原请求键。已受理、结果未知和完成分别表示;连接中断后先查询原资源。只有服务端支持幂等重放的操作才能用原键恢复,不支持重放时不会把再次提交伪装成恢复。并发同一请求只提交一次;已完成后的独立串行操作仍可执行。上次结果仍未知时,明确创建另一次尝试须提供新键并再次确认范围。`web logout` 撤销网页会话;`buke logout` 仍只删除本机 API 密钥,不混用两种凭据。
34
+
35
+ ### 短信登录与首次设密
36
+
37
+ 先查询 `auth.smsLoginStatus`,确认服务开放后发送验证码。手机号和验证码通过私有 JSON 文件或 `--data -` 标准输入提供,勿把验证码、密码写进命令行。短信登录成功后,CLI 校验账号、工作区成员身份、令牌和有效期,将真实会话保存到权限为 0600 的会话文件;失败或不完整响应不会覆盖原会话。终端、`--out` 结果和恢复记录均隐藏验证码、密码及令牌。
38
+
39
+ ```sh
40
+ buke web call auth.smsLoginStatus --json
41
+ buke web call auth.sendLoginSms --data phone.json --yes --json
42
+ buke web call auth.loginWithSms --data sms-login.json --yes --json
43
+ buke web whoami --json
44
+ buke web call auth.sendPasswordSetupSms --yes --json
45
+ buke web call auth.setupPassword --data first-password.json --yes --json
46
+ ```
47
+
48
+ `phone.json` 使用 `phone` 字段;`sms-login.json` 使用 `phone`、`code`;`first-password.json` 使用 `code`、`newPassword`。首次设密仅适用于已登录且尚未设密的账号,验证码发送给当前账号绑定手机号,不签发新会话。一键登录依赖原生手机 SDK,CLI 不提供该入口。
49
+
50
+ ### 图文、剪辑与语音入口
51
+
52
+ 固定目录补齐以下网页能力,仍使用本人会话和工作区权限;写操作继续要求 `--yes`。
53
+
54
+ | 功能 | 操作编号与参数 |
55
+ | --- | --- |
56
+ | 图文引用素材库 | `graphic.attachGraphicRunAsset`:`--params` 提供 `runId`,`--data` 提供 `assetId` |
57
+ | 图文保存到素材库 | `graphic.saveGraphicImageToLibrary`:`--params` 提供 `runId`、`imageId`,`--data` 提供 `kind`(`character` / `scene` / `prop`)和可选 `name` |
58
+ | 图文原图 | `graphic.graphicImageSource`:`runId`、`imageId` |
59
+ | 商品视频素材原图 | `videos.commercialAdImageSource`:`rootRunId`、`assetId` |
60
+ | 商品视频故事板原图 | `videos.commercialAdStoryboardSource`:`rootRunId`、`imageKey` |
61
+ | 商品视频编辑原图 | `videos.commercialAdImageEditSource`:`rootRunId`、`editId` |
62
+ | 剪辑时间线 | `videos.getCommercialAdEditTimeline` 使用 `rootRunId`;`drama.getStoryEditTimeline` 使用 `projectId` |
63
+ | 语音转文字 | `speech.health` 查询服务状态;`speech.transcribe --file <音频> --yes` 提交录音 |
64
+ | 创建入口 | `public.publicCommercialAdInspirations` 查询公开创意参考;`videos.showcaseEntryDefault` 查询当前登录账号的默认设置 |
65
+
66
+ 四种原图操作返回二进制原件,必须指定 `--out <新文件>`;原有 `download` 操作继续用于交付文件。下载拒绝未就绪的 JSON 响应,即使输出文件没有扩展名也一样。
67
+
68
+ ```sh
69
+ buke web call graphic.graphicImageSource --params image-params.json --out ./source.png --json
70
+ buke web call videos.getCommercialAdEditTimeline --params video-params.json --json
71
+ buke web call speech.health --json
72
+ buke web call speech.transcribe --file ./recording.webm --yes --json
73
+ ```
74
+
75
+ 语音转文字直接上传原始音频字节,不接受 multipart 字段或 JSON 正文。支持 WAV、MP3、WebM、M4A / MP4、OGG / Opus、AAC、FLAC,最多 2 MiB;服务端校验实际音频内容及 0.5–60 秒时长。它与短剧配音录音上传使用不同限制。
76
+
12
77
  ## 安装
13
78
 
14
79
  运行环境要求 Node.js 20 或更高版本。
@@ -21,7 +86,7 @@ npm install -g bukesiyi-cli
21
86
 
22
87
  ```console
23
88
  $ buke --version
24
- bukesiyi-cli/0.4.0
89
+ bukesiyi-cli/0.5.0
25
90
  ```
26
91
 
27
92
  也可使用 `npx bukesiyi-cli <命令>` 临时运行,例如 `npx bukesiyi-cli whoami`。
@@ -102,7 +167,7 @@ $ buke login bk_test_0123456789abcdef_……
102
167
  | `buke --version` | 输出版本号 |
103
168
  | `buke --help`、`buke <命令> --help` | 输出命令及选项帮助 |
104
169
 
105
- 写操作支持 `--idempotency-key <键>`。未指定时,CLI 自动生成并在结果中返回。重试同一操作必须保留原键和请求内容;新键表示新尝试,可能产生新订单及费用。渲染短片的报价哈希与幂等键绑定,`shorts quote` 和 `shorts order` 必须使用相同键。
170
+ 写操作支持 `--idempotency-key <键>`。未指定时,CLI 自动生成并在结果中返回。重试同一操作必须保留原键和请求内容;新键表示新尝试,可能产生新订单及费用。模板短片的报价哈希与幂等键绑定,`shorts quote` 和 `shorts order` 必须使用相同键。
106
171
 
107
172
  `shorts order --wait`、`shorts status --wait` 和 `videos status --wait` 轮询原任务。成功退出 0,终态失败或取消退出 9,等待超过 `--timeout`(默认 600 秒)退出 8。商品视频进入等待回复或确认的状态时退出 0,等待调用方处理。
108
173
 
@@ -110,7 +175,9 @@ $ buke login bk_test_0123456789abcdef_……
110
175
 
111
176
  等待失败、超时或轮询中断后,应查询原任务。JSON 错误文档中的 `recovery` 保留任务编号、最后状态和查询命令;`shorts order` 同时保留幂等键。自定义服务的查询命令保留 `--base-url`。
112
177
 
113
- `drama confirm` 失败时同样保留目标订单、最后一次成功查询的状态和已知幂等键,并返回 `operation: "confirm"`。`operationOutcome` 区分 `not_submitted`(确认请求尚未发送)、`rejected`(服务端明确拒绝)和 `unknown`(受理结果未知)。`acceptance` 仅表示原订单是否已确认存在,不表示本次费用确认成功。CLI 不自动重发确认请求;结果未知时应先查询原订单并保留原键。
178
+ 确认失败时保留目标订单、最后一次成功查询的状态和已知幂等键,并返回 `operation: "confirm"`。`operationOutcome` 区分 `not_submitted`(确认请求尚未发送)、`rejected`(服务端明确拒绝)、`accepted`(已受理,后续查询失败)和 `unknown`(受理结果未知)。`acceptance` 仅表示原订单是否已确认存在,不表示本次费用确认成功。CLI 不自动重发确认请求;结果未知时应先查询原订单并保留原键。商品视频的原确认身份保留在 `recovery.videoConfirmation`,可保存为 JSON,配合原键用 `videos confirm --data <文件> --idempotency-key <原键> --yes` 重放。
179
+
180
+ 所有等待参数在提交前检查。`drama status --wait` 到达 `quotable` 时立即停靠,等待用户报价确认。`videos music-apply` 的同步合成请求默认等待 300 秒,支持 `--timeout <秒数>`;超时不等于后台失败,应先查原配乐任务。
114
181
 
115
182
  新增的导演确认、重拍、剧集和附件写入同样保留可用的原请求键及查询入口。导演卡确认结果未知时,`recovery.confirmation` 保留原 `kind` 与 `confirmationId`,可在查询原任务后配合原键显式重放;CLI 不自动重发。
116
183
 
@@ -141,13 +208,13 @@ buke videos versions <视频编号> --json
141
208
  buke videos download <视频编号> --production-id <制作版本编号> --out ./video.mp4
142
209
  ```
143
210
 
144
- 普通创作消息用于调整要求和方案,不自动授权生成。图文 `generate --yes`、短剧 `confirm --yes` / `director-confirm --yes` / `redo --yes`、商品视频 `confirm --yes`、配乐 `music-compose --yes` 分别确认服务端当前报价或确认卡。改稿、改规格和更换素材可能使旧报价失效,应重新查询。指定已完成镜头重拍属于新制作,按新报价收费;原版本保留。
211
+ 普通创作消息用于调整要求和方案,不自动授权生成。图文 `generate --yes`、短剧 `confirm --yes` / `director-confirm --yes` / `redo --yes`、商品视频 `confirm --expected-version <已查看版本> --expected-credits <已查看金额> --yes`、配乐 `music-compose --quote-hash <已查看报价> --yes` 分别核对原报价或确认卡后提交。图文和配乐提交都必须提供已查看的报价哈希,缺失或变化不会生成。改稿、改规格和更换素材可能使旧报价失效,应重新查询。指定已完成镜头重拍属于新制作,按新报价收费;原版本保留。
145
212
 
146
213
  产品资料更新支持名称;图片和外观信息使用各自命令。平台素材只读,个人生成素材可重命名、归档和恢复。图文作品当前不支持归档;作品接口通过 `archivable: false` 表明此限制。归档不会删除已生成文件或已有订单引用。
147
214
 
148
215
  ## 输出与通用选项
149
216
 
150
- 完整成片下载只接受 HTTP 200、非空正文及合法视频类型;短剧和渲染短片为 MP4,商品视频同时兼容服务端返回的 QuickTime。HTTP 202 表示文件尚未就绪,命令退出 7,不保存响应或覆盖已有文件。应查询原任务后再次下载,不重新生成。
217
+ 完整成片下载只接受 HTTP 200、非空正文及合法视频类型;短剧和模板短片为 MP4,商品视频同时兼容服务端返回的 QuickTime。HTTP 202 表示文件尚未就绪,命令退出 7,不保存响应或覆盖已有文件。应查询原任务后再次下载,不重新生成。
151
218
 
152
219
  | 选项 | 作用 |
153
220
  | --- | --- |
@@ -202,8 +269,13 @@ $ buke whoami --json
202
269
  | `BUKE_API_KEY` | 优先使用的 API 密钥;设置后不读取本机凭据文件。`login` 验证后将其保存至本机 |
203
270
  | `BUKE_BASE_URL` | 服务源地址。`--base-url` 优先于该变量;未配置时使用 `https://buke41.com` |
204
271
  | `BUKE_CONFIG_DIR` | 凭据目录,须为绝对路径,支持展开开头的 `~`。默认依次采用 `$XDG_CONFIG_HOME/buke`、`~/.config/buke`;Windows 使用 `%APPDATA%\buke` |
272
+ | `BUKE_PASSWORD` | 网页会话登录密码;只在登录时使用,可改用隐藏终端输入 |
273
+ | `BUKE_SESSION_TOKEN` | 受控环境提供的真实网页会话令牌;不能使用 API 密钥 |
274
+ | `BUKE_WORKSPACE_ID` | 网页会话工作区;`--workspace` 优先,调用前核对真实成员身份 |
275
+
276
+ 网页会话额外支持 `BUKE_PASSWORD`(仅登录时读取)、`BUKE_SESSION_TOKEN`(受控环境提供真实会话)和 `BUKE_WORKSPACE_ID`(工作区,显式 `--workspace` 优先并核对成员身份)。
205
277
 
206
- 凭据保存在 `credentials.json` 中。macOS 和 Linux 上文件权限仅允许当前用户读写。文件包含明文密钥,不得提交至代码仓库、写入镜像或直接共享。
278
+ API 密钥保存在 `credentials.json`,网页会话保存在同目录的 `session.json`。macOS 和 Linux 上文件权限仅允许当前用户读写。文件包含明文凭据,不得提交至代码仓库、写入镜像或直接共享。
207
279
 
208
280
  启用 Node.js 环境代理时,CLI 会拒绝可能经代理传输密钥的本机 HTTP 请求。本机调试可通过 `NO_PROXY` 排除回环地址:
209
281
 
@@ -255,6 +327,19 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
255
327
  | `CLI_TASK_FAILED` | 9 | 原任务进入失败或取消终态。查询原任务,核对原因、已完成内容及计费;新制作需要重新报价和授权 |
256
328
  | `CLI_INTERRUPTED` | 130 | 进程收到中断信号。SIGTERM 和 SIGHUP 分别退出 143、129;提交被中断时先核对原任务 |
257
329
  | `CLI_INTERNAL` | 5 | 未预期的本机错误。提交脱敏错误信息、命令及版本号以供排查 |
330
+ | `CLI_STDIN_TIMEOUT` | 2 | JSON 标准输入未在时限内结束;提供完整 JSON 并关闭输入流 |
331
+ | `CLI_EVENT_HTTP_ERROR` | 2/3/4/5/6/7/10 | 实时事件请求失败;按 HTTP 状态映射退出码,先查询原任务 |
332
+ | `CLI_EVENT_LIMIT` | 7 | 实时事件达到本次读取上限;查询当前状态或重新连接 |
333
+ | `CLI_REDIRECT_BLOCKED` | 5 | 网页接口跳转被拒绝,凭据未转发;检查服务地址 |
334
+ | `CLI_WEB_NOT_LOGGED_IN` | 3 | 没有网页会话;先运行 buke web login,API 密钥不能代替 |
335
+ | `CLI_WEB_SESSION` | 5 | 网页凭据或恢复文件不安全、不可读或无法保存;核对路径与 0600 权限 |
336
+ | `CLI_WEB_WORKSPACE_FORBIDDEN` | 3 | 服务端未确认工作区成员身份;本次操作未提交 |
337
+ | `CLI_WEB_OUTPUT_FAILED` | 5 | 输出保存失败且原文件未覆盖;核对目录与磁盘空间 |
338
+ | `CLI_WEB_REQUEST_FAILED` | 2/3/4/5/6/7/10 | 网页接口返回错误;按 HTTP 状态映射退出码,先核对原操作结果 |
339
+ | `CLI_EVENT_ERROR` | 5 | 导演回合返回业务错误;查询原任务,不重新提交 |
340
+ | `CLI_EVENT_INCOMPLETE` | 7 | 事件连接提前结束,尚未收到完成回执;保留原任务和幂等键并查询 |
341
+ | `CLI_WEB_REQUEST_BUSY` | 7 | 相同网页请求正由另一进程处理,本次未提交;查询原操作结果 |
342
+ | `CLI_STREAM_INCOMPLETE` | 5 | 网页事件流缺少完成回执;保留原请求键,先查询原任务 |
258
343
 
259
344
  网络配置:
260
345