# @hadron-memory/urn-lib-js 中文文档

规范地址：https://npmcn.com/package/%40hadron-memory/urn-lib-js/

版本：0\.0\.22
npm 元数据更新时间：2026-11-14T06:59:30.066Z
中文译文更新时间：2026-11-17T05:56:35.327Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：264 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-16T00:06:53.042Z
- 最新版本发布：2026-11-14T06:59:29.876Z
- 近 30 天下载量：11858（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

硬URN作曲/平面/规范化——固定-公司驱动,与骨灰管-lib-go的跨语言等同

## 安装

```sh
npm install @hadron-memory/urn-lib-js
```

也可以使用：`pnpm add @hadron-memory/urn-lib-js`、`yarn add @hadron-memory/urn-lib-js`、`bun add @hadron-memory/urn-lib-js`

## README

# @hadron-memory/urn-lib-js (英语)

Hadron URN为JavaScript & TypeScript作曲 / 剖析 / 正常化.

发自内心 [`urn-lib-go`](https://github.com/hadron-memory/urn-lib-go)两者 执行 **同样的符合性** (单位:千美元)`fixtures/corpus.json`(b) —— 所以两种语言不能漂移 存在到 替换已经漂移过 : hadron-server / portal / docs / cli (hadron-server #239, #693) (英语).

## 状态

**增一相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.** 此放出纯自存的端口 切片为 `hadron-server/src/lib/urn.ts` 拼写地,在共同的书目背后:

-   **计划** —— 说 `CANONICAL_SCHEME`, (中文(简体) ), `LEGACY_SCHEME`, (中文(简体) ), `hasSchemePrefix`, (中文(简体) ), `normalizeScheme`
-   **登记** ——锁定类型登记簿(`URN_TYPES`, (中文(简体) ), `ROLE_MARKERS`, (中文(简体) ), `RESERVED_SLUGS`, (...) (中文(简体) )
-   **常态** —— 说 `normalizeUrnForLookup`, (中文(简体) ), `legacyMemoryUrnToCanonical`, (中文(简体) ), `agentSlugFromUrn`
-   **弹片** —— 说 `validateAtomShape`, (中文(简体) ), `validateUserSlug`, (中文(简体) ), `validateOrgSlug` (需要点取出根,为"692", `validateUserHandle` (dot-free, 第692页), `deriveSlugFromName`
-   **遗产** —— 说 `parseUrnInput`, (中文(简体) ), `formatUrn`, (中文(简体) ), `validateUrnType` (021前表面)
-   **解析器** —— 说 `parseUrn` (Cononical-form parser, D11猫 1+4),, (中文(简体) ), `isParserCanonical`, (中文(简体) ), `toParserCanonical`
-   **编曲** —— 说 `formatCanonicalUrn`, (中文(简体) ), `composeNodeUrn`, (中文(简体) ), `composeEdgeUrn`
-   **显示** —— 说 `parseDisplayUrn`, (中文(简体) ), `DISPLAY_URN_TYPES` (容忍的 spec-010 芯片解析器/注册器——与严格的克诺克解析器分开;倒回 `unknown` 未注册显示类型)
-   **错误** —— 说 `UrnParseError` + 机器稳定 `UrnParseErrorReason` 工会

**Grammar-v2 平面形式** (hardon-server#694) 移植: `parseUrnV2` 编号 : `composeUrnV2` 编号 : `isFlatV2` 结束 `hrn:<type>:<root>[:<segment>...]` (单一) 结肠,无锡吉尔,为v1表面添加剂.

**实体 v2 形状** (原服务器#696,决定D-2026-07-15-006) 也移植过 :

-   **隐藏** ——两个形状,而分量决定: `hrn:secret:<root>:<name>` (org/user root + 完全一个名字原子)和 App 密语 `hrn:secret:<root>:app:<app-slug>:<name>` (字面小写 `app` 标记, 然后是App的sult和这个秘密的名字; vers-lib-js#40. `hrn:secret:<root>:app` 仍然是平地的秘密命名 `app`两个部分、四个或四个以上部分以及任何其他部分 标记 (`APP`, (中文(简体) ), `memory`, (中文(简体) ), `org`, (中文(简体) ), `agent`, (中文(简体) ), `user`) 被拒绝, App 形状 从不坐落在保留根下(`server`, (中文(简体) ), `platform`) (中文(简体) ). 679号 `::` 拼写 `<root>::<app|memory>:<slug>::<name>` 被拒绝 `parseUrn`从来没有正常化. 以 `composeAppSecretUrnV2`· ; `parseSecretUrnV2` 就说是谁的 (单位:千美元)`{ownerKind: 'root', root, name}` 或者说 `{ownerKind: 'app', root, appSlug, name}`, (中文(简体) ), 所以消费者永远也不要重新思考 均等规则.
-   **应用程序** —— 说 `hrn:apprun:<root>:<app>:<run-id>` (固定不变).
-   **节点** —— 说 `hrn:noderev:<root>:<mem>:<loc...>:<rev>`, (中文(简体) ), **最终焦虑** (最近一次发言) 原子是修订版 id; 分解为 `parseNodeRevUrnV2`。 。 。 .
-   **节点/边缘** —— 说 `hrn:<type>:<root>:<mem>:<loc...>` (一个内存+至少一个) loc 原子; loc 是一个 **不透明终端** (边接器从不重拆) 输入 `source:target`) (中文(简体) ).
-   **`#data` 碎片** —— 说 `<node-or-apprun-urn>#data` (节点数据是 其父母,而不是独立类型. `composeDataFragmentV2` 总是发出一个 犬类 `hrn:` URN,甚至从一个遗产 `urn:`\- 骗人的家长.

`#696` 降级了 v1 节点 -**编** 类型字(`data`, (中文(简体) ), `condition`改为: 碎片 这改变了拼法,而不是意义 `parseUrn` 地图a 零碎平方v2 URN 在碎片的v1类型词上: `hrn:node:<root>:<mem>:<loc>#data` 解析为 `type: 'data'` 在父母身边 路径, 这恰恰是 v1 `hrn:data:<root>::<mem>::<loc>` 读取 同样的资源. `parserCanonical` 保留 v2 形式( 包含碎片), 因此 圆通相通. 一个V2上的碎片**仅限** 父关系( e)`apprun`, (中文(简体) ), `worker`)没有v1 类型等同并保持其 `unknown-type` 出错; 达到 `parseUrnV2` 何时 您需要父类型和片段作为单独的字段.

已键入的帮助 : `composeSecretUrnV2`, (中文(简体) ), `composeAppSecretUrnV2`, (中文(简体) ), `parseSecretUrnV2`, (中文(简体) ), `composeAppRunUrnV2`, (中文(简体) ), `composeNodeRevUrnV2`, (中文(简体) ), `composeDataFragmentV2`,以及 `parseNodeRevUrnV2`。 。 。 .

尚未移植(后来的增量,由同一实体提供):遗留链-平面 **正常化** + 存储的别名地图( hadron- server # 697) 和统一 校长**组合** 执行(哈德伦服务器#692).

## 获取 Loc: 使用分解器而不是 `pathSegments`

`ParsedUrn.pathSegments` 是一个 **原始分块,其形状跟随输入 语法** (# 12) v1 输入被分割 `::`,因此一个部分可能带有内部 `:`; 平面- v2 输入在单上分割 `:`,所以每个原子都是自己的元素. 因此,一种资源的两种拼写不同:

```ts
parseUrn('hrn:node:acme.com::specs::cor:urn').pathSegments  // ['acme.com', 'specs', 'cor:urn']
parseUrn('hrn:node:acme.com:specs:cor:urn').pathSegments    // ['acme.com', 'specs', 'cor', 'urn']
```

这影响到每个类型,其v1形式允许内部 `:` 在一段内 `memory` (价值角色标记如: `app-user:<id>`, (中文(简体) ), `node`,以及 `edge`。 。 。 . `org`, (中文(简体) ), `user`, (中文(简体) ), `agent`, (中文(简体) ), `app`, (中文(简体) ), `secret` 财务报告和审定财务报表 `asset` 在两种语法下都是相同的.

`splitNodeUrn` 编号 : `splitEdgeUrn` 实现语法正常化并报告a `#data` 因此,一个打来电话的人 从来不需要知道它是什么语法:

```ts
splitNodeUrn('hrn:node:acme.com::specs::cor:urn');       // { memoryUrn: 'acme.com:specs', loc: 'cor:urn' }
splitNodeUrn('hrn:node:acme.com:specs:cor:urn');         // { memoryUrn: 'acme.com:specs', loc: 'cor:urn' }
splitNodeUrn('hrn:node:acme.com:specs:cor:urn#data');    // { …, loc: 'cor:urn', fragment: 'data' }
```

边缘是 **不透明终端** —— 说 `splitEdgeUrn` 永不重分割为 `source:target`启用 `parseUrnV2` 如果您想要 v2 根 / 片段 / 块作为单独的字段.

当碎片是 **仅限** 核电站有问题, `parseUrn` 这么说的 页:1 `fragment-unsupported` 而不是泄露v1 解析者的申诉 关于 `#` 字符 :

```ts
parseUrn('hrn:node:acme.com:mem:loc#bogus');  // UrnParseError, reason 'fragment-unsupported'
parseUrn('hrn:worker:acme.com:eng:iris#data'); // 'unknown-type' — worker has no v1 form either way
```

测试是去除碎片是否会使输入解析. 如果是 本来的原因已经存在了 所以把错误的名字都修好 前进.

两个都回来 `NodeLikeUrnParts` (节点和边缘共用一个形状). 在v1之下 记忆可能 **多个部分**终端 `::` 段为 loc :

```ts
splitNodeUrn('hrn:node:mm.org::coding-app::coding-agent::app-mem::a:b');
// { memoryUrn: 'mm.org:coding-app:coding-agent:app-mem', loc: 'a:b' }
```

两者都是 **自验证**他们拒绝一个未注册的片段词和一个 边缘上的片段(只有 `node`编号 :`apprun` 因此,他们永远不会 比较宽容 `parseUrn` 对于相同的输入.

**已知缺口 :** 没有 `splitMemoryUrn` 然而,v2叶 `mem` 平等性 不受约束,所以 `hrn:mem:<root>:<a>:<b>:<c>` 不能拆分为容器 vs 叶子直到 v2 spec spins it (hadron-server #698).

## 使用量

```ts
import { normalizeUrnForLookup, validateOrgSlug, UrnParseError } from '@hadron-memory/urn-lib-js';

normalizeUrnForLookup('acme.com::specs::cor:urn'); // 'acme.com:specs:cor:urn'

try {
  validateOrgSlug('Acme.com');
} catch (e) {
  if (e instanceof UrnParseError) console.log(e.reason); // 'slug-not-lowercase'
}
```

## 符合性

`fixtures/corpus.json` 是行为真相的来源 每个案件都是 `{ fn, in: [args], out?, throws? }` —— 说 `out` 是预期的回报, `throws` 实值 预想数 `UrnParseError.reason`,既不意味着 `void` 一定要打电话 别扔了. `test/corpus.test.ts` \* 审理与执行有关的每一个案件; `urn-lib-go` 运行相同的文件. **增加行为 通过增加一个案件, 而不是通过编辑一种语言的测试.**

**npm是记录的软件包管理器.** `package-lock.json` 是唯一一个 树上的锁文件——不要再加第二个.

```bash
npm install
npm test          # runs the corpus
npm run build
```

## 出票人和代理任务(语法 v2)

`hrn:ticker:<root>:<app-slug>:<ticker-slug>` 财务报告和审定财务报表 `hrn:agenttask:<root>:<app-slug>:<task-id>` 每一部分在后面有两段 root根. 使用 `composeTickerUrnV2` 与滴答的永久衍生出弹片和 `composeAgentTaskUrnV2` 与任务的身份。 两个都通过 `parseUrnV2`, (中文(简体) ), 让他们自己的展出徽章, 并正常化的遗产 `urn:` 前缀为 `hrn:`。 。 。 . 它们没有v1等同物; `parseUrn` 拒绝他们 `unknown-type`。 。 。 .

任务标识遵循共享的URN原子规则(字母/数字、点、下划线和 连字符,最多64个字符). 32-hex 或 cuid ID 在任务编号中有效 叶;根名注册限制不适用于该叶.

## App事件(语法 v2)

`hrn:appevent:<root>:<app-slug>:<event-id>` 在 App 活动中的一次事件地址 (cor:urn:010:01). 它在根后有两段 `hrn:agenttask`启用 `composeAppEventUrnV2` 与事件的身份。 它解释 结束 `parseUrnV2`,使自己的显示徽章, 正常化的遗产 `urn:` 前缀为 `hrn:`,拒绝 `#data` 碎片。 仅限v2: `parseUrn` 拒绝它 `unknown-type`。事件id是一个URN原子(字母/数字, 点,下划线和连字符,最多为64个字符.

## 赠款(语法v2)

`hrn:grant:<root>:<app-slug>:<grant-id>` 在一个 App 中处理一个赠款 (cor:urn:010:01,格兰特行;裁定0255项9). 它有两个部分 根后,喜欢 `hrn:appevent`,以App弹片作为容器和 格兰特的ID作为叶子。 使用 `composeGrantUrnV2` 与补助金的ID。 它解释 结束 `parseUrnV2`,使自己的显示徽章, 正常化的遗产 `urn:` 前缀为 `hrn:`,拒绝 `#data` 碎片。 补助金是普通的 URN 原子(字母/数字、点、下划线和连字符,最多64个) 字符);没有只使用UUID的规则。 没有定义其他的分量,所以 这里没有全奥尔格的补助金 现在 `parseUrn` (v1) 拒绝 `hrn:grant` 与 `unknown-type`;这是当前的行为,而不是裁定的拒绝(赠款) 绿地 v2 仍以 Cor:rn:010:01提出.

## 根登记政策

`validateOrgSlug` 承认组织名称被点缀和取消。 都一样 `validateUserHandle` 拒绝32-hex/cuid-形状的根(`root-id-shaped`)和 保留根词 `hrn`编号 :`urn` (单位:千美元)`reserved-word-slug`) (中文(简体) ). 新手柄还剩 点无所取. 小写、字符集和长度检查仍然有效.

这是创建/重命名政策 。 普通弹壳验证、URN解析和 成分仍然宽大,所以现有存储的URN和ID形任务叶 还来回转接 过时的 `org-root-not-dotted` 理由是退休.

## 动作( 语法 v2)

`hrn:action:<root>:<agent-slug>:<code>` 根后有两段: 团队特工的弹出和动作密码(cor:urn:010:01). 使用 `composeActionUrnV2`。它通过 `parseUrnV2`,使其自己的显示 徽章,使遗产正常化 `urn:` 前缀为 `hrn:`它没有v1 等值; `parseUrn` 拒绝它 `unknown-type`两个部分都遵循 共享的URN原子规则(字母/数字、点、下划线和连字符,最多64个) 字符).

## AI 服务配置( 语法 v2)

`hrn:aiconf:<owner-root>:<owner-kind>[:<owner-slug>]:<name>`: 所有者类型 (准确,小写第一段)决定形状(cor:urn:010:01). `org` 带 `org:<name>` (单位:千美元)`hrn:aiconf:acme.com:org:default`(三); `app` 财务报告和审定财务报表 `agent` 带 `<kind>:<owner-slug>:<name>` (单位:千美元)`hrn:aiconf:acme.com:app:mealplan:default`) (中文(简体) ). 任意 拒绝其他类型作为 `invalid-segment-shape`, (中文(简体) ), `server` 包括:a 哈德伦Server所有者没有URN形式,所以"lib"为它建造了一无所有. 在 保留根 `server` 财务报告和审定财务报表 `platform` 配置完全是一个部分 名称( e)`hrn:aiconf:server:default`),没有物主型相随而来. 一个名字是一个原子 在正常情况下,一个结束于 `-` 或者说 `_` 被拒绝。 以 `composeUrnV2('aiconf', root, ...parts)`。仅检查 lib 形状: 类型匹配配置的真正所有者是分辨率( hadron- server# 3857) .

## 许可证

麻省理工学院巴拉贡股份有限公司.

## 常见问题

### @hadron-memory/urn-lib-js 是什么？

硬URN作曲/平面/规范化——固定-公司驱动,与骨灰管-lib-go的跨语言等同

### 如何安装 @hadron-memory/urn-lib-js？

在项目目录运行 npm install @hadron-memory/urn-lib-js，或使用 pnpm add / yarn add / bun add。

### @hadron-memory/urn-lib-js 支持 TypeScript 吗？

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

### @hadron-memory/urn-lib-js 支持 ESM 还是 CommonJS？

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

### @hadron-memory/urn-lib-js 可以商用吗？

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

### @hadron-memory/urn-lib-js 的下载量有多少？

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

### @hadron-memory/urn-lib-js 还在维护吗？

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

