72 lines
4.5 KiB
Markdown
72 lines
4.5 KiB
Markdown
---
|
||
name: tennis-booking
|
||
description: 通过 Pospal 公开接口访问范思伯特福中福球场，查询可订时段、识别连续场地、一次性锁场并把待支付结果回传给用户。协议、URL、Header、请求体、响应体全部以明文写在 references/protocol.md；agent 自己负责 HTTP 调用、轮询节奏、去重和用户交互；helper 脚本 scripts/pospal.mjs 只做解析、连续组合识别、锁场请求体构造、响应脱敏。用户提到网球场预约、抢场、捡漏、空场监控、PSPLVISITORID、自动锁场、范思伯特福中福、Pospal、wxservice-stg48 时即使不点名 Skill 也应使用。只处理用户本人有权使用的 PSPLVISITORID，绝不把访客凭证写入 Skill、日志或对话。
|
||
compatibility: Linux / macOS；Node.js 22+（自带 fetch 与 ESM）；仅依赖系统 curl 或 Node fetch；无 Electron、无 daemon、无守护进程
|
||
---
|
||
|
||
# Tennis Book Pospal 直连
|
||
|
||
面向 LLM agent 的球场预约 skill。把 Pospal 接口契约完整暴露在文档里，agent 自己用任何 HTTP 工具发请求；helper 脚本负责 JSON 解析、连续组合识别、锁场请求体构造、响应脱敏指纹。
|
||
|
||
不持久化任何状态，不启动后台进程，不绕过协议做事。`PSPLVISITORID` 必须在首次写操作前由 agent 向用户索取（隐藏式输入），session 内存缓存，绝不落盘。
|
||
|
||
## 目录约定
|
||
|
||
- `references/protocol.md` ⭐ 完整明文协议规范：端点、Header、请求体、响应体、状态码、字段含义、错误分类、curl 示例。
|
||
- `references/current-logic.md`：从 desktop 适配器提炼出的稳定业务规则——连续场地判定、状态解释、错误分类、脱敏指纹。
|
||
- `references/operations.md`：agent 在 Linux/macOS 上怎么调用 helper、怎么向用户隐藏式索取 PSPLVISITORID、怎么轮询、怎么处理失败。
|
||
- `references/courts/fansibote-fuzhong.md`：单一已接入球场的常量、别名和专属说明；详细端点指向 `protocol.md`。
|
||
- `scripts/pospal.mjs`：Node 22 ESM 助手。提供 `parse-availability` / `find-continuous` / `build-booking-body` / `parse-booking-response` / `fingerprint` / `redact` 子命令。
|
||
- `evals/evals.json`：行为级断言（不访问真实写接口）。
|
||
- `evals/fixtures/`：离线 fixture，用于跑 helper 子命令做冒烟验证。
|
||
|
||
## 必读顺序
|
||
|
||
1. 收到任何预约 / 查询 / 监控请求后，先读 `references/protocol.md` 拿到完整接口契约。
|
||
2. 涉及具体球场时再读 `references/courts/fansibote-fuzhong.md`。
|
||
3. 涉及业务规则（连续场地、状态解释、错误码）读 `references/current-logic.md`。
|
||
4. 涉及调用方式（helper 子命令、env、隐藏输入）读 `references/operations.md`。
|
||
5. **永远不要**把 `PSPLVISITORID` 写入 Skill 文件、日志、对话或 git 历史。
|
||
|
||
## 核心工作流
|
||
|
||
### 只读查询
|
||
|
||
```
|
||
agent: 读 protocol.md → curl/Node fetch 调 list 端点 → pipe raw JSON 到
|
||
pospal.mjs parse-availability → 输出可订时段
|
||
```
|
||
|
||
### 锁场
|
||
|
||
```
|
||
agent: 查询 → parse-availability → find-continuous --start HH --end HH
|
||
→ 若需凭证：向用户隐藏式索取 PSPLVISITORID
|
||
→ 用 helper build-booking-body 生成请求体
|
||
→ curl 调 book 端点
|
||
→ pipe raw response 到 parse-booking-response，输出待支付摘要
|
||
→ 把摘要（不含 paySign）告诉用户去小程序支付
|
||
```
|
||
|
||
### 释放
|
||
|
||
```
|
||
agent: 调 release 端点（body 必须是 `{}`），需要 PSPLVISITORID
|
||
```
|
||
|
||
## 失败与边界
|
||
|
||
- HTTP 非 2xx：按 `protocol.md` 的错误码语义解释。
|
||
- 解析失败或网络超时：告知用户"结果不确定"，**禁止重试**，必须人工去小程序核实。
|
||
- 已发起锁场但响应不确定：禁止再次下单同一时段，提示用户去小程序。
|
||
- 支付脚本（`script.paySign` 等）只在当次锁场响应里出现一次，绝不打印、绝不缓存、绝不落盘。
|
||
|
||
## 完成标准
|
||
|
||
- `node scripts/pospal.mjs --help` 正常输出子命令列表。
|
||
- `node scripts/pospal.mjs parse-availability --date 2026-07-16 < evals/fixtures/availability-sample.json` 输出结构化 JSON。
|
||
- `node scripts/pospal.mjs find-continuous --start 19 --end 21` 能识别 fixture 中的连续组合。
|
||
- `node scripts/pospal.mjs build-booking-body < evals/fixtures/continuous-slots.json` 输出符合 `protocol.md` 的请求体。
|
||
- `node scripts/pospal.mjs fingerprint <visitor-id>` 输出 12 字符 hex。
|
||
- `evals/evals.json` 中所有断言成立（agent 不绕过 helper 自行拼请求体、不打印 PSPLVISITORID 原值、不在结果不确定时重试）。
|