# @ai-matrx/diff 中文文档
规范地址：https://npmcn.com/package/%40ai-matrx/diff/
版本：0\.6\.35
npm 元数据更新时间：2026-10-28T12:43:09.756Z
中文译文更新时间：2026-11-05T18:47:16.328Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/diff
原文对照：https://npmcn.com/package/%40ai-matrx/diff/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/diff#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：1.7 MB，52 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-08-29T06:27:18.618Z
- 最新版本发布：2026-10-28T12:43:09.535Z
- 近 30 天下载量：55928（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 53 个）
## 中文简介
AI Matrx diff产品:一行级LCS文本引擎,结构树/阵列引擎,以及完整的React取景器——分出/入出/高亮取景器,词层亮点,折叠,每洪克接受/回放合并,结构实体diff与其相通
## 安装
```sh
npm install @ai-matrx/diff
```
也可以使用：`pnpm add @ai-matrx/diff`、`yarn add @ai-matrx/diff`、`bun add @ai-matrx/diff`
## README
# @ ai- matrx/ diff
完整的AI Matrx diff产品:两个纯引擎外加回放取景器 建在他们身上.
- **`@ai-matrx/diff/react`** 整个UI. `DiffViewer` (核心 其他一切组成), `TextDiff`, (中文(简体) ), `DiffReview` (平时合并), `InlineTextDiff`, (中文(简体) ), `AnimatedDiffReveal`,以及结构化实体查看器 `DiffViewerShell` 与 它的场适配器。 没有图标库,没有UI工具包,没有编辑器依赖性.
- 下面的引擎是纯粹的逻辑,零依赖性,没有DOM,没有在 导入时间 :
- **`@ai-matrx/diff/text`** ——行级LCS文本 diff. 一个计算输出两个 统一`inline`)并相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相`rows`() 说明,包括字/字级 在已更改的行配对上突出显示段并显示将 diff 转换为 unk 模式 接受/拒绝合并工具.
- **`@ai-matrx/diff/structural`** 通用树/阵列结构diff。 深潜 二 纯对象被打入每字段可插入的身份密钥的已打的更改节点树 用于阵列匹配.
词根( E)`@ai-matrx/diff`再出口两个引擎. `/react` 是一个单独的 子路径,所以一个没有头的消费者 从不支付UI.
```bash
npm install @ai-matrx/diff
```
## 反应查看器
```tsx
import { DiffViewer, DiffReview } from "@ai-matrx/diff/react";
// Read-only. Fills its container: render it as a route, a window, a modal, a
// sheet, or any region of a page.
// Merge. Every hunk is pending / applied / rejected; Apply hands back the text.
save(merged)} />
```
视图 : `split` (边接边接), `inline` (统一), `highlight` (单页- 页:1 _新设_ 仅以已改变的区域有锡 读者取景,不是代码diff. 未更改上下文折叠为几行 每跑一次更改并扩展; 前置/ 下一次在更改之间跳出; 互换翻转 哪一边是基线。 diff是计算ONCE,所以解析,扩展 和导航 永远不再运行 LCS.
### 结构(实体)
```tsx
import { computeDiff } from "@ai-matrx/diff/structural";
import {
DiffViewerShell,
createAdapterRegistry,
TextFieldAdapter,
TagsFieldAdapter,
} from "@ai-matrx/diff/react";
const adapters = createAdapterRegistry();
adapters.register("instructions", TextFieldAdapter);
adapters.register("tags", TagsFieldAdapter);
```
没有注册适配器的字段返回到软件包的 `DefaultFieldAdapter` - 从来没有下降。 证明行是明确的 他们不知道(装入或无法使用),从不取代全记录的 缺少字段日期的时标.
### Styling——代号合同
组件只通过语义符号词汇来消耗颜色 (单位:千美元)`--card`, (中文(简体) ), `--muted-foreground`, (中文(简体) ), `--border`, (中文(简体) ), `--primary`, (中文(简体) ), `--success`, (中文(简体) ), `--destructive`(中文(简体) ). 两个主机步骤:
```css
/* Tailwind v4: compile the package's utilities. */
@source "../node_modules/@ai-matrx/diff/dist";
```
```ts
// Fresh app with no token vocabulary of its own — gives every token a
// sensible light/dark value. Apps that already define the AI Matrx tokens
// must NOT import this.
import "@ai-matrx/diff/styles.css";
```
红色-去除-去除-去除-去除-去除-去加绿色-去除-去除-去除-去除-去除-去除-去除-去除-去除-去除-去取-去除-去除-去除-去除-去取-去取-去取-去取-去取-去取-去取-去取-去取-去取-去取-去取-去取-去取-去-去取-取-取-去-取-取-取-去-取-取-取-去-取-取-取-去-取-取-取-取-取-取-去-取-取-取-取-取-取-用是故意的,非自 (d) 其他一切——表面, 边框、 文本、 填充 —— 遵循主机的符号.
### 一个注射接缝:一个重(代码编辑器)渲染器
该套件不包含代码编辑依赖性. 登记一和 `DiffViewer` 路由源代码和对它的大量输入 :
```tsx
import { setHeavyDiffRenderer, MONACO_DIFF_EDITOR_OPTIONS } from "@ai-matrx/diff/react";
setHeavyDiffRenderer(MyMonacoDiff); // once, at module scope
```
由于没有登记,轻引擎使一个完整的diff——即: 工作默认,而不是站立。 只有一个 **明确** `engine="monaco"` 那个 无法被尊重是退化的, 它在工具栏和通过 `onEngineResolved`。 。 。 .
## 文本引擎
```ts
import { computeTextDiff, applyHunks } from "@ai-matrx/diff/text";
const diff = computeTextDiff("the quick fox\nsecond line", "the slow fox\nsecond line");
diff.stats; // { additions: 0, deletions: 0, modifications: 1, unchanged: 1 }
diff.inline; // unified view: one entry per line per side (removed, then added)
diff.rows; // split view: one aligned row per pair, left/right cells
diff.rows[0].left.segments;
// word-level highlights on the modified pair:
// [{ type: "unchanged", value: "the " }, { type: "removed", value: "quick" },
// { type: "unchanged", value: " fox" }]
diff.whitespaceOnly; // true when only whitespace differs
// Merge tool: accept/reject hunks, get the merged text back.
// Accept-all === modified, accept-none === original — exactly.
applyHunks(original, modified, [0, 2]); // accept hunks 0 and 2, keep the rest old
```
行为说明: 在同一变换区块中的去除/添加行 _修改_ (配对至少相近25%时带有线内段);投入太大,无法 密集的LCS基质安全地降解为整块取代OOMing; `ignoreTrailingWhitespace` 是一个显示选项 — hunk/ 相现模型总是 diffs 原始 线条可以精确地合并圆行字节. `maxLcsCells` 收紧矩阵盖.
另有两行读取共用相同的受限对齐:
```ts
import { computeLineChanges, analyzeTextChange } from "@ai-matrx/diff/text";
// A code editor's "+N −M": an edited line is one deletion plus one addition.
const { additions, deletions, lines } = computeLineChanges(before, after);
// A sync conflict's content-loss reading (who holds lines the other lacks,
// lines/chars changed, whitespace/blank-line/trim-only flags, merged segments).
const a = analyzeTextChange(local, remote, { maxLcsCells: 250_000 });
a.modifiedHasContentOriginalLacks; // keeping `local` would lose remote's lines
```
在盖子上方保留了共同的前缀和后缀,并将已更改的中间读作一体 移除了块,然后增加了一个块,然后说 `degraded: true`。 。 。 .
## 结构引擎
```ts
import { computeDiff, filterChangesDeep } from "@ai-matrx/diff/structural";
const result = computeDiff(
{ title: "Old", items: [{ id: "a", qty: 1 }, { id: "b", qty: 2 }] },
{ title: "New", items: [{ id: "b", qty: 2 }, { id: "a", qty: 5 }] },
{ identityKeys: { items: "id" } }, // or (item, index) => string
);
result.hasChanges; // true
result.stats; // { added, removed, modified, unchanged, total }
result.root; // DiffNode tree: title modified; items modified with children:
// "a" modified (qty 1 → 5), "b" reordered
filterChangesDeep(result.root); // prune everything unchanged
```
行为说明: 默认忽略对象密钥顺序( 选择通过 `orderSensitiveObjectPaths`; 下划线前缀的密钥在默认情况下进行比较—— schema 合同密钥如 `__kind` 数据(`skipUnderscorePrefix: true` 是一个明确的选入 演示文稿过滤器); 多样数组(`[{...}, "str"]`永不 抛出 — 错配的对是修改过的叶子; 当配置的身份密钥不是时 独有的,引擎会回到无损失的位置匹配,而不是静默 投放项目; `excludePaths` 将空名取为根字段或点出路径 被窝住的.
`diffRecordFields(prior, next, rowChange)` 是一行的顶级读取 写入, 对于行历史时间表: 插入 / 删除 / 更改字段, 一个 JSON 列 整体变化(平等是: `===` 或匹配 `JSON.stringify`键序 计算)和a `"insert"` 或者说 `"delete"` 以插入或 删除.
## 设计
- 纯引擎,具有匹配类型声明的双重无害环境管理/CJS,经核查 装入后装入弹丸 `import` 财务报告和审定财务报表 `require`编辑 `/react` 块携带 `"use client"` 边框; 引擎 输入时故意不这样做, 因此它们在 React Server 内保持合法 构成部分。 柏球门检查双向.
- 两台引擎在渲染过程中运行愉快;每条四相径被封住并被降解 而不是扔或吊.
- 整个严格类型 : `exactOptionalPropertyTypes`, (中文(简体) ), `noUncheckedIndexedAccess`无 `any`。 。 。 .
- `react` 编号 : `react-dom` (仅限) `/react` 需要他们.
## 许可证
麻省理工学院
### 审查会议
`DiffReview` 要求每个汉克在应用前被接受或拒绝。 对a 主机所属会话, 从 `@ai-matrx/diff/text`,通过 `session` 还有一个 `onTransition` 减小边界; 否则通过 `original` 财务报告和审定财务报表 `modified` 页:1 源键内部会话。 设定 `disabled` 当主机等待.
## 常见问题
### @ai-matrx/diff 是什么？
AI Matrx diff产品:一行级LCS文本引擎,结构树/阵列引擎,以及完整的React取景器——分出/入出/高亮取景器,词层亮点,折叠,每洪克接受/回放合并,结构实体diff与其相通
### 如何安装 @ai-matrx/diff？
在项目目录运行 npm install @ai-matrx/diff，或使用 pnpm add / yarn add / bun add。
### @ai-matrx/diff 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @ai-matrx/diff 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @ai-matrx/diff 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @ai-matrx/diff 可以商用吗？
@ai-matrx/diff 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @ai-matrx/diff 的下载量有多少？
根据 npm 官方下载统计，@ai-matrx/diff 在 2026/10/05 – 2026/11/03 这 30 天内被下载 55,928 次，日均约 1,864 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @ai-matrx/diff 还在维护吗？
最新版本 0\.6\.35 发布于 2026/10/28（8 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 53 个；首次发布于 2026/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。