Package Exports

@deepracticex/ai-config
@deepracticex/ai-config/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@deepracticex/ai-config) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@deepracticex/ai-config

一个极简的 AI 配置管理库，专注于配置存储和偏好管理。基于"如非必要，勿增实体"的设计原则。

🎯 设计原则

职责纯粹 - 只做配置存储，不预设业务逻辑
基础设施 - 提供稳定的数据持久化能力
消费者驱动 - 让使用者决定默认值和业务规则
类型安全 - 完整的 TypeScript 支持

🌟 特性

✅ 极简设计 - 只保留核心的配置和偏好管理功能
✅ 本地存储 - 基于 SQLite 的本地数据库，不依赖外部服务
✅ 跨项目共享 - 配置存储在用户目录，多个项目可共享
✅ 完整 TypeScript 支持 - 类型安全，智能提示
✅ 简单 API - 就像操作对象一样简单
✅ 零预设 - 不强加任何默认值，保持基础设施的纯粹性
✅ 偏好管理 - 分类管理用户偏好设置

📦 安装

npm install @deechat/ai-config

🚀 快速开始

基础用法

import { initializeAIConfig, getProvider, createConfig, getResolvedConfig } from '@deechat/ai-config';

// 1. 初始化（自动创建本地数据库 ~/.ai-config/config.db）
await initializeAIConfig();

// 2. 查看预置的供应商
const openai = getProvider('openai');
console.log(openai.display_name); // "OpenAI"

// 3. 创建配置
await createConfig({
  provider_code: 'openai',
  config_name: 'my-config',
  config_data: { 
    apiKey: 'sk-your-api-key-here',
    model: 'gpt-4',
    temperature: 0.7
  }
});

// 4. 使用配置（自动合并供应商默认值）
const config = await getResolvedConfig('openai', 'my-config');
console.log(config.merged_config);
// {
//   apiKey: 'sk-your-api-key-here',
//   model: 'gpt-4',
//   temperature: 0.7,
//   baseUrl: 'https://api.openai.com/v1'  // 来自供应商默认值
// }

高级用法

import { AIConfigManager } from '@deechat/ai-config';

// 使用自定义配置
const manager = new AIConfigManager({
  database_path: '/custom/path/config.db',
  auto_migrate: true,
  backup_enabled: true
});

await manager.initialize();

// 供应商管理
const providers = manager.providers.findAll({ is_enabled: true });
const openaiConfigs = manager.configs.findByProvider('openai');

// 偏好管理
await manager.preferences.set({
  key: 'default_provider',
  value: 'openai',
  category: 'ai'
});

const theme = manager.preferences.getWithDefault('ui_theme', 'system');

// 获取统计信息
const stats = await manager.getStats();
console.log(stats);

📖 详细文档

供应商管理

预置供应商包括：OpenAI、Anthropic Claude、Google Gemini、Ollama 等。

import { createProvider, getProviders, getProvider } from '@deechat/ai-config';

// 查看所有供应商
const allProviders = getProviders();

// 查看启用的供应商
const enabledProviders = getProviders({ is_enabled: true });

// 添加自定义供应商
await createProvider({
  provider_code: 'my-ai',
  display_name: 'My AI Service',
  default_base_url: 'https://api.my-ai.com/v1',
  supported_models: ['my-model-1', 'my-model-2'],
  default_model: 'my-model-1',
  description: 'My custom AI service'
});

配置管理

import { createConfig, getConfig, getResolvedConfig } from '@deechat/ai-config';

// 创建配置
await createConfig({
  provider_code: 'anthropic',
  config_name: 'production',
  config_data: {
    apiKey: 'sk-ant-xxx',
    model: 'claude-3-5-sonnet-20241022',
    maxTokens: 4096
  },
  is_default: true  // 设为默认配置
});

// 获取配置
const config = getConfig('anthropic', 'production');

// 获取默认配置
const defaultConfig = getConfig('anthropic');

// 获取解析后的配置（合并供应商默认值）
const resolved = await getResolvedConfig('anthropic');

偏好管理

import { setPreference, getPreference } from '@deechat/ai-config';

// 设置偏好
await setPreference('ui_theme', 'dark', 'ui', 'UI theme preference');
await setPreference('max_tokens', 4096, 'ai');

// 获取偏好
const theme = getPreference('ui_theme');
const maxTokens = getPreference('max_tokens', 2048); // 带默认值

// 批量操作
const manager = getAIConfigManager();
await manager.preferences.setBatch({
  'request_timeout': 30000,
  'retry_attempts': 3,
  'log_level': 'info'
}, 'system');

🗄️ 数据库架构

-- 供应商表
CREATE TABLE providers (
    provider_code TEXT PRIMARY KEY,
    display_name TEXT NOT NULL,
    default_base_url TEXT,
    supported_models TEXT,  -- JSON 数组
    default_model TEXT,
    config_schema TEXT,     -- JSON Schema
    description TEXT,
    is_enabled BOOLEAN DEFAULT 1
);

-- 配置表
CREATE TABLE configs (
    id INTEGER PRIMARY KEY,
    provider_code TEXT NOT NULL,
    config_name TEXT NOT NULL,
    config_data TEXT NOT NULL,  -- JSON 对象
    is_default BOOLEAN DEFAULT 0,
    is_active BOOLEAN DEFAULT 1,
    FOREIGN KEY (provider_code) REFERENCES providers(provider_code)
);

-- 偏好表
CREATE TABLE preferences (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,  -- JSON 值
    category TEXT,
    description TEXT
);

📁 文件结构

~/.ai-config/
├── config.db          # SQLite 数据库
└── backup-*.db        # 自动备份文件（可选）

🔧 配置选项

interface DatabaseOptions {
  database_path?: string;    // 自定义数据库路径
  auto_migrate?: boolean;    // 自动迁移数据库（默认 true）
  backup_enabled?: boolean;  // 启用备份（默认 true）
  readonly?: boolean;        // 只读模式（默认 false）
}

🧪 测试

npm test           # 运行测试
npm run test:watch # 监听模式
npm run test:coverage # 覆盖率报告

📊 示例：完整的使用流程

import { 
  initializeAIConfig, 
  createConfig, 
  getResolvedConfig,
  setPreference,
  getPreference 
} from '@deechat/ai-config';

async function setupAIConfig() {
  // 初始化
  await initializeAIConfig();

  // 配置 OpenAI
  await createConfig({
    provider_code: 'openai',
    config_name: 'development',
    config_data: {
      apiKey: process.env.OPENAI_API_KEY!,
      model: 'gpt-4o-mini', // 开发环境用便宜的模型
      temperature: 0.7
    }
  });

  await createConfig({
    provider_code: 'openai', 
    config_name: 'production',
    config_data: {
      apiKey: process.env.OPENAI_API_KEY!,
      model: 'gpt-4o', // 生产环境用最好的模型
      temperature: 0.5
    },
    is_default: true // 设为默认
  });

  // 设置全局偏好
  await setPreference('default_provider', 'openai', 'ai');
  await setPreference('request_timeout', 30000, 'ai');
  await setPreference('ui_theme', 'system', 'ui');

  // 在应用中使用
  const defaultProvider = getPreference('default_provider');
  const config = await getResolvedConfig(defaultProvider);
  
  console.log('🎯 AI 配置就绪！');
  console.log('Provider:', defaultProvider);
  console.log('Config:', config.merged_config);
}

📝 API 文档

便利函数

initializeAIConfig(options?) - 初始化全局管理器
getAIConfigManager() - 获取全局管理器
closeAIConfig() - 关闭全局管理器

供应商操作

createProvider(input) - 创建供应商
getProvider(code) - 获取供应商
getProviders(options?) - 获取供应商列表

配置操作

createConfig(input) - 创建配置
getConfig(provider, name?) - 获取配置
getResolvedConfig(provider, name?) - 获取解析配置

偏好操作

setPreference(key, value, category?, description?) - 设置偏好
getPreference(key, defaultValue?) - 获取偏好

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT

@deechat/ai-config - 让 AI 配置管理变得简单！ 🚀