Skill: ryan-zry/fbt-flight (version 1.0.0)

--- name: fbt-flight description: 分贝通机票助手 - 实现国内航班搜索、舱位查询、预订下单、机票改期、机票退票。适用于用户询问航班、查询机票价格、提交机票订单、改期航班、退票时使用。 version: 1.0.0 metadata: {"openclaw": {"emoji": "✈️", "category": "travel", "tags": ["分贝通", "机票", "航班", "预订", "改期", "退票"], "requires": {"bins": ["python3"]}, "required": true}} --- # 分贝通机票助手 当用户询问航班搜索、舱位查询、机票预订、机票改期或机票退票时，使用此 skill 调用分贝通机票服务。 ## 运行环境要求 本 skill 通过 **python3** 执行 HTTP POST 请求调用分贝通机票服务。**运行环境必须提供 python3**。 ## 隐私与个人信息（PII）说明 预订功能会将用户提供的**个人信息**（乘客姓名、手机号、证件号等）通过 HTTP POST 发送至分贝通机票服务，以完成机票预订。使用本 skill 即表示用户知晓并同意上述 PII 被发送到外部服务。请勿在日志或回复中暴露用户个人信息。 ## 可用工具 **重要**：下方示例中的参数均为占位，调用时需**根据用户当前需求**填入实际值（城市、日期、航班号、乘机人、联系方式等），勿直接照抄示例值。 ## 适用场景 - 按出发/到达城市、日期搜索航班列表 - 查看指定航班的舱位价格详情 - 用户确认后创建机票预订订单 - 查询已创建订单的详细信息 - 用户确认后改期或退票已创建订单的航班 ## 鉴权流程（必须先完成） **重要**：使用任何功能前，用户必须先完成鉴权流程。鉴权成功后获得的 apiKey 会自动保存在用户主目录的 `~/.fbt_auth.json` 文件中，新会话会自动沿用。 ### 鉴权步骤 1. **发送验证码**：用户提供手机号，系统发送验证码到手机 2. **验证并获取 apiKey**：用户输入验证码，验证成功后获得 apiKey 3. **自动注入**：后续所有 API 调用会自动携带 apiKey ### 鉴权命令 #### 1. 发送验证码 ```bash python3 scripts/auth.py send <phone> ``` **示例**： ```bash python3 scripts/auth.py send 13800138000 ``` #### 2. 验证并获取 apiKey ```bash python3 scripts/auth.py verify <phone> <code> ``` **示例**： ```bash python3 scripts/auth.py verify 13800138000 123456 ``` #### 3. 查看鉴权状态 ```bash python3 scripts/auth.py status ``` ### 鉴权检查规则 - 在执行任何航班查询、预订、改期、退票操作前，必须先检查鉴权状态 - 如果未鉴权或 apiKey 已过期，必须引导用户完成鉴权流程 - 鉴权成功后，所有 API 调用会自动携带 apiKey，无需手动传递 ### 1. 航班搜索 (searchFlight) **功能**：查询国内航班列表 **必填参数**： - `start_code`: 出发城市名称（如 北京、上海、广州） - `end_code`: 到达城市名称 - `date`: 出发日期（格式 YYYY-MM-DD） **触发词**：某地到某地航班、查机票、搜航班、机票价格 **执行命令**： ```bash python3 scripts/search_flights.py <start_code> <end_code> <date> ``` **示例**： ```bash python3 scripts/search_flights.py 北京 上海 2026-03-15 ``` **返回结果**：航班列表（航班号、航空公司、起降时间、机型、机场、最低价等） **上下文检查规则**： - 如果用户在当前或之前的消息中已经提供了某个参数，则**无需再次询问**该参数 - 只向用户询问**尚未提供**的参数 - 如果所有参数都已提供，直接发起请求 **展示要求**: - 必须使用代码块包裹脚本输出的表格 - 必须展示完整表格 - 参考"输出格式要求"章节的标准格式 ### 2. 舱位详情查询 (searchPrice) **功能**：查询特定航班的详细价格信息 **必填参数**： - `start_code`: 出发机场三字码（从 searchFlight 响应结果中获取） - `end_code`: 到达机场三字码（从 searchFlight 响应结果中获取） - `date`: 出发日期（格式 YYYY-MM-DD） - `flight_no`: 航班号 **触发词**：查看航班详情、这个航班的舱位价格 **执行命令**： ```bash python3 scripts/search_price.py <start_code> <end_code> <date> <flight_no> ``` **示例**： ```bash python3 scripts/search_price.py PEK PVG 2026-03-15 CA1501 ``` **返回结果**：该航班的各舱位价格、折扣、退改签规则等详细信息，并将舱位信息保存到 `/tmp/flight_seat_items.json` 供下单使用 **使用场景**：用户先使用航班搜索查询航班列表，从返回的航班列表中选择某个航班后，使用此功能查询该航班的详细价格信息 **展示要求**: - 必须使用代码块包裹脚本输出的表格 - 必须展示完整表格 - 参考"输出格式要求"章节的标准格式 ### 3. 退改规则和行李额查询 (searchGuestRule) **功能**：查询指定舱位的详细退改签规则和行李额 **必填参数**： - `seat_index`: 舱位编号（从舱位详情查询结果中选择，如 1、2、3） **触发词**：退改规则、退票规则、改签规则、这个舱位的退改政策、行李额、客规 **执行命令**： ```bash python3 scripts/search_guest_rule.py <seat_index> ``` **示例**： ```bash python3 scripts/search_guest_rule.py 1 ``` **返回结果**：该舱位的退票、改签、行李额等详细规则说明 **重要说明**： - 此功能为**可选流程**，仅在用户明确询问退改规则时调用 - `seat_index` 必须来自最近一次舱位详情查询的结果 - 舱位信息从 `/tmp/flight_seat_items.json` 文件中读取 - 如果文件不存在或舱位编号无效，会提示用户先执行舱位详情查询 ### 4. 机票下单 (createOrder) **功能**：创建机票订单 **必填参数**： - `seat_index`: 舱位编号（从上一步舱位详情查询结果中选择，如 1、2、3） - `passenger_name`: 乘客姓名 - `passenger_phone`: 乘客手机号 - `passenger_id`: 乘客证件号 **触发词**：订这个、预订、下单 **执行命令**： ```bash python3 scripts/create_order.py <seat_index> <passenger_name> <passenger_phone> <passenger_id> ``` **示例**： ```bash python3 scripts/create_order.py 1 "张三" "13800138000" "110101199001011234" ``` **返回结果**：订单号、支付链接、订单详情链接等 **重要说明**： - `seat_index` 必须来自最近一次舱位详情查询的结果 - 舱位信息从 `/tmp/flight_seat_items.json` 文件中读取 - 如果文件不存在或舱位编号无效，会提示用户先执行舱位详情查询 - **必须向用户索取**乘客姓名、手机号和证件号，不可使用默认值或跳过 ### 5. 订单详情查询 (orderDetail) **功能**：查询已创建订单的详细信息 **必填参数**： - `order_id`: 订单号（从下单接口返回的订单号中获取） **触发词**：订单详情、查看订单、查询订单、订单状态 **执行命令**： ```bash python3 scripts/order_detail.py <order_id> ``` **示例**： ```bash python3 scripts/order_detail.py 69a677bee4b0252bd532e35c ``` **返回结果**：订单的详细信息，包括航班信息、乘客信息、支付状态等 **重要说明**： - 订单号可以从下单接口的返回结果中获取 - 此功能可用于查询订单的实时状态和详细信息 ### 6. 取消订单 (cancelOrder) **功能**：取消待支付状态的订单 **必填参数**： - `order_id`: 订单号（从下单接口返回的订单号中获取） **触发词**：取消订单、不要了、取消这个订单 **执行命令**： ```bash python3 scripts/cancel_order.py <order_id> ``` **示例**： ```bash python3 scripts/cancel_order.py 69a677bee4b0252bd532e35c ``` **返回结果**：取消成功或失败 **重要说明**： - 此功能仅适用于待支付状态的订单 - 订单号可以从下单接口的返回结果中获取 - 已支付或已出票的订单无法通过此接口取消，需要使用退票功能 ### 7. 改期航班搜索 (endorseSearchFlight) **功能**：查询可改期的航班列表 **必填参数**： - `order_id`: 订单号（从订单详情或下单接口返回的订单号中获取） - `dep_date`: 改期日期（格式 YYYY-MM-DD，需要向用户索取） **触发词**：改期、改签、换航班、查改期航班 **执行命令**： ```bash python3 scripts/endorse_search_flight.py <order_id> <dep_date> ``` **示例**： ```bash python3 scripts/endorse_search_flight.py 69a677bee4b0252bd532e35c 2026-03-20 ``` **返回结果**：可改期的航班列表（航班号、航空公司、起降时间、机场、最低价等） **重要说明**： - 订单号可以从订单详情接口获取 - 改期日期需要向用户索取 - 此接口会自动从订单详情中提取 flight_no（从 segmentInfo.flight_no 获取）和 ticket_ids（从 passengerList[0].productId 获取） - 返回的航班列表格式与航班搜索接口一致，方便用户选择 **展示要求**: - 必须使用代码块包裹脚本输出的表格 - 必须展示完整表格 - 参考"输出格式要求"章节的标准格式 ### 8. 改期舱位详情查询 (endorseSearchPrice) **功能**：查询指定改期航班的舱位价格详情（改期费、机票差价费等） **必填参数**： - `order_id`: 订单号（从订单详情或下单接口返回的订单号中获取） - `dep_date`: 改期日期（格式 YYYY-MM-DD，与改期航班搜索时使用的日期一致） - `flight_no`: 航班号（从改期航班搜索结果中选择） **触发词**：查看改期价格、这个航班的改期费、改期舱位详情 **执行命令**： ```bash python3 scripts/endorse_search_price.py <order_id> <dep_date> <flight_no> ``` **示例**： ```bash python3 scripts/endorse_search_price.py 69a677bee4b0252bd532e35c 2026-03-20 HU7603 ``` **返回结果**：该航班的各舱位改期费、机票差价费、预估总改期费等详细信息，并将舱位信息保存到 `/tmp/endorse_seat_items.json` 供改期下单使用 **重要说明**： - 此接口必须在改期航班搜索之后调用 - flight_no 必须来自改期航班搜索返回的航班列表，需要用户选择 - 此接口会自动从订单详情中提取 ticket_ids（从 passengerList[0].productId 获取） - 展示的改期费用信息包括：改期费、机票差价费、预估总改期费 - 舱位信息会保存到临时文件供后续改期下单使用 **展示要求**: - 必须使用代码块包裹脚本输出的表格 - 必须展示完整表格 - 参考"输出格式要求"章节的标准格式 ### 9. 提交改期申请 (endorseApply) **功能**：提交改期申请，创建改期订单 **必填参数**： - `seat_index`: 舱位编号（从改期舱位详情查询结果中选择，如 1、2、3） - `order_id`: 原订单号（从订单详情或下单接口返回的订单号中获取） **触发词**：确认改期、提交改期申请、改期下单 **执行命令**： ```bash python3 scripts/endorse_apply.py <seat_index> <order_id> ``` **示例**： ```bash python3 scripts/endorse_apply.py 1 69a677bee4b0252bd532e35c ``` **返回结果**：改期单订单号、支付链接、订单详情链接等 **重要说明**： - `seat_index` 必须来自最近一次改期舱位详情查询的结果 - 舱位信息从 `/tmp/endorse_seat_items.json` 文件中读取 - 如果文件不存在或舱位编号无效，会提示用户先执行改期舱位详情查询 - 改期申请成功后会返回新的改期单订单号，需要用户完成支付 ### 10. 预估退票费查询 (refundFeeDetail) **功能**：查询退票费用详情 **必填参数**： - `order_id`: 订单号（从订单详情或下单接口返回的订单号中获取） **触发词**：查询退票费、退票费用、预估退票费 **执行命令**： ```bash python3 scripts/refund_fee_detail.py <order_id> ``` **示例**： ```bash python3 scripts/refund_fee_detail.py 69a677bee4b0252bd532e35c ``` **返回结果**：预估退票费（单票） **重要说明**： - 此接口用于在退票前预估退票费用 - 用户需要确认退票费用后才能提交退票申请 - 返回的 refund_amount 需要在提交退票申请时使用 ### 11. 提交退票申请 (refundApply) **功能**：提交退票申请 **必填参数**： - `order_id`: 订单号（从订单详情或下单接口返回的订单号中获取） - `refund_amount`: 预估退票费（从预估退票费查询接口返回的 refund_amount 获取） **触发词**：确认退票、提交退票申请、退票 **执行命令**： ```bash python3 scripts/refund_apply.py <order_id> <refund_amount> ``` **示例**： ```bash python3 scripts/refund_apply.py 69a677bee4b0252bd532e35c 808 ``` **返回结果**：退票申请结果、退票单号 **重要说明**： - 此接口必须在预估退票费查询之后调用 - refund_amount 必须来自预估退票费查询接口返回的 refund_amount - product_ids 会自动从订单详情中获取（从 passengerList 中提取 productId） - 退票申请提交后需要等待审核 ## 完整流程示例 **用户**：3月15号北京到上海的航班 **AI 执行**： 1. 检查上下文，发现用户已提供出发城市（北京）、到达城市（上海）、日期（3月15号） 2. 调用 `search_flights.py 北京 上海 2026-03-15` 3. 展示航班列表 **用户**：看一下 CA1501 这个航班的舱位 **AI 执行**： 1. 从上一轮结果确认航班号 CA1501，连同城市和日期 2. 调用 `search_price.py PEK PVG 2026-03-15 CA1501` 3. 展示舱位列表（价格、退改签规则等） 4. 提示用户可选择舱位编号进行预订 **用户**：第1个舱位的退改规则是什么？（可选步骤） **AI 执行**： 1. 调用 `search_guest_rule.py 1` 2. 展示该舱位的详细退改签规则 **用户**：订第1个，乘客张三 13800138000 110101199001011234 **AI 执行**： 1. 从用户输入提取：seat_index=1、passenger_name=张三、passenger_phone=13800138000、passenger_id=110101199001011234 2. 调用 `create_order.py 1 "张三" "13800138000" "110101199001011234"` 3. 展示订单号、支付链接等信息 4. 提醒用户完成支付 **用户**：查看订单详情 **AI 执行**： 1. 从上一轮结果获取订单号（如：69a677bee4b0252bd532e35c） 2. 如果用户没有提供手机号，向用户索要创建订单时使用的乘机人手机号 3. 调用 `order_detail.py 69a677bee4b0252bd532e35c 13800138000` 4. 展示订单的详细信息 **用户**：取消订单 **AI 执行**： 1. 从上一轮结果获取订单号和手机号 2. 调用 `cancel_order.py 69a677bee4b0252bd532e35c 13800138000` 3. 展示取消订单成功或失败的信息 **用户**：我想改期到3月20号 **AI 执行**： 1. 从上一轮订单详情中获取订单号和手机号 2. 向用户确认改期日期（3月20号，格式化为 2026-03-20） 3. 调用 `endorse_search_flight.py 69a677bee4b0252bd532e35c 13800138000 2026-03-20` 4. 展示可改期的航班列表 **用户**：看一下 HU7603 这个航班的改期价格 **AI 执行**： 1. 从上一轮改期航班搜索结果中确认航班号 HU7603 2. 调用 `endorse_search_price.py 69a677bee4b0252bd532e35c 13800138000 2026-03-20 HU7603` 3. 展示该航班的改期舱位价格详情（改期费、机票差价费、预估总改期费等） 4. 提示用户可选择舱位进行改期 **用户**：确认改期第1个舱位 **AI 执行**： 1. 从上一轮改期舱位详情查询结果中确认舱位编号 1 2. 调用 `endorse_apply.py 1 69a677bee4b0252bd532e35c 13800138000` 3. 展示改期单订单号、支付链接、订单详情链接等信息 4. 提醒用户完成支付 **用户**：我要退票 **AI 执行**： 1. 从上一轮订单详情中获取订单号、手机号和票号 2. 调用 `refund_fee_detail.py 69a677bee4b0252bd532e35c 13800138000` 3. 展示退票费详情 4. **必须强制用户确认退票费用，无论退票费是多少（包括¥0），都不得擅自提交退票申请** **用户**：确认退票 **AI 执行**： 1. 从上一轮退票费查询结果中获取退款金额 2. 调用 `refund_apply.py 69a677bee4b0252bd532e35c 525 13800138000` 3. 展示退票状态、退票单号等信息 4. 提醒用户等待审核 ## 输出格式要求 **🚨 强制要求**: 1. 禁止用自然语言改写表格内容 2. 所有表格必须用```plaintext```代码块包裹 3. 不得省略或截断任何航班/舱位信息 ### 航班列表展示 查询结果以表格形式平铺展示，每个航班一行，只显示最低价： ``` ================================================================================================= 航班号 航空公司 出发时间 到达时间 出发机场 到达机场 最低价 ================================================================================================= HO2218 吉祥航空 08:45 10:55 大兴 虹桥 ¥470 MF8561 厦门航空 07:55 10:25 大兴 浦东 ¥490 ================================================================================================= 共找到 X 个航班 ================================================================================================= ``` ### 舱位详情展示 展示各舱位价格、折扣等详细信息，并标注舱位编号供用户选择： ``` ==================================================================================== 编号 舱位 价格 折扣 机建费 燃油费 总票价 状态 ==================================================================================== [1] 经济舱 ¥800 9.5 ¥50 ¥20 ¥870 余座充足 [2] 经济舱 ¥850 10 ¥50 ¥20 ¥920 余座充足 ==================================================================================== ``` ### 退改规则展示 展示选定舱位的详细退改签规则和行李额： ``` ==================================================================================================== 舱位信息: 经济舱 | T舱 | 票面价 ¥800 ==================================================================================================== 【退票规则】 ---------------------------------------------------------------------------------------------------- • 未使用的首个航班起飞前168小时（含）到∞小时（不含）退票时,余额再收20%退票费 ---------------------------------------------------------------------------------------------------- 【改期规则】 ---------------------------------------------------------------------------------------------------- • 起飞前168小时以上：变更费按订座舱位公布运价10%收取 ---------------------------------------------------------------------------------------------------- 【签转规则】 ---------------------------------------------------------------------------------------------------- 不能签转 ---------------------------------------------------------------------------------------------------- 【行李额】 ---------------------------------------------------------------------------------------------------- • 免费托运行李额：20KG，单件尺寸上限：40*60*100CM • 免费手提行李额：5KG，单件尺寸上限：20*40*55CM ==================================================================================================== ``` ### 订单结果展示 展示订单号、支付链接、航班信息等关键信息： ``` ✅ 订单创建成功！ 航班信息: - 航班号: CA1501 - 出发时间: 08:00 - 到达时间: 10:30 - 舱位: 经济舱 订单号: 69a677bee4b0252bd532e35c 支付截止时间: 23:59 💳 [立即支付](https://dwz.cn/TftO1qmp) ``` ### 订单详情展示 展示订单的完整信息，包括航班信息、乘客信息、支付状态等： ``` ==================================================================================== 订单详情 ==================================================================================== 订单号: 69a677bee4b0252bd532e35c 订单状态: 待支付 创建时间: 2026-03-04 10:30:00 支付截止时间: 2026-03-04 23:59:59 航班信息: - 航班号: CA1501 - 出发时间: 2026-03-15 08:00 - 到达时间: 2026-03-15 10:30 - 出发机场: 北京首都T3 - 到达机场: 上海虹桥T2 - 舱位: 经济舱 乘客信息: - 姓名: 张三 - 证件类型: 身份证 - 证件号: 110101199001011234 - 联系电话: 13800138000 - 票号: 888-1234567890 价格信息: - 票面价: ¥800 - 机建费: ¥50 - 燃油费: ¥20 - 总金额: ¥870 ==================================================================================== ``` ### 改期航班搜索展示 展示可改期的航班列表，格式与航班搜索一致： ``` ========================================================================================= 正在搜索改期航班... 原航班号: HU7601 改期日期: 2026-03-20 ========================================================================================= 航班号 航空公司 出发时间 到达时间 出发机场 到达机场 最低价 ========================================================================================= HO2218 吉祥航空 08:45 10:55 大兴 虹桥 ¥470 MF8561 厦门航空 07:55 10:25 大兴 浦东 ¥490 ========================================================================================= 共找到 2 个航班 ========================================================================================= ``` ### 改期舱位详情展示 展示指定改期航班的各舱位改期费用详情： ``` ================================================================================================================================== 航班信息: HU7603 | 08:25-10:35 | 空客A330 | T2-T2 ================================================================================================================================== 编号 舱位 改期费 机票差价费 预估总改期费 状态 ================================================================================================================================== [1] 经济舱 ¥100 ¥50 ¥150 余座充足 [2] 经济舱 ¥100 ¥100 ¥200 余座充足 ================================================================================================================================== 共找到 3 个舱位价格 ================================================================================================================================== ``` ### 改期申请结果展示 展示改期申请成功后的关键信息： ``` 改期航班信息: - 航班号: HU7603 - 出发时间: 08:25 - 到达时间: 10:35 ✅ 改期申请成功！ 改期单订单号: 69b21e1ce4b0b89fdebddbd4 💳 [立即支付](https://dwz.cn/TftO1qmp) ``` ### 退票费详情展示 展示退票费用详情： ``` 预估退票费（单票）: ¥0 请确认是否同意退票费用，如同意，系统将自动提交退票申请 ``` ### 退票申请结果展示 展示退票申请结果： ``` ================================================================================ ✅ 退票申请成功，请等待审核！ 退票单号: 69c12345e4b0c12fdeabcdef 温馨提示： - 退票审核通常需要1-3个工作日 - 退款到账时间取决于银行处理速度 - 您可以随时查询订单状态了解退票进度 ================================================================================ ``` ## 注意事项 1. **PII 安全**：乘客姓名、手机号、证件号等仅在预订时发送至服务，勿在日志或回复中暴露 2. **日期格式**：所有日期均为 YYYY-MM-DD 3. **下单前**：必须先执行舱位详情查询，获取舱位信息后才能下单 4. **强制索取信息**：下单时必须向用户索取乘客姓名、手机号和证件号，不可使用默认值或跳过 5. **数据准确性**：展示结果时必须基于脚本输出的原始数据，不得修改、添加或删除任何数据 6. **禁止幻想**：不得添加任何脚本输出中不存在的航班信息、价格或推荐内容 7. **强制确认退票**：退票时必须强制用户确认退票费用，无论退票费是多少（包括¥0），都不得擅自提交退票申请


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)