# @adrkit/core 中文文档

规范地址：https://npmcn.com/package/%40adrkit/core/

版本：0\.20\.0
npm 元数据更新时间：2026-10-11T00:41:13.371Z
中文译文更新时间：2026-11-05T22:48:56.798Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adrkit/core
原文对照：https://npmcn.com/package/%40adrkit/core/?lang=original
项目主页：https://adrkit.dev/
源码仓库：https://github.com/mbeacom/adrkit

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

- 包体积（解压后）：536 kB，110 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- 首次发布：2026-07-20T03:50:48.534Z
- 最新版本发布：2026-10-11T00:41:12.948Z
- 近 30 天下载量：10839（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

纯 ADR 解析,验证,迁移,并影响解析为adrkit.

## 安装

```sh
npm install @adrkit/core
```

也可以使用：`pnpm add @adrkit/core`、`yarn add @adrkit/core`、`bun add @adrkit/core`

## README

# @ adrkit/ 核心

纯正、决定性的建筑构件 裁决记录: 分析、计划验证、程序变化、MADR迁移、, 图表构造、队列投影和 `affects` 决议.

```sh
npm install @adrkit/core      # or: bun add @adrkit/core
```

```ts
import { lintCorpus } from '@adrkit/core';

const findings = lintCorpus(records);
```

## 建立和制作决定图

图形构造、过滤和序列化是纯正和决定性的. CLI拥有TTY检测;核心调用器总是选择混凝土渲染器.

```ts
import {
  buildAdrGraph,
  filterAdrGraph,
  renderDotGraph,
  renderJsonGraph,
  renderMermaidGraph,
} from '@adrkit/core';

const graph = buildAdrGraph(records);
const supersession = filterAdrGraph(graph, {
  focus: '0014',
  kinds: ['supersedes'],
});

const dot = renderDotGraph(supersession);
const mermaid = renderMermaidGraph(supersession);
const json = renderJsonGraph(supersession);
```

`filterAdrGraph` 保持焦点记录、匹配事件边缘及其 结束点。 仅对等的过滤器会丢弃无关的孤立节点 。 JSON信封 遗 物 `{ nodes, edges }`; DOT 和 美人鱼 添加演示文稿而无需更改 图表模型.

## 双向决定的解决

`resolveAffects` 是外出边缘:一个记录声明模式,路径是 与他们相匹配. `resolveSourceMarkers` 是输入边: 源文件 宣布决定与 `@adr <id>` 在注释中标记.

```ts
import {
  mergeSourceDeclarations,
  readSourceMarkers,
  readSourceMarkersBatch,
  resolveAffects,
  resolveSourceMarkers,
  scanSourceMarkers,
  toGoverningDecisions,
} from '@adrkit/core';

const scan = await readSourceMarkers('src/services/sync/retry.ts');
const byMarker = resolveSourceMarkers({ records, markers: scan.markers });
const byPattern = resolveAffects({ records, changedFiles: ['src/services/sync/retry.ts'] });

const governedBy = mergeSourceDeclarations(
  toGoverningDecisions(records, byPattern.matches),
  records,
  byMarker.matches,
);
```

`firedMatchers` 记录ADR匹配的内容. `declaredBy` 记录文件内容 已声明。 保持它们分开,让消费者区分"这个记录匹配 从"这个文件选择了记录。"

## 标记扫描合同

`scanSourceMarkers(source, path)` 是纯半个: 文字输入, 标记出, 不 文件系统。 它只扫描第一个 `MARKER_HEADER_WINDOW_BYTES` (单位:千美元)**8192 (韩语)**(单位:千美元) 源头,请在窗口内最后一整行停留,并保留 第一个 `MARKER_DECLARATION_FILE_CAP` (单位:千美元)**64国道**() 实物/来源的有效声明 秩序。 秩序. `omittedMarkers` 报告超过上限的确切数字,不包含 分配每个标记对象.

标记必须是专用评论行上的第一个内容. 继续传教, 字符串正文,并排入从成为声明的内在评论. 行数 内部 ` ``` ` 或者说 `~~~` 围栏被忽略。 用于下标扩展 (单位:千美元)`.md`, (中文(简体) ), `.mdx`, (中文(简体) ), `.markdown`),唯一被接受的评论介绍人是 `<!--` 财务报告和审定财务报表 `{/*`。 。 。 .

`readSourceMarkers(path)` 添加已绑定的文件系统读取和报表 `state` 作为 `scanned`, (中文(简体) ), `absent`, (中文(简体) ), `unreadable`,或 `out-of-tree`,所以"没有找到标记"是 从来没有与"不能看"混淆。 扫描结果包括: `scannedBytes` 财务报告和审定财务报表 `fileBytes` 对观测到的扫描范围.

如果一个文件在读取时更改, 将这些字节计数为 而不是严格的算术.

## 文件系统边界

`readSourceMarkers` 取一个相对路径从 `cwd`。 。 。 .

-   绝对路径被拒绝为 `out-of-tree`。 。 。 .
-   从工作树上爬出的道路 `out-of-tree`。 。 。 .
-   连结被拒绝为 `unreadable` 没有打开目标.
-   非常规文件也 `unreadable`,因此 FIFOs 和类似的特殊文件 无法屏蔽读取.

## 批次扫描

`readSourceMarkersBatch(paths, cwd)` 是用于 `checkChanges`。它使输入路径正常化、调试和排序;扫描 首个 **3 000个** 最多与正常路径相通 **16个** 飞行中读取 返回每个已跳过的道路。 在同时读完之后,保留 第一个 `MARKER_DECLARATION_BATCH_CAP` (单位:千美元)**1万个**在代码单元路径中声明 然后是物理/源指令。 这批货 `declarations` 报告给出精确 `total`, (中文(简体) ), `retained`, (中文(简体) ), `omitted`, (中文(简体) ), `perFileOmitted`,以及 `batchOmitted` 计数.

传过去 `SourceMarkerBatchScan` 结束 `markerScans` 以获得标记意识 决策与决定 `markerScan` 报告而不添加文件系统 访问 `checkChanges`. 宣言分会产生一项咨询意见 `marker-declarations-capped` 查找和永远不变 `CheckOutcome.ok`。 。 。 .

公布的无害环境管理文物在22号节点或较新的节点上运行。 联合国 adrkit 仓库使用 Bun.

另见 [`@adrkit/mcp`](https://npmcn.com/package/%40adrkit/mcp/README.md),本地只读模式上下文 协议服务器将同一实体暴露于编码代理.

联合国 [https://adrkit.dev (中文(简体) )](https://adrkit.dev/)

许可证: Apache-2.0

## 常见问题

### @adrkit/core 是什么？

纯 ADR 解析,验证,迁移,并影响解析为adrkit\.

### 如何安装 @adrkit/core？

在项目目录运行 npm install @adrkit/core，或使用 pnpm add / yarn add / bun add。

### @adrkit/core 支持 TypeScript 吗？

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

### @adrkit/core 支持 ESM 还是 CommonJS？

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

### @adrkit/core 需要什么版本的 Node\.js？

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

### @adrkit/core 可以商用吗？

@adrkit/core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adrkit/core 的下载量有多少？

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

### @adrkit/core 还在维护吗？

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