@mongoui/skills 0.1.4 → 0.1.5

package/dist/commands/install.js

@@ -38,11 +38,33 @@ export async function runInstall(productName, options) {
     }
     const installTarget = resolveInstallTarget(options.tool, options.targetDir);
     const sourceSkillFile = path.join(packageRoot, product.skillFile);
+    const sourceSkillDir = product.skillDir ? path.join(packageRoot, product.skillDir) : undefined;
     const targetSkillFile = resolveTargetSkillFile(product.name, installTarget);
+    const targetSkillDir = resolveTargetSkillDir(sourceSkillDir, installTarget);
+    await fs.mkdir(installTarget.targetDir, { recursive: true });
+    if (sourceSkillDir && shouldInstallAsDirectory(installTarget.tool)) {
+        await fs.access(sourceSkillDir);
+        await fs.rm(targetSkillDir, { recursive: true, force: true });
+        await fs.rm(targetSkillFile, { force: true });
+        await copyDirectory(sourceSkillDir, targetSkillDir);
+        console.log("Installed skill:");
+        console.log("- command: install");
+        console.log(`- product: ${product.name}`);
+        console.log(`- display name: ${product.displayName}`);
+        console.log(`- tool: ${installTarget.tool}`);
+        console.log(`- source skill dir: ${sourceSkillDir}`);
+        console.log(`- source skill file: ${sourceSkillFile}`);
+        console.log(`- target dir: ${installTarget.targetDir}`);
+        console.log(`- target source: ${installTarget.source}`);
+        console.log(`- target skill dir: ${targetSkillDir}`);
+        console.log(`- target skill file: ${path.join(targetSkillDir, "SKILL.md")}`);
+        console.log("- target format: directory");
+        console.log("- status: installed");
+        return;
+    }
     await fs.access(sourceSkillFile);
     const sourceSkillContent = await fs.readFile(sourceSkillFile, "utf8");
     const targetSkillContent = renderInstalledContent(installTarget.tool, product.name, product.displayName, sourceSkillContent);
-    await fs.mkdir(installTarget.targetDir, { recursive: true });
     await fs.writeFile(targetSkillFile, targetSkillContent, "utf8");
     console.log("Installed skill:");
     console.log("- command: install");
@@ -62,7 +84,9 @@ export async function runUninstall(productName, options) {
         throw new Error(`Missing required option: "--tool <${supportedToolsText()}>".`);
     }
     const installTarget = resolveInstallTarget(options.tool, options.targetDir);
+    const targetSkillDir = resolveTargetSkillDir(undefined, installTarget, product);
     const targetSkillFile = resolveTargetSkillFile(product.name, installTarget);
+    await fs.rm(targetSkillDir, { recursive: true, force: true });
     await fs.rm(targetSkillFile, { force: true });
     console.log("Uninstalled skill:");
     console.log("- command: uninstall");
@@ -71,6 +95,7 @@ export async function runUninstall(productName, options) {
     console.log(`- tool: ${installTarget.tool}`);
     console.log(`- target dir: ${installTarget.targetDir}`);
     console.log(`- target source: ${installTarget.source}`);
+    console.log(`- target skill dir: ${targetSkillDir}`);
     console.log(`- target skill file: ${targetSkillFile}`);
     console.log(`- target format: ${installTarget.fileExtension}`);
     console.log("- status: removed");
@@ -88,3 +113,25 @@ function requireProduct(productName) {
 function resolveTargetSkillFile(productName, installTarget) {
     return path.join(installTarget.targetDir, installTarget.fileName ?? `${productName}.${installTarget.fileExtension}`);
 }
+function resolveTargetSkillDir(sourceSkillDir, installTarget, product) {
+    const dirName = sourceSkillDir
+        ? path.basename(sourceSkillDir)
+        : `${product?.name ?? "skill"}`;
+    return path.join(installTarget.targetDir, dirName);
+}
+function shouldInstallAsDirectory(tool) {
+    return tool === "codex" || tool === "kiro";
+}
+async function copyDirectory(sourceDir, targetDir) {
+    await fs.mkdir(targetDir, { recursive: true });
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetPath = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(sourcePath, targetPath);
+            continue;
+        }
+        await fs.copyFile(sourcePath, targetPath);
+    }
+}

package/dist/products/index.js

@@ -2,12 +2,14 @@ const PRODUCTS = {
     "glink-hotel-api": {
         name: "glink-hotel-api",
         displayName: "Glink Hotel API",
-        skillFile: "skills/glink-hotel-api/SKILL.md",
+        skillFile: "skills/glink-hotel-api/glink-openapi-integration/SKILL.md",
+        skillDir: "skills/glink-hotel-api/glink-openapi-integration",
     },
     "flink-flight-api": {
         name: "flink-flight-api",
         displayName: "Flink Flight API",
-        skillFile: "skills/flink-flight-api/SKILL.md",
+        skillFile: "skills/flink-flight-api/flink-openapi-integration/SKILL.md",
+        skillDir: "skills/flink-flight-api/flink-openapi-integration",
     },
     "tmc-whitelabel": {
         name: "tmc-whitelabel",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mongoui/skills",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "CLI for installing product skills into AI tools",
   "license": "MIT",
   "publishConfig": {

package/skills/flink-flight-api/flink-openapi-integration/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: flink-openapi-integration
+description: Integrate with the Flink flight OpenAPI exposed through the platform runtime gateway. Use when Codex needs to read or implement against `docs/swagger/flink-api.json`, choose the correct Flink ticket endpoint, generate `X-OP-*` signatures, explain sandbox or production credential acquisition and reset, or drive search, booking, change, refund, airport, airline, nationality, and fields workflows.
+---
+
+# Flink OpenAPI Integration
+
+## Quick Start
+
+Use this skill when the task is "call Flink through the open platform" rather than "call Flink supplier APIs directly".
+
+Start with the smallest reference that answers the request:
+
+- Read `references/auth-and-credentials.md` for signing, headers, key acquisition, reset, or auth troubleshooting.
+- Read `references/api-workflows.md` for business sequencing such as search to booking, change, or refund.
+- Read `references/endpoint-index.md` for exact method, path, required fields, and follow-up identifiers.
+- Use `scripts/flink_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 the public path under `/openapi/v1/flink/*` and the required `lang` path parameter when present.
+3. Build the minimum valid request body from `references/endpoint-index.md`.
+4. Sign the exact request path, sorted query string, and raw body bytes with the platform secret.
+5. Evaluate both HTTP status and response envelope `code`.
+
+Do not violate these rules:
+
+- Always send `X-OP-App-Key`, `X-OP-Timestamp`, `X-OP-Nonce`, and `X-OP-Sign`.
+- Never send supplier-side `appid`, `timestamp`, or `sign`; the platform injects them downstream.
+- 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`.
+- Preserve bridge identifiers across steps:
+  - `priceKey` bridges search or cabin to verify and order creation.
+  - `orderNo` bridges order detail, cancel, change, refund, and fields lookup.
+  - `changeOrderNo` and `refundOrderNo` drive their detail or cancel or confirm calls.
+- For `GET /openapi/v1/flink/fields`, send at least one of `priceKey` or `orderNo`.
+
+## Typical Requests
+
+Use these patterns by default:
+
+- Search and booking: `flight.search` -> `flight.cabin` if needed -> `flight.verify` -> `flight.order.create` -> `flight.order.pay` -> `flight.order.detail`
+- Change: `flight.order.detail` -> `flight.change.search` -> `flight.change.apply` -> `flight.order.pay` with `type=1` if payment is required -> `flight.change.detail`
+- Refund: `flight.order.detail` -> `flight.refund.apply` -> `flight.refund.detail` -> `flight.refund.confirm`
+- Base data: `airports.list`, `airlines.list`, `airports.search`, `nationality.list`, `fields`
+
+## Output Expectations
+
+When answering or coding with this skill:
+
+- Prefer concrete request examples over abstract summaries.
+- State which environment the credential belongs to.
+- State which identifier from the previous step is needed next.
+- Call out auth failures with the likely root cause and the exact header or field to inspect.

package/skills/flink-flight-api/flink-openapi-integration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flink OpenAPI 接入"
+  short_description: "帮助完成 Flink 机票开放接口鉴权、凭证获取和业务调用"
+  default_prompt: "Use $flink-openapi-integration to integrate with the Flink flight open API, including auth, credentials, and endpoint selection."

package/skills/flink-flight-api/flink-openapi-integration/references/api-workflows.md

@@ -0,0 +1,104 @@
+# Flink API Workflows
+
+## Search And Booking
+
+Use this sequence for a normal booking flow:
+
+1. `flink.flight.search`
+   - Search journeys and offer combinations.
+   - Save returned `priceKey` values for the next step.
+2. `flink.flight.cabin`
+   - Use when a selected offer needs more fare or cabin quotes.
+   - Input is `priceKey`.
+3. `flink.flight.verify`
+   - Validate the selected offer before order creation.
+   - Input is `priceKey`.
+4. `flink.flight.order.create`
+   - Create the pre-booking order with contact and passenger data.
+   - Input still depends on `priceKey`.
+5. `flink.flight.order.pay`
+   - Pay the standard order with `type=0`.
+6. `flink.flight.order.detail`
+   - Read status, ticketing progress, and later change or refund context.
+7. `flink.flight.order.cancel`
+   - Use only for cancellable standard orders.
+
+Keep these state tokens:
+
+- `priceKey`: search or cabin -> verify or order creation
+- `orderNo`: order creation or detail -> pay, cancel, change, refund, fields
+
+## Change Flow
+
+Use this sequence for voluntary or involuntary changes:
+
+1. `flink.flight.order.detail`
+   - Confirm order status and segment context.
+2. `flink.flight.change.search`
+   - Search eligible changed flights for an existing order and passenger or segment scope.
+3. `flink.flight.change.apply`
+   - Submit the actual change request with `priceKey`, passenger scope, segment scope, reason, and contact info.
+4. `flink.flight.order.pay`
+   - If the change order requires payment, pay with `type=1`.
+5. `flink.flight.change.detail`
+   - Track the change request by `changeOrderNo`.
+6. `flink.flight.change.cancel`
+   - Cancel a pending change request by `changeOrderNo`.
+
+Bridge identifiers:
+
+- `orderNo` drives change search and apply.
+- `priceKey` from change search is used in change apply.
+- `changeOrderNo` drives detail and cancel.
+
+## Refund Flow
+
+Use this sequence for refunds:
+
+1. `flink.flight.order.detail`
+   - Confirm the refundable order, passenger, and segment scope.
+2. `flink.flight.refund.apply`
+   - Submit the refund request with passenger scope, segment scope, contact data, and reason.
+3. `flink.flight.refund.detail`
+   - Track the refund request by `refundOrderNo`.
+4. `flink.flight.refund.confirm`
+   - Confirm or cancel the refund request.
+
+Bridge identifiers:
+
+- `orderNo` drives refund apply.
+- `refundOrderNo` drives detail and confirm.
+
+## Base Data And Helper Calls
+
+Use these APIs outside the booking lifecycle:
+
+- `flink.airports.list`
+  - Paged airport list with optional keyword filtering.
+- `flink.airlines.list`
+  - Paged airline list with optional keyword and code filtering.
+- `flink.airports.search`
+  - Lightweight airport search by keyword.
+- `flink.nationality.list`
+  - Nationality reference data.
+- `flink.fields`
+  - Field translations and baggage or travel notice helpers.
+  - Provide either `priceKey` or `orderNo`.
+
+## Language Parameter
+
+All Flink routes except `flink.fields` require `{lang}` in the path.
+
+Common values:
+
+- `en`
+- `zh_CN`
+- `zh_TW`
+
+Use the same `lang` across related calls unless there is a clear reason to switch.
+
+## Business Handling Rules
+
+- Do not treat HTTP `200` as enough; inspect `code`.
+- Do not rebuild supplier headers; the runtime gateway handles supplier authentication.
+- Preserve the original upstream identifiers from earlier responses instead of recomputing them.

package/skills/flink-flight-api/flink-openapi-integration/references/auth-and-credentials.md

@@ -0,0 +1,136 @@
+# Flink Auth And Credentials
+
+## Required Headers
+
+Send these headers on every Flink open-platform request:
+
+- `X-OP-App-Key`
+- `X-OP-Timestamp`
+- `X-OP-Nonce`
+- `X-OP-Sign`
+
+Optional headers that can help tracing or idempotency:
+
+- `X-OP-Client-Request-Id`
+- `X-Trace-Id`
+- `X-Idempotency-Key`
+
+`X-OP-App-Key` is the issued `open_app_id`.
+
+## Signature Algorithm
+
+Build the canonical string in this exact order, separated by newline characters:
+
+```text
+METHOD
+PATH
+CANONICAL_QUERY
+BODY_SHA256
+TIMESTAMP
+NONCE
+APP_KEY
+```
+
+Rules:
+
+- Uppercase `METHOD`.
+- Use the exact public request path, for example `/openapi/v1/flink/zh_CN/flight/search`.
+- Sort query parameters by key and then value before joining them as `k=v&k2=v2`.
+- Hash the raw request body bytes with SHA256 and use the lowercase hex digest.
+- Use the request timestamp exactly as sent in `X-OP-Timestamp`.
+- Use the request nonce exactly as sent in `X-OP-Nonce`.
+- Use the same `open_app_id` that is sent in `X-OP-App-Key`.
+- Sign the canonical string with the plain `open_app_secret` using HMAC-SHA256, then output lowercase hex.
+
+Notes:
+
+- Timestamp may be Unix seconds, Unix milliseconds, or RFC3339.
+- The platform validates timestamp drift within roughly `+-5` minutes.
+- Nonce must be unique for the same app key in a short time window.
+- For empty bodies, hash the empty byte string.
+
+Use `scripts/flink_signed_request.py` when the task needs a deterministic implementation or a quick smoke test.
+
+## Credential Acquisition
+
+Treat credentials as environment-specific.
+
+Sandbox:
+
+1. The developer applies for app access.
+2. The operator activates the app access with `env_type=sandbox`.
+3. The platform records sandbox supplier mapping and issues a sandbox `open_app_id/open_app_secret`.
+4. The app access becomes `sandbox_active`.
+
+Production:
+
+1. The developer submits production access after sandbox work is complete.
+2. The operator approves production with `env_type=production`.
+3. The platform issues a production `open_app_id/open_app_secret`.
+4. The production credential becomes usable only after the app access reaches `production_active`.
+
+Important constraints:
+
+- Sandbox and production credentials are separate and not interchangeable.
+- Developers can see platform credentials only.
+- Developers cannot see supplier-side secrets.
+
+## How To View Or Reset Keys
+
+Developer portal APIs:
+
+- `GET /api/portal/apps/{app_id}/credentials`
+  - Returns the credential list for the app.
+  - Includes `open_app_id`, `provider_code`, `env_type`, `open_secret_version`, and masked secret data.
+  - Does not return the plain secret in normal list queries.
+- `POST /api/portal/apps/{app_id}/credentials/reset`
+  - Resets the platform secret and returns `plain_open_secret`.
+  - If the app has more than one credential mapping, pass both `provider_code` and `env_type`.
+
+Response fields that matter:
+
+- `open_app_id`: the App Key to place into `X-OP-App-Key`
+- `open_secret_masked`: masked secret for display only
+- `open_secret_version`: useful for rotation tracking
+- `plain_open_secret`: returned only on first issuance or reset
+
+Practical guidance:
+
+- If a developer says "I can only see a masked secret", instruct them to use the reset endpoint or the corresponding portal UI action.
+- If the task is only to call sandbox APIs, do not assume production credentials work.
+- If the app has both sandbox and production mappings, always name the target `env_type` explicitly.
+
+## Common Auth Failures
+
+- `APP_KEY_INVALID`
+  - Wrong `open_app_id`, wrong environment, or the credential does not exist.
+- `SIGN_ERROR`
+  - Wrong secret, wrong path, wrong query ordering, wrong body hash, or newline formatting mismatch.
+- `TIMESTAMP_EXPIRED`
+  - Clock skew exceeds the allowed window.
+- `NONCE_REPLAY`
+  - Nonce was reused under the same app key.
+- `PRODUCT_FORBIDDEN`
+  - The app is not enabled for the product, the mapping is not active, or an IP whitelist rule failed.
+
+## Response Contract
+
+The platform wraps business responses in a common envelope:
+
+```json
+{
+  "request_id": "req_xxx",
+  "trace_id": "trc_xxx",
+  "downstream_request_id": "optional",
+  "code": "SUCCESS",
+  "message": "ok",
+  "data": {}
+}
+```
+
+Interpretation:
+
+- `request_id` and `trace_id` are platform-side tracing keys.
+- `downstream_request_id` is the supplier request identifier when available.
+- `code=SUCCESS` means the business call succeeded.
+- `code=SUPPLIER_BIZ_ERROR` means the supplier returned a business error and can still arrive with HTTP `200`.

package/skills/flink-flight-api/flink-openapi-integration/references/endpoint-index.md

@@ -0,0 +1,92 @@
+# Flink Endpoint Index
+
+All routes are public gateway routes. Sign the public path, not the downstream supplier path.
+
+## Flight Search
+
+- `flink.flight.search`
+  - `POST /openapi/v1/flink/{lang}/flight/search`
+  - Required body fields: `cabinClass`, `tripType`, `journeys`, `adultNum`
+  - Common optional fields: `childNum`, `infantNum`, `airline`, `transferNumber`, `journeyId`, `corporate`
+  - Main output to preserve: `priceKey`
+- `flink.flight.cabin`
+  - `POST /openapi/v1/flink/{lang}/flight/cabin`
+  - Required body fields: `priceKey`
+  - Use to expand or refine fare options for a selected result
+- `flink.flight.verify`
+  - `POST /openapi/v1/flink/{lang}/flight/verify`
+  - Required body fields: `priceKey`
+  - Use before order creation
+
+## Order Management
+
+- `flink.flight.order.create`
+  - `POST /openapi/v1/flink/{lang}/flight/order/create`
+  - Required body fields: `priceKey`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`, `passenger`
+  - Use after verify or directly after search or cabin when allowed by the business flow
+- `flink.flight.order.pay`
+  - `POST /openapi/v1/flink/{lang}/flight/order/pay`
+  - Required body fields: `orderNo`, `amount`, `type`
+  - `type=0` for standard order, `type=1` for change order
+- `flink.flight.order.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/order/detail`
+  - Required body fields: `orderNo`
+- `flink.flight.order.cancel`
+  - `POST /openapi/v1/flink/{lang}/flight/order/cancel`
+  - Required body fields: `orderNo`
+
+## Change
+
+- `flink.flight.change.search`
+  - `POST /openapi/v1/flink/{lang}/flight/change/search`
+  - Required body fields: `orderNo`, `cabinClass`, `date`, `passenger`, `segmentId`
+- `flink.flight.change.apply`
+  - `POST /openapi/v1/flink/{lang}/flight/change/apply`
+  - Required body fields: `orderNo`, `passenger`, `segmentId`, `priceKey`, `changeOrderType`, `changeType`, `contactName`, `contactPhone`, `contactEmail`, `changeReasonType`, `changeReason`
+  - `fileList` is required by schema when attachments are involved in involuntary changes
+- `flink.flight.change.cancel`
+  - `POST /openapi/v1/flink/{lang}/flight/change/cancel`
+  - Required body fields: `changeOrderNo`
+- `flink.flight.change.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/change/detail`
+  - Required body fields: `changeOrderNo`
+
+## Refund
+
+- `flink.flight.refund.apply`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/apply`
+  - Required body fields: `orderNo`, `orderType`, `passenger`, `segmentId`, `refundType`, `reasonType`, `reason`, `fileList`, `contactName`, `contactRegion`, `contactPhone`, `contactEmail`
+- `flink.flight.refund.detail`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/detail`
+  - Required body fields: `refundOrderNo`
+- `flink.flight.refund.confirm`
+  - `POST /openapi/v1/flink/{lang}/flight/refund/confirm`
+  - Required body fields: `refundOrderNo`, `confirm`
+
+## Basic Data
+
+- `flink.airports.list`
+  - `POST /openapi/v1/flink/{lang}/airports/list`
+  - Required body fields: `page`, `pageSize`
+  - Common optional fields: `keyword`
+- `flink.airlines.list`
+  - `POST /openapi/v1/flink/{lang}/airlines/list`
+  - Required body fields: `page`, `pageSize`
+  - Common optional fields: `keyword`, `code`
+- `flink.airports.search`
+  - `POST /openapi/v1/flink/{lang}/airports/search`
+  - Common body field: `keyword`
+- `flink.nationality.list`
+  - `POST /openapi/v1/flink/{lang}/nationality/list`
+  - No required body fields in the current schema
+- `flink.fields`
+  - `GET /openapi/v1/flink/fields`
+  - Query parameters: `priceKey` optional, `orderNo` optional
+  - Send at least one of `priceKey` or `orderNo`
+
+## Global Notes
+
+- `{lang}` is required on every route except `flink.fields`.
+- Platform error responses can return `401`, `403`, `404`, `500`, `502`, or `504`.
+- Common auth-related `401` codes are `APP_KEY_INVALID`, `SIGN_ERROR`, `TIMESTAMP_EXPIRED`, and `NONCE_REPLAY`.
+- Common `403` cause is `PRODUCT_FORBIDDEN`.