bukesiyi-cli 0.3.3 → 0.5.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 +85 -11
  2. package/dist/main.js +3091 -287
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,14 +1,37 @@
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、蒙版 4 MiB;表单总量最多 256 MiB。业务头用 `--headers <JSON文件>`,仅允许目录声明的字段(如录音的 `X-Script-Fingerprint`),不能覆盖认证或工作区。下载用 `--out <新文件>`,已有文件不会覆盖。签发 API 密钥、分享链接和下载凭证必须指定 `--out`;真实响应只写入权限为 0600 的文件,终端输出脱敏结果。
32
+
33
+ 网页写操作保留 `webRecovery` 与原请求键。已受理、结果未知和完成分别表示;连接中断后先查询原资源。只有服务端支持幂等重放的操作才能用原键恢复,不支持重放时不会把再次提交伪装成恢复。并发同一请求只提交一次;已完成后的独立串行操作仍可执行。上次结果仍未知时,明确创建另一次尝试须提供新键并再次确认范围。`web logout` 撤销网页会话;`buke logout` 仍只删除本机 API 密钥,不混用两种凭据。
34
+
12
35
  ## 安装
13
36
 
14
37
  运行环境要求 Node.js 20 或更高版本。
@@ -21,7 +44,7 @@ npm install -g bukesiyi-cli
21
44
 
22
45
  ```console
23
46
  $ buke --version
24
- bukesiyi-cli/0.3.3
47
+ bukesiyi-cli/0.5.0
25
48
  ```
26
49
 
27
50
  也可使用 `npx bukesiyi-cli <命令>` 临时运行,例如 `npx bukesiyi-cli whoami`。
@@ -91,14 +114,18 @@ $ buke login bk_test_0123456789abcdef_……
91
114
  | `buke whoami` | 查询密钥归属、团队、权限及有效期。优先使用 `BUKE_API_KEY`,否则读取本机凭据 |
92
115
  | `buke logout` | 删除本机凭据,不发送网络请求,不吊销密钥 |
93
116
  | `buke balance` | 查询可用、冻结及已使用额度 |
94
- | `buke products create / set-images / confirm-lock` | 创建产品、上传商品图片、确认外观信息 |
117
+ | `buke products list / search / show / create / update / archive / restore / set-images / confirm-lock` | 查询和管理产品、上传图片、确认外观信息 |
95
118
  | `buke shorts catalog / upload / quote / order / status / download / cancel` | 查询模板、上传素材、报价、创建订单、查询进度、下载和取消 |
96
- | `buke videos create / status / message / confirm / download` | 创建商品视频任务、查询进度、发送消息、确认制作和下载 |
97
- | `buke drama create / status / quote / confirm / cancel / download` | 创建短剧订单、查询进度、报价、确认制作、取消和下载 |
119
+ | `buke videos create / status / message / confirm / versions / download / cancel` | 创作商品视频,提交附件和选项,确认制作并下载指定版本 |
120
+ | `buke drama` | 短剧创作、剧本和分镜、人物与场景绑定、规格、报价、重拍、选版和交付 |
121
+ | `buke series list / show / create / episode-create` | 查询剧集、关联首集、创建续集 |
122
+ | `buke graphic` | 图文方案、报价生成、局部修改、版本管理和下载 |
123
+ | `buke library list / search / show / rename / archive / restore` | 统一查询和管理作品;以返回的 `archivable` 为准 |
124
+ | `buke assets list / search / show / upload / rename / archive / restore` | 查询平台、个人及上传素材,上传文件并管理个人素材 |
98
125
  | `buke --version` | 输出版本号 |
99
126
  | `buke --help`、`buke <命令> --help` | 输出命令及选项帮助 |
100
127
 
101
- 写操作支持 `--idempotency-key <键>`。未指定时,CLI 自动生成并在结果中返回。重试同一操作必须保留原键和请求内容;新键表示新尝试,可能产生新订单及费用。渲染短片的报价哈希与幂等键绑定,`shorts quote` 和 `shorts order` 必须使用相同键。
128
+ 写操作支持 `--idempotency-key <键>`。未指定时,CLI 自动生成并在结果中返回。重试同一操作必须保留原键和请求内容;新键表示新尝试,可能产生新订单及费用。模板短片的报价哈希与幂等键绑定,`shorts quote` 和 `shorts order` 必须使用相同键。
102
129
 
103
130
  `shorts order --wait`、`shorts status --wait` 和 `videos status --wait` 轮询原任务。成功退出 0,终态失败或取消退出 9,等待超过 `--timeout`(默认 600 秒)退出 8。商品视频进入等待回复或确认的状态时退出 0,等待调用方处理。
104
131
 
@@ -106,17 +133,46 @@ $ buke login bk_test_0123456789abcdef_……
106
133
 
107
134
  等待失败、超时或轮询中断后,应查询原任务。JSON 错误文档中的 `recovery` 保留任务编号、最后状态和查询命令;`shorts order` 同时保留幂等键。自定义服务的查询命令保留 `--base-url`。
108
135
 
109
- `drama confirm` 失败时同样保留目标订单、最后一次成功查询的状态和已知幂等键,并返回 `operation: "confirm"`。`operationOutcome` 区分 `not_submitted`(确认请求尚未发送)、`rejected`(服务端明确拒绝)和 `unknown`(受理结果未知)。`acceptance` 仅表示原订单是否已确认存在,不表示本次费用确认成功。CLI 不自动重发确认请求;结果未知时应先查询原订单并保留原键。
136
+ 确认失败时保留目标订单、最后一次成功查询的状态和已知幂等键,并返回 `operation: "confirm"`。`operationOutcome` 区分 `not_submitted`(确认请求尚未发送)、`rejected`(服务端明确拒绝)、`accepted`(已受理,后续查询失败)和 `unknown`(受理结果未知)。`acceptance` 仅表示原订单是否已确认存在,不表示本次费用确认成功。CLI 不自动重发确认请求;结果未知时应先查询原订单并保留原键。商品视频的原确认身份保留在 `recovery.videoConfirmation`,可保存为 JSON,配合原键用 `videos confirm --data <文件> --idempotency-key <原键> --yes` 重放。
137
+
138
+ 所有等待参数在提交前检查。`drama status --wait` 到达 `quotable` 时立即停靠,等待用户报价确认。`videos music-apply` 的同步合成请求默认等待 300 秒,支持 `--timeout <秒数>`;超时不等于后台失败,应先查原配乐任务。
139
+
140
+ 新增的导演确认、重拍、剧集和附件写入同样保留可用的原请求键及查询入口。导演卡确认结果未知时,`recovery.confirmation` 保留原 `kind` 与 `confirmationId`,可在查询原任务后配合原键显式重放;CLI 不自动重发。
110
141
 
111
142
  提交结果不明时,`recovery.acceptance` 为 `unknown`,不返回虚构的任务编号。保存原幂等键,在 Studio 核对原请求;不得换键重新下单。CLI 不自动重试。
112
143
 
113
144
  `drama create` 支持 `--model` 和 `--resolution`。未显式指定模型时,报价前可适配人物参考;显式指定不兼容模型时进入需要处理的状态,不自动替换。`drama quote` 展示实际制作规格、费用及适配说明。
114
145
 
115
- 短剧普通状态 JSON 可包含 `order.productionCompatibility` 和 `order.failures`。等待终态失败时,失败数组位于 JSON 顶层 `failures`,与 `error`、`recovery` 并列。素材定位不可确认时返回 `reference: null`,不推测具体图片;旧记录不会自动补齐证据。修正素材或在 Studio 明确修改规格后,须重新报价和确认,CLI 不自动切换模型或付费重试。
146
+ 短剧普通状态 JSON 可包含 `order.productionCompatibility` 和 `order.failures`。等待终态失败时,失败数组位于 JSON 顶层 `failures`,与 `error`、`recovery` 并列。素材定位不可确认时返回 `reference: null`,不推测具体图片;旧记录不会自动补齐证据。修正素材或通过 `drama spec` 明确修改规格后,须重新报价和确认,CLI 不自动切换模型或付费重试。
147
+
148
+ ## 创作与管理示例
149
+
150
+ 完整参数见[CLI 参考](https://buke41.com/developers/cli)。`--data <文件|->` 读取 JSON 对象;`-` 表示标准输入。调用方身份及工作区由密钥确定,不能通过 JSON 覆盖。
151
+
152
+ ```sh
153
+ buke products search --q "夏装" --limit 20 --json
154
+ buke library list --kind graphic --limit 20 --json
155
+ buke assets list --source platform --kind character --json
156
+ buke assets upload ./reference.png --authorization own --license "本公司自有素材" --json
157
+ buke graphic create --text "为夏季新品准备三张商品介绍图" --json
158
+ buke graphic status <图文项目编号> --wait --json
159
+ buke graphic quote <图文项目编号> --json
160
+ buke graphic generate <图文项目编号> --quote-hash <报价哈希> --yes --wait --json
161
+ buke graphic download <图文项目编号> --all --out ./images
162
+ buke drama context <短剧编号> --json
163
+ buke drama spec <短剧编号> --expected-epoch <当前版本> --model <模型> --resolution <分辨率>
164
+ buke drama versions <短剧编号> --json
165
+ buke videos versions <视频编号> --json
166
+ buke videos download <视频编号> --production-id <制作版本编号> --out ./video.mp4
167
+ ```
168
+
169
+ 普通创作消息用于调整要求和方案,不自动授权生成。图文 `generate --yes`、短剧 `confirm --yes` / `director-confirm --yes` / `redo --yes`、商品视频 `confirm --expected-version <已查看版本> --expected-credits <已查看金额> --yes`、配乐 `music-compose --quote-hash <已查看报价> --yes` 分别核对原报价或确认卡后提交。图文和配乐提交都必须提供已查看的报价哈希,缺失或变化不会生成。改稿、改规格和更换素材可能使旧报价失效,应重新查询。指定已完成镜头重拍属于新制作,按新报价收费;原版本保留。
170
+
171
+ 产品资料更新支持名称;图片和外观信息使用各自命令。平台素材只读,个人生成素材可重命名、归档和恢复。图文作品当前不支持归档;作品接口通过 `archivable: false` 表明此限制。归档不会删除已生成文件或已有订单引用。
116
172
 
117
173
  ## 输出与通用选项
118
174
 
119
- 完整成片下载只接受 HTTP 200、非空正文及合法视频类型;短剧和渲染短片为 MP4,商品视频同时兼容服务端返回的 QuickTime。HTTP 202 表示文件尚未就绪,命令退出 7,不保存响应或覆盖已有文件。应查询原任务后再次下载,不重新生成。
175
+ 完整成片下载只接受 HTTP 200、非空正文及合法视频类型;短剧和模板短片为 MP4,商品视频同时兼容服务端返回的 QuickTime。HTTP 202 表示文件尚未就绪,命令退出 7,不保存响应或覆盖已有文件。应查询原任务后再次下载,不重新生成。
120
176
 
121
177
  | 选项 | 作用 |
122
178
  | --- | --- |
@@ -171,8 +227,13 @@ $ buke whoami --json
171
227
  | `BUKE_API_KEY` | 优先使用的 API 密钥;设置后不读取本机凭据文件。`login` 验证后将其保存至本机 |
172
228
  | `BUKE_BASE_URL` | 服务源地址。`--base-url` 优先于该变量;未配置时使用 `https://buke41.com` |
173
229
  | `BUKE_CONFIG_DIR` | 凭据目录,须为绝对路径,支持展开开头的 `~`。默认依次采用 `$XDG_CONFIG_HOME/buke`、`~/.config/buke`;Windows 使用 `%APPDATA%\buke` |
230
+ | `BUKE_PASSWORD` | 网页会话登录密码;只在登录时使用,可改用隐藏终端输入 |
231
+ | `BUKE_SESSION_TOKEN` | 受控环境提供的真实网页会话令牌;不能使用 API 密钥 |
232
+ | `BUKE_WORKSPACE_ID` | 网页会话工作区;`--workspace` 优先,调用前核对真实成员身份 |
233
+
234
+ 网页会话额外支持 `BUKE_PASSWORD`(仅登录时读取)、`BUKE_SESSION_TOKEN`(受控环境提供真实会话)和 `BUKE_WORKSPACE_ID`(工作区,显式 `--workspace` 优先并核对成员身份)。
174
235
 
175
- 凭据保存在 `credentials.json` 中。macOS 和 Linux 上文件权限仅允许当前用户读写。文件包含明文密钥,不得提交至代码仓库、写入镜像或直接共享。
236
+ API 密钥保存在 `credentials.json`,网页会话保存在同目录的 `session.json`。macOS 和 Linux 上文件权限仅允许当前用户读写。文件包含明文凭据,不得提交至代码仓库、写入镜像或直接共享。
176
237
 
177
238
  启用 Node.js 环境代理时,CLI 会拒绝可能经代理传输密钥的本机 HTTP 请求。本机调试可通过 `NO_PROXY` 排除回环地址:
178
239
 
@@ -224,6 +285,19 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
224
285
  | `CLI_TASK_FAILED` | 9 | 原任务进入失败或取消终态。查询原任务,核对原因、已完成内容及计费;新制作需要重新报价和授权 |
225
286
  | `CLI_INTERRUPTED` | 130 | 进程收到中断信号。SIGTERM 和 SIGHUP 分别退出 143、129;提交被中断时先核对原任务 |
226
287
  | `CLI_INTERNAL` | 5 | 未预期的本机错误。提交脱敏错误信息、命令及版本号以供排查 |
288
+ | `CLI_STDIN_TIMEOUT` | 2 | JSON 标准输入未在时限内结束;提供完整 JSON 并关闭输入流 |
289
+ | `CLI_EVENT_HTTP_ERROR` | 2/3/4/5/6/7/10 | 实时事件请求失败;按 HTTP 状态映射退出码,先查询原任务 |
290
+ | `CLI_EVENT_LIMIT` | 7 | 实时事件达到本次读取上限;查询当前状态或重新连接 |
291
+ | `CLI_REDIRECT_BLOCKED` | 5 | 网页接口跳转被拒绝,凭据未转发;检查服务地址 |
292
+ | `CLI_WEB_NOT_LOGGED_IN` | 3 | 没有网页会话;先运行 buke web login,API 密钥不能代替 |
293
+ | `CLI_WEB_SESSION` | 5 | 网页凭据或恢复文件不安全、不可读或无法保存;核对路径与 0600 权限 |
294
+ | `CLI_WEB_WORKSPACE_FORBIDDEN` | 3 | 服务端未确认工作区成员身份;本次操作未提交 |
295
+ | `CLI_WEB_OUTPUT_FAILED` | 5 | 输出保存失败且原文件未覆盖;核对目录与磁盘空间 |
296
+ | `CLI_WEB_REQUEST_FAILED` | 2/3/4/5/6/7/10 | 网页接口返回错误;按 HTTP 状态映射退出码,先核对原操作结果 |
297
+ | `CLI_EVENT_ERROR` | 5 | 导演回合返回业务错误;查询原任务,不重新提交 |
298
+ | `CLI_EVENT_INCOMPLETE` | 7 | 事件连接提前结束,尚未收到完成回执;保留原任务和幂等键并查询 |
299
+ | `CLI_WEB_REQUEST_BUSY` | 7 | 相同网页请求正由另一进程处理,本次未提交;查询原操作结果 |
300
+ | `CLI_STREAM_INCOMPLETE` | 5 | 网页事件流缺少完成回执;保留原请求键,先查询原任务 |
227
301
 
228
302
  网络配置:
229
303