From 2751d98724eb831b45047bb5ac71b16c19844322 Mon Sep 17 00:00:00 2001
From: zizi <ChocoBunrpd@catlover.com>
Date: Wed, 17 Jun 2026 12:37:45 +0000
Subject: [PATCH] =?UTF-8?q?feat(contracts):=20=E5=86=BB=E7=BB=93=20keyston?=
 =?UTF-8?q?e=20=E5=A5=91=E7=BA=A6=20source-project.schema.json=20+=20?=
 =?UTF-8?q?=E6=94=B6=E5=8F=A3=20execution=20=E5=BE=85=E8=A7=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 contracts/agent-loop/source-project.schema.json:游戏源项目工件 schema(两开发线交汇 keystone)——轻量声明式领域模型(entity/component/behavior/scene/rule)+ profile 三维(tick/input/progress)+ 六类 assetSpec + config;改源不改打包产物;draft-07 valid JSON。后端线产出/落库、引擎线 2D 适配器消费。
- 收口 execution §12 全部待解(创始人 2026-06-17「按推荐」):①源项目表=studio 模块 ②后端 RuntimeBuild 仅落包(构建留 worker/SAA build.mjs) ③缓存/classify spike 已绿 ④classify→archetype 映射表=引导非校验 ⑤narrative needsRepair=true 等价一次九门失败计入 failCount ⑥studio create=draft+generate 一步式封装。
- 校正:V18 SQL 入 game-cloud 模块迁移(后端线实现),非 stale 的 contracts/db-schemas(契约副本约定已停于 V9)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../agent-loop/source-project.schema.json     | 104 ++++++++++++++++++
 ...定游戏架构与SAA-agentic-studio-execution.md |   4 +-
 2 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 contracts/agent-loop/source-project.schema.json

diff --git a/contracts/agent-loop/source-project.schema.json b/contracts/agent-loop/source-project.schema.json
new file mode 100644
index 00000000..e301c234
--- /dev/null
+++ b/contracts/agent-loop/source-project.schema.json
@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://wanxiang.ai/contracts/agent-loop/source-project.schema.json",
+  "title": "SourceProject",
+  "description": "游戏源项目工件:cheap agents 在固定架构上填的唯一结构化产物;改源不改打包产物(GamePackage 产物 schema 不变);Opus 设计、长期版本化升级。两开发线交汇的 keystone 契约(后端线产出/落库,引擎线 2D 适配器消费)。详见 docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md §5.1。",
+  "type": "object",
+  "required": ["schemaVersion", "sourceHash", "profile", "gameDefinition"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "1.0", "description": "源项目契约版本(独立于 GamePackage 版本)" },
+    "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "源 JSON 规范化后 sha256(可寻址/幂等键)" },
+    "buildInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "sha256(sourceHash + buildProfile);确定性构建缓存命中键" },
+    "profile": {
+      "type": "object",
+      "description": "维度无关三维(否则剧情/TRPG 类绷断,见 execution §10.2/§5.9)",
+      "required": ["tickModel", "inputModel", "progressModel"],
+      "additionalProperties": false,
+      "properties": {
+        "tickModel": { "enum": ["realtime", "turn-based", "event"], "description": "时间模型:决定适配器是否挂 update 循环" },
+        "inputModel": { "enum": ["continuous", "discrete-choice", "text-command"] },
+        "progressModel": { "enum": ["metric", "narrative"], "description": "narrative → 走 narrative-designer-reviewer 质量门(替九门)" }
+      }
+    },
+    "gameDefinition": {
+      "type": "object",
+      "description": "轻量声明式领域模型(非 AAA ECS:无 system 调度器/无 archetype 存储/无 query DSL)",
+      "required": ["entities", "scenes", "rules"],
+      "additionalProperties": false,
+      "properties": {
+        "entities": { "type": "array", "items": { "$ref": "#/$defs/entity" } },
+        "components": { "type": "array", "items": { "$ref": "#/$defs/component" }, "description": "组件定义(声明式属性:渲染/碰撞/物理)" },
+        "behaviors": { "type": "array", "items": { "$ref": "#/$defs/behavior" }, "description": "行为模块(逻辑,维度无关,读参数操作实体;真逻辑代码由核心代码 agent 产出经构建编译进 __GameBundle)" },
+        "scenes": { "type": "array", "items": { "$ref": "#/$defs/scene" }, "description": "关卡构成(数据驱动)" },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" }, "description": "胜负条件(数据驱动)" }
+      }
+    },
+    "assets": { "type": "array", "items": { "$ref": "#/$defs/assetSpec" }, "description": "六类资产规格/引用(asset 节点写入)" },
+    "config": { "type": "object", "description": "平衡参数(数值/难度/速度)——数据驱动,确定性 modify 改这里免 LLM" }
+  },
+  "$defs": {
+    "entity": {
+      "type": "object",
+      "description": "实体:transform(2D 用 xy/z=0,3D 用 xyz,同字段两维成立)+ 组件引用",
+      "required": ["id", "transform"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "transform": {
+          "type": "object",
+          "required": ["position"],
+          "additionalProperties": false,
+          "properties": {
+            "position": {
+              "type": "object",
+              "required": ["x", "y"],
+              "additionalProperties": false,
+              "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number", "default": 0 } }
+            },
+            "rotation": { "type": "number" },
+            "scale": { "type": "number", "default": 1 }
+          }
+        },
+        "components": { "type": "array", "items": { "type": "string" }, "description": "引用 components[].id" }
+      }
+    },
+    "component": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "additionalProperties": true,
+      "properties": { "id": { "type": "string" }, "kind": { "enum": ["render", "collision", "physics", "custom"] } }
+    },
+    "behavior": {
+      "type": "object",
+      "required": ["id", "trigger"],
+      "additionalProperties": true,
+      "properties": { "id": { "type": "string" }, "trigger": { "enum": ["init", "update", "input", "collision", "timer"] } }
+    },
+    "scene": {
+      "type": "object",
+      "required": ["id", "entityRefs"],
+      "additionalProperties": true,
+      "properties": { "id": { "type": "string" }, "entityRefs": { "type": "array", "items": { "type": "string" } } }
+    },
+    "rule": {
+      "type": "object",
+      "required": ["id", "condition", "outcome"],
+      "additionalProperties": true,
+      "properties": { "id": { "type": "string" }, "condition": { "type": "string" }, "outcome": { "enum": ["win", "lose", "score", "advance"] } }
+    },
+    "assetSpec": {
+      "type": "object",
+      "description": "六类资产规格/引用(对齐 v2 review C5;四处同引同一枚举)",
+      "required": ["id", "category", "ref"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "category": { "enum": ["sprite", "character", "effect", "scene", "ui", "music"], "description": "六类:图元/角色/特效/场景/界面/音乐" },
+        "ref": { "type": "string", "description": "平台 assetId/ref 为主" },
+        "url": { "type": "string", "format": "uri", "description": "只读镜像 URL" },
+        "provider": { "type": "string", "default": "mmx-cli", "description": "provider 可插拔" }
+      }
+    }
+  }
+}
diff --git a/docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md b/docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md
index ca1cb9ea..573084b9 100644
--- a/docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md
+++ b/docs/agent-specs/2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md
@@ -15,7 +15,7 @@
 2. **8 契约**(本档 §5 逐个给字段级 schema/签名):①源项目 schema ②源项目 DB(独立 `game_source_project` 表)③GamePackage 源/产物分离 ④SAA state key 全表 ⑤asset 产消 ⑥modifyPatch ⑦唯一确定性构建 API ⑧trace+cost 字段。
 3. **拓扑**(§6):现 11 节点 SAA 图 → 演进为 **render·classify(新)·design·scaffold·logic/repair(一个核心代码 agent 两面)·config/balance·asset(新)·build·QA(九门)·modify(新)** + 条件激活 **narrative-designer-reviewer** + 离线 **skill-curator**(MVP 只做 Debug Skill);救场阶梯 = cheap→连续 5 次九门失败→升档(stage1→stage2)→再 3 次失败→放弃,`recursionLimit` 按 5+3 重算。
 4. **两线切分**(§8):**后端线**(6c6g 编辑 / mini-desktop 构建)锁源项目 schema+DB、SAA state/拓扑/救场路由、studio 编排、trace+cost、modifyPatch;**引擎+前端线**(Mac)锁 2D 适配器(游戏定义→LittleJS)、asset 产消、唯一构建实现、九门 QA、前端创作/修改/预览 UI。交汇=本档 8 契约。
-5. **开工前待解**(§12):①源项目存储归属(倾向 studio 模块,待拍)②构建权威=worker/SAA 共调 `build.mjs`(已天然统一)+ 后端 RuntimeBuild 只落包(待确认本期范围)③**缓存透传 ✅ spike 已证绿(76-93%)、classify ✅ 已绿(tickModel 100%/archetype 93%)——两 spike 均解除**④classify→archetype 映射表语义=引导非校验(待确认)⑤narrative 失败计入 failCount 口径(待确认)。
+5. **开工前待解 → ✅ 全部收口**(创始人 2026-06-17「按推荐」):①源项目表归属=**studio 模块** ②后端 RuntimeBuild **只落包**(构建留 worker/SAA build.mjs)③缓存透传 ✅ spike 绿(76-93%)+ classify ✅ 绿(tickModel 100%)④classify→archetype 映射表=**引导非校验** ⑤narrative `needsRepair=true` **等价一次九门失败计入 failCount** ⑥studio `create`=**draft+generate 一步式封装**。**契约冻结进行中**:keystone `source-project.schema.json` 已落;V18/ALL_KEYS/trace = 后端线 module 实现(V18 入 game-cloud 模块迁移,非 stale 的 contracts/db-schemas)。
 
 ---
 
@@ -635,6 +635,8 @@ graph LR
 ## 12. 开工前待解(诚实列出 · 现行代码与设计未解冲突)
 
 > 以下是我判断**现行代码/文档与本设计存在未解冲突或需创始人/两线收口的点**,不糊过去。开工门(§7.0)须逐条收口。
+>
+> **✅ 全部待解经创始人 2026-06-17「按推荐」确认收口**(本节转为已收口记录):① 源项目表归属 = **studio 模块**(create/modify 编排入口在此;project 仍管 game_version 产物权威)· ② 后端 `RuntimeBuildServiceImpl` 本期**只接"落包"**,不自驱 esbuild(构建留 worker/SAA `build.mjs`)· ③ 缓存透传 **✅ spike 已证绿**(76-93%)· ④ classify→archetype 映射表语义 = **引导(品类预设)非校验**(对齐"玩法模板未废、游戏模板已废")· ⑤ narrative 失败 = **`needsRepair=true` 等价一次九门失败计入 `failCount`**(reviewer 自身抖动也计,防卡死)· ⑥ studio `create` = **`draft+generate` 一步式封装(additive,不破现两步路)**。**契约冻结进行中**:keystone `contracts/agent-loop/source-project.schema.json` 已落;V18 SQL + ALL_KEYS 扩 + trace 扩 = 后端线 module 实现(V18 入 game-cloud 模块迁移,**非 stale 的 `contracts/db-schemas/`〔已停于 V9〕**)。
 
 ### ① 源项目存储权威归属(DB review 与架构 review 口径冲突)
 - **冲突**:v2 生命周期 review §5 说"`game_version` 内容从打包产物**升级为源项目工件+构建产物双存**";架构 review §10 + 本档定"**独立 `game_source_project` 表,勿塞 game_version**"。两者矛盾。