⚠️ 使用前必读：需要 API 密钥

本技能需要 HSCIQ API 密钥才能正常工作。

获取 API 密钥

1. 访问 https://www.hsciq.com
2. 注册账号并登录
3. 在控制台申请 API 密钥
4. 将密钥配置到本地（见下方"配置"章节）

没有 API 密钥将无法查询海关编码。

---

HSCIQ MCP - 海关编码查询服务

专业的中国商品海关编码查询与归类服务，基于 HSCIQ MCP API。

功能

• search_code - 按关键词搜索海关编码（支持中国/日本/美国）
• get_code_detail - 获取海关编码详情（税率、申报要素、监管条件等）
• search_instance - 按商品名称检索归类实例（输入具体商品名如"自行车"、"手机壳"，非描述性短语）
• search_unified - 统一搜索（CIQ 项目/危化品/港口信息）
• create_guilei_form - 创建 HS 归类咨询单（需上传至少 1 张产品图片，提交给平台专业归类师人工审核，可选 categoryId 指定行业分类）
• get_guilei_form - 获取归类咨询单详情（含字段对话、归类结论、修改历史）
• list_my_guilei_forms - 获取当前用户的归类咨询单分页列表
• add_guilei_dialog_message - 在归类单字段上创建新讨论或回复已有讨论
• list_guilei_categories - 获取可用的行业分类列表（用于创建归类咨询单时选择 categoryId）

触发条件

用户提到以下关键词时自动触发：

• "海关编码"、"HS 编码"、"税号"、"商品编码"
• "查询税率"、"申报要素"、"监管条件"
• "CIQ"、"危化品"、"港口代码"
• "归类实例"、"商品归类"
• "归类咨询"、"人工复核"、"提交审核"、"专家确认"、"帮我提交归类"
• "我的咨询单"、"咨询详情"、"咨询回复"、"归类结果"
• "行业分类"、"分类列表"、"categoryId"、"归类分类"

配置

配置文件位于 ~/.openclaw/workspace/hsciq-mcp-config.json：

{
  "baseUrl": "https://www.hsciq.com",
  "apiKey": "your_api_key",
  "authHeader": "X-API-Key"
}

注意：API Key 也可以通过环境变量设置：

export HSCIQ_API_KEY=your_api_key
export HSCIQ_BASE_URL=https://www.hsciq.com

命令

# 搜索海关编码
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js search-code --keywords "塑料软管" --country CN

# 获取编码详情
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js get-detail --code "3926909090" --country CN

# 搜索归类实例
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js search-instance --keywords "自行车" --country CN

# 统一搜索（CIQ/危化品/港口）
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js search-unified --keywords "食品" --type ciq

# 创建归类咨询单（AI 自动提交人工复核）
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js create-guilei-form \
  --productNameCn "智能手机壳" \
  --uses "手机保护" \
  --ingredients "硅胶" \
  --images ./front.jpg ./back.jpg

# 获取归类咨询单详情
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js get-guilei-form --formId "abc123..."

# 查看我的归类咨询单列表
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js list-my-guilei-forms --pageIndex 1 --pageSize 20

# 在归类单上发起讨论或回复
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js add-guilei-dialog-message \
  --formId "abc123..." \
  --fieldKey "ProductNameCn" \
  --content "请问这个产品的材质是什么？"

# 获取行业分类列表（用于创建归类咨询单时选择 categoryId）
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js list-guilei-categories

# 创建归类咨询单并指定行业分类
node ~/.openclaw/skills/hsciq-mcp/hsciq-client.js create-guilei-form \
  --productNameCn "智能手机壳" \
  --categoryId 5 \
  --uses "手机保护" \
  --images ./front.jpg

使用示例

示例 1: 查询商品的海关编码

用户：帮我查一下"塑料软管"的海关编码
→ 调用 search_code，返回编码列表和税率信息

示例 2: 获取编码详情

用户：3926909090 这个编码的税率是多少
→ 调用 get_code_detail，返回完整税率、申报要素、监管条件

示例 3: 搜索归类实例

用户：看看别人是怎么归类"蓝牙耳机"的
→ 调用 search_instance，输入商品名称关键词"蓝牙耳机"（非短语），返回历史归类案例

示例 4: AI 拿不准时提交人工复核

用户：帮我查一下这个产品的 HS 编码，我不太确定 AI 给的结果对不对
→ AI 在用 search_code 查询后，如果用户对结果有疑问
→ 调用 create_guilei_form，自动提交产品信息与图片，生成归类咨询单
→ 平台专业归类师审核后给出权威结论

示例 5: 查看归类咨询单结果

用户：我之前提交的归类咨询有结果了吗？
→ 调用 list_my_guilei_forms 获取用户的归类咨询单列表
→ 找到目标单后调用 get_guilei_form 获取详情（含归类结论、字段对话）

示例 6: 在归类单上追问

用户：之前在归类单上问过的问题，我想补充信息
→ 调用 add_guilei_dialog_message
→ 传入 formId + fieldKey + content，在指定字段上发起新讨论或回复已有讨论

API 端点说明

本技能使用标准 MCP 协议（JSON-RPC over Stateless Streamable HTTP），统一端点：

端点	说明
POST https://www.hsciq.com/mcp/rpc	标准 MCP 协议端点（initialize / tools/list / tools/call）

请求要求：

• 认证头：X-API-Key: <key> 或 Authorization: Bearer <key>
• 请求头：Accept: application/json, text/event-stream
• 响应为 SSE 格式（text/event-stream），取 data: 行的 JSON-RPC 结果
• Stateless 模式：每次请求独立，无需维持会话

tools/call 调用格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_code",
    "arguments": {
      "keywords": "塑料软管",
      "country": "CN",
      "pageIndex": 1,
      "pageSize": 10
    }
  }
}

响应格式：成功结果在 result.structuredContent.result（结构化数据），result.content[0].text 为同数据的 JSON 字符串；业务错误时 result.isError=true 且 content[0].text 为错误描述。

create_guilei_form 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_guilei_form",
    "arguments": {
      "productNameCn": "智能手机壳",
      "productNameEn": "Smartphone Case",
      "categoryId": 5,
      "uses": "手机保护",
      "ingredients": "硅胶",
      "brand": "某品牌",
      "model": "X1",
      "images": [
        { "fileName": "front.jpg", "data": "base64编码的图片数据..." }
      ]
    }
  }
}

图片要求：必填，至少 1 张，最多 3 张，每张 ≤ 1MB，支持 JPG/PNG/GIF/WebP；未上传图片将创建失败。每人每天最多创建 5 次（可配置）。

categoryId（可选）：行业分类 ID，通过 list_guilei_categories 获取可用分类列表；不指定时由归类师判断。

list_guilei_categories 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_guilei_categories",
    "arguments": {}
  }
}

返回可用的行业分类列表，如 [{"id": 1, "name": "分类名称"}, ...]，用于 create_guilei_form 的 categoryId 参数。

get_guilei_form 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_guilei_form",
    "arguments": { "formId": "00000000-0000-0000-0000-000000000001" }
  }
}

返回完整的归类咨询单详情，包含产品字段、字段对话、归类结论（如有）等信息。

list_my_guilei_forms 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_my_guilei_forms",
    "arguments": { "pageIndex": 1, "pageSize": 20 }
  }
}

返回当前用户的归类咨询单分页列表，包含表单状态、创建时间等摘要信息。

add_guilei_dialog_message 调用示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_guilei_dialog_message",
    "arguments": {
      "formId": "00000000-0000-0000-0000-000000000001",
      "fieldKey": "ProductNameCn",
      "content": "这个产品的准确材质是什么？",
      "dialogId": null,
      "messageType": null
    }
  }
}

• formId / fieldKey / content 为必填
• dialogId：不为空时回复已有对话；为空时新建对话
• messageType：可选的消息类型

API 文档

完整 API 说明：https://www.hsciq.com/MCP/Docs

Python 客户端

也可以使用 Python 脚本直接调用：

# 搜索海关编码
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py search-code --keywords "塑料软管" --country CN

# 获取编码详情
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py get-detail --code "3926909090"

# 搜索归类实例
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py search-instance --keywords "自行车"

# 统一搜索
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py search-unified --keywords "食品" --type ciq

# 创建归类咨询单
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py create-guilei-form \
  --productNameCn "智能手机壳" --uses "手机保护" --ingredients "硅胶" \
  --images ./front.jpg ./back.jpg

# 获取归类咨询单详情
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py get-guilei-form --formId "abc123..."

# 查看归类咨询单列表
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py list-my-guilei-forms --pageIndex 1

# 归类单讨论
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py add-guilei-dialog-message \
  --formId "abc123..." --fieldKey "ProductNameCn" --content "追问内容"

# 获取行业分类列表（用于 create-guilei-form 的 categoryId）
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py list-guilei-categories

# 创建归类咨询单并指定行业分类
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py create-guilei-form \
  --productNameCn "智能手机壳" --categoryId 5 --uses "手机保护" --images ./front.jpg

# 列出可用工具
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py list-tools

# JSON 输出（便于程序处理）
python3 ~/.openclaw/skills/hsciq-mcp/hsciq_client.py search-code --keywords "软管" --json

Python 代码集成

from hsciq_client import HSCIQClient

client = HSCIQClient()

# 搜索编码
result = client.search_code("塑料软管", country="CN")
print(result)

# 获取详情
detail = client.get_code_detail("3926909090")
print(detail)

# 创建归类咨询（图片为文件路径，客户端自动 base64 编码）
result = client.create_guilei_form(
    productNameCn="智能手机壳",
    uses="手机保护",
    ingredients="硅胶",
    images=["./front.jpg", "./back.jpg"]
)
print(result)

# 获取归类咨询单详情
form = client.get_guilei_form("00000000-0000-0000-0000-000000000001")
print(form)

# 查看归类咨询单列表
forms = client.list_my_guilei_forms(pageIndex=1, pageSize=20)
print(forms)

# 在归类单上追问
reply = client.add_guilei_dialog_message(
    formId="00000000-0000-0000-0000-000000000001",
    fieldKey="ProductNameCn",
    content="请确认这个产品的材质"
)
print(reply)

# 获取行业分类列表
categories = client.list_guilei_categories()
print(categories)

# 创建归类咨询并指定行业分类
result = client.create_guilei_form(
    productNameCn="智能手机壳",
    categoryId=5,
    uses="手机保护",
    images=["./front.jpg"]
)
print(result)