openclaw-skill-customs

# 海关报关智能助手

## ⛔ 行为约束

严格按 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 中打开此技能的设置页面，添加环境变量：

```json
{
  "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 设置安全配置。

### 验证配置

```bash
python scripts/check_config.py
```
- 输出 `"auth_ok": true` → 通过，继续
- 输出错误 → 按提示重新配置

---

## Step 1：文件收集与上传

### 1a. 创建任务工作区

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

```bash
mkdir -p tasks/customs_<YYYYMMDD_HHMMSS>/raw
```

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

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

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

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

保存后立即确认：

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

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

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

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

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

```bash
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`：

```bash
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，再提交报关任务。**

```bash
# 第一步：从 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 文件（保存到任务目录）：
```bash
python scripts/file_transfer.py --mode download --result-id <result_id> --filename <filename> \
  --output tasks/customs_<id>/customs_result.xlsx
```

展示完结果后，**主动询问用户**：
> 📋 以上是本次报关提取结果，如需修改任何内容（如品名、编码、数量等），请直接告诉我要改什么，我会帮你修正并重新生成 Excel。

---

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

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

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

---

## 辅助命令

```bash
# 手动轮询指定任务
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](references/API_REFERENCE.md)
- 文件类型枚举与展示格式：[FILE_TYPES.md](references/FILE_TYPES.md)
- 等待期互动话术：[INTERACTION.md](references/INTERACTION.md)
- 结果修改详细流程：[MODIFICATION.md](references/MODIFICATION.md)