内容
# 目录属性标准化工具
清理和标准化来自多个来源的混乱的商品目录属性和分类映射——标题、描述、图片输入；一致的属性、单位和类别映射输出。适用于商家运营团队和供应链工具开发人员，用于处理Shopify导出、供应商CSV和市场抓取，这些数据通常对“尺寸”或“材质”等属性有不同的表示。
## 它能做什么
- 接受一批原始商品（`标题`、`描述`、`原始属性`），返回标准化的属性（规范化的尺寸/颜色/单位）以及您请求的分类法的分类映射（谷歌产品分类法、Shopify、亚马逊）。
- 作为MCP服务器（`normalize_catalog`工具）或普通的HTTPS API工作。
### 示例（MCP工具调用）
```json
{
"tool": "normalize_catalog",
"input": {
"products": [{ "title": "...", "description": "...", "raw_attributes": { "size": "Lrg", "Color": "Navy Blue" } }],
"target_taxonomies": ["google", "shopify"]
}
}
```
```json
{
"results": [
{
"schema_version": "2.0",
"source_title": "...",
"category_paths": {
"google": { "path": ["服装及配饰", "服装", "衬衫和上衣"], "leaf_id": null, "confidence": 0.9 },
"shopify": { "path": ["服装及配饰", "服装", "上衣"], "leaf_id": "aa-3-1", "confidence": 0.85 }
},
"attributes": {
"size": { "value": "L", "provenance": "canonicalized" },
"color": { "value": "navy", "provenance": "canonicalized" }
}
}
]
}
```
`attributes` 是通过受控词汇表（`size`、`color`、`material`、`gender`、`sleeve_length` — 未识别的键将被删除，不会通过模型选择的名称传递）进行索引的。每个值的 `provenance` 为 `"canonicalized"`，当它来自您自己的 `raw_attributes` 输入时（仅确定性清理，无召回），或 `"extracted"`，当模型从标题/描述中推断出它时（并且它不在您的输入中）——将 `"extracted"` 值视为建议，就像您对待低置信度的 `category_paths` 条目一样。
**属性通过构造可靠** — 规范化已经在您的输入中的值，而不是召回。**类别分类基于检索**，而不是从内存中召回：候选类别从真实的、当前的谷歌和Shopify分类法文件中检索，并作为建议提供给模型，因此 `leaf_id` 几乎总是命名一个实际存在的节点 — 在12个产品评估集中测量，**22/24（91.7%）精确路径 + leaf-ID 匹配**。仍然将 `confidence` 和 `null` `leaf_id` 视为“值得快速检查”，而不是保证 — `leaf_id` 仅在路径独立验证通过真实分类法文件时返回，因此 `null` 是一个诚实的“检查此项”信号，而不是伪造的ID。亚马逊没有可用的公共分类法参考文件，因此它保持最佳努力（从内存中召回），而不是基于检索。
## 定价
- **免费** — 500件商品/月，不需要信用卡。
- **按需付费** — 0.01美元/件商品，无最低消费。
- **专业版** — 29美元/月，适用于5,000件商品（有效价格约为0.0058美元/件商品）。
## 获取密钥
MCP服务器位于 `https://acjlabs-catalog-normalizer.acjlabs.workers.dev/mcp`。免费套餐密钥自助服务 — `POST /v1/signup` 发送 `{ "email": "you@example.com" }` 直接在响应中返回您的密钥，有效期为500件商品/月，不需要信用卡。**立即存储它 — 它只显示一次，丢失后无法恢复**（重新注册获取新的密钥）。付费密钥通过一次性声明链接提供，适用于专业版/按需付费计费生效后。
## 连接到MCP客户端
使用Claude Code：
```bash
claude mcp add --transport http catalog-normalizer \
https://acjlabs-catalog-normalizer.acjlabs.workers.dev/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
```
任何其他支持带有自定义标头的远程HTTP服务器的MCP客户端（Cursor、Cline、VS Code等）都以相同的方式工作：使用带有 `Authorization: Bearer YOUR_API_KEY` 标头的上述URL。网关或扫描仪只能转发原始密钥值（无 `Bearer` 前缀）也支持 — 两种形式都经过身份验证。工具发现（`initialize`/`tools/list`）不需要密钥；只有调用 `normalize_catalog` 需要。
## npm客户端
更喜欢类型化的函数而不是手动构造MCP JSON-RPC调用？`@acjlabs/catalog-attribute-normalizer-client`（`client/`，尚未发布 — npm发布是受控的创始人操作）包装了 `normalize_catalog` 工具调用：
```ts
import { createCatalogNormalizerClient } from "@acjlabs/catalog-attribute-normalizer-client";
const client = createCatalogNormalizerClient({
baseUrl: "https://acjlabs-catalog-normalizer.acjlabs.workers.dev",
apiKey: "...",
});
const results = await client.normalizeCatalog(products, ["google", "shopify"]);
```
## 为什么不直接使用类别分类器？
类别分类器（ProductCategorization.com、ProductClassifier.com）告诉您一个产品是什么。它们不涉及更复杂的问题：跨不同来源标准化属性，每个来源对属性的表示不同。另一家提供更全面的服务的供应商DataWeave，面向企业销售 — 没有自助服务，没有公开价格。参见[完整比较](docs/comparison.md)，或阅读[为什么“干净的产品数据”实际上是两个不同的问题](docs/attribute-normalization-vs-classification.md)（规范化与分类，以及它们如何不同地失败）。
## 源代码可用性和支持
此仓库托管托管服务的文档。服务实现不开源。欢迎在此仓库的Issues中提交错误报告和功能请求；您也可以通过 <contact@acjlabs.com> 联系我们。
