# @happyvertical/smrt-profiles 中文文档

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

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

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

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

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

- 包体积（解压后）：2.2 MB，159 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2026-06-23T01:18:40.616Z
- 最新版本发布：2026-11-17T07:54:44.971Z
- 近 30 天下载量：27901（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

与SMRT框架的关系、元数据和对等协会的概况管理系统

## 安装

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

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

## README

# @ 快乐的垂直/ smrt- profile

中央身份系统,包含多自动(Nostr/OIDC/API密钥/魔法链接),关系,被控制的元数据,以及审计记录.

## 安装

```bash
pnpm add @happyvertical/smrt-profiles @happyvertical/sql
```

## 使用量

```typescript
import {
  backfillProfileEmailKeys,
  createProfileFromOidc,
} from '@happyvertical/smrt-profiles';
import { getDatabase } from '@happyvertical/sql';

// Connect after applying schema migrations.
const persistence = { type: 'sqlite' as const, url: 'file:profiles.db' };
// Mark migrated Profile email keys ready before enabling OIDC provisioning.
const db = await getDatabase(persistence);
await backfillProfileEmailKeys(db);

// Provision a new OIDC Profile or reuse its exact issuer/subject link.
const { profile, oidcIdentity, created } = await createProfileFromOidc(
  {
    iss: 'https://accounts.google.com',
    sub: 'abc123',
    email: 'olivia@example.com',
    email_verified: true,
    name: 'Olivia Smith',
  },
  'google',
  { db },
);
```

### 拥有资产

```typescript
import { AssetCollection } from '@happyvertical/smrt-assets';
import { ProfileCollection } from '@happyvertical/smrt-profiles';

const profiles = await ProfileCollection.create({ db });
const assets = await AssetCollection.create({ db });

const headshot = await assets.create({
  name: 'alice-headshot.jpg',
  sourceUri: 'file:///tmp/alice-headshot.jpg',
  mimeType: 'image/jpeg',
});

await profile.addAsset(headshot, 'avatar');
await profiles.addAsset(profile.id!, headshot, 'gallery', 1);

const avatarAssets = await profile.getAssets('avatar');
const galleryAssets = await profiles.getAssets(profile.id!, 'gallery');
```

### 网络链接

概况的社会账户和网站,按显示顺序排列. 几个链接 平台被允许;同一地址被保留一次。 新链接取 档案的房客, 他们被删除 与档案.

```typescript
import { ProfileLinkCollection } from '@happyvertical/smrt-profiles';

await profile.setLinks([
  { platform: 'facebook', url: 'https://facebook.com/mayor' },
  { platform: 'website', url: 'https://mayor.example/' },
  { platform: 'other', url: 'https://blog.example/', label: 'Blog' },
]); // replaces the whole list in one transaction

const links = await profile.getLinks(); // ordered by sortOrder

const profileLinks = await ProfileLinkCollection.create({ db });
await profileLinks.reorder(profile.id!, [links[2].id!, links[0].id!, links[1].id!]);
```

平台: `facebook`, (中文(简体) ), `instagram`, (中文(简体) ), `x`, (中文(简体) ), `linkedin`, (中文(简体) ), `youtube`, (中文(简体) ), `tiktok`, (中文(简体) ), `website`, (中文(简体) ), `other` (单位:千美元)`PROFILE_LINK_PLATFORMS`) (中文(简体) ). 地址必须是 `http://` 或者说 `https://` (单位:千美元)`normalizeProfileLinkUrl`) (中文(简体) ). 连结的子弹是它的ID,从来不是它的 地址或标签.

`Profile.isPublic` (默认) `false`)是公共图案旗:简介为: 公开公开(民选官员、公共机构)。 它只记录事实; 申请决定它显示什么.

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Profile` | 核心身份(瓶/组织/个人的科技创新基础) |
| `Bot` | 自动代理的STI子类 |
| `Organization` | 公司/集团的科技和创新子类 |
| `Person` | 个人科学、技术和创新子类 |
| `ProfileType` | 配置分类查询表 |
| `ProfileMetadata` | 每张元数据值 |
| `ProfileMetafield` | 具有校验计划的控制词汇 |
| `ProfileRelationship` | 两个剖面图之间的方向联系 |
| `ProfileRelationshipType` | 与对等旗帜的关系分类 |
| `ProfileRelationshipTerm` | 有时限的关系期 |
| `ProfileAsset` | 专用自有资产加入存储于 `profile_assets` 与 `relationship` 财务报告和审定财务报表 `sortOrder` |
| `ProfileLink` | 在配置文件上排序的网络链接( E)`profile_links`: 平台、 url、 可选标签、 排序命令; 带有配置的级联) |

### Auth 模型

| 导出 | 说明 |
| --- | --- |
| `OidcIdentity` | OIDC 提供者身份( 发行者+主题) |
| `NostrIdentity` | 带有 AES-256-GCM 加密的鼻孔键盘 |
| `ApiKey` | SHA-256 散列 API 密钥,范围及过期 |
| `MagicLinkToken` | 一次性无密码验证符 |
| `AuditLog` | 有源头追踪的行动/资源审计线索 |

### 收款

| 导出 | 说明 |
| --- | --- |
| `ProfileCollection` | CRUD 配置文件查询 |
| `ProfileAssetCollection` | 直接进入 `profile_assets` 行外加资产助手包装 |
| `ProfileTypeCollection` | 概况类型管理,包括房客安全 `getAvailableById(id, tenantId)` 租户或全球类型 |
| `ProfileLinkCollection` | `listForProfile`, (中文(简体) ), `replaceForProfile` (一次交易中命令替换), `reorder` |
| `ProfileMetadataCollection` | 元数据值操作 |
| `ProfileMetafieldCollection` | 梅塔菲尔德词汇管理 |
| `ProfileRelationshipCollection` | 关系查询 |
| `ProfileRelationshipTypeCollection` | 关系类型管理 |
| `ProfileRelationshipTermCollection` | 任期管理 |
| `ApiKeyCollection` | API 密钥查询和管理 |
| `AuditLogCollection` | 审计日志查询 |
| `MagicLinkTokenCollection` | 魔法链接符号操作 |
| `NostrIdentityCollection` | 鼻孔身份查询(包括NIP-05) |
| `OidcIdentityCollection` | OIDC 身份查询 |

`ProfileCollection.findUniqueGlobalPersonByEmail(email)` 被支持为 验证身份查询。 它横跨租户范围阅读并返回一个简介 只有当对大小写不敏感的邮件完全匹配时,该行才是一个 全球 `Person`; 租户范围、非租户和重复火柴投掷 `CanonicalPersonProfileError`。匹配用户只读,已索引 `Profile.emailKey`,随导出类型脚本 `normalizeIdentityEmail()` 帮助器,所以 Unicode 外壳和白空执行 每个数据库适配器都一样。 使用 `requireCanonicalGlobalPerson(profileId, email?)` 以验证 针对同一变量的应用程序选择的配置文件。 何时 `email` 实值 删除, 帮助者使用配置文件当前存储的特性验证 电子邮件. `reserveCanonicalIdentityEmail(profileId, email)` 额外索赔 私人地址 `oidc_profile_email_reservations` 页:1 奥米 `email` 以同步 从配置文件当前存储的电子邮件中保留; 更改地址移动 保留,并消除保留。 遗产简单 `Person` 科学、技术和创新歧视者仍然有效,由核心正常处理 升级路径.

`OidcIdentity.identityKey` 存储一个无效的、独特的发行者/主题的自然密钥 用于交易安全第一记录赛。 模型来源于发行商和 每个保存上的主题,所以调用者不能使其脱同步 。 新链接居中 它和遗留的一行回填 当再利用它。 发行商和主体不透明, 对大小写敏感的 OIDC 标识符: 周围的白空间被保存并且是 键的一部分; 修剪只用于拒绝全白空间要求。 这个 生成 REST, MCP, 和 CLI 表面只读, 因为身份突变 是一个认证权限更改; 信任的呼叫者通过 交易提供 API。 遗产 `OidcIdentity.findOrCreate()` 方法被贬值:它以交易方式重复使用 用于兼容性的精确安全发布器/主题链接,但拒绝创建 新建认证链接 。 使用 `createProfileFromOidc()` 或用户软件包 拥有者意识为创建提供API. 堕落者 `OidcIdentityCollection.linkToProfile()` 财务报告和审定财务报表 `Profile.linkOidcIdentity()` 帮助者指派到同样的完全重复使用路径, 并且不能植入或重置 链接. 现有设施必须停止或升级 配置文件编写、运行 `smrt db:status`, (中文(简体) ), `smrt db:migrate`,然后则 `smrt db:status` 部署前 此版本用于添加身份密钥和私人电子邮件保留表 。 礛 运行 `backfillProfileEmailKeys(db)` 一次从一个单一部署流程中 能够提供经核实的电子邮件。 交易安全回填是 同位素; canonical 电子邮件搜索和预订失败 `email_key_backfill_required` 标准时 `_smrt_backfills` 准备 标记缺失 。 精确的发行者/主体再利用不依赖于电子邮件密钥 准备,因为它不执行基于电子邮件的链接. 身份边界帮手使用备战后卫并索引了钥匙. 这个 普通用途 `ProfileCollection.findByEmail()` 保留其相容的遗产 寻找行为, 不适合身份链接 。 只有明确的 部署时间回填扫描配置表和记录准备状态; 守护 运行时身份查询使用索引键并验证返回的候选人. `createProfileFromOidc()` 需要一个交易能力数据库。 通过 根数据库,必须曝光 `beginTransaction`和s -m 交易; 通过一个 保存点。 执行 Cononical 电子邮件搜索或预定所需的路径 `_smrt_backfills` 以第一个存在。 提供从未尝试的跟踪器 DDL 对于这些路径,如果没有表格,则通过 root 数据库 这样 s- m-r- t 就可以在交易之外初始化它 。 准确 发行者/ 主体重用跳过电子邮件键准备标记搜索, 但 root 协调仍在初始化共享跟踪表。 呼叫者拥有的密钥 重复使用不参考跟踪器,因此不需要该表. 只露出一个手柄 `transaction()` 模棱两可,没有关闭。 对于 没有嵌入保存点支持的适配器,包括 DuckDB, pass 根数据库,而不是在外部交易中调用帮助者. 在无法找到安全路径时, 无法在持久写入之前提供 . 键入 [OIDC 提供决定矩阵](https://npmcn.com/package/%40happyvertical/smrt-profiles/src/testing/oidcProvisioningDecisionMatrix.ts) 是"逐个包装"的行为契约 它记录了精确的再利用, 新的身份和解决者结果、准备、重试、适配者支持、公开 错误和允许的行创建; 配置和用户套件执行 直接应用行。 特别是,仅配置文件的精确再利用保留了 已建立后继链接,因为它没有创建用户/会话认证状态, 时 `UserCollection.getOrCreateFromOidc()` 保持所有者意识并关闭故障. 使用用户API进行已核实的电子邮件再利用和应用调节. 内容 `authorizeProfileOwner` 选项是新选项中唯一支持的例外 发行人/主体针对预设的拥有者:用户包 解析验证 Cononical 配置文件, 唯一批准的所有者, 匹配用户 电子邮件,以及不可重现的身份。 没有明确适用 授权, 拥有的配置文件仍然返回 `profile_owned`。 。 。 .

`Profile` 财务报告和审定财务报表 `ProfileCollection` 都暴露出来 `getAssets()`, (中文(简体) ), `addAsset()`,以及 `removeAsset()` 辅助人员 `profile_assets`。典型的关系是: `avatar`, (中文(简体) ), `gallery`,以及 `attachment`。 。 。 .

### Auth 函数

| 导出 | 说明 |
| --- | --- |
| `resolveIdentity` | 从任何认证方法解析配置 |
| `createProfileFromOidc` | 创建 Profile + OIDC 身份或重用精确的发件人/ 主题链接; 已存在的邮件匹配失败关闭 |
| `normalizeIdentityEmail` | 身份密钥使用的适应器独立 Unicode/ whitespace 电子邮件卡通器 |
| `backfillProfileEmailKeys` | 用于迁移配置文件的常态化密钥 |
| `PROFILE_EMAIL_KEY_BACKFILL_NAME` | 由 Profile 电子邮件键回填记录的持久准备标记名称 |
| `createProfileFromNostr` | 在一个呼叫中创建配置文件 + 节点身份 |
| `createAuthEvent` | 创建节点认证事件 |
| `verifyAuthEvent` | 验证 Nostr 自动事件签名 |
| `createMagicLinkService` | 魔法链接认证服务工厂 |
| `createNip05Handler` | NIP-05地址处理器工厂 |

### 鼻孔密码

| 导出 | 说明 |
| --- | --- |
| `generateNostrKeypair` | 生成新的 Nostr 密钥派 |
| `encryptPrivkey` 编号 : `decryptPrivkey` | AES-256-GCM (法语) 密钥加密 |
| `deriveEncryptionKey` | 来自主密钥的衍生加密密钥 |
| `getPublicKey` | 从小金刚取出的小金刚 |
| `signEvent` 编号 : `computeEventId` | 节点事件签名 |
| `verifyNostrSignature` | 校验节点签名 |
| `pubkeyToNpub` 编号 : `npubToPubkey` | Bech32 公用钥匙转换 |
| `privkeyToNsec` 编号 : `nsecToPrivkey` | Bech32 组合键转换 |
| `isValidPubkey` 编号 : `isValidPrivkey` | 密钥验证 |
| `parseNip05Identifier` 编号 : `isValidNip05Identifier` | NIP-05 解析 |

### 密钥类型

`ProfileOptions`, (中文(简体) ), `ProfileTypeOptions`, (中文(简体) ), `ProfileLinkOptions`, (中文(简体) ), `ProfileLinkPlatform`, (中文(简体) ), `ProfileLinkInput`, (中文(简体) ), `ProfileMetadataOptions`, (中文(简体) ), `ProfileMetafieldOptions`, (中文(简体) ), `ProfileRelationshipOptions`, (中文(简体) ), `ProfileRelationshipTypeOptions`, (中文(简体) ), `ProfileRelationshipTermOptions`, (中文(简体) ), `OidcIdentityOptions`, (中文(简体) ), `CanonicalPersonProfileErrorCode`, (中文(简体) ), `NostrIdentityOptions`, (中文(简体) ), `ApiKeyOptions`, (中文(简体) ), `GenerateKeyResult`, (中文(简体) ), `MagicLinkTokenOptions`, (中文(简体) ), `GenerateTokenResult`, (中文(简体) ), `AuditLogOptions`, (中文(简体) ), `AuditSource`, (中文(简体) ), `AuthContext`, (中文(简体) ), `ResolveIdentityResult`, (中文(简体) ), `InitiateResult`, (中文(简体) ), `VerifyResult`, (中文(简体) ), `MagicLinkConfig`, (中文(简体) ), `MagicLinkService`, (中文(简体) ), `Nip05HandlerConfig`, (中文(简体) ), `Nip05HandlerResult`, (中文(简体) ), `Nip05Request`, (中文(简体) ), `Nip05Response`, (中文(简体) ), `NostrEvent`, (中文(简体) ), `NostrKeypair`, (中文(简体) ), `EncryptedKey`, (中文(简体) ), `ValidationSchema`, (中文(简体) ), `ValidatorFunction`, (中文(简体) ), `ReciprocalHandler`

## 依赖关系

-   `@happyvertical/smrt-core` - ORM基础课程
-   `@happyvertical/ai` -- AI 客户端 (SDK)
-   `@happyvertical/sql` - 数据库操作(SDK)
-   `@happyvertical/files` - 文件系统公用设施(SDK)
-   `@happyvertical/logger` - 结构化记录(SDK)
-   `@happyvertical/utils` -- -- 共享公用事业
-   `@noble/curves` -- 鼻孔密码
-   `bech32` -- Bech32 节点键编码
-   端点 : `@happyvertical/smrt-tenancy`

### 活动日志配方

`AuditLogRecipe` 声明 `profiles.audit-log`。在授权通过 `readAuditTrail`,将返回的记录传递给 `auditActivityEntries`,然后通过它的 作为 DTO `entries` 改为 `ActivityList` 从 `@happyvertical/smrt-svelte` 在行政壳内部. 包装器只将自己的行绑入 shell 列表, 当 替换或卸载。 查看者的授权更改时替换条目 . 演员标签和记录链接是可选的主机回调;投影从未 推断有效载荷之前/之后的准入权或暴露。 无效的日期被省略 .

活动功能卡可以独立于Message独立启用. 它的食谱 在不创建模式路由的情况下建议活动段; 授权 活性绑定仍然是唯一的UI数据源.

这个 `/activity` 表面决定公众 `@happyvertical/smrt-svelte#ActivityList` 包装在Adminshell内部. 规定 `audit-log` 提供者指经主机授权 `readAuditTrail` 接下来是 `auditActivityEntries`; 无法通用 审计日志路线. JSON种子提供虚构 `entries` 直接发送给 包装. `runtime: both` 反映浏览器渲染加只读服务器审计; 种子数据从未被插入审计数据库,也从未作为授权历史处理.

## 常见问题

### @happyvertical/smrt-profiles 是什么？

与SMRT框架的关系、元数据和对等协会的概况管理系统

### 如何安装 @happyvertical/smrt-profiles？

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

### @happyvertical/smrt-profiles 支持 TypeScript 吗？

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

### @happyvertical/smrt-profiles 支持 ESM 还是 CommonJS？

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

### @happyvertical/smrt-profiles 可以商用吗？

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

### @happyvertical/smrt-profiles 的下载量有多少？

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

### @happyvertical/smrt-profiles 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

