games-development-ai/.agents/skills/ai-generation-pipeline.md

AI 生成链路开发与联调手册（ai-generation-pipeline）

🛑 DEPRECATED 蓝图（Dify/OpenGame 管线已降级远期、从未部署）

下文 §目标 / §1–§5（Dify 开发流程、OpenGame/ComfyUI 对接、DifyClient 等）为 1.x 蓝图，勿照此搭建生成链路。 现行裁决（C2 2026-06-09 / HJ-GEN-001 终审 / HJ-AGI-002，agentic 基建 HJ-AGI-001 已于 2026-06-15 被 HJ-AGI-002 覆盖）：

• 生成主线 = new-api 网关 → 便宜模型直连（生产生成=M2.7/M3/DS-V4 + harness 门；Fable 只造引擎）；agent 写码于插件库，旧「LLM 填参 / 模板驱动生成」线退役。
• agentic 编排基建 = SAA(Spring AI Alibaba v1.1.2.2)裸图编排 (HJ-AGI-002；short-term SAA-only，AgentScope 降 long-term premium 独立轨)；「自研编排引擎 / DAG 工作流引擎」表述作废。
• Dify / OpenGame / ComfyUI(文生代码部分) = 降级远期，从未部署；网关=new-api，非 Dify。
• 仍现行有效的只有下方 §⓪（agent 闭环 v1 实证 + new-api 通道 + Prompt Registry + 回调写链语义）。素材生成侧 ComfyUI/Stability/Fish 选型另见 tech-decisions（图音素材链未被本裁决推翻）。 配套现行口径：../knowledge/tech-decisions.md §1/§1.1、../rules/build-vs-buy.md。

---

蒸馏来源：docs/architecture/架构/README.md（§4.1 AI 生成链路 / §6.2 §6.7 选型 / §7.10 产物缓存 / §8 风险）、docs/architecture/架构/13模块.md（aigc/studio 模块 T-AGC-/T-STU- 技术功能）、docs/architecture/架构/README.md（§10 外部工具层开发指南 / §6.2 联调）。 适用：开发/调试 aigc 模块（及其外部 AI 引擎 Dify / OpenGame / ComfyUI 已降级远期，见顶部横幅）。 配套：降级/可靠性红线见 ../rules/security-and-reliability.md；选型背景见 ../knowledge/tech-decisions.md；模块全景见 ../knowledge/product-and-architecture.md；新模块流程见 ./add-business-module.md；契约见 ./contract-first-development.md。

⓪ 2026-06-10 现实态（agent 闭环 v1 已验收，本节=唯一现行口径，下文 §目标–§5 为退役蓝图）

生产路径 = 「便宜模型直出 + agent 闭环 QA」（new-api 网关；Dify/OpenGame/ComfyUI 文生代码均未部署，下文蓝图已退役；旧"模板驱动生成"措辞按 2026-06-12 模板哲学更新——玩法模板层废除、agent 写码于插件库）：

• 真源与配方：设计=docs/agent-specs/2026-06-09-agent化生成QA闭环-{review,execution}.md（含全部裁决账）；M-b 生成下沉=2026-06-10-Mb生成下沉-execution.md；编排器/裁决/玩家取证代码=docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/（README 有批跑用法）；验收实证=runs/batch-001/（accept 80.0%）。
• LLM 通道：new-api http://100.64.0.8:3000 + MiniMax-M2.7 + response_format=json_object（key 走 NEWAPI_KEY 环境变量不入库；抽检模型走 NEWAPI_AUDIT_MODEL）。Prompt 全部走 contracts/prompts/ Registry（改必升版过四道闸），4 模板 GameConfig schema 在 contracts/templates/（真源对齐 gen_spike.py）。
• 批跑前置铁律：①浏览器侧 frontend 必须 http://localhost:4173（crypto.subtle 安全上下文，走 IP 真包也永 demo 兜底）②执行器与批跑互斥（批前关 aigc.executor.enabled）③首批前跑一次 evalflow.py --seed-spike（幂等）④抽检模型不可用按评审版 R8 降级（同模型异版本 prompt 重裁+告警），分歧>10% 冻结下一批发布开关。
• 回调写链（真实，9bf3d54）：唯一写入路径=DifyCallbackService.handleCallback（三表同事务：task/version/runtime_package；putManifest 未命中显式失败；checksum 两段序列化消解自指）——任何新生成来源（M-b 执行器/未来真 Dify）一律复用此语义，禁止旁路。

⓪′ P3 派发面（generic 外置 worker 生成 engineBundle 入 feed，3b-A 实证 2026-06-14）

范式：M-b「执行器进程内 LLM 出 GameConfig」之外，新增「派发外置 worker 产 engineBundle」路——仅 templateId=generic 走，旧四模板（若再开放）走旧进程内路逐行不变（零回归硬约束）。链路：执行器 dispatchGeneric（AigcGenerateExecutor）组 §6.1 job POST 给 aigc.executor.worker-url → worker 异步产 bundle → 把含 engineBundle 的 DifyCallbackReqVO POST 回新开的内网回调子路由 /admin-api/aigc/dify/callback-internal → 复用 handleCallback 唯一写入路径建版本/组包/落包 → 发布翻转入 feed。执行器投递握手成功即留任务 RUNNING 等回调（超 deadline 由 watchdog 收尸兜底），不在派发路写终态、不走进程内 chatJson（日志 executor-llm 对该任务 0 命中即铁证）。

两条红线（门里逮过的真坑·复用必看）：

1. 🔴 非 RBAC 的 HTTP 回调路必须自注入系统身份（部署窗口#3 同根因，换路复发）：worker 是内部服务无登录态，回调走 @PermitAll 内网子路由（仿 SmsCallbackController/pay-notify 范式解 §6.5 auth 孤儿）；但 @PermitAll 路在 web 线程无 LoginUser → DefaultDBFieldHandler 取不到 userId → handleCallback 三表 UPDATE/INSERT 的 updater/creator 带 null 直出撞 NOT NULL（DataIntegrityViolation，任务卡 RUNNING）。修法：内网回调 controller 内自注入系统身份 LoginUser().setId(0L).setUserType(ADMIN) 入 SecurityContextHolder，finally 必 clearContext()（镜像 AigcGenerateExecutor.executeWithSystemIdentity）。RBAC 的 /dify/callback 由登录管理员提供身份故无此坑——任何新免鉴权回调路（真 worker 3b-B/外部接入）都要补这条。
2. ✅ @PermitAll 内网回调路服务间签名已补(3b-B,关裸缺口)：原仅恃「内网不可外达」兜底=任意可达请求伪造回调驱动落包(安全红线)。3b-B 补 CallbackSignatureVerifier(HMAC-SHA256 对回调原始字节验签·MessageDigest.isEqual 常数时间比对抗时序·JDK 原生零依赖·空密钥=回退仅内网兜底);controller 接 @RequestBody String rawBody 先验签错签真 HTTP 401 再反序列化(手动校验补 traceId/status 非空·绕过 @Valid);worker 侧 json.dumps(payload,ensure_ascii=False).encode("utf-8") 一次算定既签既发(Content-Type 带 charset=utf-8 使 Spring @RequestBody String 同字节还原·hexdigest() 小写对齐 Java Character.forDigit)。HMAC 逐字节对账铁律:签名字节==HTTP 发送字节,两侧密钥(CALLBACK_SECRET/AIGC_CALLBACK_SECRET)逐字节一致,否则永不匹配。e2e 三态铁证(evidence-3bB/p4*.txt):缺签/错签→401、正签→HTTP200 过门走下游。(/dify/callback 真 Dify 接入补签名 TODO 同治。)

stub worker 配方（证管线用，3b-B 换真 worker）：game-cloud/scripts/wg1_stub_worker.py（极简 HTTP，收 job→读固定 pong bundle game-runtime/games/_wg1-gen/pong/bundle.iife.js 作 engineBundle→回调；gameConfig 回 §5.2 最小占位 {templateId,title,theme,engineDriven:true}，不调 LLM 不打包）。e2e 脚手架：p3b_scaffold_pong.sql(建 gameId=9302 四态)→插 generic 任务→回调建新版本→p3b_publish_flip.sql(把 feed 翻到回调新版本)→ CDP 复用 game-studio/evidence/p3-pong/p3-pong.driver.cjs <base> <gameId> <versionId> 真玩。配置：aigc.executor.worker-url（空=派发面无端点→generic 判 failed(llm_error)，不静默卡死）；staging 经 .env 注 AIGC_WORKER_URL；stub 起 durable 单元 systemd-run --unit=wg1-stub-worker。

真 worker 服务壳(3b-B,c99014c)：wg1/gen-worker/worker/service.py=http.server 壳包 L2 run_studio(design 展开一句话→自产 gatespec→九门真玩),run.py/agent_loop 逐行不改;POST /generate 收 §6.1 job→立即 202→后台串行(全局 Lock·run_studio 占 serve 4320/CDP 9222 不可并发)asyncio.run→过门读 _wg1-gen/gen-<gameId>/bundle.iife.js→HMAC 签名回调(见红线 2)。e2e 真证结论(2026-06-14,evidence-3bB/):✅ P0-P4 安全面+全自动管线闭合(执行器认领→投 job→worker 真生成真烧模型→HMAC 双向证→handleCallback 落库);❌ P5 终局未达=三款真生成全 nine_gate_failed(截图证真出 on-theme 可渲可动「点击小怪物」游戏,仅点击→计分坏→九门质量门正确拦截不可玩)。判:plumbing+安全+质量门=L0 易部分已成且证;便宜模型过九门=moat 真壁垒→生成质量转 L1(见 cheap-model-game-generation.md §3 点击坑/§8 质量门)。

---

目标

把自然语言 Prompt 经 aigc Java 壳 → Dify 编排 → OpenGame 代码生成 / ComfyUI 素材生成，产出可运行的 GamePackage（config + code + assets）并写回 project。产出后 runtime 可编译预览、创作者可试玩发布。

前置

• AI 引擎已起：docker compose -f deploy/docker-compose.ai.yml up -d（ComfyUI 需 GPU，无 GPU 时图片走 mock 或外部 API）。
• RocketMQ Consumer 已注册（生成任务靠 MQ 异步驱动；若一直 QUEUED 多半是 Dify 没起或 Consumer 没注册，见开发团队版 §9）。
• Dify workflow 已发布并拿到 workflow_id；OpenGame /generate 端点 curl 可调通。

---

1. 架构（四段）

┌──────────────────────────────────────────────────────────────┐
│  game-module-aigc（Java 壳，Spring Boot）                      │
│  ├─ Controller         接收创作请求（/app/aigc/generate）     │
│  ├─ TaskDispatcher     RocketMQ 异步调度（削峰/重试/超时）     │
│  ├─ DifyClient         HTTP 调 Dify Workflow API              │
│  └─ ResultWriter       写回 project 模块（草稿/版本）         │
├──────────────────────────────────────────────────────────────┤
│  Dify（Docker 自部署）— DAG 可视化编排                        │
│  ├─ 多 LLM 热切换（通义千问 / DeepSeek / OpenAI）            │
│  └─ 节点：安全检测→意图解析→模板匹配→GameConfig+Schema       │
│           →HTTP 调 OpenGame→HTTP 调 ComfyUI→质量评估         │
├──────────────────────────────────────────────────────────────┤
│  OpenGame Agent（Python 微服务，HTTP API）                    │
│  └─ 6 阶段 pipeline：脚手架→设计→素材→代码→验证→修正         │
│     输出可运行 Web 游戏代码（HTML/JS/CSS + assets）          │
├──────────────────────────────────────────────────────────────┤
│  ComfyUI（自部署）— 图片/贴图/角色/场景/封面素材生成          │
│  └─ 节点化 workflow，可训练 IP 风格 LoRA，HTTP API 对接 Dify  │
└──────────────────────────────────────────────────────────────┘

分工铁律：企业级监控/链路 trace/高并发优化都在 Dify 壳外侧（Java 壳） 做，不改 Dify/OpenGame 内核，保证可升级、可替换（技术决策版 §6.2）。

本手册聚焦 Tier1（OpenGame 文生代码 → 自研 Canvas Runtime）。 Tier2/3 复杂2D·3D·原生游戏走 Cocos-MCP（agentic 工具编排，归 studio，见 ../knowledge/tech-decisions.md §1.1），非本手册范围。所有节点 prompt 统一取自 Prompt Registry（git contracts/prompts/，第 8 类契约，按 id@version 加载注入、不内嵌 Dify/OpenGame 内核）；改 prompt 走 PR + eval 门禁，详见 ../../docs/agent-specs/prompt治理体系-execution.md。

---

2. 生成链路时序

创作者 Prompt + 模板/风格
  → ① Prompt 安全检测（违禁词/敏感意图/注入攻击 → 命中即拒绝）
  → ② 意图解析（LLM 提取玩法/角色/规则/风格结构化参数）
  → ③ 模板匹配（语义映射到预制玩法：躲避/跑酷/射击/解谜/点击收集）
  → ④ GameConfig 生成 + JSON Schema 校验（数值范围/必填/资源引用）
  → ⑤ OpenGame 代码生成（6 阶段 pipeline）
  → ⑥ 质量评估（结构完整性 / 资源有效性 / 运行成功率）
  → 输出 GamePackage（config + code + assets）→ ResultWriter 写回 project

素材生成（图片/封面）由 Dify 的 HTTP 节点在链路中并行调 ComfyUI（详见 Doc B aigc 模块）。

---

3. 生成任务状态机

状态：queued / running / succeeded / failed / timed_out / canceled（技术决策版 §4.1，Doc B aigc 模块）。

[*] → QUEUED ──消费消息──→ RUNNING
RUNNING → SUCCEEDED（生成完成 + 质量通过）→ [*]
RUNNING → FAILED（生成失败 / 质量不达标）
RUNNING → TIMED_OUT（超时 120s）
FAILED   → QUEUED（重试 ≤ 2 次）；超次 → [*]
TIMED_OUT→ QUEUED（重试 ≤ 1 次）；超次 → [*]
QUEUED / RUNNING → CANCELED（用户取消）→ [*]

要点：

• LLM 调用编排：单次 LLM 调用超时 30s、重试 2 次、熔断降级、供应商故障切换（详见 Doc B aigc 模块）。
• 任务级：超时阈值 120s；失败重试 ≤2、超时重试 ≤1；用户可在 QUEUED/RUNNING 取消。
• 失败要做原因分类 + 可读提示（描述不清/违规/超时/匹配低/校验失败，详见 Doc B aigc 模块）。

---

4. 性能指标与限流

指标	目标	出处
生成 P50 耗时	< 60s	技术决策版 §4.1
生成 P95 耗时	< 180s	技术决策版 §4.1
生成成功率（MVP 验收）	≥ 80%（基于 3-5 个模板）	MVP 执行 spec §1.2 / §4 Week2 Day10
生成成功率（远期蓝图）	≥ 85%	技术决策版 §4.1 / §1.2 系统目标
队列最大积压	500 任务，超过返回 429	技术决策版 §4.1

分层口径：≥80% 为 MVP 验收线（按此判定）；≥85% 为远期蓝图目标线。

---

5. Dify 开发流程

open http://localhost:3001            # 本地 Dify UI

# 创建/编辑游戏生成 Workflow：
# 1. Dify UI → Studio → 创建 Workflow
# 2. 加节点：LLM / HTTP(OpenGame) / HTTP(ComfyUI) / 条件分支 / 变量赋值
# 3. 测试运行 → 逐节点查看输入/输出
# 4. 发布为 API → 获取 workflow_id

后端 DifyClient 调用：

POST http://localhost:3001/v1/workflows/run
Content-Type: application/json
Authorization: Bearer <dify-app-token>

{
  "inputs": { "prompt": "...", "template_id": "..." },
  "response_mode": "blocking"
}

升级 Dify 必须锁定版本，能力增强放壳层（Java 侧）做，不动内核（技术决策版 §8 风险 5）。

---

6. ComfyUI 开发流程

open http://localhost:8188            # 本地 ComfyUI

# 设计图片生成 workflow（节点拖拽）：
# 1. 加载模型节点（Flux / SDXL / 自训练 IP 风格 LoRA）
# 2. 配置 prompt / negative_prompt / 尺寸 / 步数
# 3. 运行验证效果
# 4. 导出 workflow：Save → API Format（得到 workflow JSON）

Dify HTTP 节点对接 ComfyUI：

POST http://localhost:8188/prompt          # 提交：body { "prompt": <workflow_json>, "client_id": "..." }
GET  http://localhost:8188/history/{prompt_id}   # 轮询取结果图片 URL

选 ComfyUI 而非直调 Midjourney/DALL-E：可训练 IP 风格 LoRA 出风格一致的系列素材、节点 workflow 可被 Dify 编排、自部署无审查/无 API 限制、长期成本更低（技术决策版 §6.7）。

---

7. 降级（铁律）

LLM 不可用 → 退化为确定性 Fallback 生成器（模板参数填充，不依赖 LLM），保证"LLM 挂了仍能出基础可玩游戏"（详见 Doc B aigc 模块，技术决策版 §7.2 / §8 风险 1）。降级细则与超时/重试/熔断标准见 ../rules/security-and-reliability.md。

---

8. 本地地址速查

组件	地址	联调方式
Dify	http://localhost:3001	DifyClient 调 Workflow API；UI 看执行日志
OpenGame	http://localhost:8100	Dify 节点调用，或直接 curl /generate
ComfyUI	http://localhost:8188	Dify HTTP 节点对接 /prompt + /history
safe-content-ai	http://localhost:8200	图片 NSFW 快检（compliance 用）

---

9. 常见坑

坑	排查 / 应对
生成任务一直 QUEUED	查 Dify 是否启动 + RocketMQ Consumer 是否注册（开发团队版 §9）；查 TaskDispatcher 日志
OpenGame 社区停更	fork 自维护（核心 pipeline 逻辑简单可控）；最坏退化为纯 Dify + 模板生成（技术决策版 §8 风险 4）
Dify 升级不兼容	锁定版本 + 壳层隔离，自部署可控；能力增强放 Java 壳侧（技术决策版 §8 风险 5）
同一 Prompt 反复烧 LLM token	开生成产物缓存：相同 Prompt hash 命中即跳过 LLM 调用（技术决策版 §7.10），省成本 + 加速
LLM 输出 GameConfig 不合规/字段缺失	链路内 JSON Schema 强校验 + 资源有效性校验，不达标不入库（技术决策版 §8 风险 2）
生成游戏质量飘忽	用模板约束输出 + 可玩性自动测试；模板级 Golden Config 回归比对防退化（详见 Doc B aigc 模块）
素材生成 ComfyUI 无 GPU 慢/不可用	CPU 模式慢 10x；MVP 无 GPU 时图片走 mock 或外部 API（开发团队版 §1.3）