@mongoui/skills 0.1.8 → 0.1.9

package/skills/glink-hotel-api/SKILL.md

@@ -1,152 +1,153 @@
----
+---
 name: glink-hotel-api
-description: Integrate with the Glink hotel OpenAPI exposed through the Open Platform runtime gateway. Use when Codex needs to read, verify, explain, test, or implement against `docs/swagger/glink-api.json` or Glink route code; choose Glink hotel endpoints; generate or debug `X-OP-*` signatures; explain sandbox or production credential issuance/reset; or drive Chinese/English requests about Glink hotel static data, hotel search, hotel info, product detail, booking, payment, order, cancel, order status push/callback, checkout, invoice, and balance workflows.
----
-
-# Glink OpenAPI Integration
-
-## Quick Start
-
-Use this skill when the task is "call Glink through the open platform".
-
-Start with the smallest current source that answers the request:
-
-- Prefer the repository source of truth when it exists: `docs/swagger/glink-api.json`, route handlers, DTOs, and tests.
-- Treat the current DHub shared document and `docs/swagger/glink-api.json` as the route source of truth; older bundled notes can be stale.
-- Customer-facing explanations should use only our short interface paths such as `/search/destination`, `/booking/createOrder`, and `/order/orderDetail`.
+description: Integrate with the Glink hotel OpenAPI exposed through the Open Platform runtime gateway. Use when Codex needs to read, verify, explain, test, or implement against `docs/swagger/glink-api.json` or Glink route code; choose Glink hotel endpoints; generate or debug `X-OP-*` signatures; explain sandbox or production credential issuance/reset; or drive Chinese/English requests about Glink hotel static data, hotel search, hotel info, product detail, booking, payment, order, cancel, order status push/callback, checkout, invoice, and balance workflows.
+---
+
+# Glink OpenAPI Integration
+
+## Quick Start
+
+Use this skill when the task is "call Glink through the open platform".
+
+Start with the smallest current source that answers the request:
+
+- Prefer the repository source of truth when it exists: `docs/swagger/glink-api.json`, route handlers, DTOs, and tests.
+- Treat the current DHub shared document and `docs/swagger/glink-api.json` as the route source of truth; older bundled notes can be stale.
+- Customer-facing explanations should use only our short interface paths such as `/search/destination`, `/booking/createOrder`, and `/order/orderDetail`.
 - Read `references/auth-and-credentials.md` for signing, headers, key acquisition, reset, and auth troubleshooting.
 - Read `references/api-workflows.md` for hotel search, booking, cancel, checkout, invoice, and balance workflows.
 - Read `references/endpoint-index.md` for a compact endpoint map and platform-managed field caveats, then verify fragile fields against the current swagger or code.
+- Read `references/field-and-enum-notes.md` for current response-shape changes, renamed fields, enum-like values, and practical scenarios reflected by the latest swagger examples.
 - Use `scripts/glink_signed_request.py` to generate headers, inspect the canonical string, or send a signed request.
-
-## Working Rules
-
-Follow this workflow:
-
-1. Confirm the environment: `sandbox` and `production` credentials are separate.
-2. Confirm whether the user is asking for documentation, code changes, local smoke testing, or live API calls.
-3. Confirm the interface path, for example `/search/destination` or `/booking/productDetails`.
-4. Choose the integration mode before recommending a flow:
-   - Standard API Integration: for partners who build and maintain a local saleable hotel catalog and room mapping.
-   - Lightweight Integration Flow: for faster launch with destination-driven hotel discovery and less pre-synced catalog data.
-5. Keep customer-facing docs and answers aligned to our short interface paths only, such as `/search/destination`, `/booking/productDetails`, and `/order/orderDetail`.
-6. For actual gateway signing/calls, the runtime public path is the short path prefixed with `/openapi/v1/glink`. Keep that detail in tooling/auth guidance, not in customer workflow names.
-7. Build the minimum valid request body from swagger/code first, using `references/endpoint-index.md` as navigation.
-8. Sign the exact runtime public path, sorted query string, and raw body bytes with the platform secret.
-9. Evaluate both HTTP status and response envelope `code`, not HTTP status alone.
-
-When the user asks for the Open Platform Glink hotel onboarding or booking flow, choose one of these two approved integration modes and use the mandatory interface sets below.
-
-## Standard API Integration
-
-Mandatory interfaces:
-
-| No. | Interface | Method | Path |
-| --- | --- | --- | --- |
-| 1 | Available Hotel ID List | POST | `/search/hotelIdList` |
-| 2 | Query Hotel Basic Information | POST | `/hotel/detail` |
-| 3 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
-| 4 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
-| 5 | Create Order | POST | `/booking/createOrder` |
-| 6 | Order Payment | POST | `/booking/payOrder` |
-| 7 | Cancel Order | POST | `/order/cancelOrder` |
-| 8 | Order Detail Query | POST | `/order/orderDetail` |
-
-Use this sequence by default:
-
-1. Static bootstrap: `/search/hotelIdList` -> `/hotel/detail` for hotel/room static data, then persist local hotel and room mappings.
-2. Optional foundational data: `/region/countries` and `/region/cities` can be used to build country/city mappings against the FCG hotel system.
-3. Static maintenance: run `/hotel/increment`, then call `/hotel/detail` for changed hotel IDs and update or disconnect local mappings when needed.
-4. List pricing: run `/hotel/lowestPrice` for mapped hotels as list-page display/reference data. The next 30 days of daily lowest prices are updated every day; recommend updating daily after 5:00 AM.
-5. Detail pricing: call `/booking/productDetails` in real time when the customer enters the hotel detail or booking path. Before querying, check the local saleable hotel ID cache and skip hotels not in the saleable list. Prefer `bookType=1` products as bookable candidates.
-6. Booking pre-check: when the user clicks Book, call `/booking/availabilityCheck` with the actual room count to confirm the product is bookable before entering the order form.
-7. Submit order: call `/booking/availabilityCheck` again immediately before `/booking/createOrder`; if still bookable, call `/booking/createOrder`.
-8. Payment and confirmation: after `/booking/createOrder`, call `/booking/payOrder` only after local customer payment succeeds or when the platform has decided the Glink order should be confirmed.
-9. Confirmation result: treat `/notify/orderStatus` as the primary confirmation channel and make the callback idempotent. Use `/order/orderDetail` only as low-frequency compensation if no confirmation result is received.
-10. Cancellation: call `/order/cancelOrder` for unpaid timeout such as 30 minutes or active customer cancellation. If the cancellation API returns success, update the local order and stop polling.
-
-## Lightweight Integration Flow
-
-Mandatory interfaces:
-
-| No. | Interface | Method | Path |
-| --- | --- | --- | --- |
-| 1 | Destination Query | POST | `/search/destination` |
-| 2 | Get Hotel Filter Conditions | POST | `/search/hotelFilters` |
-| 3 | Query Hotel List by Destination | POST | `/search/hotelList` |
-| 4 | Query Hotel Basic Information | POST | `/hotel/detail` |
-| 5 | Query Hotel Basic Information Increment | POST | `/hotel/increment` |
-| 6 | Query Hotel Images | POST | `/hotel/images` |
-| 7 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
-| 8 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
-| 9 | Create Order | POST | `/booking/createOrder` |
-| 10 | Order Payment | POST | `/booking/payOrder` |
-| 11 | Cancel Order | POST | `/order/cancelOrder` |
-| 12 | Order Detail Query | POST | `/order/orderDetail` |
-| 13 | Order Status Push | POST | `/notify/orderStatus` |
-
-Use this sequence by default:
-
-1. Destination bootstrap: call `/search/destination` to obtain the destination ID.
-2. Discovery: optionally call `/search/hotelFilters` for filter conditions, then call `/search/hotelList` with the destination ID to obtain matching hotels.
-3. Display hydration: call `/hotel/detail` for hotel static information and `/hotel/images` for images used by the client.
-4. Static maintenance: use `/hotel/increment` to discover changed hotel static information when local caching is used.
-5. List pricing: optionally call `/hotel/lowestPrice` as list-page price reference when the product experience needs a stable starting price.
-6. Detail pricing: call `/booking/productDetails` in real time when the customer enters the hotel detail or booking path. Prefer `bookType=1` products.
-7. Booking pre-check: when the user clicks Book, call `/booking/availabilityCheck` with the actual room count before entering the order form.
-8. Submit order: call `/booking/availabilityCheck` again immediately before `/booking/createOrder`; if still bookable, call `/booking/createOrder`.
-9. Payment and confirmation: after `/booking/createOrder`, call `/booking/payOrder` only after local customer payment succeeds or when the platform has decided the Glink order should be confirmed.
-10. Confirmation result: treat `/notify/orderStatus` as the primary confirmation channel and make the callback idempotent. Use `/order/orderDetail` only as low-frequency compensation if no confirmation result is received.
-11. Cancellation: call `/order/cancelOrder` for unpaid timeout such as 30 minutes or active customer cancellation. If the cancellation API returns success, update the local order and stop polling.
-
-## Mandatory Order Placement Flow
-
-Use these calls for order placement in both integration modes:
-
-1. `/hotel/lowestPrice`: Query the lowest price of mapped hotels as a reference for whether to display the hotel in the local hotel list.
-2. `/booking/productDetails`: Called in real time when a customer enters the hotel details or booking path.
-3. `/booking/availabilityCheck`: Validate whether a bookable product can be reserved, passing in the actual number of rooms to book.
-4. `/booking/createOrder`: Called after trial booking passes and the local order is successfully created. It is recommended to perform another trial booking validation before calling.
-5. `/booking/payOrder`: Called after the local customer pays successfully, or when the order needs confirmation, to notify FCG to process the order.
-6. `/order/cancelOrder`: Called when the order is unpaid for 30 minutes or the customer actively cancels. If the interface returns success, update the local order and stop polling.
-7. `/notify/orderStatus`: After payment notification, FCG processes the order and pushes the status. This callback must support idempotency.
-8. `/order/orderDetail`: If no confirmation result is received after payment, periodic queries can be used as compensation. Frequent polling is unnecessary; stop querying once the order is confirmed or canceled.
-
-## Do Not Violate
-
-- Always send `X-OP-App-Key`, `X-OP-Timestamp`, `X-OP-Nonce`, and `X-OP-Sign`.
-- Send only the business fields defined by our Open Platform swagger.
-- For adapter code, keep internal route configuration and customer-facing interface paths clearly separated.
-- Never invent credentials or secrets. Use explicit user-provided values or environment variables.
-- Treat `code=SUCCESS` as success. Treat `code=SUPPLIER_BIZ_ERROR` as a business failure even if HTTP status is `200`.
-- Keep timestamp skew within `+-5` minutes.
-- Reuse of the same nonce under the same app key can trigger `NONCE_REPLAY`.
-- If a swagger schema still shows Glink-managed fields as required, follow the route description first and omit those platform-managed internal fields from the client payload.
-- If external reference material and the current swagger/code use different names, use our current short interface path as the source of truth.
-- Do not frequently poll order status. Stop polling once the order is confirmed or canceled; rely on idempotent push/callback handling as the source of truth for confirmation progress.
-- Do not query real-time products for hotels outside the cached saleable hotel list; it wastes integration quota and usually returns no useful sellable data.
-- For Standard API Integration, recommend local saleable hotel cache maintenance. For Lightweight Integration Flow, recommend the smaller destination-driven flow unless the user explicitly needs full static catalog sync.
-
-## Typical Requests
-
-Use these patterns by default:
-
-- Static data and filters: `/region/countries`, `/region/cities`, `/region/popularCities`, `/region/businesses`, `/region/districts`, `/region/pois`, and `/hotel/groupBrand`.
-- Standard catalog sync: `/search/hotelIdList` -> `/hotel/detail`; maintain with `/hotel/increment` -> `/hotel/detail`.
-- Lightweight discovery: `/search/destination` -> `/search/hotelFilters` -> `/search/hotelList` -> `/hotel/detail`/`/hotel/images` -> `/booking/productDetails`.
-- Search and booking: `/hotel/lowestPrice` for list display/reference -> `/booking/productDetails` for hotel detail -> `/booking/availabilityCheck` -> optional second `/booking/availabilityCheck` -> `/booking/createOrder` -> `/booking/payOrder` -> order push/callback primary, `/order/orderDetail` as compensation.
-- Order aftercare: `/order/cancelOrder`, order push/callback, `/order/orderDetail`, `/order/checkInDetail`, `/order/checkoutRequest`, `/order/checkoutDetail`.
-- Finance: `/order/invoiceRequest`, `/order/invoiceInfo`, `/search/creditBalance`.
-
-## Output Expectations
-
-When answering or coding with this skill:
-
-- Prefer concrete request examples over abstract summaries.
-- Name the source used when the current swagger/code and bundled references disagree, but keep customer-facing answers on our short interface paths.
-- State whether the recommendation follows Standard API Integration or Lightweight Integration Flow when giving onboarding advice.
-- State which environment the credential belongs to.
-- State whether the payload should contain only business fields.
-- Call out Glink-managed field residue in the swagger when relevant.
-- Call out auth failures with the likely root cause and the exact header or field to inspect.
-- For code changes, keep internal Glink integration auth and platform gateway auth clearly separated.
+
+## Working Rules
+
+Follow this workflow:
+
+1. Confirm the environment: `sandbox` and `production` credentials are separate.
+2. Confirm whether the user is asking for documentation, code changes, local smoke testing, or live API calls.
+3. Confirm the interface path, for example `/search/destination` or `/booking/productDetails`.
+4. Choose the integration mode before recommending a flow:
+   - Standard API Integration: for partners who build and maintain a local saleable hotel catalog and room mapping.
+   - Lightweight Integration Flow: for faster launch with destination-driven hotel discovery and less pre-synced catalog data.
+5. Keep customer-facing docs and answers aligned to our short interface paths only, such as `/search/destination`, `/booking/productDetails`, and `/order/orderDetail`.
+6. For actual gateway signing/calls, the runtime public path is the short path prefixed with `/openapi/v1/glink`. Keep that detail in tooling/auth guidance, not in customer workflow names.
+7. Build the minimum valid request body from swagger/code first, using `references/endpoint-index.md` as navigation.
+8. Sign the exact runtime public path, sorted query string, and raw body bytes with the platform secret.
+9. Evaluate both HTTP status and response envelope `code`, not HTTP status alone.
+
+When the user asks for the Open Platform Glink hotel onboarding or booking flow, choose one of these two approved integration modes and use the mandatory interface sets below.
+
+## Standard API Integration
+
+Mandatory interfaces:
+
+| No. | Interface | Method | Path |
+| --- | --- | --- | --- |
+| 1 | Available Hotel ID List | POST | `/search/hotelIdList` |
+| 2 | Query Hotel Basic Information | POST | `/hotel/detail` |
+| 3 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
+| 4 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
+| 5 | Create Order | POST | `/booking/createOrder` |
+| 6 | Order Payment | POST | `/booking/payOrder` |
+| 7 | Cancel Order | POST | `/order/cancelOrder` |
+| 8 | Order Detail Query | POST | `/order/orderDetail` |
+
+Use this sequence by default:
+
+1. Static bootstrap: `/search/hotelIdList` -> `/hotel/detail` for hotel/room static data, then persist local hotel and room mappings.
+2. Optional foundational data: `/region/countries` and `/region/cities` can be used to build country/city mappings against the FCG hotel system.
+3. Static maintenance: run `/hotel/increment`, then call `/hotel/detail` for changed hotel IDs and update or disconnect local mappings when needed.
+4. List pricing: run `/hotel/lowestPrice` for mapped hotels as list-page display/reference data. The next 30 days of daily lowest prices are updated every day; recommend updating daily after 5:00 AM.
+5. Detail pricing: call `/booking/productDetails` in real time when the customer enters the hotel detail or booking path. Before querying, check the local saleable hotel ID cache and skip hotels not in the saleable list. Prefer `bookType=1` products as bookable candidates.
+6. Booking pre-check: when the user clicks Book, call `/booking/availabilityCheck` with the actual room count to confirm the product is bookable before entering the order form.
+7. Submit order: call `/booking/availabilityCheck` again immediately before `/booking/createOrder`; if still bookable, call `/booking/createOrder`.
+8. Payment and confirmation: after `/booking/createOrder`, call `/booking/payOrder` only after local customer payment succeeds or when the platform has decided the Glink order should be confirmed.
+9. Confirmation result: treat `/notify/orderStatus` as the primary confirmation channel and make the callback idempotent. Use `/order/orderDetail` only as low-frequency compensation if no confirmation result is received.
+10. Cancellation: call `/order/cancelOrder` for unpaid timeout such as 30 minutes or active customer cancellation. If the cancellation API returns success, update the local order and stop polling.
+
+## Lightweight Integration Flow
+
+Mandatory interfaces:
+
+| No. | Interface | Method | Path |
+| --- | --- | --- | --- |
+| 1 | Destination Query | POST | `/search/destination` |
+| 2 | Get Hotel Filter Conditions | POST | `/search/hotelFilters` |
+| 3 | Query Hotel List by Destination | POST | `/search/hotelList` |
+| 4 | Query Hotel Basic Information | POST | `/hotel/detail` |
+| 5 | Query Hotel Basic Information Increment | POST | `/hotel/increment` |
+| 6 | Query Hotel Images | POST | `/hotel/images` |
+| 7 | Hotel Real-Time Product Query | POST | `/booking/productDetails` |
+| 8 | Trial Booking / Availability Check | POST | `/booking/availabilityCheck` |
+| 9 | Create Order | POST | `/booking/createOrder` |
+| 10 | Order Payment | POST | `/booking/payOrder` |
+| 11 | Cancel Order | POST | `/order/cancelOrder` |
+| 12 | Order Detail Query | POST | `/order/orderDetail` |
+| 13 | Order Status Push | POST | `/notify/orderStatus` |
+
+Use this sequence by default:
+
+1. Destination bootstrap: call `/search/destination` to obtain the destination ID.
+2. Discovery: optionally call `/search/hotelFilters` for filter conditions, then call `/search/hotelList` with the destination ID to obtain matching hotels.
+3. Display hydration: call `/hotel/detail` for hotel static information and `/hotel/images` for images used by the client.
+4. Static maintenance: use `/hotel/increment` to discover changed hotel static information when local caching is used.
+5. List pricing: optionally call `/hotel/lowestPrice` as list-page price reference when the product experience needs a stable starting price.
+6. Detail pricing: call `/booking/productDetails` in real time when the customer enters the hotel detail or booking path. Prefer `bookType=1` products.
+7. Booking pre-check: when the user clicks Book, call `/booking/availabilityCheck` with the actual room count before entering the order form.
+8. Submit order: call `/booking/availabilityCheck` again immediately before `/booking/createOrder`; if still bookable, call `/booking/createOrder`.
+9. Payment and confirmation: after `/booking/createOrder`, call `/booking/payOrder` only after local customer payment succeeds or when the platform has decided the Glink order should be confirmed.
+10. Confirmation result: treat `/notify/orderStatus` as the primary confirmation channel and make the callback idempotent. Use `/order/orderDetail` only as low-frequency compensation if no confirmation result is received.
+11. Cancellation: call `/order/cancelOrder` for unpaid timeout such as 30 minutes or active customer cancellation. If the cancellation API returns success, update the local order and stop polling.
+
+## Mandatory Order Placement Flow
+
+Use these calls for order placement in both integration modes:
+
+1. `/hotel/lowestPrice`: Query the lowest price of mapped hotels as a reference for whether to display the hotel in the local hotel list.
+2. `/booking/productDetails`: Called in real time when a customer enters the hotel details or booking path.
+3. `/booking/availabilityCheck`: Validate whether a bookable product can be reserved, passing in the actual number of rooms to book.
+4. `/booking/createOrder`: Called after trial booking passes and the local order is successfully created. It is recommended to perform another trial booking validation before calling.
+5. `/booking/payOrder`: Called after the local customer pays successfully, or when the order needs confirmation, to notify FCG to process the order.
+6. `/order/cancelOrder`: Called when the order is unpaid for 30 minutes or the customer actively cancels. If the interface returns success, update the local order and stop polling.
+7. `/notify/orderStatus`: After payment notification, FCG processes the order and pushes the status. This callback must support idempotency.
+8. `/order/orderDetail`: If no confirmation result is received after payment, periodic queries can be used as compensation. Frequent polling is unnecessary; stop querying once the order is confirmed or canceled.
+
+## Do Not Violate
+
+- Always send `X-OP-App-Key`, `X-OP-Timestamp`, `X-OP-Nonce`, and `X-OP-Sign`.
+- Send only the business fields defined by our Open Platform swagger.
+- For adapter code, keep internal route configuration and customer-facing interface paths clearly separated.
+- Never invent credentials or secrets. Use explicit user-provided values or environment variables.
+- Treat `code=SUCCESS` as success. Treat `code=SUPPLIER_BIZ_ERROR` as a business failure even if HTTP status is `200`.
+- Keep timestamp skew within `+-5` minutes.
+- Reuse of the same nonce under the same app key can trigger `NONCE_REPLAY`.
+- If a swagger schema still shows Glink-managed fields as required, follow the route description first and omit those platform-managed internal fields from the client payload.
+- If external reference material and the current swagger/code use different names, use our current short interface path as the source of truth.
+- Do not frequently poll order status. Stop polling once the order is confirmed or canceled; rely on idempotent push/callback handling as the source of truth for confirmation progress.
+- Do not query real-time products for hotels outside the cached saleable hotel list; it wastes integration quota and usually returns no useful sellable data.
+- For Standard API Integration, recommend local saleable hotel cache maintenance. For Lightweight Integration Flow, recommend the smaller destination-driven flow unless the user explicitly needs full static catalog sync.
+
+## Typical Requests
+
+Use these patterns by default:
+
+- Static data and filters: `/region/countries`, `/region/cities`, `/region/popularCities`, `/region/businesses`, `/region/districts`, `/region/pois`, and `/hotel/groupBrand`.
+- Standard catalog sync: `/search/hotelIdList` -> `/hotel/detail`; maintain with `/hotel/increment` -> `/hotel/detail`.
+- Lightweight discovery: `/search/destination` -> `/search/hotelFilters` -> `/search/hotelList` -> `/hotel/detail`/`/hotel/images` -> `/booking/productDetails`.
+- Search and booking: `/hotel/lowestPrice` for list display/reference -> `/booking/productDetails` for hotel detail -> `/booking/availabilityCheck` -> optional second `/booking/availabilityCheck` -> `/booking/createOrder` -> `/booking/payOrder` -> order push/callback primary, `/order/orderDetail` as compensation.
+- Order aftercare: `/order/cancelOrder`, order push/callback, `/order/orderDetail`, `/order/checkInDetail`, `/order/checkoutRequest`, `/order/checkoutDetail`.
+- Finance: `/order/invoiceRequest`, `/order/invoiceInfo`, `/search/creditBalance`.
+
+## Output Expectations
+
+When answering or coding with this skill:
+
+- Prefer concrete request examples over abstract summaries.
+- Name the source used when the current swagger/code and bundled references disagree, but keep customer-facing answers on our short interface paths.
+- State whether the recommendation follows Standard API Integration or Lightweight Integration Flow when giving onboarding advice.
+- State which environment the credential belongs to.
+- State whether the payload should contain only business fields.
+- Call out Glink-managed field residue in the swagger when relevant.
+- Call out auth failures with the likely root cause and the exact header or field to inspect.
+- For code changes, keep internal Glink integration auth and platform gateway auth clearly separated.

package/skills/glink-hotel-api/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Glink OpenAPI 接入"
-  short_description: "Glink 酒店开放接口鉴权、签名和业务调用"
-  default_prompt: "Use $glink-hotel-api to implement or debug Glink hotel OpenAPI auth, signatures, endpoint selection, and order workflows."
+interface:
+  display_name: "Glink OpenAPI 接入"
+  short_description: "Glink 酒店开放接口鉴权、签名和业务调用"
+  default_prompt: "Use $glink-hotel-api to implement or debug Glink hotel OpenAPI auth, signatures, endpoint selection, and order workflows."