zoo-tour · AI 动物园导览管家台 🦁

DSH（deepseek-harness-java）Java Native Plugin 场景案例 P85：动物园游园购票 + AI 导览插件。

项目简介

「zoo-tour」是一个动物园游园购票场景的演示项目，包含：

• z-app：Spring Boot 应用（端口 18124），提供票种、讲解员、购票、统计等 REST 接口和一个可视化管家台页面。
• z-plugin：DSH Java Native Plugin（agent：zoo-copilot），以 SPI 方式接入 DSH，提供 5 个可被大模型调用的工具。

用户在管家台页面与 AI 对话即可完成票务咨询、购票下单、订单查询、运营问数等操作，AI 通过 DSH 调用插件工具读写业务数据。

功能一览

模块	说明
门票价目	5 种票：成人日间票 ¥120、儿童票 ¥60、亲子家庭套票 ¥288、夜场探秘票 ¥158、VIP 深度导览票 ¥398
讲解员	3 位金牌讲解：熊猫大使·阿雅（G01）、猛兽专家·大鹏（G02）、夜行侠·小鹿（G03），含评分与在带量
购票	学生凭证 8 折；10 人以上团队 85 折；1.0 米以下免票；节假日需提前 1 天预订
订单	单号 Z6001+，状态：已订票 / 已入园 / 已离园；凭手机号扫码入园
统计	总单量、已入园 / 已订票 / 已离园、收入、按票种 / 按讲解分布、运营建议

插件工具（5 个）

工具	说明
ticket_list	门票票种列表（价格 / 权益 / 优惠规则）
guide_list	讲解员列表（编号 / 特点 / 评分 / 在带量）
book	购票下单（客户 / 电话 / 票种 / 数量），先复述要素再执行
order_info	订单查询（单号、状态、入园提醒）
stats	运营统计（单量 / 收入 / 分布 / 建议）

快速开始

1. 启动 DSH standalone（如未启动）

cd ~/.dsh/standalone && java -Dspring.profiles.active=standalone -Dserver.port=8090 \
  -jar ~/.dsh/skills/dsh-java-plugin-skills/runtime/deepseek-harness-java-app.jar

2. 构建并启动应用

mvn clean package
cd z-app && java -jar target/z-app-1.0.0-SNAPSHOT.jar --server.port=18124

3. 安装并激活插件

cp z-plugin/target/z-plugin-1.0.0-SNAPSHOT.jar ~/.dsh/standalone/plugins/zoo-copilot.jar

curl -X POST http://127.0.0.1:8090/api/harness/plugins/install \
  -H 'Content-Type: application/json' \
  -d '{"pluginId":"zoo-copilot","displayName":"AI 动物园导览管家","pluginVersion":"1.0.0","runtimeType":"JAVA_NATIVE","sourcePath":"/Users/<you>/.dsh/standalone/plugins/zoo-copilot.jar","entrypoint":"cn.xiaofuge.z.plugin.ZooTourPlugin"}'

curl -X POST http://127.0.0.1:8090/api/harness/plugins/activate \
  -H 'Content-Type: application/json' -d '{"pluginId":"zoo-copilot"}'

4. 打开管家台

浏览器访问 http://127.0.0.1:18124，点击右侧 AI 面板的快捷按钮或直接对话，例如：

• 「有哪些门票？多少钱？」
• 「我要买 2 张成人日间票 + 1 张儿童票，要熊猫大使阿雅讲解，连女士 13800665544」
• 「查一下订单 Z6001 的状态」
• 「今天运营情况怎么样？」

5. E2E 验证（可选）

python3 zoo_e2e.py

依次验证 5 个工具调用（票种 / 讲解 / 购票 / 查询 / 统计）。

截图预览

截图	说明
	管家台首页：运营看板 + 门票价目 + 最新订单
	AI 咨询票种与价格
	AI 复述确认后下单成功（多票种智能拆单）
	AI 查询订单状态与入园提醒
	AI 运营问数与建议

目录结构

zoo-tour/
├── pom.xml                # 父工程（z-app / z-plugin）
├── z-app/                 # Spring Boot 应用（18124）
│   └── src/main/java/cn/xiaofuge/z/app/
│       ├── ZooTourApplication.java    # 启动类
│       ├── ZStore.java                # 业务数据中心（内存）
│       ├── ZController.java           # REST 接口
│       └── AssistantController.java   # SSE 代理 → DSH /api/agent/stream
├── z-plugin/              # DSH Java Native Plugin
│   └── src/main/java/cn/xiaofuge/z/plugin/
│       └── ZooTourPlugin.java         # 5 个工具 + 系统提示词
├── docs/                  # 使用说明 + 截图
└── zoo_e2e.py             # E2E 验证脚本

技术要点

• Java Native Plugin：继承 AbstractHarnessPlugin，内部工具继承 AbstractTool，以 plugin__zoo-copilot__<name> 暴露给大模型。
• SPI 注册：META-INF/services/cn.xiaofuge.deepseek.harness.domain.spi.JavaHarnessPlugin 指向 cn.xiaofuge.z.plugin.ZooTourPlugin。
• SSE 透传：前端 /api/assistant/stream → DSH /api/agent/stream（agentId=zoo-copilot），流式返回。
• 数值容错：LLM 常传字符串数字（如 "2"），Controller 对 qty 做双格式解析。
• 安全红线：系统提示词约定「先复述要素再下单」「凭手机号扫码入园」「熊猫馆投喂讲解时间」等规则。

场景标签（topics）

dsh-java dsh-java-plugin zoo tourism spring-boot