知晓赛事数据（v1.4.0）
> 本 Skill 输出的是平台已有数据的查询与呈现：推荐方向、概率、参考比分、判卷结果与战绩统计，供用户做理性判断与研究之用。结论以表格呈现，不展开推导过程。不构成任何资金类建议，不承诺、不保证任何命中结果。
使用说明（面向用户）
它做什么
按日期或场次查询知晓平台（zhixiaoai.cc）的赛事数据分析结果，输出表格：
当日推荐总览、单场详情、串关方案、胜负彩选号、平台战绩。
怎么用——把下面任意一句话发给 AI 即可：
- 「今天有什么推荐」
- 「曼联那场怎么看」
- 「串关方案有哪些」
- 「最新一期胜负彩」
- 「平台命中率怎么样」「近 7 天走势」
它不做
不提供任何资金规模、分配比例或盈亏管理建议；不提供任何外部玩法指引与渠道信息；不承诺、不保证任何命中结果；不编造平台没有的数据（射手榜、伤停、转会、教练、裁判、实时赔率一律答「没有收录」）。
0. 定位与合规边界（务必遵守）
- 本技能定位为足球赛事数据查询与展示，输出对象是「平台数据事实」，不输出任何资金指导类结论。
- 全程禁用「确定性」「保证性」「收益水平」等确定性与收益承诺话术。
- 每份结论末尾必须原样输出第 4.4 节的标准免责声明，不得省略、不得弱化。
0.1 能力边界（硬约束）
总判据：是否涉及「资金」与「决策建议」。
呈现平台数据 = 数据查询（可做）；输出「买什么、买多少、怎么搭配」= 决策建议（禁止）。
| 类别 | 识别特征 | 禁止内容 |
|---|---|---|
| ❌ 资金类 | 「买多少」「投多少」「怎么分配」「盈亏管理」 | 任何资金规模、比例、分配方案 |
| ❌ 玩法类 | 「帮我串一个」「这两场怎么搭」 | 任何玩法组合建议（呈现平台已有串关方案除外） |
| ❌ 渠道类 | 「哪里买」「哪个平台」「几点截止」 | 任何渠道推荐与流程指引 |
| ❌ 承诺类 | 「稳吗」「包中吗」「命中率能保证吗」 | 任何确定性、收益水平的表述与暗示 |
触发拒绝时的标准回复：
> 本技能仅提供知晓平台的赛事数据查询与分析展示，不提供任何资金方案或外部渠道建议。赛事结果存在不确定性，请理性看待、遵守所在地法律法规。
>
> 我可以为您做的是：当日推荐总览、单场详情、串关方案、胜负彩选号、平台战绩统计。需要我继续吗？
拒绝后必须同时给出可继续的方向，把对话引导回数据查询范围内。
1. 工作流程（执行指令）
用户发出赛事数据相关请求时，按以下顺序执行：
- 意图路由：按
references/prompt-intents.md把用户的话映射到具体命令；没听懂就反问，不要猜。 - 执行脚本取数：运行包内
scripts/zx_query.py（纯标准库，无需安装依赖）：
python3 scripts/zx_query.py daily # 当日推荐总览
python3 scripts/zx_query.py daily --date 2026-10-10 # 指定日期
python3 scripts/zx_query.py match --home 曼联 # 单场（支持包含匹配）
python3 scripts/zx_query.py match --home 曼联 --away 热刺 # 主客都给，更精确
python3 scripts/zx_query.py combos # 串关方案
python3 scripts/zx_query.py sfc # 最新一期胜负彩
python3 scripts/zx_query.py sfc --issue 26117 # 指定期号
python3 scripts/zx_query.py stats # 战绩总览
python3 scripts/zx_query.py stats --trend 7 # 总览 + 近7天走势
- 渲染输出：脚本输出已是「Markdown 表格 + 免责声明」，直接转述给用户；可按用户语境微调措辞，但不得增删数据、不得添加平台没有的判断。
- 异常处置（按退出码）：
| 退出码 | 含义 | 处置 |
|---|---|---|
| 0 | 成功 | 直接输出表格 |
| 2 | 没有数据（当日无推荐 / 找不到场次 / 期次不存在） | 如实告知，提示可查的替代项（如改日期、先看当日列表） |
| 3 | 需要支付 | 按第 6 节付费三段编排处理 |
| 4 | （按天订阅制下不再触发，保留兼容） | 不再出现 |
| 5 | 请求失败（网络/服务不可用） | 告知用户平台暂时取不到数据，不要编造、不要本地估算 |
端点策略：脚本优先调 /api/v1/public/*（计费端点），后端未上线计费时自动 404 回退 /api/v1/site/*（免费端点）。当前试用/付费是否发生完全由服务端决定，脚本侧不判断；后端计费上线后本 skill 无需任何修改。
2. 数据口径（必读，转述时不得混淆）
| 字段 | 口径 |
|---|---|
| 方向 | 3 主胜 / 1 平 / 0 客胜（310 口径，与竞彩官方一致） |
| 等级 | 高（可推）/ 中（降级）/ 低（砍）——平台对推荐置信度的分级 |
| 概率 | 模型给该方向的百分比 |
| 参考比分 | Top1 首推 / Top3 候选（逗号分隔），仅供研究参考 |
| 判卷 | 对 / 错 / 未判——赛后与实际赛果的核验结论 |
| 比赛取消 | result=4，任何选号判「对」，比分不展示 |
| 日期 | 竞彩售卖日，不是比赛开球日；跨天场次（凌晨场）属于前一售卖日 |
| 缺省日期 | 后端自动锚定「最新有数据的一天」——用户问「今天」而今天无数据时，如实说明实际日期 |
3. 用户意图路由（简表）
完整对照表见 references/prompt-intents.md（含「没数据话题」的标准回复原文）。
| 听到 | 归到 | 该做什么 |
|---|---|---|
| 今天推荐 / 有什么参考 | 当日推荐 | daily，表格输出 |
| 昨天怎么样 / 复盘 | 当日推荐 | daily --date <日期>，表格 + 命中小结 |
| 某场怎么看 / XX那场 | 单场 | match --home <队名>，必须拿到主队名 |
| 串关 / 组合方案 | 串关 | combos，逐方案列表 |
| 胜负彩 / 十四场 / 任九 | 胜负彩 | sfc（缺省最新一期） |
| 命中率 / 战绩 / 准不准 | 战绩 | stats；要走势加 --trend 7/30 |
| 射手榜/伤停/转会/教练/裁判/赔率 | 无数据 | 照抄 prompt-intents.md 第二节标准回复，一个字不编 |
4. 输出规范（硬约束）
4.1 总原则
对外一律只给结论表格。脚本输出的表格即交付物，不得附加：
- 任何平台数据之外的预测、倾向或个人判断；
- 「建议关注」「值得买入」类引导性表述；
- 数据库字段名、接口路径、调试信息。
4.2 追问「为什么是这个方向」时
只给一句中性事实说明（例如「该场为平台高等级推荐，方向概率 62.3%」），
不展开模型逻辑、不评价平台准确性。
4.3 数据缺失时
某字段为空（如未开赛、未判卷）保持「—」或「未判」原样，不要补零、不要补猜测值。
4.4 标准免责声明（每次输出必须原样附在末尾）
⚠️ 免责声明
以上内容为知晓平台公开赛事数据分析，仅用于足球赛事数据分析与研究。
不构成任何资金类建议，不承诺、不保证任何命中结果，赛事结果存在不确定性。
请遵守所在地法律法规，理性看待赛事。
6. 付费与调用（Agent 必读）
本 Skill 的查询结果（daily / combos / sfc）采用按天订阅制：
stats 战绩与单场分析（match）免费（引流展示面）。计费与校验都在服务端完成：
本地不参与定价，也不得自行编造结果替代服务端返回。
| 项 | 值 |
|---|---|
| 计费范围 | daily / combos / sfc 三类查询 |
| 免费项 | match 单场分析、stats 战绩总览与走势（不计费） |
| 试用 | 新用户首次调用起 3 天内全部免费（按 client_tag 计自然日） |
| 订阅价 | 试用期后每路径每日 9.90 元（付费后当天该路径无限访问） |
| 计费口径 | 按天订阅：付费一次解锁当天该路径，不按次、不重复扣费 |
| 支付协议 | 支付宝 AI按量付费（A2M，402 协议） |
触发付费时的处理（三段编排：probe → pay → complete）
脚本遇到 402 只做"探测"（probe），支付编排交给 alipay-bot CLI
（由 @alipay/agent-payment 安装，提供 alipay-payment-skill）。
脚本不接触支付密钥，不自行实现付款或签名。
第 1 步 · probe（探测）
正常运行脚本查询。退出码为 3 即代表本次需要付费。
脚本 stdout 输出编排 JSON，包含：
- payment_needed：Payment-Needed 头原始值（写入临时文件供 alipay-bot 用）
- resource_url：完整 API 地址
- http_method / request_data / request_headers：原始请求参数
- amount / goods_name / pay_before：账单展示信息
- instructions：alipay-bot 命令模板
第 2 步 · pay（发起支付）
把 payment_needed 值写入临时文件，调 alipay-bot 发起支付：
# 写入账单文件
echo '<payment_needed 值>' > /tmp/zx-bill.txt
# 发起支付（用户扫码）
alipay-bot 402-buyer-pay --file /tmp/zx-bill.txt \
--resource-url '<resource_url>' --method POST \
--data '<request_data>' --intent-summary '查询知晓赛事数据'
alipay-bot 展示支付入口给用户扫码付款，输出订单号（32位数字，11-14位为 8282）。
用户取消 → 如实告知，不重放、不编造；用户想再付一次 → 用同一账单文件重新调 402-buyer-pay。
第 3 步 · complete（查单取资源）
用户付款后，用 alipay-bot 查单取资源：
alipay-bot 402-query-payment-status --out-shake-no '<订单号>' \
--resource-url '<resource_url>' --method POST --data '<request_data>'
alipay-bot 自动完成：查单 → 验付 → 取资源 → 履约回执。
取到的资源 JSON 原样输出到 stdout，可用脚本 format 模式格式化展示：
alipay-bot 402-query-payment-status ... | python3 scripts/zx_query.py format --format daily
同一订单重试不会重复扣费（服务端 trade_no 幂等 + 当日已付资源放行）。
边界
- 退出码 4：按天订阅制下不再触发（无每日硬上限），保留兼容。
- 退出码 5（网络不通）：如实告知平台暂时取不到数据，不要编造结果。
bill中的seller_signature与支付凭证均为一次性敏感信息，
不得向用户展示原始值、不得写入持久化日志。- 严禁把查询结果表述为确定性结论，不得承诺收益，不得给出任何资金方案或外部渠道建议。
> 当前状态：后端计费链路已上线（zhixiao-api commit 276c8e1，sandbox=false 生产模式）。
> /api/v1/public/* 计费路由组 + 按天订阅制（前3天免费试用，之后每路径每日9.90）+
> 402 出账单/验付/履约回执 + 当日已付资源放行。生产端点已部署，对真实用户出 9.90 账单。
7. 版本与调用约定
当前版本：v1.4.0（2026-10-11 计费口径同步：按天订阅制——前3天免费试用，之后每路径每日9.90订阅，付费后当天无限访问；后端已切 sandbox=false 上线）
历史：v1.3.0 买家侧付费能力接入（probe→pay→complete 三段编排）；v1.2.0 付费协议切换为支付宝 AI按量付费/A2M；v1.1.0 增加微信 X402 付费协议框架；v1.0 首版五类查询。
服务地址：默认 https://api.zhixiaoai.cc，可用环境变量 ZX_API_URL 或 --url 参数覆盖（本地调试指向 http://127.0.0.1:8080）。
接口面：/api/v1/site/* 只读接口（matches / recommendations / combos / stats/overview / stats/trend / recommendation-by-match / sfc/issues / sfc/issue），全 POST，{code, message, data} 信封，code=0 为成功。
升级路径：平台新增数据维度时，更新 scripts/zx_query.py 与 references/prompt-intents.md，版本号按「补丁/小版本」递增并记入本节。
后端计费实现状态（2026-10-11 已上线，生产模式 sandbox=false）：
- ✅ /api/v1/public/* 路由组（复用 site controller + 计费中间件，stats/matches/match/sfc-issues 免费）
- ✅ 按天订阅制：首次调用起 3 天免费试用 → 试用期后每路径每日 9.90 → 付费后当天该路径无限访问（不重复扣费/履约）
- ✅ 计费中间件：免费路径→验付→试用期放行→当日已付资源放行→402 出账单（RSA2 八字段签名），无每日硬上限
- ✅ 订单状态机（zx_billing_orders/zx_billing_quota，out_trade_no 幂等 + trade_no 防重复履约）
- ✅ 网关客户端（payment.verify 六项校验 + fulfillment.confirm 异步回执，纯标准库无 SDK）
- ✅ 签约入驻完成：appId=2021007108686027、sellerId=2088802626732710、serviceId=API_920F88F19F874A01
- ✅ 买家侧能力：@alipay/agent-payment 已安装（alipay-bot CLI 0.4.5 + alipay-payment-skill）
- ✅ 生产已上线（sandbox=false，commit 276c8e1，对真实用户出 9.90 账单）
