写入 API

两个写入接口都要带 key，都收 JSON，都可能因为要抓 GitHub 数据而比读接口慢 （/repos 最长 60 秒，/projects 最长 300 秒——大仓库要拉 README、翻译技能文档）。

请求体只有两种形态复制标题链接

两个写入端点的请求体形状相同，都只收一个地址——要么完整 URL，要么裸的 owner/repo。两者都可选地带回调参数。

形态一：完整 URL复制标题链接

curl -X POST "$CONSOLE_ORIGIN/api/v1/repos" \
  -H "Authorization: Bearer $CONSOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/vercel/next.js"}'

url 接受 https://github.com/owner/repo、不带协议的 github.com/owner/repo、 owner/repo，末尾带 .git 或 / 也认。

形态二：裸 owner/repo复制标题链接

curl -X POST "$CONSOLE_ORIGIN/api/v1/repos" \
  -H "Authorization: Bearer $CONSOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repo":"vercel/next.js"}'

这种形态拒绝带协议的输入（{"repo":"https://github.com/vercel/next.js"} 返回 invalid_url）——两种形态各有各的写法，混着写只会让一半的请求白跑。

回调参数复制标题链接

两个形态都接受 callbackUrl + callbackSecret，成对出现：给了地址没给密钥返回 invalid_body。

curl -X POST "$CONSOLE_ORIGIN/api/v1/repos" \
  -H "Authorization: Bearer $CONSOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "vercel/next.js",
    "callbackUrl": "https://example.com/hooks/radar",
    "callbackSecret": "your-shared-secret"
  }'

落库完成之后服务端同步发一次回调，等它返回或超时（30 秒）才响应你的请求。 同步是故意的：异步发出去的话，回调地址写错这件事永远不会被发现。

请求体：

{
  "eventId": "repo.registered.V1StGXR8Z5jd",
  "event": "repo.registered",
  "occurredAt": "2026-03-24T08:12:03.000Z",
  "fullName": "vercel/next.js",
  "repoId": "V1StGXR8Z5jd",
  "created": true
}

event 只有两个取值：登记是 repo.registered，发布是 repo.published（多带一个 projectId）。eventId 由事件名加 repoId 派生，不是随机值——同一个写请求 因为超时被重发时它不变，接收方按它去重就能认出这是同一件事，而不是两次独立的 登记。

签名头与订阅投递完全一致，用同一段代码算：

验签要按原始字节算：先解析 JSON 再重新序列化，字段顺序或空格变了，签名就对不上。 收到的时间戳与当前时间相差超过 300 秒就丢掉——那是重放。

POST /api/v1/repos — 登记一个仓库复制标题链接

让它开始跟踪，不会发布任何东西。

响应复制标题链接

{
  "ok": true,
  "repo": { "id": "V1StGXR8Z5jd", "full_name": "vercel/next.js", "stars": 132000 },
  "created": true,
  "projectCount": 0
}

created 区分「新建」与「刷新」；projectCount 是已经有多少个已发布的项目 指向这个仓库——登记端点自己不建 project，所以它非零只可能因为这个仓库先前被 策展过，这时你传的 type 会被拒绝而不是被采纳，看到这个数就知道了。

失败时是统一的错误形状（见调用、限流与错误）：invalid_body （附 detail 指出第一个不合法的字段）、invalid_url、type_not_accepted、 insufficient_scope、rate_limited、github_unavailable。

POST /api/v1/projects — 发布一个项目复制标题链接

把一个仓库策展成 project，也就是放到公开站上。地址同样有两种写法，另加可选的 type（缺省 application）与那对回调参数。

curl -X POST "$CONSOLE_ORIGIN/api/v1/projects" \
  -H "Authorization: Bearer $CONSOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repo":"vercel/next.js","type":"application"}'

请求体：

响应复制标题链接

{
  "ok": true,
  "status": "created",
  "repo": { "full_name": "vercel/next.js" },
  "project": { "...": "整行 project 数据" },
  "readme": { "...": "解析后的 README" },
  "skills": { "count": 0, "translated": 0, "empty": false },
  "authorLinked": true,
  "delivered": null
}

• project、readme、skills 是这次写进去的东西；skills 只有 type: "skill" 时才有意义。
• delivered 只对 skill 有意义：true 表示技能已经推到下游站点、那边现在就能用； false 表示有技能没推成功（行已经进重试队列）；null 表示这个部署没配下游， 不是失败。
• 已经发布过的仓库再调一次不会建第二行，返回 existing。此时若 type 是 skill， 技能同步会重新跑一遍——调用方要的是「现在就能拿到技能」，不能只答一个 existing 就把人丢去等调度器。

失败：invalid_body、invalid_url、insufficient_scope（这把 key 没有 projects:write）、create_failed（502，可以重试）、github_unavailable。

写入之后会发生什么复制标题链接