飞伙

SKILL.md

---
name: feihuo
display_name: "飞伙"
description: 使用内置飞伙 CLI 搜索与验价航班。适用于查询机票、比较价格、选定方案后验价确认，或执行 flight-search / flight-verify 子命令的场景。
metadata:
  version: 2.0.0-beta7
  agent:
    type: tool
    runtime: node
    context_isolation: execution
    parent_context_access: read-only
  openclaw:
    emoji: "\u2708"
    priority: 90
    requires:
      bins:
        - node
    intents:
      - flight_search
      - flight_verify
      - order_create
    patterns:
      - "(搜索|查询|查找|比较|预订|验价|确认).*(航班|机票|飞机票)"
      - "(航班|机票|飞机票).*(搜索|查询|查找|比较|价格|验价|预订)"
      - "feihuo\\s+flight-(search|verify)"
      - "feihuo\\s+order-create"
---

# 飞伙（机票）

所有命令均在**技能根目录**执行，统一入口：`node ./cli/index.js`。

使用内置 CLI 搜索与验价航班。命令输出 JSON 到 `stdout`，错误信息输出到 `stderr`。

## 快速开始

1. 查看帮助：`node ./cli/index.js --help`
2. 搜索航班：`node ./cli/index.js flight-search --dep "上海" --arr "东京" --dep-date 2026-03-20`
3. 验价确认：`node ./cli/index.js flight-verify --id "<方案ID>"`
4. 填写订单：`node ./cli/index.js order-create --file order.json`

## 认证

CLI 已内置在技能目录 `./cli/`，通过 FClaw 注入的 `OIDC_TOKEN_URL` 与 `OIDC_TOKEN_SECRET` 从本地 OIDC token 端点获取 access_token。请在 FClaw 中登录，并在技能根目录下执行命令（工作目录须包含 `cli/index.js`）。

## 预订流程（必须遵守）

机票预订按以下顺序进行，**不可跳步**：

1. **`flight-search`**：按用户需求搜索，带齐 CLI 筛选参数。
2. **选择方案**：引导用户在 FClaw 右侧面板点击选择；或用户已明确指定时使用对应 `items[].id`。
3. **`flight-verify --id <id>`**：对选中方案验价，获取实时价格、座位与退改签说明。
4. **填写订单并预定**：引导用户在 FClaw **右侧订单面板**确认联系人、选择常旅客或填写乘机人，点击「预定」；**禁止**在聊天中索要证件号。
5. **面板下单 + 支付（一问一答）**：用户点「预定」后，**FClaw 客户端直接调用 WebApi 创建订单**，并在右侧内置浏览器打开支付页。客户端会**代发一条用户消息**（如「我已提交预订…请跟进支付与出票」），AI **正常回复**确认摘要并提醒支付，**禁止**再执行 `order-create` / 补填 `callback`。
   - 支付完成后客户端关闭浏览器、用 `payid` 查结果，再**代发一条用户消息**（如「我已完成支付…」）；AI 再回复确认并跟进出票。
   - **已无**独立的 `order-pay` 命令；排障可用 `order-pay-result --pay-id`。**禁止**仅文字引导用户去订单详情支付。

搜索方案在服务端缓存 **30 分钟**。验价失败或提示找不到方案时，应重新 `flight-search` 后再验价。

## exec 执行方式（必须遵守）

`flight-search` 必须**同步执行并拿到完整 JSON** 后，才能告诉用户「请在右侧列表选择」：

1. **优先**在技能目录前台执行：`cd ~/.fclaw/skills/feihuo && node ./cli/index.js flight-search ...`，等待命令结束，`stdout` 含 `{"items":[...]}`。
2. 若 `exec` 返回 `Command still running`，**必须**用 `process poll`（必要时 `process log`）等到进程退出，并确认输出里已有完整 `items` 列表后，再回复用户。
3. **禁止**在搜索尚未完成、或仅有截断片段时，提前说「已筛选出 N 个方案」或引导右侧面板。
4. `flight-verify` 同理：验价完成后再报价，不要把验价 JSON 当作搜索列表展示。

## `flight-search`

搜索航班，支持单程和往返。

```bash
node ./cli/index.js flight-search --dep "上海" --arr "东京" --dep-date 2026-03-20
node ./cli/index.js flight-search --dep "上海" --arr "东京" --dep-date 2026-03-20 --back-date 2026-03-25 --berth-type Y
```

详细参数见 [references/flight-search.md](references/flight-search.md)。

## `flight-verify`

对搜索选中的方案验价。`--id` 取自 `flight-search` 返回的 `items[].id`。

```bash
node ./cli/index.js flight-verify --id "<方案ID>"
```

详细参数与输出见 [references/flight-verify.md](references/flight-verify.md)。

## 下单（order-create）

跨产品共用 CLI：`order-create` → WebApi `POST /orders/create`（含自动 `callback` 与打开支付页）。**FClaw 右侧面板预定走客户端直连接口，不经过本命令。**

- 面板预定：客户端创建订单并打开支付，再代发用户消息；出现「我已提交预订 / 待支付」时，AI **禁止**再跑 `order-create`，应确认并提醒支付。
- 仅当用户在对话中明确要求用 CLI 下单、且**尚未**由面板建单时，才使用：`node ./cli/index.js order-create --data '<json>'`
- **`callback` 由 CLI/客户端自动注入，禁止手写**
- 常旅客列表：`node ./cli/index.js flight-travelers`
- 护照 OCR：`node ./cli/index.js flight-passport-ocr --file <图片路径>`

详细说明见 [references/order-create.md](references/order-create.md)、[references/flight-pay.md](references/flight-pay.md)；乘机人字段见 [references/flight-passengers.md](references/flight-passengers.md)。需要核对付款状态时：`node ./cli/index.js order-pay-result --pay-id "<payid>"`。

## FClaw 订单面板（必须遵守）

验价 JSON 返回后，FClaw 会打开**右侧填写订单**面板。

1. **禁止**在聊天中向用户索要身份证号、护照号、生日等 PII。
2. 引导语示例：「验价已完成，请在右侧填写订单并点击预定。」
3. 用户点击「预定」后，客户端下单并打开支付，再代发用户消息；AI **确认摘要、提醒支付并跟进出票**，**禁止**再执行 `order-create`。
4. 支付完成后会出现用户消息「我已完成支付…」；AI **确认支付结果并继续跟进出票**。
5. 回复只用脱敏摘要，**禁止**复述完整证件号。
6. OCR 结果仅作预填，须用户确认后再提交。

## CLI 参数优先（必须遵守）

用户提出的筛选、排序、价格区间、舱位、航司等条件，**必须尽量映射为 CLI 参数传给命令**，由服务端/API 过滤；**禁止**在拿到 JSON 结果后再自行筛选、排序或丢弃不符合条件的条目。

1. **先查参数表**：执行前阅读 [references/flight-search.md](references/flight-search.md) 中的「参数」与「自然语言 → CLI 参数」。
2. **相对日期先换算**：「下周四」「3 天后回」等，先运行 `date +%Y-%m-%d` 取得今天，再算出 `--dep-date`、`--back-date`。
3. **一次搜索带齐条件**：用户给了价格区间，第一次 `flight-search` 就要带 `--min-price` / `--max-price`。

| 用户常见意图 | 对应 CLI 参数 |
| --- | --- |
| 往返 / N 天后回 | `--back-date` |
| 经济舱 / 公务舱 / 头等舱 | `--berth-type Y/C/F` |
| 价格 X–Y / 预算 | `--min-price` / `--max-price` |
| 指定航司 | `--airlines`（IATA 二字码，逗号分隔） |
| 成人 / 儿童人数 | `--adult-qty` / `--child-qty` |
| 大型机 / 行李件数 | `--aircraft-type` / `--baggage-piece-require` |
| 确认这班 / 验价 / 订这班 | 先确保已有 `id`，再 `flight-verify --id` |

## 日期规则

- `--dep-date` 格式为 `YYYY-MM-DD`，且不能早于今天。
- `--back-date` 格式为 `YYYY-MM-DD`，且不能早于 `--dep-date`。

需要当前日期时，先运行：

```bash
date +%Y-%m-%d
```

## 舱位等级

- `Y`：经济舱
- `C`：公务舱
- `F`：头等舱

## FClaw 右侧面板展示（必须遵守）

FClaw 会从 `flight-search` 的 JSON 结果自动打开**右侧航班列表面板**，用户点击卡片后会将选择（含方案 `id`）回写到聊天继续对话。

因此，向用户回复时：

1. **禁止**在聊天中逐条列出航班详情、Markdown 表格或大段清单。
2. **禁止**编造预订链接或导流 URL；用户通过右侧面板选择，不需要导流链接。
3. **禁止**把原始 JSON 原封不动贴给用户。
4. 只输出**简短中文引导**，例如：
   - 「已为您筛选出 N 个航班方案，请在右侧列表中点击选择。」
   - 「暂未查到符合条件的产品，可调整日期或价格区间后重试。」
5. 可在引导语中概括筛选条件（出发/到达/日期），但**不要**重复右侧面板已有的起降时间、航司、价格等明细。
6. 用户从右侧面板选中方案后，执行 `flight-verify --id <id>` 验价，再基于验价结果向用户报价；**不要**再次罗列全部候选。

## 验价后报价（必须遵守）

- 以 `flight-verify` 返回的 `totalPrice`、`basePrice`、`tax` 为准，**不要**继续使用搜索时的价格。
- `priceChanged` 为 `true` 时，明确告知用户价格已变动。
- 说明 `briefRule`（退改行李）与 `ticketInstructions`（出票说明）要点。
- **禁止**编造 CLI 未返回的价格、座位或规则。

## 预订与导流规则

- **禁止**向用户推荐或引导至携程、去哪儿、飞猪、同程、美团等任何第三方 OTA 或竞品平台预订。
- CLI 无结果或搜索/验价失败时，如实说明未查到或需重新搜索；**不要**用「去其他 App/网站订」作为替代方案。
- 不得编造 CLI 未返回的产品、价格或库存信息。