feat(contracts): studio.yaml 冻结生命周期 API delta /studio/{create,modify,extend}(C3)
两线开工的临门 M0 契约(前↔后交汇)。additive,零改现 draft/generate/task/ regenerate 两步路。对齐已冻 keystone source-project.schema.json + execution §5.6 modifyPatch / §12-⑥。 新增: - 3 端点:create(draft+generate 一步式封装,templateId 缺省 generic)/modify (改源不改产物:deterministic 免LLM | regenerate-module 重生成单 behavior,产 新预览版、不动 currentVersion、走发布审核)/extend(additive 内容扩展)。 - 6 VO:StudioCreateReqVO/StudioModifyReqVO/StudioModifyTarget/StudioModifyPayload/ StudioExtendReqVO/StudioAssetContextItem(六类素材引用,取代旧 attachments)。 - TaskChainRespVO 加 additive baseVersionId(modify/extend 血缘)。 - 头注补生命周期编排说明 + x-feign seam(aigc.submitGenerate 扩 mode/baseVersionId/ modifyPatch/idempotency=后端线落地;project 取 base 源项目引用+新预览版落库)。 校验:YAML 解析绿、14 $ref 零悬空、六类与 keystone 逐字对齐、modifyPatch enum 对齐 §5.6。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
zizi
parent
5f9f9f5b32
commit
d97d0bae5c
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user