6.5 KiB
Prompt Museum 服务端协作契约
状态：客户端第一版已按本契约接入。服务端可以先实现接口和数据后台，再逐步补充内容。
1. 产品边界
Prompt Museum（提示词博物馆）是 Makelore Canvas 的灵感陈列模块，不是社区，也不承载用户关系链。
V1 只做：
- 展示经过审核的作品预览、提示词和分类；
- 支持搜索、按使用场景/风格/主体筛选、分页；
- 查看作者、来源、许可证和署名说明；
- 将完整 Prompt 带回当前 Canvas 设计会话的输入框，用户自行修改后发送。
V1 不做：
- 用户投稿、评论、点赞、收藏、关注、排行榜；
- 用户作品发布或上传到博物馆；
- 在客户端打包静态 Prompt 数据集；
- 服务端代替用户自动发送 Prompt 或直接生成作品。
客户端入口位于 Canvas 侧栏“新建设计项目”上方，按钮文案为“获取灵感”。
2. 请求链路与接口
Renderer 只请求本地 Host API；Main 负责 Works Square 登录态、上游鉴权和代理。Renderer 不接触 Works Square access token，也不应直连上游服务。
| 层 | 方法 | 路径 | 用途 |
|---|---|---|---|
| Host API | GET |
/api/works/image-prompt-museum |
获取分页卡片和筛选项 |
| Host API | GET |
/api/works/image-prompt-museum/:id |
获取单条完整详情 |
| Works Square 上游 | GET |
/api/image-prompt-museum |
与 Host API 对应的服务端实现 |
| Works Square 上游 | GET |
/api/image-prompt-museum/:id |
与 Host API 对应的服务端实现 |
Host API 会把当前用户的 Works Square Bearer Token 放在上游请求中。无登录态返回 401，上游错误不要伪装成空列表。
列表查询参数
所有参数可选，客户端只会发送以下白名单字段：
| 参数 | 类型 | 说明 |
|---|---|---|
q |
string | 标题、摘要、Prompt 的服务端全文搜索；建议限制长度 120 |
use_case |
string | 使用场景分类 id |
style |
string | 风格分类 id |
subject |
string | 主体分类 id |
language |
string | zh-CN、en 等语言代码 |
model |
string | 模型 id |
cursor |
string | 不透明分页游标 |
limit |
integer | 1–48，默认 24 |
默认排序使用后台策展顺序；不要按点赞、浏览或用户互动排序。
统一响应封装
成功响应：
{
"success": true,
"data": {
"items": [],
"facets": {
"useCases": [],
"styles": [],
"subjects": []
},
"nextCursor": null,
"total": 0
}
}
详情响应：
{
"success": true,
"data": {
"id": "prompt-001",
"slug": "editorial-product-poster",
"title": "编辑感产品海报",
"summary": "适合把产品主体放进留白充足的编辑版式。",
"thumbnail": {
"url": "https://cdn.example.com/prompt-001/thumb.webp",
"width": 1200,
"height": 900,
"alt": "编辑感产品海报示例"
},
"categories": [
{ "id": "poster", "name": "海报", "group": "use_case" },
{ "id": "editorial", "name": "编辑感", "group": "style" },
{ "id": "product", "name": "产品", "group": "subject" }
],
"model": { "id": "gpt-image-2", "name": "GPT Image 2" },
"language": "zh-CN",
"attribution": {
"author": { "name": "作者名称", "url": "https://example.com/author" },
"source": { "name": "来源名称", "url": "https://example.com/source" },
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/",
"attributionText": "作者名称 / 来源名称 / CC BY 4.0"
}
},
"publishedAt": "2026-08-01T00:00:00Z",
"updatedAt": "2026-08-01T00:00:00Z",
"prompt": "Create a clean editorial product poster...",
"variables": [],
"images": [
{
"url": "https://cdn.example.com/prompt-001/result.webp",
"width": 1200,
"height": 900,
"alt": "编辑感产品海报示例"
}
],
"requiresReferenceImages": false
}
}
字段的 TypeScript 定义在 shared/image-prompt-museum.ts，服务端字段命名请与其保持一致。
3. 数据发布与合规门槛
只有通过后台审核的记录才能进入列表。每条记录必须同时具备：
- 非空
attribution.author.name； - 可访问的
attribution.source.url； - 明确的
attribution.license.name和attribution.license.attributionText； - 作品预览与 Prompt 的授权状态；
publishedAt、updatedAt和稳定不可变的id。
如果原作者未知，不要静默省略作者字段；请在后台按合规流程处理“未署名/待核实”记录，未核实记录不要发布到客户端。
来源、作者和许可证必须在详情抽屉中可见。客户端不会替服务端推断或补全版权信息。
图片 URL 应为 HTTPS 的 CDN 地址或短期签名 URL，不要在 URL 或 JSON 中放 access token、内部存储路径或用户隐私。若未来必须使用受保护素材，应新增 Main-owned 媒体代理，不要让 Renderer 直连带凭据的对象存储。
Prompt 可以保留模板变量，但 V1 客户端按原文回填，不做插值和自动发送。建议变量沿用 {argument name="..." default="..."} 这类明确语法，并把可编辑变量同步放在 variables 数组中。
4. 错误码
错误仍使用项目现有封装：
{
"success": false,
"status": 503,
"code": "PROMPT_MUSEUM_UNAVAILABLE",
"error": "提示词博物馆暂时不可用"
}
建议至少支持：
PROMPT_MUSEUM_AUTH_REQUIRED（401）；PROMPT_MUSEUM_NOT_FOUND（404）；PROMPT_MUSEUM_INVALID_QUERY（400）；PROMPT_MUSEUM_UNAVAILABLE（502/503）。
空结果是正常业务状态，应返回 200 + items: []，不要用 404 表示搜索无结果。
5. 内容来源参考
外部 Prompt 目录可作为内容组织和分类方式的参考，但不是 Makelore 的现成前端或数据依赖：
- YouMind awesome-gpt-image-2：可参考 Use Cases / Styles / Subjects 的分类与 Prompt 展示方式；导入任何内容前仍需单独确认授权和署名。
- GPT Image 2 官方模型文档：模型能力与接口以官方文档为准，不以第三方目录的描述为准。
外部内容进入库前，请保留原始来源 URL、作者、许可证和审核记录，避免把“参考展示”误解为内容再授权。