games-development-ai/AGENTS.md

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

本项目以 AI 驱动开发的方式构建。 无论你是 AI agent 还是人类工程师,每项任务都从这里开始。 本文件是 single source of truth。它既回答 "这个项目是什么"(定位 / 目标 / 目录),也回答 "在它里面怎么干活"(先读什么、去哪里看、要遵守哪些规则、如何把学到的东西反哺回来)。 CLAUDE.md 只是通过 @AGENTS.md 导入本文件;不存在另一份需要同步维护的项目文档。

---

1. 项目定位

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

核心论点:

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

差异化护城河 = 生成 + 流量 + 变现的 "全闭环"。大多数竞品止步于"生成工具";绘境AI 把"能造出来 → 有人玩 → 能赚钱"串成一条链。真正的护城河不是生成引擎(大模型迟早会追上),而是四层:数据、网络效应、资产、合规。

---

2. 项目目标(MVP 阶段)

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

关键量化目标:

指标	目标	出处
AI 生成成功率	≥ 80%(基于 3–5 个模板)	MVP execution spec
游戏 feed 首屏加载	P75 < 3s	MVP execution spec
服务可用性	≥ 99.5%	可用性目标
MVP 基础设施成本	< ¥5,000/月(投资人版 ≈ ¥4,300/月,约 ¥50k/年)	投资人版
P0 产品功能覆盖	55/55 P0 产品功能可验证(Doc A 产品范围)	Three-Doc Suite Doc A/C

两条路线图并存 —— 不要混用:

• 投资人版(HJ-ARCH-002): 5 人核心团队 + ¥4,300/月基础设施 + 11 周 MVP,强调资本效率与窗口期验证。
• MVP execution spec(HJ-MVP-SPEC-001): 10 人 × 3 周(15 个工作日),强调 contract-first + 五工位并行。验收 = Doc A 中的 55 个 P0 产品功能;工作量 ≈ 137 个技术项。
• 生成成功率:采用 execution spec 的 ≥80%(投资人版未给直接数字)。引用指标时要对应到相应文档。

日常默认 = MVP execution-spec 版(10 人 × 3 周 / 55 P0 / ≈137 技术项);投资人版仅用于对外 / 资本效率叙述,不作为日常执行基线。本 §1–2 即是顶层目标锚点的 single source of truth(当前 MVP 目标 = 上面那一行全链路闭环)。明细归宿 —— docs/mvp/goals.md(章程)、.agents/knowledge/mvp-scope-and-milestones.md(55 P0 明细)、docs/architecture/运营/合规闸门.md(护城河 / 合规)—— 从这里通过指针展开;不要另立一份平行的目标文档。

---

3. 项目目录

3.1 三个业务代码库(目前是本 monorepo 的子目录;后续拆为独立仓)

状态: 三个代码库都 在本仓 内(game-cloud/、game-admin/、game-studio/;monorepo 先行、后续再拆)。游戏生成现行两条并存的线:Tier0/1 廉价线(便宜模型经 new-api 由 SAA 裸图编排、产物落 LittleJS 增强发行版、过九门兜底)与 tier2 富游戏线(AgentScope 自治 agent + Phaser 造多系统富游戏、独立 Python service、待 0 号 spike 验证)。两线终态产物都是 src/ 多文件源工程;Dify/OpenGame/RocketMQ/Nacos 均不在 MVP runtime(降级远期或 future-state)。细节见 .agents/knowledge/tech-decisions.md §1.1/§4 与 docs/architecture/架构/生成引擎/;演进史见 git。

代码库	角色	技术栈
game-cloud	后端(Huijing Cloud fork + 13 个游戏业务模块)	Java 17 + Spring Cloud Alibaba + MySQL + Redis + new-api gateway(生成主线)+ SAA(Spring AI Alibaba v1.1.2.2)裸图编排 (HJ-AGI-002;廉价线 agentic 基建 = SAA-only); Dify/OpenGame 降为 long-term 且从未部署, RocketMQ/Nacos future-state —— 这四者均不在 MVP runtime 中。tier2 富游戏线的 AgentScope 是独立 Python service、不在 Java 后端内(见上文 §3.1 banner)。
game-admin	管理后台前端(运营 / 管理员)	Vue3 + Element Plus(huijing-ui-admin-vue3 fork)
game-studio	产品前端(创作者 + 玩家)	Vue3 + Vant + LittleJS 增强发行版(引擎+能力插件库,Tier0/1 廉价线;旧「自研 Canvas Runtime <15KB」已于 2026-06-12 废除,见 .agents tech-decisions §1.1) + WanxiangGameSDK。tier2 富游戏线另用 AgentScope(Python 自治 agent)+ Phaser 造多系统富游戏(待 0号 spike 验证、尚未落代码);Cocos 只留 3D / 渠道导出轴(编辑器 + 人在环),3D / 独立 App 属更长期层级。

注(命名区分): Wave3 在 后端 game-cloud 内部新增了一个 studio 业务模块(创作流编排,错误码段 112 / Flyway V8)。它与上表中的 产品前端仓 game-studio 是两回事 —— 前者是后端编排模块,后者是 Vue3 前端仓。不要混淆。

3.2 当前仓(monorepo)目录结构

games-development-ai/
├── CLAUDE.md                  # 导入 @AGENTS.md(重定向到下面的单一入口)
├── AGENTS.md                  # 本文件:项目总览 + 在此如何工作(single source of truth)
├── contracts/                 # 8 个契约类(API yaml / DB Flyway / SDK / GamePackage / events / Dify IO / ad-slot / prompts)—— 跨端的 single source of truth
├── game-cloud/                # 后端(huijing fork + game-module-*;见 game-cloud/.agent)
├── game-admin/                # 管理后台前端(huijing-ui-admin-vue3 fork)
├── game-studio/               # 产品前端(创作者 + 玩家;见 game-studio/.agent)
├── deploy/                    # 部署与 smoke-gate 脚本(smoke-test.sh)
├── docs/
│   ├── architecture/          # 设计文档 SoT 根(2026-06-20 域化重构):README 总索引 + 6 域(产品/架构含生成引擎🚧/后端/前端/运营/运维)4 级人读散文树;旧长档归 _archive
│   ├── agent-specs/           # review/execution specs + close-out reports + _index.md(活地图·先读,辨活/死/被谁推翻)+ agent-loop orchestrator 与 runs(见 orchestrator/.agent)
│   ├── superpowers/specs/     # execution 级 specs,如 MVP execution spec
│   ├── mvp/                   # 活账本:进度总账 / 作战清单(+历史归档)/ 闸门看板 / 单位经济模型
│   └── memorys/               # (Legacy)早期任务快照 —— 已被 agent-specs/ 下的 close-out reports 取代;不再增长
├── docs-design/               # 产品 / 视觉设计材料
└── .agents/                   # Agent 能力中枢(knowledge/rules/skills/workflows)

3.3 两层文档与检索(2026-06-17 文档体系重构)

文档分为 两层 —— 这是一种阅读原则,而非新目录(分类 / 蒸馏门规则见 .agents/rules/engineering-conventions.md §10.6;来由见 docs/brainstorms/2026-06-17-文档体系重构-requirements.md):

• 策展层(少而准 · 读它 = 当前真相) —— 每个概念一份 SoT:
  • 顶层目标 / 定位 → 本文件 §1–2(MVP 目标锚点)
  • 产品 WHAT / 技术 HOW / 映射 / 各子系统现行架构 → docs/architecture/ 6 域设计树(2026-06-20 改根;§4 表,总索引 README)
  • 横切进度 + 13 模块完成度 → docs/mvp/MVP进度总账.md(模块进度单一 SoT = 其 §2 矩阵)
  • 各子系统的当前架构 → docs/architecture/ 对应域(2026-06-20 改根;生成引擎子树 🚧 架构演进中);docs/agent-specs/ 降为留痕 + 生成域演进设计链
  • 可复用能力 / 规则 / playbook → .agents/
• 留痕层(放开累积 · 检索,不要线性通读) —— 前门给出单一检索入口,而非逐文件链接:
  • 设计 / 任务喂料:docs/brainstorms/(WHAT)、docs/plans/(HOW),以及 docs/agent-specs/ 下带日期的功能设计文档(-设计.md,取代旧 review/execution 双档;见 .agents/skills/feature-design-doc.md)
  • 历史 / 证据:docs/agent-specs/_archive/、close-out reports
  • 检索入口 = docs/agent-specs/_index.md(活地图)+ git grep + frontmatter
• 界外:Claude auto-memory(~/.claude/projects/.../memory/,引擎托管 · 在仓外 · 每会话私有)—— 仅是个人加速器;仓库才是权威源,任何可复用的东西必须蒸馏回 .agents/ 才算数。
• 死库:docs/memorys/(legacy,只读,不再增长;新的留痕去 docs/brainstorms/ + docs/plans/)。

3.4 关键模块架构设计(引用 · 不在此展开)

各关键模块的简洁架构描述(每模块 ≤50 字:职责 + 架构组成 + 依赖)集中在单一 SoT .agents/knowledge/product-and-architecture.md,本入口只给指针、不重复内容:

• §5 = 13 个后端业务模块速查:studio · project · aigc · runtime · feed · telemetry · pay · trade · community · ip · compliance · biz · ad;
• 配 §3 分层架构 · §4 三仓与模块归属 · §6 模块依赖图 · §8 Game SDK 分层。
• 更深一层的子系统现行架构(生成主线 / 引擎与运行时 / 渠道发行 / studio 前端 / 变现与单位经济 等)→ docs/architecture/ 6 域树(2026-06-20 改根),导航见 docs/architecture/README.md;生成引擎子树 🚧 演进中。

---

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

设计文档已于 2026-06-20 域化重构:策展层设计 SoT 根 = docs/architecture/README.md(总索引,6 域 4 级人读散文树)。首次 onboarding 或架构级任务从它进;日常开发优先读 .agents/knowledge/ 蒸馏版。

顺序	文档	角色
1	docs/architecture/README.md(设计文档总索引 · 唯一入口)	6 域设计树:产品(定位/需求/护城河)· 架构(分层/技术决策/13 模块 / 生成引擎 🚧 演进中)· 前端 · 运营(变现/渠道/合规)· 后端 · 运维。取代旧的系统概要设计×3 + Three-Doc Suite(原档已归 docs/architecture/_archive/,决策史留档)
2	docs/superpowers/specs/mvp-execution-spec-design.md	MVP execution spec:10 人 × 3 周,contract-first(验收 = 55 个 P0 产品功能 / 工作量 ≈ 137 个技术项)

提示:蒸馏版位于 .agents/knowledge/,是日常默认入口;设计细节进 6 域树按需下钻。

---

5. .agents/ 目录导航

.agents/ 是项目的"Agent 能力中枢",分四类 —— knowledge(是什么) / rules(必须怎样) / skills(怎么做) / workflows(如何承接任务)。完整资产清单与一句话说明 = 单一事实源 .agents/README.md(本入口只给分类、不重复清单,避免双维护漂移);维护规则同见该 README。

---

6. 工作协议(硬约束)

以下是浓缩条款;完整流程见 .agents/workflows/ai-development-protocol.md。

1. 先读再动:对任何有真实复杂度的任务,先读 .agents/knowledge/ 及相关 docs/,对齐事实,再开工。
2. 复杂 / 高风险工作先评审:跨模块、改变用户可见行为、或触及外部服务 / 支付 / 数据的任务,先产一份功能设计文档(意图 / 目标 / 边界 / 验证 + 方案 / 步骤,见 .agents/skills/feature-design-doc.md)→ 评审 → 再执行;不要直接写代码。
3. 证据规则:区分"已验证事实 / 推断 / 假设"。没有验证证据,绝不宣称"完成 / 修好 / 通过 / 无问题"。 任何可运行的东西(测试、构建、lint、smoke)都必须跑。
4. 最小改动:只动与当前需求直接相关的代码,复用既有模式,不要随手重构无关的命名 / 目录 / 格式。
5. 中文注释:所有代码都必须带完整的简体中文注释;外部交互、核心实现、错误路径都必须有可追溯的日志。
6. Contract-first:接口 / 数据结构变更要先改契约(contracts/ 与 -api 包),再实现,并通知相关方。
7. 不留孤儿设计:任何新功能、数据结构、API、领域模型或工作流,都必须连同其面向用户的入口、使用路径、失败模式与验收标准一并交付 —— 没有无入口的 API、没有不接产品流程的孤立能力、没有只是把一份 spec 硬凑到另一份上的拼接方案。
8. plan 文档双(双边)评审门(2026-06-18,创始人):新建 brainstorm / plan 文档 —— 包括把新 units 折进一份既有活计划 —— 收口前必须过 Codex + Opus 双评审;若 Codex 不可用,回落到 Opus 单评。 两者并行跑(codex:codex-rescue + 一次 Opus 对抗式文档评审),把设计前提喂进去以免有意决策被当成缺陷,在文档内修掉发现项,并把跨文档发现项列为收口 TODO。
9. 内网阶段:决策与密钥进项目文档,不进 env var(2026-06-18,创始人):内网阶段,所有决策、所有密钥/凭据都进项目文档(内网 Tailscale 地址 / 密钥 / token 明确允许入仓)。密钥 → docs/内网凭据与端点.md(single source of truth —— NEWAPI_KEY / 端点 / 机器都在那)。需要 key?读那份文档 —— 不要再问创始人,也不要依赖环境变量。 决策 → 相应的 plan / 活档,永不只留在聊天里。
10. 文档治理强制门 —— 把规则编译成机器门(规则必须编译成机器门,否则等于没有)(2026-06-20,创始人文档治理工作):在无状态 agent 系统里,每一条文档治理规则(§7;engineering-conventions §10)只作为散文存在就毫无价值 —— 一个无状态、单会话的 agent 不会去"自我执行"它。规则必须被编译成机器门,在 wave-close 与 pre-commit 时运行,并 在违规时红线拦截:① 品牌不变量门(brand-invariant) —— rg 在活层里搜退役名 造梦AI 返回零(白名单:docs/ip 法律备案、_archive、带日期的留痕文档);② canonical 唯一性门(canonical-uniqueness) —— 每个 topic 至多一份文档标记为 canonical;第二份即红线(杀掉 doc-sprawl / 影子 SoT);③ doc↔code 兑现门(fulfillment) —— 一项基石设计的关键产品约束,要携带真正会运行的、机器可校验的断言(例如:生成产物必须是 src/ 多文件项目;逻辑不得只以 JSON 字符串 / new Function blob 的形式存在)—— 设计声称 X,代码就必须可验证地兑现 X;④ 入口卫生门(entry-hygiene) —— AGENTS.md 只承载项目事实:扫描禁入 git clone / 全局工具安装 / 个人绝对路径(~/.claude)/ 硬编码端口。门脚本 + 白名单见 engineering-conventions §10。
11. 横切一致性主人 + AGENTS.md 自审(整体一致性必须有一个有状态的主人)(2026-06-20,创始人文档治理工作):跨文档 / 跨任务 / 跨时间的一致性 —— SoT 收敛、品牌统一、设计↔代码兑现,以及 AGENTS.md 自身的新鲜度 —— 不得继续无主地压在"主 agent"(一个无状态、用完即弃的主体)身上,因为 人人无主即无人为主,整体随后会被局部最优的 agent 悄悄侵蚀。要显式指派:横切一致性主人 = 创始人 + 6c6g 文档/设计线(一个有状态的主体),负责机器门做不出的灰色地带判断(哪份文档过期了、两份冲突文档哪份胜出、一个补丁是否其实是架构信号)。并且 AGENTS.md 自审 —— 入口文件也会过期,而无人看守的根最危险(改名十天后它的标题仍写着"造梦AI"):任何改名 / 子系统增删 / 核心决策被推翻时,同一个 commit 必须重审 AGENTS.md;wave-close 门扫描它(品牌残留、死链、canonical 对账、入口卫生);主人定期做一次全量复审。
12. 落档文档 = 资深工程师写的散文,不是 AI 产出(2026-06-21,创始人):架构 / 设计 / 分析 / 评审 / 方案文档要清晰表达、逻辑连续,必要处配直白图表,写成流畅的人读散文。禁三样:① 元叙述 —— 不写讲述文档自身或写作过程的话("本文讲什么 / 下面介绍 / 这里要诚实交代 / 前面讲过 / 后面会讲 / 一句话收束"),直接陈述内容,逻辑靠内容自己往前走、不靠连接词宣告;② AI 造词与黑话堆砌 —— 不自造唬人的新词、不堆缩写行话(项目既有术语如 SAA / 九门 / O2 可用,首次出现讲清);③ 套话空强调 —— 去掉"至关重要 / 本质上 / 归根结底 / 值得注意的是"这类填充。口头汇报仍紧凑,但紧凑 ≠ 黑话。派子代理 / Workflow 写文档,必须把本标准连同正反例一起传下去 —— 实测只传"写散文"不够,输出会退回 AI 味(2026-06-21 控制面 v2 即栽在此)。

---

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

.agents/ 的目的,是让团队在长期开发中 复利式累积能力,持续抬高 AI 驱动开发的 能力、准确度与稳定性。因此:

• 每完成一项有价值的任务,你都必须把可复用的产出写回对应的 .agents/ 目录:
  • 新事实 / 蓝图知识 → knowledge/
  • 新硬约束 / 踩坑红线 → rules/
  • 新的可复用操作 playbook → skills/
  • 流程级改进 → workflows/
• 新增前先查重:优先更新既有文件而非新建;立刻修正或删除过时内容。
• 改动 .agents/ 时,同步更新 .agents/README.md 里的索引与交叉链接,以保持导航一致。
• 所有内容保持 简体中文、单一主题、简洁、易于快速检索。

没有蒸馏的任务是一次性消耗;有了蒸馏,下一个类似任务才能更快、更准地在既有成果上接着干。

---

8. 效率原则(复利)

AI 驱动开发应当"越做越快"—— 把每一份产出蒸馏成可复用资产,让效率随工作推进而复利累积。8 条核心策略(见 .agents/workflows/mvp-execution-orchestration.md):

1. 黄金模板先行:先把一个模块打磨到位,再克隆它的骨架到其余模块。
2. Contract-first:在任何并行工作之前先锁定契约(API/DB/SDK/event)。
3. 复用优先于重建(三级次序):写代码前,按顺序搜索 —— ① 仓内(skills/, knowledge/, existing code),② 生态现货(npm/PyPI/GitHub,强制 prior-art 步,见 .agents/rules/build-vs-buy.md),③ 而后才许自研; 基建类组件另须先过 Build-vs-Buy 前置门。
4. 验证门前置:TDD + 门 + 完成前验证,尽早抓出错误、防止返工(返工是头号效率杀手)。
5. 并行边界 = 模块边界:agent 之间零共享状态、worktree 隔离、只经契约交互。
6. .agents 复利蒸馏:每次交付都把学到的东西写回(见 §7)。
7. 缓存昂贵步骤:Prompt hash 命中就跳过 LLM;缓存构建 / 产物。
8. 可复现编排:把 fan-out + verify 冻结进 Workflow 脚本。

---

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

gstack 是一套 按开发者机器安装的全局工具(browse / review / QA / deploy / docs)。它 不属于本项目:其安装与完整用法存在于每位开发者的全局环境配置里(全局 CLAUDE.md),不在本项目入口。项目约定仅此一条:所有网页浏览 / 评审 / QA 都经由那个唯一的 /gstack 入口走,前提是机器已装好它。

入口卫生规则: 这份顶层 SoT 入口只承载 项目事实 —— 绝不放按机器的 setup、安装命令或个人绝对路径。那些存在于开发者的全局配置里,不在这里。(这条规则本身由文档治理工作中引入的品牌/入口卫生门强制执行。)