对外 API

独立命名空间 /open/v1,面向小程序、外部合作方与其他系统的只读接口。

版本 v0.1(草案):已实现并上线 4 个只读端点,测试通过。本文只写对外承诺的接口;站内内部契约不是对外接口,两者不要混用。

一、定位与边界

二、认证

请求头携带 Bearer 形式的 API Key:

Authorization: Bearer tk_live_xxxxxxxx

三、统一返回信封

所有成功响应遵循同一外层结构:

{
  "data": { },
  "meta": { "schema_version": "1.0", "summary": "可选的人类可读摘要" },
  "page": { "total": 120, "next_token": "..." },
  "evidence": [ { "quote": "...", "source": "..." } ],
  "next_actions": [],
  "warnings": []
}

错误响应:

{ "code": "invalid_body", "message": "参数错误", "field_errors": [ { "field": "kind", "message": "必填" } ], "hint": "kind 取 school/company/position/city" }

四、v1 只读端点(4 条)

4.1 字段归一

POST /open/v1/resolve

{ "kind": "school", "text": "北林" }

返回 data:{status, confidence, code, label, alternatives[], source}。 status 取值为 resolved / ambiguous / pending / non_entity。 ambiguous 时 alternatives 给候选,由调用方选择,不自动拍板。

4.2 字典查询

GET /open/v1/dict/{type}?q=&page_token=&limit=

4.3 候选人评分查询

GET /open/v1/candidates/{id}/score

返回最新一条已发布评分:final_score、tier、primary_type、directions、review_reasons。 不含原始简历、联系方式、访谈全文;评分是 AI 产物,人工校准后以校准值为准。

4.4 需求匹配查询

GET /open/v1/demands/{id}/matches?limit=

返回预匹配队列:candidate_id、脱敏姓名、score、band、coverage、why_like[]。 只读已生成的预匹配结果,不触发重算。信息不足时 band=insufficient,如实返回,不假报分数。

五、分页、限流与幂等

六、版本与兼容

七、错误码

codeHTTP含义
invalid_key401Key 无效或过期
forbidden403缺少 scope
invalid_body400参数缺失或类型错(带 field_errors)
not_found404资源不存在或无权查看
rate_limited429超过配额
internal500服务内部错误

八、签发与调用

在服务器(或能连 TALENT_DATABASE_URL 的机器)签发,明文只显示一次:

# 签发与查看(明文只显示一次)
OPEN_API_DSN='postgres://...' openkey issue --name 小程序只读 --scopes dict:view,candidates:view,clients:view
openkey list
openkey disable --id 3

调用示例:

curl -s https://talent.founduai.com/open/v1/dict/schools?limit=2 \
  -H "Authorization: Bearer tk_xxx"

curl -s -X POST https://talent.founduai.com/open/v1/resolve \
  -H "Authorization: Bearer tk_xxx" -H 'Content-Type: application/json' \
  -d '{"kind":"school","text":"北京林业大学"}'

curl -s https://talent.founduai.com/open/v1/candidates/1/score -H "Authorization: Bearer tk_xxx"
curl -s https://talent.founduai.com/open/v1/demands/1/matches -H "Authorization: Bearer tk_xxx"

九、落地路径(实现侧)

  1. 契约层增加 Surfaces 标记:http / cli / mcp / agent / external,只把 external 的条目投影到 /open/v1。
  2. 新增 API Key 表与中间件:Key → scope 集合 → 复用现有 auth.RequirePoint。
  3. 新增 internal/openapi 生成器:从契约导出 OpenAPI 3.1,人读文档由它派生,避免漂移。
  4. 先只读 4 条上线;写接口按需再评。

十、已定决策

  1. Key 由管理侧用 openkey 签发,明文只返回一次,库里只存 sha256。
  2. 小程序 v1 只读;写操作不进对外面。
  3. 配额按 Key 每分钟,默认 120,可由 OPENV1_RATE_PER_MIN 调整。
  4. 批量查询(按 id 列表取评分)后置到 v1.1。