Genarrative/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md

AI 游戏创作项目开发工作台 PRD

更新时间：2026-07-20

1. 产品定位

项目开发工作台是 AI 游戏创作独立客户端中承接“做游戏”后的唯一项目级工作区，不是单独的新页面，也不新建第二套项目、资产、Agent 或预览系统。

工作台固定由四个区域组成：

1. 左侧平台导航。
2. 中央主视窗。
3. 右侧 Project Supervisor 对话与确认区。
4. 底部专业 Agent 状态栏。

中央主视窗在“资源管理”和“运行测试”之间切换。正式预览始终在客户端当前窗口内展开，只允许载入当前项目启动的 127.0.0.1:<port> 本地 HTTP 预览，不调用系统外部浏览器。

2. 创作工具平台接入声明

• 工作台模式：对话式 Project Supervisor 项目工作台，属于 Agent 原生创作例外。
• 例外原因：该工作台负责跨策划、美术、程序、数值、音频和发布专业组的持续协作，结构化表单不能覆盖多轮项目开发与确认恢复。
• 复用边界：图片、音频、上传、素材库、画板和外部生成继续复用现有平台能力，不在工作台内新建平行资产系统。
• 创作链路：做游戏入口 -> 本地项目工作台 -> 资源/运行迭代 -> 导出或后续发布链路。
• 业务真相：项目 manifest、Agent Runtime、持久对话、本地预览状态和后端计费投影；前端只保存短生命周期展示态。
• 当前切片不新增玩法 playId、公开作品 read model、发布路由或 SpacetimeDB schema。

3. 已确认产品决策

3.1 预览与窗口

• 游戏预览直接在当前客户端窗口内展开。
• 客户端仅交付横屏，默认与最小窗口均为 1280×800。
• 右侧 Supervisor 和底部 Agent 状态栏常驻；窗口不得缩小到破坏该结构。
• 浏览器窄屏样式只作为开发兼容，不属于本版本产品合同。

3.2 版本与资源替换

• 可运行版本不可变。
• 替换版本引用资源时创建下一迭代版本，不原地修改既有版本。
• 新版本必须记录 parentVersionId、替换前后资源身份和创建原因。
• 当前运行中的版本不消费尚未生成的新版本变更。

3.3 资源布局

• “按依赖”和“按类型”分别保存画布位置。
• 切换布局模式后恢复该模式最后一次用户手动拖动结果。
• 新资源首次进入某个布局时才执行默认不重叠排版；已有坐标不得被自动排序覆盖。
• 依赖布局使用资源生成/引用关系；类型布局按资源大类、子类型、尺寸规格排序。
• 不同资源分区不可互相拖入。

3.4 数值微调

• 数值修改立即写入当前项目的编辑态配置。
• 当前已拉起的体验预览和测试切片不热更新；必须重新拉起后才能消费新值。
• 自然语言新增数值项只能映射到预定义参数注册表，不允许生成或修改代码。

3.5 专业 Agent

现有六个专业组为：

group	普通用户名称	当前职责
design	策划组	玩法规格、界面原型、规则与验收口径
art	美术组	角色、场景、UI、动画和美术素材
code	程序组	可运行原型、模块实现和工程验证
balance	数值组	速度、生命、得分和难度参数
audio	音频组	背景音乐、音效和音频资源
publishing	发布组	质量评审、试玩、打包和发布准备

• 底栏默认突出策划、美术、程序三组。
• 允许在同一底栏展开数值、音频、发布组，不删除既有专业组。
• 状态、当前任务和完成进度来自真实 manifest/Runtime。
• 泥点消耗必须来自后端计费归因投影；无数据时显示“未统计”，不得用前端估算。

3.6 审批与扩展能力

• 默认档位为严格审批。
• P0 只有严格审批是有效运行合同。
• 高风险审批依赖未确定的 Rank 算法，作为低优先级待解决事项。
• 无需审批只有在 Runtime、计费、副作用、sandbox 和 reconciliation 均支持对应策略后才能开放。
• 未开放选项使用“视觉不可用但可点击说明原因”，不使用无法触发说明的原生 disabled。
• 普通用户暂不开放 Agent.md 编辑和自定义 Skill 安装；后续必须先定义来源审核、版本、权限、沙箱和回滚合同。

4. 工作台状态机

4.1 主视窗

resources
  -> run（存在 runnableVersion 且 loopback preview 可启动）

run.playing
  -> run.paused（用户暂停或切片结束）
  -> resources（先暂停当前预览表现，再切换视图）

run.paused
  -> run.playing（继续当前切片）
  -> run.relaunching（数值或版本编辑态发生变化）
  -> resources

运行入口不可用时仍允许点击，显示“当前无可运行版本”，但不切换状态。

4.2 测试切片

idle -> starting -> playing -> paused -> completed
                     |          |
                     +-> failed +-> playing

completed -> starting(nextSlice)

• 单个切片完成后自动进入 paused。
• 上一项/下一项会停止当前切片并启动目标切片。
• 数值编辑态变化后，当前切片标记 stale；重新拉起前不消费新值。

4.3 资源聚焦

idle -> focused(document|art|audio|version) -> idle

• 文档：在中央画布展开并独立滚动。
• 美术/音频：进入对应媒体聚焦状态，工具能力复用现有编辑器。
• 版本：高亮版本引用资源；替换动作只创建下一迭代版本。

4.4 历史成果与当前状态

• “当前工作状态”只展示当前 Supervisor run 下的专业 Runtime。
• “项目已有成果”按项目持久保存，不随 Supervisor run 切换而清空。
• Agent 文本成果只认可带合法 agent-finalization-<32 lower hex> messageId 的 assistant 消息。
• 新 run 失败、待确认或未完成时继续展示最近一次成功成果；新的成功 finalization 才替换同 Agent 的旧成果。
• 文本回执不得冒充图片、音频、项目文件或 manifest asset。

5. 数据合同

以下合同先冻结字段语义；P0 只实现标注为 P0 的部分。

5.1 工作台视图状态（P0）

type ProjectWorkbenchViewState = {
  schemaVersion: 'game-creator-workbench-view.v1';
  projectId: string;
  mode: 'resources' | 'run';
  approvalMode: 'strict' | 'risk' | 'none';
  expandedAgentGroups: Array<'balance' | 'audio' | 'publishing'>;
};

P0 中 approvalMode 只能有效写入 strict；其它值只能作为不可用选项展示。

5.2 资源画布布局（P1）

type ProjectResourceCanvasLayout = {
  schemaVersion: 'game-creator-resource-layout.v1';
  projectId: string;
  mode: 'dependency' | 'type';
  revision: number;
  positions: Array<{
    resourceId: string;
    section: 'document' | 'version' | 'art' | 'audio';
    x: number;
    y: number;
    manuallyPlaced: boolean;
  }>;
  updatedAt: number;
};

两个 mode 是两份独立坐标集合；服务端或本地项目持久层以 projectId + mode 做 CAS 更新。

5.3 资源类型与替换兼容性（P1）

type ProjectResourceDescriptor = {
  resourceId: string;
  category: 'document' | 'version' | 'art' | 'audio';
  subtype: string;
  width?: number;
  height?: number;
  durationMs?: number;
  format: string;
};

type ProjectVersionResourceReplacement = {
  sourceVersionId: string;
  sourceResourceId: string;
  replacementResourceId: string;
  compatibility: {
    categoryEqual: boolean;
    subtypeEqual: boolean;
    sizeSpecEqual: boolean;
  };
};

三项兼容性必须同时为 true 才能创建下一版本。

5.4 游戏迭代版本（P1）

type GameIterationVersion = {
  versionId: string;
  parentVersionId: string | null;
  projectRevision: number;
  resourceBindings: Array<{ slotId: string; resourceId: string }>;
  parameterSnapshotId: string;
  createdReason: 'initial' | 'resource-replacement' | 'agent-revision';
  createdAt: number;
};

版本写入后不可修改。

5.5 测试切片与数值参数（P2）

type GameTestSlice = {
  sliceId: string;
  versionId: string;
  title: string;
  order: number;
  startCondition: string;
  endCondition: string;
  status: 'idle' | 'starting' | 'playing' | 'paused' | 'completed' | 'failed';
};

type GameTunableParameterDefinition = {
  parameterId: string;
  label: string;
  valueType: 'integer' | 'number' | 'boolean' | 'enum';
  min?: number;
  max?: number;
  step?: number;
  enumValues?: string[];
  writePath: string;
  codeMutationAllowed: false;
};

参数写入立即增加编辑态 revision；当前 preview/slice 保持旧 revision，并显示“需要重新拉起”。

5.6 Agent 泥点归因（P2）

type ProjectAgentMudPointAttribution = {
  projectId: string;
  agentGroup: 'design' | 'art' | 'code' | 'balance' | 'audio' | 'publishing';
  chargedMudPoints: number;
  refundedMudPoints: number;
  netMudPoints: number;
  asOf: number;
};

该投影只能由后端账本聚合产生。

6. 分阶段范围

P0：当前实施切片

• 复用现有四区工作台壳。
• 资源/运行切换与客户端内 loopback 预览。
• 只读资源画布、文档展开、美术/音频聚焦入口。
• Supervisor 正式会话、上传、Runtime 确认与安全错误。
• 当前 run 专业状态与项目历史成果分离。
• 默认三专业组，并可展开另外三组。
• 严格审批有效；风险/无需审批可点击查看未开放原因。
• 橙色低保真视觉与 1280×800 横屏边界。

P1

• 依赖/类型两套坐标持久化。
• 资源关系线与首次自动布局。
• 版本资源高亮、兼容性判断和不可变下一迭代版本。
• 美术/音频编辑状态接线。

P2

• 测试切片正式协议与恢复。
• 参数注册表、立即写编辑态和预览重新拉起。
• 泥点归因 read model。
• Agent.md/Skill 安全合同。
• 高风险审批 Rank 与无需审批运行合同。

7. P0 验收

1. 1280×800 下页面无横向或纵向溢出，输入框与 Agent Dock 始终可见。
2. 运行入口不可用时点击给出原因；可用时只在客户端内打开 loopback 预览。
3. 当前 Supervisor run 变化后，旧成功 Agent 文本成果仍可查看；普通失败 assistant 不进入资源区。
4. 底栏默认显示策划、美术、程序，可展开数值、音频、发布；状态与任务来自真实 Runtime/manifest。
5. 风险审批和无需审批不能改变运行策略，点击后明确提示尚未开放；严格审批继续使用现有 Runtime 门禁。
6. 不显示伪造泥点、伪造资源完成度、伪造图片或外部浏览器成功提示。

8. 非目标

• 本切片不实现 P1/P2 持久合同。
• 不修改 SpacetimeDB schema。
• 不开放普通用户 Agent.md/Skill。
• 不自动确认 Agent 动作，不自动触发可能扣费的生成。
• 不把当前项目工作台推广为其它玩法的默认创作模式。