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>

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: