bukesiyi-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+# bukesiyi-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+《不可思议》（<https://buke41.com>）开放接口的命令行客户端，命令名是 `buke`。
+
+开放接口是《不可思议》平台给程序用的入口：你的脚本、流水线，或者替你干活的 AI agent，拿一把 API 密钥，不经过网页就能调用平台。这个工具替你把密钥带对、存好。
+
+## 现状
+
+装之前先看这几条：
+
+- **这一版只做登录这一件事**，一共三条命令：`buke login`、`buke whoami`、`buke logout`——用一把 API 密钥登录、确认它能用、把它稳妥地保存在本机。下单、查进度、下载成片这些命令现在没有，随开放接口上线后提供。
+- **开放接口尚未对外开通。** 现在逐个账号开通，需要联系《不可思议》的客服为账号开通（联系方式见文末「联系我们」）。没有开通的账号拿不到密钥；装了这个工具，也登录不了。
+- **密钥在网页上创建，不在这个工具里。** 已经开通的账号登录 Studio，在账号页的「API 密钥」里创建、查看和吊销：<https://buke41.com/account/api-keys>。完整的密钥只在创建成功的那一刻显示一次。没有开通的账号在账号页里看不到这个入口。
+
+下面的输出例子都是用这一版实际跑出来的，对面是一个按接口约定应答的本机模拟服务；密钥、家目录、编号是演示用的占位。
+
+## 安装
+
+需要 Node.js 20 或更高版本。
+
+```sh
+npm install -g bukesiyi-cli
+```
+
+装好之后命令名是 `buke`：
+
+```console
+$ buke --version
+bukesiyi-cli/0.1.1
+```
+
+不想全局安装时，可以用 npx 临时运行，写法是 `npx bukesiyi-cli <命令>`，例如 `npx bukesiyi-cli whoami`。下面的例子都直接写 `buke`。
+
+## 三步上手
+
+先准备一把 API 密钥：登录 Studio，在账号页的「API 密钥」（<https://buke41.com/account/api-keys>）里创建一把——起个名字，选有效期（30 天、90 天、180 天、365 天，或者长期有效），创建成功时把显示出来的完整密钥复制下来。它只显示这一次。
+
+第一步，登录。它先说一句要登录到哪个地址，再请你粘贴密钥；看一眼地址对不对，然后粘贴、回车。输入不会显示在屏幕上。
+
+```console
+$ buke login
+将登录 https://buke41.com
+请粘贴 API 密钥（输入不会显示），回车确认：
+已登录 https://buke41.com
+密钥：CI 机器（bk_test_0123456789abcdef）
+制片空间：ws-11111111222243338444555555555555（owner）
+权限：open:produce
+有效期：长期有效
+凭据保存在 /home/you/.config/buke/credentials.json（只有本人可读写）
+```
+
+第二步，确认当前登录的是谁：
+
+```console
+$ buke whoami
+当前登录 https://buke41.com
+密钥：CI 机器（bk_test_0123456789abcdef）
+制片空间：ws-11111111222243338444555555555555（owner）
+权限：open:produce
+有效期：长期有效
+密钥来自：/home/you/.config/buke/credentials.json
+```
+
+第三步，不用了就退出登录：
+
+```console
+$ buke logout
+已退出登录，本机保存的密钥已删除。这把密钥本身仍然有效，要作废请吊销它
+```
+
+在脚本、流水线和 AI agent 里不要粘贴：把密钥放进环境变量 `BUKE_API_KEY`（由平台的保密变量注入），或者从管道送进去：
+
+```console
+$ printf '%s' "$KEY" | buke login
+已登录 https://buke41.com
+密钥：CI 机器（bk_test_0123456789abcdef）
+制片空间：ws-11111111222243338444555555555555（owner）
+权限：open:produce
+有效期：长期有效
+凭据保存在 /home/you/.config/buke/credentials.json（只有本人可读写）
+```
+
+**密钥不能写在命令行参数里**——参数会留在 shell 历史和进程列表里。`buke` 发现参数里有像密钥的东西，会立刻停下：
+
+```console
+$ buke login bk_test_0123456789abcdef_……
+错误：密钥不要写在命令行里（会留在 shell 历史和进程列表里）。请用环境变量 BUKE_API_KEY，或者通过管道传给 buke login。刚才这把如果是真的，建议吊销后重建。
+（错误码 CLI_KEY_IN_ARGV）
+```
+
+## 命令速查
+
+| 命令 | 做什么 |
+| --- | --- |
+| `buke login` | 取密钥、向服务端确认它可用，然后保存到本机。密钥依次从环境变量 `BUKE_API_KEY`、标准输入、终端粘贴里取 |
+| `buke whoami` | 显示当前这把密钥是谁的、绑定哪个制片空间、有什么权限、什么时候到期。设了 `BUKE_API_KEY` 就用它，否则用本机保存的 |
+| `buke logout` | 删除本机保存的密钥。不联网，也不会吊销密钥 |
+| `buke --version` | 显示版本 |
+| `buke --help`、`buke <命令> --help` | 显示用法 |
+
+通用选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `--json` | 标准输出上只给一个 JSON 文档，成功是结果，失败是错误（含错误码、能不能重试）。脚本和 AI agent 请用这个 |
+| `--base-url <地址>` | 服务地址，默认 `https://buke41.com`。只写到域名为止，必须是 https；本机调试可以用 http，但只认 `localhost`、`127.0.0.1`、`[::1]` 三种写法。`logout` 不接受它 |
+
+加 `--json` 时的样子：
+
+```console
+$ buke whoami --json
+{
+  "baseUrl": "https://buke41.com",
+  "key": {
+    "id": "0123456789abcdef",
+    "name": "CI 机器",
+    "scopes": [
+      "open:produce"
+    ],
+    "expiresAt": null,
+    "displayPrefix": "bk_test_0123456789abcdef"
+  },
+  "account": {
+    "id": "11111111-2222-4333-8444-555555555555"
+  },
+  "workspace": {
+    "id": "ws-11111111222243338444555555555555",
+    "role": "owner"
+  },
+  "source": "file",
+  "credentialsPath": "/home/you/.config/buke/credentials.json"
+}
+```
+
+```console
+$ buke whoami --json
+{
+  "error": {
+    "code": "CLI_NOT_LOGGED_IN",
+    "message": "还没有登录。先运行 buke login，或者设置环境变量 BUKE_API_KEY",
+    "retryable": false,
+    "traceId": null
+  }
+}
+```
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `BUKE_API_KEY` | API 密钥。设了它，`whoami` 直接用它，不读本机的凭据文件；`login` 用它登录并保存到本机 |
+| `BUKE_BASE_URL` | 服务地址，作用同 `--base-url`；两个都给时以 `--base-url` 为准。不设就用默认的 `https://buke41.com`，只有要指到别的环境时才设 |
+| `BUKE_CONFIG_DIR` | 保存凭据的目录，要写绝对路径（开头的 `~` 会换成家目录）。不设时是 `$XDG_CONFIG_HOME/buke`，再不然是 `~/.config/buke`（Windows 上是 `%APPDATA%\buke`） |
+
+凭据保存在上面那个目录里的 `credentials.json`；在 macOS 和 Linux 上，文件权限是只有本人可读写。里面是明文密钥，不要提交进代码仓库、打进镜像或拷给别人。
+
+环境里让 Node.js 按环境变量走代理时（设了 `NODE_USE_ENV_PROXY`，同时有 `HTTP_PROXY`），发往本机明文地址的请求不会发出去（否则密钥会明文交到代理手里），命令报错退出。要在这样的环境里做本机调试，先把本机地址排除在代理之外：
+
+```sh
+export NO_PROXY='localhost,127.0.0.1,[::1]'
+```
+
+## 退出码
+
+| 退出码 | 含义 | 这一版会不会出现 |
+| --- | --- | --- |
+| 0 | 成功 | 会 |
+| 2 | 参数或用法不对 | 会 |
+| 3 | 没有登录，或者密钥、账号现在不能用 | 会 |
+| 4 | 余额或额度不够 | 不会 |
+| 5 | 服务端、网络或本机出错 | 会 |
+| 6 | 报价变了 | 不会 |
+| 7 | 请求太频繁，稍后重试 | 会 |
+| 8 | 等待超时 | 不会 |
+| 9 | 任务失败 | 不会 |
+| 10 | 要找的东西不存在 | 会 |
+| 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`；地址没错，就是还没有开通，重试没有用。
+
+## 安全须知
+
+- 密钥就是权限：拿到它的人，可以用你的账号在那个制片空间里调用开放接口。
+- 密钥只要进过命令行参数、地址、日志、截图、聊天或者和 AI 的对话，就当作已经泄露：吊销它，换一把新的。
+- `buke logout` 只删除本机的文件，**不等于吊销**；密钥在服务端仍然有效。
+- 吊销和新建都由账号本人在 Studio 账号页的「API 密钥」里做：<https://buke41.com/account/api-keys>。改登录密码不会让密钥失效，要作废只能吊销。
+- 输出里的公开前缀（形如 `bk_test_0123456789abcdef`）、密钥编号、追踪编号、错误码可以放心给别人看；完整的密钥不会出现在输出里。
+- 每台机器、每条流水线、每个 agent 各用一把密钥，能设有效期就设。
+
+## 从仓库源码运行
+
+这一节只给拿得到代码仓库、要改这个工具的人：构建、直接运行、让 `buke` 这个名字指到仓库里那一份的做法，写在仓库的 `docs/open-api/cli.md` 第 2.2 节。只是使用的话，按上面「安装」一节从 npm 装就够了。
+
+## 联系我们
+
+- 网站：<https://buke41.com>
+- 客服邮箱：<winrock.inc@outlook.com>。为账号开通、这份说明没写到的地方、用的时候遇到的问题，都可以发到这里。
+
+报问题时请带上：运行的命令、完整的报错（连同错误码；有追踪编号的话一起给）、`buke --version` 的输出、大概的时间。**不要把完整的密钥发过来**——要指明是哪一把，给公开前缀（形如 `bk_test_0123456789abcdef`）就够了。
+
+更完整的使用说明（鉴权是怎么做的、每条命令的输出与 JSON 字段、给脚本和 AI agent 的建议、更多的问题排查）随对外开通一起公布。

package/bin/buke.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// 启动器：构建产物不进仓库，这个文件进，所以命令的入口必须是它。逻辑都在 dist/main.js 里。
+const entry = new URL("../dist/main.js", import.meta.url)
+try {
+  await import(entry.href)
+} catch (error) {
+  // 只接「入口文件本身不存在」这一种；入口里面出的错照常抛，别被说成没有构建。
+  if (error?.code !== "ERR_MODULE_NOT_FOUND" || error.url !== entry.href) throw error
+  process.stderr.write("还没有构建：在仓库里先运行 npm run build -w bukesiyi-cli\n")
+  process.exitCode = 5
+}