5d0f351050
2026-07-09 创始人方向性质疑经五路审计坐实,正式推翻两个历史结论(80% 天花板=口径混淆 +stripCode 污染;玩法坏死主因=判卷合约缺口误标),病根三条=判定语义膨胀/判卷合约反噬/ 真相层缺失。本批为纯文档批: - 诊断档 docs/brainstorms/2026-07-09-生成线harness方向性诊断与换轴方向.md(人审版) - SoT 修订×4(双评审修入、docs-gate 绿):质量模型裁定三(L1 双证据=机械预筛∧独立模型 玩法判定,fail-closed+金标校准)/图说护城河改「分层验收」/验收门 §2.4/AGENTS.md §3.1 - 执行版 plan×2:07-09 三波换轴 + 07-10 验收v2(测试agent替E/G/H,创始人已批, 含附录A SoT 修订逐字终文与波0-3 工单拆分) - 策展层定点勘误:tech-decisions/三份生成线 skill 追加 2026-07-09 勘误注记(过九门 自此只算机械预筛),feature-design-doc 固化「人审版=brainstorm/SoT、执行版=plan」定位 - 在飞板登记 W-AXIS Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
130 lines
13 KiB
Markdown
130 lines
13 KiB
Markdown
# AGENTS.md — 绘境AI Project · Agent 入口
|
||
|
||
> **本项目以 AI 驱动开发的方式构建。** 无论你是 AI agent 还是人类工程师,每项任务都从这里开始。
|
||
> 本文件是项目入口的 **single source of truth**:回答"这个项目是什么"与"在它里面怎么干活"。`CLAUDE.md` 只是通过 `@AGENTS.md` 导入本文件。
|
||
> 设计文档的权威索引 = [`docs/architecture/README.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`](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`](.agents/knowledge/mvp-scope-and-milestones.md),进度见 [`docs/mvp/MVP进度总账.md`](docs/mvp/MVP进度总账.md)。
|
||
|
||
## 3. 项目目录
|
||
|
||
### 3.1 三个业务代码库(本 monorepo 子目录,后续拆独立仓)
|
||
|
||
现行技术口径(决策史与依据一律见 [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md),运行时单一真相见 [`docs/architecture/架构/生成引擎/agentic运行时架构图说.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`](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`](.agents/rules/engineering-conventions.md) §10.6):**策展层**(少而准,读它 = 当前真相:架构 6 域树 + mvp 活账 + `.agents/` + 本文件)与**留痕层**(放开累积,检索不通读:plans / brainstorms / agent-specs 带日期档)。
|
||
|
||
- 每个概念在策展层**只有一份 SoT**,登记在 [`docs/architecture/README.md`](docs/architecture/README.md) §2 注册表(frontmatter `topic` + `canonical: true`,docs-gate 机器对账);
|
||
- **检索入口**:注册表(当前真相)→ [`docs/agent-specs/_index.md`](docs/agent-specs/_index.md)(在飞)→ git grep / `git show`(历史);
|
||
- Claude auto-memory(引擎托管、仓外、每会话私有)只是个人加速器;**仓库才是权威源**,可复用产出必须蒸馏回 `.agents/`。
|
||
|
||
### 3.4 关键模块架构(引用)
|
||
|
||
13 个后端模块速查(每模块 ≤50 字)= [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md) §5,配 §3 分层 / §4 三仓归属 / §6 依赖图 / §8 SDK 分层;更深的子系统设计 → 架构 6 域树。
|
||
|
||
## 4. 任何任务开工前的必读顺序
|
||
|
||
| 顺序 | 文档 | 角色 |
|
||
|---|---|---|
|
||
| 1 | [`docs/architecture/README.md`](docs/architecture/README.md) | 设计总索引 + **SoT 注册表**(唯一入口) |
|
||
| 2 | [`docs/superpowers/specs/mvp-execution-spec-design.md`](docs/superpowers/specs/mvp-execution-spec-design.md) | MVP execution spec(55 P0 验收来源,主计划视图) |
|
||
|
||
> 日常开发默认先读 [`.agents/knowledge/`](.agents/knowledge/) 蒸馏版;设计细节进 6 域树按需下钻。
|
||
|
||
## 5. `.agents/` 目录导航
|
||
|
||
`.agents/` 是项目的"Agent 能力中枢",四类:**knowledge**(是什么)/ **rules**(必须怎样)/ **skills**(怎么做)/ **workflows**(如何承接任务),另有 **tools**(门脚本等)。**完整清单 = 单一事实源 [`.agents/README.md`](.agents/README.md)**;本入口不重复清单。
|
||
|
||
## 6. 工作协议(硬约束)
|
||
|
||
完整流程见 [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md)。
|
||
|
||
1. **先读再动**:任何有真实复杂度的任务,先读 [`.agents/knowledge/`](.agents/knowledge/) 及相关 `docs/`,对齐事实再开工。
|
||
2. **复杂/高风险工作先评审**:跨模块、改用户可见行为、触及外部服务/支付/数据的任务,先产一份功能设计文档(见 [`.agents/skills/feature-design-doc.md`](.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`](docs/内网凭据与端点.md)(single source of truth,需要 key 读它、不要再问);决策 → 相应活档,永不只留在聊天里。
|
||
10. **文档治理机器门**(2026-06-20 立,2026-07-02 落地脚本):规则必须编译成机器门,否则等于没有。门 = [`.agents/tools/docs-gate.sh`](.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](.agents/rules/engineering-conventions.md)。门③(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`](.agents/README.md) 索引。全部简体中文、单一主题、可检索。没有蒸馏的任务是一次性消耗。
|
||
|
||
## 8. 效率原则(复利)
|
||
|
||
八条核心策略(详见 [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md)):黄金模板先行;contract-first;复用优先于重建(仓内 → 生态现货([build-vs-buy](.agents/rules/build-vs-buy.md) 强制 prior-art)→ 才许自研);验证门前置;并行边界 = 模块边界;`.agents` 复利蒸馏;缓存昂贵步骤;可复现编排。
|
||
|
||
## 9. gstack 工具集(全局 · 仅指针)
|
||
|
||
gstack 是按开发者机器安装的全局工具(browse/review/QA/deploy/docs),**不属于本项目**;项目约定仅一条:所有网页浏览/评审/QA 经唯一 `/gstack` 入口走。
|
||
|
||
> **入口卫生规则**:本文件只承载项目事实——不放按机器的 setup、安装命令或个人绝对路径(docs-gate G4 强制)。
|