174 lines
6.5 KiB
Markdown
174 lines
6.5 KiB
Markdown
# 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 |
|
||
|
||
默认排序使用后台策展顺序；不要按点赞、浏览或用户互动排序。
|
||
|
||
### 统一响应封装
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [],
|
||
"facets": {
|
||
"useCases": [],
|
||
"styles": [],
|
||
"subjects": []
|
||
},
|
||
"nextCursor": null,
|
||
"total": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
详情响应：
|
||
|
||
```json
|
||
{
|
||
"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`](../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. 错误码
|
||
|
||
错误仍使用项目现有封装：
|
||
|
||
```json
|
||
{
|
||
"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](https://github.com/YouMind-OpenLab/awesome-gpt-image-2)：可参考 Use Cases / Styles / Subjects 的分类与 Prompt 展示方式；导入任何内容前仍需单独确认授权和署名。
|
||
- [GPT Image 2 官方模型文档](https://developers.openai.com/api/docs/models/gpt-image-2)：模型能力与接口以官方文档为准，不以第三方目录的描述为准。
|
||
|
||
外部内容进入库前，请保留原始来源 URL、作者、许可证和审核记录，避免把“参考展示”误解为内容再授权。
|