feat(contracts): 冻结 keystone 契约 source-project.schema.json + 收口 execution 待解
- 新增 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>
This commit is contained in:
zizi
parent
133182d803
commit
2751d98724
104
contracts/agent-loop/source-project.schema.json
Normal file
104
contracts/agent-loop/source-project.schema.json
Normal file
@ -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 可插拔" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -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**"。两者矛盾。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user