挥拍运动通用AI教练

概述

AI Detect 视频分析

使用当前会话中用户上传的视频创建异步分析任务，再按订单号查询结果。服务端处理通常需要约 2 分钟。

所需信息

• 视频附件：优先使用当前消息中的附件；仅有一个视频时直接使用。
• 订单号：服务端已有且已支付的订单号；用户没有订单号时，按下方支付流程创建。
• 运动类型：tabletennis（乒乓球）、badminton（羽毛球）、tennis（网球）或 golf（高尔夫）。
• 身高：可选，单位为米，默认 1.75。
• 高尔夫球杆：仅高尔夫可选，值为 driver（1号木杆）或 7iron（7号铁杆）。

缺少视频或运动类型时，先向用户索取。若同一消息中有多个视频且无法根据文件名或描述唯一确定，询问用户选择哪个文件。不要猜测订单号或附件路径。

附件可以是本地路径或 file:// URI。不要读取视频内容到对话中，不要转为 Base64。支持 .mp4、.mov、.mkv、.avi、.webm 和 .m4v；文件最大 20 MB。服务端会将超过 10 秒的视频截取为前 10 秒。

服务配置

固定服务地址：https://app.yqtx.group/ai-detect/。脚本也支持环境变量 AI_DETECT_BASE_URL 或 --base-url 覆盖，仅供私有化部署使用，正常情况下不要改动。

计费方式：按次计费。一次成功支付对应一个视频的一次分析，重复查询已有订单不额外收费。

付费前置检查

调用本 Skill 前，先确认当前 Agent 已安装 weixinpay 插件、具备微信支付 AI 专属卡支付能力：

• 已安装：继续提供付费服务；
• 未安装：提示"当前 Agent 暂不支持微信支付付费能力"并终止流程，不要绕过支付校验，不要试图用其他方式取内容。

执行流程

第一步：创建订单（无支付凭据 → 服务端返回 402）

python3 <skill-dir>/scripts/create_order.py

服务端返回 HTTP 402 且 code 为 PAYMENT_REQUIRED 时，必须同时保存两项，缺一不可：

• WeixinPay.WeixinPay-Required：支付码 payment_code；
• out_trade_no：商户订单号（重试时通过请求头 X-Out-Trade-No 回传）。

第二步：发起支付

将 WeixinPay-Required 的值作为 paymentCode 调用 weixinpay_pay，由用户在支付卡片上完成授权。不要代替用户确认支付，不要重复创建订单。支付码有效期 15 分钟，过期需重新执行第一步。

第三步：支付成功后必须重新请求服务端确认（不可跳过）

不能仅凭 Agent 侧的支付成功消息继续。必须用第一步保存的订单号与支付码重新请求，由服务端以微信支付查单或支付回调为准验付：

python3 <skill-dir>/scripts/create_order.py 
  --confirm "<out_trade_no>" 
  --payment-code "<WeixinPay-Required>"

即请求携带 X-Out-Trade-No: <out_trade_no> 与 WeixinPay-Required: <payment_code> 两个请求头。仅当返回 code 为 SUCCESS 且 status 为 paid 时，才把返回的 ordernum 用于视频提交。

同一订单只履约一次：重复确认返回已履约状态时直接复用原结果，不要重复上传视频、不要重复分析。若当前 Agent 没有微信支付能力，说明暂不支持付费流程并停止。用户已提供有效且已支付的订单号时，可跳过第一步到第三步。

第四步：提交视频并轮询结果

先调用异步提交脚本。脚本固定向现有 POST /api/detect 发送 sync=false，不会等待分析完成：

python3 <skill-dir>/scripts/submit_video.py 
  "<视频路径或 file:// URI>" 
  --ordernum "<订单号>" 
  --sport-type "<运动类型>" 
  --height 1.75

高尔夫且用户指定球杆时追加 --golf-club driver 或 --golf-club 7iron。

仅当提交结果的 code 为 00 且 data.status 为 analyzing 时继续。随后调用查询脚本；它默认每 5 秒查询一次，最多等待 300 秒：

python3 <skill-dir>/scripts/query_task.py --ordernum "<订单号>"

需要调整等待策略时可使用 --poll-interval <秒>、--wait-timeout <秒>；只查询一次时使用 --once。默认结果会省略可能很长的 csv_content，只有用户明确需要原始 CSV 时才追加 --include-csv。

订单状态含义：0 为等待处理，1 为完成，2 为失败，3 为分析中。不要在提交失败、查询失败或订单状态为失败时自动重新上传；说明服务端返回的中文错误并让用户决定下一步，避免对同一付费订单重复执行。

返回用户

完成后优先概述 detect_result，并按实际存在的字段提供分析视频 video_resp、原始视频 video_req、分析图 plt_url、击球帧 impact_frame_annotated 和耗时 detect_cost。不要声称空字段对应的产物已经生成。

若查询等待超时，说明任务仍未在等待窗口内完成，并保留订单号供后续使用；超时不等于分析失败，可用同一订单号继续查询，不会产生额外费用。