# @happyvertical/smrt-facts 中文文档

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

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

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

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

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

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

## 中文简介

分布式内存和知识管理,跟踪SMRT框架的出处

## 安装

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

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

## README

# @ happyvertical/ smrt- facts (欢快的垂直/扭曲)

具备语义分解,出处跟踪,S-m-r-t框架信心分数的知识库. 事实通过父母-子女连锁关系演变,与来源和主体相联,并经过3个区间调节,以防止重复.

## 安装

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

## 使用量

```typescript
import {
  Fact, FactCollection,
  FactSource, FactSourceCollection,
  FactSubject, FactSubjectCollection,
  FactContent, FactContentCollection,
  FactTag, FactTagCollection,
  calculateConfidence, normalizeText,
} from '@happyvertical/smrt-facts';

// Create a fact with provenance
const facts = await FactCollection.create({ db });
const fact = await facts.create({
  textRefined: 'The Eiffel Tower is 330 meters tall',
  type: 'measurement',
  domain: 'landmarks',
  status: 'active',
});

// Attach a source with credibility score
const sources = await FactSourceCollection.create({ db });
await sources.create({
  factId: fact.id,
  sourceUrl: 'https://example.com/eiffel-tower',
  sourceTitle: 'Tourism Board',
  credibility: 0.9,
});

// Recalculate confidence from all sources
await facts.recalculateConfidence(fact.id);

// 3-zone semantic reconciliation
// Exact normalized statements first reuse an active fact only within the same
// tenant, domain, and type. PostgreSQL callers are serialized on that key, so
// this identity guarantee also holds when embeddings fail or calls overlap.
// >= 0.85 similarity: auto-merge (same fact, update metadata)
// 0.60-0.85: optional typed decision, otherwise AI disambiguation
// Typed decisions merge only when their selected merge probability meets the
// conservative 0.75 operating threshold; uncertainty and provider errors branch.
// < 0.60: create new fact
const result = await facts.reconcile({
  rawInput: 'The Eiffel Tower stands 330m tall',
  type: 'measurement',
  domain: 'landmarks',
  source: { sourceUrl: 'https://another-source.com', credibility: 0.8 },
});
// result.action: 'created' | 'merged' | 'branched'

// Evolution chains: branch creates a successor fact linked via previousFactId
const successor = await facts.branch(fact.id, {
  textRefined: 'The Eiffel Tower is 330 meters tall including the antenna',
}, 'correction');
// 'correction' and 'contradiction' mark the predecessor as superseded

// Walk evolution: root -> current (via previousFactId)
const chain = await facts.getEvolutionChain(successor.id);
// Find highest-confidence leaf (via getSuccessors)
const latest = await facts.getLatestInChain(fact.id);
// Full tree (BFS with cycle detection)
const tree = await facts.getEvolutionTree(fact.id);

// Per-fact navigation: getPredecessor / getSuccessors / hasPredecessor
const previous = await successor.getPredecessor();
const successors = await fact.getSuccessors();
if (successor.hasPredecessor()) {
  // ...
}

// Entity briefing: all facts for a given entity
const briefing = await facts.getEntityBriefing('Place', placeId);
// { facts, totalCount, byType, byStatus }
```

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Fact` | 知识股 `textRefined`, (中文(简体) ), `type`, (中文(简体) ), `status`, (中文(简体) ), `confidence`, (中文(简体) ), `previousFactId` 用于进化链(前继指针;而不是结构等级边缘),以及自动生成的嵌入 |
| `FactSource` | 证明记录 `sourceUrl`, (中文(简体) ), `sourceType`, (中文(简体) ), `credibility` (0-1), (中文(简体) ), `extractedAt` |
| `FactSubject` | 多态实体链接( C)`entityType` + 键 `entityId`, (中文(简体) ), `conflictColumns: ['fact_id', 'entity_type', 'entity_id']` |
| `FactContent` | 把事实和内容联系起来的表格, `conflictColumns: ['fact_id', 'content_id', 'relationship']` |
| `FactTag` | 对事实的标签关联 |

### 收款

| 导出 | 说明 |
| --- | --- |
| `FactCollection` | 按状态/类型/领域查询, `reconcile()`, (中文(简体) ), `branch()`进化的转弯, `recalculateConfidence()`, (中文(简体) ), `getEntityBriefing()`, (中文(简体) ), `findWithGlobals(tenantId)` |
| `FactSourceCollection` | 源管理 `getForFact()` |
| `FactSubjectCollection` | 主题与 `getForFact()`, (中文(简体) ), `getForEntity()` |
| `FactContentCollection` | 事实与内容的关系 |
| `FactTagCollection` | 事实标签管理 |

### 职能

| 导出 | 说明 |
| --- | --- |
| `calculateConfidence` | 加权公式:基数为0.5 + 源量(最大为0.3) + 可信度(0.2) + 复用(0.1,10天后衰变) + 证实(0.1) 被夹入 \[0, 1\] |
| `normalizeText` | 三进制,倒塌的白空格,小写 -- -- 用于去除比较 |

### 密钥类型

`FactType` (确认/观察/衡量/定义/关系/活动/意见/预测), `FactStatus` (待处理/正在处理/争议/已处理/已处理/已处理/已处理), `EvolutionType` (原始内容/更正/精炼/缩写/扩展/出现), `SubjectRole`, (中文(简体) ), `ReconcileAction`, (中文(简体) ), `ReconcileOptions`, (中文(简体) ), `ReconcileResult`, (中文(简体) ), `FactContentRelationship`, (中文(简体) ), `EntityBriefing`

## 依赖关系

-   `@happyvertical/smrt-core` - ORM、代码生成和语义搜索
-   `@happyvertical/smrt-tenancy` - 可选多租户范围界定 `findWithGlobals()`
-   `@happyvertical/ai` - 大赦国际在和解方面的分歧

## 贡献者指南

见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-facts/AGENTS.md) 用于软件包结构、变化、验证、, 和贡献者的指导.

## 编目标记

`browseCatalog(query, { limit, offset, latestOnly, tenantId })` 默认为 25 除非 `latestOnly: false` 提供. 空清水清浏览和成功的语义搜索只将请求的水合物 SQL页面. 空缺候选人的资格仍受限制 `offset + 2 * limit`因此,解锁和解锁链可以返回a 简页。 语义学候选人检索仍受限制 `offset + limit`。 。 。 . 这些 SQL 窗口使用请求的页形值而不是收藏 `defaultListLimit`. 完整的租户可见的接班人可以连锁解析,甚至 当继任者位于候选窗口或状态过滤器外时。 隐含范围 信任关系保留了最新的接班人,与先前命令读取的匹配.

没有明确的租户,默认候选人身份是: `active`;带有 明确租户、租户和全球候选人除外 `superseded`。 。 。 . `includeSuperseded` 删除状态过滤器。 租户仍在继续 并拒绝要求另一房客。 科学、技术和创新儿童 藏书既限制候选人,也限制继任者歧视他们.

目录读取正常应用 `beforeList` 候选人的前提, 准备检查,以及完整的后继图表,包括空查询. 明确租户/全球阅读使用 `withTenantGlobalRead`,允许内置 租地列表钩 狭长的范围 而商业钩 保持原始用户, 权限、租户上下文和系统/非系统身份。 实际系统呼叫 保持系统呼叫。 截取器拒绝和应用程序 SQL 失败 致召师. 只无法嵌入配置或查询- 嵌入提供者失败 允许文本倒置;语义授权失败永远不会发生.

在无法查询嵌入时, 文本倒转匹配精确的 JavaScript 表达式 `` `${textRefined} ${textRaw}`.toLowerCase().includes(query.toLowerCase()) ``。 。 。 . 它继续使用 `catalogSearch` 存储和相同的SQL页面 traversal. 存储编码小写 UTF-16 单位为对齐的 ASCII 令牌, 保存 Unicode, 白空格, 字形通配符字符, 和代码单位边界 SQL 整理或大小写文件夹差异. 在文本前进行平面准备状态检查 搜索;如果任何允许的行未回填,则用回填指令来扔出. 数据库可以在内部扫描匹配行和演化边缘,但只扫描 事实页跨越数据库边界。 任意子字符串匹配 无法使用普通的 B- tree 索引;没有添加误导性搜索栏索引.

### 现有部署

这是一种明确的图案和数据迁移;普通读取从不创建图案. 停止旧的应用程序写入器, 部署新显示/ 代码, 然后运行 `smrt db:migrate` (和 `smrt db:status --parity`) (中文(简体) ). 添加无效 `catalog_search`历史 排为 NULL 。 在启用目录文本读取前, 随您运行以下 应用程序的数据库配置并重复到 `remaining` 为 0 :

```typescript
import { FactCollection } from '@happyvertical/smrt-facts';
import { withSystemContext } from '@happyvertical/smrt-tenancy';

const facts = await FactCollection.create({ db });
await withSystemContext(async () => {
  while ((await facts.backfillCatalogSearch(100)).remaining > 0) {
    // Each call is independently resumable; record progress in your job runner.
  }
});
```

回填需要明确的系统上下文,每个调用最多100行的过程 默认( 最大为 1000) , 只更新源文本仍然匹配的 NULL 值 读取快照。 它不会改变源文本,时间戳,嵌入或修改. 崩溃或同时写作可以安全重试;必须停止持续的老写作 这样手术就可以完成 a. 子类型收集只包含其歧视者; 使用基地集合进行全员部署。 在计划改变前退后; 通过重新运行迁移/回填而不是丢弃历史数据来滚动.

`Fact.save()`,收集创建/get-或插入/get-或upsert,并生成模型 更新维护源字段的搜索存储. `catalogSearch` (a) 产生; 调用者不得编写,生成的运输表面排除使用 只读/敏感字段元数据。 衍生使用 : 可变 `beforeSave` 钩子和完整的子类 `transformJSON` 链条, 保持持续文本和搜索存储的一致性。 如果自定义转换省略了源列,则返回字符串以外的值 或显式的 NULL,或用未发音的 UTF-16 代词返回字符串,则写入 保留其普通适配器语义(保留、默认或强制);搜索存储为 无效为 NULL 而不是从实例值中猜测 。 已读目录文本 然后因准备错误而失败,直到特权限制回填读 实际坚持的栏目。 在自定义写入后运行回填 恢复目录文本读取 。 只有形状良好的字符串和明确的 NULL 源 数值在持久性之前已知。 查询编码仍然准确的 UTF-16 编码单位匹配,包括包含未发售代位的查询. 普通/公开系列化 保留所保存的标记,而不是从转换前实例文本中重算. 直接 SQL 写入器必须设置 `catalog_search = NULL` 当任一源文本 更改,然后在文本读取恢复前返回填充. 如果习惯写作者或发行前的执行产生了已知的停滞 非 NULL 搜索值, 明确设置受影响的行 `catalog_search` 改为 NULL和运行相同的被限制回填. 故意后补选 NULL 标记;它不扫描或修复非NULL值。 这是定点修复, 不是一个新列迁移的附加步骤.

在回填后不要让旧的应用程序作者继续活动: 它们无法维护 这种新的无常。 未来 JavaScript 下加码/编码的更改需要 清晰的新回填; 格式不依赖地块 .

PostgreSQL和SQLite运行的克恩克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 DuckDB 查询 覆盖范围使用明确识别的 SQL 唯一固定: Cononical Fact schema 创建当前拒绝其演化的自我参照,在 [2830号](https://github.com/happyvertical/smrt/issues/2830)DuckDB水分问题 一个 `DESCRIBE` 每页加一个数据查询; PostgreSQL 和 SQLite 使用一个数据 如果有的话,在语义性候选人检索后进行查询。 文本倒置也执行一个 scalar 准备查询 .

编目 保存水分 `afterList` 在每个最后限定的页面上, 包括空页,取自生-query悬钩和相似性说明后. 一样 列表上下文和原始呼叫者身份在钩子之前/之后到达。 过滤或 编辑可能会缩短一页;浏览不会重新填充. 政策拒绝 传播并永不触发嵌入式无法获取的文本倒置 .

文本倒置由核心的提供者- 来源可用性结果选择 : 缺失嵌入配置或失败的查询嵌入使其得以实现。 错误 从授权、排名、SQL、水合物或结果的钩传播到没有改变, 甚至当一个召唤者抛出 `EmbeddingUnavailableError` 从那些行动.

目录文本读取准备状态保留数据库权限,即瞬间和未知 错误不变。 只收到确认的缺失表格/列驱动诊断 迁移/回填指令,保留原错误作为原因. `Fact` 声明 `catalog_search` 作为其允许的最终衍生列; 自定义 正常化必须维护这一宣言,不能取代框架 身份、租户、修订或冲突栏.

### 调节准入范围

`reconcile({ rawInput, tenantId, accessScope: 'public' })` 分区候选人 既包括租户,也包括精确、有应用定义的范围标志。 精确匹配和 语义排名在候选文本被水分或发送之前排除了其他范围 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}去散开 创造的事实和演变分支保留这一范围; `branch()` 反对明确的范围变化。 使用公开收集的上游 例如 `facts.list({ where: { tenantId, accessScope: 'public' } })` 范围 `get()` 重用结果时呼叫。 一般目录和演化 API 不 默示授权范围:申请必须授权访问和适用 其范围在提交证据或将条款事实联系起来之前即为上游.

托肯是大小写敏感、非空格字符串,最多256个字符没有 控制字符或未给付代位符。 他们是分区识别器, **未授权 全权证书**申请必须来自可信赖的授权国; 绝不接受任意的客户端选择的符号作为阅读范围的权限. 事实必须仅以其范围所代表的能见度来汇总来源. 源元数据不能确定候选人的能见度.

`accessScope` 由服务器管理:生成的 REST/ MCP 创建和更新输入 在允许普通可写字字段时将其剥去。 信任的服务器侧 `FactCollection.create()`, (中文(简体) ), `reconcile()` 财务报告和审定财务报表 `branch()` 保持持续访问. 所有者授权的迁移代码可以指定字段并调用 `save()` 在一个 有对齐写符的系统上下文已停止;没有生成 重分类端点被曝光 。 不要暴露操作程序或 转发未信任的请求机构来引导收藏撰写.

运行标准 `smrt db:migrate` 在部署使用此字段的作者之前. 无效 `Fact.accessScope` 栏中未对已存在的行进行分类. 选择 `accessScope` (或通过) `null`) 只搜索此遗产 NULL 分区; 明确范围绝不包括遗留行。 没有迁移猜测 来源元数据的能见度。 只能通过 停止所有者授权的数据与对账写入器的迁移,或将它们分开并重新摘录到 适当范围。 范围变化不是普通的调节行动.

PostgreSQL 调节保留其交易事实/源写和 每个身份的锁。 SQLite 保留其现有的部分写合同:失败 来源书写可能留下事实,重试发现相同的范围精确事实. 在全部写入成功之前不要记录应用程序提取收据 .

## 常见问题

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

分布式内存和知识管理,跟踪SMRT框架的出处

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

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

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

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

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

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

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

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

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

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

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

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

