# @commercetools/processors 中文文档

规范地址：https://npmcn.com/package/%40commercetools/processors/

版本：0\.1\.1
npm 元数据更新时间：2026-10-23T12:13:36.065Z
中文译文更新时间：2026-11-10T14:02:58.736Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40commercetools/processors
原文对照：https://npmcn.com/package/%40commercetools/processors/?lang=original
项目主页：https://github.com/commercetools/commerce-mcp
源码仓库：https://github.com/commercetools/commerce-mcp

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

- 包体积（解压后）：57.5 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-05-04T11:04:04.346Z
- 最新版本发布：2026-10-23T12:13:35.621Z
- 近 30 天下载量：2263（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

MCP 服务器的输出处理器集

## 安装

```sh
npm install @commercetools/processors
```

也可以使用：`pnpm add @commercetools/processors`、`yarn add @commercetools/processors`、`bun add @commercetools/processors`

## README

# @ 商业工具/ 处理器

**输出处理器** 用于MCP型工具有效载荷和类似JSON:声明式 **字段过滤** (按键)和 **编辑** (任务值,包括URL形状字符串内的查询字符串),加 **转换** 将结构化工具结果转化为 **表格** 或者说 **贾森** 文本.

图书馆是 **域不可识别**:您通过普通对象/阵列/原始对象(任何通常情况下) `JSON.parse`) (中文(简体) ). 规则的使用 **点路径** 从您输入的值的根入 `filterFields`。 。 。 .

* * *

## 安装

```bash
npm add @commercetools/processors
```

或者说

```
yarn add @commercetools/processors
```

您还可以使用 `npm` 或者说 `yarn` 使用相同的软件包名称.

**运行时间 :** 节点 **第18条**。 。 。 .

* * *

## 软件包布局( 每个区域做什么)

| 区域 | 责任 |
| --- | --- |
| **`FieldFilteringHandler`** | 递归行走一个值。 打开 **对象**,每个密钥路径应用规则 **数组**,将每个元素相映射(路径规则不添加数组索引-见下文)。 打开 **字符串**如果字符串是 **无效的 URL**,运行相同的规则逻辑 **查询参数名称**;其他字符串作为-s留下. |
| **`FieldFilteringManagerConfig`** | 宣布性规则清单`paths`, (中文(简体) ), `properties`, (中文(简体) ), `includes`\+ 可选 **白名单** 路径和自定义 **编辑占位符** jSON 对 URL 查询值的字符串 . |
| **`FieldFilteringManager`** | 接口 : `filterFields` + 键 `filterUrlFields`. 互换执行(例如远程政策)和使用 **`isFieldFilteringManager`** 在运行时间告诉 **配置** 从 **实例**。 。 。 . |
| **`transformToolOutput`** | 转换 `data` 改为 a **字符串**默认 **`tabular`** (缩进,财产名称通过 `transformPropertyName`,布尔表示 `Yes`编号 :`No`,酌情列出对象数组的表格) **`json`** 把JSON绑起来. |
| **`transformPropertyName`** | 转换标识符像 `orderLineId` 或者说 `order_line_id` 以人为主的标签(内部用表格输出和标题). |
| **`urlHelpers`** | **`isValidUrl`**, (中文(简体) ), **`normaliseUrl`**, (中文(简体) ), **`generateQueryString`** ——小公用设施与处理器的URL处理共享. |
| **`defaultFilteringRules`**, (中文(简体) ), **`defaultJsonRedactionText`**, (中文(简体) ), **`defaultUrlRedactionText`** | 配置中省略时的编辑占位符默认值( E)`[REDACTED]` 编号 : `REDACTED`) (中文(简体) ). |

* * *

## 使用概况

```ts
import {
  FieldFilteringHandler,
  type FieldFilteringManagerConfig,
  type FieldFilteringRule,
  type FieldFilteringManager,
  isFieldFilteringManager,
  defaultFilteringRules,
  defaultJsonRedactionText,
  defaultUrlRedactionText,
  transformToolOutput,
  transformPropertyName,
  isValidUrl,
  generateQueryString,
  normaliseUrl,
} from '@commercetools/processors';
```

典型流量 : **克隆** (或剖析新鲜的JSON) **`new FieldFilteringHandler(config).filterFields(data)`** ——可选 **`transformToolOutput({ data: safe, ... })`** 在发送到模型、代理或客户之前.

* * *

## 实地过滤和编辑

### 克隆为何重要

`filterFields` **变异** 设置对象图表(删除密钥,替换值)。 如果在别处引用同一对象(缓存、记录器、重试),这些视图也会改变。 永远 **`structuredClone`**, (中文(简体) ), `JSON.parse(JSON.stringify(x))`,或另一个 **深层复制** 在需要隔离时过滤.

### 如何评价规则(精神模型)

对于每个对象键,处理器会构建一个 **路径** 喜欢 `parent.child.leaf`。然后,为 **过滤器** 或者说 **编辑** 单独:

1.  **白名单** 如果当前路径匹配白名单条目, **没有** 从声明列表中过滤/删除路径(精确/例规则如测试).
2.  **`paths`** 完全路径匹配; **`filter`** 拆除该财产; **`redact`** 替换 **路径的全部值** 与 `jsonRedactionText` (子树不会像嵌入式钥匙那样在路径校正上进一步穿行——边缘情况请参见处理器测试).
3.  **`properties`** 比较 **最后一段** 每个规则的路径(关键名称).
4.  **`includes`** 下弦比对 **最后一段** (例如:. `secret` 匹配 `clientSecret` 当事无因.

**矩阵 :** 元素与 **不变** `currentPath` 作为母数组( 无) `.0`, (中文(简体) ), `.1` 在路径。 规则已按键 **属性名称** 或者说 **`includes`** 仍在对象内应用 **内部** 阵列; **满 `paths`** 假设的规则 `items.0.field` 将 **没有** 匹配库存处理器 - 使用 **`properties`编号 :`includes`** 或习惯 **`FieldFilteringManager`**。 。 。 .

### `FieldFilteringManagerConfig` (参考文献)

每个顶级域都是 **选项**;只提供你需要的东西.

| 选项 | 类型 | 作用 |
| --- | --- | --- |
| **`paths`** | `FieldFilteringRule[]` | 符合 **全点路径** 从数值的根移到 `filterFields`。 。 。 . `type: 'filter'` 删除密钥. `type: 'redact'` 以 `jsonRedactionText` (通常整个对象成为占位符字符串). |
| **`properties`** | `FieldFilteringRule[]` | 符合 **叶键名称** 时间 **任意** 深度( 如每 个) `token` ) (中文(简体) ). |
| **`includes`** | `FieldFilteringRule[]` | 叶名匹配 **包含** `rule.value` (下),按规则可选可折行. |
| **`whitelistPaths`** | `Omit<FieldFilteringRule, 'type'>[]` | 路径 **压制** 当评估的路径匹配时从上面的列表中过滤/校正(见精确对大小写不敏感行为的测试). |
| **`jsonRedactionText`** | `string?` | 修改后的替换 **贾森** 值( 默认值) **`[REDACTED]`**) (中文(简体) ). |
| **`urlRedactionText`** | `string?` | 修改后的替换 **URL 查询** 值( 默认值) **`REDACTED`**) (中文(简体) ). |

### `FieldFilteringRule`

| 外地 | 含义 |
| --- | --- |
| **`value`** | 路径, 叶名, 或下弦针( 取决于规则的阵列 ) . |
| **`caseSensitive`** | 若为 `false`,比较时使用已执行的不区分大小写匹配. |
| **`type`** | **`'filter'`** ——去除密钥(或查询参数). **`'redact'`** ——保留密钥/名,替换值. |

### `FieldFilteringManager` 财务报告和审定财务报表 `isFieldFilteringManager`

使用一个 **自定义类** 执行 `filterFields` 编号 : `filterUrlFields` 当您需要日志、远程策略或不同路径语义时 `FieldFilteringHandler`。 。 。 . **`isFieldFilteringManager(x)`** 当 `x` 具有两种方法(打字),所以可以接受 **无论是** 简单 **配置** 或现成 **管理器** 从配置 :

```ts
import {
  FieldFilteringHandler,
  isFieldFilteringManager,
  type FieldFilteringManager,
  type FieldFilteringManagerConfig,
} from '@commercetools/processors';

function getHandler(
  input: FieldFilteringManagerConfig | FieldFilteringManager
): FieldFilteringManager {
  if (isFieldFilteringManager(input)) {
    return input;
  }
  return new FieldFilteringHandler(input);
}

const handler = getHandler({
  properties: [{value: 'x', caseSensitive: true, type: 'filter'}],
});
const out = handler.filterFields({x: 1, y: 2});

// Expected `out`:
// { y: 2 }
```

* * *

## 实例: `FieldFilteringHandler` 关于JSON的

```ts
import {
  FieldFilteringHandler,
  type FieldFilteringManagerConfig,
} from '@commercetools/processors';

const config: FieldFilteringManagerConfig = {
  // Full path: redact only this branch's value (here the string becomes "[REDACTED]")
  paths: [
    {value: 'credentials.accessToken', caseSensitive: true, type: 'redact'},
  ],
  // Any key named apiKey (any casing): remove entirely
  properties: [{value: 'apiKey', caseSensitive: false, type: 'filter'}],
  // Any leaf name containing "secret": redact value, keep key
  includes: [{value: 'secret', caseSensitive: false, type: 'redact'}],
};

const toolResult = {
  credentials: {accessToken: 'tok', refresh: 'r'},
  apiKey: 'k',
  clientSecret: 's',
};

const safe = structuredClone(toolResult);
new FieldFilteringHandler(config).filterFields(safe);

// Expected `safe` (JSON-serialized for clarity):
// {"credentials":{"accessToken":"[REDACTED]","refresh":"r"},"clientSecret":"[REDACTED]"}
// - paths: credentials.accessToken value replaced; refresh unchanged
// - properties: apiKey key removed
// - includes: clientSecret value redacted (leaf name contains "secret")
```

* * *

## 实例: `filterUrlFields` (叫声字符串)

规则使用相同的机器: **过滤器** 丢弃查询对; **编辑** 保留名称并设定值为 **`urlRedactionText`**。 。 。 .

```ts
import {FieldFilteringHandler} from '@commercetools/processors';

const redacted = new FieldFilteringHandler({
  properties: [{value: 'sig', caseSensitive: false, type: 'redact'}],
}).filterUrlFields('https://x.example/y?sig=abc123&ok=1');

// Expected `redacted`:
// "https://x.example/y?sig=REDACTED&ok=1"

const stripped = new FieldFilteringHandler({
  properties: [{value: 'token', caseSensitive: false, type: 'filter'}],
}).filterUrlFields('https://api.example.com/callback?token=abc&ok=1');

// Expected `stripped`:
// "https://api.example.com/callback?ok=1"
```

* * *

## 实例: `transformToolOutput`

`format` 默认为 **`'tabular'`**与一个 **`title`**,标题为大写(在 `transformPropertyName`)并用作标题. 布尔斯变成 **`Yes`编号 :`No`**; 嵌入对象得到缩进行; 空平方对象生成 **`no properties`** (带有可选标题前缀-见下文).

### 表格, 有标题

```ts
import {transformToolOutput} from '@commercetools/processors';

const text = transformToolOutput({
  data: {orderId: '123', total: {currency: 'EUR', centAmount: 4200}},
  title: 'Order summary',
  format: 'tabular',
});

// Expected `text` (string; newlines shown as \n here):
// "ORDER SUMMARY\nOrder Id: 123\nTotal:\n\tCurrency: EUR\n\tCent Amount: 4200"
```

### 表格, 无标题

```ts
const plain = transformToolOutput({
  data: {a: 1},
  format: 'tabular',
});

// Expected `plain`:
// "A: 1"
```

### 表格, 空对象

```ts
const empty = transformToolOutput({data: {}, format: 'tabular'});

// Expected `empty`:
// "no properties"
```

### 图表,布尔

```ts
const stock = transformToolOutput({
  data: {inStock: true},
  format: 'tabular',
});

// Expected `stock`:
// "In Stock: Yes"
```

### JSON 格式

与 **`format: 'json'`**,输出为 `JSON.stringify` 数据(或单键对象,其键为转换后的标题) `title` 已设定).

```ts
const json = transformToolOutput({
  data: {orderId: '123', total: {currency: 'EUR', centAmount: 4200}},
  title: 'Order summary',
  format: 'json',
});

// Expected `json` (parsed shape):
// {"ORDER SUMMARY":{"orderId":"123","total":{"currency":"EUR","centAmount":4200}}}
// Exact string spacing follows JSON.stringify.
```

* * *

## 实例: `transformPropertyName`

分块 **骆驼 Case**, (中文(简体) ), **帕斯卡案件**, (中文(简体) ), **蛇脚( c)**,以及 **弹匣** 以字为单位,并应用轻标题式外壳(关于缩写边框的单位测试).

```ts
import {transformPropertyName} from '@commercetools/processors';

transformPropertyName('customerId');
// Expected: "Customer Id"

transformPropertyName('order_line_id');
// Expected: "Order Line Id"

transformPropertyName('propertyNameSDK');
// Expected: "Property Name SDK"
```

* * *

## 示例: URL 帮助者

```ts
import {
  isValidUrl,
  normaliseUrl,
  generateQueryString,
} from '@commercetools/processors';

isValidUrl('https://example.com/path?q=1');
// Expected: true

isValidUrl('not a url');
// Expected: false

normaliseUrl('https://a.com//b/../c?x=1');
// Example output (string; normalises slashes/host segment style — see tests for full matrix):
// "https://a.com/b/../c?x=1"

generateQueryString({a: 1, b: [2, 3]});
// Expected (qs indices format; leading `?`):
// "?a=1&b[0]=2&b[1]=3"
```

更多案件: **`processors/test/field-filtering/urlHelpers.test.ts`**。 。 。 .

* * *

## 默认导出

```ts
import {
  defaultFilteringRules,
  defaultJsonRedactionText,
  defaultUrlRedactionText,
} from '@commercetools/processors';

// `defaultFilteringRules` is a FieldFilteringManagerConfig-shaped object with only the default redaction strings set.
// `defaultJsonRedactionText` === '[REDACTED]'
// `defaultUrlRedactionText` === 'REDACTED'
```

* * *

## 从源建( Monorepo)

```bash
pnpm --filter @commercetools/processors install
pnpm --filter @commercetools/processors run build
pnpm --filter @commercetools/processors run test
```

* * *

## 进一步阅读

行为细节( 白名单 vs 路径, URL 括号密钥, 空规则短路等) 被覆盖 [这里](https://npmcn.com/package/%40commercetools/processors/test/field-filtering/FieldFilteringHandler.test.ts) 财务报告和审定财务报表 [这里](https://npmcn.com/package/%40commercetools/processors/test/transform/transformToolOutput.test.ts)

## 常见问题

### @commercetools/processors 是什么？

MCP 服务器的输出处理器集

### 如何安装 @commercetools/processors？

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

### @commercetools/processors 支持 TypeScript 吗？

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

### @commercetools/processors 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @commercetools/processors 需要什么版本的 Node\.js？

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

### @commercetools/processors 可以商用吗？

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

### @commercetools/processors 的下载量有多少？

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

### @commercetools/processors 还在维护吗？

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