@happyvertical/smrt-config

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5万

SMRT模块的集中配置管理

中文使用文档
文档目录14 节
  1. 安装
  2. 使用量
  3. 创建配置文件
  4. 应用程序运行时间配置
  5. 起草部署合同
  6. 在代码中使用配置
  7. 类型安全配置文件
  8. SSG 安全出口
  9. AI 供应商
  10. API 密码
  11. 职能
  12. 优先权顺序
  13. 密钥类型
  14. 依赖关系

@ happyvertical/ smrt- config( 欢快的垂直) name

S-m-r-t框架的集中配置管理. 用途 宇宙图 要装入 smrt.config.{js,ts,json} 文件,包含秘密消毒和SSG安全导出.

安装

pnpm add @happyvertical/smrt-config

使用量

创建配置文件

// smrt.config.js
export default {
  runtime: {
    profile: 'local',
  },

  smrt: {
    cacheDir: '.cache',
    logLevel: 'info',
  },

  packages: {
    ai: {
      defaultProvider: 'anthropic',
      defaultModel: 'claude-sonnet-4-20250514',
      apiKeys: {
        anthropic: process.env.ANTHROPIC_API_KEY,
      },
    },
  },

  modules: {
    'town-scraper': {
      cronSchedule: '0 0 * * *',
      maxPages: 100,
    },
  },
};

应用程序运行时间配置

runtime.profile 选择一个有效的基础设施组成,而不包含 用于创建应用程序对象或工作流程。 启动前进行验证; 不支持的组合 RuntimeProfileValidationError 恢复 行动.

// smrt.config.ts
import { defineConfig } from '@happyvertical/smrt-config';

export default defineConfig({
  runtime: {
    profile: 'self-hosted',
    providers: {
      authentication: { provider: 'magic-link' },
      tenancy: { mode: 'multi-tenant', context: 'required' },
      assets: { provider: 'local-files' },
    },
  },
});
// application startup
import {
  loadConfig,
  resolveConfiguredApplicationRuntime,
} from '@happyvertical/smrt-config';

await loadConfig();
const runtime = resolveConfiguredApplicationRuntime();
// Safe for doctor output and agent inspection: provider selectors and derived
// capabilities are present; URLs, paths, credentials, and secret values are not.
console.log(JSON.stringify(runtime));
简介数据库认证租赁资产/秘密工作网络
local用户拥有的 SQLite单用途所有者拖带实际默认租户用户拥有的本地文件嵌入( n)inline 允许的覆盖)循环
self-hosted运算符 PostgreSQLOIDC( 美国magic-link 或者说 password 允许)单身租户multi-tenant 允许)S3相容 + 环境机密(允许记录本地/外部重置)外部工人公开 TLS
cloud管理 PostgreSQL主机身份需要的多租户上下文、应用程序隔离或 RLS管理对象存储/机密可扩展工人公开 TLS

每个配置文件都支持逻辑导出/导入. 本地概况 广告文件- snapshot 备份; 部署配置文件指定物理备份 操作员或管理下的提供者.

覆盖接合只选择基础设施提供者。 无法修改 域模型,生成REST/CLI/MCP/WebMCP定义,动作效果 元数据、批准政策、授权记录或职务引用 API. 这些是互不相识的变种,在每一个解开的快照中都有所释放出. 提供方的实施工作保持其证书和连接值 自己的配置; 不将这些值添加到 runtime.providers。 。 。 .

使用 resolveApplicationRuntime(config.runtime) 纯粹、明确的价值 作为测试固定。 应用程序启动应使用 resolveConfiguredApplicationRuntime(): 它由已载入的文件组成 最高优先事项 setConfig() 在验证前覆盖 . getConfig() 保留 它的后遗症意义和返回只包含文件状态。 相继 setConfig() 在配置文件不变时调用深层提供者; 明确配置文件 在应用新程序之前, 切换先前运行时间提供者的选择 简介.

可忽略块用途的应用程序 resolveEffectiveApplicationRuntime(await loadConfig()),规则 smrt app 和 SvelteKit 运行时共享 : 当文件或 a setConfig() 覆盖声明 runtime,该简介是 local; 当前值为 非运行时块( n)null, (中文(简体) ), false, (中文(简体) ), 0, (中文(简体) ), '')抛出相同的 RuntimeProfileValidationError 而不是选择 local· ; setConfig() 拒绝这样的 runtime 在存储任何信息之前, 使用这个错误 .

起草部署合同

@happyvertical/smrt-config/deployment 读取应用程序的编译文件为 其部署申报。 文件携带 x-happyvertical 扩展字段 (合同版本1):一个顶级区块,与 preset, (中文(简体) ), domain 财务报告和审定财务报表 migrate, (中文(简体) ), role: web|worker 带有 health 检查应用程序运行的服务, 财务报告和审定财务报表 binding: postgres|bucket|email|ai 本地对讲平台 服务。 见 起草部署合同 字段和所支持的平台子集.

import { parse } from 'yaml';
import {
  formatComposeDeploymentReport,
  renderSmrtAppChartValues,
  validateComposeDeployment,
} from '@happyvertical/smrt-config/deployment';

// The entry does no I/O: parse the YAML yourself, with merge keys enabled.
const document = parse(composeText, { merge: true });

// `declare` checks the file as written; `deploy` also requires image digests.
const result = validateComposeDeployment(document, {
  stage: 'deploy',
  images: { web: webDigest, worker: workerDigest },
});
if (!result.ok) throw new Error(formatComposeDeploymentReport(result));

// Self-host rendering: values for the smrt-app chart.
const values = renderSmrtAppChartValues(result.declaration, inputs);

每个问题都有 code页:1 path 输入文件,一种普通语言 message (单位:千美元) fix未加说明的服务作为警告报告:它们在当地运行 而且从未部署过 说明的JSON Schema作为 @happyvertical/smrt-config/schemas/x-happyvertical.v1.schema.json从 a 终端, 使用 smrt deploy:check 财务报告和审定财务报表 smrt deploy:chart-values。 。 。 .

要在平台运营商上主持同样的声明, composeHostedApp() (相同的条目) 转动它+ 呼叫者提供的权利(批准的约束, 已验证域,音量大小)为 a HostedApp 显示或结构 拒绝. @happyvertical/smrt-config/deployment/hosting 持有 I/O: readGitHubComposeDeclaration() 读取文件的准确承诺和 createHostedAppApplier() 服务器侧应用列表。 见 部署指南"发布平台运营商申报".

在代码中使用配置

import { loadConfig, getPackageConfig, getModuleConfig, setConfig } from '@happyvertical/smrt-config';

// Load config from file (cosmiconfig auto-discovery)
await loadConfig();

// Get package-scoped config with defaults
const aiConfig = getPackageConfig('ai', {
  defaultProvider: 'openai',
  defaultModel: 'gpt-4',
});

// Get module-scoped config with defaults
const scraperConfig = getModuleConfig('town-scraper', {
  cronSchedule: '0 0 * * *',
  maxPages: 50,
});

// Runtime overrides (highest priority)
setConfig({
  packages: {
    ai: { defaultModel: 'gpt-4-turbo' },
  },
});

类型安全配置文件

import { defineConfig } from '@happyvertical/smrt-config';

export default defineConfig({
  smrt: {
    logLevel: 'info',
  },
  packages: {
    ai: {
      defaultProvider: 'anthropic',
    },
  },
});

SSG 安全出口

import { loadConfig, exportConfig, sanitizeConfig } from '@happyvertical/smrt-config';

const config = await loadConfig();

// Export config without secrets (safe for static site generation)
const safeJson = exportConfig(config, { includeSecrets: false });

// Or manually sanitize — strips secret-bearing keys (case-insensitive, across
// camelCase / snake_case / kebab / UPPER variants): apiKey, password, secret,
// token, credential, private, oauth, authorization, accessKey, signingKey, encryptionKey,
// connectionString, dbUrl, cookie, salt, cert, and similar. Biases toward
// over-redaction; pass `{ includeSecrets: true }` to opt out.
const sanitized = sanitizeConfig(config);

AI 供应商

宣布一个助手模式 smrt.config.ts;在环境中保守秘密.

export default defineConfig({
  ai: { provider: 'openai', model: 'gpt-4o', apiKeyEnv: 'OPENAI_API_KEY' },
});
import { resolveConfiguredAIProvider, toAIClientOptions } from '@happyvertical/smrt-config';
import { getAI } from '@happyvertical/ai';

const ai = await getAI(toAIClientOptions(resolveConfiguredAIProvider()));

默认优先,每个字段适用(provider, (中文(简体) ), apiKey, (中文(简体) ), baseUrl, (中文(简体) ), model),最高第一:

  1. explicit 呼叫者传递的值( 例如类) options.ai(中文(简体) )
  2. 页:1 ai 块provider, (中文(简体) ), model, (中文(简体) ), baseUrl, (中文(简体) ), apiKeyEnv; 遗产 packages.ai 见下文 ai(中文(简体) )
  3. 环境,一次一个前缀: <PREFIX>_PROVIDER, (中文(简体) ), _API_KEY, (中文(简体) ), _BASE_URL, (中文(简体) ), _MODEL 页:1 SMRT_AI,则 HAVE_AI
  4. 选定提供者自己的密钥变量( q)OPENAI_API_KEY, (中文(简体) ), ANTHROPIC_API_KEY, (中文(简体) ), GEMINI_API_KEY; 从未使用过任何其他提供者的密钥
  5. 未选择提供者, 自动检测第一个关键变量被设定的提供者( openai、 人类 、 gemini)

证书绑定:一个密钥或基础 URL 属于由自己来源命名的提供者(说明 ai block,或一个env前缀). 如果高优先级源选择不同的提供者,则下 源的密钥和碱基 URL 被丢弃, 而密钥只来自对所选对象有效的来源 提供者(然后是提供者自己的关键变量)。 一个提供密钥的源头, 但是没有提供者的名称 通用并绑定在所选择的提供者。 显示基准 URL (E)toJSON(), (中文(简体) ), describeAIProviderConfig(), (中文(简体) ), redactBaseUrl())只披露来源;真实的URL仍然去客户端. 规则在每一层: ai 块层(运行时间) ai运行时间 packages.ai,文件 ai,文件 packages.ai(中文(简体) ) 与供应商所有权合并mergeAIConfigLayers:当较高层命名不同的提供者时,下层 层' apiKey, (中文(简体) ), apiKeyEnv, (中文(简体) ), baseUrl 财务报告和审定财务报表 model 被丢弃(模型代号是针对提供者的)。 没有提供者的层 绑定到目前所选择的提供者 。 核心在其全球范围内适用同样的规则 ai 配置和 options.ai,而且总是 从解析器的定点结果构建客户端. 离子在结合之前是常态化的(provider编号 :type, (中文(简体) ), model编号 :defaultModel),所以一个空白的初级从不隐藏别名. 所有对象的合并都通过一个可控辅助器, mergeAIConfigObjects(lower, higher) (单位:倍) provider编号 :type 财务报告和审定财务报表 model编号 :defaultModel,将空投,并将下方的提供者、密钥、密钥变量、基址和模型 当更高的边名指定不同的提供者时:累积 setConfig({ ai }) 编号 : setConfig({ packages: { ai } }), (中文(简体) ), mergeExportedConfig ai 和核心的全球 ai + 键 options.ai。 。 。 . withAIAliases() 在最终结果上设置两个客户端化名. 核心仅在区块命名时查阅 provider; 局部块的行为像没有块.

呼叫网站通过选项保持历史顺序: 聊天- dev 路由通过 prefixes: ['SMRT_CHAT_DEV', 'SMRT_AI', 'HAVE_AI'] 财务报告和审定财务报表 envOverridesConfig: true; 核心传出 prefixes: ['SMRT_AI'], (中文(简体) ), autoDetect: false。 。 。 . resolveAIProviderConfig 掷出 AIProviderNotConfiguredError (仅命名变量)当没有配置时; tryResolveAIProviderConfig 返回时 undefined。结果编辑密钥 toJSON() 编号 : describeAIProviderConfig();错误从不包含密钥或 URL 证书.

API 密码

职能

导出说明
loadConfig(options?)通过宇宙onfig从文件加载Async
getConfig()获得完整的合并配置
getPackageConfig(name, defaults?)获取套件扫描配置区域
getModuleConfig(name, defaults?)获得模块扫描配置部分
getSiteConfig()获取站点级别配置
setConfig(overrides)运行时间覆盖( 最高优先级)
clearCache()重置缓存配置( 全球 —— 影响所有模块)
defineConfig(config)类型安全配置文件帮助器
exportConfig(config, options?)SSG 安全导出( 默认为无秘密)
sanitizeConfig(config)移除密钥
resolveApplicationRuntime(config)解析和关闭失败验证运行时配置文件
resolveConfiguredApplicationRuntime()解析有效的文件外加运行时间覆盖的配置配置配置
resolveEffectiveApplicationRuntime(config)一样,但不行 runtime 块( 文件或覆盖) 选择 local; 当前非块值未关闭
getApplicationRuntimePreset(profile)检查一个不可更改的配置预设副本
resolveCliDatabaseConfig(env?)这个 smrt 编号 : smrt-dev-mcp 数据库:已配置 packages.cli.database.url,则 DATABASE_URL 编号 : DATABASE_TYPE (只读)
mergeExportedConfig(baseConfig, exportedConfig)将导出配置合并到一个碱基上
parseExportedConfig(raw)解析导出配置字符串
resolveAIProviderConfig(options?) 编号 : tryResolveAIProviderConfig(options?)纯解析器( 推出/ 返回) undefined 未配置时)
resolveConfiguredAIProvider(options?) 编号 : tryResolveConfiguredAIProvider(options?)相同,对已装入的 ai 块
getAIConfigBlock()有效 ai 块(运行时间 > 文件; ai > 翻译: packages.ai(中文(简体) )
toAIClientOptions(resolved)getAI() 选项(type, (中文(简体) ), provider, (中文(简体) ), apiKey, (中文(简体) ), baseUrl, (中文(简体) ), defaultModel(中文(简体) )

优先权顺序

配置合并( 最高到最低) :

  1. 运行时间通过 setConfig()
  2. 配置文件( E)smrt.config.{js,ts,json}(中文(简体) )
  3. 软件包/模块默认

密钥类型

SmrtConfig, (中文(简体) ), SmrtGlobalConfig, (中文(简体) ), ApplicationRuntimeConfig, (中文(简体) ), ResolvedApplicationRuntime, (中文(简体) ), RuntimeProviders, (中文(简体) ), RuntimeCapabilities, (中文(简体) ), RuntimeInvariants, (中文(简体) ), RuntimeProfileValidationError, (中文(简体) ), DatabaseConfig, (中文(简体) ), SiteConfig, (中文(简体) ), MigrationsConfig, (中文(简体) ), LoadConfigOptions, (中文(简体) ), ExportConfig, (中文(简体) ), ExportConfigOptions

依赖关系

没有兄弟包依赖性 。 这是一个奠基软件包.

版本与发布记录

@happyvertical/smrt-config 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-config 的常见问题

@happyvertical/smrt-config 是什么?

SMRT模块的集中配置管理

如何安装 @happyvertical/smrt-config?

在项目目录运行 npm install @happyvertical/smrt-config,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-config 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-config 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-config 可以商用吗?

@happyvertical/smrt-config 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-config 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-config 在 2026/10/17 – 2026/11/15 这 30 天内被下载 50,094 次,日均约 1,670 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-config 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。