API 协议 - DropCV

URL

所有 skill 调用走同一形态：

POST /api/external/v1/skills/{skill_key}/invoke

辅助端点：

GET  /api/external/v1/skills              # 列出可用 skill
GET  /api/external/v1/skills/{skill_key}  # 单 skill 元数据 + Pydantic schema
POST /api/external/v1/files/upload        # 文件上传，详见文件上传页

请求 envelope

POST /api/external/v1/skills/candidate_search/invoke
Authorization: Bearer drop_cv_xxxxx...
Content-Type: application/json

{
  "params": { "query": "Python 后端 5 年", "top_k": 10 }
}

params 字典就是该 skill 的 schema 定义。每个 skill 的 params 详见对应文档。

响应 envelope（成功）

{
  "success": true,
  "skill_key": "candidate_search",
  "invocation_id": "inv_01HXXXXXXX...",
  "result": { /* skill 自己的输出，参考对应 skill 文档 */ },
  "metadata": { "latency_ms": 234 }
}

响应 envelope（失败）

{
  "success": false,
  "skill_key": "candidate_search",
  "invocation_id": "inv_01HXXXXXXX...",
  "error": { "code": "INVALID_PARAMS", "message": "query is empty" }
}

错误码

code	HTTP	含义	怎么修
`INVALID_API_KEY`	401	Key 无效 / 撤销 / 不存在	检查 Authorization 头，重新生成
`INSUFFICIENT_PERMISSION`	403	写 skill 但 key 没开 write 权限	在 API Keys 页面勾”允许写入”
`SKILL_NOT_FOUND`	404	skill_key 拼错	看 `GET /skills` 列表
`CANDIDATE_NOT_FOUND`	404	candidate_id 不存在或不属于本账号	核对 candidate_id
`FILE_NOT_FOUND`	404	attachment_file_id 不存在 / 已过期 / 不属于本 user	重新上传文件
`BUSINESS_ERROR`	400	入参语义不合法（依赖资源状态不对等）	看 message 说明
`INVALID_PARAMS`	422	params 不符合 schema	看 message 里的字段错误说明
`INTERNAL_ERROR`	500	服务端业务异常	凭 invocation_id 联系支持

invocation_id

每次调用都会生成 inv_<ULID> 格式的 id。记录它——如果调用结果有问题：

在 DropCV 设置 → 用量里按 invocation_id 搜索能看到完整调用详情（参数、状态、延迟、错误信息）
联系支持时附上这个 id 便于快速定位

CLI 出错时会自动在 stderr 打印 invocation_id；MCP 客户端通常不显示但也会写入审计。