skb-cli

SKB 命令行工具的 npm 包，与 Go 版 cli/ 命令完全兼容，共享 ~/.skb/config.json 配置。

默认 API 地址：https://skb-api.langboat.com

安装

要求：Node.js >= 18（使用了原生 fetch / FormData）

# 全局安装（推荐，可直接使用 skb-cli 命令）
npm install -g skb-cli

# 项目内安装（需通过 npx 或 .bin 调用）
npm install skb-cli
npx skb-cli help
# 或
./node_modules/.bin/skb-cli help

# 不安装，直接运行
npx skb-cli adm library list

npm install skb-cli（不加 -g）只会装到当前目录的 node_modules，不会加入系统 PATH，因此直接输入 skb-cli 会 command not found。请用 npm install -g 或 npx skb-cli。

Node 版本过低时

若看到 EBADENGINE 或 Node < 18：

# 查看版本
node -v

# 升级 Node（示例）
nvm install 18 && nvm use 18
npm install -g skb-cli

无法在容器内升级 Node 时，请改用 Go 二进制：

go build -o skb-cli ./cli
./skb-cli help

使用

skb-cli init --token sk-xxx
skb-cli config show
skb-cli config set debug on
skb-cli adm library list
skb-cli adm doc upload --file ./a.pdf --library-id 1
skb-cli open retrieval --query "关键词"
skb-cli --debug adm library list

编程式调用

const { loadConfig, createClient, defaultConfigPath } = require('skb-cli');

const cfg = loadConfig();
const client = createClient(cfg, true);

const libs = await client.getLibraries();
console.log(libs.data);

与 Go 版关系

| 方式 | 说明 | |------|------| | go build -o skb-cli ./cli | Go 原生二进制，无 Node 依赖 | | npm install -g skb-cli | Node.js 实现，需 Node >= 18 |

两者使用相同的配置文件和命令行接口，可互换使用。

子命令帮助：skb-cli <command> [subcommand] --help（详见 cli/README.md）。

npm 发布指南

包名：skb-cli
发布地址：https://registry.npmjs.org/

一、发布前准备

1. 拥有 npmjs.com 账号，且邮箱已验证
2. 确认 registry 指向官方源（不要用 npmmirror 等镜像发布）：

npm config get registry
# 应为 https://registry.npmjs.org/

# 若不是，执行：
npm config set registry https://registry.npmjs.org/

3. 不要设置空的 NPM_TOKEN 环境变量，也不要在项目内放置含无效 _authToken 的 .npmrc（会覆盖登录凭据）

二、创建 Access Token（账号开启 2FA 时必做）

npm 账号若开启了两步验证（2FA），不能仅用 npm login 密码发布，必须使用 Granular Access Token。

1. 打开 npm Access Tokens
2. 点击 Generate New Token → 选择 Granular Access Token
3. 按以下配置：

| 配置项 | 建议值 | |--------|--------| | Token name | skb-cli-publish（自定义） | | Expiration | 按需选择 | | Packages and scopes | 选择 Only select packages and scopes → 添加 skb-cli；或选 All packages | | Permissions | Read and write | | Organizations | 无需选择（skb-cli 为无 scope 包名） | | 2FA | 选择 Bypass 2FA（命令行 / CI 发布需要） |

4. 生成后复制 token（npm_ 开头，只显示一次）

说明：不要使用 @langboat/skb-cli 这类 scoped 包名，除非已在 npm 创建 @langboat 组织并授权，否则会报 404 Not Found。

三、配置 token 并发布

cd cli/npm

# 方式 A：写入 npm 配置（本地开发）
npm config set //registry.npmjs.org/:_authToken npm_你的token

# 方式 B：环境变量（推荐 CI）
export NPM_TOKEN=npm_你的token

# 确认身份
npm whoami

# 发布（prepublishOnly 会自动校验包可用性）
npm run publish:npm

四、发布后验证

npm view skb-cli version
npx skb-cli help

五、CI 发布

参考 .npmrc.example，在流水线中注入 NPM_TOKEN：

registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

六、常见错误

| 错误信息 | 原因 | 处理方式 | |----------|------|----------| | 404 Not Found（PUT） | 未登录、token 无效/为空，或 scoped 包无组织权限 | 检查 npm whoami；重新设置 token；无 scope 包名用 skb-cli | | 403 ... Two-factor authentication or granular access token... | 账号开启 2FA，未使用 Granular Token | 按「二」创建带 Bypass 2FA 的 Granular Access Token | | 403 Forbidden（包名） | 包名已被他人占用 | 修改 package.json 中的 name | | 发布到镜像源失败 | registry 指向 npmmirror 等 | npm config set registry https://registry.npmjs.org/ |

七、更新版本

修改 package.json 中的 version 后重新发布：

npm version patch   # 1.0.0 → 1.0.1
npm run publish:npm