> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dropcv.work/llms.txt
> Use this file to discover all available pages before exploring further.

# 调用 skill

> 所有 skill 调用走这一个端点。请求体固定为 `{ "params": { ... } }`，`params` 的字段由 skill 自身的 schema 决定。

响应是统一 envelope：成功带 `result`，失败带 `error`，两种情况都带 `invocation_id` 便于审计排查。



## OpenAPI

````yaml /openapi.json post /skills/{skill_key}/invoke
openapi: 3.1.0
info:
  title: DropCV Skills API
  version: 1.0.0
  description: >-
    DropCV 对外开放的人才库能力接口。所有能力（skill）走统一的调用形态：


    `POST /skills/{skill_key}/invoke`


    用 API Key 鉴权（`Authorization: Bearer drop_cv_...`）。同一套能力也通过 MCP Server 和
    `@dropcv/cli` 命令行暴露。
servers:
  - url: https://api.dropcv.work/api/external/v1
    description: 生产环境
security:
  - ApiKeyAuth: []
paths:
  /skills/{skill_key}/invoke:
    post:
      tags:
        - Skills
      summary: 调用 skill
      description: >-
        所有 skill 调用走这一个端点。请求体固定为 `{ "params": { ... } }`，`params` 的字段由 skill 自身的
        schema 决定。


        响应是统一 envelope：成功带 `result`，失败带 `error`，两种情况都带 `invocation_id` 便于审计排查。
      operationId: invokeSkill
      parameters:
        - name: skill_key
          in: path
          required: true
          description: 要调用的 skill 标识
          schema:
            type: string
            enum:
              - candidate_search
              - candidate_profile_read
              - jd_parse
              - save_candidate
              - candidate_update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeRequest'
            examples:
              candidate_search:
                summary: candidate_search — 人才库搜索
                value:
                  params:
                    query: 5 年 Java 微服务，Spring Boot，有大厂经验
                    top_k: 5
              candidate_profile_read:
                summary: candidate_profile_read — 读取候选人档案
                value:
                  params:
                    candidate_id: 9f8b2c1a-7d4e-4a2b-9c3d-1e2f3a4b5c6d
              jd_parse:
                summary: jd_parse — JD 结构化解析
                value:
                  params:
                    jd_text: >-
                      岗位名称：高级后端工程师

                      任职要求：5 年以上 Java 后端经验，精通 Spring
                      Boot，有微服务治理和分布式事务实战经验，计算机相关专业本科及以上。
              save_candidate:
                summary: save_candidate — 候选人入库（需 write 权限）
                value:
                  params:
                    candidate_profile_text: |-
                      张三 / 28 岁 / 杭州
                      教育：浙江大学 计算机本科 2018
                      经历：
                      - 阿里巴巴 P6 后端 (2018-2023)
                      - 字节跳动 高级工程师 (2023-至今)
                      技能：Java/Spring Boot/MySQL/Kafka/Redis
                    attachment_file_id: f_01HABCDEFGHIJKLMNOPQRSTUVW
                    source_url: https://www.zhipin.com/job_detail/xxxx.html
              candidate_update:
                summary: candidate_update — 更新候选人字段（需 write 权限）
                value:
                  params:
                    candidate_id: 9f8b2c1a-7d4e-4a2b-9c3d-1e2f3a4b5c6d
                    fields:
                      current_title: 技术总监
                      interview_notes: 5/12 一面通过，技术功底扎实
      responses:
        '200':
          description: 调用成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          description: API Key 无效 / 已撤销
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: 调用写 skill 但 API Key 没有 write 权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: skill_key 不存在，或引用的资源未找到
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: params 不符合 skill schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    InvokeRequest:
      type: object
      required:
        - params
      properties:
        params:
          type: object
          description: >-
            skill 的入参，字段由 skill 自身 schema 决定。详见 GET /skills/{skill_key} 或对应
            skill 文档。
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: true
        skill_key:
          type: string
          example: candidate_search
        invocation_id:
          type: string
          description: 本次调用的唯一 ID，格式 inv_<ULID>
          example: inv_01HXXXXXXXXXXXXXXXXXXXXXXX
        result:
          type: object
          description: skill 的输出，结构由 skill 自身决定
        metadata:
          type: object
          properties:
            latency_ms:
              type: integer
              example: 234
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: false
        skill_key:
          type:
            - string
            - 'null'
          example: candidate_search
        invocation_id:
          type: string
          example: inv_01HXXXXXXXXXXXXXXXXXXXXXXX
        error:
          type: object
          properties:
            code:
              type: string
              description: 封闭错误码枚举
              enum:
                - INVALID_API_KEY
                - INSUFFICIENT_PERMISSION
                - SKILL_NOT_FOUND
                - CANDIDATE_NOT_FOUND
                - FILE_NOT_FOUND
                - INVALID_PARAMS
                - BUSINESS_ERROR
                - INTERNAL_ERROR
            message:
              type: string
              description: 人类可读错误说明
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: DropCV API Key。在 设置 → API Keys 生成，格式 drop_cv_<32 位随机字符>。

````