# 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、作者、许可证和审核记录，避免把“参考展示”误解为内容再授权。