企业官网建设流程全解析

• 桌面应用

本文整理docs/migration/bongo-cat-mver-frame-rate-semantics.md记录的帧率语义对照结论，面向 BongoCat（跨平台桌面宠物应用）的开发者与对该项目迁移决策感兴趣的技术读者。文章回答两个核心问题：帧率限制应该在哪里生效，以及模型动画应该如何消费时间；并完整呈现参考实现的行为事实、本产品 Rust 侧的对等实现，以及三处明确不采纳的细节与理由。

这篇指南以 BongoCat 仓库中已冻结的参考基线（docs/migration/bongo-cat-mver-reference.md固定的Bongo-Cat-Mvertagv1.6.0，即 commit4da0b9468ad3b6ffaa096eba3f080501d6ab0b5c）为依据，逐项核对「最大帧率」在参考实现中的配置位置、节流算法与动画时间源，并对照本产品bongocat-runtime的FramePacer实现。读完你将掌握：SFML 帧预算睡眠补差与 deadline 锚定等待的本质差异、动画时间与帧率彻底解耦的机制，以及为什么「给动画单帧步长设上限」这条看似自然的优化在 BongoCat 中被明确否决。

1. 文档定位：帧率一项上的冻结对照

这份帧率语义文档不是独立的研究，而是docs/migration/bongo-cat-mver-reference.md在「帧率与动画时间」维度上的展开。它的状态明确写着：参考实现的帧率语义已冻结；对照后 1 项采纳（overlay.maximum_fps契约补值域与语义）、3 项明确不采纳，记录日期为 2026-09-23。

三个关键约束贯穿全文：

• 固定 commit：所有行为结论都针对Bongo-Cat-Mver的 tagv1.6.0= commit4da0b9468ad3b6ffaa096eba3f080501d6ab0b5c，外加其上游依赖SFML 2.5.1与CubismNativeSamples。后续考古必须先确认所观察源码的 commit，不能用浮动默认分支覆盖基线。
• 只读对照：文档记录的是参考实现的行为事实，不授权复制、翻译或重新许可其源码，所有引用均为只读对照，也不改动任何产品行为。
• 关键行为不在 Mver 自己的代码里：Mver 没有手写任何节流循环，节流语义完全由 SFML 的窗口层决定，所以必须引用上游代码才能说明问题。

2. 参考实现的配置与应用点

Bongo-Cat-Mver对「最大帧率」的完整链路可以压缩成一张表：

注意 UI 的输入约束：MaxLength=3允许填1（此时动作几乎不动），LostFocus时把空值写回0——这构成只挡上界、不挡下界的输入过滤，是本产品决定把下限提到15的直接参照（见第 5.1 节）。

还有一个容易被误解的点需要澄清：

0是合法的第三态：SFML 把它折叠成「无限制」，不是「每秒 0 帧」。

3. 节流语义：睡眠补足帧预算的余额

SFML 的setFramerateLimit只负责记录每帧预算，真正的等待发生在每次呈现（display()）时：

// SFML 2.5.1 src/SFML/Window/Window.cpp void Window::setFramerateLimit(unsigned int limit) { if (limit > 0) m_frameTimeLimit = seconds(1.f / limit); else m_frameTimeLimit = Time::Zero; // 0 = 不限制 } void Window::display() { if (setActive()) m_context->display(); // 交换缓冲、呈现 if (m_frameTimeLimit != Time::Zero) { sleep(m_frameTimeLimit - m_clock.getElapsedTime()); m_clock.restart(); } }

决定成败的是m_clock何时重启：它在上一次display()的末尾重启（另一次在initialize()）。所以下一次读到getElapsedTime()时，它恰好等于本帧已经花掉的时间——睡眠只补差额，因此：

呈现间隔恒等于1/limit，而不是1/limit + 工作耗时。

Mver 的循环顺序也支持这一点：clearCatWindow()→drawCat()（含模型求值）→window.display()（src/main.cpp:241、:262）。模型求值的时间已经计入m_clock，睡眠只补齐剩余部分。

超预算时不会雪崩也不会补帧，因为sf::sleep对非正时长直接返回：

// SFML 2.5.1 src/SFML/System/Sleep.cpp void sleep(Time duration) { if (duration >= Time::Zero) priv::sleepImpl(duration); }

即：工作耗时超过一帧预算时不睡、不追赶、不突发补帧，呈现节奏退化为「能跑多快跑多快」。

与本产品的对应关系：这正是bongocat_runtime::FramePacer（截止时间网格、超时重锚不补发）的同一套语义，差别只在锚点——SFML 存的是「相对上次呈现的余额」，FramePacer存的是绝对deadline；两者稳态周期一致。

4. 动画时间源：与帧率彻底解耦

帧率限制只决定采样密度，动画进度由模型自己的时间源决定。Mver 每帧在 Live2D 模式的draw()开头更新一次时间：

// BongoCatMver/src/mode/mode98_live2d_standard.cpp:231 LAppPal::UpdateTime();

模型随后读取它：

// BongoCatMver/src/myUserModel.cpp:368 const csmFloat32 deltaTimeSeconds = LAppPal::GetDeltaTime(); _userTimeSeconds += deltaTimeSeconds; _dragManager->Update(deltaTimeSeconds); // 之后交给 Cubism 的 motion/expression manager

LAppPal来自官方 sample，用高精度性能计数器求两次计数的差，保存绝对时间戳而不是累加：

// CubismNativeSamples Samples/D3D11/Demo/proj.d3d11.cmake/src/LAppPal.cpp void LAppPal::UpdateTime() { if (s_frequency.QuadPart == 0) { StartTimer(); QueryPerformanceCounter(&s_lastFrame); s_deltaTime = 0.0f; return; } LARGE_INTEGER current; QueryPerformanceCounter(&current); const LONGLONG BASIS = 1000000; LONGLONG dwTime = ((current.QuadPart - s_lastFrame.QuadPart) * BASIS / s_frequency.QuadPart); s_deltaTime = (double)dwTime / (double)BASIS; s_lastFrame = current; }

由此得到一个关键推论：

60 FPS 与 30 FPS 下，同一墙钟时刻的模型姿态完全一致：帧率只改变采样密度，不改变动作进度。

需要注意它没有任何步长上限——这正是第 5.2 节讨论「是否给单帧步长设上限」的前提。

非 Live2D 模式则根本不是时间动画：mode 1/2的手/键盘贴图由按键状态直接选择，sf::Clock（catfunc.cpp:286）只作为「哪个键最新按下」的排序时间戳（catfunc.cpp:245的max_time()）。所以两类模式都不存在「帧率改变动作速度」的可能。

5. 与本产品的逐项对照

文档给出了参考实现与本产品（2026-09-24 修复后）的完整对照表：

6. 本产品侧的实现：deadline 锚定的 FramePacer

对照表中的「本产品」一侧可以在仓库源码中逐一印证。核心实现在 crates/bongocat-runtime/src/pacing.rs，模块注释开门见山：

Pacing is deadline-anchored rather than sleep-after-work: waiting one interval after a frame finishes makes the achieved cadenceinterval + work……

FramePacer维护一个固定间隔的 deadline 网格（pacing.rs）：

• wait(now, interval)返回deadline.saturating_duration_since(now)，一个已经到期的帧可以完全不等待；如果interval发生变化（maximum_fps改动或 overlay 隐藏降频），会先重锚网格再量等待，新节奏无需重启即可生效。
• frame_produced(now, interval)记录帧产出并推进网格：提前产出的帧不消耗槽位（等待保持不变）；超时过度的槽位重锚而不是突发补帧。

值域边界定义在 crates/bongocat-runtime/src/lib.rs：

pub const DEFAULT_MAXIMUM_FPS: u16 = 60; pub const MINIMUM_FPS: u16 = 15; pub const MAXIMUM_FPS: u16 = 240; pub const HIDDEN_OVERLAY_FRAME_INTERVAL: Duration = Duration::from_millis(100); pub const fn maximum_fps_is_valid(maximum_fps: u16) -> bool { maximum_fps >= MINIMUM_FPS && maximum_fps <= MAXIMUM_FPS }

runtime worker 是三个节流点之一（crates/bongocat-runtime/src/worker/mod.rs）：循环用FramePacer::new(...)初始化，随后以receiver.recv_timeout(frame_pacer.wait(Instant::now(), frame_interval))等待，注释明确写道「The wait is measured against the frame deadline rather than started once the previous frame finished, so evaluation keeps the configuredmaximum_fpsinstead of drifting one frame cost lower every frame」。SetMaximumFps命令在 worker/mod.rs 处先经maximum_fps_is_valid校验，非法值返回RuntimeRenderErrorCode::MaximumFpsInvalid并保留旧值；产品 frame source 侧的 pacer 接线在 crates/bongocat-app/src/main.rs。

配置契约侧，overlay.maximum_fps的值域与语义已经写入 shared/config/contract.md：

overlay.maximum_fps是15..=240的 overlay 目标帧率。它决定 runtime 周期求值、GPUI 产品 frame source 与独立 overlay run loop 的下一帧间隔，间隔按帧截止时间计算（单帧工作耗时由等待吸收），因此只要单帧工作能在间隔内完成，实际帧率就等于设置值；overlay 隐藏时三者统一降到100 ms。它不是硬上限：输入边沿可以提前触发一次求值以压低输入延迟，这类帧不消耗周期槽位，被呈现的帧率仍由 frame source 的节拍决定……越界值在 typed command 与配置校验两处都被拒绝并保留旧值。

对应 schema 的schemars(range(min = 15, max = 240))注解在 crates/bongocat-config/src/config_schema/overlay.rs。

动画时间源的「可测试」体现在哪：MonotonicClocktrait（pacing.rs）允许注入手动时钟。回归测试用clock.set(...)驱动大步长（如Duration::from_secs(2)、Duration::from_secs(10)）验证一次性 motion 完成语义，见 crates/bongocat-runtime/src/tests/motions.rs。

「量帧率必须量两次 present 的间隔」的落地：runtime_worker_frame_pacing_reaches_the_configured_maximum_fps测试（crates/bongocat-runtime/src/tests/pacing.rs）以「发布帧数 / 时间窗」计算达成帧率，并在注释中记录了关键历史数据——引入FramePacer之前，60 FPS 默认值下该测试量到48.6 FPS的漂移（因为旧的「每帧完成后睡一整帧」会让达成节奏变成interval + work）。

7. 明确不采纳的三项决定

7.10 = 不限制与只挡上界的输入过滤

0是第三态，需要FramePacer能表达「无上限」（等待恒为 0）。本产品目前是15..=240闭区间，且参考实现的 UI 只挡上界（MaxLength=3允许填1，动作几乎不动）——因此本产品把下限 15视为更合理的取值。是否引入「不限制」属于产品能力取舍，未确认前不新增。

7.2 动画时间的单帧步长上限（评估后决定不加）

两边的动画时间都是「绝对时间戳求差」，因此一次长间隔——系统睡眠、应用挂起、或模型窗口隐藏一段时间后重新显示——会作为一个巨大的步长到达。其后果是可预测的：

• 一次性 motion 直接进入 completed 并固定在包含自然 fade 权重的完整终点样本；
• expression 淡出瞬间结束；
• motion UserData 跨过的每个时间戳仍按有效播放模式发出（只有单次有界批次超过上限时才跳过并计入skipped_occurrences）。

一个自然的想法是给单帧步长设上限（例如100 ms），让动画「接着演」。不采纳的具体阻塞：

这会与 Technical Design 已冻结的契约冲突。该契约要求淡入淡出按「从过渡起点起算的绝对经过时间」求值，使同一时间点在任何帧率下得到同一个 alpha；把动画时间轴改成按上限推进的累加时间后，同一墙钟时刻的 alpha 会随是否发生过卡顿而不同，而且 1 s 的 clip 在卡顿时会播超过 1 s。

代价可测：bongocat-runtime的回归用clock.set(...)的大步长驱动动画到达某个时刻——from_secs(2)与from_secs(10)两次一次性 motion 完成、1 s 淡出用 1.5 s 跳步完成，另有 6 处在 400–1000 ms 之间取中间帧（crates/bongocat-runtime/src/tests/motions.rs）。改为按上限推进后，这些用例必须全部重写成多步序列，否则断言会失去原意。

当前行为不是缺陷，而是该契约的推论：一个巨大的步长意味着「那一瞬间动画就是处于终点状态」。一次性 motion 因此直接进入 completed，并在后续每帧默认值恢复后继续应用其终点参数、part opacity 与 model opacity；它不是被「跳过」，也不会被清回 idle。显式 stop fade 同样可以在一次大步长内完成。文档记录的是评估后维持绝对时间语义。

触发重新评估的条件（满足任一再评估）：出现可复现的用户可见跳变（需要实机证据，而非推断）；或产品显式要求「隐藏期间动画时间不流逝」。届时的取法是只钳制 step、同时把「同一时间点同一 alpha」这条契约改成「同一动画时间点同一 alpha」——文档明确指出，这两者不能同时成立。

7.3 其它不照抄的实现细节

• 自测 FPS 是错的：FPStimeer.restart()在循环顶部（src/main.cpp:95），读数在src/main.cpp:246，而节流睡眠在src/main.cpp:262的window.display()里——测量窗口把要量的那件事排除在外，量到的是「工作耗时的倒数」（工作 1 ms 就显示约 1000 FPS）。量帧率必须量两次 present 的间隔。本产品的回归用「发布帧数 / 时间窗」，是对的。
• 忙等：while (!data::init());（src/main.cpp启动处）在配置读取失败时空转。
• 设置只走重载路径：UI 保存 →PostMessage(UIWM_WRITECONFIG)→ 重读配置 →setWindow()才重新应用帧率；本产品的 typed command 更强（实时生效、带 revision CAS），不采纳这种「设了但要等重载」的路径。

8. 采纳结果汇总

• 本轮已采纳：maximum_fps的配置契约补上值域与语义说明（shared/config/contract.md），对齐参考实现「把帧率的含义与代价写进随产品发布的配置文档」这一做法。
• 上一轮已等价：差额睡眠 / 超时不追赶 / 单一节流语义 / 动画用绝对时间差，见bongocat_runtime::FramePacer（crates/bongocat-runtime/src/pacing.rs）。

9. 继续深入阅读

• docs/migration/bongo-cat-mver-frame-rate-semantics.md：本文的直接依据，帧率语义与不采纳项的完整记录。
• docs/migration/bongo-cat-mver-reference.md：帧率文档所依附的基线文档，规定固定 commit、优先查阅入口与使用规则。
• docs/technical-design.md：「同一时间点同一 alpha」等已冻结契约的架构事实来源。
• crates/bongocat-runtime/src/pacing.rs：FramePacer与MonotonicClock实现。
• crates/bongocat-runtime/src/tests/pacing.rs：帧率达成与预算诊断的回归测试。
• shared/config/contract.md：overlay.maximum_fps采纳后的配置契约原文。

一句话总结本文的实践价值：「帧率限制放在呈现环节、按截止时间补差；动画进度由独立的绝对时间戳驱动」——这套语义在参考实现与本产品之间已经对齐，且每一项取舍都有可执行的回归测试与明确的配置契约背书，后续任何想改动它的提案都必须先回答文档第 5.2 节列出的两个触发条件。

• 桌面应用