@jacksontian/aispm

用于管理 AI Provider 配置的 TypeScript 库，提供类型定义、归一化、当前激活 Provider 解析，以及 JSON / 文件读写能力。

Features

• 管理 ProviderRegistry、Provider、BaseUrl、ApiKey、Model
• 归一化配置数据，补齐默认值并修正无效引用
• 解析当前激活 Provider 的运行时配置
• 读写带版本号的 JSON 配置文件

Installation

npm i @jacksontian/aispm

Requirements

• ESM 环境
• 支持 async / await 的现代 JavaScript 运行时
• TypeScript 项目可直接获得类型定义

Basic Example

import {
  load,
  resolve,
} from '@jacksontian/aispm';

const registry = await load('./provider-registry.json', {
  missing: 'empty',
});

const activeProfile = resolve(
  registry.providers,
  registry.activeProviderId
);

console.log(activeProfile?.baseUrl);
console.log(activeProfile?.apiKey);

Quick Start

下面示例演示一个完整流程：加载配置、添加 Provider、修改字段、删除条目、解析当前激活项并保存。

import {
  BaseUrlKind,
  ModelIOKind,
  emptyProvider,
  makeId,
  normalizeBaseUrlString,
  resolve,
  load,
  save,
} from '@jacksontian/aispm';

const filePath = './provider-registry.json';

// 加载配置；文件不存在时返回空配置
const registry = await load(filePath, { missing: 'empty' });

// 添加 Provider
let provider = registry.providers.find((item) => item.id === 'openai');
if (!provider) {
  provider = emptyProvider();
  provider.id = 'openai';
  provider.name = 'OpenAI';
  registry.providers.push(provider);
}

// 修改 Base URL
provider.baseUrls[0] = {
  id: provider.baseUrls[0]?.id ?? makeId(),
  url: normalizeBaseUrlString('https://api.openai.com/v1/'),
  baseUrlType: BaseUrlKind.OPENAI,
};

// 修改 API Key
provider.apiKeys[0] = {
  id: provider.apiKeys[0]?.id ?? makeId(),
  label: 'main',
  key: process.env.OPENAI_API_KEY ?? '',
};
provider.activeApiKeyId = provider.apiKeys[0].id;

// 添加或更新模型
provider.models = provider.models.filter((model) => model.id !== 'gpt-4o-mini');
provider.models.push({
  id: 'gpt-4o-mini',
  supportsThinking: false,
  supportsWebSearch: true,
  inputTypes: [ModelIOKind.TEXT, ModelIOKind.IMAGE],
  outputTypes: [ModelIOKind.TEXT],
});
provider.activeModelId = 'gpt-4o-mini';

// 删除不再使用的内容
provider.models = provider.models.filter((model) => model.id !== 'old-model');
registry.providers = registry.providers.filter((item) => item.id !== 'deprecated-provider');

// 设置当前激活 Provider
registry.activeProviderId = provider.id;

// 解析运行时配置
const activeProfile = resolve(
  registry.providers,
  registry.activeProviderId
);

console.log(activeProfile?.baseUrl);
console.log(activeProfile?.apiKey);
console.log(activeProfile?.activeModelId);

// 保存配置；保存时会自动归一化
await save(filePath, registry);

如果你只想处理 JSON 字符串，目前需要从内部存储模块自行使用相关工具函数，包入口不再导出它们。

Core Concepts

• ProviderRegistry：整个配置的根对象
• Provider：单个 AI 服务提供商配置
• BaseUrl：某个 Provider 的请求入口地址
• ApiKey：某个 Provider 下的一条 API 凭证记录
• Model：某个 Provider 提供的模型定义
• ActiveProviderProfile：当前激活 Provider 解析后的运行时配置视图

API

Registry

• normalizeProviderRegistry()：归一化任意输入为 ProviderRegistry
• emptyProvider()：创建空的 Provider

Runtime

• resolve()：解析当前激活 Provider 的运行时配置

Storage

• load()：从文件读取配置
• save()：保存配置到文件
• FORMAT_VERSION：当前磁盘格式版本号

File Format

磁盘上的配置文件采用带版本号的结构：

{
  "version": 1,
  "providers": [],
  "activeProviderId": null
}

• 当前库只接受带 version 的正式格式
• 版本不兼容时会抛出 ProviderRegistryVersionError

Error Handling

当配置文件缺少 version、版本过旧、或版本高于当前库支持范围时，读操作会抛出 ProviderRegistryVersionError。

import {
  ProviderRegistryVersionError,
  load,
} from '@jacksontian/aispm';

try {
  await load('./provider-registry.json');
} catch (error) {
  if (error instanceof ProviderRegistryVersionError) {
    console.error(error.fileVersion, error.supportedVersion);
  }
  throw error;
}

Development

npm run build
npm test
npm run test:coverage