dsh-flight-compare

簡介¶

dsh-flight-compare 是一個 DeepSeek Harness (DSH) 插件，用於註冊 flight_compare 工具。該工具從多個數據源獲取單條航線的機票價格，並按「航班號 + 出發日期」進行聚合，標出每個航班跨數據源的最低價及其來源，最後按最低價升序輸出 Markdown 表格。

插件由用戶 123wansui-989 維護，屬於聯網工具類別。

核心能力¶

插件實現了以下功能：

工具註冊：註冊 flight_compare 工具供 DSH 調用。
多源獲取：支持 Travelpayouts 和 Amadeus 兩個數據源。
- Travelpayouts：接口爲 GET /v2/prices/month-matrix，支持整月查詢，按城市 IATA 碼查詢。
- Amadeus：接口爲 GET /v2/shopping/flight-offers，官方 Self-Service API 實時報價，按機場 IATA 碼查詢，僅支持單日查詢。
數據聚合與比對：統一返回 Flight 對象（包含航班號、航司、時間、價格、幣種、來源等）。某個數據源查詢失敗不會導致整體調用失敗，失敗原因會在結果中列出。
結果輸出：輸出 Markdown 表格，包含最低價、來源及排序信息。

安裝與構建¶

插件基於 Node.js 構建，需要執行安裝和編譯步驟。

cd dsh-flight-compare
pnpm install
pnpm build

構建產物位於 lib/ 目錄，包含入口文件 index.js 和類型定義 index.d.ts。

配置說明¶

插件憑據僅從環境變量讀取，不寫入代碼。配置覆蓋需通過 cordis.patch.yml 文件進行。

環境變量¶

必須設置 Travelpayouts 的 Token。Amadeus 的 Client ID 和 Secret 爲可選，若兩項都留空，該源將自動跳過，插件退化爲單源比價。

export TRAVELPAYOUTS_TOKEN="<your-travelpayouts-token>"

# 可選：啓用 Amadeus
export AMADEUS_CLIENT_ID="<your-amadeus-api-key>"
export AMADEUS_CLIENT_SECRET="<your-amadeus-api-secret>"
export AMADEUS_PRODUCTION="false"   # false 使用 test.api.amadeus.com，true 使用 api.amadeus.com

配置項列表¶

插件依賴包版本爲 0.2.0，核心依賴包括 @deepseek-ai/cosmokit 和 @deepseek-ai/dsh-tools。主要配置項如下：

配置項	默認值/來源	說明
`travelpayoutsToken`	`process.env.TRAVELPAYOUTS_TOKEN`	Travelpayouts token，必填，作爲 `X-Access-Token` 發送。
`amadeusClientId`	`process.env.AMADEUS_CLIENT_ID`	Amadeus API key。
`amadeusClientSecret`	`process.env.AMADEUS_CLIENT_SECRET`	Amadeus API secret，用於 OAuth2 認證。
`amadeusProduction`	`false`	控制是否使用生產環境 API。
`amadeusMaxResults`	`20`	每次搜索向 Amadeus 請求的報價條數上限。
`currency`	`RUB`	價格幣種，例如 RUB、USD。
`maxRows`	`30`	輸出表格的最大行數。
`timeoutMs`	`20000`	每個數據源單次請求的超時時間（毫秒）。

配置覆蓋示例¶

使用 cordis.patch.yml 覆蓋默認配置：

- insert:
    - id: dsh-flight-compare
      name: dsh-flight-compare
      config:
        travelpayoutsToken: !!js process.env.TRAVELPAYOUTS_TOKEN
        amadeusClientId: !!js process.env.AMADEUS_CLIENT_ID
        amadeusClientSecret: !!js process.env.AMADEUS_CLIENT_SECRET
        amadeusProduction: !!js process.env.AMADEUS_PRODUCTION === 'true'
        currency: USD
        maxRows: 30

使用方式¶

在設置好環境變量和配置文件後，通過 DSH 的 --patch 參數加載插件。

# 設置環境變量
export TRAVELPAYOUTS_TOKEN="<your-travelpayouts-token>"
export AMADEUS_CLIENT_ID="<your-amadeus-api-key>"
export AMADEUS_CLIENT_SECRET="<your-amadeus-api-secret>"

# 啓動 DSH 並加載插件補丁
dsh --profile web --patch ./cordis.patch.yml

啓動後，flight_compare 工具即可被調用。在調用 departDate 參數傳 YYYY-MM-DD 時，兩個源都會查詢；傳 YYYY-MM 或不傳時，僅 Travelpayouts 參與比對。

注意事項¶

權限運行：插件以當前 DSH 進程的權限運行，調用 API 時需確保環境變量中包含有效的授權憑證。
數據源限制：Travelpayouts 支持整月查詢，Amadeus 搜索接口只接受單日。當 Amadeus 的 Client ID 和 Secret 均爲空時，該源會自動跳過。
源碼審查：使用前請檢查插件源碼及許可證狀態（當前未定義）。
調試：可使用 --dump-config 參數先確認組合配置結果再啓動。