153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# agent 调用方式
|
||
|
||
## 必备工具
|
||
|
||
- HTTP 客户端：agent 自带 `web_fetch` / `curl` / Node 22 `fetch` 任一
|
||
- Node 22：执行 `scripts/pospal.mjs`（Linux / macOS 自带 `node` 或 NVM）
|
||
- 隐藏式输入：Linux/macOS `bash read -rs`、或 Node `readline` 关闭回显
|
||
- 单次请求硬性超时：`AbortSignal.timeout(12000)`（12 秒）
|
||
|
||
## 凭证管理
|
||
|
||
### 首次获取（agent 主动询问）
|
||
|
||
```bash
|
||
printf "PSPLVISITORID: " >&2
|
||
IFS= read -rs PSPAL_VISITOR_ID
|
||
printf "\n" >&2
|
||
```
|
||
|
||
旧版 `bash` 不支持 `-s` 时：
|
||
|
||
```bash
|
||
stty -echo
|
||
printf "PSPLVISITORID: " >&2
|
||
read PSPAL_VISITOR_ID
|
||
stty echo
|
||
printf "\n" >&2
|
||
```
|
||
|
||
### 注入到 helper 调用
|
||
|
||
```bash
|
||
export POSPAL_VISITOR_ID="$PSPAL_VISITOR_ID"
|
||
node scripts/pospal.mjs build-booking-body < continuous-slots.json
|
||
```
|
||
|
||
helper 也支持 `--visitor <value>`，但**优先用 env**——避免值出现在进程列表 (`ps aux`)。
|
||
|
||
### Session 结束
|
||
|
||
```bash
|
||
unset POSPAL_VISITOR_ID
|
||
```
|
||
|
||
新 session 必须重新索取，不允许持久化。
|
||
|
||
## helper 子命令
|
||
|
||
| 子命令 | 作用 | 何时用 |
|
||
|---|---|---|
|
||
| `parse-availability` | 把 list 端点原始 JSON 转结构化 slots（含状态判定、活动合并） | 每次拿到 list 响应后必跑 |
|
||
| `find-continuous` | 从 slots 中找符合 `--start HH --end HH` 的完整连续组合 | 拿到结构化 slots 后 |
|
||
| `build-booking-body` | 从连续组合生成锁场请求体 | 锁场前 |
|
||
| `parse-booking-response` | 解析锁场响应，**剥离 `script.paySign`** | 锁场后 |
|
||
| `fingerprint` | 访客凭证 → 12 字符 hex 指纹 | 日志关联 |
|
||
| `redact` | 任意 JSON → 移除敏感字段 | 落盘或汇报前 |
|
||
|
||
所有子命令从 stdin 读 JSON（除 `fingerprint`），都支持 `--help`。
|
||
|
||
## 工作流示例
|
||
|
||
### 单次查询
|
||
|
||
```bash
|
||
# 1. 调 list 端点
|
||
RAW=$(curl -sS -X POST 'https://wxservice-stg48.pospal.cn/wxapi/AppointmentVenue/LoadValidClassRoomApptSettingV2' \
|
||
-H 'Accept: */*' \
|
||
-H 'APPTYPE: 1' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'PSPLVISITORAUTO: API' \
|
||
-H 'Referer: https://servicewechat.com/wx2088ca46b47d8be7/11/page-frame.html' \
|
||
-H 'STOREID: 6038652' \
|
||
-H 'VERSIONINFO: NC|2026.07.03' \
|
||
-d '{"dateTime":"2026-07-16","userId":6038652,"projectUid":"1775556129325750199"}')
|
||
|
||
# 2. 解析
|
||
echo "$RAW" | node scripts/pospal.mjs parse-availability --date 2026-07-16
|
||
|
||
# 3. 找连续组合
|
||
echo "$RAW" | node scripts/pospal.mjs parse-availability --date 2026-07-16 \
|
||
| node scripts/pospal.mjs find-continuous --start 19 --end 21
|
||
```
|
||
|
||
### 锁场
|
||
|
||
```bash
|
||
# 1. 重新查一次（不复用旧缓存）
|
||
RAW=$(curl -sS -X POST '...' -d '...')
|
||
|
||
# 2. 解析 + 找连续 + 构造请求体
|
||
BODY=$(echo "$RAW" | node scripts/pospal.mjs parse-availability --date 2026-07-16 \
|
||
| node scripts/pospal.mjs find-continuous --start 19 --end 21 \
|
||
| node scripts/pospal.mjs build-booking-body)
|
||
|
||
# 3. 调锁场
|
||
RESP=$(curl -sS -X POST 'https://wxservice-stg48.pospal.cn/wxapi/AppointmentVenue/SaveVenueAppointmentV2' \
|
||
-H "PSPLVISITORID: $POSPAL_VISITOR_ID" \
|
||
-H @write-headers.txt \
|
||
-d "$BODY")
|
||
|
||
# 4. 解析并脱敏
|
||
echo "$RESP" | node scripts/pospal.mjs parse-booking-response --slots continuous-slots.json
|
||
```
|
||
|
||
`write-headers.txt` 模板见 `references/protocol.md` 末尾。
|
||
|
||
### 监控循环（agent 自行实现）
|
||
|
||
```
|
||
for date in today, today+1, ..., today+6:
|
||
slots = curl list(date) → parse-availability
|
||
cont = find-continuous(slots, target_start, target_end)
|
||
key = (date, cont.txtClassroomUid, cont.startTime, cont.endTime, sum_price)
|
||
if cont and key not in seen:
|
||
notify(cont)
|
||
seen.add(key)
|
||
elif not cont and key in seen:
|
||
notify("removed: {key}")
|
||
seen.discard(key)
|
||
sleep 10
|
||
```
|
||
|
||
整点（如 `19:00:00.000`）agent 主动绕过冷却立即查一次。同一 date 的并发查询只允许一个在飞。
|
||
|
||
## 失败处理速查
|
||
|
||
| 现象 | agent 动作 |
|
||
|---|---|
|
||
| 列表返回 `successed: false` | 视为该日无可订数据，不重试 |
|
||
| 列表返回缺字段 | 视为接口变更，停止对该球场所有操作，告诉用户"接口字段变化，暂停服务" |
|
||
| 锁场 `successed: false` | 换时段最多重试 1 次，仍失败则停下 |
|
||
| 锁场 HTTP 5xx / 网络错误 | 不重试，告诉用户"结果不确定，请去小程序核实" |
|
||
| 锁场后 `script.expireTime` 已过 | 锁场已失效，告知用户 |
|
||
| `enrollSlots` 含目标时段 | 该时段按已订处理，不计入连续组合 |
|
||
| `PSPLVISITORID` 未索取 | 写操作前必须先向用户隐藏式索取；缺则停下 |
|
||
|
||
## 调试与脱敏
|
||
|
||
```bash
|
||
# 任何写操作前，确认 visitor 指纹
|
||
node scripts/pospal.mjs fingerprint "$POSPAL_VISITOR_ID"
|
||
# → "a3f9b21c0e4d" (12 字符)
|
||
|
||
# 落盘任何响应前必须 redact
|
||
curl ...list... | node scripts/pospal.mjs redact > list-redacted.json
|
||
|
||
# 看 helper 自检
|
||
node scripts/pospal.mjs parse-availability --date 2026-07-16 \
|
||
< evals/fixtures/availability-sample.json
|
||
```
|
||
|
||
完整 `list-headers.txt` / `write-headers.txt` 模板见 `references/protocol.md` 末尾的 curl 示例。
|