docs(agents): 精简 AGENTS/指令体系 + 立功能设计文档规范，删退役 pipeline
- 新增 feature-design-doc.md：功能设计文档作业手册（WHAT+HOW 合一·图文一式两份：文字+mermaid 给人/AI、svg/html 给人更重要；取代 review/execution 双档） - 删退役 ai-generation-pipeline.md（Dify/OpenGame 蓝图）；现行红线（回调唯一写入路径/免鉴权身份注入/HMAC 验签）抢救进 security-and-reliability §1.3；8 处引用改指向 agentic-amodel/saa/§1.3/§5.2 - AGENTS.md 226→182：§5 四张资产表删→指针（根治与 README 双维护漂移，补回漏列项）；§3.1 生成线 banner 考古史瘦身；§3.3+§6 接入功能设计文档 - README 索引同步 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
zizi
parent
c1bf28f15b
commit
3cd4769f6b
@ -47,7 +47,6 @@
|
||||
|---|---|
|
||||
| `skills/add-business-module.md` | 新增一个 game-module 业务模块的标准步骤 |
|
||||
| `skills/add-game-template.md` | 新玩法模板接入配方（契约→prompt→runtime→后端→编排器→五级验收门，merge 实战收口版） |
|
||||
| `skills/ai-generation-pipeline.md` | AI 生成链路（Dify + OpenGame + aigc 壳）开发手册 |
|
||||
| `skills/littlejs-game-dev.md` | **AI 直接写 LittleJS 游戏代码作业手册(code 层)**：12 插件 API 速查(8 基元 + 4 编排=session-score/hud-ui/scene-fsm/timer-scheduler) + 可导航代码结构 + 写 WHAT 调 HOW 边界 + 资产/mmx 流 + 工厂五法契约 + 受控面铁律（终态产物=src/ 多文件工程，取代废弃的 gameDefinition JSON 投影线） |
|
||||
| `skills/sim-business-game-design.md` | **经营模拟小游戏玩法设计作业手册(给 SAA design 层)**：放置/经营/养成爆款范式(玩法/机制/进度/数值/美术/UI/音)→ 映射 A-model 12 插件可达子集 + design 层输出配方 + 反"无趣"8 条自检；与 littlejs-game-dev(code 层)配对 |
|
||||
| `skills/runtime-and-multichannel.md` | 运行时打包、沙箱、SDK 与多渠道导出手册 |
|
||||
@ -63,6 +62,7 @@
|
||||
| `skills/doc-organizer.md` | 文档整理助手（创始人手动触发）：增量(上次清理→现在)+**两阶段审批门**——发起分析 Workflow→编清理计划→评审→批准后才执行；三轴=过期档清理(归档/压缩)/核心设计档措辞对齐现行真相/主任务总账回填；底层 `tools/doc-organizer.{sh,-analyze.mjs,-state.json}`（检测自动·判断留人·脚本不自删·最新日在飞档不碰） |
|
||||
| `skills/drive-remote-claude-tmux.md` | 远程驱动交互式 Claude Code（ssh + tmux）：双向通道 send-keys 派活 + capture-pane 读屏，不走 ACP/headless；每设备配置块 + onboarding 侦察配方 + 专用会话(独立 worktree 防撞树) + bypass-perms + 安全红线；**完成判据=git push 非读屏**（创始人 2026-06-18 拍板·多设备复用） |
|
||||
| `skills/architecture-diagram-atlas.md` | 架构图集生成配方：house style 规格 / 图说文档结构(金样板) / 三范式纪律(单源·防漂移门·状态双层) / 按域并行编排(克隆金样板·结构化返回) / 复验脚本 / 双评审揪出的六坑(漏域·现行远期错标·缺状态列·契约画理想·凑数配额·复制Mermaid漂移) / 分两期+跨session协调(生成引擎子树归在飞线只链不画)（2026-06-22 第一期实证） |
|
||||
| `skills/feature-design-doc.md` | **功能设计文档作业手册**：取代 agent-specs review/execution 双档；一份文档 WHAT(意图/目标/边界/验证)+HOW(方案/步骤)合一；一式两份(文字+Mermaid 给人/AI · SVG/HTML 给人更重要、看图即懂)；复用 atlas house style + 防漂移单源(文字为准) + 媒介分工(md 直渲 Mermaid/SVG · HTML 链接打开)（2026-06-24 创始人定） |
|
||||
|
||||
**workflows/**
|
||||
|
||||
|
||||
@ -42,6 +42,14 @@
|
||||
- 第二道：高风险样本送**阿里云内容安全**二次确认；文本/音频审核走阿里云 API；AI 输出走 Dify 节点内置 Guardrails。
|
||||
- 阈值（Nacos 配置）：**block = 0.7（直接拦截）/ review = 0.4（送人工）/ pass < 0.4（自动通过）**。
|
||||
|
||||
### 1.3 内网服务间回调安全（生成 worker 回调实证）
|
||||
|
||||
生成走「执行器派发 job → 外置 worker 产物 → 回调写库入 feed」时，回调是免登录的内网 HTTP 路（仿 SmsCallback / pay-notify）。三条红线缺一即被伪造或卡死：
|
||||
|
||||
- **唯一写入路径，禁旁路**：任何生成来源（进程内执行器 / 外置 worker / 未来真第三方）回写版本与产物，一律复用同一个写库服务方法（三表同事务：task / version / runtime_package，putManifest 未命中即显式失败）。新增来源不得另开写库旁路。
|
||||
- **免鉴权回调必自注入系统身份**：`@PermitAll` 回调路在 web 线程无 LoginUser，审计字段 creator/updater 取不到值会撞 NOT NULL、任务卡死。回调 controller 内必须自注入系统身份（`LoginUser(id=0, ADMIN)` 入 SecurityContext），`finally` 必 `clearContext()`。
|
||||
- **服务间回调必 HMAC 验签**：仅靠「内网不可外达」兜底，等于任意可达请求都能伪造回调驱动落包。回调体按**原始字节** HMAC-SHA256 验签（`MessageDigest.isEqual` 常数时间比对）、**先验签错签直接 401、再反序列化**；两侧密钥与签名字节须逐字节一致。
|
||||
|
||||
---
|
||||
|
||||
## 2. 创作链路 7 道门禁
|
||||
|
||||
@ -15,7 +15,7 @@
|
||||
>
|
||||
> 蒸馏来源：`docs/agent-specs/_archive/2026-06-10-Mc模板波-execution.md`（HJ-MC-TPL-EXEC-001 §3–§9 全链）+ M-c 批① merge 模板实战收口（2026-06-10，五级验收门全过：构建/体积/契约门+真玩五AND双模板+Golden v1.1.2 PASS+校准批 accept 10/10+金丝雀10条入feed；途中逮修三真缺陷，见各节红框）。
|
||||
> 适用（~~已退役，见顶部横幅~~）：给「模板驱动生成 + agent 闭环 QA」生产链**新增一个可玩玩法模板**（merge/idle/tycoon 类纯 Canvas Tier1 玩法），覆盖契约→prompt→runtime→后端→编排器→五级验收门全链。
|
||||
> 配套：新增后端业务模块（非玩法模板）见 [`./add-business-module.md`](./add-business-module.md)；生成链路现实态见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md) ⓪ 节；契约先行见 [`./contract-first-development.md`](./contract-first-development.md)；运行时/SDK 见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；Prompt 治理见 [`./prompt-governance.md`](./prompt-governance.md)；可靠性红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||||
> 配套：新增后端业务模块（非玩法模板）见 [`./add-business-module.md`](./add-business-module.md)；生成链路现实态见 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md)；契约先行见 [`./contract-first-development.md`](./contract-first-development.md)；运行时/SDK 见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；Prompt 治理见 [`./prompt-governance.md`](./prompt-governance.md)；可靠性红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||||
|
||||
---
|
||||
|
||||
@ -30,7 +30,7 @@
|
||||
|
||||
## 前置
|
||||
|
||||
- 已读 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md) ⓪ 节（生产路径已切「模板驱动生成 + agent 闭环 QA」），对齐编排器三件位置：`docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/`（`run_batch.py` / `player_cdp.py` / `judge.py` / `prompts.py`）。
|
||||
- 已读 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md)（现行生产形态），对齐编排器三件位置：`docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/`（`run_batch.py` / `player_cdp.py` / `judge.py` / `prompts.py`）。
|
||||
- 重型构建/测试一律走 **mini-desktop**（git push→pull 同步，本机严禁 `mvn`/`npm build`，记忆 `internal-build-infra-servers`）；前端构建必须 `npm run build -- --mode staging`（缺 staging env → mock 接管 → 静默 demo 兜底）。
|
||||
- 与在飞波次的**文件级共改**先排程：若另一波已改 `game-module-aigc-server/pom.xml` 或 `service/task/AigcTaskServiceImpl.java`（如鉴权波 PlayerApi seam），本波在其合入后开工，开工前 `git pull`/`rebase` 取最新基线（执行版 §11.1）。
|
||||
|
||||
|
||||
@ -1,213 +0,0 @@
|
||||
# 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`](../knowledge/tech-decisions.md) §1/§1.1、[`../rules/build-vs-buy.md`](../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`](../rules/security-and-reliability.md)；选型背景见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md)；模块全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；新模块流程见 [`./add-business-module.md`](./add-business-module.md)；契约见 [`./contract-first-development.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`](./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`](../knowledge/tech-decisions.md) §1.1），非本手册范围。所有节点 prompt 统一取自 **Prompt Registry**（git `contracts/prompts/`，第 8 类契约，按 `id@version` 加载注入、不内嵌 Dify/OpenGame 内核）；改 prompt 走 PR + eval 门禁，详见 [`../../docs/architecture/架构/生成引擎/prompt治理.md`](../../docs/architecture/架构/生成引擎/prompt治理.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 开发流程
|
||||
|
||||
```bash
|
||||
open http://localhost:3001 # 本地 Dify UI
|
||||
|
||||
# 创建/编辑游戏生成 Workflow：
|
||||
# 1. Dify UI → Studio → 创建 Workflow
|
||||
# 2. 加节点：LLM / HTTP(OpenGame) / HTTP(ComfyUI) / 条件分支 / 变量赋值
|
||||
# 3. 测试运行 → 逐节点查看输入/输出
|
||||
# 4. 发布为 API → 获取 workflow_id
|
||||
```
|
||||
|
||||
后端 `DifyClient` 调用：
|
||||
|
||||
```http
|
||||
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 开发流程
|
||||
|
||||
```bash
|
||||
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：
|
||||
|
||||
```http
|
||||
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`](../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） |
|
||||
@ -37,7 +37,7 @@ brief 题面 → 便宜模型写 `generated-factory.js`（一个 `GameHostFactor
|
||||
## 5. 边界与未做
|
||||
|
||||
- 只消费冻结契约（`game-host.d.ts` / 6 受控面 / `__GameBundle` / `bootGameHost`）**零修改**；只在 lane 分支，不推 dev/2.0.0。
|
||||
- **✅ 生产接线已成(3b-B 派发面,`c99014c`)**：`AigcGenerateExecutor.dispatchGeneric`→真 worker `service.py`(包 `run_studio`)→HMAC 回调→落库入 feed 全链真证闭合(见 [`ai-generation-pipeline.md`](./ai-generation-pipeline.md) §⓪′)。3b-B 单款一句话「点击小怪物」真生成卡九门(Score 恒 0→**质量门正确拒发不可玩=系统履职非故障**),`run_studio` 自修 `max_repairs` 未救回。**⚠️ 但单点失败≠模型壁垒**:L1 scale-20 14 款实证(§9)便宜模型实际相当能干(主力 7/8 可玩、自写 CCD/文本HUD/网格/match 全对),多数失败是**宿主键盘桥 host bug(已修 `d754b71`)+ driver-coverage(harness 太朴素),非模型**;3b-B 那款真因(driver-coverage 或该款 hit-detection)续查并入 §9 画像。**真难点不是模型能力,是 harness driver 覆盖 + 宿主门面完备**(§9)。
|
||||
- **✅ 生产接线已成(3b-B 派发面,`c99014c`)**：`AigcGenerateExecutor.dispatchGeneric`→真 worker `service.py`(包 `run_studio`)→HMAC 回调→落库入 feed 全链真证闭合(见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md) §1.3)。3b-B 单款一句话「点击小怪物」真生成卡九门(Score 恒 0→**质量门正确拒发不可玩=系统履职非故障**),`run_studio` 自修 `max_repairs` 未救回。**⚠️ 但单点失败≠模型壁垒**:L1 scale-20 14 款实证(§9)便宜模型实际相当能干(主力 7/8 可玩、自写 CCD/文本HUD/网格/match 全对),多数失败是**宿主键盘桥 host bug(已修 `d754b71`)+ driver-coverage(harness 太朴素),非模型**;3b-B 那款真因(driver-coverage 或该款 hit-detection)续查并入 §9 画像。**真难点不是模型能力,是 harness driver 覆盖 + 宿主门面完备**(§9)。
|
||||
- **未做/续(创始人并行)**：20 款补全(scale-20 已 14 款,见 §9)、四模型横比(过门率/重试/¥每过门)、6 个 driver-coverage 失败款的 driver 增强(flappy/multiball/愤怒小鸟等)、键盘款修后批量重跑、calibration 人锚补全——规划见 [`2026-06-14-WG1-bakeoff天花板与Claude-free评估门-review.md`](../../docs/agent-specs/_archive/2026-06-14-WG1-bakeoff天花板与Claude-free评估门-review.md)。
|
||||
|
||||
## 6. 官方 latch 终态契约 + 套壳（P3 对齐，2026-06-14）
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
> 蒸馏来源：`docs/superpowers/specs/mvp-execution-spec-design.md`（§3 契约先行 / §6 并行解耦与 Mock / §8.3 联调规则）、`docs/architecture/架构/README.md`（§6 联调协议）、`docs/architecture/架构/README.md`（§7.7 API 契约与版本）。
|
||||
> 适用：多工位（前端/后端/SDK/AI/数据）并行开发同一交付时，先锁契约、再各自 mock 解耦、最后集中联调。
|
||||
> 配套：工程规范（错误码/API 路径/`-api` 包）见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；新模块契约落地见 [`./add-business-module.md`](./add-business-module.md)；生成链路契约见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md)；SDK 契约见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；任务协议见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)。
|
||||
> 配套：工程规范（错误码/API 路径/`-api` 包）见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；新模块契约落地见 [`./add-business-module.md`](./add-business-module.md)；生成链路见 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md) 与编排 [`./saa-graph-orchestration.md`](./saa-graph-orchestration.md)；SDK 契约见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；任务协议见 [`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
86
.agents/skills/feature-design-doc.md
Normal file
86
.agents/skills/feature-design-doc.md
Normal file
@ -0,0 +1,86 @@
|
||||
# 功能设计文档作业手册（feature-design-doc）
|
||||
|
||||
> 每个有真实复杂度的功能，开工前产出**一份**「功能设计文档」，取代旧的 `-review.md` + `-execution.md` 双档。一份文档同时承载 **WHAT**（意图/目标/边界/验证）与 **HOW**（方案/步骤），并以**一式两份**的表达服务两类读者：**文字 + Mermaid** 给人和 AI（AI 主靠它），**SVG / HTML** 给人（更重要，看图即懂边界与核心思想）。
|
||||
|
||||
## 何时用
|
||||
|
||||
- 新功能、跨模块、改变用户可见行为、触及外部服务 / 支付 / 数据的**设计阶段**。
|
||||
- 简单、局部、低风险任务**不需要**——直接做，别为一次性改动套重型文档。
|
||||
|
||||
## 这份文档承载什么（WHAT + HOW 合一）
|
||||
|
||||
| 段 | 回答 | 要点 |
|
||||
|---|---|---|
|
||||
| 意图 | 为什么做 | 解决什么真实问题、不做会怎样 |
|
||||
| 目标 | 要达成什么 | 尽量可量化（指标 / 验收线） |
|
||||
| 边界 | 做 / 不做 | in scope / out of scope 一眼分清，挡住范围蔓延 |
|
||||
| 方案 | 怎么实现（架构级） | 模块如何协作、关键设计决策与取舍 |
|
||||
| 步骤计划 | 分几步落地 | 每阶段：交付物 / 验证 / 依赖 / 风险 |
|
||||
| 验证 | 怎么算成功 | 验收标准、可观测信号 |
|
||||
|
||||
**禁令（硬约束）**：禁代码细节（函数签名 / 伪代码 / 具体实现——那是写代码时的事）；禁黑话 / AI 味 / 元叙述；方案与步骤只写**架构级 HOW**（做什么、谁产出什么、怎么验），不写代码级 HOW。
|
||||
|
||||
## 一式两份：四种表达的分工
|
||||
|
||||
| 媒介 | 读者 | 角色 | 在 md 里 |
|
||||
|---|---|---|---|
|
||||
| **文字（中文散文）** | 人 + AI | **事实源**，自洽——脱离图也能读懂全部设计；后续 AI 主要消费它 | 正文 |
|
||||
| **Mermaid** | 人 + AI | 结构图（流程 / 状态 / 时序 / 依赖），文本可 diff、随文档同源 | 内联 ```mermaid``` 块 |
|
||||
| **SVG** | 人（**更重要**） | 核心概览 / 边界 / 关系大图，看图即懂；颜色舒适、留白、核心路径高亮 | `assets/` 引用 inline |
|
||||
| **HTML** | 人（可选增强） | 需交互 / 超丰富排版时的独立澄清页 | **链接**打开，不内联 |
|
||||
|
||||
**渲染现实（别踩）**：Markdown 渲染器（GitHub / Gitea）**直渲 Mermaid 与 inline SVG**，但**不内联渲染独立 `.html`**（md 内的 html 标签多被过滤）。所以——md 阅读流里**能直接看到的 = Mermaid + SVG**；HTML 只作「🔗 在浏览器打开交互版」的链接，**非必需**：SVG 能讲清就不上 HTML。
|
||||
|
||||
**媒介怎么选**：结构关系 / 流程 → Mermaid；「一眼看懂全局 / 边界 / 核心思想」→ SVG（本文档的门面）；确需交互（可展开、可切换、可点选）→ HTML 独立页。
|
||||
|
||||
## House style（复用，不另起）
|
||||
|
||||
功能设计文档的所有图，**配色 / 三线语义 / 徽章 / 脚注 / 转义 / 复验脚本一律照** [`architecture-diagram-atlas.md`](architecture-diagram-atlas.md)：浅底 `#f8fafc`、主字 `#0f172a`、实线=现行 / 虚线=自建远期、远期紫 `#7c3aed`、红线 `#dc2626`、圆角 `rx 7~12`、脚注全角「：」、SVG 文字内 `< > &` 必转义。
|
||||
|
||||
**侧重差异**：atlas 面向「据图找缝」，**功能设计文档面向「快速理解」**——更重留白、层次分明、核心路径高亮，别堆信息密度。颜色要舒适、对比柔和。
|
||||
|
||||
- SVG 在 6c6g 出文本；PNG 批量转在 **mini-desktop**（6c6g 禁 chrome）。见 [`staging-ops.md`](staging-ops.md)。
|
||||
|
||||
## 防漂移：一式两份的单一事实源
|
||||
|
||||
「两份」绝不能平等维护，否则必漂移（本项目反复踩的坑）：
|
||||
|
||||
- **文字 + Mermaid = 事实源**（随 md 走、可 diff）；**SVG / HTML = 派生视觉**。
|
||||
- 设计变更：**先改文字 + Mermaid，再据此更新 SVG / HTML**；图文冲突**以文字为准**。
|
||||
- frontmatter 防漂移门（复用 atlas）：记关联**代码 / 契约的 commit hash** + 图清单；收口比对 hash，对不上标「待复核」。
|
||||
- 权威**细节**只写在文字里（图里重复一份 = 又一个漂移面）；图只承载**结构与边界的直觉**。
|
||||
|
||||
## 文档结构骨架
|
||||
|
||||
```
|
||||
---
|
||||
date / topic / status（草稿 | 评审中 | 已批准 | 已实现）
|
||||
关联: <代码 / 契约路径 + commit hash> # 防漂移门
|
||||
图清单: [图1 概览, 图2 边界, ...]
|
||||
---
|
||||
# <功能> 功能设计
|
||||
|
||||
## 0 一图看懂 # 顶部放最重要的 SVG 概览 + 三句话：核心思想 / 边界 / 怎么算成功
|
||||
## 1 意图与目标 # 为什么做、要达成什么（可量化）
|
||||
## 2 边界 # 做什么 / 不做什么（配边界图）
|
||||
## 3 方案 # 架构级，关键决策与取舍（配结构图）
|
||||
## 4 步骤计划 # 分阶段：交付物 / 验证 / 依赖 / 风险（配阶段图）
|
||||
## 5 验证方式 # 验收标准、可观测信号
|
||||
## 6 风险与回滚
|
||||
## 附 图清单与状态 · HTML 增强页链接
|
||||
```
|
||||
|
||||
**§0「一图看懂」是门面**：一张 SVG + 三句话，让人 30 秒抓住意图、边界、核心思想；这是本文档「给人读、更重要」的承诺所在。
|
||||
|
||||
## 生产与评审
|
||||
|
||||
- **文字层**由主会话 / opus 写，务必自洽——后续 AI 消费它，缺图也要能读懂全部设计。
|
||||
- **图层**每图一 opus 子代理：克隆 atlas 金样板 → 画 → 跑复验脚本 → 对抗自检；house style 与散文铁律（连同正反例）**随 prompt 一起传下去**（只传「画图」不够，输出会回退 AI 味）。
|
||||
- **评审**：这份文档仍过双评审门（Codex + Opus，Codex 挂回落 Opus 单评），对象 = 这一份文档。
|
||||
- 命名 `docs/agent-specs/YYYY-MM-DD-<功能>-设计.md`；SVG / HTML 入同名或共享 `assets/`（顶层文档 → 子目录 assets 单向下引，别跨子目录引图）。
|
||||
|
||||
## 取代关系
|
||||
|
||||
取代旧的 `-review.md` + `-execution.md` 双档（2026-06-24 创始人定）。存量双档作 trace 留 git / `_archive`，**不强行合并历史**；新功能一律产这一份。
|
||||
|
||||
> 相关：[`architecture-diagram-atlas.md`](architecture-diagram-atlas.md)（house style / 复验脚本 / 三范式防漂移）、[`wave-close-checklist.md`](wave-close-checklist.md)（收口同步纪律）、[`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)（设计在协议中的位置）。
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
> 蒸馏来源：执行版 [`../../docs/architecture/架构/生成引擎/prompt治理.md`](../../docs/architecture/架构/生成引擎/prompt治理.md)（HJ-PROMPT-GOV-EXEC-001）。
|
||||
> 适用：新增/修改任何生命周期 prompt（意图/代码生成/素材/剧情/锁风/测试/平台转换/运营诊断）、搭建 Prompt Registry 与 eval 门禁、对接人在环（HITL）节点。
|
||||
> 配套：契约先行见 [`./contract-first-development.md`](./contract-first-development.md)；AI 生成链路见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md)；运行时/Cocos 见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；选型见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1；降级红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||||
> 配套：契约先行见 [`./contract-first-development.md`](./contract-first-development.md)；AI 生成链路见 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md)；运行时/Cocos 见 [`./runtime-and-multichannel.md`](./runtime-and-multichannel.md)；选型见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1；降级红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||||
>
|
||||
> **⚠️ 引擎上下文纠偏（2026-06-12）**：本手册**核心理念（Prompt 即第 8 契约 / Registry / eval 门禁 / HITL）现行有效不变**；但下文凡以 **Dify / OpenGame** 为注入目标/引擎载体的描述均按现行裁决改读——**Dify/OpenGame=降级远期未部署**（C2/HJ-GEN-001），Tier1 生成主线=**new-api 网关 + agent 写码于插件库**（引擎=LittleJS 增强发行版），agentic 编排基建=**AgentScope 2.x**（HJ-AGI-001）。"模板填充"措辞按模板哲学终裁更新（玩法模板层废除）。Cocos-MCP（Tier2/3）仍现行有效。
|
||||
|
||||
@ -132,7 +132,7 @@ aigc 新增**无状态原子**：输入 GameConfig → 输出可玩性测试脚
|
||||
| 失败点 | 降级 |
|
||||
|---|---|
|
||||
| prompt 加载失败（缺 id/version） | 回退**内置默认 prompt** + 告警，不中断生成 |
|
||||
| LLM 不可用 | 退化为确定性 Fallback 生成器（确定性兜底产出，~~模板填充~~措辞已更新，见 ai-generation-pipeline §⓪/§7） |
|
||||
| LLM 不可用 | 退化为确定性 Fallback 生成器（确定性兜底产出，~~模板填充~~措辞已更新，见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md) §5.2） |
|
||||
| Cocos-MCP 工具调用失败 | 降级 Tier1 路径（~~OpenGame~~ 已退役）；MVP Tier2/3 仅探针 |
|
||||
| eval CI 跑不通（LLM 限流） | 标记 skip + 人工兜底审，不阻塞紧急修复 |
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
> 蒸馏来源：`docs/architecture/架构/README.md`（§3.4 Game SDK / §4.2 运行时三容器 / §6.6 运行时与导出选型）、`docs/architecture/架构/13模块.md`（runtime 模块 T-RT-* 技术功能）、`docs/architecture/架构/README.md`（§2 模块地图 / §10.4 LayaAir CLI）。
|
||||
> 适用：开发/调试 runtime 模块、WanxiangGameSDK、多渠道（微信/抖音/快手）小游戏导出。
|
||||
> 配套：SDK 降级铁律与沙箱安全红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；工程规范见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；架构全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；上游生成见 [`./ai-generation-pipeline.md`](./ai-generation-pipeline.md)；契约见 [`./contract-first-development.md`](./contract-first-development.md)。
|
||||
> 配套：SDK 降级铁律与沙箱安全红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；工程规范见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；架构全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；上游生成见 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md)；契约见 [`./contract-first-development.md`](./contract-first-development.md)。
|
||||
> **⚠️ 状态升级（2026-06-12 终裁，取代 2026-06-11 待 spike 表述）**：本手册「自研 Canvas Runtime(<15KB)」相关段落=**1.x 历史口径，渲染层已改判**。现行裁决：
|
||||
> - **Tier1 渲染层 = LittleJS 增强发行版 + Runner v2**（2026-06-12 创始人终裁，spike 85/82；Phaser 竞标落选）；「自研轻量 Canvas Runtime / <15KB 体积门」废除（15KB 系 srcdoc 内联架构衍生约束，前提已失效），改三层约束框架（SLO@千元机+4G P75 / B1 gz≤350KB·raw≤1.5MB / 工程增强层）。
|
||||
> - **模板 = LittleJS 能力插件/二次开发件**（玩法模板层废除）；粒子/物理/后处理三插件=引擎能力包装层（裁决①2026-06-12），collision/手感=引擎缺件维持自研。
|
||||
|
||||
@ -51,7 +51,7 @@ graph LR
|
||||
| 4 | **验证门禁前置 / fail-fast** | TDD + 7 门禁 + 完成前验证（evidence），早拦错 | **返工是头号效率杀手**，越早拦越省 | [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md) |
|
||||
| 5 | **并行边界 = 模块边界** | Agent 间零共享状态、worktree 隔离、只经契约交互 | 无写冲突 / 无串扰才能稳定并行 | 本篇 §1 |
|
||||
| 6 | **`.agents` 复利沉淀** | 每个 Agent 交付后回写事实/红线/套路 | 知识不重置，后人站在前人肩上 | [`../README.md`](../README.md) 维护规则 |
|
||||
| 7 | **昂贵步骤缓存** | 相同 Prompt hash 命中跳过 LLM 生成；Maven/构建缓存；产物缓存 | 运行期 + 构建期双重提速、省成本 | [`../skills/ai-generation-pipeline.md`](../skills/ai-generation-pipeline.md) |
|
||||
| 7 | **昂贵步骤缓存** | 相同 Prompt hash 命中跳过 LLM 生成；Maven/构建缓存；产物缓存 | 运行期 + 构建期双重提速、省成本 | [`../skills/saa-graph-orchestration.md`](../skills/saa-graph-orchestration.md) |
|
||||
| 8 | **可复现编排** | 用 Workflow 脚本固化"按模块 fan-out + 逐个 verify" | 编排可重跑、可审计、可断点续跑 | 本篇 §6 |
|
||||
|
||||
---
|
||||
|
||||
52
AGENTS.md
52
AGENTS.md
@ -47,7 +47,7 @@ MVP 目标:交付一条 **种子用户可试用的全链路闭环** —— creat
|
||||
|
||||
### 3.1 三个业务代码库(目前是本 monorepo 的子目录;后续拆为独立仓)
|
||||
|
||||
> **状态(2026-06-11):** 三个代码库都 **在本仓** 内,即 `game-cloud/`、`game-admin/`、`game-studio/`(monorepo 先行、后续再拆 —— 见 memory `monorepo-first-split-later`)。下表的技术栈列是蓝图级。**游戏生成现行是两条并存的线**(详见 `.agents/knowledge/tech-decisions.md` §1.1/§4 与 `docs/architecture/架构/生成引擎/`):一条是 **Tier0/1 廉价线** —— 便宜模型经 new-api gateway 由 SAA(Spring AI Alibaba)裸图编排,产物落在 LittleJS 增强发行版上,过九门兜底(早先的"模板驱动 / 填参式"路线已随 W-CLEAN 退役,改为 agent 写码;创始人 2026-06-20 进一步把终态定调为可维护的 `src/` 多文件源工程,当前的 gameDefinition 中间表示只是通往 src/ 的脚手架);另一条是 **tier2 富游戏线** —— 一个自治 ReAct agent 用 AgentScope(Python·独立 service)造现有廉价线做不出的多系统富游戏,产物是真 Phaser 源工程,**现状=待 0号 spike 验证、尚未落代码**。Dify/OpenGame 降为长期增强且从未部署,RocketMQ/Nacos 是 future-state、MVP 不部署 —— 这四者均不在 MVP runtime 中。
|
||||
> **状态:** 三个代码库都 **在本仓** 内(`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`](.agents/knowledge/tech-decisions.md) §1.1/§4 与 `docs/architecture/架构/生成引擎/`;演进史见 git。
|
||||
|
||||
| 代码库 | 角色 | 技术栈 |
|
||||
|---|---|---|
|
||||
@ -89,7 +89,7 @@ games-development-ai/
|
||||
- 各子系统的当前架构 → `docs/architecture/` 对应域(2026-06-20 改根;生成引擎子树 🚧 架构演进中);`docs/agent-specs/` 降为留痕 + 生成域演进设计链
|
||||
- 可复用能力 / 规则 / playbook → `.agents/`
|
||||
- **留痕层(放开累积 · 检索,不要线性通读)** —— 前门给出单一检索入口,而非逐文件链接:
|
||||
- 设计 / 任务喂料:`docs/brainstorms/`(WHAT)、`docs/plans/`(HOW),以及 `docs/agent-specs/` 下带日期的 `review/execution/report`
|
||||
- 设计 / 任务喂料:`docs/brainstorms/`(WHAT)、`docs/plans/`(HOW),以及 `docs/agent-specs/` 下带日期的**功能设计文档**(`-设计.md`,取代旧 `review/execution` 双档;见 [`.agents/skills/feature-design-doc.md`](.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/` 才算数。
|
||||
@ -120,51 +120,7 @@ games-development-ai/
|
||||
|
||||
## 5. `.agents/` 目录导航
|
||||
|
||||
`.agents/` 是项目的"Agent 能力中枢",分为四类。维护规则见 [`.agents/README.md`](.agents/README.md)。
|
||||
|
||||
### knowledge/ —— 蒸馏后的事实与蓝图,回答"**它是什么**"
|
||||
|
||||
| 文件 | 一句话 |
|
||||
|---|---|
|
||||
| [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md) | 产品定位、13 个模块及其依赖、三仓 / 三前端架构(蒸馏版) |
|
||||
| [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md) | 技术栈与关键选型理由(Huijing 框架 / 生成两条线 SAA+LittleJS 廉价线与 AgentScope+Phaser 富游戏线 / Cocos 退 3D·渠道导出轴 / Prompt 治理 等) |
|
||||
| [`.agents/knowledge/mvp-scope-and-milestones.md`](.agents/knowledge/mvp-scope-and-milestones.md) | MVP 的 55 个 P0 产品功能范围、里程碑与验收指标 |
|
||||
| [`.agents/knowledge/glossary.md`](.agents/knowledge/glossary.md) | 术语表(game feed / GameConfig / Manifest / quality score 等) |
|
||||
|
||||
### rules/ —— 硬约束,回答"**它必须怎样**"
|
||||
|
||||
| 文件 | 一句话 |
|
||||
|---|---|
|
||||
| [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) | 命名 / 分层 / API 路径 / 错误码 / commit / PR 规范 |
|
||||
| [`.agents/rules/security-and-reliability.md`](.agents/rules/security-and-reliability.md) | 安全基线、幂等、超时与重试、合规与可靠性约束 |
|
||||
|
||||
### skills/ —— 可复用的 playbook,回答"**如何做某一类事**"
|
||||
|
||||
| 文件 | 一句话 |
|
||||
|---|---|
|
||||
| [`.agents/skills/add-business-module.md`](.agents/skills/add-business-module.md) | 新增一个 game-module 业务模块的标准步骤 |
|
||||
| [`.agents/skills/add-game-template.md`](.agents/skills/add-game-template.md) | 新玩法模板上线配方(contract→prompt→runtime→backend→orchestrator→五级验收门) |
|
||||
| [`.agents/skills/ai-generation-pipeline.md`](.agents/skills/ai-generation-pipeline.md) | AI 生成流水线(Dify + OpenGame + aigc 外壳)开发手册 |
|
||||
| [`.agents/skills/cheap-model-game-generation.md`](.agents/skills/cheap-model-game-generation.md) | 便宜模型造游戏(W-G1):worker loop · 九门真玩 harness · design-agent 自产 gatespec · 成本 / 模型选择 · 5 个坑(HJ-GEN-001 已验证) |
|
||||
| [`.agents/skills/agentic-amodel-generation.md`](.agents/skills/agentic-amodel-generation.md) | **agentic A-model 生成 harness(ReAct+M3 已实证·生产形态)**:scaffold→工具循环(read/write/list/check/build/done)→循环外 play;5 文件 + 运行配方 + 8 坑(write 前缀/compaction/停机纪律/防假绿/bundle.tick/boot envelope/路径深度)+ M3 3-玩法自闭环实证;取代旧 gamedef 单次产线(HJ-AGI-003) |
|
||||
| [`.agents/skills/saa-graph-orchestration.md`](.agents/skills/saa-graph-orchestration.md) | SAA 裸 StateGraph 生成编排:拓扑 / 加节点 / new-api(剥 /v1)/ checkpoint(含 saved_at 无 tiebreaker 的框架坑 + 显式 checkPointId 修法)/ 观测 / 最小依赖集 / dispatcher 契约 / 门(HJ-AGI-002 已验证) |
|
||||
| [`.agents/skills/prompt-governance.md`](.agents/skills/prompt-governance.md) | Prompt 作为第 8 契约:Registry / 加载-注入 / eval 门 / HITL 治理 |
|
||||
| [`.agents/skills/littlejs-game-dev.md`](.agents/skills/littlejs-game-dev.md) | **AI 直接写 LittleJS 游戏代码作业手册(code 层)**:12 插件 API 速查(8 基元 + 4 编排=session-score/hud-ui/scene-fsm/timer-scheduler)+ 可导航代码结构 + 写 WHAT 调 HOW 边界 + 资产/mmx 流 + 工厂五法契约 + 受控面铁律(终态产物=src/ 多文件工程,取代废弃的 gameDefinition JSON 投影线) |
|
||||
| [`.agents/skills/sim-business-game-design.md`](.agents/skills/sim-business-game-design.md) | **经营模拟小游戏玩法设计作业手册(给 SAA design 层)**:放置/经营/养成爆款范式(玩法/机制/进度/数值/美术/UI/音)→ 映射 A-model 12 插件可达子集 + design 层输出配方 + 反"无趣"8 条自检;与 littlejs-game-dev(code 层)配对 |
|
||||
| [`.agents/skills/runtime-and-multichannel.md`](.agents/skills/runtime-and-multichannel.md) | Runtime 打包、沙箱、SDK 与多渠道导出手册 |
|
||||
| [`.agents/skills/contract-first-development.md`](.agents/skills/contract-first-development.md) | Contract-first:对齐 API/DB/SDK/event 契约并解耦并行工作 |
|
||||
| [`.agents/skills/wave-close-checklist.md`](.agents/skills/wave-close-checklist.md) | Wave 收口 8 步清单 —— 所有收口铁律指向的那份唯一可执行清单(第 8 步 = spec 退役/分层 + _index 维护) |
|
||||
| [`.agents/skills/staging-ops.md`](.agents/skills/staging-ops.md) | Staging 运维配方:机器角色 / 代码同步 / 后端重部署 / 构建门 / smoke 门 |
|
||||
| [`.agents/skills/ui-walkthrough-cdp.md`](.agents/skills/ui-walkthrough-cdp.md) | 在 mini-desktop 上经 CDP 做真 UI 走查(studio/admin)+ bridge 探针 |
|
||||
| [`.agents/skills/game-e2e-cdp-harness.md`](.agents/skills/game-e2e-cdp-harness.md) | Canvas 游戏 e2e 证据 harness:编排形态 / driver 六规则 / ship 红线 / 四件套证据(T1b-α 已验证,W-G1 复用) |
|
||||
| [`.agents/skills/doc-organizer.md`](.agents/skills/doc-organizer.md) | 文档整理助手（手动触发）：增量(上次清理→现在)·两阶段审批门——发起分析 Workflow→编清理计划→评审→创始人批准后才执行；三轴=过期档清理/核心设计档措辞对齐现行真相/主任务总账回填；配 `.agents/tools/doc-organizer.{sh,-analyze.mjs,-state.json}` |
|
||||
|
||||
### workflows/ —— 元流程,回答"**如何承接一项任务**"
|
||||
|
||||
| 文件 | 一句话 |
|
||||
|---|---|
|
||||
| [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md) | 完整 protocol:承接任务 → 分析 → 评审 → 执行 → 验证 → 蒸馏 |
|
||||
| [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md) | MVP 10-Agent × 3 周执行编排 + 8 条复利效率策略 |
|
||||
`.agents/` 是项目的"Agent 能力中枢",分四类 —— **knowledge**(是什么) / **rules**(必须怎样) / **skills**(怎么做) / **workflows**(如何承接任务)。**完整资产清单与一句话说明 = 单一事实源 [`.agents/README.md`](.agents/README.md)**(本入口只给分类、不重复清单,避免双维护漂移);维护规则同见该 README。
|
||||
|
||||
---
|
||||
|
||||
@ -173,7 +129,7 @@ games-development-ai/
|
||||
以下是浓缩条款;完整流程见 [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md)。
|
||||
|
||||
1. **先读再动**:对任何有真实复杂度的任务,先读 [`.agents/knowledge/`](.agents/knowledge/) 及相关 `docs/`,对齐事实,再开工。
|
||||
2. **复杂 / 高风险工作先评审**:跨模块、改变用户可见行为、或触及外部服务 / 支付 / 数据的任务,必须走 **评审版 → 两轮评审 → 再执行**;不要直接写代码。
|
||||
2. **复杂 / 高风险工作先评审**:跨模块、改变用户可见行为、或触及外部服务 / 支付 / 数据的任务,先产**一份功能设计文档**(意图 / 目标 / 边界 / 验证 + 方案 / 步骤,见 [`.agents/skills/feature-design-doc.md`](.agents/skills/feature-design-doc.md))→ 评审 → 再执行;不要直接写代码。
|
||||
3. **证据规则**:区分"已验证事实 / 推断 / 假设"。**没有验证证据,绝不宣称"完成 / 修好 / 通过 / 无问题"。** 任何可运行的东西(测试、构建、lint、smoke)都必须跑。
|
||||
4. **最小改动**:只动与当前需求直接相关的代码,复用既有模式,不要随手重构无关的命名 / 目录 / 格式。
|
||||
5. **中文注释**:所有代码都必须带完整的简体中文注释;外部交互、核心实现、错误路径都必须有可追溯的日志。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user