express-tracking · AI 快递助手台（DSH Java Native 插件场景案例 P55）

基于 deepseek-harness-java（DSH）Java Native 插件机制 的快递查寄场景案例：运单轨迹时间线（4 票样例含异常滞留）+ 运费估算（首重/续重/保价）+ 寄件下单（二次确认）+ 营业网点（距离/排队）+ 派送异常总览，通过 express-copilot 插件接入 AI 助手，支持自然语言查件、报价、下单、找网点、处理异常。

一、项目组成

模块	说明
e-app	Spring Boot 3.2 应用（端口 18094），快递查寄 REST API 与前端页面
e-plugin	DSH Java Native 插件（express-copilot），打包 5 个 AI 工具

业务数据：4 票运单（派送中/异常滞留/已签收/运输中，含完整轨迹时间线）、4 类产品价格表（标准快递/次日达/经济件/同城闪送）、5 个营业网点（距离/排队/可办业务）、异常件清单与处理建议。

二、插件工具（5 个）

工具	说明
track	查运单轨迹：收发地/类型/状态/签收人/轨迹时间线/异常说明
estimate	运费估算：首重/续重/保价费/合计/预计时效
order	寄件下单：生成 orderId + waybillNo + 费用 + 取件时间
branch	网点查询：名称/电话/营业时间/可办业务/距离/排队，按距离排序
exceptions	异常总览：异常件清单/派送中数量/处理建议

三、REST API

方法	路径	说明
GET	/api/waybills?status=	运单列表
GET	/api/track?no=	运单轨迹
GET	/api/estimate?type=&weightKg=&insured=&declaredValue=	运费估算
POST	/api/order	寄件下单 {from,to,type,weightKg,pickupTime}
GET	/api/orders	寄件订单列表
GET	/api/branches?area=	营业网点
GET	/api/exceptions	异常总览
POST	/api/assistant/stream	AI 助手 SSE（透传 DSH）

四、快速开始

mvn clean package -DskipTests
java -Dserver.port=18094 -jar e-app/target/e-app-1.0.0-SNAPSHOT.jar

bash install_plugin.sh e-plugin/target/e-plugin-1.0.0-SNAPSHOT.jar \
  express-copilot 1.0.0-SNAPSHOT e-plugin-1.0.0-SNAPSHOT.jar "AI 快递助手"

open http://127.0.0.1:18094/

五、端到端验证

bash agent_stream.sh 127.0.0.1:8090 express-copilot "SF1023847561 到哪了？"
bash agent_stream.sh 127.0.0.1:8090 express-copilot "我要寄 6 公斤从上海徐汇到北京朝阳，走次日达多少钱？"
bash agent_stream.sh 127.0.0.1:8090 express-copilot "确认下单，今天 17 点后取件"
bash agent_stream.sh 127.0.0.1:8090 express-copilot "YT2093841123 怎么回事？附近朝阳区哪个网点能自提？"

5 个工具全部验证通过。验证截图：

截图	内容
	AI 解释武汉暴雨滞留原因并给改走航空件建议
	AI 报首重/续重/合计三项并主动提示保价
	AI 下单前二次确认地址/类型/重量

六、技术要点

• 运费模型：首重 1kg 按类型定价，续重按 0.5×首重/kg；保价费 = 声明价值 × 0.5%（最低 1 元）；时效按类型映射（次日达/同城闪送/标准/经济）。
• 下单二次确认：系统提示强制「先 estimate 报价 → 用户确认 → 再 order」，下单后必须报 orderId + waybillNo + 费用。
• 异常件处理：轨迹含「滞留」节点时 Waybill 标记异常，exceptions 输出异常清单与「联系收件人/改走航空」建议，AI 主动解释原因。
• 结论约束：查件按轨迹时间线汇报（先结论后明细），报价必须报首重/续重/合计三项，数据全部来自工具返回。

七、目录结构

express-tracking/
├── pom.xml                  # 父 pom（maven.compiler.parameters=true）
├── e-app/                   # Spring Boot 应用 (18094)
│   └── src/main/java/cn/xiaofuge/e/app/
│       ├── ExpressApplication.java
│       ├── EStore.java        # 运单/轨迹/价格/网点/异常
│       ├── EController.java   # REST API
│       └── AssistantController.java # SSE 透传 DSH
├── e-plugin/                # DSH 插件 (express-copilot)
│   └── src/main/
│       ├── java/.../ExpressPlugin.java  # 5 工具
│       └── resources/META-INF/       # plugin.yaml + SPI
└── docs/
    ├── 使用说明.md
    └── images/              # 验证截图 ×4