# @happyvertical/smrt-config 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-config/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:53:45.091Z
中文译文更新时间：2026-11-17T09:27:59.676Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-config
原文对照：https://npmcn.com/package/%40happyvertical/smrt-config/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：530 kB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-06-23T01:18:29.351Z
- 最新版本发布：2026-11-17T07:53:44.873Z
- 近 30 天下载量：50094（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 366 个）

## 中文简介

SMRT模块的集中配置管理

## 安装

```sh
npm install @happyvertical/smrt-config
```

也可以使用：`pnpm add @happyvertical/smrt-config`、`yarn add @happyvertical/smrt-config`、`bun add @happyvertical/smrt-config`

## README

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

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

## 安装

```bash
pnpm add @happyvertical/smrt-config
```

## 使用量

### 创建配置文件

```javascript
// 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` 恢复 行动.

```typescript
// 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' },
    },
  },
});
```

```typescript
// 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` 本地对讲平台 服务。 见 [起草部署合同](https://github.com/happyvertical/smrt/blob/main/docs/content/deployment-compose.md) 字段和所支持的平台子集.

```typescript
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()` 服务器侧应用列表。 见 部署指南"发布平台运营商申报".

### 在代码中使用配置

```typescript
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' },
  },
});
```

### 类型安全配置文件

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

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

### SSG 安全出口

```typescript
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`;在环境中保守秘密.

```ts
export default defineConfig({
  ai: { provider: 'openai', model: 'gpt-4o', apiKeyEnv: 'OPENAI_API_KEY' },
});
```

```ts
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 是什么？

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 和提交记录判断。

