报关单智能提取（profy-customs）

把合同、发票、提单、装箱单、核注清单这类贸易单据，转成一份字段级可追溯、可机器校验的报关单 JSON。每个字段都带 value / reason / confidence / page——你能看到它从第几页的哪句话来的，而不是拿到一堆无从复核的结果。

这是垂直行业插件，不是通用 OCR。它内置了中国海关的字段定义、代码表、跨字段规则与歧义决策树；通用 OCR 只能给你文字，它给你的是可申报的字段。

启用方式

profy-customs 是 user_selectable: true 的插件——必须在对话的插件面板里手动勾选，不会自动介入。它的 activation 只有 user_selectable 一项，没有 requires 也没有 conditions：勾选后在任何沙箱模式下都可用，不依赖 Desktop、不依赖浏览器。

"activation": { "user_selectable": true }

快速开始

上传单据后直接说：

帮我提取这份报关单

或指定模式：

你想做的事	说法	走的路径
完整提取	「帮我提取这份报关单」	Step 1 → Step 7 全流程
问字段规则	「成交方式怎么填」	只加载对应字段组说明
校验已有结果	「帮我校验这份 JSON」	直接调 `customs_validate`
代码互查	「一般贸易的监管方式代码是什么」	直接调 `customs_code_lookup`

三个工具

`customs_ocr` — 版面级文字识别

customs_ocr(
    file_url="https://.../bill-of-lading.pdf",
    pages="all",        # 或 "1-3"
)

调用自建 OCR 服务（RapidOCR），不在 Agent 进程内跑 OCR。返回每页：

字段	含义
`page`	页码（从 1 开始）
`width` / `height`	页面像素尺寸
`texts[]`	每条含 `text` / `bbox([x1,y1,x2,y2])` / `score`
`blocks[]`	版面块，`type` 为 `table` / `text` / `title`
`markdown`	整页的 markdown 表示，表格转成 md table

bbox 是这个工具存在的理由：报关单大量信息在表格里，光有文字流会丢掉「这个数字属于哪一列」。 服务地址由 CUSTOMS_OCR_URL 决定，默认 http://profy-ocr:8001，请求打到 /ocr/parse，单次超时 120 秒。

`customs_code_lookup` — 海关代码表查询

customs_code_lookup(
    table="supervision-methods",
    query="一般贸易",
    direction="name_to_code",   # 或 code_to_name
    fuzzy=False,
)

五张标准代码表：

`table` 取值	中文
`supervision-methods`	监管方式
`transport-modes`	运输方式
`trade-terms`	成交方式
`packaging-types`	包装种类
`insurance-modes`	保险方式

确定性查表，不让模型猜代码值。精确匹配会同时比对 name 与 aliases；fuzzy=True 走子串匹配，最多返回 10 条（防止工具输出撑爆上下文）。

`customs_validate` — 格式与跨字段校验

customs_validate(fields_json="{...完整提取结果...}")

纯计算，无外部调用。返回：

{
  "passed": true,
  "errors": [],
  "cross_issues": [],
  "summary": {
    "total_fields": 83,
    "failed": 0,
    "cross_issues": 0,
    "by_severity": { "P0": 0, "P1": 0, "P2": 0, "P3": 0 }
  }
}

passed 的判定是 P0 与 P1 均为 0——P2/P3 不影响通过。

字段全集（83 个）

表头 56 个 + 表体 27 个。按组路由，处理哪组才加载哪组的规则说明：

组	字段数	主题
1+2 身份信息	14	备案、企业主体、检验检疫编码
5 运输	9	运输方式、提单号、启运港
7 成交条件	8	成交方式、运保费、杂费
8 货物规格	5	件数、包装、毛/净重
9 集装箱	3	箱号、规格、项号关系
10 目的地	5	贸易国别、目的地
11 监管	6	监管方式、征免、随附单证
12 确认事项	6	价格确认、标记唛码
表体基础	14	商品明细（每行）
表体·食品	7	食品进口特殊字段
表体·危险品	6	危险品特殊字段

食品组与危险品组是条件激活的：HS 编码监管条件含 A/B 才加载食品组，出现 MSDS 且第十四部分有危险品分类才加载危险品组。

校验规则全表

格式校验

字段	规则	报错原文	级别
商品编号(HSCODE)	`^\d{10}$`	HS编码必须为10位纯数字	P0
境内收发货人-18位社会信用代码	`^[0-9A-Z]{18}$`	统一社会信用代码必须为18位字母数字	P0
境内收发货人-10位海关编码	`^\d{10}$`	海关编码必须为10位纯数字	P0
消费使用单位-10位海关编码	`^(\d{10}\|NO)$`	海关编码必须为10位纯数字或’NO’	P1
运输方式	`^[25]$`	运输方式代码必须为2(海运)或5(空运)	P0
净重 / 毛重	`^\d+(\.\d+)?$`	净重必须为纯数字	P0
件数	`^\d+$`	件数必须为正整数	P0
进口日期 / 启运时间	`^\d{8}$` + 真实日历校验	日期格式必须为YYYYMMDD 8位数字	P1
成交方式	`^(CIF\|FOB\|C&F\|EXW\|C&I)$`	成交方式必须为CIF/FOB/C&F/EXW/C&I之一	P1
运费方式 / 保费方式	`^[123]$`	运费方式必须为1(率)/2(单价)/3(总价)	P1
征免性质	`^\d{3}$`	征免性质必须为3位数字代码	P1
备案号	`^[A-Z]\d{11}$`	备案号首位大写字母+11位数字(共12位)	P1
包装种类	`^\d{2}$`	包装种类必须为2位数字代码	P1
集装箱规格	8 种标准选项枚举	集装箱规格必须是8种标准选项之一	P2

日期不只看位数：年份限 1900–2099，月份 1–12，日按 calendar.monthrange 取该年该月真实天数，所以 20250230 会报「日期30超出2025年2月最大天数28」。

跨字段一致性

检查项	触发条件	报错原文	级别
净重≤毛重	两者都有值且净重 > 毛重	净重(N)大于毛重(M)	P0
海运FCL必填集装箱号	运输方式=2 且提单号含 CY 且无箱号	海运整箱(CY)场景下集装箱号为必填	P0
CIF/C&F运费留空	成交方式为 CIF/C&F 但运费方式有值	成交方式为CIF时运费方式应留空，当前值=X	P1
CIF保费留空	成交方式为 CIF 但保费方式有值	成交方式为CIF时保费方式应留空，当前值=X	P1
备案号首字母与监管方式匹配	B/C 应对应加工贸易，Z 应对应一般贸易	备案号首字母B通常对应[‘来料加工’,…]，当前监管方式=X	P2
空运无集装箱	运输方式=5 但集装箱号有值	运输方式为空运(5)时集装箱号应留空	P2

边界与失败态

customs_validate 不检查必填。空值直接跳过校验并按 P3 通过——它回答的是「填了的对不对」，不是「该填的填了没」。缺字段要靠提取阶段的清点环节发现，别指望校验兜底。

其余边界：

跨字段检查只跑表头。表体逐行只做格式校验，行间关系不检查。
customs_code_lookup 模糊搜索最多 10 条，超出静默截断，返回的 count 是截断后的数量。
未知代码表名返回 {"error": "未知代码表 'X'", "available_tables": [...]}，不会抛异常。
大票建议拆会话。提取按 Phase 拆分：Phase A 做表头 56 字段，Phase B 做表体；表体 ≥8 行时建议开新会话，否则上下文会被单据原文吃满。

排错

症状	原因	处理
`OCR 服务超时（120s），请尝试减少页数或检查服务状态`	多页 PDF 在 CPU 上跑满 120 秒	用 `pages="1-3"` 分批识别
`无法连接 OCR 服务 http://profy-ocr:8001`	OCR 服务未就绪或 `CUSTOMS_OCR_URL` 配错	联系管理员确认服务状态
`OCR 服务返回 HTTP 4xx/5xx: ...`	文件 URL 不可达或格式不支持	确认文件已上传成功、是 PDF/PNG/JPG
`代码表 'supervision-methods' 为空或文件不存在`	代码表文件未随镜像分发到工具期望的路径	见下方说明
`输入 JSON 解析失败: ...`	传给 `customs_validate` 的不是合法 JSON	检查是否误传了 markdown 代码块围栏

已知缺陷（核对于 2026-08-11）：customs_code_lookup 读取代码表的路径是插件目录下的 data/code-tables/，而实际代码表文件位于 skills/customs-extraction/assets/code-tables/。路径不一致时该工具对五张表都会返回 代码表 'X' 为空或文件不存在。规避方式是直接问模型（技能文档里带了常用代码），或在提取流程中依赖技能自带的映射表而非该工具。

结果去哪了

最终 JSON 会由 Core 在对话 complete 时写入 message.metadata.declaration，映射为预览契约 {basic, fields, goods, ...}。这是插件与产品之间的持久化契约——前端报关单预览面读的就是它。

验证你的配置

勾选插件后，先做一次不带文件的代码查询：「一般贸易的监管方式代码是什么」。若返回 代码表 ... 为空或文件不存在，说明命中了上面的已知缺陷。
传一份单页发票，说「只提取表头身份信息组」。应该看到 OCR 卡片展开、字段带 page 与 confidence。
拿提取结果说「帮我校验」。应看到校验卡片给出 by_severity 统计——这一步返回 passed: true 才算链路通。

插件总览

28 个内置插件的定位与激活方式

技能

技能如何按需加载，为什么不一次性塞满上下文

核对日期 2026-08-11。来源：services/agent-runtime/src/plugins/builtin/customs/plugin.json、tools/customs_ocr.py、tools/customs_code_lookup.py、tools/customs_validate.py、skills/customs-extraction/SKILL.md。

开始使用

核心概念

使用指南

平台与账户

深入了解

报关单智能提取

报关单智能提取（profy-customs）

启用方式

快速开始

三个工具

`customs_ocr` — 版面级文字识别

`customs_code_lookup` — 海关代码表查询

`customs_validate` — 格式与跨字段校验

字段全集（83 个）

校验规则全表

格式校验

跨字段一致性

边界与失败态

排错

结果去哪了

验证你的配置

相关页面

插件总览

技能

​报关单智能提取（profy-customs）

​启用方式

​快速开始

​三个工具

​customs_ocr — 版面级文字识别

​customs_code_lookup — 海关代码表查询

​customs_validate — 格式与跨字段校验

​字段全集（83 个）

​校验规则全表

​格式校验

​跨字段一致性

​边界与失败态

​排错

​结果去哪了

​验证你的配置

​相关页面

插件总览

技能

报关单智能提取（profy-customs）

启用方式

快速开始

三个工具

`customs_ocr` — 版面级文字识别

`customs_code_lookup` — 海关代码表查询

`customs_validate` — 格式与跨字段校验

字段全集（83 个）

校验规则全表

格式校验

跨字段一致性

边界与失败态

排错

结果去哪了

验证你的配置

相关页面