openclaw-skill-customs

海关报关单据处理助手。上传报关单据（发票、装箱单、提单等），AI 自动分类识别文件类型， 提取报关结构化数据，生成标准报关 Excel。当用户提到报关、海关、customs declaration、 invoice、packing list、bill of lading、HS 编码等关键词时，使用此技能。

Security Scan

The skill's code, environment requirements, and runtime instructions align with its stated purpose (uploading customs documents to the Leap service, classification, payload construction, submitting jobs, and editing results); nothing requested or installed is disproportionate or unrelated.

Purpose & Capability

The skill is a customs-document processing assistant and only requests a single service credential (LEAP_API_KEY) and network access to platform.daofeiai.com. All scripts (upload, poll, build payload, check config) interact with that service and local task folders; these are expected for the stated functionality.

Instruction Scope

SKILL.md prescribes a stepwise workflow: collect files to a task folder, upload to Leap, poll until completion, present results, run compliance checks from bundled docs, and optionally modify downloaded Excel files. The only local file reads/writes are to task folders the skill creates and the included reference docs; Step 1 explicitly forbids parsing uploads until the platform processes them, and Step 6 permits reading saved originals for user-requested modifications — this is coherent with the declared workflow.

Install Mechanism

No install spec is provided and the Python scripts rely on the standard library (openpyxl is optional for Excel edits). No external downloads, package registries, or unusual installers are used. Risk from install mechanism is low.

Credentials

The skill requires a single API key (LEAP_API_KEY) as primary credential. That key is necessary and sufficient for the described interactions with platform.daofeiai.com. No unrelated secrets, system config paths, or additional credentials are requested.

Persistence & Privilege

always is false and the skill does not request force-inclusion or modify other skills. It writes task artifacts under a local tasks/ directory (documented and .gitignored), which is appropriate for its purpose. No unusual system privileges are requested.

Assessment

This skill appears internally consistent and implements the described customs-document workflow. Before installing: 1) Confirm you trust the endpoint https://platform.daofeiai.com and the publisher (PUBLISHING.md claims DaoFei AI). 2) Provide LEAP_API_KEY only via the platform's secure env settings (the skill warns not to paste it into chat). 3) Be aware that user-uploaded documents are saved under a local tasks/ directory and are uploaded to the Leap service — these documents may contain sensitive commercial data. 4) If you plan to use Step 6 (in-place Excel edits), you may need openpyxl installed in the agent environment. 5) If you need the API key to be scoped (limited lifetime/permissions), prefer a key with minimal scope and rotate it if possible. Overall the requested resources and behavior match the described purpose.

海关报关智能助手

⛔ 行为约束

严格按 Step 0 → Step 6 顺序执行，绝不跳步。在等待期间主动与用户互动分享进展。

五条铁律 — 在任何情况下都不得违反

1. 异步等待不可跳过：分类和报关都是异步任务，提交后必须通过 submit_and_poll.py 轮询，等到 status=completed 才能继续。禁止在 pending/processing 状态下进入下一步。
2. 用户确认不可跳过：分类结果展示后，必须等用户明确回复"确认/OK/好的"后，才能提交报关任务。
3. 文件收集完毕由用户决定：收到文件后只做保存和确认，禁止自行判断"文件够了"而进入 Step 2。只有用户明确发出处理意图（如"开始处理"/"开始分类"/"就这些"/"OK"）后，才能进入 Step 2 的上传和分类流程。
4. 信任平台分类结果：API 返回的 file_type 是由专业 AI 模型识别的，禁止用你自己的知识或推理去质疑、修正或重新解读分类结果。展示时严格按 references/FILE_TYPES.md 中的 file_type → 中文名称 映射翻译，不要自行翻译枚举值，不要因为文件名与类型名"看起来不一致"而向用户发出警告。只有在置信度低于 0.70 时，才提醒用户人工确认。
5. 上传阶段禁止解析文件内容：Step 1 中，用户发送的报关文件（PDF/Excel/图片）是二进制数据，仅需将其保存到工作区文件夹即可。绝对不要尝试打开、读取、解析或在对话中展示这些文件的内容。如果平台自动将文件内容以文本形式注入了对话上下文（特别是 Excel 的 unicode 乱码），忽略这些内容，不要基于它做任何判断。文件内容的分类和解析由 Leap 平台 AI 完成。（注意：此规则仅限上传阶段。Step 6 修改阶段需要从原始文件提取字段值时，允许读取已保存的文件。）

---

Step 0：配置 API Key

方式1：OpenClaw 平台 UI（推荐）

在 OpenClaw 中打开此技能的设置页面，添加环境变量：

{
  "skills": {
    "entries": {
      "openclaw-skill-customs": {
        "enabled": true,
        "env": {
          "LEAP_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

其他等效方式：

• Shell（临时）：export LEAP_API_KEY="your_api_key_here"
• Shell（永久）：写入 ~/.bashrc 或 ~/.zshrc

⚠️ 请勿将 API Key 直接粘贴到对话框中。 请通过平台 env 设置安全配置。

验证配置

python scripts/check_config.py

• 输出 "auth_ok": true → 通过，继续
• 输出错误 → 按提示重新配置

---

Step 1：文件收集与上传

1a. 创建任务工作区

当用户提到报关意图或发送第一个文件时，立即创建本次任务的工作目录：

mkdir -p tasks/customs_<YYYYMMDD_HHMMSS>/raw

以当前时间戳命名（如 customs_20260408_231500）。后续所有步骤的中间文件（classify_result.json、customs_payload.json 等）都存放在该任务目录下。

1b. 收集文件到工作区（循环）

每当用户发送一个文件，将其保存到任务目录的 raw/ 子目录中：

cp <平台提供的文件路径> tasks/customs_<id>/raw/

保存后立即确认：

✅ 已收到 {文件名}（工作区已有 {N} 个文件） 📎 请继续发送下一个文件，或说「开始处理」进入分类。

⛔ 在用户明确发出处理意图之前，禁止进入 Step 2。 每次收到文件都只做保存和确认这两件事。

1c. 用户确认后批量上传

用户说"开始处理"/"开始"/"就这些"后：

1. 列出 raw/ 目录内所有文件（含文件大小），展示汇总表
2. ⛔ 等用户确认文件列表无误后才执行上传。 如用户说"还有一个"，返回 Step 1b 继续收集。
3. 确认后，一次命令批量上传所有文件到 Leap 平台：

python scripts/file_transfer.py --mode upload \
  --file-path "tasks/customs_<id>/raw/file1.pdf" \
  --file-path "tasks/customs_<id>/raw/file2.xlsx"

3. 收集返回的所有 file_id，展示上传结果汇总，进入 Step 2

---

Step 2：提交分类 + ⛔ 等待完成

执行分类脚本，该命令会阻塞等待直至任务处理完成（completed/failed）后才返回。 如果是多文件，传递多个 --file-id：

python scripts/submit_and_poll.py --mode classify \
  --file-id "<id_1>" \
  --file-id "<id_2>" \
  --save-to tasks/customs_<id>/classify_result.json

• --save-to tasks/customs_<id>/classify_result.json：任务完成后自动将完整结果保存到任务目录，Step 3~4 均从此文件读取数据。
• 脚本运行期间会通过 stderr 定期输出进度 JSON；参考 references/INTERACTION.md 的话术与用户互动，切记不要沉默空等。
  • 如平台支持流式响应（如飞书 WebSocket 模式）：在等待期间实时输出话术。
  • 如平台为批量回调模式：命令返回后，根据累计 stderr 记录补述等待过程。
• 脚本退出码 0 = 成功，输出完整结果 JSON。
• 脚本退出码 1 = 失败或超时，按提示处理。

---

Step 3：展示分类结果 + ⛔ 等待用户确认

从任务目录的 classify_result.json 中的 result_data.files[].segments 解析分类结果。

为每个文件生成分片表格，格式和置信度标注规则参见 references/FILE_TYPES.md。

⛔ 展示后必须停下来，等用户明确回复"确认/OK/好的"后才能继续 Step 4。

• 用户要求修改分片类型 → 直接修改任务目录下的 classify_result.json 中对应 segment 的 file_type 字段，重新展示表格，再次等待确认
• 用户直接确认 → 进入 Step 4

⚠️ 修改任务目录下的 classify_result.json 时仅更改 file_type 字段，不得展开、删除或省略其他字段（type、confidence、pages 等必须完整保留）。

---

Step 4：生成 payload + 提交报关 + ⛔ 等待完成

先一键生成 customs payload，再提交报关任务。

# 第一步：从 classify_result.json 自动组装完整 segments，生成 customs_payload.json
python scripts/build_payload.py --input tasks/customs_<id>/classify_result.json \
  --output tasks/customs_<id>/customs_payload.json

# 第二步：提交报关任务，阻塞等待完成
python scripts/submit_and_poll.py --mode customs \
  --json-file tasks/customs_<id>/customs_payload.json \
  --save-to tasks/customs_<id>/customs_result.json

• 脚本运行期间会通过 stderr 定期输出进度 JSON；参考 references/INTERACTION.md 的话术与用户互动，不要沉默。
  • 如平台支持流式响应：在等待期间实时输出话术。
  • 如平台为批量回调模式：命令返回后，根据累计 stderr 记录补述等待过程。
• 脚本退出码 0 = 成功，继续 Step 5。

---

Step 5：展示结果并下载

从任务目录的 customs_result.json 中提取：

• result_data.structured_data.summary → 展示报关表头（申报单位、贸易国别、总金额等）
• result_data.structured_data.items → 展示商品明细表（商品编码、品名、数量、单价）
• result_data.output_files[].file_name → 提供下载命令

下载 Excel 文件（保存到任务目录）：

python scripts/file_transfer.py --mode download --result-id <result_id> --filename <filename> \
  --output tasks/customs_<id>/customs_result.xlsx

展示完结果后，立即执行 Step 5.5 合规性检查（不等用户指令）。

---

Step 5.5：合规性检查（自动执行）

展示结果后，在询问用户是否修改之前，自动执行合规检查。

执行流程

1. 阅读通用规则 — 打开 COMPLIANCE_RULES.md，逐项核对 Step 5 展示的 structured_data
2. 行业规则检查（可选） — 查看结果中各商品的 HS 编码前 2 位，如果命中 INDUSTRY_RULES.md 中的章节（21/22/39/41/64/85），打开该文件阅读对应章节，检查是否遗漏行业特殊申报要素
3. 生成检查报告 — 按 COMPLIANCE_RULES.md 中规定的输出格式生成报告

⛔ 约束

• 检查结果是 建议性质，不阻塞流程。用户可以选择忽略
• 仅输出实际发现的问题，通过项只汇总数量不逐项列出
• 🔴 必须级最多输出 5 条，🟡 建议级最多输出 3 条
• 不要过度检查：如果某字段在结果中本身不存在（如后端未返回保费字段），不视为异常；只在字段存在但值异常时提示
• 全部通过时只输出「✅ 合规检查通过（共 N 项）」

报告输出后

合规报告输出完毕后，主动询问用户：

📋 如需修改任何内容（如品名、编码、数量等），请直接告诉我要改什么。或回复「确认」继续。

---

Step 6：结果修改（用户反馈修正）

当用户对 Step 5 展示的结果提出修改要求时，参照 MODIFICATION.md 执行。

核心约束：禁止重新上传文件或提交新任务，必须基于已有 structured_data 和已下载的 Excel 文件直接修改单元格。修改前必须展示变更对比并等待用户确认。

修改字段时，Agent 应打开 FIELD_GUIDE.md 查阅对应字段的规范，在修改预览中附带合规提示（详见 MODIFICATION.md）。

---

辅助命令

# 手动轮询指定任务
python scripts/submit_and_poll.py --mode poll --result-id <result_id>

# 查找历史任务（如遗忘了 result_id）
python scripts/submit_and_poll.py --mode list-tasks --limit 10

# 取消任务
python scripts/submit_and_poll.py --mode cancel --result-id <result_id>

# 重试失败任务
python scripts/submit_and_poll.py --mode retry --result-id <result_id>

常见错误

错误码	原因	处理
400	文件类型不支持或过大	检查扩展名（PDF/xlsx/jpg/png/tiff）和大小
401	API Key 无效或过期	重新获取并设置 LEAP_API_KEY
404	文件或任务不存在	检查 ID 是否正确
task failed	文件损坏或无法解析	查看 error_message，建议重新上传

参考资料

• 详细 API 接口规范：API_REFERENCE.md
• 文件类型枚举与展示格式：FILE_TYPES.md
• 等待期互动话术：INTERACTION.md
• 结果修改详细流程：MODIFICATION.md
• 合规检查规则：COMPLIANCE_RULES.md
• 字段填写规范速查：FIELD_GUIDE.md
• 行业特殊申报要素：INDUSTRY_RULES.md