Customs Declaration Extraction (profy-customs)

Turn trade paperwork — contracts, commercial invoices, bills of lading, packing lists, bonded-zone manifests — into a customs declaration JSON where every field is traceable and machine-checkable. Each field carries value, reason, confidence, and page, so you can see which sentence on which page produced it instead of receiving a pile of numbers you have no way to audit.

This is a vertical-domain plugin, not a general OCR wrapper. It ships China Customs field definitions, the five standard code tables, cross-field consistency rules, and a set of disambiguation decision trees. General OCR gives you text; this gives you declarable fields.

Enabling it

profy-customs is user_selectable: true — you must tick it in the plugin panel for a conversation. It never joins on its own. Its activation block contains only user_selectable. There is no requires and no conditions, which means once selected it works in any sandbox mode. It does not need Desktop, and it does not need a browser.

"activation": { "user_selectable": true }

Compare this with the three MCP bridge plugins (Blender / Godot / Photoshop), which additionally gate on desktop_connected: true. Customs has no such gate — it is pure server-side computation plus one HTTP call to the OCR service.

Quick start

Upload the documents, then say:

Extract the customs declaration from these documents

The skill routes on intent before doing anything else:

What you want	How to phrase it	Path taken
Full extraction	”Extract the customs declaration”	Step 1 → Step 7, the complete pipeline
Ask about a field rule	”How should 成交方式 (trade terms) be filled?”	Loads only that field group’s reference
Validate existing JSON	”Validate this declaration JSON”	Calls `customs_validate` directly
Look up a code	”What is the supervision method code for general trade?”	Calls `customs_code_lookup` directly

Routing on intent matters because the full pipeline is expensive. A question about one field should not trigger a seven-step extraction.

The three tools

`customs_ocr` — layout-aware text recognition

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

Calls the self-hosted RapidOCR service over HTTP. It never runs OCR in-process — that constraint keeps the agent runtime free of heavyweight vision dependencies and lets OCR scale independently. Returns, per page:

Field	Meaning
`page`	Page number, 1-based
`width` / `height`	Page dimensions in pixels
`texts[]`	Each entry has `text`, `bbox([x1,y1,x2,y2])`, `score`
`blocks[]`	Layout blocks, `type` is one of `table` / `text` / `title`
`markdown`	The page rendered as markdown, with tables converted to md tables

bbox is the reason this tool exists. Most of the information on a customs document lives inside tables, and a flat text stream loses “which column does this number belong to”. Coordinates let the extraction step reconstruct the table structure. Service endpoint is controlled by CUSTOMS_OCR_URL, defaulting to http://profy-ocr:8001. Requests go to /ocr/parse with a 120-second per-request timeout.

`customs_code_lookup` — standard code tables

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

Five standard tables ship with the plugin:

`table` value	Domain
`supervision-methods`	Supervision method (监管方式)
`transport-modes`	Mode of transport (运输方式)
`trade-terms`	Trade terms / Incoterms (成交方式)
`packaging-types`	Packaging type (包装种类)
`insurance-modes`	Insurance mode (保险方式)

This is a deterministic lookup — the design intent is that the model never guesses a code value. Exact matching compares against both name and any aliases on the entry. Setting fuzzy=True switches to substring matching over the serialized entry and returns at most 10 results, a hard cap that keeps tool output from flooding the context window.

`customs_validate` — format and cross-field checks

customs_validate(fields_json="{...full extraction result...}")

Pure computation, no external calls. Response shape:

{
  "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 is computed as P0 count == 0 AND P1 count == 0. P2 and P3 findings are reported but do not block. The severity ladder maps to real customs rejection risk: P0 means the declaration will be rejected, P1 means it likely will, P2 is a consistency smell worth a human look, P3 is informational.

The full field set (83 fields)

56 header fields plus 27 body fields. Fields are grouped, and the skill loads only the reference for the group it is currently working on:

Group	Fields	Subject
1+2 Identity	14	Filing number, corporate entities, inspection & quarantine codes
5 Transport	9	Mode of transport, B/L number, port of departure
7 Trade terms	8	Incoterms, freight and insurance, miscellaneous charges
8 Cargo spec	5	Package count, packaging, gross / net weight
9 Container	3	Container number, size type, item-number relations
10 Destination	5	Trading country, destination
11 Supervision	6	Supervision method, duty exemption, accompanying documents
12 Confirmation	6	Price confirmation items, marks and numbers
Body — basic	14	Commodity line items, per row
Body — food	7	Food import specific fields
Body — hazard	6	Dangerous goods specific fields

The food and hazard groups are conditionally activated. Food fields load when the HS code’s regulatory conditions include A or B; hazard fields load when an MSDS is present and its section 14 carries a dangerous goods classification. Loading all groups unconditionally would waste context on the majority of shipments that are neither.

Scenario detection

Before extracting anything, the skill classifies the shipment, because the same field means different things across scenarios:

Signal in the documents	Scenario	Consequence
A bonded-zone manifest exists, or filing number starts with B/C/Z	Bonded / special supervision zone	Most fields prefer the manifest as source; declaring customs office takes the last 4 digits of the QD number
B/L contains AWB / HAWB / MAWB	Air freight	Transport mode = 5; B/L number is `master_awb_house_awb`; no container
B/L contains B/L No. / Vessel / CY / CFS	Ocean freight	Transport mode = 2; FCL vs LCL decides whether container number is mandatory
HS code is a food category (regulatory condition A/B)	Food import	Activates the food field group
MSDS present with a section 14 classification	Dangerous goods	Activates the hazard field group

Validation rules in full

Format validation

Field	Rule	Exact message	Severity
商品编号(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}$` plus real calendar check	日期格式必须为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
集装箱规格	Enum of 8 standard options	集装箱规格必须是8种标准选项之一	P2

Messages are emitted in Chinese because they mirror what a Chinese customs broker expects to read. Date validation goes beyond digit count: the year must fall in 1900–2099, the month in 1–12, and the day is bounded by calendar.monthrange for that specific year and month. So 20250230 fails with 日期30超出2025年2月最大天数28 rather than passing a naive regex.

Cross-field consistency

Check	Trigger	Exact message	Severity
Net ≤ gross weight	Both present and net > gross	净重(N)大于毛重(M)	P0
Ocean FCL requires container	Transport = 2, B/L contains CY, no container number	海运整箱(CY)场景下集装箱号为必填	P0
CIF/C&F freight must be blank	Trade term is CIF or C&F but freight mode has a value	成交方式为CIF时运费方式应留空，当前值=X	P1
CIF insurance must be blank	Trade term is CIF but insurance mode has a value	成交方式为CIF时保费方式应留空，当前值=X	P1
Filing prefix matches supervision	B/C should pair with processing trade, Z with general trade	备案号首字母B通常对应[‘来料加工’,…]，当前监管方式=X	P2
Air freight has no container	Transport = 5 but container number has a value	运输方式为空运(5)时集装箱号应留空	P2

These encode the arithmetic a customs broker does by hand. CIF already includes freight and insurance in the price, so declaring them separately double-counts — hence P1 rather than a warning.

How extraction is structured

Phase split

Phase	Scope	Context budget
A	Steps 1–5, the 56 header fields plus code mapping	One session
B	Steps 3–4, N body rows × 14 basic fields plus conditional groups	New session recommended when N ≥ 8

Three-tier context loading

Reference material is loaded and released deliberately rather than dumped up front:

Tier	File	Loaded	Released
L0	`CHEATSHEET.md`	Always, first	Kept until the end
L1	Group reference (11 files)	When handling that group	After writing the lock
L1	`decision-trees.md`	On ambiguity	Immediately after use
L2	`rag-label-mapping.md`	Step 5, code mapping	After mapping
L2	`anti-patterns.md`	Step 6, validation	After validation
Lock	`extraction_lock.json`	Read before each group, written after	Held through Step 7

The lock file is what makes long extractions survivable. Committed field values are written to disk, so a session that runs long does not have to keep every intermediate result in the context window, and a resumed session picks up where the previous one stopped.

Ten disambiguation decision trees

Situation	Tree	Typical ambiguity
No explicit transport marking	DT-1	Default to ocean, lower the confidence
Multiple B/L numbers	DT-2	Master + house, same carrier multi-lot, different carriers
Trade term outside the standard 5	DT-3	CIP→CIF, CFR→C&F, D-group→CIF
Contract number conflicts with invoice	DT-4	Contract wins
English-only company name	DT-5	Do not translate; trigger a registry lookup
Transshipment	DT-6	Country of departure ≠ trading country
Consumer / end-user backfill	DT-7	No agency agreement → copy the domestic consignee
Bonded-zone filing number	DT-8	Manifest present → extract, absent → leave blank
Container size type	DT-9	20GP→S, 40HC→L
Duty exemption	DT-10	Derived from the supervision method

Each tree resolves to a deterministic choice plus a confidence adjustment, which is why the output carries confidence per field rather than one number for the document.

Boundaries and failure modes

customs_validate does not check for required fields. An empty value short-circuits validation and returns as passing at P3. The tool answers “is what you filled in correct”, not “did you fill in everything you had to”. Missing fields must be caught during the extraction inventory step — do not treat validation as a safety net for completeness.

Other boundaries worth knowing before you rely on this in production:

Cross-field checks only run over header fields. Body rows get per-field format validation only; relationships between rows are not checked.
Fuzzy lookup truncates silently at 10 results. The returned count is the post-truncation count, so it cannot be used to detect that truncation happened.
An unknown table name returns a structured error, {"error": "未知代码表 'X'", "available_tables": [...]}, rather than raising. All three tools return errors as JSON — they never throw into the agent loop.
Large consignments should be split across sessions. Beyond roughly 8 body rows, the raw document text alone will dominate the context window.

Troubleshooting

Symptom	Cause	Fix
`OCR 服务超时（120s），请尝试减少页数或检查服务状态`	Multi-page PDF exceeded the 120s CPU budget	Split with `pages="1-3"`
`无法连接 OCR 服务 http://profy-ocr:8001`	OCR service not ready, or `CUSTOMS_OCR_URL` misconfigured	Ask your administrator to check the service
`OCR 服务返回 HTTP 4xx/5xx: ...`	File URL unreachable, or unsupported format	Confirm the upload succeeded and the file is PDF/PNG/JPG
`代码表 'supervision-methods' 为空或文件不存在`	Code table files are not at the path the tool reads	See the known defect below
`输入 JSON 解析失败: ...`	The argument passed to `customs_validate` is not valid JSON	Check for stray markdown code fences

Known defect (verified 2026-08-11): customs_code_lookup resolves code tables from data/code-tables/ under the plugin directory, but the files actually ship at skills/customs-extraction/assets/code-tables/. While the paths disagree, all five tables return 代码表 'X' 为空或文件不存在. Work around it by asking the model directly — the skill references carry the common codes — rather than relying on this tool.

Where the result goes

The final JSON is written by Core into message.metadata.declaration when the conversation reaches complete, mapped to the preview contract {basic, fields, goods, ...}. This is the persistence contract between the plugin and the product: the declaration preview panel in the UI reads exactly this. Do not invent parallel field names such as draftResult or declarationForm — nothing downstream reads them.

Verify your setup

With the plugin ticked, run a lookup with no file attached: “What is the supervision method code for general trade?” A response of 代码表 ... 为空或文件不存在 means you have hit the known defect above.
Upload a single-page invoice and say “extract only the identity field group”. You should see the OCR card expand, and each field should carry page and confidence.
Feed the extraction result back with “validate this”. The validation card should render a by_severity breakdown — passed: true here is the signal that the whole chain works.

Plugin overview

All 28 built-in plugins and how they activate

Skills

How skills load on demand instead of filling the context up front

Verified 2026-08-11. Sources: 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.

Get Started

Core Concepts

Guides

Platform & Account

Deep Dive

Customs Declaration Extraction

Customs Declaration Extraction (profy-customs)

Enabling it

Quick start

The three tools

`customs_ocr` — layout-aware text recognition

`customs_code_lookup` — standard code tables

`customs_validate` — format and cross-field checks

The full field set (83 fields)

Scenario detection

Validation rules in full

Format validation

Cross-field consistency

How extraction is structured

Phase split

Three-tier context loading

Ten disambiguation decision trees

Boundaries and failure modes

Troubleshooting

Where the result goes

Verify your setup

Plugin overview

Skills

​Customs Declaration Extraction (profy-customs)

​Enabling it

​Quick start

​The three tools

​customs_ocr — layout-aware text recognition

​customs_code_lookup — standard code tables

​customs_validate — format and cross-field checks

​The full field set (83 fields)

​Scenario detection

​Validation rules in full

​Format validation

​Cross-field consistency

​How extraction is structured

​Phase split

​Three-tier context loading

​Ten disambiguation decision trees

​Boundaries and failure modes

​Troubleshooting

​Where the result goes

​Verify your setup

​Related

Plugin overview

Skills

Customs Declaration Extraction (profy-customs)

Enabling it

Quick start

The three tools

`customs_ocr` — layout-aware text recognition

`customs_code_lookup` — standard code tables

`customs_validate` — format and cross-field checks

The full field set (83 fields)

Scenario detection

Validation rules in full

Format validation

Cross-field consistency

How extraction is structured

Phase split

Three-tier context loading

Ten disambiguation decision trees

Boundaries and failure modes

Troubleshooting

Where the result goes

Verify your setup

Related