diff --git a/docs/AI_INTEGRATION_GUIDE.md b/docs/AI_INTEGRATION_GUIDE.md index e519d82..eb50509 100644 --- a/docs/AI_INTEGRATION_GUIDE.md +++ b/docs/AI_INTEGRATION_GUIDE.md @@ -159,6 +159,17 @@ AI 默认不要使用 `date`,除非调用平台只能传固定后台日期格 ## 6. AI 对话到接口参数映射 +### 6.1 工具选择规则 + +- 用户问“订单汇总”“多少单”“订单金额合计”“实付金额合计”“活跃商户数量”时,选择 `order_summary`。 +- 用户问“状态分布”“支付类型分布”“订单类型分布”“抵扣金额”“手续费”“diamond/钻石/绿宝石/算力统计”时,选择 `offline_stats`。 +- 用户问“排行”“排名”“Top 商家”“商户排行”时,选择 `merchant_ranking`。 +- 用户问“活跃商户有哪些”“活跃商户名称”“商户列表”“有哪些商家”“店铺名称”时,必须选择 `merchant_ranking`,不要选择 `order_summary`。 +- `order_summary` 只返回活跃商户数量 `activeMerchantCount`,不返回商户名称。 +- `merchant_ranking` 返回 `ranking[].merchantName`,可用于回答商户名称、商户列表、店铺名称相关问题。 + +### 6.2 对话示例 + 用户说“今天订单怎么样?”时调用: ```json @@ -191,6 +202,23 @@ AI 默认不要使用 `date`,除非调用平台只能传固定后台日期格 推荐接口:`POST /api/merchant-ranking` +用户说“2026 年 6 月 25 日活跃商户名称有哪些?”时调用: + +```json +{ + "timePreset": "custom", + "startDate": "2026-06-25", + "endDate": "2026-06-25", + "status": -1, + "sortBy": "totalRealPay", + "limit": 100 +} +``` + +推荐接口:`POST /api/merchant-ranking` + +注意:不要用 `POST /api/order-summary` 回答这个问题,因为它只返回活跃商户数量,不返回商户名称。 + 用户说“查 6 月 1 日到 6 月 23 日订单统计”时调用: ```json @@ -439,5 +467,5 @@ Invoke-RestMethod ` ## 13. 推荐给 AI 的简短系统提示词 ```text -你需要通过 Merchant AI HTTP API 分析订单数据。统计接口只能使用 POST。不要直接请求后台订单接口,不要暴露 token。用户提到时间时,优先转换为 timePreset:今天=today,昨天=yesterday,最近7天=last_7_days,最近30天=last_30_days,本周=this_week,上周=last_week,本月=this_month,上月=last_month。只有明确起止日期时使用 custom,并传 startDate/endDate,格式 YYYY-MM-DD。不要把“今天”“昨天”“本月”等自然语言直接作为参数传给接口。如果用户没说时间,默认 timePreset=today。订单状态 status:全部=-1,待支付=0,已完成/成功=1,已取消=2,待核销/待使用=3,已退款=4;如果用户没有限定状态,默认 status=-1。解读接口返回时,必须只使用 JSON 中真实存在的字段和数值,不允许编造订单数、成功订单数、商户数、金额、日均值、趋势或业务结论。可以基于返回字段做简单计算,但必须说明“根据当前返回数据计算”。如果返回 _debug_query.time,可以作为查询时间范围。当前接口会自动分页拉取当前筛选条件下的订单数据后再统计,_debug_query 只表示筛选条件。 +你需要通过 Merchant AI HTTP API 分析订单数据。统计接口只能使用 POST。不要直接请求后台订单接口,不要暴露 token。用户提到时间时,优先转换为 timePreset:今天=today,昨天=yesterday,最近7天=last_7_days,最近30天=last_30_days,本周=this_week,上周=last_week,本月=this_month,上月=last_month。只有明确起止日期时使用 custom,并传 startDate/endDate,格式 YYYY-MM-DD。不要把“今天”“昨天”“本月”等自然语言直接作为参数传给接口。如果用户没说时间,默认 timePreset=today。订单状态 status:全部=-1,待支付=0,已完成/成功=1,已取消=2,待核销/待使用=3,已退款=4;如果用户没有限定状态,默认 status=-1。工具选择:问订单汇总、多少单、金额合计、活跃商户数量,选择 order_summary;问状态分布、支付类型、订单类型、抵扣、手续费、diamond/钻石/绿宝石/算力统计,选择 offline_stats;问排行、排名、Top 商家、商户名称、活跃商户有哪些、商户列表、店铺名称,选择 merchant_ranking。注意 order_summary 只返回 activeMerchantCount,不返回商户名称;需要商户名称时必须用 merchant_ranking。解读接口返回时,必须只使用 JSON 中真实存在的字段和数值,不允许编造订单数、成功订单数、商户数、金额、日均值、趋势或业务结论。可以基于返回字段做简单计算,但必须说明“根据当前返回数据计算”。如果返回 _debug_query.time,可以作为查询时间范围。当前接口会自动分页拉取当前筛选条件下的订单数据后再统计,_debug_query 只表示筛选条件。 ``` diff --git a/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md b/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md index 3c2cf3c..a24e06d 100644 --- a/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md +++ b/docs/AI_RESPONSE_INTERPRETATION_GUIDE.md @@ -98,6 +98,12 @@ AI 必须严格遵守: | `totalRealPay` | 当前筛选条件下的实付总金额 | | `_debug_query.time` | 本次查询时间范围 | +注意:`/api/order-summary` 不返回商户名称列表。 + +- 如果用户问“活跃商户数量”,可以使用 `activeMerchantCount` 回答。 +- 如果用户问“活跃商户有哪些”“商户名称”“店铺名称”,不能用 `/api/order-summary` 的结果强行回答。 +- 遇到商户名称类问题,应提示需要使用 `/api/merchant-ranking` 的 `ranking[].merchantName` 数据。 + 推荐解读模板: ```text @@ -342,6 +348,20 @@ AI 必须严格遵守: 当前查询条件下没有返回可排行的商户数据。 ``` +如果用户问题是“活跃商户有哪些”“商户名称有哪些”“店铺名称有哪些”,AI 应从 `ranking[].merchantName` 提取名称;如果 `merchantName` 为空,则使用 `merchantId` 兜底。 + +推荐输出: + +```text +本次查询时间范围:{_debug_query.time} + +活跃商户如下: +1. {merchantName 或 merchantId} +2. {merchantName 或 merchantId} + +以上商户来自 merchant-ranking 接口返回的 ranking 列表。 +``` + ## 7. 允许的计算 AI 可以进行以下简单计算: