docs: 无AI味写作标准入 AGENTS §6.12 + tier2 自治富游戏引擎设计(生成引擎子树·风格金样板)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

AGENTS.md

@@ -180,6 +180,7 @@ games-development-ai/
 9. **内网阶段:决策与密钥进项目文档,不进 env var**(2026-06-18,创始人):内网阶段,**所有决策、所有密钥/凭据都进项目文档**(内网 Tailscale 地址 / 密钥 / token 明确允许入仓)。密钥 → [`docs/内网凭据与端点.md`](docs/内网凭据与端点.md)(single source of truth —— `NEWAPI_KEY` / 端点 / 机器都在那)。**需要 key?读那份文档 —— 不要再问创始人,也不要依赖环境变量。** 决策 → 相应的 plan / 活档,永不只留在聊天里。
 10. **文档治理强制门 —— 把规则编译成机器门(规则必须编译成机器门,否则等于没有)**(2026-06-20,创始人文档治理工作):在无状态 agent 系统里,每一条文档治理规则(§7;[engineering-conventions §10](.agents/rules/engineering-conventions.md))只作为散文存在就毫无价值 —— 一个无状态、单会话的 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](.agents/rules/engineering-conventions.md)。
 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 即栽在此)。
 
 ---
 

docs/architecture/架构/生成引擎/自治富游戏引擎.md

@@ -0,0 +1,99 @@
+# 自治富游戏引擎
+
+> 🚧 设计中 · tier2 是待 0号 spike 验证的假设,尚未落代码;过了 spike 才进建设。
+
+> **这是什么**:绘境AI 第二条游戏生成轨的设计 —— 用一个能自治工作的 AI agent,造现有廉价流水线做不出来的多系统富游戏(合成、经营、挂机这类)。
+> **给谁看**:生成主线的工程师、做技术选型与评审的人、想判断"富游戏能不能自动生成"的产品与创始人。
+
+## 现有生成线的天花板
+
+绘境AI 现在的生成线只擅长一件事:超休闲小游戏 —— 单场景、轻 UI、一个核心循环。它靠一套固定脚手架:强模型搭出声明式结构,便宜模型往里填逻辑,九门 harness 在真浏览器里真玩一遍判它能不能玩。pong、点击器、躲避、跑酷这类几何色块的单局游戏,它做得又快又稳。
+
+合成、经营、挂机、经济养成这些品类它做不出来。最典型的是《肥鹅美食街》那一档:屏幕上同时摆着资源栏、合成棋盘、店铺列表、订单面板、商店背包,内容上百件物品、一整套经济数值。难点不在画面,在三件事 —— 重 UI、多个系统互相接线、大内容量。固定脚手架的运行时本身装不下多关卡、库存、对话树、敌人状态机、可变 HUD;它的生成方式是一次性填一组固定的槽,而富游戏的系统之间是一张稠密的依赖图(合成产出进库存、订单读库存、解锁扣金币),一次填空填不出来。
+
+2026-06-20 的对抗审查把这条路判死:声明式数据壳加一坨不受约束的自由 JS,结构上只能到几何色块单局游戏这一档。这不是"还不够好",是范式的天花板 —— 让同一套 schema 同时背"可靠"和"复杂"两个互斥目标,正是审查点名的误判。富游戏必须另起一轨,不是给现有产线加分支。
+
+## 换一种生成方式
+
+造富游戏要把生成方式整个换掉:给一个 agent 一台完整的游戏工作站 —— 读引擎文档、写多个源文件、构建、跑真玩验收门、看截图、查资产 —— 让它在一圈确定性验收门的笼子里反复迭代,把游戏逼出来。
+
+这条轨叫 tier2,面向价值更高、产量更低的 premium 场景。它和现有超休闲廉价线解耦并存:两条轨各吃各的市场、各跑各的运行时。这是整条设计最硬的边界 —— tier2 的任何改动都不许碰、不许回归现有廉价线。
+
+## 三层拆分:数据表、骨架、表现层
+
+给 agent 一台工作站不等于放任它乱写。tier2 的范式叫"约束自治"(内部代号 O2,是"纯填充"和"纯自治"之间的折中)。它先把一款游戏拆三层,用三层框住 agent 的自由度:
+
+| 层 | 谁写 | 占比 | 内容 |
+|---|---|---|---|
+| 数据表 | LLM 填值 | 19% | 关卡参数、商品、合成链、订单、经济数值 |
+| 系统骨架 | 平台预建 | 25% | 资源结算、合成规则、订单状态机 —— 每个经营游戏都长一样 |
+| 表现层 | LLM 现写 | 56% | 场景画面、点击反馈、这款游戏独有的规则 |
+
+占比那列是实测的,而且这个数推翻了立项时的判断。立项时拍的是 80/10 —— 80% 复杂度能压成数据表加骨架、绕过 LLM,只 10% 要 LLM 真写。后来拿仓里一款真做出来的王蓝莓经营游戏量了一遍:12 个源文件、180KB,最贵的模型 Fable 配三轮人工编排造的,过了真输入 harness、赢和输两条路都能走到。逐文件按字节归类,结果是 19/25/56 —— 绕过 LLM 的只有 44%,LLM 必须真写的是 56%,是原估的五倍。最大的一块是 render.js 那种逐像素手画的场景和 UI,近两百处直接调底层 canvas,既压不成数据表也压不成骨架。
+
+44/56 没给 O2 判死刑,但它说清了真实的成本结构。约束这条杠杆,对"系统加手感"那 44% 真有效,而那 44% 恰恰是便宜模型最容易崩的部分:经营游戏的状态机(顾客队列、耐心、经济账本、结算循环)是可复用的品类骨架;手感、物理、粒子、音频、存档全走受控的插件 API(王蓝莓那款逻辑文件里几乎没有裸 canvas 调用,却有近百处插件 API 调用)。便宜模型最不会的事 —— 发明对的系统结构并正确接线 —— 被骨架和插件 API 接管了。
+
+真正烧钱和翻车的是那 56% 的表现层:每款都得 LLM 现写,体量最大,最容易出错 —— 布局乱、命中几何和渲染几何对不上、事件接错。所以 O2 的自治那一侧,担子比立项设想的重得多。这把成本和可靠性的赌注抬高了,也把后面那个 0号 spike 从"锦上添花"变成了"不证就不能投"。
+
+两端的选项也是这么排除的。一端是纯填充(O1),模型只填不写 —— 实测直接排掉,纯填充产不出那 56% 的手画场景,只能做换皮。另一端是纯自治(O3),不加约束 —— 它会在那 44% 上烧钱发散,富游戏工程的搜索空间太大,便宜模型会反复打转。O2 取中间,只比立项设想更靠自治一点:用骨架、数据表、插件 API 把系统层最难的 44% 锁死,把 LLM 的火力集中到必须写的 56%,再用门和熔断把自治关在笼子里。
+
+## 谁在写:单写者 ReAct + 四道熔断
+
+写游戏的是一个单写者 ReAct agent。ReAct 指 agent"想一步、调一个工具、看结果、再想下一步"的循环,不是一次把答案写完。单写者指只有一个 agent 持有整个工程的全局视图,它一个人写,不并行拆给多个 agent;旁边配几个只读的探路 agent 和一道独立评审。
+
+坚持单写者,是因为经营游戏多个系统共享同一套状态和约定,拆给并行 agent 几乎必然不一致。一个一手教训:曾经把"造一个 Flappy Bird"拆给并行子 agent,背景跑成了马里奥。
+
+```
+单写者 ReAct 循环(都在验收门内)
+
+  读文档/资产 → 写源文件 → 构建 → 九门 harness
+                  ↑                        │
+                  └──── 改 ← 读 verdict ───┘
+
+  四道熔断,任一先触发即停:
+  步数硬顶 · 网关预算闸 · 语义卡死探测 · 双层超时
+```
+
+agent 在门内能任意迭代,但被四道熔断关着,任一道先触发就停:每系统构建-修复的步数硬顶、网关的预算闸、语义层的卡死探测、双层超时。其中预算闸现在还不是强制硬闸,这条边界归《agentic 集成架构》那份。
+
+## 验收:机器判能不能跑,人判好不好玩
+
+验收切两层。
+
+确定性的归机器:能不能运行、玩起来正不正常、产物体积小不小,由九门 harness 在真浏览器里真玩一遍判。这一层有一条铁律 —— 绝不让 LLM 给自己打分。LLM 一旦进验收当裁判,会学会把游戏优化成"让裁判说好"而不是"真的好",门就废了。这条继承自现有九门:把"做完了"钉死在真浏览器真玩一遍,不是模型自夸。
+
+主观的归人:好不好玩、好不好看机器判不了,交人工终审,配一个 player panel 辅助。两个极端都不取 —— 把确定性门扩到自动判好玩,会得到一堆能刷的代理指标(同一套机制门下,精心做的打砖块和"摆三块砖点一下就赢"的退化品都能全绿);纯靠 LLM 当玩家裁判判好玩,又踩了上面那条 Goodhart 红线。人工终审这一环的吞吐和判据怎么定,是一笔待补的设计债,归《tier2 实现详设》。
+
+## 引擎选型:先过无头硬筛
+
+tier2 的产物是真引擎工程,引擎首批选 Phaser 和 PixiJS,过程是一道硬筛加一个判断。
+
+硬筛:引擎必须能全无头驱动 —— 纯代码或 CLI 就能建出游戏,不依赖任何图形编辑器。生成游戏的是 agent 不是人,从生成到构建到验收没有一步有人坐在编辑器前点鼠标;任何要开编辑器拖拽才能出工程的引擎,agent 无从下手。
+
+这道筛子筛掉了中文生态最厚的两个 —— Cocos Creator 和 LayaAir,它们都强制依赖图形编辑器、没有成熟的无头 CLI。更老的纯代码引擎 Cocos2d-x 和 Egret 过得了无头门,但已经社区停滞、维护断档,不能拿一条要长期演进的轨去押死引擎。
+
+排除 Cocos 要正面处理一处冲突,绕不过去:仓里有一份锁定结论写着 Tier2/3 = Cocos Creator 加 MCP,理由是"158 工具的 MCP 让 AI 驱动可行",并据此否决了 Phaser。这条结论站不住。核实过一手资料:Cocos Creator 官方 3.8《命令行发布》明写"从命令行运行仍需 GUI 环境""不存在独立于编辑器的 CLI";被当成核心理由的那个 MCP,上游 README 自述是 Cocos Creator 的编辑器扩展插件,要编辑器进程开着才能跑,根本不是 headless。所以本设计推翻这条锁定结论:tier2 自治生成引擎定为 Phaser/Pixi;Cocos 退回它真正合适的地方 —— 3D、复杂场景、渠道导出,人在环离线作者,进不了无人值守的生成循环。两件事活在两条正交的轴上,Cocos 当初为后一条轴被选没有错,只是进不了 tier2 的循环。
+
+选 Phaser/Pixi 的判断,是从 AI 作者的角度看引擎,不是从人类工程师的角度。对人,引擎好不好用看 API 顺不顺手;对 AI,第一位的是生态丰不丰富,因为生态丰富约等于训练数据密集 —— 模型见过这个引擎的真实代码越多,写出来越对、越不容易在自治循环里漂。Phaser 近四万星、2013 年至今持续演进、有现成的挂机经营先例、3.2 以上官方支持无头模式、用 esbuild 构建,正好和现有 Tier1 那条全程 Node/CLI 的路同构,能直接塞进现有 worker 循环和九门 harness。Pixi 是 Web 2D 渲染的事实标准,本身是纯渲染层,适合当能力包加载。
+
+这一档不用 LittleJS,两个理由:富游戏品类零先例,没人拿它做过有分量的经营、挂机;太冷门,训练语料里几乎没有它的代码,模型不会写。LittleJS 留给超休闲极小包那一档。
+
+两份证据别搅混:王蓝莓那款样本用的是 LittleJS,它证的是"真多文件引擎工程装得下经营富游戏",与具体引擎无关;Phaser 这条路能跑通另有证据 —— 2026-06-11 的引擎 spike 把同一款王蓝莓小卖部在 Phaser 上做了一遍,过了五门(真输入跑通赢和输两条路、39 次真点击、金币从 20 涨到 100、倒闭终态齐全)。两次成功都是最贵的模型加重人工编排做到的,不是便宜模型自治 —— 它们证伪了"形状做不出",把"模型降下来、自治换掉人工"这一半留给了 0号 spike。
+
+## 引擎是能力包,不是底座
+
+引擎在这套架构里不是一次选定、所有游戏都长在上面的固定底座,而是动态加载的能力包:每个引擎对应一套给 agent 用的 skill、tool、mcp、rag,换引擎对 agent 就是换一套加载的工具集,不是架构重写。这正合 agent"我有哪些工具能调"的工作方式。
+
+第一版不把这套接口建满。一上来就建满(skill / mcp / tool / rag / 脚手架五件套)而只有 Phaser 一个真实现、Pixi 留桩,接口形状会被那唯一的实现反向决定,接第二个引擎时多半得改。实验阶段只做两件最小的:把九门 harness 的引擎钩子(canvas 选择器、帧计数源)参数化,把 Phaser 的 rag 和脚手架硬编码进 worker。真正的能力包接口,等第二个引擎(Pixi)落地、有两个实现做依据,再抽。
+
+## 渠道:能发,只是从热发降为精选
+
+放弃 Cocos 不等于丢渠道。Phaser/Pixi 的游戏能发微信、抖音、快手小游戏,这是一项能建的能力,不是墙。所谓 Cocos 的渠道优势,核实下来大半蒸发:微信官方说 weapp-adapter 只是参考实现、不再维护,钦定"开发者基于自己的引擎实现自己的 adapter" —— 自研 adapter 本来就是正路,Cocos 的"一键"只是把这步在引擎内部替你做了,省掉的几步都是一次性能固化进产线的脚手架;变现 SDK 是 wx.* 原生调用,所有引擎都得手动接;快手没有任何引擎的专用导出,全平权。甚至有一处 Phaser 反占优:Cocos 的渠道构建要 Windows / Mac 机,纯代码引擎全 Linux 就能打包,对一条要服务器化的产线是反向收益。仓里 W-CH-α 这个 spike 已经为结构相同的 LittleJS 把这条路验到 P0(adapter 启动、收到合成触摸、6 门全过)。
+
+一处真约束、与引擎无关:渠道侧禁止动态生成代码(微信、抖音剥离远程代码、禁 eval 类解释器),只许"包内固定模板加远程纯数据配置"。所以 tier2 的富游戏上渠道,得从 web feed 那种"热发任意生成游戏"降为"精选款固化进壳、走平台提审"。这定义了产品形态:web feed 拿热发的长尾,渠道拿精选的爆款。Cocos 同样撞这堵墙,不是 Phaser 的劣势。
+
+## 现在证到哪,赌注在哪
+
+已证的是产物形态:王蓝莓那款 12 文件、180KB 的多系统经营游戏真做出来过、过了 harness,证伪了"声明式数据壳之外的真引擎工程装不下肥鹅级富游戏";Phaser 这条路能过确定性门也有 2026-06-11 的五门证据。
+
+没证的是 tier2 真正押的那一半 —— 这两次都是最贵的模型加重人工编排,不是便宜模型自治。最大的赌注是:便宜或中等模型的自治 agent,在经营骨架、玩法模板、资产池、RAG、九门兜底这套约束下,能不能稳定地把那 56% 的表现层写出来、过确定性门。整条 tier2 的 go/no-go 全悬在这上面,架构论证替代不了实测。这个赌注押在 0号 spike 上,怎么跑、过门阈值、退路树在《tier2 实现详设》。