@ganziliang/kb-model-setup 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,227 @@
+# @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 项目中直接使用：
+
+```bash
+npm install @ganziliang/kb-model-setup
+```
+
+全局安装仅适用于需要调试或单独管理该模块的情况：
+
+```bash
+npm install -g @ganziliang/kb-model-setup
+```
+
+安装 `@ganziliang/kb` 时会自动安装此依赖：
+
+```bash
+npm install -g @ganziliang/kb
+```
+
+## 在 kb 中使用
+
+通常不需要直接调用本包。安装并启动 `kb`：
+
+```bash
+kb
+```
+
+首次启动时，`kb` 会自动进入模型配置流程，依次询问：
+
+1. 智真 `api-stats` 页面地址或 `apiId`
+2. API Key
+
+可粘贴以下形式的 `api-stats` 页面地址：
+
+```text
+https://llm-gateway.zhizhengroup.com/admin-next/api-stats?apiId=<你的apiId>
+```
+
+也可以直接输入 `apiId`。模块随后会查询可用模型，并优先选择 `gpt-5.6-luna`；如果该模型不可用，则选择其他可用 GPT 模型，或者选择可用的 Anthropic 模型。
+
+模型配置由 `kb` 保存到：
+
+```text
+~/.config/kb/config.json
+```
+
+Windows 示例：
+
+```text
+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 示例：
+
+```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 配置示例：
+
+```powershell
+$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`
+
+创建模型配置扩展：
+
+```js
+import { createModelSetupExtension } from "@ganziliang/kb-model-setup";
+
+const setup = createModelSetupExtension();
+```
+
+#### `configure(prompter)`
+
+使用自定义交互提示器配置模型。提示器需要实现 `SetupPrompter` 接口：
+
+```ts
+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>;
+};
+```
+
+示例：
+
+```ts
+const config = await setup.configure(prompter);
+console.log(config);
+```
+
+返回的配置结构：
+
+```ts
+type ModelConfig = {
+  provider: string;
+  api: "openai-responses" | "anthropic-messages";
+  model: string;
+  baseURL: string;
+  apiKey: string;
+};
+```
+
+### `validate(config)`
+
+校验模型配置并返回错误信息数组：
+
+```ts
+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`
+
+从环境变量读取配置：
+
+```ts
+import { configFromEnvironment } from "@ganziliang/kb-model-setup";
+
+const config = configFromEnvironment();
+if (!config) {
+  console.log("环境变量配置不完整或无效");
+}
+```
+
+也可以传入自定义环境变量对象，便于测试：
+
+```ts
+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 查询接口：
+
+```text
+https://llm-gateway.zhizhengroup.com/apiStats/api/user-stats
+```
+
+## 安全提示
+
+- API Key 会被保存到 `kb` 的配置文件中，请不要将该文件提交到 Git。
+- 不要在日志、截图或公开文档中暴露 API Key。
+- `apiId` 和 API Key 应仅使用有权限的账号信息。
+
+## 开发和测试
+
+在源码目录执行：
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+源码位于 `src/index.ts`，编译产物位于 `dist/`。修改源码后需要重新执行 `npm run build`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganziliang/kb-model-setup",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Interactive model configuration for the kb local knowledge base agent",
   "type": "module",
   "main": "dist/index.js",