games-development-ai/contracts/agent-loop/source-project.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://wanxiang.ai/contracts/agent-loop/source-project.schema.json",
  "title": "SourceProject",
  "description": "游戏源源项目工件:agents 在固定架构上填的唯一结构化产物;改源不改打包产物(GamePackage 产物 schema 不变)。【schemaVersion 2.0=A-model 多文件代码工件(固定 plumbing + LLM 写的表达性多文件 src/)】。注:1.0 gamedef 声明式表示已随 gamedef 错误路线于 2026-06-21 删除,本 schema 现仅 A-model(2.0)。本 schema 限 Tier0/1 线;tier2 真 Phaser 引擎工程的源项目契约另立一份独立 schema(tier2-source-project.schema.json)、不复用本路。两开发线交汇的 keystone 契约(后端线产出/落库,引擎线消费)。",
  "type": "object",
  "required": ["schemaVersion"],
  "oneOf": [
    { "$ref": "#/$defs/sourceProjectV2" }
  ],
  "$defs": {
    "sourceProjectV2": {
      "type": "object",
      "description": "2.0 A-model:多文件代码工件。固定零表达性 plumbing(entry/main/index) + LLM 写的表达性多文件 src/(core/render/game/host-config/balance/assets)。逃离 gamedef 的 JSON 框死——一切玩法/渲染/数值/wiring 都是真 JS。",
      "required": ["schemaVersion", "sourceHash", "profile", "files", "entry", "globalName"],
      "additionalProperties": false,
      "properties": {
        "schemaVersion": { "const": "2.0", "description": "A-model 源工件契约版本" },
        "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "源(规范化 files)sha256(可寻址/幂等键)" },
        "buildInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "sha256(sourceHash + buildProfile);确定性构建缓存命中键" },
        "profile": { "$ref": "#/$defs/profile" },
        "files": {
          "type": "object",
          "description": "多文件源:相对路径(相对 game 根)→ 文件文本内容。含 LLM 写的表达性代码(src/{core,render,game,host-config,balance,assets}.js)+ 固定 plumbing(entry.js/src/main.js/index.html)。",
          "minProperties": 1,
          "propertyNames": { "pattern": "^[A-Za-z0-9_./-]+$" },
          "additionalProperties": { "type": "string" }
        },
        "entry": { "type": "string", "minLength": 1, "description": "esbuild 入口文件相对路径(如 entry.js)" },
        "globalName": { "const": "__GameBundle", "description": "iife 全局名:对齐 SAA 九门契约(index 调 __GameBundle.bootGameHost)" },
        "plugins": { "type": "array", "items": { "type": "string" }, "description": "本款用到的插件键名(host-config 注入;诊断/审计用)" },
        "assets": { "type": "array", "items": { "$ref": "#/$defs/assetSpec" }, "description": "六类资产规格/引用(design assetSpec → asset 节点;A-model 同用此枚举)" },
        "config": { "type": "object", "description": "平衡参数(数值/难度/速度)——确定性 modify 改这里免 LLM" }
      }
    },
    "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 质量门(替九门)" }
      }
    },
    "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 可插拔" }
      }
    }
  }
}