AUDIOGENIC 的设计目标，是根据玩家提供的音乐生成一场具有段落变化的 Boss 战，将音频中的能量、频谱与节拍特征转化为攻击类型、移动方式和战斗压力。早期方案由浏览器提取音频特征，再由模型直接生成行为时间线。实际开发中，节拍误判、弱音段落的特征缺失、模型重复选招和计划时间重叠，会与子弹生成后立即消失、预警范围和伤害范围不一致等运行时问题同时出现，导致调试时难以区分问题来源。为此，我将流程拆成音频分析、音乐原语、行为规划、确定性编译和运行时执行五个环节，让每一层分别处理信号识别、段落表达、战斗安排、技能约束和逐帧执行。
音频
-> 分帧、频谱与节拍分析
-> 段落和音乐原语
-> DeepSeek 生成 PrimitivePlan
-> 本地编译成 BehaviorTimeline
-> 游戏运行时逐帧执行
音频分析
音频通过浏览器的 Web Audio API 解码，随后将多声道数据下混为单声道。直接取声道平均值存在反相抵消的问题：当左右声道接近反相时，下混结果的能量会显著下降，后续分析可能将正常音乐识别为接近静音的信号。当前处理方式是同时计算下混信号与各单声道的能量；如果下混能量低于最强声道的 5%，则改用最强声道。分帧窗口取约 46 毫秒，并向上调整到最近的 2 次幂，帧移为半个窗口。每帧经过 Hann 窗处理后执行 FFT，提取短时能量、低频与高频占比、频谱质心和频谱通量，其中低频范围为 40—250 Hz，高频范围为 2—8 kHz。段落划分结合能量变化、频谱变化和节拍检测结果，为后续行为规划提供时间边界与段落特征。
节拍检测的主要偏差包括半速、双速误判和起拍位置偏移，例如将 128 BPM 识别为 64 或 256 BPM。由于速度误判和起拍偏移会分别影响后续节拍网格的间距与整体位置，我在战斗前加入了十次点击校准：玩家跟随音乐点击，程序根据点击间隔重新比较半速与双速候选，并修正第一拍的位置。这一交互将 tempo candidate 和 downbeat 的参数修正放进准备流程，玩家通过跟拍完成校准，无需手动填写 BPM。
音乐原语
早期行为层直接使用段落能量、频谱和节拍密度，模型可以返回最终的 BehaviorTimeline，但特征与招式之间缺少便于检查的中间表示。例如，某段音乐生成激光后，仅凭高频占比、能量、频谱通量和提示词，很难判断选招依据；更换模型后，映射结果也可能改变。同时，规则模式与模型模式各自维护映射，修改一个招式需要检查两条链路。我因此在音频段落和行为计划之间增加六种音乐原语，用相对固定的分类表达段落特征：
bass-impact表示低频冲击。bright-beam表示高频较强、声音偏亮。flux-break表示频谱变化突然增大。dense-pressure表示节拍和能量持续密集。stable-groove表示节奏相对稳定。climax表示高能量或高张力段落。
每个段落分别计算六种原语的得分，剔除低于 0.48 的结果，再保留得分最高的三个，以限制规划输入的规模。保留过多原语时，模型容易在不同段落中反复找到使用高潮技能的依据，削弱段落间的压力差异。原语与招式采用一对多映射，例如 bass-impact 可以编译为冲锋、震地或近战重击，具体选择取决于段落位置、强度和前后阶段。对于六种原语均未达到阈值的弱音段落，程序根据频谱倾斜、通量、能量和节拍密度补充一个低置信度原语，其强度仍低于正常阈值。这样既能避免行为计划出现空段，也能保留弱信号与强信号的区别，为编译阶段控制战斗压力提供依据。
行为编译
DeepSeek 接收 BPM、起拍位置、总时长、段落特征、节拍网格样本和原语列表，请求经过 Vite 服务端代理，API Key 不进入浏览器，当前输出上限为 2400 tokens，超时时间为 90 秒。模型返回的 PrimitivePlan 描述各步骤的起止时间、原语引用、阶段作用、组合方式、强度和解释，其中阶段作用限定为准备、施压、爆发、换位和恢复，组合方式限定为单招、叠加和高潮组合。进入本地编译器前，计划需要通过字段、枚举、时间范围、原语引用、段落覆盖和步骤重叠检查，以便将格式错误、引用错误和时间安排错误与后续技能配置问题分开处理。
本地编译器目前包含八种移动方式和十三种攻击方式，负责选取具体技能，并补齐子弹数量、速度、开火间隔、预警强度和压力等级。编译阶段同时处理音乐强度与技能组合之间的约束：低能量段落即使被模型标为高潮，也不会直接配置高压组合技；近战攻击缺少追击或快速位移时，需要调整移动方式，避免攻击选择与接近目标的能力脱节。针对模型连续选用同一招式的问题，编译后还会检查主攻击序列，连续三段相同时替换后续动作，减少单一音频特征持续主导选招的情况。
规则模式同样先构造 PrimitivePlan，经由同一个编译器生成 BehaviorTimeline，与模型模式共用运行时。模型返回非法 JSON、时间线存在缺口或请求失败时，由规则计划接替生成流程。当前管线已能运行，各层职责仍可继续细化；这一划分对开发最直接的作用，是将音频特征、段落安排、技能数值和战斗反馈分别对应到分析、规划、编译和运行时，调试时可以沿中间结果逐层检查。音乐驱动的战斗因此有了可追查的生成过程，也为后续调整段落压力和招式组合提供了明确的修改位置。