# @empressaio/atom-contract 中文文档

规范地址：https://npmcn.com/package/%40empressaio/atom-contract/

版本：1\.44\.0
npm 元数据更新时间：2026-11-12T21:27:45.297Z
中文译文更新时间：2026-11-13T15:54:41.942Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40empressaio/atom-contract
原文对照：https://npmcn.com/package/%40empressaio/atom-contract/?lang=original
项目主页：https://github.com/empressaioemail-tech/hauska-atom-contract#readme
源码仓库：https://github.com/empressaioemail-tech/hauska-atom-contract

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

- 包体积（解压后）：1.9 MB，471 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.18\.0
- 运行依赖：2 个
- 首次发布：2026-07-07T13:03:15.682Z
- 最新版本发布：2026-11-12T21:27:45.045Z
- 近 30 天下载量：14973（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

输入的数据底座每个皇太后原子都满足:身份、上下文界面、组成声明和历史锚定。 对接Hauska SDK(`@hauska-sdk/*`;每个产品表面和MCP服务器直接消耗.

## 安装

```sh
npm install @empressaio/atom-contract
```

也可以使用：`pnpm add @empressaio/atom-contract`、`yarn add @empressaio/atom-contract`、`bun add @empressaio/atom-contract`

## README

# `@empressaio/atom-contract`

每个皇太后原子的输入数据基底必须满足:, 上下文界面、 成分声明和历史锁定. 对接Hauska SDK(`@hauska-sdk/*`);每个产品表面直接消耗 和 MCP 服务器.

这个软件包是 **仅限框架**它运送合同,运行时间 它执行它, 计划的历史层写到 测试脚手架消费者包 用来证明它们的原子符合要求. 目录原子登记(实际原子类型) - `engagement`, (中文(简体) ), `code-section`, (中文(简体) ), `jurisdiction-corpus`(a) 生活在消费品包中 这取决于这个.

皇后商业基底,对等到 `@hauska-sdk/*` 财务报告和审定财务报表 `hauska-engine`, (中文(简体) ), 每个 doc repo ADR-018(原子合同下层投放)。 这个 软件包为零 `@hauska-sdk/*` 依赖性: MCP 服务器或产品 表面可以依赖合同而不继承商业 堆栈.

## 安装

```bash
npm install @empressaio/atom-contract
# or
pnpm add @empressaio/atom-contract
```

要求18.18+和 `drizzle-orm` (^0.30.0),如果您打算使用 `PostgresEventAnchoringService`无法支撑历史的原子 使用情况 `createInMemoryEventService()` 从 `./testing` 子路径.

## 出版(经营者)

这个 `hauska-sdk` npm 账户用途 **已分阶段发布 + Windows Hello** (passkey 2FA),不是颗粒活字符号. 见 [`docs/npm-publish-automation.md`](https://npmcn.com/package/%40empressaio/atom-contract/docs/npm-publish-automation.md)。 。 。 .

```powershell
.\publish-1.4.0.ps1
.\publish-approve-1.4.0.ps1 -StageId <uuid-from-stage-list>
```

## 公众表面

```ts
import {
  createAtomRegistry,
  defaultScope,
  resolveMode,
  parseInlineReferences,
  serializeInlineReference,
  httpContextSummary,
  resolveComposition,
  PostgresEventAnchoringService,
  wrapForStorage,
  unwrapFromStorage,
  type AccessPolicy,
  type AtomRegistration,
  type AtomMode,
  type AtomReference,
  type ContextSummary,
  type Scope,
  type AtomComposition,
  type EventAnchoringService,
} from "@empressaio/atom-contract";
```

测试公用设施 在一个单独的子路径后面 所以生产捆绑 从来没有拉他们进来:

```ts
import {
  createTestRegistry,
  createInMemoryEventService,
  runAtomContractTests,
} from "@empressaio/atom-contract/testing";
```

## 四层的合约

具有一个结构型对象的原子登记册:

```ts
const taskAtom: AtomRegistration<"task", ["card", "compact", "expanded"]> = {
  // identity
  entityType: "task",
  domain: "sprint",

  // render-mode contract (type-level)
  supportedModes: ["card", "compact", "expanded"],
  defaultMode: "card",

  // context interface
  contextSummary: async (entityId, scope) => ({
    prose: `Task ${entityId}: ...`,
    typed: { id: entityId },
    keyMetrics: [{ label: "Status", value: "open" }],
    relatedAtoms: [],
    historyProvenance: { latestEventId: "evt-...", latestEventAt: "2026-..." },
    scopeFiltered: false,
  }),

  // composition declaration (multi-child; required field)
  composition: [
    { childEntityType: "blocker", childMode: "compact", dataKey: "blockers" },
  ],
};

const registry = createAtomRegistry();
registry.register(taskAtom);
```

汇编时间保证:

-   `defaultMode` 必须是 `supportedModes`。错配的默认值 无法输入检查.
-   `entityType` 是一个字面字符串, 一直缩小到 `registry.resolve("task")` 所以,消费者看到 确切的类型回.
-   `domain` 需要并且可以通过 `registry.listByDomain(...)`。 。 。 .
-   `composition` 需要时间。 过 `[]` 宣布没有孩子.

5个模式作为字面结合: `inline`, (中文(简体) ), `compact`, (中文(简体) ), `card`, (中文(简体) ), `expanded`, (中文(简体) ), `focus`. 装订(反应) `<AtomShell>`,每个模式 组件, 焦点存储接线) 在一个单独的软件包中存在 这取决于这个.

## 呼叫地点的范围

`contextSummary` 总是需要一秒钟 `Scope` 参数 :

```ts
interface Scope {
  audience: "ai" | "user" | "internal";
  requestor?: { kind: "user" | "agent"; id: string };
  asOf?: Date;
  permissions?: ReadonlyArray<string>;
}
```

不按范围区分的原子 忽略它并设定 `scopeFiltered: false`。测试使用 `defaultScope()` 帮手.

## 组成

组成是一个多子的宣示图. 登记册消耗 字段: `registry.validate()` 每个注册的构成 边缘并报告未登记的儿童实体类型的任何点. 使用 `resolveComposition(parent, parentRef, parentData, registry)` 改为 将声明变成一个已准备好可供渲染的打字儿童列表 迭相会.

**靴子时间合同 :** 应用程序拖带必须调用 `registry.validate()` 之后的一次 `register()` 呼叫已经运行 无法在结果为时启动 `{ ok: false }`。登记处确实 不重验证每个字的构成 `register()` (父母可以 在儿童面前合法登记)和 `resolve()` 没有 重查查,否则会互相引用 只在成分分辨率时表面.

组成边缘可通过设置选择退出存在验证 `forwardRef: true`。前向边缘被两者跳过 `validate()` 财务报告和审定财务报表 `resolveComposition` 在孩子没有注册的情况下 母原子可以发送一个声明,将一个孩子命名为 后来冲刺而未撞出靴子.

## 准入政策(可见级别)

原子可能声明为 CDR-017 访问级. 合同未履行 执行;下游地表(MCP) `list_*`,目录 APIs)大门打开 这个值.

```ts
type AccessPolicy =
  | "public-free"        // unauthenticated public catalog
  | "public-paid"        // catalog-visible, entitlement-gated at fetch
  | "platform-internal"  // platform staff only; never enumerated publicly
  | "tenant-private"     // owning tenant only
  | "tenant-shared";     // explicit cross-tenant share (ADR-017)
```

球场分两地出现:

-   `AtomRegistration.accessPolicy?` ——原子类型默认. 有用的时候 整个类型是内部的(例如审计原子).
-   `ContextSummary.accessPolicy?` ——每件价值. 让我们 多数是公用原子标记内部的个别实例——例如:, a 公众 `jurisdiction-corpus` 伙伴关系支出目录 辖区被标记 `"platform-internal"` 直至伙伴关系 关闭.

分辨率:每方 `ContextSummary.accessPolicy` 当获胜时 ,否则就回到登记簿上 `accessPolicy`, (中文(简体) ), 否则将原子视为 `"public-free"`。快速建设者 目录( e)`registry.describeForPrompt()`使登记正常化 值为 `"public-free"` 当未申报的下游过滤分支 没有无名卫士.

## 历史( A)`EventAnchoringService`(中文(简体) )

每个原子突变流经 `EventAnchoringService.appendEvent`, (中文(简体) ), 将一行写为 `atom_events` 页:1 运出 `PostgresEventAnchoringService` 写一个SHA-256链 散货. `prevHash` 链接每个事件到上一个事件 `(entityType, entityId)` 成对,产生一对实体散列链.

**界面-稳定/执行-演变.** 这个 `EventAnchoringService` 接口是合同。 决定性因素 SHA-256的执行将取而代之的是真正的加密 锁定(Merkle root + 外部分类账锁定)于后一里程碑 不改变消费者界面。 标记应当为 重审结转 `TODO(M2-C):` 标记.

主办项目拥有 `atom_events` 计划(表一栏, (见E/CN.4/Sub.2/2000/L.31)。 该图书馆根据商定的表格名称发布原始 SQL 只靠靠着 `drizzle-orm`是因为 `sql` 帮助SQL调温器.

## VDA 包装( 今天不开放)

`wrapForStorage(value)` 返回时 `{ envelope: { version: 1, vdaApplied: false }, payload: value }` 财务报告和审定财务报表 `unwrapFromStorage(stored)` 返回时 `stored.payload`消费者呼唤 这些从今天的写入路径; 不操作变成一个真正的信封 (版本链 + 墓碑语义) 在后面的里程碑上没有 消费变化.

## 内含引用语法

聊天层使用 `{{atom|type|id|label}}`数字 :

```ts
parseInlineReferences("see {{atom|task|t1|Pick HVAC}}");
// -> [
//   { kind: "text", text: "see " },
//   { kind: "atom", reference: { kind: "atom", entityType: "task", entityId: "t1", displayLabel: "Pick HVAC" }, raw: "{{atom|task|t1|Pick HVAC}}" }
// ]
```

分隔符是 `|`上一个形状 `:` 无法 代表Spec 51本身包含的实体ID `:` (例如:. `parcel-briefing:{parcelId}:{intentHash}`) (中文(简体) ). 旧的形状不再了 解析 : 没有双段兼容路径 .

## 保留原子类型(ADR-020/ADR-021)

私人记录的土地使用仪器船,作为Zod验证的有效载荷 页:1 `./encumbrances` 子路径(v1.2.0+). 类型是 **永远** `public-free`; 计划只接受 `tenant-private` 财务报告和审定财务报表 `tenant-shared`。 。 。 .

```ts
import {
  RECORDED_INSTRUMENT_SCHEMA,
  RESTRICTION_CLAUSE_SCHEMA,
  ENCUMBRANCE_RENDER_MODES,
  SAMPLE_RECORDED_INSTRUMENT,
} from "@empressaio/atom-contract/encumbrances";
```

## 石油和天然气原子类型(ADR-025)

O&G作为Zod验证有效载荷的可操作性、地上和地上原子船 页:1 `./og` 子路径 (v1. 7. 0). 覆盖资产脊椎(井,井, 完成、区、地、生产时间序列、设备状况、土地 (矿-租赁、rc-租赁、道、所有权-利息)和收入 分配单位。 主要义务(核心域中立型) 模块,不 `./og`。 。 。 .

```ts
import {
  WELL_SCHEMA,
  MINERAL_LEASE_SCHEMA,
  REVENUE_ALLOCATION_UNIT_SCHEMA,
  SAMPLE_WELL,
  OG_DEFAULT_ACCESS_POLICY,
} from "@empressaio/atom-contract/og";
```

## 属性推理原子类型(主 WDLL 3.2–3.6)

Parcel可构建的链式原子飞船 `./property` 子路径 (v1.9.0+): (中文(简体) ) `parcel-node`, (中文(简体) ), `zoning-fact`, (中文(简体) ), `setback-rule`, (中文(简体) ), `buildable-envelope`, (中文(简体) ), `parcel-terrain-model`, (中文(简体) ), `road-node`, (中文(简体) ), `building-footprint`, (中文(简体) ), `utility-easement`, (中文(简体) ), `plat-building-line` (1.44.0) (中文(简体) ). 均为数据一级(`atomTier: "data"`默认为 `public-free` 登记未申报时的准入政策.

**(一-E) 校准在READ(一-E)中的信心:** 可能带有 `ReasoningReadContract` 在写作时声称的快照,包括a 占位符 `calibratedConfidence` 与 `provenance: "asserted"`在读取, 校正轴通过校正上方解决——它不是 被冻结了 不添加一个 `labeling x district` 相乘场.

```ts
import {
  ZONING_FACT_SCHEMA,
  SETBACK_RULE_SCHEMA,
  BUILDABLE_ENVELOPE_SCHEMA,
  HAYS_ZONING_FACT_FIXTURE,
  BEXAR_NULL_ZONING_FACT_FIXTURE,
  HAYS_BUILDABLE_ENVELOPE_FIXTURE,
  type ZoningFactAtomInstance,
  type SetbackRuleAtomInstance,
  type BuildableEnvelopeAtomInstance,
} from "@empressaio/atom-contract/property";
```

| `entityType` | `reasoningKind` | 关键字段 |
| --- | --- | --- |
| `parcel-node` | `observed` | `keyKind`, (中文(简体) ), `geometryStoreRef` 指针(绝不是指环) OR `absence`编号 :`verifiedAbsence` |
| `zoning-fact` | `observed` | `district` 或 `absence.no-zoning-stamp` |
| `setback-rule` | `observed` | `front`编号 :`side`编号 :`rear`键入 `sourceCodeAtomRef`, (中文(简体) ), `matchBasis` |
| `buildable-envelope` | `derived` | `buildable-envelope-inset-v1`,输入参考事实+规则+几何 |
| `parcel-terrain-model` | `derived` | `parcel-terrain-mesh-ifc-v1`,格式化的文物 |
| `road-node` | `observed` | `{fips}:road:{osm_way_id}`中线+假定ROW |
| `building-footprint` | `observed` | `footprintGeometry` 或 `absence`编号 :`verifiedAbsence`· ; `sourceTier` |
| `utility-easement` | `observed` | `easementGeometry`, (中文(简体) ), `easementClass`, (中文(简体) ), `public-free` 总是; 可选 `easementKind`, (中文(简体) ), `placement`, (中文(简体) ), `platRef` (1.44.0) (中文(简体) ) |
| `plat-building-line` | `observed` | `lineGeometry`编号 :`offsetDistanceFt`, (中文(简体) ), `appliesTo`, (中文(简体) ), `platRef`, (中文(简体) ), `placement` 或 `absence` (1.44.0) (中文(简体) ) |

`parcel-node` 铁路一号锁定其他所有地产铁路钥匙 它记录 包裹身份和戒指PROVENCE;戒指本身留在 `txgio_parcel`,则 1 个几何真相框架(地理学法则1). `geometryStoreRef` 严格 指针,所以一个内线环无法解析.

ICC 代码引用版税通过核心生成 `ObligationAtomInstance` 行——无独立 `SourceAttribution` 类型.

### 附加制成模式

| `entityType` | 目的 | 建议的渲染模式 |
| --- | --- | --- |
| `recorded-instrument` | 父器; 通过湿 PDF `sourceDocumentCid` | `card`, (中文(简体) ), `compact`, (中文(简体) ), `expanded` |
| `restriction-clause` | 可执行片段;计划审查引用目标 | `inline` . `focus` (单位:千美元)**默认 `focus`**(中文(简体) ) |
| `restriction-corpus` | CC & R 分类包 | `card`, (中文(简体) ), `expanded` |
| `administrative-rule` | 未记录的人道主义援助准则`legalWeight: advisory`(中文(简体) ) | `inline`, (中文(简体) ), `compact`, (中文(简体) ), `card`, (中文(简体) ), `expanded` |
| `constraint-resolution` | 有效制约(ADR-021) | `card`, (中文(简体) ), `expanded` |

发动机 `AtomRegistration` 公升和摄入量生产者属于 `hauska-engine/packages/atoms/` (cc-agent-E); Cortex 第1阶段可 在引擎注册着陆前验证这些计划上的上传.

## 显示词汇表(OPS-23 R-6/P-167)

人肉化显示绳索 要求飞船 `./display` 子路径(v1.32.0+),因此属性探索器面板,可行性PDF, 和 Smart Site MCP 连接器为同一个原子制作相同的单词 从一个地方 而不是手印副本。 两个模块:

-   `buildable`数字 : `mapBuildableDisplay` 及其类型——可建/可置换 卡片、PDF和跨地表协议式词汇。 逐字记录 从五个字节同 `buildable-display-vocab.ts` 副本 曾经生活在hauska-map和hauska-engine, 被平等锁在一起 固定装置.
-   `wire`数字 : `VOCABULARY`, (中文(简体) ), `WIRE_DISPOSITION_DISPLAY_TEXT`, (中文(简体) ), `DERIVED_FIGURES_POLICY` – Smart Site MCP 线脚词汇 页:1 从遗留设计工具逐字移动 `artifacts/smartsite-mcp/src/vocabulary.ts` (P-91 v3表),随同 从 MCP 服务器导入的九个显示常数 拥有 `mcp-app.ts`,因此这个模块对MCP服务器没有依赖性.

```ts
import {
  mapBuildableDisplay,
  type BuildableDisplayInput,
  VOCABULARY,
  WIRE_DISPOSITION_DISPLAY_TEXT,
} from "@empressaio/atom-contract/display";
```

截止到1.32.0,还没有消费者进口这一次路径和以前的副本 仍然存在; 退出(删除副本、 等值锁和 跳过供应商驱动测试)是同一计划行的后一步骤,上门 `P-153` 在hauska-map和遗产设计工具中合并.

## 读取合同类型(Calibrated Spine F4 / F6 / K6)

宽, 三轴信心在读取时返回. 毫无障碍, 未来源的置信是无法表达的: 估计是一个品牌 名义类型只能通过 `createWidthedConfidence`。 。 。 . 在此软件包中不存储衍生数字 .

```ts
import {
  createReadContract,
  createWidthedConfidence,
  READ_CONTRACT_SCHEMA,
  SAMPLE_READ_CONTRACT,
  type ReadContract,
  type CalibrationProvenance,
} from "@empressaio/atom-contract/read-contract";
```

| 导出 | 作用 |
| --- | --- |
| `WidthedConfidence` | 不可分离估计数 + `n` + 键 `intervalWidth` + 来源 |
| `ThreeAxisConfidence` | 准确性、源质量和后果轴 |
| `ReadContract` | 完全的收看对象 每一个表面必须发射 |
| `ModelAttributionStamp` | 定金印章(型号,即时,原子集id) |
| `CalibrationProvenance` | `asserted` | `backtest` | `seed` | `live` |

传播到MCP,皮层-api, Cortex,扩展和地图是一种 消费者- 侧波2 相撞后 `^1.4.0`。 。 。 .

## 测试公用事业

消费者包 进口合同测试套件以证明 注册在一个函数调用中是很好的:

```ts
import { describe } from "vitest";
import { runAtomContractTests } from "@empressaio/atom-contract/testing";
import { taskAtom } from "./task.reg";

describe("task atom contract", () => {
  runAtomContractTests(taskAtom, {
    withFixture: { entityId: "t1", setUp: seedTestData },
    alsoRegister: [/* any composition children */],
  });
});
```

套房声称:

1.  身份存在 `entityType` 非空无一物,
2.  `defaultMode` 进入 `supportedModes`, (中文(简体) ),
3.  `contextSummary` 返回有效的四层形状 `historyProvenance` 财务报告和审定财务报表 `scopeFiltered`, (中文(简体) ),
4.  每一个成分边缘都与 `alsoRegister + this`, (中文(简体) ),
5.  内含此原子的来回引用.

`createInMemoryEventService()` 提供内存 `EventAnchoringService` 用于不需要邮购的单位测试; `createTestRegistry(initial)` 是一个方便结束 `createAtomRegistry()`。 。 。 .

## 这个包裹不运送什么

-   **目录原子注册.** 没有 `engagement.atom.ts`, (中文(简体) ), `code-section.atom.ts`等. Catalog 原子生活在消费品包中 (单位:千美元)`hauska-engine/packages/atoms/`,产品 api 服务器等) 取决于这个。 行: 此软件包拥有注册 _机制_ 和合同; 消费者拥有每个原子 _实例_。 。 。 .
-   **反应渲染层.** 只有类型级的渲染模式合同。 这个 `<AtomRenderer>`, (中文(简体) ), `<AtomShell>`每模式组件,焦点存储 接通了,右侧的状态机器 所有船在后来的兄弟 软件包.
-   **加密锁定 `atom_events`。 。 。 .** `chainHash` 实值 今天确定性SHA-256; Merkle root + 外部锚地 后来的里程碑.
-   **真正的VDA后卫.** `wrapForStorage` 编号 : `unwrapFromStorage` 为: 无操作; 真正的信封、 版本链和墓碑语义 在后来的里程碑中着陆.

## 线性

此软件包提取工作空间- 私人 `@workspace/empressa-atom` 住在这里的人 `legacy-design-tools/lib/empressa-atom/`B. 框架 已逐字保存;只有软件包名称和 `@workspace/db` 测试时间依赖性改变.

## 许可证

见利能斯.

## 常见问题

### @empressaio/atom-contract 是什么？

输入的数据底座每个皇太后原子都满足:身份、上下文界面、组成声明和历史锚定。 对接Hauska SDK\(@hauska-sdk/\*;每个产品表面和MCP服务器直接消耗\.

### 如何安装 @empressaio/atom-contract？

在项目目录运行 npm install @empressaio/atom-contract，或使用 pnpm add / yarn add / bun add。

### @empressaio/atom-contract 支持 TypeScript 吗？

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

### @empressaio/atom-contract 支持 ESM 还是 CommonJS？

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

### @empressaio/atom-contract 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @empressaio/atom-contract 可以商用吗？

@empressaio/atom-contract 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @empressaio/atom-contract 的下载量有多少？

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

### @empressaio/atom-contract 还在维护吗？

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