games-development-ai/AGENTS.md

AGENTS.md — 绘境AI Project · Agent 入口

本项目以 AI 驱动开发的方式构建。 无论你是 AI agent 还是人类工程师,每项任务都从这里开始。 本文件是项目入口的 single source of truth:回答"这个项目是什么"与"在它里面怎么干活"。CLAUDE.md 只是通过 @AGENTS.md 导入本文件。 设计文档的权威索引 = docs/architecture/README.md(总索引 + SoT 注册表);本文件只给指针,不重复清单。

---

1. 项目定位

绘境AI = 一个 AI 驱动、面向大众市场的游戏创作与变现平台。

• 零技能用户可以从一句话构建出一款可上线、可变现的轻量小游戏;
• 玩家在类短视频的"游戏 feed"里发现游戏并即点即玩;
• 平台通过三条线变现:广告分成 / 订阅会员 / B 端定制。

差异化护城河 = 生成 + 流量 + 变现的全闭环。真正的护城河不是生成引擎(大模型迟早追上),而是四层:数据、网络效应、资产、合规。

2. 项目目标(MVP 阶段)

MVP 目标:交付一条种子用户可试用的全链路闭环 —— create → generate → preview → publish → review → game feed → play → interact → ads → revenue → telemetry → recommendation optimization。

指标	目标
AI 生成成功率	≥ 80%(基于 3–5 个模板)
游戏 feed 首屏加载	P75 < 3s
服务可用性	≥ 99.5%
MVP 基础设施成本	< ¥5,000/月(投资人版 ≈ ¥4,300/月)
P0 产品功能覆盖	55/55 P0 可验证

上线主计划 SoT = docs/mvp/可行性方案16周-波次映射.md(16 周日历闸门为骨架、55 个 P0 为验收定义,canonical)。曾并列的两套旧路线图已降为它之下的视图:MVP execution spec(10 人 × 3 周,产品验收来源)与投资人版(资本效率叙述)。日常排期与上线判定以 16 周主计划为准;本 §1–2 是顶层目标锚点;55 P0 明细见 .agents/knowledge/mvp-scope-and-milestones.md,进度见 docs/mvp/MVP进度总账.md。

3. 项目目录

3.1 三个业务代码库(本 monorepo 子目录,后续拆独立仓)

现行技术口径(决策史与依据一律见 .agents/knowledge/tech-decisions.md,运行时单一真相见 docs/architecture/架构/生成引擎/agentic运行时架构图说.md):

• 游戏生成统一收敛 AgentScope(2026-06-25):按 AI 参与深度分三档(Tier0/1/2),全部高度模板化;产物终态 = src/ 多文件源工程(gameDefinition 已废);各档过分层验收(2026-07-09,裁定见质量模型 SoT 裁定三):九门机械预筛兜「未见明显死」地板;玩法地板便宜档 = 独立模型判定(W-AXIS 落地中)、tier2 = 富三门双路真玩(对位物,是否叠加模型判定随校准另议)。tier2 富游戏档 = AgentScope + Phaser 独立 Python service。
• 引擎按表现复杂度选:轻-中档 LittleJS 增强发行版 / 最高档 Phaser;引擎不是分档轴;Cocos 只留 3D/渠道导出(人在环)。
• SAA / Dify / coze 降为最低优先级远期(适配验证可插拔目标,不在 MVP runtime)。
• Nacos / RocketMQ / Sentinel = MVP 生产 runtime(2026-07-01 反转:Spring Cloud Alibaba 原生三件套,自托管 mini-infra;配置控制面在飞,见 docs/agent-specs/_index.md)。

代码库	角色	技术栈
game-cloud	后端(Huijing Cloud fork + 13 个游戏业务模块)	Java 17 + Spring Cloud Alibaba(Nacos 配置+发现 / RocketMQ 异步 gen 队列 / Sentinel 流控)+ MySQL + Redis + new-api gateway(生成计费/模型接入)
game-admin	管理后台前端(运营/管理员)	Vue3 + Element Plus(huijing-ui-admin-vue3 fork)
game-studio	产品前端(创作者+玩家)	Vue3 + Vant + LittleJS 增强发行版(引擎+能力插件库)+ WanxiangGameSDK;tier2 富游戏档由独立 Python service 生成(Phaser)

命名区分:后端 game-cloud 内部有一个 studio 业务模块(创作流编排,错误码段 112);它与产品前端仓 game-studio 是两回事。

3.2 当前仓(monorepo)目录结构

games-development-ai/
├── AGENTS.md                  # 本文件:项目入口(CLAUDE.md 仅导入它)
├── contracts/                 # 8 类契约(API/DB/SDK/GamePackage/events/ad-slot/prompts…)= 跨端 single source of truth
├── game-cloud/                # 后端(huijing fork + game-module-*)
├── game-admin/                # 管理后台前端
├── game-studio/               # 产品前端
├── deploy/                    # 部署与 smoke-gate 脚本
├── spikes/                    # 仓级 spike 资产(代码类,如 channel-spike)
├── docs/
│   ├── architecture/          # 设计文档 SoT 根:README = 总索引 + SoT 注册表;6 域 4 级人读散文树
│   ├── agent-specs/           # 在飞设计 + _index.md(在飞板);历史一律 git 找
│   ├── plans/ · brainstorms/  # 留痕层(在飞 plan 之外定期清缩)
│   ├── superpowers/specs/     # mvp-execution-spec(16 周主计划的视图)
│   ├── mvp/                   # 活账本:16周主计划 / 进度总账 / 作战清单 / 闸门看板 / 单位经济
│   └── ip/                    # 软著/专利/备案材料(删除红线)
├── docs-design/               # 产品/视觉设计材料
└── .agents/                   # Agent 能力中枢(knowledge/rules/skills/workflows/tools,索引见其 README)

3.3 两层文档与检索

文档分两层(规则细则见 .agents/rules/engineering-conventions.md §10.6):策展层(少而准,读它 = 当前真相:架构 6 域树 + mvp 活账 + .agents/ + 本文件)与留痕层(放开累积,检索不通读:plans / brainstorms / agent-specs 带日期档)。

• 每个概念在策展层只有一份 SoT,登记在 docs/architecture/README.md §2 注册表(frontmatter topic + canonical: true,docs-gate 机器对账);
• 检索入口:注册表(当前真相)→ docs/agent-specs/_index.md(在飞)→ git grep / git show(历史);
• Claude auto-memory(引擎托管、仓外、每会话私有)只是个人加速器;仓库才是权威源,可复用产出必须蒸馏回 .agents/。

3.4 关键模块架构(引用)

13 个后端模块速查(每模块 ≤50 字)= .agents/knowledge/product-and-architecture.md §5,配 §3 分层 / §4 三仓归属 / §6 依赖图 / §8 SDK 分层;更深的子系统设计 → 架构 6 域树。

4. 任何任务开工前的必读顺序

顺序	文档	角色
1	docs/architecture/README.md	设计总索引 + SoT 注册表(唯一入口)
2	docs/superpowers/specs/mvp-execution-spec-design.md	MVP execution spec(55 P0 验收来源,主计划视图)

日常开发默认先读 .agents/knowledge/ 蒸馏版;设计细节进 6 域树按需下钻。

5. .agents/ 目录导航

.agents/ 是项目的"Agent 能力中枢",四类:knowledge(是什么)/ rules(必须怎样)/ skills(怎么做)/ workflows(如何承接任务),另有 tools(门脚本等)。完整清单 = 单一事实源 .agents/README.md;本入口不重复清单。

6. 工作协议(硬约束)

完整流程见 .agents/workflows/ai-development-protocol.md。

1. 先读再动:任何有真实复杂度的任务,先读 .agents/knowledge/ 及相关 docs/,对齐事实再开工。
2. 复杂/高风险工作先评审:跨模块、改用户可见行为、触及外部服务/支付/数据的任务,先产一份功能设计文档(见 .agents/skills/feature-design-doc.md),开工前先查 SoT 注册表并在 frontmatter 申报 sot-impact,评审过再执行。
3. 证据规则:区分"已验证事实/推断/假设";没有验证证据,绝不宣称"完成/修好/通过/无问题";可运行的(测试/构建/lint/smoke)必须跑。
4. 最小改动:只动与需求直接相关的代码,复用既有模式,不顺手重构无关内容。
5. 中文注释:代码带完整简体中文注释;外部交互、核心实现、错误路径必须有可追溯日志。
6. Contract-first:接口/数据结构变更先改契约(contracts/ 与 -api 包)再实现,并通知相关方。
7. 不留孤儿设计:新功能/数据结构/API/领域模型,连同入口、使用路径、失败模式、验收标准一并交付。
8. plan 文档双评审门(2026-06-18,创始人):新建 brainstorm/plan/设计文档,收口前必须过 Codex + Opus 双评审(Codex 不可用则 Opus 单评);把设计前提喂进去,文内修掉发现项。
9. 内网阶段:决策与密钥进项目文档,不进 env var(2026-06-18,创始人):密钥 → docs/内网凭据与端点.md(single source of truth,需要 key 读它、不要再问);决策 → 相应活档,永不只留在聊天里。
10. 文档治理机器门(2026-06-20 立,2026-07-02 落地脚本):规则必须编译成机器门,否则等于没有。门 = .agents/tools/docs-gate.sh 七检——G1 品牌不变量(活层禁退役品牌名;唯一字面量存于门脚本)/ G2 canonical 唯一性 + 注册表对账 / G3 死链 / G4 入口卫生(本文件禁机器 setup、个人路径、硬编码端口)/ G5 留痕隔离(策展层不链非 canonical 留痕)/ G6 设计档申报(topic/status/sot-impact)/ G7 计划谱系(新建 plan/设计档必带 frontmatter 上级: 单指针,沿链可达 canonical SoT;谱系树用 .agents/tools/plan-tree.py 查询)。挂载:pre-commit + Gitea Actions + wave-close 第 8 步;细则与白名单见 engineering-conventions §10.7。门③(doc↔code 兑现断言)规格同见 §10.7,随生成主线 harness 落地。
11. 横切一致性主人 + AGENTS.md 自审(2026-06-20,创始人):跨文档/跨时间的一致性(SoT 收敛、品牌统一、设计↔代码兑现、本文件新鲜度)显式归创始人 + 6c6g 文档/设计线(有状态主体),负责机器门做不出的灰色判断。任何改名/子系统增删/核心决策推翻,同一 commit 必须重审本文件(品牌、死链、canonical 对账、入口卫生——docs-gate 固定扫)。
12. 落档文档 = 资深工程师写的散文(2026-06-21,创始人):流畅人读中文、逻辑连续、必要处配直白图表。禁三样:元叙述("本文讲什么/下面介绍/前面讲过")、AI 造词与黑话堆砌(项目既有术语可用,首次出现讲清)、套话空强调("至关重要/本质上/值得注意的是")。派子代理写文档,必须把本标准连同正反例一起传下去(只传"写散文"不够,输出会退回 AI 味)。
13. 工具输出只是参考,不是事实;最终产物必须真浏览器验收(2026-07-08,创始人):任何工具 / harness 的判定(check.ok / 九门 verdict.pass / smoke / lint / bright、distinctStates 等)一律只作参考、绝不当成事实——它们会假阳也会假阴。2026-07-08 坐实:stripCode 遇字符串内 //(如赛博文案 'JACK IN // FLOOR')误把真代码当注释抹掉,致 check 假阴性误报红线缺失、模型明明写对却被反复拒到熔断烧钱;反向地,九门也放行过秒死 / 存档刷分 / 死锁的坏死游戏(假阳性)。因此:每一个最终产物(生成的游戏 / 页面 / 任何可交付物)必须真实用浏览器打开、亲眼看、亲手玩,以截图为硬证验收——工具判过 ≠ 验收过。产物失败或报错时,根因分析「为什么失败 / 报错」下钻到具体代码 / 数据 / 配置,绝不停在「工具说通过 / 工具说不行」。模型能力类判断(玩法、美术、音乐、好不好玩)本就不进代码校验,只能靠真看真玩 + agent/skill/mcp。

7. 知识累积机制(同样是硬约束)

每完成一项有价值的任务,把可复用产出写回 .agents/:新事实→knowledge/、新红线→rules/、新 playbook→skills/、流程改进→workflows/。新增前先查重(优先更新既有文件);过时立即修正或删除;改动同步 .agents/README.md 索引。全部简体中文、单一主题、可检索。没有蒸馏的任务是一次性消耗。

8. 效率原则(复利)

八条核心策略(详见 .agents/workflows/mvp-execution-orchestration.md):黄金模板先行;contract-first;复用优先于重建(仓内 → 生态现货(build-vs-buy 强制 prior-art)→ 才许自研);验证门前置;并行边界 = 模块边界;.agents 复利蒸馏;缓存昂贵步骤;可复现编排。

9. gstack 工具集(全局 · 仅指针)

gstack 是按开发者机器安装的全局工具(browse/review/QA/deploy/docs),不属于本项目;项目约定仅一条:所有网页浏览/评审/QA 经唯一 /gstack 入口走。

入口卫生规则:本文件只承载项目事实——不放按机器的 setup、安装命令或个人绝对路径(docs-gate G4 强制)。