# @adlc/behavior-diff 中文文档

规范地址：https://npmcn.com/package/%40adlc/behavior-diff/

版本：1\.12\.0
npm 元数据更新时间：2026-10-10T03:09:30.202Z
中文译文更新时间：2026-11-06T00:20:32.229Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adlc/behavior-diff
原文对照：https://npmcn.com/package/%40adlc/behavior-diff/?lang=original
项目主页：https://github.com/voodootikigod/adlc/tree/main/packages/behavior-diff#readme
源码仓库：https://github.com/voodootikigod/adlc

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

- 包体积（解压后）：32.6 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-06-13T21:12:05.655Z
- 最新版本发布：2026-10-10T03:09:29.811Z
- 近 30 天下载量：8227（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

行为-空间diff用于P6人行门——回顾行为上的变化,而不是5000行diff.

## 安装

```sh
npm install @adlc/behavior-diff
```

也可以使用：`pnpm add @adlc/behavior-diff`、`yarn add @adlc/behavior-diff`、`bun add @adlc/behavior-diff`

## README

# 行为- diff —— ADLC C14

用于 **P6 人行门**. 审查 _变了什么_ 在行为, 不是五千行长 捕获可观测到的HTTP表面(状态、内容类型、体) 结构)在变化前后,然后diffs在行为空间:"3个终点 换了外形,1去掉,其他的都一样"

代码diff为5000行;行为diff为6项. 人文审查 **意图对行为** ——唯一判断机器不能作出——同时显示 (C11)证明机器已经做了其余的.

* * *

## ADLC 阶段

**P6 — 人行门**由人文审查员在出道时直接使用. 与 `gate-manifest` (C11): 清单证明机器检查通过;行为差异 证明可观察到的行为在预期范围内.

* * *

## 动词

### `capture`

点击配置文件中的每个路径, 将可观察到的 HTTP 行为记录到 JSON 示意图.

```
behavior-diff capture --config behavior.json --out before.json
```

**旗帜 :**

| 旗帜 | 需求 | 说明 |
| --- | --- | --- |
| `--config <path>` | 对 | JSON 文件的行为配置路径 |
| `--out <path>` | 对 | 快取 JSON 输出路径 |
| `--json` | 没有 | 打印机器可读结果摘要到 stdout |

**配置格式** (单位:千美元)`behavior.json`:

```json
{
  "baseUrl": "http://localhost:3000",
  "routes": [
    { "method": "GET", "path": "/health" },
    { "method": "GET", "path": "/api/users" },
    { "method": "POST", "path": "/api/items", "body": { "name": "test" } },
    { "method": "GET", "path": "/api/data", "headers": { "Accept": "application/json" } }
  ]
}
```

每条路线: `{ method, path, body?, headers? }`。 。 。 . `body` 序列化为 JSON 与 `Content-Type: application/json` 自动添加.

**记录每条路由错误** (截至 `{ method, path, error }`(不中止) 运行。 该快照中总是包含每个配置路径的条目.

**抓取的退出代码 :**

| 代码 | 含义 |
| --- | --- |
| `0` | 所有路线都尝试过, 至少一个可以到达; 快照写入( 有些路线可能错误) Name |
| `1` | 操作错误: 配置文件无法读取, 无效配置, 无法写入输出 |

* * *

### `compare`

比较两个快照,并产生一个人可读的行为报告.

```
behavior-diff compare before.json after.json [--json]
```

**旗帜 :**

| 旗帜 | 需求 | 说明 |
| --- | --- | --- |
| `--json` | 没有 | 打印机器可读的 diff 结果到 stdout |

**产出(人可读):**

```
2 routes identical, 2 changed, 0 errored

  + GET /metrics: route added (absent in before, present in after)
  ~ GET /health:
      body (json): 2 changes:
        ~ version: "1.0.0" → "2.0.0"
        + newField: "added"
  ~ GET /users:
      status: 200 → 503
      body (json): 2 changes:
        - users: [...]
        + error: "Service Unavailable"
```

**Diff 规则 :**

-   匹配的路线 `METHOD path`。 。 。 .
-   状况变化:直接报告.
-   内容类型变化:报告(参数如下): `; charset=utf-8` 页:1.
-   JSON身体:结构递归diff. 路径使用点标记( I)`body.items[3].price`) (中文(简体) ). 阵列: 长度变化报告 + 第一个不同的索引已钻入 。 潜入了50道.
-   文字/二元体:由SHA-256散列作比较.
-   道路只进入前 ~"删除"。 只有"加"之后的路线.

**比较的退出代码 :**

| 代码 | 含义 |
| --- | --- |
| `0` | 出入口——所有路线相同 |
| `1` | 操作错误: 快照文件无法读取或无效的 JSON |
| `2` | 门失败——一个或多个路线被更改、去除或添加 |

* * *

## 典型的工作流程

```bash
# Before the change: capture baseline
behavior-diff capture --config behavior.json --out before.json

# Make your code change, restart the service, then:
behavior-diff capture --config behavior.json --out after.json

# Review behavior diff (exits 0 if clean, 2 if changes found)
behavior-diff compare before.json after.json
```

* * *

## 抓图格式

```json
{
  "baseUrl": "http://localhost:3000",
  "capturedAt": "2024-01-15T10:30:00.000Z",
  "routes": [
    {
      "method": "GET",
      "path": "/health",
      "status": 200,
      "contentType": "application/json",
      "body": { "status": "ok" }
    },
    {
      "method": "GET",
      "path": "/large-html",
      "status": 200,
      "contentType": "text/html",
      "body": { "textHash": "sha256hex...", "bytes": 4096 }
    },
    {
      "method": "GET",
      "path": "/broken",
      "error": "timeout after 10000ms"
    }
  ]
}
```

-   JSON回应:身体被解析并存储为JSON值.
-   非JSON反应: 被储存为 `{ textHash, bytes }`。 。 。 .
-   错误: 路由存储为 `{ method, path, error }` (无状态/机构).

* * *

## 未来工作(请注意)

**浏览器/ 无头模式** ——通过无头浏览器渲染路由,diff渲染出 DOM 或者截图 已记录为今后的工作;尚未执行。 HTTP 固定模式 (此工具) 是当前支持的模式 .

* * *

## 核心差距

无。 此工具自成一体, 只使用 `parseArgs`, (中文(简体) ), `pass`, (中文(简体) ), `gateFail`, (中文(简体) ), `opError`,以及 `printJson` 从 `@adlc/core`。在本地通过 `node:crypto` 而不是核心 `sha256` 帮助避免对齐抓取 序列化格式到共享库.

## 常见问题

### @adlc/behavior-diff 是什么？

行为-空间diff用于P6人行门——回顾行为上的变化,而不是5000行diff\.

### 如何安装 @adlc/behavior-diff？

在项目目录运行 npm install @adlc/behavior-diff，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 behavior-diff，可以用 npx behavior-diff 直接运行。

### @adlc/behavior-diff 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adlc\_\_behavior-diff 是否存在。

### @adlc/behavior-diff 支持 ESM 还是 CommonJS？

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

### @adlc/behavior-diff 需要什么版本的 Node\.js？

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

### @adlc/behavior-diff 可以商用吗？

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

### @adlc/behavior-diff 的下载量有多少？

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

### @adlc/behavior-diff 还在维护吗？

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