6.3 KiB
API 接入指南
认证
工作台使用 HttpOnly Cookie；外部客户端使用：
Authorization: Bearer dd_live_xxx
平台级 Key 可跨组创建和查询项目。项目级 Key 只能操作绑定项目，包括在该项目中新建作品和验收轮次。密钥明文只在创建时返回一次。
Agent 安全上传 Skill
项目内置 .agents/skills/upload-delivery-desk-work，用于引导 Agent 精确定位运营组、项目和作品后创建作品或提交新验收轮次。它强制执行“发现 → 生成计划 → 操作者确认 → 单次提交 → 回读验证”，不允许根据名称猜测目标。
更新 Skill 后重新生成分发包：
powershell -ExecutionPolicy Bypass -File scripts/package-upload-skill.ps1
压缩包输出到 skill-packages/upload-delivery-desk-work.zip。API Key 只能通过 DELIVERY_DESK_API_KEY 环境变量提供，不应写入 Skill、计划文件或命令参数。
发现资源
# 查询 Key 可访问的项目，响应包含 group_id、group_name 和项目 id
curl http://localhost:3010/api/projects \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
# 查询项目作品
curl http://localhost:3010/api/projects/1/works \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
调用方不再需要作品交付集 ID。externalId 在项目内唯一，可用于安全重试和找回作品。
创建项目
只有平台级 Key 可以创建项目。
curl -X POST http://localhost:3010/api/projects \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"7 月内容计划","slug":"july-content","groupId":1,"client_description":"客户可见说明"}'
创建作品
JSON 请求中的 images 为 1–30 个公开 HTTP/HTTPS URL，且平台必须已有活动 COS 配置。数组顺序就是展示顺序，第一张为封面。
- 所有 URL 都会先拒绝
localhost、本机、私有网段、局域网和保留地址；即使域名与配置同源也不会绕过这项检查。 - URL 与活动 COS 的公开域名或 CDN 域名同源时直接保存，不重复上传。
- 其他域名的图片会由服务端下载并转存到活动 COS，最终入库 URL 来自该 COS。
- 外部图片单张不得超过 20 MB，必须返回受支持的图片类型；本机、内网、保留地址和非标准端口会被拒绝。
curl -X POST http://localhost:3010/api/projects/1/works \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId":"client-work-20260722-001",
"title":"作品标题",
"description":"正文内容",
"tags":["#夏日","用户原文"],
"images":["https://cdn.example.com/01.jpg","https://cdn.example.com/02.jpg"]
}'
相同 projectId + externalId 的重试不会重复创建，响应包含 idempotent: true。异源图片成功转存后不再依赖原地址长期可用；任意图片校验或转存失败时不会创建作品记录。
本地文件上传
外部 Agent 只有本地图片时，不需要转换为 Base64。相同接口支持 multipart/form-data，重复使用 images 文件字段，并通过 Bearer API Key 鉴权：
curl -X POST http://localhost:3010/api/projects/1/works \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
-F "externalId=client-2026-002" \
-F "title=本地生成作品" \
-F 'tags=["#本地文件"]' \
-F "images=@01.png" \
-F "images=@02.png"
URL 与本地文件不能在同一次请求中混用。文件顺序即展示顺序，第一张为封面；单张不超过 20 MB，服务端会校验真实图片内容并上传到活动 COS。
创建新验收轮次
每轮只能提交一个方案。标题、正文、标签和图片会形成不可修改的轮次快照；新轮次自动锁定上一轮。
curl -X POST http://localhost:3010/api/works/12/rounds \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title":"修改后的标题",
"description":"修改后的正文",
"tags":["#第二轮"],
"images":["https://cdn.example.com/round-2.jpg"]
}'
查询作品与全部反馈
# 当前轮或指定轮
curl "http://localhost:3010/api/works/12?round=2" \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
# 按轮返回该作品全部反馈和验收事件
curl http://localhost:3010/api/works/12/annotations \
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
标题、正文和 Tag 选区批注使用：
{
"round_number": 2,
"target": "description",
"start_offset": 4,
"end_offset": 8,
"selected_text": "选中文字",
"content": "这里需要调整"
}
服务会校验偏移量和所选文字是否匹配当前轮次快照。历史轮次或已完成项目返回 409。
批注、文字批注和总体反馈都可回复，类型分别为 image_annotation、text_annotation、comment：
POST /api/works/:workId/feedback/:type/:feedbackId/replies
POST /api/works/:workId/feedback/:type/:feedbackId/withdraw
撤回只允许原作者执行，不会删除数据库记录。客户入口在路径前增加 /api/review/:slug，并执行相同的项目归属与身份校验。
客户验收
客户输入项目密码和姓名后使用 Cookie 调用：
curl -X POST http://localhost:3010/api/review/july-content/works/12/decision \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{"round_number":2,"decision":"approved"}'
decision 为 approved 或 changes_requested；退修必须填写 reason。只允许决定活动轮次。
客户侧全部反馈接口为 /api/review/:slug/works/:workId/annotations，仍会校验客户会话绑定的项目。
兼容接口
旧的 /api/notes、/api/notes/:id/versions、/api/notes/:id/review-rounds 与 /api/projects/:id/collections 暂保留一个兼容周期。旧交付集 URL 会跳转到项目页；旧多候选稿请求会返回 400，不会再创建多方案轮次。新接入必须使用项目、作品和轮次接口。
错误响应均包含 { "error": "错误说明" }。常见状态码：400 输入无效或地址被安全策略拒绝、401 未认证、403 越权、404 不存在、409 状态冲突或未启用 COS、413 图片超过 20 MB、422 外部图片无法下载或内容无效、502 转存 COS 失败。