{"openapi":"3.1.0","info":{"title":"游隙管理 API","version":"1.0.0","description":"当前管理 HTTP 接口与健康检查。input 结构从运行时 Zod 合约生成；跨字段、文件和业务约束仍以服务器校验为准。授权请使用本地 MCP 客户端的浏览器授权流程。"},"servers":[{"url":"https://scalia.ltd"}],"externalDocs":{"url":"https://scalia.ltd/docs/api"},"components":{"securitySchemes":{"managementBearer":{"type":"http","scheme":"bearer","description":"经站主授权的管理访问令牌。客户端自动刷新；不要使用网站密码或 SMTP 授权码。"},"managementWebSession":{"type":"apiKey","in":"cookie","name":"__Host-youxi-web.session_token","description":"正式站网页登录会话，由浏览器管理。"},"managementWebCsrf":{"type":"apiKey","in":"header","name":"X-Youxi-Csrf","description":"当前网页会话的 CSRF 值；还需同源 Origin、X-Youxi-Request: 1。"}}},"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"公开健康检查","responses":{"200":{"description":"服务正常"},"503":{"description":"服务降级"}}}},"/api/v1/manage/status":{"get":{"operationId":"managementStatus","summary":"检查管理连接","security":[{"managementBearer":[]}],"responses":{"200":{"description":"已授权","content":{"application/json":{"schema":{"type":"object","required":["connected"],"properties":{"connected":{"const":true},"connectionId":{"type":"string"}}}}}},"401":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"403":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"503":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}}}}},"/api/v1/manage":{"post":{"operationId":"managementAction","summary":"执行管理动作","security":[{"managementBearer":[]},{"managementWebSession":[],"managementWebCsrf":[]}],"description":"只读动作直接返回数据；写动作返回含 data 的结果信封。JSON 请求体最多 128 KiB。写操作需要 requestId 和稳定 idempotencyKey。add_owner/remove_owner 仅供主管理员在网页后台使用，要求有效网页会话、同源请求和 X-Youxi-Csrf，Bearer 令牌不能执行；这两个动作不暴露为 MCP 工具。","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"list_comments","description":"分页读取评论与待处理举报","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_comments"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cursor":{"type":"string","maxLength":500},"limit":{"default":20,"type":"integer","minimum":1,"maximum":50},"filter":{"default":"reported","type":"string","enum":["reported","visible","hidden","all"]},"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"moderate_comment","description":"隐藏、恢复评论或忽略待处理举报","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"moderate_comment"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"commentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"decision":{"type":"string","enum":["hide","restore","dismiss_reports"]}},"required":["commentId","expectedRevision","decision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"get_overview","description":"读取管理概览","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"get_overview"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"get_analytics","description":"按北京时间读取用户与游戏统计","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"get_analytics"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"days":{"default":7,"anyOf":[{"type":"number","const":1},{"type":"number","const":7},{"type":"number","const":30}]}},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"list_recent_accounts","description":"读取最近 10 个注册账号","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_recent_accounts"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"list_games","description":"列出游戏","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_games"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"get_game","description":"读取游戏、工作稿和历史候选","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"get_game"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["gameId"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"create_game","description":"创建游戏工作稿","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"create_game"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","maxLength":80,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"snapshot":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":100},"summary":{"type":"string","maxLength":500},"description":{"default":"","type":"string","maxLength":10000},"instructions":{"default":"","type":"string","maxLength":5000},"devices":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["desktop","mobile"]}},"categories":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"coverId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["title","summary","devices"],"additionalProperties":false}},"required":["slug","snapshot"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"save_game_draft","description":"保存游戏资料工作稿","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"save_game_draft"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedDraftRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"snapshot":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":100},"summary":{"type":"string","maxLength":500},"description":{"default":"","type":"string","maxLength":10000},"instructions":{"default":"","type":"string","maxLength":5000},"devices":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["desktop","mobile"]}},"categories":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"coverId":{"default":null,"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},"required":["title","summary","devices"],"additionalProperties":false}},"required":["gameId","expectedDraftRevision","snapshot"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"create_game_preview","description":"冻结游戏候选并取得私有预览路径","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"create_game_preview"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedDraftRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["gameId","expectedDraftRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"publish_game","description":"发布指定游戏候选","x-required-scope":"manage:publish","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"publish_game"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"candidateId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedStateRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["gameId","candidateId","expectedStateRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"set_game_availability","description":"设置游戏上架或下架","x-required-scope":"manage:publish","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"set_game_availability"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"available":{"type":"boolean"},"expectedStateRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["gameId","available","expectedStateRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"rollback_game","description":"切回曾经发布的游戏版本","x-required-scope":"manage:publish","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"rollback_game"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"versionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedStateRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["gameId","versionId","expectedStateRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"get_site_config","description":"读取站点配置与历史","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"get_site_config"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"save_site_draft","description":"保存站点工作稿","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"save_site_draft"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"expectedDraftRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"snapshot":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"intro":{"type":"string","maxLength":500},"categories":{"maxItems":30,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":30}},"required":["id","name"],"additionalProperties":false}},"featured":{"maxItems":12,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"recommended":{"maxItems":12,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"order":{"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["name","intro","categories","featured","recommended","order"],"additionalProperties":false}},"required":["expectedDraftRevision","snapshot"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"create_site_preview","description":"冻结站点候选","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"create_site_preview"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"expectedDraftRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedDraftRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"publish_site_config","description":"发布指定站点候选","x-required-scope":"manage:publish","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"publish_site_config"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"candidateId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedStateRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["candidateId","expectedStateRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"rollback_site_config","description":"切回曾经发布的站点版本","x-required-scope":"manage:publish","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"rollback_site_config"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"versionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedStateRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["versionId","expectedStateRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"find_accounts","description":"按完整邮箱或 ID 查询账号","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"find_accounts"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":254}},"required":["query"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"list_owners","description":"列出站主与主管理员","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_owners"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"add_owner","description":"主管理员添加已验证的站主","x-required-scope":"manage:accounts","x-primary-web-session-only":true,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"add_owner"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"userId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedAccountRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["userId","expectedAccountRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"remove_owner","description":"主管理员移除站主","x-required-scope":"manage:accounts","x-primary-web-session-only":true,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"remove_owner"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"userId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedAccountRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["userId","expectedAccountRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"set_account_status","description":"停用或恢复账号","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"set_account_status"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"userId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"disabled":{"type":"boolean"},"expectedAccountRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["userId","disabled","expectedAccountRevision"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"list_operations","description":"分页读取操作记录","x-required-scope":"manage:read","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_operations"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cursor":{"type":"string","pattern":"^[0-9]+$"},"limit":{"default":30,"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"list_connections","description":"列出独立管理连接","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"list_connections"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"revoke_connection","description":"撤销指定管理连接","x-required-scope":"manage:accounts","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"revoke_connection"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"connectionId":{"type":"string","minLength":1,"maxLength":256}},"required":["connectionId"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"begin_upload","description":"创建游戏或封面上传会话","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"begin_upload"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"gameId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedDraftRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","enum":["game","cover"]},"entry":{"type":"string","minLength":1,"maxLength":500}},"required":["gameId","expectedDraftRevision","kind","entry"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"get_upload","description":"读取上传状态","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input"],"properties":{"action":{"const":"get_upload"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"uploadId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["uploadId"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},{"type":"object","title":"finish_upload","description":"校验上传并关联工作稿","x-required-scope":"manage:draft","x-primary-web-session-only":false,"required":["action","input","requestId","idempotencyKey"],"properties":{"action":{"const":"finish_upload"},"input":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"uploadId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["uploadId"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}}]}}}},"responses":{"200":{"description":"只读时为动作数据本身；写入时为结果信封。各动作 data 的结构见接入说明。","content":{"application/json":{"schema":{}}}},"400":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"401":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"403":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"404":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"409":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"413":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"503":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}}}}},"/api/v1/manage/uploads/{uploadId}":{"put":{"operationId":"uploadFile","summary":"向上传会话传输一个文件","security":[{"managementBearer":[]}],"description":"需要 manage:draft；先 begin_upload，逐文件 PUT，最后 finish_upload。每个文件最多 64 MiB，封面最多 500 KB。","parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"path","in":"query","required":true,"description":"包内相对路径，使用 URL 编码；拒绝路径穿越与符号链接。","schema":{"type":"string"}},{"name":"X-Youxi-Digest","in":"header","required":true,"description":"文件内容的 SHA-256 小写十六进制摘要","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"文件已保存，或相同路径和摘要已存在"},"400":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"401":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"403":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"409":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"413":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}},"503":{"description":"失败；根据 code 处理，修订冲突时重新读取。","content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}}}}}}}}}