@ganziliang/kb-model-setup

@ganziliang/kb-model-setup 是 @ganziliang/kb 使用的模型配置模块，负责：

• 通过智真 LLM Gateway 查询账号可用模型
• 引导用户输入 apiId 和 API Key
• 自动选择可用的 OpenAI 或 Anthropic 模型
• 校验模型配置
• 从环境变量读取模型配置

这是一个配置扩展模块，不是独立的聊天命令行工具。普通用户安装 @ganziliang/kb 时会自动安装它，不需要单独操作。

环境要求

• Node.js >=22.5.0
• 能够访问智真 LLM Gateway
• 有效的 apiId 和模型 API Key

安装

如果要在其他 Node.js 项目中直接使用：

npm install @ganziliang/kb-model-setup

全局安装仅适用于需要调试或单独管理该模块的情况：

npm install -g @ganziliang/kb-model-setup

安装 @ganziliang/kb 时会自动安装此依赖：

npm install -g @ganziliang/kb

在 kb 中使用

通常不需要直接调用本包。安装并启动 kb：

kb

首次启动时，kb 会自动进入模型配置流程，依次询问：

1. 智真 api-stats 页面地址或 apiId
2. API Key

可粘贴以下形式的 api-stats 页面地址：

https://llm-gateway.zhizhengroup.com/admin-next/api-stats?apiId=<你的apiId>

也可以直接输入 apiId。模块随后会查询可用模型，并优先选择 gpt-5.6-luna；如果该模型不可用，则选择其他可用 GPT 模型，或者选择可用的 Anthropic 模型。

模型配置由 kb 保存到：

~/.config/kb/config.json

Windows 示例：

C:\Users\<用户名>\.config\kb\config.json

环境变量配置

如果不想使用交互式配置，可以设置以下完整环境变量：

| 环境变量 | 说明 | | --- | --- | | KB_PROVIDER | 模型提供方名称，例如 company-gpt | | KB_API | API 协议，只支持 openai-responses 或 anthropic-messages | | KB_MODEL | 模型名称 | | KB_BASE_URL | 模型网关基础地址 | | KB_API_KEY | API Key |

PowerShell 示例：

$env:KB_PROVIDER = "company-gpt"
$env:KB_API = "openai-responses"
$env:KB_MODEL = "gpt-5.6-luna"
$env:KB_BASE_URL = "https://llm-gateway.zhizhengroup.com/openai"
$env:KB_API_KEY = "你的APIKey"
kb

Anthropic 配置示例：

$env:KB_PROVIDER = "company-anthropic"
$env:KB_API = "anthropic-messages"
$env:KB_MODEL = "你的Anthropic模型"
$env:KB_BASE_URL = "https://llm-gateway.zhizhengroup.com/api"
$env:KB_API_KEY = "你的APIKey"
kb

环境变量必须全部设置且通过校验，否则程序会回退到交互式配置流程。

编程接口

createModelSetupExtension

创建模型配置扩展：

import { createModelSetupExtension } from "@ganziliang/kb-model-setup";

const setup = createModelSetupExtension();

configure(prompter)

使用自定义交互提示器配置模型。提示器需要实现 SetupPrompter 接口：

type SetupPrompter = {
  ask(question: string, initial?: string): Promise<string>;
  select(question: string, choices: string[], initial?: number): Promise<number>;
  confirm(question: string): Promise<boolean>;
  notice(message: string): Promise<void>;
};

示例：

const config = await setup.configure(prompter);
console.log(config);

返回的配置结构：

type ModelConfig = {
  provider: string;
  api: "openai-responses" | "anthropic-messages";
  model: string;
  baseURL: string;
  apiKey: string;
};

validate(config)

校验模型配置并返回错误信息数组：

const errors = setup.validate({
  provider: "company-gpt",
  api: "openai-responses",
  model: "gpt-5.6-luna",
  baseURL: "https://llm-gateway.zhizhengroup.com/openai",
  apiKey: "your-api-key",
});

if (errors.length > 0) {
  console.error(errors);
}

返回空数组表示配置有效。

configFromEnvironment

从环境变量读取配置：

import { configFromEnvironment } from "@ganziliang/kb-model-setup";

const config = configFromEnvironment();
if (!config) {
  console.log("环境变量配置不完整或无效");
}

也可以传入自定义环境变量对象，便于测试：

const config = configFromEnvironment({
  KB_PROVIDER: "company",
  KB_API: "anthropic-messages",
  KB_MODEL: "model-a",
  KB_BASE_URL: "https://example.test",
  KB_API_KEY: "secret",
});

支持的协议

当前支持两种协议：

• openai-responses
• anthropic-messages

模块使用固定的智真 LLM Gateway 查询接口：

https://llm-gateway.zhizhengroup.com/apiStats/api/user-stats

安全提示

• API Key 会被保存到 kb 的配置文件中，请不要将该文件提交到 Git。
• 不要在日志、截图或公开文档中暴露 API Key。
• apiId 和 API Key 应仅使用有权限的账号信息。

开发和测试

在源码目录执行：

npm install
npm run typecheck
npm run build
npm test

源码位于 src/index.ts，编译产物位于 dist/。修改源码后需要重新执行 npm run build。