API 参考

Preflight API

搜索结果会过时。preflight 在 Agent 调用前的几毫秒，对某个具体动作重新核一遍：实时状态、容量、预期延迟，以及一个有界的有效期窗口。

POST/v1/capabilities/preflight

请求体

字段	说明
capability_id	要检查的能力，取自搜索结果。
action	要调用的具体动作。评分按动作维度而非服务维度计算。
agent_runtime	调用方运行时标识。
task_family	任务族，用于任务相关的排序，如 pdf_table_to_csv。
timeout_budget_ms	时间预算；预期延迟超出时会被标记。
risk_level	本次调用可接受的风险等级。

request.sh

curl -X POST http://101.32.68.30/v1/capabilities/preflight \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "capability_id": "cap_pdf_extract_table",
    "action": "extract_table",
    "agent_runtime": "claude-code",
    "task_family": "pdf_table_to_csv",
    "timeout_budget_ms": 10000,
    "risk_level": "read_only"
  }'

响应

status 取值为 ready、degraded 或 blocked。请将 valid_for_seconds 视为硬性过期时间：超过后应重新执行 preflight，不再使用旧结果。

response.json

{
  "status": "ready",
  "invoke_now_score": 0.91,
  "confidence": 0.83,
  "valid_for_seconds": 45,
  "expected_p95_latency_ms": 3200,
  "capacity_state": "ok",
  "auth_state": "not_required",
  "warnings": [],
  "fallbacks": [
    {
      "capability_id": "cap_slow_but_local_cli",
      "reason": "local_execution_available"
    }
  ]
}