bukesiyi-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,218 @@
-# 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.0
+```
+
+不想全局安装时，可以用 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 上：全局安装之后就在。
+
+## 安全须知
+
+- 密钥就是权限：拿到它的人，可以用你的账号在那个制片空间里调用开放接口。
+- 密钥只要进过命令行参数、地址、日志、截图、聊天或者和 AI 的对话，就当作已经泄露：吊销它，换一把新的。
+- `buke logout` 只删除本机的文件，**不等于吊销**；密钥在服务端仍然有效。
+- 吊销和新建都由账号本人在 Studio 账号页的「API 密钥」里做：<https://buke41.com/account/api-keys>。改登录密码不会让密钥失效，要作废只能吊销。
+- 输出里的公开前缀（形如 `bk_test_0123456789abcdef`）、密钥编号、追踪编号、错误码可以放心给别人看；完整的密钥不会出现在输出里。
+- 每台机器、每条流水线、每个 agent 各用一把密钥，能设有效期就设。
+
+## 从仓库源码运行
+
+这一节只给拿得到代码仓库、要改这个工具的人；只是使用的话，按上面「安装」一节从 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 的启动文件。
+
+## 更多
+
+完整的使用说明（鉴权是怎么做的、密钥的三种给法、地址规则、每条命令的输出与 JSON 字段、错误对照表、给脚本和 AI agent 的建议、常见问题排查）在代码仓库的 `docs/open-api/cli.md` 里，随开放接口开通后对外公布。在那之前，这份说明没写到的地方，请联系客服。

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
+}