diff --git a/contracts/api-schemas/studio.yaml b/contracts/api-schemas/studio.yaml index ca3a2a8f..a19e7922 100644 --- a/contracts/api-schemas/studio.yaml +++ b/contracts/api-schemas/studio.yaml @@ -16,6 +16,19 @@ openapi: 3.0.3 # - aigc-api AigcApi.submitGenerate / getTask / retryTask / getTemplateList（Wave3 新增 seam，纯暴露层委托 AigcTaskService） # attachments（R7）：StudioGenerateReqVO.attachments 本波仅持久化（studio 侧落库），不透传 aigc（aigc reqDTO 无 attachments 字段）；P1 再透传。 # 狠切留 seam 不实现（P1）：rig/对白树/可视化批量；资产图仅槽位表（game_studio_asset）+ 单步调度，不六路并发。 +# --------------------------------------------------------------------------- +# 生命周期编排扩展（契约 C3 | 2026-06-17 固定架构+SAA studio execution §5.6/§12-⑥）： +# 范式：游戏 = 长生命周期源项目（LLM as 工作室）。新增 create/modify/extend 三生命周期操作（additive，不破现 draft/generate/regenerate 两步路）。 +# - POST /create = draft+generate 一步式封装（templateId 缺省 generic，一句话直生免选模板，对齐 generic 桥接 7534bdf9）。 +# - POST /modify = 改源不改打包产物：在 baseVersion 源项目上改一处（换美术/调参/改关卡=确定性免 LLM；改玩法=LLM 重生成单 behavior）→ 重构建出新预览版； +# 不动 currentVersion、不自动入 feed，仍走发布审核（B1 链）；失败=不建新版、base 不动。 +# - POST /extend = additive 内容扩展（加关卡/机制/内容，不重写既有部件）→ 新预览版。 +# 三者均委托 aigc（job 模型 mode/baseVersionId/modifyPatch/idempotency）→ SAA 固定架构图产源项目 → 唯一确定性构建 → handleCallback 唯一写入路径落包； +# 产物均经 taskChain 轮询（复用 /task/{id}），完成后 versionId=新（预览）版。 +# 关联冻结契约：contracts/agent-loop/source-project.schema.json（源项目工件）、modifyPatch（execution §5.6）、六类 assetContext（取代旧 attachments，additive）。 +# x-feign-contracts（新增 seam，studio 为调用方，本契约不对外暴露 Feign）： +# - aigc-api AigcApi.submitGenerate 扩 mode/baseVersionId/modifyPatch/idempotencyKey（生命周期编排参数，additive；后端线落地）。 +# - project-api ProjectApi 取 baseVersion 源项目引用 + 新预览版落库（version 产物权威仍在 project；源项目独立 game_source_project 表存 V18）。 info: title: 造梦AI studio 模块 API version: 1.0.0 @@ -112,6 +125,68 @@ paths: application/json: schema: { $ref: '#/components/schemas/CommonResultStudioTaskChain' } + # --------------------------------------------------------------------------- + # 生命周期操作（契约 C3，execution §5.6/§12-⑥；additive，不破现两步路） + # --------------------------------------------------------------------------- + /app-api/studio/create: + post: + tags: [app-studio] + summary: 一步式创作（C3；draft+generate 封装，P-CRT-01/10） + description: >- + 编排：建草稿（委托 project createProject，templateId 缺省 generic）→ 立即委托 aigc submitGenerate → 落任务链(status=1) + → 返回任务链句柄供前端轮询（复用 /task/{id}）。一步式封装，不破现 draft+generate 两步路（additive）。 + 六类 assetContext 透传生成上下文（取代旧 attachments）。 + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/StudioCreateReqVO' } + responses: + '200': + description: 成功（任务链句柄，含 aigc_task_id） + content: + application/json: + schema: { $ref: '#/components/schemas/CommonResultStudioTaskChain' } + + /app-api/studio/modify: + post: + tags: [app-studio] + summary: 修改（C3；改源不改产物，P-CRT-09 进阶） + description: >- + 编排：取 baseVersion 源项目 → 应用 modifyPatch（mode=deterministic 确定性编辑免 LLM / regenerate-module LLM 只重生成单 behavior） + → 唯一确定性构建出新预览版 → 落任务链供轮询。产物=新预览版（不动 currentVersion、不自动入 feed，仍走发布审核）； + 失败=不建新版、base 不动。modifyPatch 字段见 execution §5.6。 + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/StudioModifyReqVO' } + responses: + '200': + description: 成功（新预览版任务链句柄，完成后 versionId=新预览版、baseVersionId=被改版本） + content: + application/json: + schema: { $ref: '#/components/schemas/CommonResultStudioTaskChain' } + + /app-api/studio/extend: + post: + tags: [app-studio] + summary: 扩展（C3；additive 内容扩展） + description: >- + 编排：在 baseVersion 源项目上做 additive 内容扩展（加关卡/机制/内容）→ 重构建出新预览版 → 落任务链供轮询。 + 语义=additive（不重写既有部件）；产物处置同 modify（新预览版、不动 currentVersion、走发布审核）。 + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/StudioExtendReqVO' } + responses: + '200': + description: 成功（新预览版任务链句柄） + content: + application/json: + schema: { $ref: '#/components/schemas/CommonResultStudioTaskChain' } + components: schemas: # ========== 请求 VO ========== @@ -132,6 +207,64 @@ components: prompt: { type: string, maxLength: 1000, description: '一句话 Prompt（透传 aigc submitGenerate）', example: '做一个躲避陨石的小游戏' } attachments: { type: string, description: '附件上下文 JSON（P-CRT-04）；【本波仅持久化，P1 透传 aigc】——studio 侧落库持久化，本波不透传 aigc' } + # ---- 生命周期操作请求 VO（契约 C3，execution §5.6）---- + StudioCreateReqVO: + type: object + required: [title, prompt] + description: 一步式创作（draft+generate 封装）；templateId 缺省 generic，assetContext 取代旧 attachments + properties: + title: { type: string, maxLength: 128, description: '作品标题（透传 project createProject）', example: '我的放置小镇' } + prompt: { type: string, maxLength: 1000, description: '一句话 Prompt（一步式必填，透传 aigc）', example: '做一个躲避陨石的小游戏' } + templateId: { type: string, description: '玩法模板/品类引导 ID；缺省 generic（一句话直生免选模板，对齐 7534bdf9）', example: 'generic' } + assetContext: { type: array, items: { $ref: '#/components/schemas/StudioAssetContextItem' }, description: '六类素材引用（取代旧 attachments，additive）；空=纯一句话生成' } + idempotencyKey: { type: string, maxLength: 64, description: '幂等键（C3；防重复提交触发重复生成，可空）' } + + StudioModifyReqVO: + type: object + required: [baseVersionId, mode, target] + description: 改源不改产物（execution §5.6 modifyPatch）；产新预览版，不动 currentVersion，走发布审核 + properties: + baseVersionId: { type: integer, format: int64, description: '被改的 base 产物版本 ID（project.game_version.id）', example: 4096 } + mode: { type: string, enum: [deterministic, regenerate-module], description: 'deterministic=确定性编辑源文件免 LLM；regenerate-module=LLM 只重生成单 behavior 模块', example: 'deterministic' } + target: { $ref: '#/components/schemas/StudioModifyTarget' } + payload: { $ref: '#/components/schemas/StudioModifyPayload' } + idempotencyKey: { type: string, maxLength: 64, description: '幂等键（C3，可空）' } + + StudioModifyTarget: + type: object + required: [kind] + description: 寻址源项目部件（path 与 id 二选一） + properties: + kind: { type: string, enum: [asset, config, level, behavior], description: '换美术=asset / 调参=config / 改关卡=level(scene) / 改玩法=behavior' } + path: { type: string, description: '源项目内 JSON 指针（如 /config/speed、/assets/0、/gameDefinition/scenes/2）', example: '/config/speed' } + id: { type: string, description: '或按部件 id 寻址（behaviors[].id / assets[].id）' } + + StudioModifyPayload: + type: object + description: mode=deterministic 用 value（直接覆写免 LLM）；mode=regenerate-module 用 intent（喂 LLM 重生成意图） + properties: + value: { type: object, additionalProperties: true, description: 'deterministic 新值（确定性覆写）' } + intent: { type: string, maxLength: 1000, description: 'regenerate-module 改玩法逻辑的自然语言意图（只重生成那一个 behavior）', example: '把陨石下落改成会左右摇摆' } + + StudioExtendReqVO: + type: object + required: [baseVersionId, intent] + description: additive 内容扩展（加关卡/机制/内容），不重写既有部件 + properties: + baseVersionId: { type: integer, format: int64, description: '在哪个产物版本上扩展', example: 4096 } + intent: { type: string, maxLength: 1000, description: '扩展意图（加关卡/机制/内容）', example: '再加一个 boss 关卡' } + assetContext: { type: array, items: { $ref: '#/components/schemas/StudioAssetContextItem' }, description: '扩展用的新增六类素材引用（可空）' } + idempotencyKey: { type: string, maxLength: 64, description: '幂等键（C3，可空）' } + + StudioAssetContextItem: + type: object + required: [category, ref] + description: 六类素材引用（对齐 source-project.schema.json assetSpec.category；取代旧 attachments） + properties: + category: { type: string, enum: [sprite, character, effect, scene, ui, music], description: '六类：图元/角色/特效/场景/界面/音乐' } + ref: { type: string, description: '平台 assetId/ref（主）', example: 'asset_88231' } + url: { type: string, format: uri, description: '只读镜像 URL（可空）' } + # ========== 响应 VO ========== StudioTemplateRespVO: type: object @@ -164,6 +297,7 @@ components: status: { type: integer, description: '任务链状态：0初始 1生成中 2完成 3失败', example: 1 } progress: { type: integer, description: '进度百分比 0-100（透传 aigc）', example: 60 } retryOf: { type: integer, format: int64, description: '若为重生成，指向原任务链 ID（P-CRT-09 血缘）', example: 1000 } + baseVersionId: { type: integer, format: int64, description: 'modify/extend 血缘：本预览版派生自的 base 版本（create/generate 为空，additive）', example: 4096 } # ========== CommonResult 信封 ========== CommonResultStudioTemplateList: