~LiuDehao
← Back · Projects

Game Designer

2026

运行在单机上的游戏设计 Agent 工作台：Supervisor + 领域专家多智能体，完成游戏全流程设计（不含代码开发）。

PythonFastAPILangGraphMulti-Agent

源码 liudeihao/game-designer

Repo

Game Designer

面向游戏设计文档的 Agent 工作台（附 React 前端）。

Game Designer 工作台截图

项目关注真实 Agent 产品里常见的工程问题：单一主 Agent 与领域能力如何协作、结构化工作区如何作为事实来源、局部写入与并发、长任务过程如何可观测，以及人机协作点如何显式中断与恢复。工作区对象是游戏设计文档（GDD），不覆盖引擎或程序实现。

当前形态：

  • 单机 C/S：FastAPI 后端 + React 前端
  • 主 Agent（Studio）对接用户，领域能力作为可派发子 Agent / 工具
  • GDD 以多文件对象存储；对话状态与设计资产分离持久化
  • OpenAI 兼容模型接口（需自行配置）

Why

设计工作不是单轮补全。上下文会跨愿景、机制、数值、内容与资产持续累积；若把一切压进一次长对话或一份巨型文档，会出现上下文污染、整文件覆盖、过程不可见、以及过早生图带来的返工成本。

本项目把「对话 Agent」与「设计工作区」拆开：

  • Studio 在单一 agent loop 中理解意图、派发能力、向用户总结
  • 领域能力 安静写入结构化对象，过程以工具树呈现
  • GDD 文件 是项目级事实；会话 checkpoint 只服务对话恢复
  • 聊天引用 把本轮变更文件挂到回复上，可点开对照工作区

目标不是堆叠更多 Agent 角色，而是建立清晰的写边界与可恢复的执行路径：能局部改的不强行整份重写，需要人确认的才 interrupt，其余保持用户驱动。

Architecture

同步请求路径与工作区落盘分开：

                 Browser
                    |
              Vite / React
                    |
                 /api (SSE + REST)
                    |
                 FastAPI
            +-------+-------+
            |               |
         LangGraph      Persistence
      Studio ↔ experts   +----------+----------+
                         |          |          |
                    registry   checkpoints    gdd/
                    (SQLite)    (SQLite)    (多文件 JSON)
  • 对话线程：thread_id = conversation_id，interrupt 可 resume
  • 设计资产：projects/{id}/gdd/**/*.json，读时组装、写时按对象 patch
  • 回合结束：对回合起点做 diff，只持久化本轮变更对象

Key Design

Orchestrator + Capability Router + Subagent

用户只与 Studio（Orchestrator） 对话。Studio 从 Capability（产品/路由单元）目录中选择要派发的能力 id；Capability Router（app/routing/）将 Capability 解析为对应的 Subagent（领域 Agent 包）。

Studio 以单一增长式 agent loop运行：领域能力作为进程内 handoff 工具挂在同一轮工具轨迹上，观察结果留在共享消息历史（Codex 风格），同一轮可继续读工作区、再次 handoff，或以人话回复。澄清 / 规划 / 决策通过 propose_* 工具 interrupt，恢复后观察写回 loop，而不是无历史地重写对外回复。Subagent 不直接对用户寒暄。

每个 Subagent（app/subagents/<id>/）拥有：

  • Skills（skills/<id>/SKILL.md 或 shared/skills/）— 领域知识与流程
  • Tools — 在 subagent.json 声明，由 app/infrastructure/tools/ 执行（本地模拟 + MCP）
  • Capabilities[] — 可派发单元，含产出/依赖/质量规则/反思配置

Studio / Plan 位于 app/studio/、app/plan/，不在 subagents 包内。

多文件 GDD 工作区

一个设计对象对应一个文件（如 vision.json、mechanics/{id}.json）。API / Agent 使用组装后的整份视图；磁盘写入走 write_patch，list 字段不删除未出现在 patch 中的兄弟项。

并发语义为 按对象 last-write-wins（对齐编辑器按文件覆盖的直觉）。GameGDD.version 是展示计数，不是分布式锁；跨对象无事务。

人机协作（HITL）

保留的 interrupt：澄清提问、设计决策提案（propose_decision）、Plan 模式建议（propose_plan）。
已移除：资产审批门、启发式 GDD「完成度」进度条与强制阶段评审——它们不构成有效安全边界，却增加打断与假进度。项目列表改用用户可编辑的状态标签（预设：构思 / 进行中 / Done，亦可自定义）。

资产生成由用户在实体化界面主动触发；占位符描述可先登记，再按需出图（当前为 mock，真实生图接口可替换）。

流式可观测与工作区引用

LangGraph updates / custom 映射为 SSE。Studio handoff 为父 trace 卡，Capability / Tool 步骤挂子树，前端折叠进消息；最终回复流式输出时过滤工具调用泄漏。回合落盘的工作区变更会以 file_refs 挂在 AI 消息上，聊天中渲染可点击文件引用并打开对应设计视图（内联 DocSource，不再依赖独立 Source / Worklog 侧栏）。

代价：流式、interrupt 与落盘边界耦合，缺事件时前端需做配对兜底。

对话记忆（通用压缩）

app/memory/ 提供预算感知的上下文压缩：默认保留完整工具与对话历史，接近模型窗口时才把较早轮次收成 conversation_summary。与单一 agent loop 配套——不按回合清空 transcript。Studio / Plan 共用算法，可通过 purpose 做摘要侧重点特化；Subagent 读取共享摘要，不各自硬切窗口。用量侧区分 provider 回报与本地估算，并拆分 input 构成（设置 / Analytics 可见）。

Capability Catalog

backend/app/subagents/<id>/ 按领域 Subagent 打包：subagent.json（含 capabilities[]、skills、tools）+ skills/ + node.py；共享 Skill 在 subagents/shared/skills/。Capability Router 在 app/routing/；模型、MCP 与 Tool 适配器位于 app/infrastructure/。

数值模拟与 MCP

平衡模拟使用固定 numpy kernel 与固定 seed，禁止执行模型生成代码。外部 MCP 可选加载，失败时降级为空工具集，不阻塞主路径。

Tech Stack

后端： Python 3.11+、FastAPI、LangGraph、LangChain（OpenAI 兼容）、SQLite

前端： React、Vite、TypeScript

Getting Started

Backend

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m app.main          # http://127.0.0.1:8000

Frontend

cd frontend
npm install
npm run dev                 # http://127.0.0.1:5173

Tests

cd backend && pytest -q

未配置模型时无法调用 LLM。请在工作台「设置」中完成厂商与模型配置。

Layout

backend/app/graph/           图编排（build / gates / suggest）
backend/app/routing/         Capability Router（Orchestrator 选 Capability → Subagent）
backend/app/studio/          Orchestrator（含 prompts）
backend/app/plan/            Plan 模式（含 prompts）
backend/app/subagents/       领域 Subagent 包（Skills / Tools / Capabilities / prompts）
backend/app/infrastructure/  LLM / MCP / Tool 外部运行时适配
backend/app/persistence/     项目 registry 与多文件 GDD
backend/app/assets/          占位符实体化
frontend/src/                工作台 UI（execution trace）