接口文档转字段映射（ERP/OpenAPI 一键结构化）

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

解析 ERP/第三方接口文档（Markdown 表格 / JSON Schema / 示例 JSON / 纯文本字段列表），提取字段名、类型、必填、说明，并自动推断接口端点与请求/响应结构，生成字段映射。触发词：解析接口文档、提取 API 字段、文档转字段映射、对接第三方接口、ERP 字段解析、接口文档结构化。

parse-api-doc —— 接口文档字段智能解析

功能概述

parse-api-doc —— 接口文档字段智能解析是一项面向实际任务的技能，主要用于把任意格式的接口/字段文档，解析成结构化字段清单 + 字段映射，用于对接第三方系统；纯函数实现（Node ESM，零依赖），可直接 import 使用，也可作为 AI 抽取字段映射的参考实现；

核心要点

拿到一份 ERP / 开放平台 / 内部中台的接口说明，要快速知道「有哪些字段、什么类型、哪些必填」；
要把对方文档字段映射到自己。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

parse-api-doc —— 接口文档字段智能解析

把任意格式的接口/字段文档，解析成结构化字段清单 + 字段映射，用于对接第三方系统。纯函数实现（Node ESM，零依赖），可直接 import 使用，也可作为 AI 抽取字段映射的参考实现。

适用场景

拿到一份 ERP / 开放平台 / 内部中台的接口说明，要快速知道「有哪些字段、什么类型、哪些必填」
要把对方文档字段映射到自己的采集/存储字段（字段名不一致时的别名模糊匹配）
从 Markdown 表格、JSON Schema、示例 JSON、纯文本字段列表里批量提取字段

支持的输入格式（自动探测）

Markdown 表格：| 字段 | 类型 | 必填 | 说明 |
JSON Schema：含 "properties" + "type"
示例 JSON：{ "asin": "B0XXX", "title": "标题" }
纯文本字段列表：asin: 商品ID / title (string) 商品标题

用法

import { parseErpDocument, matchField, loadVocabulary } from './scripts/doc-parser.mjs';

const doc = `
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asin | string | 是 | 商品ID |
| title | string | 否 | 商品标题 |
`;

const result = parseErpDocument(doc);
console.log(result.detectedFormat);   // markdown_table
console.log(result.productFields);    // [{name,type,required,description}]
console.log(result.fieldMappings);    // [{erpField,erpType,erpRequired,erpDescription,collectorField}]
console.log(result.endpoint);         // 自动推断的 方法+路径

核心 API

parseErpDocument(content, options?) → DocParseResult
- options.vocabulary：自定义字段词汇表（默认内置一组常见电商/API 字段，可注入你自己的）
- 返回：{ success, detectedFormat, productFields[], endpoint, requestStructure, responseStructure, fieldMappings[], error? }
matchField(name, vocabulary?) → 命中的标准字段 key（模糊/别名匹配，归一化大小写与 _-）
loadVocabulary(text) → 从文本构建词汇表（便于按需扩展）

字段映射词汇表（可注入）

默认词汇表覆盖常见字段（asin/title/price/rating/bsr/image/brand...）。对接自家系统时，传入你自己的词汇表即可：

const myVocab = [
  { key: 'sku', aliases: ['sku', '货号', '商品编码'] },
  { key: 'stock', aliases: ['stock', '库存', 'quantity'] },
];
parseErpDocument(doc, { vocabulary: myVocab });

注意

解析失败时 success=false 且带 error.code（EMPTY_CONTENT / PARSE_ERROR / NO_FIELDS_FOUND），error.suggestion 给出针对性修改建议。
这是结构抽取工具，不调用网络、不发送任何数据，纯本地解析。