酒店预订助手

分贝通酒店预定助手，实时查询搜索酒店、展示酒店列表、查询酒店房型、展示房型产品和报价、预定酒店、查看订单、取消订单、查看酒店基础信息和酒店评论信息。

Security Scan

This skill appears to implement the described hotel search/booking functionality and its requirements are largely coherent, but there are a few implementation details (hard-coded test token, token persistence, and a payment URL that embeds tokens) you should review before use.

Purpose & Capability

Name/description match the included code and SKILL.md: the package provides search, price/query, detail, comments, create/cancel/query order functionality against the fenbeitong endpoint. Required binary (python3) is reasonable for this Python skill.

Instruction Scope

Runtime instructions are focused on the hotel's API and require using scripts/fb_hotel_api.py. They mandate saving/reading an access token at ~/.fbt-auth.json (expected). The SKILL.md explicitly forbids fabricating data and instructs to call only the API wrapper functions — this keeps scope tight. Note: SKILL.md / API spec indicate payment redirect URLs that may include the access token as a query parameter (potential token leakage via referer/logs).

Install Mechanism

No install spec is provided (instruction-only), but the skill includes Python code files and a requirements.txt. That is coherent but means dependencies (requests, pyyaml, python-dotenv) may not be automatically installed by the platform; runtime will require python and those libraries to be present. No downloads from unknown URLs or extract/install steps are present.

Credentials

The skill requests no environment variables and does not ask for unrelated credentials. It persists an access token to ~/.fbt-auth.json — expected for this use case. Two points to review: 1) there is a hard-coded DEFAULT_ACCESS_TOKEN (test token) in the code, which means the client will fall back to this token if no saved token is present; 2) documentation shows a payment redirect URL that can include the access token in the query string, which can expose tokens in logs/referrers if used as-is.

Persistence & Privilege

The skill writes only to its own auth file (~/.fbt-auth.json) for token persistence and does not request always:true or system-wide config changes. It does not modify other skills' configs or claim elevated privileges.

Assessment

This skill is coherent with its stated hotel-booking purpose, but take these precautions before installing: (1) review and, if desired, remove or replace the hard-coded DEFAULT_ACCESS_TOKEN in scripts/fb_hotel_api.py so the skill cannot silently use a fallback token; (2) be aware the skill saves your access token to ~/.fbt-auth.json — protect that file (it grants API access); (3) note the payment redirect URL format may embed the token in the query string (token leakage risk via referer or logs), so confirm how payment links are used or sanitize tokens before building URLs; (4) ensure the runtime environment has the dependencies in requirements.txt installed (requests, pyyaml, python-dotenv) since there is no automated install step; (5) if you need higher assurance, inspect network calls in a controlled environment (or review the server-side API behavior) to confirm no unexpected endpoints are contacted. If you want, I can show exact lines that reference DEFAULT_ACCESS_TOKEN and the payment URL so you can change them.

分贝通酒店预定助手 (fb-hotel-skill)

技能描述

分贝通酒店预定助手，实时查询搜索酒店、展示酒店列表、查询酒店房型、展示房型产品和报价、预定酒店、查看订单、取消订单、查看酒店基础信息和酒店评论信息。

---

🔐 鉴权流程（必须先完成）

重要：使用任何功能前，用户必须先完成鉴权流程。鉴权成功后获得的 identity_code（access-token）会自动保存在 ~/.fbt-auth.json 文件中，新会话会自动沿用。

鉴权步骤

步骤 1：发送验证码

用户回复: 分贝通登录
AI: 请输入您的手机号以接收验证码（例如：13800138000）

用户输入: 13800138000
AI: ✅ 验证码已发送到 138****8000，请在5分钟内输入验证码

API调用：

from scripts.fb_hotel_api import send_verification_code

result = send_verification_code("13800138000")
# 成功响应: {"code": 0, "msg": "success", "data": true}

步骤 2：验证并获取 identity_code

用户输入: 1234
AI: 🎉 认证成功！身份编码已保存到 ~/.fbt-auth.json，有效期90天
    现在可以使用分贝通企业接口了

API调用：

from scripts.fb_hotel_api import verify_and_get_token

success, result = verify_and_get_token("13800138000", "1234")
if success:
    access_token = result  # fbsk-xxx
    # token 已自动保存到 ~/.fbt-auth.json
else:
    print(f"验证失败: {result}")

步骤 3：自动注入（后续调用）

后续所有 API 调用会自动从 ~/.fbt-auth.json 读取 token：

from scripts.fb_hotel_api import FbHotelApi

# 无需传入 token，自动从文件读取
api = FbHotelApi()
result = api.search_hotel_list(city_name="北京市", keywords="国贸")

Token 存储管理

文件	路径	说明
鉴权文件	~/.fbt-auth.json	保存 identity_code 和手机号

文件格式：

{
  "identity_code": "fbsk-2db251f6c8d74ce69ae3dcb82ed1055b",
  "mobile": "138****8000",
  "created_at": "2026-03-25T09:48:00",
  "updated_at": "2026-03-25T09:48:00"
}

API 函数

from scripts.fb_hotel_api import (
    save_auth_token,    # 保存 token
    load_auth_token,    # 读取 token
    get_auth_info,      # 获取完整认证信息
    clear_auth_token    # 清除认证信息
)

# 保存 token
save_auth_token("fbsk-xxx", "13800138000")

# 读取 token
token = load_auth_token()

# 获取完整信息
info = get_auth_info()  # {"identity_code": "...", "mobile": "..."}

# 清除认证
clear_auth_token()

接口鉴权说明

skill_type	接口名称	需要认证
getMobileCaptcha	获取手机号验证码	❌ 否
getIdentityCode	获取身份编码	❌ 否
searchHotelList	搜索酒店列表	✅ 是
queryHotelPrice	查询酒店价格详情	✅ 是
queryHotelDetail	查询酒店扩展详情	✅ 是
queryHotelComment	查询酒店评论	✅ 是
createOrder	酒店下单	✅ 是
cancelOrder	取消订单	✅ 是
queryOrder	查询订单	✅ 是

---

⚠️ 【重要约束】

• 必须调用 scripts/fb_hotel_api.py 中的函数获取数据
• 禁止自行编造酒店信息、价格或评论
• 接口返回什么数据就展示什么，不要修改
• 首次使用必须先完成分贝通企业认证

---

对接信息

环境配置

环境	域名
FAT 测试环境	https://app-gate.fenbeitong.com
线上环境	https://app-gate.fenbeitong.com

统一接口入口

所有接口统一使用同一入口：

POST /business/hotel/open/push/skill/access

通过 skill_type 参数区分不同操作。

请求格式

Headers:

Content-Type: application/json
access-token: fbsk-xxx  （认证类接口除外）

Body:

{
    "skill_type": "searchHotelList",
    // 其他参数...
}

---

核心接口列表

一、认证类接口

1. 获取手机号验证码

skill_type: getMobileCaptcha

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"getMobileCaptcha",
    "mobile":"18301187051"
}'

响应示例：

{
    "request_id": "nQabT9pHt5u5m0mA",
    "code": 0,
    "msg": "success",
    "data": true
}

2. 获取身份编码

skill_type: getIdentityCode

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"getIdentityCode",
    "mobile":"18301187051",
    "captcha":"1234"
}'

响应示例：

{
    "request_id": "oKXv9eCYuFIXoxRn",
    "code": 0,
    "msg": "success",
    "data": {
        "identity_code": "fbsk-2db251f6c8d74ce69ae3dcb82ed1055b"
    }
}

---

二、酒店查询接口

1. 搜索酒店列表

skill_type: searchHotelList

请求参数：

参数	类型	必填	说明
city_name	string	是	城市名称（如"北京市"）
keywords	string	否	关键词（用户输入原样传递）
hotel_name	string	否	酒店名称
page_index	int	否	页码，默认1
page_size	int	否	每页数量，默认5

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"searchHotelList",
    "city_name":"北京市",
    "keywords":"预订北京国贸附近1公里的酒店",
    "page_index":1,
    "page_size":5
}'

响应字段：

字段	说明
hotel_id	酒店ID
name	酒店名称
star_level_name	星级类型（高档型、豪华型等）
address	地址
district_name	区域
business_zone_name	商圈
score	评分
min_price	最低价
main_logo	酒店图片

2. 查询酒店价格详情

skill_type: queryHotelPrice

请求参数：

参数	类型	必填	说明
hotel_id	string	是	酒店ID
check_in_date	string	是	入住日期 yyyy-MM-dd
check_out_date	string	是	退房日期 yyyy-MM-dd
payment_type	string	否	支付方式 PP=预付 SP=现付
nation_type	int	否	1=国内 2=国际

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryHotelPrice",
    "nation_type":1,
    "payment_type":"PP",
    "hotel_id":"5a39df2fbbfdc4732360eaa9",
    "check_in_date":"2026-03-27",
    "check_out_date":"2026-03-28"
}'

响应字段：

字段	说明
hotel	酒店基本信息
rooms[]	房型列表
rooms[].room_id	房型ID
rooms[].room_name	房型名称
rooms[].bed_type	床型
rooms[].window_type	窗户类型
rooms[].area	面积
rooms[].status	是否可预订
rooms[].plan_list[]	产品列表
plan_list[].plan_id	产品ID
plan_list[].plan_name	产品名称
plan_list[].breakfast	早餐
plan_list[].cancel_type	取消政策类型
plan_list[].cancel_rule	取消政策详情
plan_list[].total_price	总价
plan_list[].status	是否可预订

3. 查询酒店扩展详情

skill_type: queryHotelDetail

请求参数：

参数	类型	必填	说明
hotel_id	string	是	酒店ID

4. 查询酒店评论

skill_type: queryHotelComment

请求参数：

参数	类型	必填	说明
hotel_id	string	是	酒店ID
page_index	int	否	页码
page_size	int	否	每页数量

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryHotelComment",
    "hotel_id":"8502475",
    "page_size":5
}'

---

三、订单接口

1. 酒店下单

skill_type: createOrder

请求参数：

参数	类型	必填	说明
nation_type	int	是	1=国内 2=国际
payment_type	string	是	PP=预付 SP=现付
hotel_id	string	是	酒店ID
check_in_date	string	是	入住日期
check_out_date	string	是	退房日期
room_id	string	是	房型ID
plan_id	string	是	产品ID
total_price	float	是	总价
room_count	int	是	房间数
contact	object	是	联系人信息
guestList1	array	是	入住人列表（二维数组）

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"createOrder",
    "nation_type":1,
    "payment_type":"PP",
    "hotel_id":"5a39df2fbbfdc4732360eaa9",
    "check_in_date":"2026-03-27",
    "check_out_date":"2026-03-28",
    "room_id":"7617d7bbb3a94537a58bb3d33108b429",
    "plan_id":"69c23ae4e37c7d156e3e0c01",
    "total_price":280,
    "room_count":1,
    "contact":{
        "name":"周聪",
        "phone":"18301187051"
    },
    "guestList1":[
        [
            {
                "name":"周聪",
                "phone":"13126525502"
            }
        ]
    ]
}'

重要：guestList1 参数必须为二维数组格式！

2. 取消订单

skill_type: cancelOrder

请求参数：

参数	类型	必填	说明
order_id	string	是	订单ID
cancel_reason	string	否	取消原因

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"cancelOrder",
    "order_id": "69c23b67e37c7d156e3e0c1b",
    "cancel_reason":"取消原因"
}'

3. 查询订单

skill_type: queryOrder

请求参数：

参数	类型	必填	说明
order_id	string	是	订单ID

请求示例：

curl --location 'https://app-gate.fenbeitong.com/business/hotel/open/push/skill/access' \
--header 'access-token: fbsk-2db251f6c8d74ce69ae3dcb82ed1055b' \
--header 'Content-Type: application/json' \
--data '{
    "skill_type":"queryOrder",
    "order_id": "69c23b67e37c7d156e3e0c1b"
}'

---

四、收银台支付

订单创建成功后，通过以下链接引导用户完成支付：

类型	链接格式
立即支付	{域名}/business/hotel/open/push/redirect?orderId={order_id}&type=0&token={access_token}
查看订单	{域名}/business/hotel/open/push/redirect?orderId={order_id}&type=1&token={access_token}

FAT环境示例：

• 支付：https://app-gate.fenbeitong.com/business/hotel/open/push/redirect?orderId={order_id}&type=0&token=fbsk-xxx
• 订单：https://app-gate.fenbeitong.com/business/hotel/open/push/redirect?orderId={order_id}&type=1&token=fbsk-xxx

---

使用流程

1. 酒店搜索

触发条件：用户输入「酒店搜索/订酒店/找酒店/搜酒店」+ 城市/关键词

步骤：

1. 检查用户认证状态
2. 调用 search_hotel_list() 获取酒店列表
3. 格式化展示酒店列表（表格形式）

展示格式：

🏨 北京国贸附近酒店

| 序号 | 酒店名称 | 星级 | 区域 | 最低价 |
|:---:|---------|:---:|------|---:|
| 1 | 北京建国饭店 | 高档型 | 朝阳区 | ¥572 |
| 2 | 北京共享际5L饭店 | 高档型 | 朝阳区 | ¥712 |

💡 回复序号查看房型价格，如"1"
💡 回复"序号-详情"查看酒店信息和评论，如"1-详情"

2. 查看房型价格

触发条件：用户回复序号（如"1"）

步骤：

1. 获取酒店ID（从之前的搜索结果）
2. 调用 query_hotel_price() 获取房型和产品
3. 过滤 status=false 的房型和产品
4. 展示前5个房型，每个房型展示前5个产品

展示格式：

🏨 汉庭酒店(北京长虹桥店)
📍 农展馆南里12号院5号楼 | ⭐4.8分 | 经济型
📅 入住：2026-03-27 → 退房：2026-03-28

**房型1：测试房型**
床型：2张1.80m大床 | 窗户：有窗 | 面积：22㎡
| 序号 | 价格 | 早餐 | 取消政策 | 取消详情 |
|:---:|---:|:---:|:---:|---|
| 1-1 | ¥1 | 单早 | ✅限时取消 | 3月26日 12:00前免费取消... |

💡 回复"房型序号-产品序号"预订，如"1-1"

3. 创建订单

触发条件：用户回复"房型序号-产品序号"（如"1-1"）

步骤：

1. 收集入住人信息（姓名、手机号）
2. 构建请求参数（注意 guestList1 为二维数组）
3. 调用 create_order() 创建订单
4. 展示订单信息和支付链接

展示格式：

✅ 订单创建成功！

🏨 订单号：69c23b67e37c7d156e3e0c1b
📅 入住：2026-03-27 → 退房：2026-03-28
🛏️ 房型：测试房型
💰 价格：¥280
📋 最晚取消时间：2026-03-26 12:00:00

🔗 [立即支付](https://app-gate.fenbeitong.com/...)
🔗 [查看订单详情](https://app-gate.fenbeitong.com/...)

---

Python API 参考

from scripts.fb_hotel_api import FbHotelApi, send_verification_code, verify_and_get_token

# 初始化（使用默认token或指定token）
api = FbHotelApi(access_token="fbsk-xxx")

# 发送验证码
result = send_verification_code("13800138000")

# 验证并获取token
success, token = verify_and_get_token("13800138000", "1234")

# 搜索酒店
result = api.search_hotel_list(
    city_name="北京市",
    keywords="国贸附近",
    page_size=5
)

# 查询酒店价格
result = api.query_hotel_price(
    hotel_id="5a39df2fbbfdc4732360e860",
    check_in_date="2026-03-27",
    check_out_date="2026-03-28"
)

# 查询酒店扩展详情
result = api.query_hotel_detail(hotel_id="5a39df2fbbfdc4732360e860")

# 查询酒店评论
result = api.query_hotel_comment(hotel_id="8502475", page_size=5)

# 创建订单
result = api.create_order(
    hotel_id="5a39df2fbbfdc4732360eaa9",
    room_id="7617d7bbb3a94537a58bb3d33108b429",
    plan_id="69c23ae4e37c7d156e3e0c01",
    check_in_date="2026-03-27",
    check_out_date="2026-03-28",
    total_price=280,
    contact={"name": "张三", "phone": "13800138000"},
    guest_list=[[{"name": "张三", "phone": "13800138000"}]]
)

# 查询订单
result = api.query_order(order_id="69c23b67e37c7d156e3e0c1b")

# 取消订单
result = api.cancel_order(order_id="69c23b67e37c7d156e3e0c1b", cancel_reason="不想要了")

# 格式化输出
print(api.format_hotel_list(result))
print(api.format_hotel_price(result, "2026-03-27", "2026-03-28"))

---

📝 格式化输出模块

文件位置：scripts/formatter.py

展示配置

配置项	默认值	说明
HOTEL_LIST_LIMIT	5	酒店列表展示数量
ROOM_LIST_LIMIT	5	房型展示数量
PLAN_LIST_LIMIT	5	每个房型展示的产品数量

格式化函数

from scripts.formatter import (
    format_hotel_list,      # 酒店列表格式化
    format_hotel_rooms,     # 房型价格格式化
    format_order_result,    # 订单创建结果格式化
    format_trip_plan,       # 行程规划格式化
    format_order_confirmation,  # 订单确认格式化
    format_order_detail_full    # 完整订单详情格式化
)

展示字段规范

酒店列表必须包含：

• 序号、酒店名称、评分、星级、地址、最低价

房型价格必须包含：

• 序号、房型名称、床型、面积、窗户类型
• 价格、早餐、取消政策类型、取消详情

订单详情必须包含：

• 订单号、酒店信息、房型信息
• 床型、面积、窗户、早餐、价格
• 取消政策类型和详情
• [立即支付] 按钮（不是"查看订单详情"）

---

版本历史

版本	日期	变更说明
3.1.0	2026-03-25	新增格式化输出模块，固化展示逻辑
3.0.0	2026-03-25	统一接口入口，新增认证流程，重构API
2.9.1	2026-03-20	修复订单创建问题
1.9.1	2026-03-15	新增酒店评论查询