企业官网建设流程全解析

• 桌面应用

导读

docs/migration/legacy-behavior-inventory.md是 BongoCat 从旧版 Tauri + Vue/Ant Design 架构迁移到新版 Rust + GPUI 原生架构时的一份行为迁移基线：它逐条盘点旧版产品能力，把「Windows/macOS 首发必须具备」的行为冻结为P0 首发，把历史缺陷与旧技术细节列为不迁移反例，并用冻结的基线 commit 与修订记录约束实现期范围。读完本文，你将掌握 BongoCat 迁移行为的完整功能矩阵（主窗口、键盘/鼠标/手柄输入、Live2D、模型、快捷键、托盘、更新等 48 项）、P0 与不迁移的判定规则，以及每条行为对应的源码证据、待确认事项与已闭合决策（ADR）的引用链，可直接用于理解当前仓库各模块的能力边界与验收口径。

这份清单是什么：冻结的功能范围与优先级契约

清单是一份静态考古产物：它固定的是基线 commit44f44bc时的旧版行为事实（记录日期 2026-08-28），而不是持续跟随旧分支代码演进的动态文档。文档开篇明确三条规则：

• P0 首发：Windows/macOS 首发必须具备；可以修复旧缺陷，但产品能力不能静默消失。
• 不迁移：只作为行为对照或反例，不进入 BongoCat 产品实现。
• 优先级描述的是产品能力，不承诺复制旧实现。列为P0 首发的行为仍须通过 fixture、平台 contract 或实机验收后才能宣称兼容。

这意味着「P0」只回答「旧版有这个能力、新版必须保留」，而「新版怎么实现」由 ADR、技术设计（technical-design.md）与配置契约另行约束。文档同时规定：历史源码后续变化不自动改变本矩阵，任何范围变化必须显式评审并更新本文件——这正是它作为迁移期「防静默扩缩范围」基准的机制价值。

功能矩阵总览：48 项行为的三级归类

清单以一张领域×行为×优先级×源码结论×待确认的五列矩阵承载全部盘点，按领域覆盖主窗口、窗口状态、主窗口菜单、键盘、鼠标、手柄、Live2D、模型、快捷键、行为快捷键、托盘、系统、权限、设置、更新、外观、错误、诊断、配置与平台。当前统计为P0 首发 40 项 / 不迁移 8 项，合计 48（2026-09-28 修订后不再保留P1 首发后一档，图例与统计表同步收敛）。

主窗口与窗口状态（P0 全部）

矩阵备注了两处由P1 首发后上调为P0 首发的能力（2026-09-16 修订）：主窗口圆角与hover 延迟隐藏。二者上调的原因一致——维护者要求新版同步支持旧版已有的配置项，因此overlay.corner_radius_percent、overlay.hide_on_pointer_hover、overlay.hide_on_pointer_hover_delay_seconds三个字段直接进入当前 v1 schema、默认值、fixture 与实现（见 contract.md 的 Initial Version Boundary 与窗口圆角段落）。同时待确认项随之改写：

• 圆角：旧版通过内容裁剪百分比实现，新版沿用片元着色器按窗口宽高百分比裁剪的路径，不再引入原生窗口形状 API，待确认项由「原生窗口边缘与背景资源一致性」改为「抗锯齿边缘与多层重叠」。
• hover 隐藏：旧版是 DOMopacity加setIgnoreCursorEvents，新版把隐藏实现为窗口 alpha 淡出加临时穿透，待确认项由「多显示器边界与丢失离开事件」改为「实机淡出观感与穿透时序」。

2026-09-24 修订补充了一个关键实现事实：基线44f44bc的src/pages/main/index.vue把window.opacity / 100施加到包含背景、Live2D canvas 和按键图的根容器，而不是分别修改每个 Live2D drawable。因此 BongoCat 将窗口 presentation opacity 定义为最终 surface 的一次性 alpha，平台实现细节仍需实机 readback 验证。对应配置侧，opacity_percent/corner_radius_percent/hide_on_pointer_hover等在应用层经 settings_commands.rs 写入配置、并由 config_projection.rs 投影到设置快照，形成「设置页 → typed command → v1 配置」的完整链路。

窗口状态方面，window-state.json使用独立的schema_version: 1只保存可恢复的 settings 与 overlay 窗口布局：settings_window为空时在鼠标所在显示器居中按800x600打开，overlay_window为空时以350px作为100%默认逻辑宽度、高度按模型 Canvas 宽高比自适应；恢复前会再次检查窗口与当前显示器是否相交，显示器移除或完全离屏时回退居中默认布局。而旧版保存的是物理 x/y/width/height，跨 DPI/显示器恢复需要新规范（见下「配置不迁移」），新版改用逻辑坐标，window-state 契约 即为这一迁移的产物。

主窗口菜单：托盘与右键共用一棵菜单树

旧版行为：打开设置、模型窗口显隐/穿透/置顶/鼠标移入隐藏、可用的检查更新和退出；托盘与模型窗口右键共用同一套菜单。矩阵结论：两个入口复用同一 popup 根和模型窗口分组。

该行为在 ADR-0068 中被固定为「一棵 popup 根、一个 owner」：bongocat-platform::SystemMenu是唯一的托盘/菜单 owner，持有TrayIcon、一个muda::Menu根、一个模型窗口Submenu与强类型SystemMenuAction事件队列。菜单结构为：

设置 ──────── 模型窗口 ├─ □ 隐藏模型窗口 ├─ □ 鼠标穿透 ├─ □ 始终置顶 └─ □ 鼠标悬停时隐藏 ──────── 检查更新（仅在更新能力可用时创建） ──────── 退出 BongoCat

2026-09-25 修订说明：源码、版本、重启以及重复的缩放/透明度选项从原生菜单移除，分别由 About、设置页和右键拖动承担；两个入口展示相同的项目、状态和 action，菜单项状态由 settings snapshot 驱动，显隐是 runtime 会话状态不写入config.json。唯一实现替换点是 system_menu_native.rs 与 overlay 的HasWindowHandle实现。

键盘：键位图、降级规则与「不迁移」的长按兜底

键盘领域的核心迁移原则在 ADR-0049 与 ADR-0041 / ADR-0042 中被反复钉住：

1. Fn是「F 编号通配符」而非 Fn 键：旧版pre-refactor:src/composables/useDevice.ts:105-110只有key.replace(/F(\d+)/, 'Fn')这一处产出，对「模型没逐键画图」的F<数字>生效；两个预置键盘模型出厂的Fn.png就是这张共享回退图。地球键在旧版叫Function（keycode 63，rdev的 macOS 表），与Fn只差两个字符而意思不同，因此 BongoCat 把产品名定为Globe（USB HID usage0xff03），Function只作末位别名以兼容已安装旧包；Fn.png不改名、不迁移。
2. 键位词表是与模型作者的契约，不是「预置模型当前画了哪些图」的清单：ADR-0041 补齐了标点、导航、PrintScreen、小键盘等全部缺失 usage 的精确名（0x2dMinus …0x67KpEqual），并恢复出厂即存在却因缺命名 arm 永远画不出来的Delete.png（0x4c）。
3. 键位图存在才触发按键动作（ADR-0042）：bongocat-live2d-render新增KeyImageInventory，read(root)扫描resources/left-keys与resources/right-keys（不解码任何图片），can_draw(side, hid_usage)按key_name_candidates的候选顺序回答「这个键在这一手能不能画出来」；bongocat-app::input_bindings_for_model把静态 hand 表与模型键位图取交集写入InputBindings，缺图的键既不动爪子（CatParamLeftHandDown/RightHandDown）也不产生按键图层。
4. CapsLock 是锁存键（ADR-0004）：macOS 平台实测只投递「锁存翻转」事件而完全不投递物理松开，因此按产品既定的「短暂触发」语义在固定100 ms后由 adapter 合成释放边沿；该时长是按键行为本身，不是超时配置、不进 schema、不得推广到任何其它键。新版输入状态由「低延迟按下/释放事件 + 系统状态校正 + 生命周期 Reset」三类信号共同维护（Windows 以 Raw Input 为主路径并用GetAsyncKeyState校正，macOS 用 CGEventTap 并用CGEventSourceKeyState校正），因此旧版「每次 KeyDown 创建 3 秒自动释放 timer」的兜底被明确列为不迁移——它破坏长按语义且不能证明真实释放。

鼠标：参数映射与平滑，「非 Left 全部当作 Right」不迁移

鼠标按钮映射的「不迁移」项与旧版输入协议缺陷直接相关：旧版把所有非 Left 按钮统一映射为 Right，中键、侧键语义错误；新版输入协议显式枚举或忽略。指针平滑在 runtime 侧由CursorSmoother实现，worker/input.rs中smoother.set_target(sample, now)后advance(now)推进、normalized()产出归一化游标，worker/mod.rs 在 worker 初始化时创建平滑器；矩阵记录的「60 FPS 基准 decay 为 0.75、距离 <0.5 时收敛」正是CursorSmoother的默认参数事实（crates/bongocat-runtime/src/tests/input.rs有runtime_smooths_cursor_with_the_injected_monotonic_clock用例验证确定性行为）。

手柄：按钮/D-pad/trigger 与双摇杆参数

CatParamStick*系列参数在 parameter.rs 中逐一映射：CatParamStickLeftDown、CatParamStickRightDown、CatParamStickShowLeftHand、CatParamStickShowRightHand、CatParamStickLX/LY/RX/RY，对应双摇杆的按下、显示与 XY 参数语义。手柄连接模型自动切换（model.gamepad_auto_switch，默认关闭）在 ADR-0071 中设计为「谁观察、谁决定、谁写入」的完整通路：产品 frame source 观察 runtime 的connected_gamepad_count的「0 ↔ >0」跨帧跳变，发送GamepadConnectionChanged（不携带状态，处理时重读 runtime），settings service worker 作为唯一决定者复用Application::select_model两阶段提交；「上次使用」是会话内事实而非配置字段。

Live2D：加载、motion、expression 与参数更新

注意矩阵对旧版「motion sound 默认开」的观察，在配置契约中已被刻意收窄：model.play_motion_audio默认false，新装或新建配置一律静音，只有用户显式打开开关后 motion 音效才会预解码并发布Play（见 contract.md 的model.play_motion_audio段落，它明确引用本清单作为「旧版默认音效开」的证据来源）。这正是「P0 保证能力不静默消失、但允许修复旧缺陷/改变默认值」的典型例证。最大 FPS 语义的迁移对照见 bongo-cat-mver-frame-rate-semantics.md：overlay.maximum_fps接受15..=240，决定 runtime 周期求值、GPUI 产品 frame source 与独立 overlay run loop 的下一帧间隔（按帧截止时间计算，隐藏时统一降到 100 ms）。

模型：预置/导入/输入模式判定/删除保护

普通包输入模式判定是矩阵中经历了「不迁移 → P0 首发」升级的条目（2026-09-25 修订）：ModelStore 在 staging 提交前按left-keys/right-keys与手柄专用键名判定，无法判定直接拒绝导入，不再静默产生无模式记录；判定结果作为input_mode持久化到model.imported_models（闭合集合standard/keyboard/gamepad），模型卡片显示的模式来自强类型配置/构建事实：Mver 转换记录所选 section、预置记录由稳定 preset id 派生。矩阵末尾的模式补充（2026-09-25）特别声明：该 Badge 是展示元数据，不代表本阶段已改变 runtime 输入绑定。删除语义上，「删除失败仍从列表移除」被列为不迁移反例——新版必须保证失败保留原模型，删除走 prepare/commit 与删除事务。

快捷键与行为快捷键：自动分配、门禁与作用域

行为快捷键是本清单修订最密集的领域，经历了三次关键变更：

1. 2026-09-19 上调 P0：维护者要求新版保留旧版「模型加载后即为每个 motion 和 expression 自动分配组合键」的行为，否则快捷键页面在用户录制之前整页为空，属于产品能力静默消失。自动分配的分层、顺序与容量与旧版一致；有意差异是已占用的组合键跳过而非重用（旧版按位置索引，用户改过一项后可能把已被占用的组合键再发一次，而配置会因重复组合键整份失效），以及应用级 command 绑定同样计入占用。开关shortcuts.model_behaviors_enabled仍默认false：分配照常写入配置并在页面上可见可改，但不在用户开启前进入平台匹配表。
2. 2026-09-21 占用范围收窄到「同一模型 + 应用级 command」：切换模型后应只有当前模型的快捷键生效，且每个模型都从Cmd+1（macOS）/Ctrl+1重新编号。冲突判定按作用域进行（命令内唯一、同一模型内唯一、模型绑定不得与命令冲突），跨模型允许复用组合键，平台表只编译当前模型的绑定，切换模型时立即重建该表。
3. 2026-09-21 门禁跟随分组：模型行为快捷键开关从「交互」页搬到快捷键页面的「模型行为快捷键」分组第一行并改名「启用模型行为快捷键」；应用级快捷键新增自己的门禁「启用窗口快捷键」（shortcuts.commands_enabled，默认true，见 ADR-0052）。两个开关都是正向字段直出（无取反）、只带标题不带描述；门禁只把对应的一半排除在平台匹配表之外，不清空、不改写绑定。

自动分配的完整契约在 contract.md 中给出：primary在 macOS 是Command、其它平台是Control；分层顺序为[primary]、[primary, Shift]、[primary, Alt]、[primary, Shift, Alt]；每层先走数字1234567890再走字母QWERTYUIOPASDFGHJKLZXCVBNM，共4 × (10 + 26) = 144个名额——该容量在源码中即BEHAVIOR_SHORTCUT_CAPACITY（shortcuts/config.rs），行为 id 沿用motion:{group}:{index}与expression:{name}，超过 144 个的行为保持未绑定。分配是幂等的：已有绑定的行为永不重写，模型每次激活可安全重复执行。门禁的唯一实现点是ShortcutConfig::active_bindings（「此刻生效的绑定」的唯一投影，模型侧的活动模型过滤也在同一处）；字段级默认值在 config.rs 中为commands_enabled: true/model_behaviors_enabled: false，且Default是手写实现以避免派生默认值把全新配置判成「窗口快捷键已关闭」。

托盘、系统、权限与设置

托盘与任务栏图标在配置契约中由system.show_taskbar_icon（Windows 模型窗口任务栏按钮可见性，默认false，模型窗口是无标题栏WS_POPUP，任务栏按钮没有对应窗口可操作，因此默认不额外占用）与system.show_status_icon（Windows 托盘或 macOS 菜单栏状态图标）分别控制；macOS 另有system.show_dock_icon（程序坞图标唯一来源，默认false，进程以NSApplicationActivationPolicyAccessory运行）。显隐是平台能力而非持久化第二份布尔值：修改时先通过有界主线程 bridge 应用平台显隐，成功后才按 expected revision 原子提交配置，平台失败不提交、配置失败恢复旧平台可见性。

更新、外观、错误与诊断

旧 updater 的「HTTP endpoint + 前端嵌入固定请求凭据」是不迁移反例：BongoCat 的更新协议只允许 HTTPS 与签名（相关信任模型见 ADR-0021、ADR-0022、ADR-0025、ADR-0034）。自动检查周期为 24 小时，对应配置updates.check_interval_hours（默认24，接受1..=8760，check_automatically默认false）。

诊断项在 2026-09-28 由P1 首发后上调为P0 首发：脱敏诊断包导出与 About 页入口均已实现，隐私边界由 ADR-0016 的诊断导出契约固定。导出经ExportDiagnostics强类型 command 生成 format version 1 JSON 到当前环境的logs/diagnostics.json，只包含 runtime/input/configuration 的稳定 code、匿名计数、模型来源计数和 revision；模型 ID、路径、原始按键或事件流、原始配置、时间戳和动态 I/O 文本永远不进入导出。语言方面，appearance.language是严格的七值枚举（system、zh-CN、zh-TW、en-US、ar-SA、vi-VN、pt-BR），system每次启动读取平台首选 locale 并按 primary subtag 归类（RFC 4647 fallback），未知值由 v1 解析入口直接拒绝，不提供 alias、迁移或 fallback——旧版「不支持时回退英文」在新版被更精确的 locale 归类规则替代。

配置与平台：不迁移边界

配置领域的不迁移边界与 ADR-0008、ADR-0067 一致：初始版本是全新的，完整配置直接定义为schema_version: 1，不实现 migration、字段 alias、旧数据转换或历史版本判断；解析入口只接受完整 v1 并明确拒绝其他版本且不改写原文件。旧配置仅保留为只读考古 fixture。Linux 不进入首发范围，与 ADR-0006 的「首发后单独能力评估」决策一致。

主要源码证据与修订机制

清单的主要源码证据指向远端pre-refactor-tauri分支的对应实现（窗口、菜单、输入、手柄、模型、设置、系统集成和发布配置），并强调两点：

• 这些路径固定的是基线 commit 中的静态事实，历史源码后续变化不自动改变矩阵；
• 任何范围变化必须显式评审并更新本文件。

对应地，清单内嵌了大量修订记录，本身就是一部迁移决策日志：2026-09-16（圆角、hover 隐藏上调 P0）、2026-09-19（行为快捷键上调 P0、统计表对齐真实行数）、2026-09-21（占用范围收窄、门禁跟随分组）、2026-09-24（presentation opacity 定义）、2026-09-25（模式判定闭环、菜单树复用）、2026-09-28（诊断项上调 P0、移除 P1 档）。其中 2026-09-19 的修订记录还揭示了统计表本身的一次纠错：此前表里的P0 34 / P1 4与矩阵实际内容不符且早于改动就存在，不迁移一列始终是对的——说明该表本来就是逐行计数而非另一套口径，本次对优先级的净影响只有一行。

范围统计：40 / 8 的闭环口径

统计用于防止实现期静默扩缩范围；拆分或合并矩阵行时必须同步更新。8 个不迁移项完整清单为：Windows KeyDown 3 秒自动释放 timer、非 Left 鼠标按钮全部当作 Right、模型删除失败仍从列表移除、原样复刻旧 Vue/Ant Design 页面、旧 updater 的 HTTP endpoint 与嵌入凭据、读取/导入旧 Tauri/Pinia 配置、恢复旧物理坐标与旧模型 id、Linux 平台能力。

已确认的行为风险：新实现不得复制的八个反例

清单末尾以「已确认的行为风险」形式总结了八条必须由新实现规避的旧版问题，它们与矩阵的「不迁移」行互为印证：

1. Windows KeyDown 后通过 timer 自动释放，不能证明真实按键状态，长按语义受 delay 影响——由 KeyUp、reconcile、Reset 替代（ADR-0004）。
2. pressed key 图片按「手目录」互斥，不是任意多键叠加；fixture 必须保留该产品语义或明确修改。
3. 模型删除在文件删除失败时仍会从列表移除，新实现不得复制该错误行为（失败必须保留原模型）。
4. 模型 mode 通过 right-keys 内容推断，属于启发式协议，需要显式验证与诊断——现由 ModelStore staging 判定替代。
5. 当前窗口状态保存物理坐标，跨 DPI/显示器恢复需要新规范——新版使用逻辑坐标与window-state.json。
6. 当前更新、模型和输入错误多以字符串传播，新 runtime 需要稳定 error code。
7. 旧 updater 允许 HTTP endpoint 并把固定请求凭据放在前端源码，BongoCat 不得复制（新协议只允许 HTTPS 与签名）。
8. 旧设置页面、Tauri plugin API 和 Pinia 字段名不是兼容面，只保留为功能入口证据。

结语：清单如何约束新版实现

legacy-behavior-inventory.md在 BongoCat 迁移工程中扮演的角色可以概括为三句话：它是「旧版必须保留哪些能力」的唯一仲裁者（P0 40 项构成双平台可发布闭环）；它是「旧版哪些缺陷不得复制」的反例库（8 项不迁移与 8 条行为风险互为印证）；它是「范围变更必须显式评审」的修订日志（每条修订记录都注明日期、原因与对矩阵行的影响）。对阅读源码的开发者而言，这张矩阵提供了从产品能力到实现证据的导航：行为快捷键的自动分配契约与容量（contract.md 与 shortcuts/config.rs）、地球键/Fn 语义（ADR-0049 与 macos.rs）、键位图即动作门禁（ADR-0042 与KeyImageInventory）、双摇杆参数（parameter.rs）、菜单树复用（ADR-0068）、诊断导出（ADR-0016），每一处都能沿矩阵的「源码结论」列继续下钻到 crate 实现与测试。

• 桌面应用