openapi: 3.0.0
info:
  title: Liyu Pinche Tencent ADP readonly five-tool candidate
  version: 2026.07.02-five-tool-saved-shape-no-submit
  description: >
    里鱼拼车腾讯 ADP 五工具只读候选包。本文件按已保存并通过 CheckTool 的插件形态整理：
    smartRideSearch、getLiyuCapabilities、searchRides、getRideDetail、searchGroups。
    本候选仅用于 owner review 和后续复核；不代表已发布、提交或公开投放。
servers:
  - url: https://www.pcsfc.com
    description: 里鱼拼车生产域名
paths:
  /lypinche/smart:
    post:
      operationId: smartRideSearch
      summary: 自然语言智能查询拼车信息
      description: >
        用户用自然语言询问路线、日期、拼车或货找车时优先调用。返回里鱼拼车真实业务数据、有效性字段和可参考 reply。
        不得编造车次、价格、联系方式、成交率或担保承诺。
      parameters:
        - $ref: "#/components/parameters/LiyuPlatformHeader"
        - $ref: "#/components/parameters/LiyuTraceHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: 用户自然语言拼车需求。
            examples:
              normal:
                value:
                  query: 明天济南到北京有没有顺风车
      responses:
        "200":
          $ref: "#/components/responses/StandardJson"
  /lypinche/capabilities:
    post:
      operationId: getLiyuCapabilities
      summary: 获取里鱼拼车工具能力清单
      description: >
        智能体需要确认里鱼拼车 API 能做什么、有哪些边界、哪些只读工具可用时调用。不要用它回答具体路线供给。
      parameters:
        - $ref: "#/components/parameters/LiyuPlatformHeader"
        - $ref: "#/components/parameters/LiyuTraceHeader"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        "200":
          $ref: "#/components/responses/StandardJson"
  /lypinche/search:
    post:
      operationId: searchRides
      summary: 使用结构化条件查询拼车信息
      description: >
        已有出发地、目的地、类型或日期时调用。返回公开拼车列表、有效性字段和脱敏联系边界；不要把过期结果当作当前可用。
      parameters:
        - $ref: "#/components/parameters/LiyuPlatformHeader"
        - $ref: "#/components/parameters/LiyuTraceHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                departure:
                  type: string
                  description: 出发地。
                destination:
                  type: string
                  description: 目的地。
                type:
                  type: integer
                  enum: [1, 2, 3, 4]
                  description: 1=人找车，2=车找人，3=车找货，4=货找车。
                date:
                  type: string
                  description: 日期或日期文本。
                page:
                  type: integer
                  default: 1
                  minimum: 1
                page_size:
                  type: integer
                  default: 3
                  minimum: 1
                  maximum: 5
            examples:
              route:
                value:
                  departure: 济南
                  destination: 北京
                  page: 1
                  page_size: 3
      responses:
        "200":
          $ref: "#/components/responses/StandardJson"
  /lypinche/pcdetail:
    post:
      operationId: getRideDetail
      summary: 获取单条拼车公开详情
      description: >
        已有拼车信息 ID 时调用。返回公开详情、有效性和脱敏联系方式；不得还原隐藏号码或输出完整隐私联系信息。
      parameters:
        - $ref: "#/components/parameters/LiyuPlatformHeader"
        - $ref: "#/components/parameters/LiyuTraceHeader"
        - name: info_id
          in: query
          required: true
          description: 拼车信息 ID。
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        "200":
          $ref: "#/components/responses/StandardJson"
  /lypinche:
    get:
      operationId: searchGroups
      summary: 搜索官方拼车群入口
      description: >
        用户明确找拼车群、官方群、群入口，或路线无结果需要下一步官方群入口时调用。
        只返回官方中转页 entry_page_url，不输出 raw qrcode path 或内部文件路径。
      parameters:
        - $ref: "#/components/parameters/LiyuPlatformHeader"
        - $ref: "#/components/parameters/LiyuTraceHeader"
        - name: action
          in: query
          required: true
          description: 固定为 groups。
          schema:
            type: string
            enum:
              - groups
        - name: version
          in: query
          required: false
          description: API 版本。
          schema:
            type: string
            default: v1
        - name: keyword
          in: query
          required: false
          description: 群关键词，例如 曹县青岛拼车群。
          schema:
            type: string
        - name: departure
          in: query
          required: false
          description: 出发地。
          schema:
            type: string
        - name: destination
          in: query
          required: false
          description: 目的地。
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: 返回群数量上限。
          schema:
            type: integer
            minimum: 1
            maximum: 5
            default: 3
        - name: include_detail
          in: query
          required: false
          description: 固定建议为 0，避免返回大字段或敏感细节。
          schema:
            type: string
            enum:
              - "0"
            default: "0"
      responses:
        "200":
          $ref: "#/components/responses/StandardJson"
components:
  parameters:
    LiyuPlatformHeader:
      name: X-Liyu-Platform
      in: header
      required: false
      description: 平台归因标识。腾讯 ADP 填写 tencent-adp。
      schema:
        type: string
        enum:
          - tencent-adp
    LiyuTraceHeader:
      name: X-Liyu-Trace-Id
      in: header
      required: false
      description: 调用方请求追踪 ID，用于平台校验和日志归因。
      schema:
        type: string
        maxLength: 128
  responses:
    StandardJson:
      description: 里鱼拼车只读 JSON 结果
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
            properties:
              code:
                type: integer
                description: 0 表示成功。
              message:
                type: string
              data:
                type: object
                additionalProperties: true
              suggestion:
                type: string
              meta:
                type: object
                additionalProperties: true
