@ 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 | 运算符 PostgreSQL | OIDC( 美国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),最高第一:
explicit呼叫者传递的值( 例如类)options.ai(中文(简体) )- 页:1
ai块provider, (中文(简体) ),model, (中文(简体) ),baseUrl, (中文(简体) ),apiKeyEnv; 遗产packages.ai见下文ai(中文(简体) ) - 环境,一次一个前缀:
<PREFIX>_PROVIDER, (中文(简体) ),_API_KEY, (中文(简体) ),_BASE_URL, (中文(简体) ),_MODEL页:1SMRT_AI,则HAVE_AI - 选定提供者自己的密钥变量( q)
OPENAI_API_KEY, (中文(简体) ),ANTHROPIC_API_KEY, (中文(简体) ),GEMINI_API_KEY; 从未使用过任何其他提供者的密钥 - 未选择提供者, 自动检测第一个关键变量被设定的提供者( 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(中文(简体) ) |
优先权顺序
配置合并( 最高到最低) :
- 运行时间通过
setConfig() - 配置文件( E)
smrt.config.{js,ts,json}(中文(简体) ) - 软件包/模块默认
密钥类型
SmrtConfig, (中文(简体) ), SmrtGlobalConfig, (中文(简体) ), ApplicationRuntimeConfig, (中文(简体) ), ResolvedApplicationRuntime, (中文(简体) ), RuntimeProviders, (中文(简体) ), RuntimeCapabilities, (中文(简体) ), RuntimeInvariants, (中文(简体) ), RuntimeProfileValidationError, (中文(简体) ), DatabaseConfig, (中文(简体) ), SiteConfig, (中文(简体) ), MigrationsConfig, (中文(简体) ), LoadConfigOptions, (中文(简体) ), ExportConfig, (中文(简体) ), ExportConfigOptions
依赖关系
没有兄弟包依赖性 。 这是一个奠基软件包.