{
  "openapi": "3.1.0",
  "info": {
    "title": "NexusMC 公共 API v1",
    "version": "1.0.0",
    "description": "独立资源只读网关。默认 server 仅是本地开发示例，不是生产地址；部署后由运营方提供实际 origin。允许匿名读取；可选 PAT 或 OAuth access Bearer 必须具备 resource:read:feed，错误凭据绝不降级匿名。任何 Cookie 请求头均返回 400，不发 Cookie，不承担网站会话。仅支持本规范三条路径的 GET/HEAD；已知路径其他方法返回 405，Allow: GET, HEAD，未知版本/路径返回 404。未知参数、重复标量、非法编码/UTF-8、空多选值和请求正文返回 400。查询键和值中的 C0（U+0000–U+001F）及 DEL（U+007F）在 trim 去除首尾空白前拒绝；正常 Unicode 查询与正文文本保留，不使用整段文本过滤。请求 URI 最多 16 KiB、最多 256 个查询参数；响应最多 2 MiB。HTTP 固定最多 256 条已接受连接，默认最多 64 个并发 RPC 槽位，两者分别计数。默认 CORS 不开放；限流按规范化客户端 IP 且各网关副本独立。成功不包装 data/ok；错误使用 error.code/message。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:4520",
      "description": "本地开发示例地址，不是生产服务地址。"
    }
  ],
  "tags": [
    {
      "name": "公共资源 v1",
      "description": "资源列表、详情和当前公开构建。"
    }
  ],
  "paths": {
    "/v1/resources": {
      "get": {
        "operationId": "publicV1ListResources",
        "summary": "筛选公开资源",
        "description": "列表、计数与筛选读取同一快照。loader、mc、type 必须在同一原始发布记录上同时满足；同维度 OR、跨维度 AND。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "capability",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "关键字最多 200 个 UTF-16 单元（补充平面字符占两个单元）。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "排序方式。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "enum": [
                "updated",
                "downloads"
              ],
              "default": "updated"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "页码；使用 cursor 时只能为 1。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "每次读取的最大条数。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "不透明签名游标，仅允许 sort=updated 且 page=1；继续分页时保持其它筛选一致。格式、签名、版本或范围错误返回 400/INVALID_INPUT；列表快照过期返回 409/CURSOR_STALE。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "maxLength": 4096
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功。所有声明的 JSON 字段稳定存在，空值明确为 null。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceList"
                },
                "example": {
                  "items": [
                    {
                      "id": "01K7EXAMPLE0000000000000001",
                      "slug": "example-resource",
                      "title": "示例资源",
                      "summary": "资源摘要示例。",
                      "ownerId": "01K7EXAMPLE0000000000000002",
                      "coverUrl": null,
                      "tags": [
                        {
                          "slug": "utility",
                          "label": "实用工具",
                          "dimension": "gameplay"
                        }
                      ],
                      "capabilities": [
                        "download"
                      ],
                      "loaders": [
                        "fabric"
                      ],
                      "releaseCount": 1,
                      "matchedReleaseCount": 1
                    }
                  ],
                  "total": "1",
                  "page": 1,
                  "limit": 20,
                  "nextCursor": null
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "publicV1HeadListResources",
        "summary": "筛选公开资源（HEAD）",
        "description": "列表、计数与筛选读取同一快照。loader、mc、type 必须在同一原始发布记录上同时满足；同维度 OR、跨维度 AND。 HEAD 执行相同参数、认证与可见性检查，只返回状态和响应头。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "capability",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "关键字最多 200 个 UTF-16 单元（补充平面字符占两个单元）。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "排序方式。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "enum": [
                "updated",
                "downloads"
              ],
              "default": "updated"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "页码；使用 cursor 时只能为 1。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "每次读取的最大条数。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "不透明签名游标，仅允许 sort=updated 且 page=1；继续分页时保持其它筛选一致。格式、签名、版本或范围错误返回 400/INVALID_INPUT；列表快照过期返回 409/CURSOR_STALE。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "string",
              "maxLength": 4096
            }
          }
        ],
        "responses": {
          "200": {
            "description": "与 GET 相同的状态和响应头，不发送响应正文。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          }
        }
      }
    },
    "/v1/resources/{slug}": {
      "get": {
        "operationId": "publicV1GetResource",
        "summary": "读取公开资源详情",
        "description": "返回稳定资源投影，不嵌入发布历史。构建选择请使用 updates；其兼容性仍在同一原始发布记录上判断。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "小写 ASCII 字母数字及单连字符，长度 1–100。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            }
          },
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功。所有声明的 JSON 字段稳定存在，空值明确为 null。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceResult"
                },
                "example": {
                  "resource": {
                    "id": "01K7EXAMPLE0000000000000001",
                    "slug": "example-resource",
                    "title": "示例资源",
                    "summary": "资源摘要示例。",
                    "ownerId": "01K7EXAMPLE0000000000000002",
                    "coverUrl": null,
                    "tags": [
                      {
                        "slug": "utility",
                        "label": "实用工具",
                        "dimension": "gameplay"
                      }
                    ],
                    "capabilities": [
                      "download"
                    ],
                    "loaders": [
                      "fabric"
                    ],
                    "releaseCount": 1,
                    "matchedReleaseCount": 1,
                    "body": "示例正文。",
                    "mcVersions": [
                      "1.20.1"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "publicV1HeadGetResource",
        "summary": "读取公开资源详情（HEAD）",
        "description": "返回稳定资源投影，不嵌入发布历史。构建选择请使用 updates；其兼容性仍在同一原始发布记录上判断。 HEAD 执行相同参数、认证与可见性检查，只返回状态和响应头。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "小写 ASCII 字母数字及单连字符，长度 1–100。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            }
          },
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "与 GET 相同的状态和响应头，不发送响应正文。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          }
        }
      }
    },
    "/v1/resources/{slug}/updates": {
      "get": {
        "operationId": "publicV1ResourceUpdates",
        "summary": "读取当前兼容更新构建",
        "description": "当前公开原始发布快照，默认稳定渠道，按发布时间倒序。相同文件和版本号也不合并兼容配对。无历史游标，hasMore 表示还有更旧构建；安装前再次复核。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "小写 ASCII 字母数字及单连字符，长度 1–100。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            }
          },
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "releaseType",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "enum": [
                  "release",
                  "beta",
                  "alpha"
                ]
              },
              "default": [
                "release"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "每次读取的最大条数。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "支持单个或逗号分隔的 ETag、弱标签以及 *。公开 ETag 绑定 PUBLIC_API_SITE_ORIGIN；网关只将当前 origin 的有效公开标签解包后传给 Node，Node 每次仍执行用户认证与资源可见性门禁。未知标签或旧 origin 标签作为不匹配处理，返回 200；* 保留正常存在性语义，也须经过同样门禁。不能在网关仅凭旧缓存返回 304。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功。所有声明的 JSON 字段稳定存在，空值明确为 null。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "ETag": {
                "description": "当前 v1 HTTP JSON 表示的实体标签，绑定 PUBLIC_API_SITE_ORIGIN 网站 origin，因为下载 URL 的绝对化会改变表示；仅在本次完整查询和权限复核后产生。",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceUpdates"
                },
                "example": {
                  "resource": {
                    "id": "01K7EXAMPLE0000000000000001",
                    "slug": "example-resource",
                    "title": "示例资源"
                  },
                  "revision": "1:1:1",
                  "items": [
                    {
                      "id": "01K7EXAMPLE0000000000000003",
                      "versionNumber": "1.0.0",
                      "name": null,
                      "releaseType": "release",
                      "publishedAt": "2026-10-15T00:00:00.123456Z",
                      "loaders": [
                        "fabric"
                      ],
                      "mcVersions": [
                        "1.20.1"
                      ],
                      "files": [
                        {
                          "id": "01K7EXAMPLE0000000000000004",
                          "filename": "example.jar",
                          "size": "4096",
                          "sha512": null,
                          "isPrimary": true,
                          "url": "https://files.example.test/example.jar",
                          "format": "jar"
                        }
                      ]
                    }
                  ],
                  "hasMore": false
                }
              }
            }
          },
          "304": {
            "description": "资源可见性与用户认证均完成本次复核，当前表示符合 If-None-Match；无正文。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "ETag": {
                "description": "当前 v1 HTTP JSON 表示的实体标签，绑定 PUBLIC_API_SITE_ORIGIN 网站 origin，因为下载 URL 的绝对化会改变表示；仅在本次完整查询和权限复核后产生。",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "publicV1HeadResourceUpdates",
        "summary": "读取当前兼容更新构建（HEAD）",
        "description": "当前公开原始发布快照，默认稳定渠道，按发布时间倒序。相同文件和版本号也不合并兼容配对。无历史游标，hasMore 表示还有更旧构建；安装前再次复核。 HEAD 执行相同参数、认证与可见性检查，只返回状态和响应头。",
        "tags": [
          "公共资源 v1"
        ],
        "security": [
          {},
          {
            "PublicBearer": []
          }
        ],
        "x-required-scope": "resource:read:feed",
        "x-cookie-policy": "reject",
        "x-unknown-query-parameters": "reject",
        "x-request-body-policy": "reject",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "小写 ASCII 字母数字及单连字符，长度 1–100。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            }
          },
          {
            "name": "loader",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "mc",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          },
          {
            "name": "releaseType",
            "in": "query",
            "required": false,
            "style": "form",
            "explode": true,
            "description": "可重复同名参数，也可用逗号分隔；同维度为 OR，跨维度为 AND。每维最多 64 个非空值，每值最多 128 个字符；在 trim 去除首尾空白前拒绝 C0/DEL 控制字符。",
            "schema": {
              "type": "array",
              "maxItems": 64,
              "items": {
                "type": "string",
                "enum": [
                  "release",
                  "beta",
                  "alpha"
                ]
              },
              "default": [
                "release"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "x-repeatable": false,
            "description": "每次读取的最大条数。 单值参数，重复同名键返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "支持单个或逗号分隔的 ETag、弱标签以及 *。公开 ETag 绑定 PUBLIC_API_SITE_ORIGIN；网关只将当前 origin 的有效公开标签解包后传给 Node，Node 每次仍执行用户认证与资源可见性门禁。未知标签或旧 origin 标签作为不匹配处理，返回 200；* 保留正常存在性语义，也须经过同样门禁。不能在网关仅凭旧缓存返回 304。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "与 GET 相同的状态和响应头，不发送响应正文。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "ETag": {
                "description": "当前 v1 HTTP JSON 表示的实体标签，绑定 PUBLIC_API_SITE_ORIGIN 网站 origin，因为下载 URL 的绝对化会改变表示；仅在本次完整查询和权限复核后产生。",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "资源可见性与用户认证均完成本次复核，当前表示符合 If-None-Match；无正文。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "ETag": {
                "description": "当前 v1 HTTP JSON 表示的实体标签，绑定 PUBLIC_API_SITE_ORIGIN 网站 origin，因为下载 URL 的绝对化会改变表示；仅在本次完整查询和权限复核后产生。",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "参数、编码、重复标量、Cookie 或 GET/HEAD 正文不合法。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "401": {
            "description": "提供的用户 Bearer 无效、过期或已撤销；不降级为匿名请求。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "403": {
            "description": "提供的 PAT/OAuth Bearer 缺少 resource:read:feed 权限。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "404": {
            "description": "资源不存在、未公开或已删除；未知版本和路径同样返回 404。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "409": {
            "description": "CURSOR_STALE：列表快照已过期，请重新开始列表分页；游标格式、签名、版本或范围错误返回 400。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          },
          "429": {
            "description": "当前客户端 IP 的请求频率超过额度。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "服务暂不可用或当前容量已满。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              },
              "Retry-After": {
                "description": "存在时为建议等待的秒数。",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "504": {
            "description": "查询超时；可稍后重试。",
            "headers": {
              "Cache-Control": {
                "description": "不得缓存到共享或持久缓存。",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              },
              "X-Content-Type-Options": {
                "schema": {
                  "type": "string",
                  "const": "nosniff"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PublicBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "PAT / OAuth access token",
        "description": "可选。PAT 或 OAuth access token 必须具备 resource:read:feed；缺省时匿名，提供后无效则返回 401/403，不退回匿名。文档不预填凭据。"
      }
    },
    "schemas": {
      "Tag": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "slug",
          "label",
          "dimension"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "dimension": {
            "type": "string",
            "description": "开放标签维度：gameplay、style、quality 或 unclassified。"
          }
        }
      },
      "ResourceSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "title",
          "summary",
          "ownerId",
          "coverUrl",
          "tags",
          "capabilities",
          "loaders",
          "releaseCount",
          "matchedReleaseCount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "不透明资源 ID。"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "ownerId": {
            "type": "string",
            "description": "不透明所有者 ID，不包含账户私有资料。"
          },
          "coverUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "能力 ID；不包含网站展示结构或任意能力载荷。"
          },
          "loaders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "releaseCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "展示合并单元总数，并非原始发布行数。"
          },
          "matchedReleaseCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "同一原始发布记录满足当前 loader、mc、type 条件的展示合并单元数。"
          }
        }
      },
      "ResourceDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "title",
          "summary",
          "ownerId",
          "coverUrl",
          "tags",
          "capabilities",
          "loaders",
          "releaseCount",
          "matchedReleaseCount",
          "body",
          "mcVersions"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "不透明资源 ID。"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "ownerId": {
            "type": "string",
            "description": "不透明所有者 ID，不包含账户私有资料。"
          },
          "coverUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "能力 ID；不包含网站展示结构或任意能力载荷。"
          },
          "loaders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "releaseCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "展示合并单元总数，并非原始发布行数。"
          },
          "matchedReleaseCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "同一原始发布记录满足当前 loader、mc、type 条件的展示合并单元数。"
          },
          "body": {
            "type": [
              "string",
              "null"
            ],
            "description": "原始正文文本；客户端按自己的输出上下文安全呈现，不执行其中的 HTML。"
          },
          "mcVersions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ResourceList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "limit",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceSummary"
            },
            "maxItems": 50
          },
          "total": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "非负十进制整数字符串；不要转换成可能丢失精度的 JavaScript number。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "不透明游标；没有后续游标时固定为 null。仅 updated 排序提供。"
          }
        }
      },
      "ResourceResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource"
        ],
        "properties": {
          "resource": {
            "$ref": "#/components/schemas/ResourceDetail"
          }
        }
      },
      "ResourceRef": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        }
      },
      "UpdateFile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "filename",
          "size",
          "sha512",
          "isPrimary",
          "url",
          "format"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "size": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "非负十进制整数字符串；不要转换成可能丢失精度的 JavaScript number。"
          },
          "sha512": {
            "type": [
              "string",
              "null"
            ],
            "description": "已知的 SHA512；未知时固定为 null。哈希不授予文件所有权或读取权限。"
          },
          "isPrimary": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "绝对下载 URL；读取可能仍需相应权限。"
          },
          "format": {
            "type": "string"
          }
        }
      },
      "UpdateRelease": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "versionNumber",
          "name",
          "releaseType",
          "publishedAt",
          "loaders",
          "mcVersions",
          "files"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "versionNumber": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "releaseType": {
            "type": "string",
            "enum": [
              "release",
              "beta",
              "alpha"
            ]
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC 发布时间字符串，保留原始微秒精度；不要重新格式化后用于排序或游标。"
          },
          "loaders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mcVersions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UpdateFile"
            }
          }
        }
      },
      "ResourceUpdates": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "revision",
          "items",
          "hasMore"
        ],
        "properties": {
          "resource": {
            "$ref": "#/components/schemas/ResourceRef"
          },
          "revision": {
            "type": "string",
            "description": "不透明当前快照 revision，不能当作时间或历史事件序号。"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UpdateRelease"
            },
            "maxItems": 50
          },
          "hasMore": {
            "type": "boolean",
            "description": "还有更旧的当前公开构建；本接口不提供历史分页游标。"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "稳定公开错误代码，例如 INVALID_INPUT、CURSOR_STALE；不包含内部异常细节。"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
