# YuE2 中央调度收编批（GpuScheduler + UGQ 双面）

## 背景（operator 已实地侦察，直接采信；不符处走「工单纠错」节）

- 目标引擎 = YuE2 音乐生成，现役形态：**旁路常驻容器** `comfyui-yue2-probe`（:8195→8188，UUID 钉死 GPU1=`GPU-c5cdd49c-5a18-7d0b-2af5-1d2f642538c6`，restart=no，~7.6G 显存，Up 18h）。
- KAP 路由族 `src/routes/production/yue2/index.ts`（HEAD 1c4e7bcc）：五端点，**只提交不长轮询**（history 轮询归调用方），engineAdmission 已覆盖 yue2（本批禁动）。
- 现状两个「没进」：① GpuScheduler（src/services/gpu/GpuScheduler.ts）无 yue2 profile；② UGQ 无 yue2（不在 ENGINE_VRAM_REQUIREMENTS，路由无 dispatchEngine）。
- Kai 令（2026-10-14）：**两面都收编**。
- 参考先例：GpuScheduler profile = ming-image（commit 22cb83a6，latest main 8c42e09c）；UGQ dispatchEngine = minimax-h3/generate.ts:1985（queueWaitMs 补偿 + onRedirect + callerTag 全套）；**反面模板 = music3/generate.ts 的 withGpuQueue（legacy 直派不进 UGQ pending，禁模仿）**。
- 本仓分支纪律：worktree `/data/workspace/wt-yue2-scheduler`（分支 wt/yue2-scheduler-adoption，已建好，node_modules 已 symlink 主仓）。改动全在此 worktree 提交。

## C1 — GpuScheduler 收编（服务级）

1. 注册 profile `yue2-music`，逐字段对照 ming-image 先例：
   - gpuId: 1（静态兜底=现役卡）；gpuRole: "yue2" + **live /opt/kais-gpu/gpu.conf 增行 `yue2_role=RENDER_GEN1`**（现役真值=GPU1；/opt 非 git 仓，报告里记录 diff）。
   - vramEstMb: 实测值（`docker stats --no-stream comfyui-yue2-probe` + nvidia-smi per-process 交叉；docstring 参考 ~7.6G=7680，以实测为准四舍五入到 128 倍数）。
   - priority: 1（渲染族，与 tts/ming 同级）；category: "comfyui"（既有枚举免扩 union，wemm/ming 同款手法）。
   - start/stop: `{ type: "docker-start" / "docker-stop", containerName: "comfyui-yue2-probe" }`（comfyui-primary 同款，**不需要自写 bash 脚本**——容器已是标准 ComfyUI 容器）。
   - healthUrl: `http://127.0.0.1:8195/system_stats`（ComfyUI 标准健康面）；healthTimeoutMs 按族惯例；idleTimeoutMs: 0（**保持常驻语义=现状零行为变化**，懒加载由容器自管）。
2. 注册表 id 全集 N→N+1：机械更新 gpuSchedulerProfiles.test.ts / gpuSchedulerRoles.test.ts（先例惯例，断言注释即编年史）。

## C2 — UGQ 收编（作业级）

1. `src/lib/gpuVramManager.ts` ENGINE_VRAM_REQUIREMENTS 增 `yue2`（=C1 实测同源值）。
2. **YuE2 是单容器引擎（仅 :8195 一实例，无对臂）→ 按 music3/rtx_vsr 同类处置：进 UGQ 但钉死单卡**。机制读 gpuVramManager §UGQ 节实码（`KAP_UGQ_PINNED_ENGINES` env 或 opts 等价形态，以仓内实现为准）；**禁做 onRedirect 双臂补投**（无对臂可投）。
3. 路由三个提交路径（/generate、/abc、/transcribe）锁入口迁 `dispatchEngine("yue2", fn, opts)`：
   - fn = 探针 /prompt 提交段（现有 axios {proxy:false} 逻辑原样内移）；**响应契约逐字节不变**（{promptId, statusUrl, license} / transcribe 同理）——既有 yue2Route.test.ts / yue2FullApis.test.ts 必须原样全绿，禁改测试断言来适配实现。
   - queueWaitMs：提交型 fn 无长轮询预算可补，但**必须消费该参数**（注释声明「提交型 fn，排队补偿无消费点」），禁未使用变量告警。
   - opts: callerTag 照 minimax-h3 模式接线（readCallerTag 若路由层未有则不引入，保持最小面）；**禁直传 gpuIndex: dispatch.gpuIndex**（UGQ 收编模板第③条）。
   - pinTaskGpu：按 final 卡钉扎（观测面用，status 路由固定 :8195 不受影响，仍按钉扎卡语义写）。
4. 消费端 ensure：三路由探针转发前插 `ensureAllocated("yue2-music")`（wemm/hybridAsr 路由同款；常驻态=fast-path no-op；拒绝→503 allocate-not-granted）。
5. 新增单测：dispatchEngine 接线（mock UGQ 层）、钉死语义、契约不变回归。测试运行器 = `node --import tsx --test src/...`（本仓无 vitest/npm test，禁试）。

## C3 — 文档 + 部署冒烟

1. docs/yue2-engine-integration.md §4「有意不注册」段更新为收编后事实（保留 license 红线段）。
2. 部署（重启用 sudo 时若 NOPASSWD 不可用，写清命令交 operator，禁卡死等待）：重启前三判定（3090 无 compute-apps 作业 + 双 ComfyUI 容器 /queue 空 + journal 近 60min 无 gpuQueue 活动）→ `sudo -n systemctl restart kais-aigc-platform` → **端口绑定验证**：`ss -tlnp | grep 10588` 的 listening PID == systemctl MainPID（不等=旧 user-systemd 实例占端口，kill 后重启再验）。
3. 真机冒烟（全绿才算完）：GET /api/production/yue2/config 含新注册事实 → gpu-queue 端点确认 yue2 进 UGQ 面 → POST /generate（固定 seed，maxDuration 用小值如 5s）→ 轮询 /status/:promptId 到 completed → GpuScheduler services 面含 yue2-music。
4. 交付报告 REPORT.md：C1/C2/C3 逐项 + 验收三件套原文（测试输出/tsc/冒烟）+ 「工单纠错」节（实读与工单不符处）+ 自纠记录。

## 红线

- API 契约零变化；engineAdmission.ts 禁动；既有测试断言禁改；默认行为（常驻、:8195、GPU1）零变化。
- 关闸态（KAP_UGQ_ENABLED=0）行为逐位兼容 = 验收硬门。
- 主仓 /data/workspace/kais-aigc-platform 工作区有他人未提交改动，**禁碰**；一切改动限 worktree，merge 由 operator 验收后执行。
- 不新增 npm 依赖。

## 完成定义

worktree 内 commit 齐全（feat 分主题）+ 全测试绿 + `npm run build:server` tsc 0 + 真机冒烟三件全过 + REPORT.md 落 `/home/kai/shared/2026-10-14/yue2_adoption/REPORT.md`。