bukesiyi-cli 0.1.0 → 0.1.1

package/README.md

@@ -9,7 +9,7 @@
 装之前先看这几条：
 
 - **这一版只做登录这一件事**，一共三条命令：`buke login`、`buke whoami`、`buke logout`——用一把 API 密钥登录、确认它能用、把它稳妥地保存在本机。下单、查进度、下载成片这些命令现在没有，随开放接口上线后提供。
-- **开放接口尚未对外开通。** 现在逐个账号开通，需要联系《不可思议》的客服为账号开通。没有开通的账号拿不到密钥；装了这个工具，也登录不了。
+- **开放接口尚未对外开通。** 现在逐个账号开通，需要联系《不可思议》的客服为账号开通（联系方式见文末「联系我们」）。没有开通的账号拿不到密钥；装了这个工具，也登录不了。
 - **密钥在网页上创建，不在这个工具里。** 已经开通的账号登录 Studio，在账号页的「API 密钥」里创建、查看和吊销：<https://buke41.com/account/api-keys>。完整的密钥只在创建成功的那一刻显示一次。没有开通的账号在账号页里看不到这个入口。
 
 下面的输出例子都是用这一版实际跑出来的，对面是一个按接口约定应答的本机模拟服务；密钥、家目录、编号是演示用的占位。
@@ -26,7 +26,7 @@ npm install -g bukesiyi-cli
 
 ```console
 $ buke --version
-bukesiyi-cli/0.1.0
+bukesiyi-cli/0.1.1
 ```
 
 不想全局安装时，可以用 npx 临时运行，写法是 `npx bukesiyi-cli <命令>`，例如 `npx bukesiyi-cli whoami`。下面的例子都直接写 `buke`。
@@ -174,10 +174,46 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 | 8 | 等待超时 | 不会 |
 | 9 | 任务失败 | 不会 |
 | 10 | 要找的东西不存在 | 会 |
-| 130 | 被 Ctrl-C 打断；运行到一半被要求结束（SIGTERM）是 143，终端断开（SIGHUP）是 129 | 会 |
+| 130 | 被 Ctrl-C 打断 | 会 |
+
+运行到一半被别的信号打断时数字不同：被要求结束（SIGTERM）是 143，终端断开（SIGHUP）是 129。
 
 脚本里先看退出码，再看 `--json` 输出里的 `error.code` 和 `error.retryable`；遇到 7，按 `error.retryAfterSeconds` 给的秒数等够了再试。要让脚本调得到 `buke`，它得在 PATH 上：全局安装之后就在。
 
+## 错误码
+
+出错时，给人看的输出里有一行「（错误码 …）」；加了 `--json` 时，错误码在 `error.code` 里。错误码有两类：
+
+- `OPEN_API_` 开头的是服务端回的：请求送到了，服务端没有接受。报错的第一行是服务端的原话，写明了原因和该怎么办；这类报错带一个追踪编号（`--json` 里是 `error.traceId`），找客服时把它一起给出。退出码按上面那张表：密钥或账号现在不能用是 3，请求太频繁是 7，这个地址上没有接口是 10，服务端出错是 5。
+- `CLI_` 开头的是这个工具自己发现的问题：命令的写法、密钥的给法、服务地址、本机的凭据文件、网络。这一版一共有下面这些：
+
+| 错误码 | 退出码 | 怎么办 |
+| --- | --- | --- |
+| `CLI_USAGE` | 2 | 命令或选项写错了。运行 `buke --help` 对照用法 |
+| `CLI_KEY_IN_ARGV` | 2 | 命令行参数里出现了像密钥的东西，命令什么都没做。改用环境变量 `BUKE_API_KEY`、管道或终端粘贴；那把密钥如果是真的，当作已经泄露：吊销后换一把 |
+| `CLI_KEY_MISSING` | 2 | `login` 没有读到密钥：没设 `BUKE_API_KEY`，标准输入又是空的，或者等了 30 秒还没有结束。按「三步上手」里的三种给法之一重来 |
+| `CLI_KEY_MALFORMED` | 2 | 给的东西不像一把密钥：不是 `bk_` 开头，或者中间有空格、换行。核对是不是贴错、贴漏了，或者把别的内容送了进来 |
+| `CLI_BASE_URL_INVALID` | 2 | 服务地址不是一个完整的网址，或者带了路径、参数、账号密码。只写到域名为止，例如 `https://buke41.com` |
+| `CLI_BASE_URL_INSECURE` | 2 | 服务地址不是 https（本机调试用的 `localhost`、`127.0.0.1`、`[::1]` 除外）；或者地址是本机的明文地址，而环境里开着代理。换成 https 地址；本机调试遇到代理时，把本机地址排除在代理之外（见「环境变量」一节末尾） |
+| `CLI_BASE_URL_MISMATCH` | 2 | `whoami` 用的是本机保存的密钥，而这次指定的地址和登录时的不一样，请求没有发出。去掉 `--base-url` 或 `BUKE_BASE_URL`；确实要换地址，就对新地址重新 `buke login` |
+| `CLI_NOT_LOGGED_IN` | 3 | `whoami` 找不到密钥：没设 `BUKE_API_KEY`，本机也没有保存。先 `buke login`，或者设置 `BUKE_API_KEY` |
+| `CLI_CONFIG_DIR_INVALID` | 2 | 不知道凭据该放在哪里：`BUKE_CONFIG_DIR` 写成了相对路径，或者系统说不出家目录在哪。把 `BUKE_CONFIG_DIR` 写成绝对路径，或者用 `~/` 开头 |
+| `CLI_CREDENTIALS_UNREADABLE` | 5 | 本机的凭据文件读不懂（内容损坏、被手改过）或者读不了（没有权限，或者那个位置上不是一个普通文件）。`buke logout` 清掉后重新 `buke login`；是权限问题就先修权限 |
+| `CLI_CREDENTIALS_WRITE_FAILED` | 5 | 凭据文件没能保存或没能删除，多半是目录没有写权限。修好目录权限，或者用 `BUKE_CONFIG_DIR` 换一个目录，再运行一次 |
+| `CLI_NETWORK` | 5 | 连不上服务地址，冒号后面是系统给的原因。先核对地址和网络，确认无误后可以重试；证书和代理的情况见表后 |
+| `CLI_TIMEOUT` | 5 | 等了 15 秒，服务端没有回完。稍后重试；总是超时就检查网络，或者中间有没有代理、防火墙拦着 |
+| `CLI_REDIRECT` | 5 | 服务器要求跳转到别处；为了不把密钥带过去，没有跟随。核对服务地址（报错的括号里是跳转指向的地方），用正确的地址重新登录 |
+| `CLI_BAD_RESPONSE` | 5 | 收到的回应不是约定的格式，多半是中间的网关或别的网站回的，括号里是 HTTP 状态码。状态码是 429 或 5xx 时稍后重试；其余的先核对服务地址，重试多半没有用 |
+| `CLI_INTERRUPTED` | 130 | 命令被打断了：按了 Ctrl-C，或者收到了 SIGTERM、SIGHUP（这两种的退出码是 143、129）。需要时重新运行 |
+| `CLI_INTERNAL` | 5 | 工具自己出了没有料到的错，正常使用不应该遇到。把完整的报错和运行的命令（不要带密钥）发给客服，联系方式见文末「联系我们」 |
+
+两种常见的「连不上」：
+
+- **内部环境用的是自签证书**：报 `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`；地址没错，就是还没有开通，重试没有用。
+
 ## 安全须知
 
 - 密钥就是权限：拿到它的人，可以用你的账号在那个制片空间里调用开放接口。
@@ -189,30 +225,13 @@ export NO_PROXY='localhost,127.0.0.1,[::1]'
 
 ## 从仓库源码运行
 
-这一节只给拿得到代码仓库、要改这个工具的人；只是使用的话，按上面「安装」一节从 npm 装就够了。
+这一节只给拿得到代码仓库、要改这个工具的人：构建、直接运行、让 `buke` 这个名字指到仓库里那一份的做法，写在仓库的 `docs/open-api/cli.md` 第 2.2 节。只是使用的话，按上面「安装」一节从 npm 装就够了。
 
-在仓库根目录、依赖已经装好的前提下，先构建，再用 Node.js 直接运行：
-
-```sh
-npm run build -w bukesiyi-cli
-node packages/cli/bin/buke.js --version
-```
-
-```text
-bukesiyi-cli/0.1.0
-```
-
-要让 `buke` 这个名字指到仓库里的这一份，并且在脚本和别的程序里也能用，就在 PATH 上的某个目录里放一个两行的小脚本。下面放在 `$HOME/bin`；先把 `BUKE_REPO` 设成仓库所在的绝对路径：
-
-```sh
-mkdir -p "$HOME/bin"
-printf '#!/bin/sh\nexec node "%s/packages/cli/bin/buke.js" "$@"\n' "$BUKE_REPO" > "$HOME/bin/buke"
-chmod +x "$HOME/bin/buke"
-export PATH="$HOME/bin:$PATH"
-```
+## 联系我们
 
-最后那句 `export PATH=…` 只对当前这个 shell 和它启动的程序有效；要长期用，把它写进 shell 的启动文件。
+- 网站：<https://buke41.com>
+- 客服邮箱：<winrock.inc@outlook.com>。为账号开通、这份说明没写到的地方、用的时候遇到的问题，都可以发到这里。
 
-## 更多
+报问题时请带上：运行的命令、完整的报错（连同错误码；有追踪编号的话一起给）、`buke --version` 的输出、大概的时间。**不要把完整的密钥发过来**——要指明是哪一把，给公开前缀（形如 `bk_test_0123456789abcdef`）就够了。
 
-完整的使用说明（鉴权是怎么做的、密钥的三种给法、地址规则、每条命令的输出与 JSON 字段、错误对照表、给脚本和 AI agent 的建议、常见问题排查）在代码仓库的 `docs/open-api/cli.md` 里，随开放接口开通后对外公布。在那之前，这份说明没写到的地方，请联系客服。
+更完整的使用说明（鉴权是怎么做的、每条命令的输出与 JSON 字段、给脚本和 AI agent 的建议、更多的问题排查）随对外开通一起公布。

package/dist/main.js

@@ -394,7 +394,7 @@ async function readNewKey(io) {
 
 // package.json
 var name = "bukesiyi-cli";
-var version = "0.1.0";
+var version = "0.1.1";
 
 // src/version.ts
 var PACKAGE_NAME = name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bukesiyi-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "《不可思议》开放接口的命令行客户端（命令名 buke）",
   "type": "module",
   "bin": {