agent-download 接口文档

POST /api/download — 提交下载

立即返回任务列表（异步执行）；用 /api/job/:id 轮询结果。

参数

请求示例

curl -X POST https://agent-download.kukukala.com/api/download \
  -H "x-auth-token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","resolution":"1080p"}'

响应示例

{ "jobs": [ { "jobId": "j_a1b2c3d4", "status": "queued", "platform": "youtube" } ] }

批量且含无效 URL 时逐个处理，无效项原样带回：

{ "jobs": [
  { "jobId": "j_a1b2c3d4", "status": "queued", "platform": "youtube" },
  { "url": "https://v.douyin.com/xxx", "rejected": true, "errorCode": "platform_not_supported" }
] }

GET /api/job/:id — 查询任务

curl -H "x-auth-token: $TOKEN" https://agent-download.kukukala.com/api/job/j_a1b2c3d4

{
  "jobId": "j_a1b2c3d4", "platform": "youtube", "status": "done", "progress": 100,
  "title": "…", "sizeBytes": 104857600, "durationS": 245.3,
  "error": null,
  "downloadUrl": "/file/j_a1b2c3d4?token=…",
  "expiresAt": 1759286400000, "attempt": 1
}

状态机：queued → dispatched → downloading → uploading → done | failed，另有 expired（48h 到期）。progress 为 0–1 浮点。error 形如 {"code":"youtube_blocked","message":"…","retryable":true}（见错误码表）。downloadUrl 仅 done 时返回，随查询实时签发、48h 内有效。

GET /api/status — 服务状态

curl -H "x-auth-token: $TOKEN" https://agent-download.kukukala.com/api/status

{
  "capacity": { "maxInstances": 1, "jobsPerInstance": 2, "globalInflightCap": 2,
                "inflight": 2, "queued": 3,
                "note": "预算值（软约束）：实际并发由派发闸控制，实例布局由 FC 决定" },
  "stats": { "youtube": { "attempts24h": 12, "successes24h": 11, "lastAttemptAt": …, "lastSuccessAt": … } },
  "supportedPlatforms": ["youtube"],
  "channels": { "youtube": { "target": 5, "current": 5, "inflight": 2, "queued": 3, "recentFailRate": 0.1 } },
  "instances": [ { "instanceId": "i_x", "startedAt": 1759200000000, "lastHeartbeatAt": 1759200090000, "activeJobs": ["j_a1b2c3d4"] } ],
  "jobs": [ /* 最近 50 条，元素同 /api/job 响应 */ ]
}

实例 90 秒内心跳视为存活；current 是频道并发池的当前上限（服务按失败自动降半、成功回升，介于 1 与 target 之间）。stats 为 24h 尝试/成功（rollup 历史 + 存活任务双源合并）与全时段最后成功时点。

GET / PUT /api/settings — 运行时设置

curl -X PUT https://agent-download.kukukala.com/api/settings \
  -H "x-auth-token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"maxInstances": 2, "jobsPerInstance": 2, "channelLimits": {"youtube": {"target": 3}}}'

GET /file/:jobId?token=… — 下载成品

downloadUrl 自带签名 token，无需再带 x-auth-token。支持 HEAD、Range 断点（206/416）、Content-Length，可直接喂给播放器。

# 整段下载
curl -OJ "https://agent-download.kukukala.com/file/j_a1b2c3d4?token=…"
# 断点续传（Range）
curl -H "Range: bytes=1048576-" -o part.mp4 "https://agent-download.kukukala.com/file/j_a1b2c3d4?token=…"

生命周期

48 小时计时从任务完成时开始（不是提交时）。到期后：410 Gone；URL token 失效同样 410；任务不存在 404。已开始的下载不会被主动中断，但过期后无法发起新请求。

GET /api/health — 渠道健康总览

curl -H "x-auth-token: $TOKEN" $BASE/api/health

{ "platforms": { "youtube": {
  "healthy": "unknown",          // healthy｜unhealthy（连败中）｜unknown（未探测）
  "lastProbeAt": 1759200000000, "lastResult": { "status": "failed", "errorCode": "youtube_blocked", "at": … },
  "failStreak": 3,               // channel 类连败（探针失败累加、成功清零）
  "infraFails": 0, "unknownCodes": 0,
  "sampleStale": false,          // true=样本失效（token 过期/视频删除），连败与修复触发冻结
  "urls": ["https://www.youtube.com/watch?v=…"],   // 样本 URL
  "expected": { "titleKeywords": […], "descriptionKeywords": […], "durationSRange": [60,300],
                "coverSha256": "…", "ordShas": […], "imageCount": 3 }   // sha 基准由首探成功自动写回（B5），只读
} } }

POST /api/health/:platform — 手动探针

用该渠道当前样本 URL 建一个 kind=probe 任务并立即补派。同渠道同时至多 1 个活跃探针（409 probe_active）；未配样本 409 no_sample_url。每周 cron 自动全渠道巡检一轮。

PUT /api/health/samples — 样本与预期基准编辑

curl -X PUT $BASE/api/health/samples -H "x-auth-token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"platform":"youtube","urls":["https://www.youtube.com/watch?v=…"],
       "expected":{"titleKeywords":["关键词"],"descriptionKeywords":["正文词"],"durationSRange":[60,300]}}'

GET /api/repairs · POST /api/repair/:platform · POST /api/repair/:id/rollback · GET /api/repair/:id/log

修复生命周期：pending → running（排他领取）→ published｜failed｜expired｜conflicted。自动触发条件：探针 channel 类连败 ≥3 且样本未失效（R1）。conflicted（发布时基线已被人移走）不立即重派——下次触发时自动以 retry_of 挂链新派一次。

POST /internal/repair/:id/:action — FC 侧回调（内部）

claim（排他领取，REPAIR_TOKEN）/ candidate（候选 zip，内容寻址封存）/ verify（验证结果与 CAS 发布，VERIFY_TOKEN 独立凭据，repair token 调它 401）/ patch（diff 留痕）/ failed / log。仅限 FC 容器回调，不走 API token。