菜单
Maps every HOT-Step CPP feature to its route file, service, UI folder, and engine subsystem, including port topology and the browser-to-engine request path. Use when you need to find where a feature or bug lives, which tier owns a symptom, or how a request flows through the system.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Explains how HOT-Step's LoRA/LoKr adapter system loads, merges, caches, stacks, and regionally masks adapters at runtime, including hard-won failure modes. Use when working on adapter loading/merging, multi-adapter stacking, per-section adapter masking, adapter cache keys, cross-base adapter conversion, debugging adapters that sound wrong or silent, or when UI adapter knobs (Adapter VRAM, Alignment Timing, Sum/Blend, trigger words, [Section]{k=v} lyric directives) appear dead or ignored.
Diagnoses HOT-Step CPP generation failures, engine crashes, hangs, and startup problems from the logs/ session folders. Use when a music generation failed, ace-server crashed or keeps respawning, the app hangs with no progress, an API call returns 500/503, or you need to trace a gen_<uuid> log back to engine output.
Guides adding or modifying a feature in the HOT-Step CPP Node/TypeScript server (Express route + service pattern, better-sqlite3 schema changes, engine calls via aceClient, logging, tsx watch dev loop). Use when creating/editing files under server/src/, adding an /api/* endpoint, changing the SQLite schema, adding a config/env setting, wiring a server feature to the C++ engine, or debugging server-side failures (stalled/stuck generation jobs, engine HTTP timeouts, SQLite errors, engine crash-respawn loops).
Runbook for cutting and publishing a HOT-Step CPP release via a v* git tag that triggers the multi-platform CI build and drafts a GitHub Release. Use when asked to cut a release, publish a release, bump the version, push a version tag, run a CI compile test, verify release assets, or debug a failed Release/Cache Warm workflow run.
Explains how model files, checkpoints, GGUF quantization, and the Model Manager work in HOT-Step CPP. Use when adding/converting/quantizing models, debugging "no GGUF models found" or missing-model/wrong-model failures, working on the model download service or Model Manager UI, or answering which component (LM/DiT/VAE/text-encoder) needs which file.
Explains how to write, test, and debug HOT-Step Lua plugins (solvers, schedulers, guidance modes, postprocess) including the apg()/post_step() API and UI param flow. Use when adding or modifying a sampling solver, noise scheduler, CFG/guidance mode, or VAE-decode postprocess plugin, or when a plugin fails to load, has no effect, or produces noise.
| name | project-map |
| description | Maps every HOT-Step CPP feature to its route file, service, UI folder, and engine subsystem, including port topology and the browser-to-engine request path. Use when you need to find where a feature or bug lives, which tier owns a symptom, or how a request flows through the system. |
HOT-Step CPP is a desktop app for local AI music generation (caption + lyrics in, stereo 48 kHz audio out). It is a heavily-extended fork of acestep.cpp, a C++/GGML port of ACE-Step 1.5. Three tiers:
engine/. Pipeline: LM (Qwen3 language model that emits audio_codes) → DiT (Diffusion Transformer, the flow-matching synth stage) → VAE (decodes latents to audio).server/src/. Orchestrates the engine, owns SQLite and files, serves the UI.ui/src/. One component folder per "studio" (feature area)..\dev-rebuild.bat at repo root, NEVER engine\build.cmd directly, under any circumstances. WHY: you cannot reliably tell whether the app is running; the Node server auto-respawns ace-server.exe on crash (server/src/index.ts:284-308); killing the engine mid-run causes an infinite respawn + file-lock loop that blocks the build. dev-rebuild.bat POSTs /api/shutdown, waits for the process (force-kills at 10 s), then builds. It does NOT relaunch — restart with .\dev.bat or .\LAUNCH.bat yourself. Recompile immediately after editing any engine/src/ or engine/tools/ file.cmake --build . --clean-first unless the GGML/CUDA layer itself changed. WHY: CUDA kernel recompilation takes 20+ minutes. For stale .obj issues delete only engine\build\acestep-core.dir\ and engine\build\Release\acestep-core.lib.engine/tools/hot-step-server.cpp, NOT engine/tools/ace-server.cpp. WHY: upstream ace-server.cpp is kept as reference and is NOT compiled — the ace-server binary is built from hot-step-server.cpp (engine/CMakeLists.txt:416-419). Edits to ace-server.cpp silently do nothing.npm run build during dev. Type-check with npx tsc --noEmit (run in server\ and ui\). Only build before user testing.master, no branches. Never git add -A or git add -f (re-adds gitignored .agents/, checkpoints/, node_modules/). Stage explicit paths. Push requires explicit user approval. Commit locally often. Any pushed v* tag triggers a full multi-platform CI release build — use a -CI-Test suffix for throwaway tags.powershell -File engine\verify-hooks.ps1. The pipeline-synth-ops.cpp hook loss is SILENT — it compiles but all solvers/schedulers/guidance go dead.engines field enforces <24).; not && (unless pwsh 7 chaining). Windows 11 environment.LAUNCH.bat (prod) or dev.bat (dev)
└─ Node server server/src/index.ts → Express :3001 (host 0.0.0.0, config.ts:186-187)
├─ serves prebuilt ui/dist/ with SPA fallback (index.ts:123-140)
├─ /api/* routes → SQLite server/data/hotstep.db
├─ /audio → server/data/audio/, /references → server/data/references/ (index.ts:98-121)
└─ spawns child: ace-server.exe (C++ engine) on 127.0.0.1:8085 (config.ts:102-103)
Dev mode adds Vite on :3000 (HMR); vite.config.ts proxies /api, /audio, /references → 127.0.0.1:3001.
tsx watch auto-restarts the Node server on server-code changes.
index.ts:166-213: --models --host --port, plus conditional --adapters, --keep-loaded, --noise-profile, --draft-lm (deliberately disabled by default — config.ts:117-122), --vae-chunk, --vae-overlap, --onnx-dir.index.ts:284-308): abnormal exit → restart after 3 s; ≥3 crashes in 30 s → give up, engine marked not-ready ("check logs for missing DLLs").index.ts:318 onward)..env at repo root, auto-bootstrapped from .env.example (config.ts:20-30). Settings UI can only edit whitelisted EXPOSED_ENV_KEYS (config.ts:265-286); keys in RESTART_REQUIRED_KEYS (config.ts:289-294) never hot-apply; the rest hot-reload via reloadEnvConfig() (config.ts:300).Key term: AceRequest — the JSON request object sent to the engine, typed at server/src/services/aceClient.ts:38-151 (caption/lyrics/bpm/seed, LM sampling params, DiT params like inference_steps/guidance_scale/scheduler, model routing, adapter fields, plugin_params, streaming fields). aceReq in code = the instance of this object for the current job.
ui/src/components/create/CreatePanel.tsx + ui/src/stores/globalParamsStore.ts (Zustand store holding all generation params) → ui/src/services/api.ts (thin fetch wrapper, base /api) → POST /api/generate.server/src/routes/generate.ts (~1550 lines). Jobs live in an in-memory jobs Map (generate.ts:79) with a serial queue. Inside runGeneration (generate.ts:173):
translateParams (services/generation/translateParams.ts) converts UI params → AceRequest.aceClient.submitLm (generate.ts:303); results cached by seed+params in services/generation/lmCache.ts.generate.ts:312-328): server-only fields (adapter_runtime_quant, rebase, plugin_params, …) — the "sideband" = params the Node server adds that are not part of the C++ LM struct — do NOT survive the /lm round trip. Synth requests are rebuilt from the original aceReq plus only the LM-generated fields (audio_codes, caption, lyrics, bpm, duration, keyscale, timesignature). Never whitelist-echo the LM response.generate.ts:449-478, services/generation/sourceAudio.ts, sourceLatentCache.ts).aceClient.submitSynth or submitSynthMultipart when binary latents/audio are attached (generate.ts:823-826).generate.ts:940+, services/whisperTranscribe.ts); auto-trim silence (generate.ts:1057-1094, services/autoTrim.ts).runPostProcessingChain (services/generation/postProcessing.ts:70), fixed order: quality-check(unmastered) → PP-VAE re-encode → Spectral Lifter → Vocal Naturalizer → gain offset → VST chain → Mastering → LUFS normalize → quality-check(mastered) (postProcessing.ts:105-309).services/aceClient.ts wraps every engine endpoint. The engine is single-threaded httplib — during DiT/VAE/adapter compute it cannot answer HTTP at all. Timeouts are deliberately generous: 15 s quick / 30 s poll / 300 s result fetch (aceClient.ts:17-19). A "hung" health check mid-generation is normal.GET /api/generate/status/:id; live log lines via routes/logs.ts (pushLog/subscribeLines, logs.ts:34,49).pollUntilDone (generate.ts:102-140): no progress for 2 min → cancel + fail as stalled; wall-clock timeout clamped 5–120 min, default 45.POST /lm or /synth returns a job id; poll GET /job?id=; fetch result via POST /job. Node job ids ≠ engine job ids (mapped by the aceJobId field, generate.ts:47).Engine HTTP endpoints (engine/tools/hot-step-server.cpp:2704-3535): POST /lm /synth /understand /vae /warm /job /models/unload /pp-vae-reencode /supersep/separate /supersep/recombine /spectral-lifter; GET /health /props /logs /jobs /job /plugins /vram /models/loaded /supersep/progress /supersep/result /supersep/serve / (embedded webui).
API mounts are all registered in server/src/index.ts:72-95. Route files in server/src/routes/, services in server/src/services/, UI folders in ui/src/components/.
| Feature / Studio | API mount | Route file | Key service(s) | UI folder / file | Engine piece |
|---|---|---|---|---|---|
| Create (main generation) | /api/generate | generate.ts | generation/*, aceClient, autoTrim, latentFormat, whisperTranscribe | create/ + global-bar/ | /lm /synth → pipeline-lm.cpp, pipeline-synth*.cpp |
| Insta-Gen (genre-first quick gen) | /api/inspire | inspire.ts | lireek/llmService (LLM lyrics) | insta-gen/ (ui/src/services/inspireApi.ts) | via generate queue |
| Lyric Studio ("Lireek") | /api/lireek | lireek.ts | lireek/{llmService, geniusService, profilerService, prompts, slopDetector, exportService, llm/} | lyric-studio/ (ui/src/services/lireekApi.ts) | none (external LLMs) |
| Song library | /api/songs | songs.ts | audioCrop, disco-analyzer, whisperTranscribe | library/, player/, details/ | — |
| Models dropdown | /api/models | models.ts | aceClient (GET /props) | global-bar/ModelsDropdown.tsx | model-registry.h, model-store.cpp |
| Model Manager (downloads) | /api/model-manager | modelManager.ts | modelDownloadService.ts + server/src/data/model-registry.json | model-manager/ | — |
| Adapters (LoRA/LoKr fine-tunes) | /api/adapters | adapters.ts | generation/adapterSections.ts | create/AdaptersAccordion.tsx, global-bar/AdaptersDropdown.tsx | adapter-merge.h, adapter-runtime.h, adapter-cancel.h |
| Stem Studio (separation) | /api/stem-studio | stemStudio.ts (2 modes: extract = DiT per-track /synth; supersep = ONNX NN, stemStudio.ts:1-8) | aceClient, audioConvert | stem-studio/ (ui/src/services/stemStudioApi.ts) | supersep.cpp, supersep-stft.h; /supersep/* |
| SuperSep raw proxy | /api/supersep | supersep.ts | — | shared/StemMixer.tsx (ui/src/services/supersepApi.ts) | /supersep/* |
| Stem Builder (layering) | uses stem/gen APIs | — | — | stem-builder/ | — |
| Repaint Studio | /api/generate (task_type) | generate.ts | generation/sourceAudio.ts | repaint-studio/ | sampler-repaint.h |
| Song Builder | /api/builder | songBuilder.ts | — | song-builder/ | seed-latent path, generate.ts:470-478 |
| Cover Studio (audio covers) | /api/generate + /api/analyze | generate.ts, analyze.ts | generation/sourceAudio.ts, audioMetadata, disco-analyzer | cover-studio/ | cover fields in request.h |
| Cover Art (images) | /api/cover-art | coverArt.ts | coverArt/{coverArtService, coverArtDownloader, promptBuilder} | library/CoverArtPromptModal.tsx, global-bar/CoverArtDropdown.tsx | external sd-cli (not the music engine) |
| Mastering | /api/mastering | mastering.ts | generation/postProcessing.ts | create/MasteringSection.tsx, global-bar/MasteringDropdown.tsx | mastering.h, tools/mastering.cpp |
| VST3 chain + monitor | /api/vst | vst.ts | spawns vst-host.exe (config.ts:234-250) | global-bar/VstChainDropdown.tsx, ui/src/stores/vstChainStore.ts | tools/vst-host.cpp |
| Lua plugins (solvers etc.) | /api/plugins | plugins.ts | aceClient (GET /plugins) | global-bar/PluginControls.tsx, ui/src/hooks/usePluginRegistry.ts | lua-plugin.h, lua-plugin-registry.h, hot-step-sampler.h |
| Assistant (in-app help chat) | /api/assistant | assistant.ts | server/src/data/assistant-knowledge.md, lireek/llmService | assistant/ (ui/src/services/assistantApi.ts) | — |
| Settings (.env editor) | /api/settings | settings.ts | config.ts reloadEnvConfig | settings/ | — |
| Seeds manager | /api/seeds | seeds.ts | — | global-bar/SeedManagerDrawer.tsx (component name unverified — check global-bar/) | — |
| Uploads (audio/latent/cover) | /api/upload | upload.ts | latentFormat.ts | shared/LatentImport.tsx (unverified) | — |
| Downloads / export | /api/download | download.ts | audioConvert.ts (ffmpeg) | player/, library/ | tools/mp3-codec.cpp |
| Logs / VRAM / terminal | /api/logs (/, /vram, /models-loaded, /models-unload — logs.ts:56-133) | logs.ts | logger.ts | terminal/, shared/VramIndicator.tsx (unverified) | /vram, /models/loaded |
| Health / lifecycle | /api/health, /api/shutdown | health.ts, shutdown.ts | engineState.ts (at server/src/engineState.ts, NOT services/) | — | /health |
| Auth (local single-user) | /api/auth | auth.ts | db/database.ts | — | — |
| Analyze (BPM/key of upload) | /api/analyze | analyze.ts | Essentia binary (config.ts:180-182), audioMetadata | cover-studio/ | /understand (pipeline-understand.cpp) |
UI views (ui/src/App.tsx:99-114): default create, plus insta-gen, lyric-studio, cover-studio, stem-studio, stem-builder, song-builder, repaint, library, settings; overlay panels for assistant and terminal. Zustand stores in ui/src/stores/: globalParamsStore, playbackStore, audioGenQueueStore, streamingStore, vstChainStore, abCompareStore, discoStore.
Engine source map: full per-subsystem table in reference.md. Fast rules: LM phase → engine/src/pipeline-lm.cpp / qwen3-lm.h; DiT synth → pipeline-synth*.cpp / dit.h; all solver/scheduler/guidance routing → hot-step-sampler.h (upstream dit-sampler.h is bypassed); adapters → adapter-merge.h / adapter-runtime.h; VAE → vae.h / vae-ort.h; HTTP server → engine/tools/hot-step-server.cpp.
Plugins: solvers (21) / schedulers (9) / guidance (7) are hot-loadable Lua files in engine/plugins/{solvers,schedulers,guidance}/; the registry also scans repo-root plugins/ as a project overlay (engine/src/lua-plugin-registry.h:35-50), which holds postprocess/ (md_audio_tiled). Drop a .lua in the right subdir → appears in UI next launch, no C++ rebuild. Adding a solver/scheduler/guidance = write a Lua plugin, never edit dit-sampler.h. Guide: docs/PLUGINS.md. Native headers in engine/src/solvers|schedulers|guidance/ are legacy — new work goes in Lua.
server/data/, NOT repo-root data/. DATA_DIR in .env resolves relative to server/ (config.ts:192: path.resolve(__dirname, '..', DATA_DIR)). A stale legacy data/ directory exists at repo root with a plausible-looking but outdated hotstep.db — do not trust it, and do not delete it without asking.server/data/hotstep.db (better-sqlite3). Tables (server/src/db/database.ts:39-191): users, songs, playlists, playlist_songs, artists, lyrics_sets, profiles, generations, settings, album_presets, audio_generations, builder_projects, builder_sections. Lireek tables are unified into hotstep.db (index.ts:20) — config.lireek.dbPath pointing at lireek.db (config.ts:225-227) is vestigial; don't trust it.server/data/): audio/ (outputs), references/ (mastering refs), stems/<jobId>/, vst/{states,chain.json}, lyrics/ (exports). Never delete generated audio outputs or experiment artifacts on your own judgment — the user verifies results by ear; ask first.logs/YYYY-MM-DD_HH-MM-SS/{ace_engine.log, node_console.log, generations/gen_<uuid>_<task>.log}. Newest folder = current session. Generation failure → matching gen_*.log first, then cross-ref the other two..\dev.bat # Dev: Vite :3000 HMR + Node :3001 tsx watch
.\LAUNCH.bat # Prod
.\dev-rebuild.bat # C++ rebuild: graceful shutdown -> wait -> build (then relaunch yourself)
npx tsc --noEmit -p server # Type-check server, from repo root (do NOT npm run build in dev)
npx tsc --noEmit -p ui # Type-check UI, from repo root
# Stale .obj without the 20-min CUDA recompile:
Remove-Item -Recurse -Force engine\build\acestep-core.dir; Remove-Item -Force engine\build\Release\acestep-core.lib
powershell -File engine\verify-hooks.ps1 # After any upstream sync
| Symptom | Cause | Fix / first file |
|---|---|---|
[ace-server] Restarting in 3 seconds... (crash N/3) then giving up | Missing DLL next to ace-server.exe or bad model | logs/<newest>/ace_engine.log; respawn logic index.ts:284-308 |
| Solver/scheduler/guidance UI options silently do nothing | Upstream sync overwrote the hot-step-sampler.h include in engine/src/pipeline-synth-ops.cpp:9. Compiles fine — silent. | Run engine\verify-hooks.ps1; restore the include |
| Compile error in model-store.h / dit.h after sync | Lost hot-step-params.h include (model-store.h:53) or adapter-merge.h+adapter-runtime.h (dit.h:11,13) | Restore includes; verify-hooks.ps1 confirms |
| Generation stuck ~2 min then fails "stalled" | pollUntilDone stall watchdog (generate.ts:107,128) | Check gen_*.log for last engine phase; adapter_precompute ~17 s LoKr cold-start is normal |
/api/health or engine health flaky mid-generation | Engine is single-threaded httplib; can't answer during compute (aceClient.ts:6-8) | Not a bug unless it persists after the job ends |
| Synth params vanish after LM phase (adapter/solver settings ignored) | Sideband fields don't survive the /lm round trip | Rebuild synth req from original aceReq + LM fields only (generate.ts:312-328) |
| Infinite ace-server respawn + file locks during rebuild | You ran engine\build.cmd with the app up | Use .\dev-rebuild.bat |
| npm install fails / weird dep errors | Node 24+ | Use Node 18–22 |
| Vulkan pinned-memory alloc failure in VAE | VAE chunk too large | Tune ACESTEPCPP_VAE_CHUNK / ACESTEPCPP_VAE_OVERLAP in .env |
| First-launch hang "Downloading CUDA runtime" | Portable CUDA DLL bootstrap (index.ts:318+) | Wait or go offline → engine starts CPU-only |
| Accidental CI release build | Pushed a v* tag | Use -CI-Test suffix for throwaways; see docs/RELEASING.md |
ace-server.exe builds from engine/tools/hot-step-server.cpp; upstream ace-server.cpp is uncompiled reference (engine/CMakeLists.txt:416-419).AceRequest fields never survive the /lm round trip; synth requests must be rebuilt from the original request + LM output fields only, never echoed back (generate.ts:312-328).ee041e1. The adapter_section_isolation field still exists in AceRequest (aceClient.ts:97). Do NOT re-attempt without a design that preserves cross-section musical coherence — naive per-section attention masking is known to break continuity.config.ts:117-122): GGML per-call overhead (~10 ms) negates the speedup.--keep-loaded is spawn-time (restart required); flips the engine ModelStore to EVICT_NEVER so the ~17 s LoKr precompute happens once. Separate per-request ?keep_loaded=1 co-resident toggle also exists (config.ts:124-132). Default OFF (VRAM trade-off).lmCache.ts): changing only synth params reuses cached codes; changing seed re-runs the LM.rebase_source/rebase_beta fields exist (aceClient.ts:112-113) implementing β·(S−T) toward the adapter's training base; efficacy unproven. Non-turbo XL bases still fail despite ~99% weight identity (basin sensitivity, not drift). When multiple adapters are stacked, the basin re-base applies once per STACK, never once per adapter (issue #72; regression class fixed in 168dcb5).*.obj, test_trtllm_*, nul) — untracked experiment leftovers. Do NOT delete them without asking; they may be the user's test artifacts.AceRequest field catalogue, data/config details.FEATURES.md — full feature catalogue (100+). engine/docs/ARCHITECTURE.md — engine internals, CLI, request JSON. docs/PLUGINS.md — Lua plugin authoring. docs/RELEASING.md — release runbook. server/src/data/assistant-knowledge.md — in-app assistant KB.docs/plans/ is gitignored (local-only) — internal design/investigation docs (perf, adapters, upstream-sync-workflow.md); may be absent on a fresh clone.