BongoCat Documentation

Technical Documentation: ayangweb/BongoCat

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[](./LICENSE)
[](https://github.com/ayangweb/BongoCat/releases/latest)
[](https://github.com/ayangweb/BongoCat/releases)



[](https://trendshift.io/developers/8507)
[](https://trendshift.io/repositories/14605)
<a href="https://hellogithub.com/repository/7d23863fd4be47b39e816193ded385c9" target="_blank">
  
    
    
    
  
</a>

BongoCat is a desktop companion for Windows and macOS. A Live2D cat lives on your screen, its eyes
and paws follow your mouse, and it reacts to every key, mouse button and gamepad button you press.
Bring your own models, move the window wherever you like, and it stays out of your way until you
want it again.

Inspired by Bongo-Cat-Mver by
MMmmmoko.

Features Copy Chapter

• Runs on macOS and Windows.
• Matches the right motion to every key, mouse button or gamepad button you press.
• Bring your own Live2D models and make the cat your own.
• Fully open source, public code, and no collection of user data.
• Works offline with no network access, so your privacy is protected.

More models Copy Chapter

You can browse and download more cat models, or share your own, in
Awesome-BongoCat.

Community Copy Chapter

Support Copy Chapter

Every bit of recognition is appreciated. Donations are welcome, but never expected — thank you for
loving the cat ❤️

Contributing Copy Chapter

Contributions are very welcome. Please read the contributing guide.

Star history Copy Chapter

License Copy Chapter

BongoCat is open source under the Apache License 2.0 license.

Overview (`docs/benchmark/README.md`) Copy Section

Benchmark Records

本目录保存可重复的性能测试方法和结果。每份记录至少包含：

• 构建 commit 和 release/debug 配置
• 操作系统、CPU、GPU、内存和显示器/DPI
• 模型、窗口尺寸、目标 FPS 和输入脚本
• 预热、样本数、测量工具和原始数据位置
• p50/p95/p99、误差来源和结论

macOS Metal overlay 的第一个单机 draw-time diagnostic baseline 见
macos-overlay-frame-timing-90e0aa7.md
及其 raw CSV。它只验证当前 preview 的有界计时器，未覆盖发布性能矩阵。

Overview (`spikes/gpui-settings/README.md`) Copy Section

GPUI Settings Spike

This is an isolated Phase 0 probe for gpui = 0.2.2. It intentionally does not
belong to the legacy Tauri workspace and does not implement product state,
Live2D, input capture, or the native overlay.

Run it from this directory:

cargo run

For a repeatable lifecycle smoke test:

BONGOCAT_SPIKE_AUTO_QUIT_MS=1500 cargo run --locked

Successful output includes window opened, a first-frame line with a positive
platform scale_factor, runtime snapshot revision=1, runtime stopped, and
stopped. Window initialization failure exits non-zero after the runtime
shutdown hook completes, so automated smoke tests cannot pass on an error log
alone.

The synthetic runtime bridge uses a bounded typed command channel. The UI reads
revisioned snapshots through a GPUI task, while application shutdown waits for
the runtime acknowledgement. Run its contract test with:

cargo test --locked

Launch with --runtime-error-probe to exercise non-blocking loading, typed
failure, retry, and revision recovery. The first refresh resolves to revision
1, the second reports runtime probe failed, and the retry resolves to revision
2; each read waits three seconds on the GPUI background executor rather than blocking the UI
thread.

The Reset command exercises GPUI's public tooltip API and a project-owned modal
dialog. The dialog traps Tab/Shift-Tab between Cancel and Reset and supports
Enter/Space activation and Escape dismissal. It remains a Phase 0 interaction
probe, not a product settings reset implementation.

This probe is visual-first like the product: it does not maintain a
project-owned accessibility tree, adapter or action channel, and it does not
depend on accesskit, accesskit_macos or accesskit_windows (ADR-0054). Its
CI smoke therefore checks window lifecycle, the typed runtime bridge and the
visible UI probes, not an auxiliary-technology tree.

On macOS, launch with --menu-probe to verify the native Application, Edit,
and Window menu structure. The probe dispatches Select All, Cut, and Paste via
the installed NSMenu items on later AppKit run-loop turns, then checks the
focused GPUI text input and clipboard without logging their contents. This does
not validate the later NSStatusItem menu-bar service.

Launch with --tooltip-probe to send synthetic native mouse-move messages
through the platform window and GPUI input path. The probe finds the Reset
hitbox, waits for GPUI's 500 ms tooltip delay, verifies that the tooltip is
built, then moves out and verifies hover cleanup. It does not replace a physical
pointer.

Build the release binary and collect the macOS Phase 0 performance probe with:

./scripts/package-macos.sh
./scripts/benchmark-macos.sh

Raw CSV files and a summary are written below target/benchmark/. First-frame
time starts at Rust main, so it excludes dyld and process creation. Idle CPU
is the lifetime average reported by macOS ps; RSS is sampled in KiB after a
five-second warmup. The binary increment compares the unsigned release
executable with an empty Rust executable built by the same toolchain using
opt-level=2 and thin LTO.

Build an ad-hoc-signed macOS application bundle and launch it through
LaunchServices:

./scripts/package-macos.sh
open -W "target/package/BongoCat GPUI Spike.app" --args --auto-quit-ms 6000 --menu-probe --tooltip-probe

The ad-hoc signature only validates local bundle integrity. It is not a
Developer ID signature or notarization result.

The spike is successful only when the window opens, renders text without
clipping, and closes cleanly on the target machine. It is not evidence that the
production runtime, UI, or overlay lifecycle is complete.

This probe uses GPUI's default precompiled shader path. On macOS, install the
optional Metal Toolchain before building:

xcodebuild -downloadComponent MetalToolchain

The validated component version is 17F109.

Overview (`spikes/overlay-windows/README.md`) Copy Section

Windows Native Overlay Spike

This Phase 0 crate owns the independent Windows overlay boundary used by the
GPUI coexistence probe. It creates a thread-confined Win32 popup and a separate
D3D11 + DXGI + DirectComposition renderer without accessing GPUI renderer
internals.

Hypothesis Copy Chapter

A Rust-owned HWND with a premultiplied-alpha composition swap chain can live
beside a GPUI settings window, clear/present transparently, transition between
visible and hidden states, and release GPU/DirectComposition resources before
destroying the window.

The spike attempts a hardware D3D11 device first and falls back to WARP so CI
can test ownership and composition APIs without claiming physical-GPU
performance. Windows ARM64 is compile-checked only; Cubism R5 still blocks an
ARM64 release.

Boundaries Copy Chapter

• The crate returns project-local strings and reports; Win32/COM types stay
  private.
• The owner is deliberately !Send/!Sync and asserts its creation thread.
• unsafe is limited to documented Win32, D3D11, DXGI and DirectComposition
  calls.
• Renderer teardown detaches the composition graph and flushes D3D11 before
  the HWND owner is dropped.
• This does not render Live2D, validate physical-GPU performance, recover a
  removed device, or prove leak freedom beyond the measured process handle
  contract.

Validation Copy Chapter

Portable and cross-target checks:

cargo fmt --manifest-path spikes/overlay-windows/Cargo.toml -- --check
cargo clippy --manifest-path spikes/overlay-windows/Cargo.toml --locked --target x86_64-pc-windows-msvc --all-targets -- -D warnings
cargo check --manifest-path spikes/overlay-windows/Cargo.toml --locked --target aarch64-pc-windows-msvc

The windows-latest CI job runs the GPUI coexistence executable in three
modes:

--auto-quit-ms 1800
--simulate-overlay-init-failure --auto-quit-ms 900
--windows-overlay-cycles 100

The normal path must report two transparent presents and ordered GPU/HWND
teardown; the GPUI quit path explicitly releases the overlay owner before
posting the platform quit message. The injected failure must leave the GPUI
settings window alive with a degraded status. The cycle probe warms
process-global graphics state, then
requires 100 full create/show/present/hide/drop cycles without process handle
growth beyond a fixed four-handle tolerance. The standalone cycle process owns
a thread-confined COM apartment, and CI terminates any individual smoke process
that does not exit within 30 seconds.

Overview (`tools/cubism-bindgen/README.md`) Copy Section

Cubism Core Binding Generator

This offline tool fixes the raw-binding generation contract for Cubism 5 SDK
for Native R5. It does not download the SDK, accept a license, link Cubism
Core, or implement product behavior.

The committed fixture header and expected bindings are synthetic BongoCat test
data. They verify the symbol allowlist, three R5 desktop target configurations,
the C ABI, deterministic output, and generated-file drift. They are not copied
from the Cubism SDK. Windows x86 and native Windows ARM64 are outside the
final target set; Windows on ARM runs the x64 build. R5 has no matching
desktop Windows ARM64 Core to bind.

Fixture check Copy Chapter

cargo run --manifest-path tools/cubism-bindgen/Cargo.toml --locked -- check-fixtures

Expected bindings are generated files and must not be edited manually. After
reviewing an intentional generator or synthetic-header change, refresh them
with:

cargo run --manifest-path tools/cubism-bindgen/Cargo.toml --locked -- refresh-fixtures

Licensed R5 header Copy Chapter

Only a maintainer who has legally acquired the pinned R5 SDK may run real
generation. Use the header SHA-256 reported by tools/inspect-cubism-sdk.py:

cargo run --manifest-path tools/cubism-bindgen/Cargo.toml --locked -- \
  generate \
  --header /absolute/path/outside/repository/Live2DCubismCore.h \
  --expected-header-sha256 <64-hex-digest> \
  --target aarch64-apple-darwin \
  --output-directory /absolute/new/path/outside/repository/cubism-bindings-aarch64

The tool refuses repository-local licensed headers and output, refuses an
existing output directory, and emits only bindings.rs plus
provenance.json. The provenance records header/output/config hashes,
bindgen, libclang, Rust edition, and target configuration without recording
the local SDK path.

The approved minimal R5 developer baseline under vendor/cubism/5-r.5 and the
real generated bindings may be committed for local development and ABI evidence.
The official SDK ZIP, extracted SDK, and unreviewed generated output must remain
outside the repository unless the maintainer records a later permission decision.
Review of new generated output must happen in the controlled external directory and cover:

1. header hash against the independently verified R5 SDK report;
2. exact generated symbol inventory and target calling convention;
3. a second generation with the recorded bindgen/libclang configuration;
4. diff and SHA-256 equality between both outputs;
5. compile/link/ABI smoke against the matching official Core artifact.

Overview (`tools/cubism-core-probe/README.md`) Copy Section

Cubism Core Probe

This standalone Rust tool validates a locally supplied Cubism Core and generated raw
bindings without committing licensed SDK material. It checks the fixed Core/Moc
versions, aligned Moc and Model lifecycle, parameter/part/drawable arrays, enhanced
rendering blend/offscreen arrays, masks, geometry, canvas data, and repeated teardown.

The tool intentionally has no default binding or library path. Prepare the official
header, generated binding, and matching Core outside the repository, then compile with
explicit paths:

BONGOCAT_CUBISM_BINDINGS=/external/bindings.rs \
RUSTFLAGS='-L native=/external/core -l dylib=Live2DCubismCore' \
cargo build --manifest-path tools/cubism-core-probe/Cargo.toml --release \
  --target-dir /external/probe-target

Run one or more absolute Moc paths as id=/absolute/path.moc3; use repeated lifecycle
cycles for the Phase 0 evidence:

DYLD_LIBRARY_PATH=/external/core \
/external/probe-target/release/bongocat-cubism-core-probe --cycles 100 \
  standard=/absolute/path/demomodel.moc3

On Windows, link the matching x64 import library and place the official DLL next to the
probe executable or on its controlled DLL search path. Native Windows ARM64 is outside
the final target set after ADR-0033, so Windows on ARM runs the x64 probe/build; this
probe must not use the UWP artifact.

The approved minimal developer baseline may commit the official header and reviewed
real generated bindings under vendor/cubism/5-r.5 and bongocat-live2d. The SDK
ZIP, extracted SDK, additional Core binaries, and probe target directory remain
outside the repository unless a later permission decision says otherwise. Probe output
proves Core ABI and model-array access only; it
does not prove Framework behavior, GPU rendering, publication rights, or another target's
ABI.

TODO (`docs/TODO.md`) Copy Section

TODO

Phase 4：设置与模型管理 Copy Chapter

• P4-WINDOW-MODE（issue #1130）：Windows 普通窗口、可配置纯色背景、OBS 窗口捕获与抠图、旧 v1 配置读取、禁用颜色预览和统一客户区等比例缩放已实现。依赖 ADR-0057、ADR-0054；协议见 ADR-0089。退出条件：配置/UI/runtime/HWND/D3D11 回归、just check、Windows product smoke、OBS BitBlt/WGC/抠图验收，以及 Windows 10 和 125/150/200% 跨屏实机验证。当前 Windows 11 OBS 与自动化验收已有证据，缺少的 Windows 10、跨屏与设置布局验收保持未勾选；macOS 不在本任务范围。证据见 docs/benchmark/windows-window-mode-2026-10-08.md。
• P4-MOTION-OVERLAP（issue #1107）：默认关闭的动作叠加开关、旧 v1 文档读取、独立计时/淡出/停止和按启动顺序求值已实现，标准模型跨组重复资源重播有自动化回归。依赖 ADR-0061、ADR-0012（动作音效）；协议见 ADR-0088。退出条件：workspace 与独立 config-store contract、just check、双平台 CI smoke，以及 Windows/macOS 实机多动作叠加、跨组重播和 800×600/DPI/Retina 目视验收。尚缺的平台实机证据保持未勾选。
• P4-NESTED-MODEL-IMPORT（issue #1105）：嵌套模型发现、单模型自动继续、多模型复用选择弹框、模式选择及顺序导入已实现。依赖 ADR-0037、ADR-0055、ADR-0059；协议与扫描边界见 ADR-0087。退出条件：自动化扫描/服务/GPUI 交互回归、just check、macOS smoke，以及 Windows/macOS 实机文件夹选择与拖入、800×600 和 DPI/Retina 目视验收。缺少的平台实机证据仍保持未勾选，不由另一平台编译或 headless 测试代替。

Changelog Conventions (`docs/changelog-conventions.md`) Copy Section

更新日志书写规范

文档性质：规范性约定。 本文只约束 CHANGELOG.md 与 CHANGELOG.zh-CN.md 的分段标题
怎么写。目标架构仍以 docs/technical-design.md 和 docs/adr/ 为准。

UI 文案的书写规范另见 docs/localization-copy-conventions.md；该文 §1.2 明确把
CHANGELOG 排除在自己的适用范围之外，所以两套规范互不覆盖。

适用范围：CHANGELOG.md 与 CHANGELOG.zh-CN.md 的版本条目内的 ### 分段标题。
版本标题（## <version> - <date>）不受本文约束。

1. 分段标题只能取自固定词表 Copy Chapter

规则：一个分段标题由一个 emoji 加一个固定文案组成，英文侧和中文侧各自只能从词表里取。

发布时 just release-notes 会把两份 changelog 的同一条目拼成同一份文档（GitHub
release 正文和 App 内更新窗口读的是同一个文件），读者会在同一段文字里连续看到中英文。
如果分段标题是临时想出来的，就会出现"中文条目有这一节、英文条目没有"或"同一节两种
叫法"，而读者无从判断这是漏译还是本来就不同。

因此词表按 emoji 索引：emoji 是这一节的标识，两侧文案是它的固定写法。

不需要某一节就整节省略，不要保留空标题，也不要为了凑齐词表而新增空节。

1.1 emoji 的变体选择符不作要求 Copy Section

⚠️（U+26A0 U+FE0F）与 ⚠（U+26A0）在不同编辑器里都会被写出来，U+FE0F 只决定字形
怎么画，不决定它是哪一节。校验比较前会去掉 U+FE0F，所以两种写法都算对；不要为了
"统一"去批量改写某一侧的 emoji。

1.2 新增一节 Copy Chapter

需要词表里没有的分段时，在词表里加一行，同时给出英文和中文，再在两份 changelog 里使用。
不要只在一侧新增后靠人工翻译——那正是本规范要消除的情况。

1.3 下载链接、模型库与赞助不进 changelog Copy Section

发布说明不只有 changelog 条目。bongocat-packaging 给每个语言块生成一个
## Changelog / ## 更新日志 标题，并在块末尾生成一节下载链接、一节模型库
（Awesome-BongoCat）和一节赞助（见 §1.4），再与两份 changelog 的条目合成同一份文件。
不要把这些内容写进 CHANGELOG.md 或 CHANGELOG.zh-CN.md：

• 它们的每一项事实都由打包工具已经持有的值生成——产物名来自 ReleaseTarget::download_asset，
  下载地址来自 release_asset_url，版本号来自同一个 CARGO_PKG_VERSION；手写一份就多出一处
  要在每次发版时人工核对的地方。
• 它们每个版本都一样，进 changelog 等于每次发版改两个文件重述一遍不变的文字。
• 词表管的是 changelog 条目内的 ### 分段。生成块用的是 ##，因此不需要在词表里
  加行，加了反而会让门禁去校验一份根本不由人写的文案。

要改文案、换赞助或加赞助商，改 crates/bongocat-packaging/src/main.rs 里的
APPENDIX_ENGLISH、APPENDIX_CHINESE 和 RELEASE_SPONSORS，两份 changelog 不动。

1.4 生成块的形状 Copy Section

--extract-release-notes 产出的文件是「## Changelog → 条目 → 生成块 → --- → ## 更新日志
→ 条目 → 生成块」。每个语言块内，changelog 条目在前、生成块在后：条目通常以「⚠️ 升级说明」
开头，而 2.0.0 这类版本要求先卸载旧版本再装新版本，读者应当先读到这句再点到下载链接。

条目自己只写 ### 分段，而生成块的三节都是 ##。所以条目前面必须由工具补一个
## Changelog / ## 更新日志：没有它，条目会顶着文档开头，它的 ### 看上去像是属于
前一个块，而读者分不清哪一半是人写的、哪一半是发版时生成的。这个 ## 同样不要写进
changelog 文件——门禁会把粘进去的写法拦下来。

生成块只用 App 内更新窗口能安全渲染的 Markdown：普通链接和列表项，不含图片和内联 HTML
（crates/bongocat-ui/src/update_markdown 会拒绝解释两者）。链接目标一律 https，
因为窗口只把 https 渲染成可点击控件，其余 scheme 会被降级为纯文本。

1.5 怎么强制 Copy Section

tools/tests/test_release_changelog_contract.py 的 ChangelogSectionVocabularyTests
逐条断言：

• 两侧每个 ### 标题的 emoji 在词表内，且文案与词表逐字相同；
• 两侧的 emoji 序列完全一致且顺序相同（漏译一侧会失败）；
• 词表自身没有重复项。

ReleaseNotesContractTests 另外断言两份 changelog 都没有写 §1.3 的生成块标题——有人把它
粘进 changelog 就会失败，因为发布后那几行会各出现两次。

python3 -m unittest tools.tests.test_release_changelog_contract

因此这条规则不依赖 review 记忆：写错、漏译或在词表外自造一节都会在门禁上变红。
python3 -m unittest discover -s tools/tests 会一并跑到它。

2. 版本标题 Copy Chapter

版本标题是 ## <version> - <date>。just release-notes 按
[workspace.package].version（即 just version 打印的值）去 changelog 里找对应条目，
找不到就让发布失败。因此发版时必须把 ## Unreleased 改成 ## <version> - <date>。
详见 docs/adr/0033-build-packaging-and-release-toolchain.md。

3. 发布提交：标题固定为 `chore: release v` Copy Chapter

规则：打 tag 的那个 commit，标题必须逐字为 chore: release v<version>，其中
${version} 就是 tag 去掉 v 后的部分。

chore: release v2.0.0

理由：

• 历史读起来和发布页一致。 git log 里一眼能看出哪个 commit 是发版点，不必先知道
  版本号再去找 tag。
• 版本升级是可检索的。 git log --grep='^chore: release' 就能列出所有发版点。
• 它把「发版」和「改代码」分成两类。 发版 commit 只装版本相关的改动（版本号、
  changelog 标题），功能改动留在各自的 feat/fix 里。Conventional Commits 的
  chore 正是这个用途。

3.1 怎么强制 Copy Section

.github/workflows/release.yml 的「Check the tag against the single product version
source」步骤在构建之前就断言这件事，所以标题写错只需几秒就失败，而不是等三个平台
白跑二十分钟：

::error::the commit tagged v2.0.0 is titled 'fix: 某个功能'; a release commit must be titled 'chore: release v2.0.0'

这个断言和同一步里既有的 tag／版本号一致性断言是同一个守卫：只有
GITHUB_REF_TYPE == 'tag' 时才生效，因此用 workflow_dispatch 手动跑不会误伤。

3.2 发版时的动作顺序 Copy Section

# 1. 版本号只有一个来源，改它：[workspace.package].version
# 2. 两份 changelog 的 `## Unreleased` 改成 `## 2.0.0 - <date>`
# 3. 提交，标题逐字为 `chore: release v2.0.0`
git commit -m "chore: release v2.0.0"
# 4. 打 tag 并推送，流水线按 tag 触发
git tag -a v2.0.0 -m "Release 2.0.0"
git push origin master && git push origin v2.0.0

改完第 2 步先本地验一次，避免构建跑完才发现发布说明取不到：

just release-notes release-notes.md

Localization Copy Conventions (`docs/localization-copy-conventions.md`) Copy Section

本地化文案书写规范

文档性质：规范性约定。 本文只约束 crates/bongocat-i18n/locales/*.json 里的 UI 文案
怎么写。目标架构仍以 docs/technical-design.md 和 docs/adr/ 为准；
catalog 的结构、key 命名与占位符规则见
docs/adr/0012-json-localization.md。

适用范围：crates/bongocat-i18n/locales/ 下的全部语言资源。新增文案一律遵守，
不因语言而异。

1. 省略号：一律三个点 Copy Chapter

规则：省略号写成单个 …（U+2026），一个字符，视觉上是三个点。

理由：

• 同一份 catalog 的同一个 key 由中英文共用，写法必须与语言无关。…… 只在中文排版里
  成立、... 只在拉丁文里成立，任何一种都会让另一语言看起来是错的。
• … 是单个字符、占一个码位，中英文字体都能正确渲染，宽度也稳定；…… 是两个字符，
  在非中文字体下还可能被拆成两个独立字形。
• 文案里没有需要区分"三个点"和"六个点"的语义，长度差异纯属排版习惯。

示例（crates/bongocat-i18n/locales/zh-CN.json）：

{
  "models": {
    "import": {
      "step": {
        "choosing": "正在打开文件选择器…",
        "importing": "正在导入模型…",
        "capturing": "正在截取封面…"
      }
    }
  }
}

英文侧同样是一个 …，不写 ...：

{
  "models": {
    "import": {
      "step": {
        "choosing": "Opening the file picker…",
        "importing": "Importing model…",
        "capturing": "Capturing cover…"
      }
    }
  }
}

1.1 怎么强制 Copy Section

tools/validate-locales.py 会遍历每个 locale 的每个值：一旦出现连续两个及以上的 …
或连续两个及以上的 ASCII .，校验直接失败并报出 key 与实际写法，例如：

error: zh-CN: models.import.step.importing spells an ellipsis as '……'; use a single '…' (U+2026) in every locale

因此这条规则不依赖 review 记忆：写错就会在门禁上变红。新增/修改文案后本地跑一次
python3 tools/validate-locales.py 即可。

1.2 例外 Copy Section

• 文档、源码注释、CHANGELOG、memory 记录属于自然语言，不受本规范约束。但引用 UI 文案时
  照抄 catalog 里的写法，否则文档与界面会不一致。
• 代码里的 ..、...（Rust 语法、路径、范围表达式）不属于文案。

Product Runtime (`docs/product-runtime.md`) Copy Section

BongoCat Product Runtime

The repository root is the formal workspace and the only product build entry. The previous
implementation is retained only in the remote pre-refactor-tauri branch; master carries the
current code rather than a historical implementation.

Build Environments Copy Chapter

Direct Cargo commands from the repository root use the Development environment by default; the
selection is compiled into the artifact. The formal just dev, just test, and just check
recipes also use Development for the workspace. Run product commands from the repository root:

cargo run -p bongocat-app --release

Enable the production feature for a standalone Production build:

cargo run -p bongocat-app --release --features production

The environment is a mutually exclusive compile-time feature, not a runtime environment variable;
the legacy BONGOCAT_BUILD_ENV name is ignored.

This is the current formal visible product entry on macOS and Windows. It loads the selected bundled
preset (standard by default), starts the product runtime and platform input producer, and displays
the transparent Metal or D3D11 overlay. Closing the settings window leaves the runtime, input, and
overlay active and destroys the settings GPUI window; the next open creates a fresh settings entity
from the current runtime snapshot. The process-local settings navigation memory restores the last
top-level sidebar page until the application restarts. Update windows also destroy their window on
close while their worker continues independently. Explicit Windows quit first stops and joins every
BongoCat-owned runtime, input, audio, renderer, GPU, and overlay owner. The platform adapter then
terminates the process without dropping the final GPUI window, because GPUI 0.2.2 synchronously
re-enters its borrowed AsyncApp from WM_DESTROY. This final-step workaround must be removed when
a fixed GPUI revision is adopted.
The application stays active until an explicit Quit command by default. --run-seconds <seconds>
with a positive value is reserved for bounded smoke and diagnostic runs; 0 is the explicit spelling
of the normal unbounded lifetime used by platform startup-item registrations.

The cross-platform product smoke closes and reopens the settings window, verifies that a fresh entity
receives the current snapshot, and checks that the process-local sidebar page is restored:

cargo run -p bongocat-app --release -- --run-seconds 4 --settings-window-smoke

On macOS, grant Input Monitoring permission to the launching terminal for global keyboard and
mouse-button animation. Permission denial is reported as a degraded input state and does not
prevent the model from appearing. On Windows, the product uses a dedicated hidden Raw Input owner
window, periodically reconciles locally pressed candidates with GetAsyncKeyState, and resets input
on device, session, power, queue, and service lifecycle changes. Physical PixPin, Win+L, UAC,
administrator-boundary, and long-running input tests remain release evidence tasks.

Production must be selected at build time. The packaging entry point rejects an unknown
--environment value before invoking Cargo and translates the selection into the app's Cargo
feature:

just build

just build forwards its arguments to crates/bongocat-packaging, which is the only place that
decides how the product is compiled and packaged. It compiles the release binary with the immutable
production feature where selected, writes build provenance, and hands the executable to
cargo-packager, which owns the macOS .app layout, Info.plist generation and the Windows NSIS
installer. Both local developers and CI run this same entry point, so there is one code path and one
configuration:

just build                                            # Production, host target, all artifacts
just build --target x86_64-apple-darwin               # explicit target (macOS can cross-build both)
just build --environment development --formats app     # Development .app only, for smoke tests
just version                                          # the resolved product version

The product version has one source of truth: [workspace.package].version in the root Cargo.toml.
All workspace crates inherit it, including bongocat-packaging, so Cargo itself resolves the
value before the packager runs; the settings window, system menu, and update runtime read the
compiled CARGO_PKG_VERSION. Cargo.lock records the resolved workspace versions as generated
metadata; a release changes the root manifest once and lets Cargo refresh the lockfile. The Windows
executable resource derives its file, product, and display versions from that value, and
cargo-packager writes CFBundleShortVersionString into the bundle from the same configured
version. The release workflow refuses to publish a tag that disagrees with just version.

On macOS just build produces target/package/BongoCat.app and
target/package/BongoCat-<version>-<arch>.dmg, and prints both absolute paths. The disk image
contains the signed bundle plus an /Applications drop link. On Windows it produces the x64 NSIS
current-user installer at target/package/BongoCat_<version>_x64.exe.

Build provenance is written as path-free JSON with the source commit, Cargo.lock SHA-256,
Rust toolchain, target, profile, feature set, and build environment. The macOS package includes
Contents/Resources/build-provenance.json; the Windows installer payload does too.

Windows x64 packaging is a current-user NSIS install. cargo-packager obtains its own NSIS
toolchain, so no release workstation state is required, and the installer requests no administrator
privileges and writes only HKCU uninstall metadata plus its own product directory. The installer is
signed only when a signing identity or signing command is configured; without one the release
workflow reports the unsigned installer as unsuitable for a stable release.
The wizard opens with a language picker covering exactly the application languages (Simplified and
Traditional Chinese, English, Arabic, Vietnamese, Brazilian Portuguese, Korean, French); it preselects the
system language and falls back to English. The choice only changes the installer and uninstaller
text, never the application language setting. NSIS stores it in HKCU, so a machine that already has
BongoCat installed reuses the stored language without showing the picker, and silent updates never
show it. cargo-packager embeds the installer messages for every language except Vietnamese, whose
strings live in crates/bongocat-packaging/installer/Vietnamese.nsh. Windows install,
upgrade, uninstall, and rollback smoke remain release gates.

Preset models are product resources, not user data. macOS loads them from
BongoCat.app/Contents/Resources/models; Windows packages must place them under
resources/models beside bongocat-app.exe. An unpackaged development binary falls back to the
repository resource tree only when that product-relative location is absent.

The application does not expose a runtime environment switch. Both environments use the same
schema and relative layout under separate development/ and production/ roots.
The formal startup API always resolves that root from the compiled environment. Process-level tests
that require an isolated temporary layout must explicitly enable storage-test-injection; the
feature is absent from the default CLI/API and is rejected at compile time for Production builds.

Verification Copy Chapter

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --exclude bongocat-app -- -D warnings
cargo clippy -p bongocat-app --all-targets --features storage-test-injection -- -D warnings
cargo clippy -p bongocat-app --all-targets --features production -- -D warnings
cargo test --workspace
cargo check --workspace --release

Live2D Diagnostic Preview Copy Chapter

bongocat-overlay remains a diagnostic executable for selecting presets, injecting deterministic
input, and exercising model switching. It is not the product entry. The final positional argument
is the preview duration in seconds. The interactive and fixed-duration preview is currently
available on macOS:

cargo run -p bongocat-overlay --release -- standard 30
cargo run -p bongocat-overlay --release -- keyboard 30
cargo run -p bongocat-overlay --release -- gamepad 30

On macOS, the completion line includes frame_timing=Some(...). Its draw_*_us
values are nearest-rank percentiles over the interval surrounding each Metal
draw call, including the initial draw. missed_deadlines is the number of
full preview-loop iterations that reached the next 60 FPS deadline before the
loop could sleep. The collector retains at most 4,096 samples and reports
additional samples as samples_dropped; it intentionally excludes input,
runtime handoff, and sleep. Windows' switch-only preview reports
frame_timing=None until it has an equivalent paced diagnostic path.

On Windows or macOS, exercise transactional GPU model replacement with all three presets by running
100 measured standard -> keyboard -> gamepad -> standard cycles (300 reported generations):

cargo run -p bongocat-overlay --release -- standard 0 --switch-cycles 100

The switch probe first injects one invalid texture preparation and requires the current CPU model,
input bindings, and GPU generation to remain active and drawable. Rejected candidate generations
may create a gap, but committed generations must remain strictly monotonic. Every valid generation
performs a non-transparent frame readback. Before the requested Windows measurement interval, the
probe runs at least 100 equivalent warmup cycles and waits for driver workers to settle. The warmup
high-water mark is a snapshot, not a hard ceiling: process-global D3D11, DXGI, and thread-pool
workers can be created after the settle window and then persist for the life of the process, so the
probe accepts a settled count within two threads of the mark while still rejecting the per-switch
growth that scales with the measured switch count. It also rejects more than four additional
handles or DXGI local-memory growth, and the preview reports the warmup mark and the settled count
so the remaining allowance stays visible. The macOS probe rejects Metal allocation growth between
warmed-up standard baselines.

By default the preview applies deterministic, model-specific input through the product runtime so
hand, pointer, head, and eye changes exercise per-frame Cubism evaluation and GPU buffer updates.
To use the formal macOS listen-only CGEventTap and gilrs/IOHID producers for keyboard, mouse and
gamepad input instead, grant Input Monitoring permission to the launching terminal and run:

cargo run -p bongocat-overlay --release -- standard 30 --interactive

The interactive path uses the same typed runtime input state as the deterministic preview and
stops the platform producer before the runtime and Metal overlay. It seeds the current global
cursor position at startup and then coalesces cursor movement through an independent latest-value
transport; pointer, head, and eye parameters use the active display's logical viewport. The pinned
gilrs fork now exposes bounded backend queue/epoch recovery and an explicit bounded shutdown
acknowledgement; BongoCat maps those results into its own diagnostics, while physical gamepad
focus, device, and long-lifecycle evidence remains a release gate. The product entry now owns this
runtime/input/render lifecycle on both launch platforms. GPUI settings coexistence, installed-model
selection, physical gamepad validation, and remaining lifecycle evidence are separate work items.

Cubism model evaluation and Metal GPU ownership are separated by the platform-independent
bongocat-render contract. The single runtime worker owns the mutable Cubism model and publishes
immutable resource/frame pairs through its latest-frame transport; the overlay resolves drawables,
masks, and textures with strong resource IDs and never receives the mutable Cubism model.

The same worker now owns typed motion playback. Application::start_motion resolves a validated
model3 group/index, applies motion3 linear, Bezier, stepped, or inverse-stepped curves using monotonic
elapsed time, and publishes the resulting immutable drawable frame. A product motion advances for one
cycle and then remains the current motion layer at the clip's fully evaluated terminal sample; later
frames restore Core defaults and reapply that final motion contribution instead of snapping back to
idle. The held sample retains the resource's natural fade weights. Completion is derived from elapsed
monotonic time even when no frame was delivered, so a hidden or sleeping overlay still releases the
completed layer's priority before the next command. The completed layer no longer reserves priority,
so the next motion request may replace or restart it.
Runtime snapshots expose only the active motion identity, priority, originating command sequence,
and optional first stop command sequence. Explicit stop also matches a completed held motion,
preserves the first frame, multiplies curve weights by the model3 sine fade-out, and clears the motion
only after the fade completes; duplicate stops cannot restart it. A different old motion ID cannot
stop a newer run, while a same-ID replay is the current run targeted by a later same-ID stop.
PartOpacity curves follow the official Framework part-opacity sink and remain separate from weighted
parameter samples. Each frame restores the fresh-model part opacity values before applying the active
motion, preventing stop or replacement from leaving stale part visibility. Model3 Parameter groups
drive R5-compatible Model curves: EyeBlink multiplies matching parameter curves, LipSync adds to
them, and both update unmatched group parameters with the motion fade. Model Opacity travels in the
immutable render snapshot and is multiplied only in the final D3D11/Metal color pass, leaving mask
generation unchanged.
Product input is applied after motion curves so an actual pressed key or button remains authoritative
for hand parameters.

The Model behavior setting model.allow_motion_overlap enables independent motion
layers ordered by accepted start, oldest first (ADR-0088). Replays move their
matching layer to the newest position, so older held terminal poses cannot mask
newer starts from another group. Existing documents
and fresh installations use replacement playback until the setting is enabled.
The runtime publishes active_motions and derives active_motion from the latest
surviving start. Each stop and UserData occurrence belongs to one motion identity;
model commit and shutdown clear all layers. Audio remains one ordered stream.

Accepted motions now publish an ordered side effect to the independent bongocat-audio worker.
The worker uses rodio with only playback and FLAC enabled, owns one voice, and resolves no model
metadata itself. A new motion, explicit stop, disabled audio setting, successful model switch, or
shutdown stops the old voice. Missing/corrupt audio, output failure, or queue pressure is retained as
anonymous runtime diagnostics and never fails motion or rendering. Motion3 UserData crossings use
the effective runtime playback mode, so a one-shot run of a looping asset emits its start timestamp
only once; crossings remain monotonic, de-duplicated, and bounded.

Expression playback uses Application::set_expression with the model3 expression name. Every
declared exp3 resource is parsed and cached during model preparation; Add, Multiply, and Overwrite
parameters use the file's sine fade times. Replacing an expression fades the immediately previous
layer out while the new layer fades in, keeping at most two layers. Once its fade-in completes, the
newest expression's full weight is pinned until another valid expression replaces it, a model commit
succeeds, or shutdown begins; a test-clock rollback cannot restart that completed fade-in, and
expressions do not auto-clear to idle. An invalid request leaves the active expression unchanged. The
per-frame order is parameter/part-opacity defaults, motion, expression, typed product input, then
Cubism Core update.

model.random_behavior.mode and model.random_behavior.interval_seconds form one typed runtime
setting. The mode is a single enumeration whose off value is the gate: when it selects a kind, the
worker waits one complete interval on its injected monotonic clock and uniformly selects from the active
model's declared behaviors of that kind, each item equally weighted
(motions_and_expressions is one pool, not a 50/50 split between the two kinds). A successful model
commit, a settings change, or a re-enable re-anchors the schedule; a long pause does not emit a
catch-up burst. Automatic motion uses Idle priority and cannot replace a live Normal/Force
product motion, while expressions follow the normal latest-expression replacement rule. The
scheduler is disabled during a pending model commit and shutdown, and a model that declares no behavior
of the selected kind is a
no-op rather than a fallback to the other kind. Automatic behavior and shutdown requests share an
admission gate: the request records
shutdown immediately and starts its bounded wait, while an already-admitted action finishes before
the worker drains shutdown state and later actions are skipped. Runtime event sequences for automatic
playback are separate from the bongocat-audio command sequence allocator; overflow recovery retains
model-preparation commands so accepted audio preparation cannot leave a model commit pending. A
hidden overlay's non-zero motion fade is considered settled from the injected clock even when no
frame was delivered. The GPUI Model behavior page exposes the mode dropdown and the whole-second interval
through the revision-checked settings service; the interval row is disabled while the mode is
off but keeps its saved value, and the dropdown itself stays operable so the behavior can be turned back
on.

bongocat-live2d-playback owns the SDK-independent motion3/exp3 byte parser and numeric
curve/blend evaluation. bongocat-live2d-render prepares model-package RenderResources and
owns the shared key-image inventory/overlay resolver; bongocat-live2d writes the resulting
motion/expression values into Core. Runtime remains the sole owner of active playback identity,
priority, stop/crossfade timing, and model-generation cleanup.

The fixed-version Cubism Core, header, generated bindings, and preset model development baseline are
committed under vendor/cubism/5-r.5 and resources/models. Builds do not download SDK artifacts.
Their provenance and release gates are documented in
docs/adr/0011-progressive-implementation-release-gates.md and the Phase 0 Cubism records.

Model package parsing is also SDK-independent. bongocat-model prepares and validates package
metadata before a typed command transfers an opaque committed model to the runtime. The runtime
creates and evaluates Cubism state; GPU resource upload remains a separate renderer stage.

Model imports are copied into a unique staging directory under the current build environment's
models/ root. The importer rejects symbolic links and unsupported filesystem entries, reapplies
package limits while copying, flushes every file, validates the staged package again, and commits it
with a same-root directory rename. An existing model ID is never overwritten, and a failed import
removes only the staging directory owned by that operation.

The user-model catalog is rebuilt deterministically from the environment's installed directories;
no separate database can drift from disk. A writer lock under locks/ serializes import, catalog,
load, delete, and startup recovery. Corrupt packages remain visible as per-model diagnostics, while
well-formed abandoned import/delete directories are removed on the next start. Product code can
activate only an opaque CommittedModel issued by either the environment store after commit/load
or the bundled read-only preset catalog, and it must replace the active model before deleting it.

Technical Design (`docs/technical-design.md`) Copy Section

Technical Design

状态：架构决策稿，Phase 0 证据补齐与 Phase 1 渐进实现并行
最后更新：2026-09-25
首发平台：Windows 10 1903+、macOS 12+
后续平台：Linux（首发后评估）

BongoCat 采用单一 Rust 应用。GPUI 负责设置界面，Rust 平台模块直接负责输入、窗口、系统集成和 GPU 渲染。

1. 设计结论 Copy Chapter

Rust 2024 edition application
├── GPUI                         设置、模型管理、快捷键和诊断 UI
├── Product Runtime              状态、输入语义、动画和配置协调
├── Live2D Runtime               模型、动作、表情、物理和音效
├── Windows Backend              windows-rs、Raw Input、gilrs/WGI、D3D11
├── macOS Backend                objc2、CGEventTap、gilrs/IOHID、Metal
└── Shared Assets / Fixtures     模型、schema、本地化和测试数据

主要决策：

• BongoCat 自有应用代码统一使用 Rust。
• Windows 只发布 x86_64-pc-windows-msvc，不构建或发布 x86 与原生 ARM64；Windows on ARM 通过系统 x64 仿真运行该构建。
• GPUI 只负责常规设置 UI，不承担模型渲染。
• 模型窗口由 Rust 平台模块直接创建和管理，与 GPUI 设置窗口共享同一应用生命周期。
• Windows 模型窗口支持透明桌宠与普通窗口模式（ADR-0089）。普通窗口使用系统标题栏、等比例
  resize 边框、最小化/关闭按钮和不透明 D3D11 HWND swap chain，支持窗口捕获。背景为用户选择的
  RGB 纯色，默认绿色；模型自带背景和绘制层次保持不变。模式与背景通过既有 revision-checked
  overlay command 持久化，缺失新字段的 v1 数据仍按桌宠默认启动，macOS 不应用这两项。
  普通窗口暂停点击穿透、悬停/空闲隐藏、不透明度及圆角裁剪，不改写桌宠偏好。关闭隐藏模型窗口，
  不提前销毁 renderer 的 HWND；客户区几何用于 renderer 和持久化，最小化不写入 shell 的占位坐标。
  Windows 两种呈现共用客户区尺寸规则，保留未取整的模型画布宽高。数字及手势缩放按当前 DPI、
  100% 时 350 逻辑像素的基准宽度计算绝对尺寸；恢复、模式和模型切换保留客户区宽度，再按
  画布推导高度。尺寸上下限统一作用于比例，不分别截断两轴；系统边框在最后计算。原生尺寸
  变更及 DPI 建议矩形同样经过该规则，避免系统标题栏最小宽度再单独改动一轴。renderer 跟随
  实测客户区尺寸，最小化期间更新恢复几何；边框拖动回写的百分比再次应用时不叠加缩放。
  只有实际改变客户区尺寸的系统 resize 操作回写缩放；移动窗口（包括跨屏 DPI 调整）、未改变
  尺寸或取消的 resize 不回写缩放，不把恢复的窗口几何误当作新缩放比例。
  模型切换在原 HWND 上 prepare/validate/commit，失败保留当前可捕获模型；改变颜色、缩放和置顶
  同样不替换捕获目标。模式切换需要重建对应呈现资源。
• Windows 使用 D3D11，macOS 使用 Metal；首发不为了未来 Linux 强行统一 GPU backend。
• Windows 键鼠输入优先评估成熟输入库；若没有方案能同时满足事件边缘完整性、系统状态校正、
  Raw Input 设备语义和已确认的生命周期复位不变量，则直接使用 windows-rs 实现最小适配层，
  从架构上避免 issue #47 的永久卡键。
• macOS 输入优先评估成熟输入库；若没有方案能同时满足 listen-only CGEventTap、TCC 权限状态、
  tap 恢复和左右修饰键状态校正，则直接使用 objc2 封装最小适配层。
• 双平台手柄 backend 固定使用 ayangweb/gilrs 精确 commit：Windows 为 WGI，macOS 为 IOHID；
  bongocat-platform 只保留强类型事件/axis、连接 generation、Reset 重播和产品阈值适配，所有
  驱动、mapping 与 backend 生命周期修复进入 fork（ADR-0066）。
• 官方 Cubism Core 是预编译厂商二进制，是“应用代码纯 Rust”的唯一 FFI 例外；BongoCat 业务逻辑不得进入 SDK bridge。
• Linux 不进入首发范围，但共享业务 crate 不得依赖 Win32/AppKit 类型，不得故意封死后续 backend。

2. “纯 Rust”的定义 Copy Chapter

本项目中的“纯 Rust”定义为：

• 应用入口、UI、状态、动画、输入、配置、模型管理、窗口、渲染和系统服务的产品边界均由本
  Rust workspace 组装和拥有；实现可以使用经过评审的第三方 Rust crate。
• UI、运行时和平台服务均由同一个 Rust workspace 构建和管理，第三方依赖不得形成第二套业务
  runtime 或绕过既定 command/event/snapshot 边界。
• 允许通过窄 FFI 调用官方 Cubism Core 平台二进制，因为 .moc3 运行依赖厂商 SDK。
• 操作系统 API、GPU driver 和系统 framework 不属于应用语言范围。

因此对外准确表述应为“BongoCat 应用代码使用 Rust 重写”，而不是“最终二进制完全不含任何非 Rust 代码”。

3. 目标与非目标 Copy Chapter

3.1 目标 Copy Section

• 使用 Rust 实现完整的桌面应用、设置 UI 和实时运行链路。
• 使用一套 Rust 业务实现覆盖 Windows 和 macOS。
• 保持现有模型、动作、表情和用户资源格式尽可能兼容；配置使用全新的配置 schema 和命名。
• 修复输入事件丢失导致的永久卡键，包括 issue #47 的截图快捷键场景。
• 设置界面具备一致、清晰、可主题化的桌面体验。
• 模型窗口具备低延迟、透明、置顶、穿透、多显示器和高 DPI/Retina 支持。
• 所有后台服务具有明确的 start、stop、restart 和 shutdown 生命周期。
• 使用 fixture 验证跨平台行为，而不是只依靠人工观察。

3.2 非目标 Copy Section

• 首发不支持 Linux，不承诺 Wayland 全局输入能力。
• 不提供进程内插件 ABI。
• 不要求 Windows/macOS 像素完全一致。
• 不把 GPUI fork、Zed 私有 UI crate 或第三方输入库变成业务 API。
• 历史版本只作为行为与模型资源参考；BongoCat 不读取或导入旧 Tauri/Pinia 配置。
• 不在技术 spike 通过前完整迁移所有产品功能。

4. 设计原则 Copy Chapter

5. GPUI 决策 Copy Chapter

5.1 为什么选择 GPUI Copy Section

GPUI 用于设置窗口、模型管理、快捷键编辑、权限状态、更新和诊断：

• Rust 原生、GPU 加速，适合视觉统一的桌面工具界面。
• Windows 后端使用 Win32、DirectWrite、D3D11/DirectComposition，macOS 使用 AppKit/Metal。
• retained/immediate 混合模型适合设置表单、列表、实时预览和自定义控件。
• 已有目标桌面平台 backend，并为后续 Linux 留出路径。
• Zed 的实际产品规模证明其能够支撑复杂桌面 UI。

5.2 GPUI 边界 Copy Section

GPUI 仍是 pre-1.0，公共渲染 API 也没有稳定的 Windows/macOS 外部 Live2D 纹理合成路径。因此：

• 正式 workspace 只直接依赖 crates.io 的 gpui-kit = "=0.7.3" 并提交 Cargo.lock；GPUI Kit
  是唯一直接 GPUI 依赖，其 suite 内五个 package 都从同一 registry 版本解析。禁止另行声明或替换
  gpui、platform、component 和 assets。
• v0.7.0 是首个同时发布 SettingGroup::variant() 与 Popover::arrow() 的 release，此前为拿到
  这两项能力而固定的 longbridge/gpui-kit git revision 已删除，deny.toml 不再放行该仓库。
  GPUI Kit 仍通过 crates.io 的 gpui-pre 0.3.9 同步包提供元数据对应 Zed gpui 0.2.2 的整套
  GPUI crate，并把这套家族精确 pin 在 =0.3.9。
• 不自动跟随 Zed main，不直接依赖 Zed 应用内部 UI crate。
• 以 gpui_kit::component 提供的主题和基础组件为 design system 基础；窗口使用其官方
  Root，图标使用 gpui_kit::assets，项目只保留领域适配、产品 token 覆盖和组件库未覆盖
  的薄业务控件。应用统一调用 gpui_kit::init，平台入口只从 gpui_kit::platform 获取。
• GPUI Entity 只保存视图状态；真实输入、动画、配置和模型状态由 runtime 管理。
• 正式 bongocat-ui-protocol 定义设置 command/snapshot 协议，bongocat-ui 只负责 GPUI 视图与
  presentation policy；bongocat-app 的有界 service worker 独占配置写入和 runtime command，
  UI executor 不执行阻塞 I/O。
• SettingsSnapshot.revision 是 UI 快照排序用的单调版本，能够因 runtime、平台状态、诊断或
  catalog 变化推进；可编辑配置另携带可选 config_revision，仅由当前环境的持久化配置版本
  驱动。修改配置的 command 必须携带 expected_config_revision，在任何 config/runtime 写入
  前执行 compare-and-swap，避免输入诊断等无关变化制造假冲突。
• appearance.theme 通过独立 SettingsTheme 投影和 revision-checked typed command 修改，由
  Application owner 原子持久化，不进入 runtime。GPUI 收到新 snapshot 后调用组件库公开的
  Theme::change 即时更新内容；选择在快照往返前先乐观应用（system 在 macOS 上先清应用级
  覆盖再解析，见 ADR-0048 修正）；light/dark 同时请求匹配的原生窗口外观，system 清除
  覆盖并仅在该模式下响应系统外观通知。Entity 只缓存已经应用的显示模式以避免重复刷新，不成为
  配置事实来源。
• 原生表面（窗口框、系统弹框、右键菜单、托盘菜单、文件选择框）的主题由 bongocat-platform
  的 theme 模块独占（ADR-0048），UI 层不再直接调用平台外观 API。该模块只接受已解析的
  AppTheme（System 不往下传），并按平台能力矩阵落地：macOS 用进程级
  NSApplication.appearance，一处覆盖窗口框、弹框、菜单和面板；Windows 用
  DWMWA_USE_IMMERSIVE_DARK_MODE 覆盖窗口框——该属性一旦显式写入便不再自动跟随系统，因此
  偏好为 system 时（平台层收到的是 None，System 不往下传）以 gpui 同源的
  UISettings 查询实时重推导并写入该属性；其余表面接受跟随系统主题，由进程在创建任何
  窗口前调用一次未文档化的 SetPreferredAppMode(AllowDark) 使其生效。system 的解析口径统一
  在平台层（macOS 查 NSApplication.effectiveAppearance）且全 UI crate 只有一处解析入口，
  render 路径与 smoke 断言共用它——不读 gpui 的窗口外观缓存，因为该缓存只在延迟触发的
  appearance_changed 中更新；也不复用 gpui 的外观名映射，因为它不识别
  AccessibilityHighContrastDarkAqua，会把开启「提高对比度」的暗色系统判成浅色。主题失败一律
  降级为该表面保持系统外观，不报错、不改配置、不阻止启动。
• appearance.language 只接受 system、zh-CN、zh-TW、en-US、ar-SA、vi-VN、pt-BR、ko-KR 和 fr-FR 九个当前 v1 值，默认 system。
  平台 adapter 在启动时读取系统首选 locale，并按 primary subtag 归类（RFC 4647 language-subtag
  fallback）：ar、ar-EG、ar-SA 等阿拉伯语 locale 归为 ar-SA，vi 与 vi-VN 归为 vi-VN，
  pt 与 pt-PT 归为 pt-BR，ko 归为 ko-KR，fr、fr-CA 等法语 locale 归为 fr-FR，简繁之外的英语 locale 归为 en-US。zh 是
  primary subtag 唯一无法判定的情形：简繁是不同书写体系而非地区变体，因此 zh-Hant 与 TW/HK/MO
  归为 zh-TW，其余 zh 标签归为 zh-CN。
  其它 locale 也回退 en-US，不把解析结果写回配置。UI 通过独立 SettingsLanguage、revision-checked typed
  command 和 GPUI Kit Select 修改并立即刷新窗口标题、导航和当前可见文案。
  未知持久化值直接拒绝，不增加 alias、开发中间版本兼容或旧配置导入。
  语言下拉里每种语言用自身文字书写（endonym），因此看不懂当前窗口语言的用户仍能找回自己的。
• 启动项等系统能力通过 UI 自有的 typed platform snapshot 显示，由 settings service worker
  读取和显式变更；外部状态变化递增 settings revision。读取失败只形成可重试状态，写入失败
  不改变 config/runtime，Development macOS 的 unsupported 状态不允许发出变更 command。
• 输入诊断通过 UI 自有的计数型 snapshot 投影 captured/reconciled/fallback/reset、sequence 和可靠队列
  transport 指标；不得包含具体按键、原始事件或时间戳。即使 queue full 等 transport-only 变化
  未推进 runtime revision，settings service 也必须观察投影变化并推进 settings revision。
• 设置 UI 采用 visual-first 契约（ADR-0054）：项目只定义并绘制用户可见、可操作的内容。
  BongoCat 不维护项目自有 AccessKit tree、native bridge、辅助技术 action、隐藏 label/action
  或只为辅助技术存在的文案；gpui-kit 传递提供的默认语义不作为项目 UI contract。
• 可见控件、键盘导航、focus、loading/error 和 value 共用同一份 UI snapshot；实现和 smoke
  只为可见行为建立断言，不复制辅助语义状态。
• GPUI 不加载 Cubism、不持有模型 GPU 资源、不驱动模型帧循环。
• 全局快捷键使用配置边界编译出的 CompiledShortcuts，由操作系统注册（Windows
  RegisterHotKey、macOS RegisterEventHotKey，见 ADR-0044），单一 owner 线程持有平台
  manager 并把共享 ShortcutTable 增量映射为真实注册；只有匹配当前 active model 的
  motion/expression target 才能转成 typed runtime command。只有物理按下边沿才分发：
  两个平台都会在组合键被按住期间按系统重复节奏继续投递 pressed 事件，重复事件必须被丢弃
  而不是再次触发目标，因此一次按住永远只产生一次动作。应用级 target 必须经 coordinator 的
  配置 revision-aware
  command 执行，平台层不得直接改 overlay 或设置状态。配置提交后通过共享 ShortcutTable
  原子替换 compiled bindings，owner 线程在下一轮轮询读取新表；快捷键注册与输入服务生命周期
  解耦，替换不涉及输入管线的 pressed set。增量映射以 chord 为身份：仍留在表内的 chord 复用既有
  注册（平台会拒绝重复注册，或产生重复的注册），只把其 target 更新为新表的目标；离开表的 chord
  必须注销并从 owner 的记录中移除，否则同一组合键再次进入表时不会被重新注册。跨模型复用同一
  组合键是合法配置，模型切换正是靠这一步把共享 chord 从旧模型改指新模型，否则它们会被下游的
  active-model 判定当作非活动模型丢弃。应用级 target 通过有界
  typed handoff 进入 settings service；显隐、镜像、穿透、置顶以及三个模型输入忽略开关由唯一
  Application owner 按当前配置 revision 持久化，后三个 target 分别切换 model.ignore_pointer、
  model.ignore_keyboard 和 model.ignore_gamepad，不停止平台输入采集。open_settings 交给
  GPUI coordinator，避免平台线程直接触碰 UI 生命周期。open_settings 通过线程安全的一次性请求位
  交给 GPUI frame source，后者在
  owner 线程切换设置窗口可见性：窗口已显示时关闭并销毁，两个平台都走同一套 GPUI close 路径；
  窗口不存在时才创建并显示。设置窗口的当前侧边栏页面由 app coordinator 持有的 process-local
  SettingsNavigationMemory 记忆，重建窗口时恢复，应用重启后回到 Appearance。forwarder 必须支持
  有界停止与 join。
• 快捷键页面由两个带标题的 group 组成，每个 group 的第一行是它自己的门禁开关：启用窗口快捷键
  （shortcuts.commands_enabled，默认 true）与 启用模型行为快捷键
  （shortcuts.model_behaviors_enabled，默认 false）。两个门禁彼此独立，各自只决定对应的一半是否
  进入活动的 CompiledShortcuts：都不清空、不改写配置中的绑定，因此重新打开时无需重录即可恢复
  全部已校验绑定。门禁的唯一实现点是 ShortcutConfig::active_bindings——"此刻生效的绑定"的唯一
  投影，模型侧的活动模型过滤也在同一处，应用层与平台层不得再判一次。门禁变更必须经
  revision-checked settings command 原子持久化并替换共享 shortcut table。
  两个开关都是正向字段的直出：可见 UI 和 settings command 读同一个布尔值，全链路不存在取反；
  开关只带标题、不带描述（标题已经表达了它的作用），因此两个分组第一行都是纯标题行。
  门禁关闭时该作用域的行在 UI 上置灰且不可交互（捕获与清除都不再可用，tab 跳过），
  mutator 用同一谓词守卫；这是「开关门禁」统一禁用绑定规则（ADR-0053，并经 ADR-0054
  收窄为“可见行与 mutator 同源”）的落地。
• shortcuts.model_behaviors_enabled 默认关闭是对旧版行为的刻意收窄：旧版在模型加载完成后无条件为
  每个 motion 和 expression 自动分配一整层 primary + [Shift/Alt] + 数字/字母 组合键，用户没有
  拒绝的机会。BongoCat 按维护者决定移植这套自动分配，但把"是否让这些组合键真正生效"交给用户。
  该开关只作用于 motion/expression 绑定，不得清空或改写配置中的绑定，也不得连带禁用
  open_settings、overlay 显隐以及三个模型输入忽略开关等应用级快捷键——应用级快捷键有它自己的开关。
• model.behavior_names 是每个模型每个行为一行的自定义显示名，behavior_id 与快捷键绑定、随机播放
  勾选共用同一种拼法。设置窗口把它解析成 SettingsModelBehaviorName（只含已命名的行、只含当前模型），
  shortcut_rows 优先用它作为行标签，未命名的行保持「动作 N / 表情 N」。空白名字不落盘，清空字段等于
  删除这一行；删除模型时一并清掉它的名字。窗口侧的限长与配置侧一致
  （MODEL_BEHAVIOR_NAME_MAXIMUM_CHARS），因此窗口不会送出配置会拒绝的值。改名在行内完成（ADR-0085
  §4）：行名称后面有一个编辑图标（提示就是「重命名」一词，且是唯一入口），点击它把名称就地换成文本框；
  字段自身不带控件与说明文案——Enter 保存、Esc 放弃、焦点被别处拿走视为保存，字段仍是原标签时不发送
  请求。一次只有一个字段打开，打开另一行的编辑会先提交已打开的那份编辑。录制/播放/清除三个控件的位置与
  tab 序号保持不变，改名面不新增 tab stop。
• 模型行为快捷键的自动分配与旧版同构：模型激活时（prepare_model / select_model）按声明顺序
  遍历该模型的 motion 与 expression，依次填入 [primary]、[primary, Shift]、[primary, Alt]、
  [primary, Shift, Alt] 四层、每层先数字后字母的组合键，共 144 个名额；primary 在 macOS 是
  Command、其它平台是 Control。编号对每个模型独立从第一个名额开始——占用范围是"应用级 command 绑定
  • 该模型自身的绑定"，其它模型已占用的组合键不计入，因为同一时刻只有当前模型的绑定生效。已有绑定
    的行为永不重写，因此重复激活是幂等的，只有用户尚未录制的行为会被补上；同一作用域内已被占用的组合键
    跳过而非重用，否则 shortcuts.conflict 会让整份配置失效。分配结果随选中模型同一次 commit 落盘，
    且不依赖 shortcuts.model_behaviors_enabled——绑定在快捷键页面始终可见，门禁关闭时该分组行置灰
    不可改（ADR-0053），是否进入平台匹配表则由同一分组第一行的 启用模型行为快捷键 开关决定。
• 只有当前模型的绑定进入平台编译表。配置按模型保存绑定且跨模型允许复用同一组合键，所以
  shortcuts.conflict 是作用域内的判定（命令内唯一、同一模型内唯一、模型绑定不得与命令冲突），
  整份配置本身不是一张无歧义的表：active_shortcuts 先按当前模型投影再编译。prepare_model 与
  select_model 都在激活成功后重建该表，因此被离开的模型立即停止触发它独占的组合键，被切到的模型
  无需重启即可用自己的组合键，非活动模型的绑定也不再占用全局热键。
• system.show_status_icon 通过独立的 revision-checked settings command 修改。settings worker
  以有界 request/reply bridge 请求平台主线程隐藏或显示状态图标，平台成功后才由 Application owner
  原子提交配置；配置提交失败时必须把图标恢复为旧状态。macOS/Windows 共用 tray-icon 0.26.1 托盘
  owner 与直接依赖的 muda 0.21.2 菜单 owner：TrayIcon、一个 popup 菜单根、菜单项 receiver 和强类型
  事件队列在整个运行期保持存活，set_visible 只改变平台表示（macOS 移除 NSStatusItem，Windows 保留
  注册并设置隐藏），重新显示不创建第二套业务状态或菜单 owner。托盘和 overlay 右键复用同一棵菜单树，
  由 muda 从 overlay 的真实 HWND/NSView 弹出，不借用托盘隐藏窗口。
  正式启动不创建或显示设置窗口，设置窗口、单实例唤醒和 application reopen 仍提供恢复入口；
  平台失败只返回稳定匿名 settings error。
• system.show_taskbar_icon 只控制 Windows 模型窗口的任务栏按钮，默认 false，不改变窗口
  可见性，也不映射为 macOS Dock 图标。默认关闭是刻意的：模型窗口是无标题栏的 WS_POPUP，
  它在任务栏里的按钮没有用户可操作的对应窗口，而设置窗口才是可用的任务栏入口，因此默认
  不额外占用一个任务栏位置。设置窗口始终保留 GPUI 创建时带的任务栏按钮与原生标题栏：
  给它套上 WS_EX_TOOLWINDOW 会连标题栏一起换成工具窗口的短标题栏，因此产品不写它的
  扩展样式。该偏好在桌宠模式切换模型窗口的 WS_EX_APPWINDOW/WS_EX_TOOLWINDOW；普通窗口模式
  固定使用 WS_EX_APPWINDOW，以保留普通标题栏和可恢复的任务栏入口，原偏好不被重写。
  settings worker 通过独立的有界 request/reply bridge 请求主线程在 overlay 会话上应用并回读，
  平台成功后才由 Application owner 按 expected revision 原子提交；配置提交失败时恢复旧值。
  启动必须把当前 v1 值写进 overlay 会话选项，模型切换重建 HWND 时沿用会话记录的应用值，
  平台失败只返回稳定匿名 settings error。
• system.show_dock_icon 控制 macOS 仅剩猫窗口时是否显示程序坞图标，默认 false，
  独立于 Windows 的 show_taskbar_icon。设置或更新窗口打开期间（包括最小化）保持 Regular
  并显示 Dock 图标；全部关闭后按后台偏好使用 Regular 或 Accessory（ADR-0054）。
  Application 主线程复用 GPUI 的窗口列表计算实际模式，打开普通窗口前启用 Dock，关闭回调中
  重新计算；开窗失败恢复后台偏好。切换偏好不关闭、隐藏或重建已有窗口，不枚举 AppKit 窗口
  或自行恢复焦点。配置仍先在主线程应用实际模式并回读，再原子提交；配置失败恢复旧偏好，
  返回稳定匿名 settings error。启动应用后台偏好排在 overlay 初始化之后。
• 关闭设置窗口不影响 runtime、输入、音频、frame source 和 overlay，它们继续由 app
  coordinator 持有。设置和更新窗口的普通 close 都销毁各自的 GPUI 窗口；设置窗口下次打开时创建新的
  Entity，更新窗口也按原有行为重新创建。两个平台共用 GPUI close 路径，平台差异不改变窗口生命周期。
  设置侧边栏当前页面由 app coordinator 持有的 process-local SettingsNavigationMemory 记录：
  SettingPage::title_suffix 在当前页渲染时回报页面，新的设置窗口用该 index 作为
  Settings::default_selected_index；应用重启后重新从 Appearance 开始。系统菜单的 presentation 轮询
  同样不得每秒重建完整快照：它先读取只返回 revision 的命令（ReadSnapshotRevision，只比较 service
  已持有的状态），仅在 revision 变化时才读取完整快照，完整快照中的模型目录扫描因此不再随 20 Hz
  轮询反复执行；CGPreflightListenEventAccess 这类 TCC 查询由 snapshot clock 按上限 1 s 缓存，
  只有显示用途的值不再要求每次快照都访问系统。Windows GPUI 0.2.2 的最终 WM_DESTROY 同步重入
  兼容退出路径仍只用于显式 Quit 后的产品 owner 关闭阶段；普通设置/更新窗口销毁必须由双平台原生
  smoke 验证。Windows 显式退出先请求 frame source 停止并停止输入生产者，确认 frame source 已退出后
  再 shutdown/join runtime、配置和音频 owner，最后释放 renderer/GPU 与 overlay；该兼容措施不得提前
  终止业务 shutdown；升级到修复此回调的固定 GPUI 版本后必须移除，并恢复正常 GPUI 析构门禁。
• 正式 executable 无参数启动时持续运行到显式 Quit 或系统终止；正数 --run-seconds 只用于
  有界 smoke/诊断，不能成为安装包或 Finder/Explorer 启动的隐式退出条件。所有正常退出仍须
  进入同一 shutdown coordinator。
• Windows 的 GPUI 平台循环独占线程消息派发；宿主产品调用的 overlay tick 不得再次 pump
  Win32 队列，并且必须在没有持有 GPUI App/Window borrow 时执行。独立 preview 的
  run_for 循环才负责主动 pump。这一约束防止 D3D11 tick 同步派发设置窗口消息后重入
  AsyncApp。
• 平台服务不返回 GPUI 类型，避免框架扩散到业务模块。
• GPUI 升级必须单独提交，附变更说明、双平台构建和 UI smoke test。

所有新的 crates.io 直接依赖同样先选择引入时最新的非 yanked 稳定版，再精确 pin 并提交 lockfile。只有 Rust toolchain、目标平台、许可证或已验证的安全边界不兼容时才允许暂缓，且必须留下可复核的版本差异和解除条件；不能用旧版本回避正常的 API 迁移。传递依赖在上游约束允许的范围内保持最新，不 fork 上游只为修改版本号。

Phase 0 必须验证输入法、文本编辑、缩放、UI/主题、窗口重开、托盘应用生命周期，以及 GPUI 设置窗口与独立 overlay 共存。ADR-0011 允许已通过自动化契约的模块进入正式 workspace；未解决的问题继续阻塞对应完整功能或 stable 发布，并必须在进入完整 UI 实现前解决并记录。

6. 总体架构 Copy Chapter

GPUI settings window
                              |
                       Commands / Snapshots
                              |
                     App coordinator/service
                              |
Platform input ---> Runtime thread ---> Model/Animation state
     |                    |                    |
     |                    +--> Config service |
     |                    +--> Audio service  |
     |                                         v
     +--> reconciliation                 Render snapshot
                                                   |
                                      Native overlay window
                                      D3D11 / Metal renderer

6.1 模块责任 Copy Section

• app：应用入口、服务装配、生命周期、单实例和 shutdown coordinator。
• runtime：唯一业务状态所有者，处理输入、快捷键、动画选择和模型命令。
• ui：显示 runtime snapshot，发送显式 command，不直接修改业务字段。
• platform：窗口、输入、托盘、权限、显示器、启动项、文件和更新。
• model：模型包解析、路径安全、资源索引和只读预置模型目录；不持有用户 store 的写入生命周期。
• model-store：用户模型 store、writer lock、staging/提交/删除、目录与 BongoCatMver 导入、键名归一化和用户侧封面覆盖。
• live2d-playback：motion3/exp3 字节解析、曲线/fade/loop/UserData 与 expression 混合的纯数值求值；不持有 Cubism Core 或 GPU 资源。
• live2d-render：将 CommittedModel 的纹理、背景和键位图资源准备为 RenderResources，并提供同源的键位图清单与 overlay 解析；不持有 Cubism Core 或 GPU handle。
• live2d：Cubism Core 生命周期、Core parameter/part 写入、motion/expression 到 Core 的适配和不可变 RenderSnapshot 生产。
• audio：motion 音效的有序 command、FLAC 解码、唯一 voice、输出设备和 shutdown。
• render：不可变 render snapshot 和 renderer contract。
• config：环境隔离、当前 v1 schema、验证、备份和原子提交。

6.2 依赖方向 Copy Section

ui protocol <------- app -------> runtime <------- platform adapters
                    |                 |
                    v                 v
             model-store ---------> model
                    ^                 |
                    |                 v
              user model data     live2d-render ---------> render contract
                                      ^                 ^
                                      |                 |
                                      +------ live2d ---+
                                      |
                                      +------ live2d-playback

                         D3D11 renderer / Metal renderer

业务 crate 不得导入 Win32、Objective-C、GPUI 或 GPU handle。平台实现可以依赖业务定义的 command/event 类型。runtime 可直接使用 live2d-playback 的 clip/evaluation 类型和 live2d-render 的键位图解析 contract；两层都不读取 runtime command、Core snapshot 或 GPU 资源。

7. 仓库布局 Copy Chapter

BongoCat/
  Cargo.toml                  正式 workspace 根
  Cargo.lock
  rust-toolchain.toml
  resources/                  随产品打包的模型与产品图标
  crates/
    bongocat-app/             入口、装配和 shutdown
    bongocat-input/           平台无关输入协议、producer 和 latest-value transport
    bongocat-ui-protocol/     设置/更新 DTO、typed command、reply 和 bounded client
    bongocat-runtime/         状态、输入 reducer、模型投影、动画和命令
    bongocat-config/          schema、环境隔离和原子存储
    bongocat-storage/         用户私有存储原语：权限、私有目录、原子替换
    bongocat-model/           模型包解析、只读资源索引和预置模型目录
    bongocat-model-store/     用户模型持久化、导入事务、Mver 转换和封面覆盖
    bongocat-live2d/          Cubism Core 边界与 Core-coupled model adapter
    bongocat-live2d-playback/ motion3/exp3 纯解析、曲线求值和 expression 混合
    bongocat-live2d-render/  模型资源准备、键位图清单和 overlay 解析
    bongocat-audio/           motion 音效队列、解码与设备 owner
    bongocat-render/          render snapshot/contract
    bongocat-ui/              GPUI 设置界面和 design system
    bongocat-update/          发布清单读取、版本/target 判定、载荷验签与安装策略
    bongocat-platform/        Windows/macOS 平台服务
  shared/
    config/                   JSON 配置 schema、命名与存储契约
    behavior/                 输入、动画和快捷键规范
    fixtures/                 输入序列、预期状态和模型样本
    resources/                模型、图标和本地化
  tools/                      不随应用发布的验证与考古工具
  docs/
    adr/
    benchmark/
    migration/                历史参考，不进入生产配置路径

crate 是编译和责任边界，不是动态库。首期不为目录美观建立空 crate；只有依赖方向或测试隔离确实需要时才拆分。

bongocat-ui-protocol 只承载设置/更新服务的进程内强类型 contract：snapshot、command、reply、
operation control、state handle 和 bounded client/endpoint。它不依赖 GPUI、OS API、配置、平台、
本地化或 update 库；bongocat-ui 负责把这些 contract 映射为 GPUI view，app service 负责把
config/platform/update producer 映射为 protocol 类型。debounce、语言显示文案、更新窗口轮询节奏和
文件选择后的展示判断留在 UI/适配器，不进入跨层 contract。

正式 workspace 位于仓库根目录，是仓库中唯一的产品构建入口。重构前实现仅在远端
pre-refactor-tauri 分支中保留，当前工作树不包含其源码、资源或构建入口；master 承载当前代码，
不作为旧实现参考。该路径安排不改变 crate 边界或产品架构。

8. Runtime 与并发 Copy Chapter

8.1 状态所有权 Copy Section

单一 runtime 线程拥有 AppState、InputState、AnimationState 和当前模型控制状态。其他线程不能通过共享可变引用修改它们。bongocat-input 只拥有平台无关的事件协议、可靠输入 hand-off、latest-value transport 和匿名诊断；InputState、输入到模型的投影以及 worker/shutdown 生命周期仍由 bongocat-runtime 独占。

Input producers ---- reliable edge queue -----+
UI commands -------- reliable command queue --+--> runtime tick
Cursor motion ------- latest-value slot -------+        |
Gamepad axes -------- latest-value slot -------+        +--> UI snapshot
                                                        +--> Render snapshot

• Key/button down/up、设备连接和 command 必须可靠、有序；溢出是可观测错误，不能静默丢弃。
• 可靠队列溢出时必须清空无法证明顺序的缓存，并在队首注入 Reset；原始失败 item 返回 producer，溢出、恢复和被清理 item 数量进入诊断 snapshot。
• 鼠标移动和摇杆轴可以合并为最新值，不能阻塞边沿事件。
• input.mouse.force_move 打开时，平台 adapter 不发布绝对光标位置，而是把设备报告的相对位移
  累加成一个位置再发布（CursorMotionAccumulator）：以前台应用捕获指针、把光标钉在一处时，
  绝对位置不再变化但设备仍在报告每次移动，按绝对位置跟随的模型会停住。累加器以绝对位置为种子，
  在第一个采样和 viewport 变化时重新对齐，并夹在该 viewport 内；开启与关闭、以及输入 Reset
  都清空累加值。累加在平台线程完成而不是 runtime：CursorProducer 是 latest-value 通道，跨两次
  发布之间的位移必须在发布前合并，否则被合并掉的采样会连同位移一起丢失。累加值仍走同一条
  latest-value 通道和同一套平滑，因此 runtime、renderer 和 ModelSettings 都不知道这个开关存在。
• runtime 在独立 latest-value 通道之后按可注入单调时钟平滑光标位置；以 60 FPS 为基准每帧
  保留 0.75 的剩余距离，并在逻辑坐标距离小于 0.5 时收敛到目标。首个样本和显示器
  viewport 变化直接对齐目标，避免跨显示器插值使用错误坐标系；renderer 只消费平滑后的参数。
• 手柄 axis latest-value 以 {device_id, connection_generation, axis} 为 key 并限制总 key 数；共享 runtime transport 为每个 device id 的每次连接分配单调 generation，平台将同一 connection 通过可靠 GamepadConnected/GamepadDisconnected 事件和 axis key 传递。断开只清理该 connection 的 pressed/axis，不重置其他输入；键鼠状态校正不扫描 gamepad pressed state。旧 generation 的迟到边沿和 axis 样本必须计数并拒绝。
• Runtime 在 latest-value 消费后统一应用 GamepadAxisSettings 的 stick/trigger dead-zone；gilrs
  adapter 关闭默认 jitter/dead-zone filter 和环境 mapping，只负责 fork mapping 后的完整范围值、
  trigger 连续值与无效值诊断，不把设备默认 dead-zone 写入共享协议。轴值随后以
  ModelInputSnapshot 的不可变字段投影给 renderer。
• 手柄六个轴按 {device_id, connection_generation, axis} 分别取最新样本，不先挑一个
  connection 再只投影它的六个值；多手柄同时连接时后动的那只在它动过的轴上立即生效，回中
  读到 0（ADR-0082，与重构前合并全部手柄的同名轴一致）。
• CatParamStickShowLeftHand/CatParamStickShowRightHand 是模型声明的摇杆可见性，由
  apply_model_input 写入：该侧摇杆偏离中心（死区之后）或摇杆键按下即为 1。同一个条件也
  让该侧 hand-down 落下，但只在模型声明了该参数时——把 ADR-0042 的「缺图不动爪」从按键图
  片推广到摇杆美术，使键盘/鼠标模型上的摇杆完全惰性。三个事实仍互相独立：*Stick*Down 只
  表示摇杆键，CatParamStickL*/R* 只表示位置（ADR-0082）。
• 手柄连接状态的事实来源只有 runtime 的 InputState：RuntimeSnapshot::input 的
  connected_gamepad_count 是上层唯一可读的形式（ADR-0071）。产品 frame source 每帧已经读取
  该 snapshot，因此在「无手柄 ↔ 至少一个手柄」跨帧变化时向 settings service 发送一次无载荷
  GamepadConnectionChanged；第一帧只建立基线，发送失败保留待发状态并在下帧重试。
  settings service 处理时重新读取 runtime 计数，重复、迟到与补发的通知因此落在同一结果上。
  它是产品行为，因此走 Application::select_model 的同一条路径（配置 revision-checked 提交、
  行为快捷键分配、失败回滚、selected_model 持久化与两阶段 commit），不新增第二条切换路径，
  也不在 platform callback、UI executor 或 GPUI Entity 内加载模型。
• 平台 input worker 通过独立 latest diagnostics producer 发布项目稳定计数；该通道不占用可靠
  command/input edge 队列，Windows service tick 与 macOS run-loop slice 都刷新 live snapshot。
  callback 原子计数、worker 恢复计数和 cursor latest 统计在平台 owner 内合并后进入
  RuntimeSnapshot::platform_input；停止输入时须先发布包含 clean_shutdown 的最终快照，再停止 runtime。
• 动画和延迟使用单调时钟 Instant，持久化时间才使用墙上时钟。
• Runtime 可接收 typed Tick command，在使用注入单调时钟的 contract/fixture 或受控
  coordinator 场景显式驱动一次评估；生产环境仍由 runtime worker 的定时等待负责周期 tick，
  UI 和平台 adapter 不直接调用 renderer。
• overlay.maximum_fps 是 15..=240 的 runtime-owned 强类型设置，通过 revision-checked settings
  command 持久化并进入 RuntimeSnapshot。它同时决定 runtime 周期评估、GPUI owner 调度的产品
  overlay frame source 和独立 overlay run loop 的下一帧间隔；变更无需重启。间隔是相对帧截止
  时间的等待，不是帧完成后的延时：一帧的开销由等待吸收，因此只要单帧工作在间隔内完成，实际
  节拍就等于设置值——按「完成后起算」会让实际节拍变成 interval + work，设置越高偏差越大。
  命令驱动的求值可以提前于截止时间出帧以压低输入延迟，这种帧不消耗周期槽位，因此周期节拍不变，
  被呈现的帧率仍由 frame source 自己的节拍决定。renderer 仍只消费
  不可变 RenderSnapshot，不读取 config 或 GPUI 状态。overlay 隐藏时，runtime 周期等待和产品
  frame source 统一降至 100 ms；可靠 command 仍会立即唤醒 runtime，产品重新显示的轮询延迟
  上限为 100 ms。
• motion_start 触发的动作只播放一个循环：到达 clip 声明时长后，动作进入 completed 状态并
  保留该次完整求值产生的最终参数、part opacity 与 model opacity，作为当前 motion layer 在后续
  每帧默认值恢复后继续重放；它不会继续推进，也不会自动退回 idle。这里的“最终样本”包含
  model3/curve 自然 fade 的权重，完成语义不会绕过自然淡出而暴露更早的原始曲线端点。clip 的
  Meta.Loop 不改变这一点（它描述资源如何制作，不描述产品如何触发），否则动作会永远停在循环中。
  completion 由注入单调时钟和 clip duration 推导，不依赖下一帧是否已投递，因此 overlay 隐藏、
  睡眠或大时间步之后的命令不会仍把动作误判为 in-flight。completed motion 不再占用 priority
  保留位，下一次请求可替换或重新播放它；显式 motion_stop 仍可让最终姿态按资源 fade 退出。
  同一动作在同一 priority 上仍在播放时，重复请求被忽略（R5 motion queue 的 equal-priority
  规则），因此按键重复和连按既不会重启 clip 也不会重放 motion 音效。预览播放同样只播放一个
  循环并保持最终姿态，但每次请求都重新开始。显式停止的非零 fade 即使在 overlay 隐藏、没有
  下一帧时，也会按注入单调时钟在 fade duration 结束后视为 settled，避免过期 motion 阻塞随机行为。
• model.allow_motion_overlap 默认关闭，旧 v1 文档缺少字段时按 false 读取。
  打开后不同 motion identity 独立保留 clip、单调开始时间、完成状态、stop fade 与 UserData 游标；
  共享参数按接纳启动的先后顺序求值，后启动层用资源自己的淡入淡出权重覆盖前层；重播匹配
  identity 会移到末尾，幂等重复和 stop 不改变顺序。顺序来自插入次序而不是时间戳，因此同一
  时钟采样内的启动也有确定次序，旧层终态不会永久遮住其他动作组的新播放。
  优先级只仲裁匹配 identity，重复产品触发保持幂等，预览只重启匹配层。
  关闭开关立即只保留最近启动的存活层；成功模型 commit 和 shutdown 清除全部层。
  snapshot 的 active_motions 显示完整集合，active_motion 派生为最近启动的存活层；
  UserData 保留来源 identity。随机动作仍让位于任何未结束的手动动作，音效沿用单路有序
  worker（ADR-0088）。
• motion_stop 只作用于匹配的当前动作，包括已完成并保持最终姿态的 motion。非零
  FadeOutTime 在 runtime snapshot 中保留
  active identity 和首次 stop command sequence，renderer 以正弦权重淡出并在结束帧后
  清理；重复 stop 不重启计时，零时长立即清理。不同 motion identity 的旧 stop 不影响新动作；
  同一 ID 重播后仍是当前 run，之后到达的同名 stop 有意停止该 run。
• model.random_behavior.mode 不为 off 时，runtime 以可注入单调时钟按
  model.random_behavior.interval_seconds 从当前模型声明的对应类别列表中均匀选择
  一个行为（每个声明项等权）。mode 先收窄候选集合再抽取，因此选中项一定属于用户允许的类别；
  模型没有声明所选类别的行为时保持无操作，不退回另一类。第一次选择等待一个完整间隔；成功模型切换、
  设置变更和重新启用都会重锚定时器，长暂停只产生一次选择而不追赶补发。自动 motion 使用 Idle
  priority，不能替换正在进行
  的 Normal/Force 产品 motion；随机 expression 继续遵守最新 expression 替换语义，模型没有行为
  时保持无操作。待处理模型 commit 或 shutdown 时不选择新行为；自动行为与 shutdown request
  通过同一 admission gate 排序。shutdown request 只记录状态并立即开始有界等待，已被接纳的动作
  会在 worker 进入 shutdown drain 前完成，后续请求不会插入新的自动副作用。自动行为的 runtime
  event sequence 与 audio command sequence 分离，所有生产 audio command 使用
  MotionAudioClient 的独立序号分配器，并在同一 publish lock 下完成分配与入队。随机选择器使用
  runtime 内部 seed，测试可以通过固定 seed 和单调时间得到同一序列。
• 用户主动触发的 expression command 除了更新当前 active_expression，还写入 runtime snapshot 的
  user_expression_memory：该次选择时的模型身份、表情名与 command sequence。随机行为走
  renderer 而不是 command 队列，因此不会产生这条记录。
• model.toggle_repeated_expression 打开时，SetExpression 请求的表达式等于当前
  active_expression 时该命令变成「关闭」而不是「重新应用」：runtime 让所有表达式图层开始淡出、
  不压入新图层，active_expression 置空，并且不写 user_expression_memory。关闭动作因此不会
  进入 model.last_expressions，记住的仍然是用户最后选择穿上的那张脸。判定放在 runtime 而不是
  Application，因为两个触发源（设置窗口的播放按钮与快捷键）都收敛为这一条 command，只有 runtime
  知道当前生效的是哪个表情；模型切换会先清空 active_expression，被延迟到 commit 之后执行的
  「恢复上次表情」因此永远不会被读成重复触发。该记录描述「用户选过什么」而不是
  「屏幕上是什么」，所以它不随模型切换清除——切换会清掉 active_expression，而做出这次选择的
  模型仍需要把记录写进配置。Application 按模型身份把它并入
  model.last_expressions；模型成为当前模型时，若 model.remember_last_expression 打开且该模型
  有记录，Application 发送一次 SetExpression，runtime 在该模型 commit 后应用。记录只由
  SetExpression 产生，因此它是「用户主动」的唯一判据，不需要额外的来源标记。
• render snapshot 不含锁和平台对象，通过双缓冲或 latest-value channel 交给渲染线程。
• ModelSettings 是 runtime 的强类型模型交互设置：mirror 只影响不可变
  RenderSnapshot::mirror_horizontal 的水平变换，mirror_pointer_tracking_horizontal 只反转
  指针的 X/Z 产品参数，mirror_pointer_tracking_vertical 只反转指针的 Y 产品参数；两者相互独立，
  都默认 false。ignore_pointer 跳过所有指针参数覆盖；ignore_keyboard 和
  ignore_gamepad 只在模型输入投影中屏蔽对应来源的按键/按钮/手柄轴贡献，不停止可靠采集、
  pressed-state 恢复、诊断或快捷键注册。六项通过 SetModelSettings command 和
  revisioned snapshot 传播，renderer 不读取配置；三个输入门禁还可由对应的 application
  shortcut target 经 settings service 切换，持久化后仍只改变模型输入投影。
• GPUI 通过 command/snapshot 边界交互，不直接持有 runtime mutex。
• GPUI 拥有平台主事件循环；应用 coordinator 在该主线程调度 overlay tick，GPUI
  Entity 不持有 renderer、render snapshot 或 frame-loop 状态。
• shutdown 顺序：阻止新的 frame tick -> 停止输入 -> 确认 frame source 已退出 -> runtime
  drain/停止 -> 保存配置 -> 停止音频并 join -> 释放 renderer/GPU -> 销毁 overlay -> 关闭 GPUI。

8.2 输入事件 Copy Section

enum InputEvent {
    KeyDown { key: PhysicalKey, at: Instant, repeat: bool },
    KeyUp { key: PhysicalKey, at: Instant },
    MouseDown { button: MouseButton, at: Instant },
    MouseUp { button: MouseButton, at: Instant },
    CursorMoved { position: PhysicalPoint, at: Instant },
    DeviceConnected { id: DeviceId, at: Instant },
    DeviceDisconnected { id: DeviceId, at: Instant },
    Reset { reason: InputResetReason, at: Instant },
}

应用优先保存物理键身份；字符、布局和显示名称属于映射层。左右 Ctrl/Alt/Shift/Meta 必须可区分。

9. 输入可靠性 Copy Chapter

9.1 issue #47 Copy Section

PixPin、Win+L 或其他系统级快捷键可能让应用收到按下边沿，却收不到对应的释放边沿。输入系统不能把事件流视为永远完整，必须通过系统状态查询和生命周期复位保证 pressed state 最终一致。系统查询集中在输入服务中，renderer 不直接读取键盘状态。

9.2 Windows Copy Section

1. 使用 windows-rs 调用 RegisterRawInputDevices，后台窗口接收 WM_INPUT。
2. 从 scan code、extended flag 和 RI_KEY_BREAK 建立物理键边沿。
3. runtime 维护 pressed set，但事件流不是唯一事实来源。
4. 校正使用单调时钟周期调度；默认每 250 ms 查询一次，并要求同一个 key 连续 2 次快照缺失才确认释放，避免单次系统查询异常误清除。时钟回退不得推进调度游标。
5. 对 pressed set 中确认释放的键生成内部 KeyUp。
6. 会话锁定、桌面切换、睡眠、设备移除、服务重启和队列异常时发送 Reset；这些生命周期复位不等待确认阈值。
7. 必要时用 WH_KEYBOARD_LL 补充合成事件，但 hook 不得覆盖 Raw Input 物理状态。
8. RegisterHotKey 只处理应用快捷键；冲突必须反馈 UI 并保留旧绑定。
9. 手柄由 ayangweb/gilrs 固定 commit 的 WGI backend 提供。adapter 将位置名、连接/断开和按钮
   送入可靠序列，将 stick/trigger 送入带 connection generation 的 latest-values；每 tick 最多
   drain 256 个 event，产品最多活动 4 个手柄。gilrs 默认 dead-zone、force feedback 和环境 mapping
   关闭，D-pad 使用 gilrs 自带转换；backend 构造失败只禁用手柄并计数，不能停止键鼠服务。Windows
   WGI 的 bounded join/错误 acknowledgement、hidden/unfocused Raw Input window 与 click-through
   overlay 下的实机投递仍是发布门禁；初始 held-state snapshot 也必须由 backend 提供。

Windows 的 WM_QUERYENDSESSION 与已确认的 WM_ENDSESSION 只记录系统终止请求并立即返回；
GPUI owner 在下一帧进入既有 shutdown coordinator，Win32 callback 不阻塞或析构 runtime/GPU 资源。

该方案不承诺安全桌面交付每个释放事件，而是保证丢事件不会产生永久卡键。
清除一个已按下 control 的路径是且只有三条：可靠 KeyUp、系统状态校正和生命周期 Reset。
经过的时间不构成释放：用户仍按住的按键与丢失的松开事件在时长上无法区分，用时长区分会把一帧
变慢变成一个猫不再相信的按键。因此没有按键释放超时配置，runtime 也不维护基于单调时钟的按键
期限或与之相关的匿名计数。

Windows 验收覆盖 PixPin Ctrl+Alt+A、Win+L、PrintScreen、UAC、管理员/非管理员进程、睡眠唤醒、多键连按和队列压力。

9.3 macOS Copy Section

• 使用 listen-only CGEventTap，不经过 GPUI 响应链。
• 区分 Input Monitoring 的 unknown、denied、granted、restart-required 状态。
• 全局输入监听只请求 Input Monitoring：CGPreflightListenEventAccess 只读查询，权限请求只由用户
  发起的明确设置操作触发。设置窗口不安装项目 AccessKit bridge，也不需要、不得请求 Accessibility
  trust；Input Monitoring 状态与输入服务运行状态分别投影，授权变化不等于 tap 已重启（ADR-0024）。
  可见 settings 窗口最多每秒一次读取只读 preflight 并通过 revisioned snapshot 刷新该状态；轮询不发起
  TCC request、不重试或重启 event tap，窗口释放后停止。
• PlatformInputDiagnostics 以稳定 service_status 和单调 service_start_attempts 公开输入服务
  的 not-started/running/permission-denied/backend-unavailable/failed/stopped 状态，不携带平台错误文本。
  平台 owner 每次产品启动只尝试一次；权限拒绝或 backend 启动失败不阻止 overlay/runtime，settings
  health 进入 degraded 并以匿名状态进入 revisioned snapshot，不在后台循环请求权限或重启服务。
• 设置窗口只展示用户可操作的设置，导航分两级（ADR-0066）。一级页面按用户任务固定为
  Appearance & language、Model library、Model behavior、Model window、Input & interaction、
  Shortcuts、App & system 七个业务分类，About 作为设置菜单中的最后一个普通页面。Appearance & language
  直接展示主题与语言，不再重复同名分组；Model library 单独展示模型卡片，Model behavior 单独展示模型镜像、动作音效，以及随机播放内容的模式下拉（关闭 / 仅表情 / 仅动作 / 表情和动作，ADR-0072）和它控制的间隔，模型行为快捷键仍留在 Shortcuts；Input & interaction 按 Mouse、Keyboard、
  Gamepad 分组；Gamepad 分组末尾是「连接或断开手柄时自动切换模型」门禁开关及其
  连接/断开两个模型下拉（ADR-0071）；App & system 按 Startup & desktop、Updates、Logging 分组。Updates、Logging 与 Model window 的设置项只保留标题和控件，
  不显示重复描述。Model window 继续按 Window behavior、Window appearance、Window performance 分组；
  「按住修饰键进行交互」的录入控件是 Window behavior 分组的最后一行（ADR-0080）。它排最后不是随意的：
  这一行是对另外两行的修饰而不是它们之中的一行，而任何线性位置都无法让它同时挨着那两行——鼠标穿透在
  第三行、鼠标悬停时隐藏在第六行，中间还隔着「保持在屏幕内」。放在整组之后，它读作对上方设置的一条附注；
  撤销型修饰出现在被修饰项之后，而不是之前（之前会读成「这个开关启用了它们」）。这一行是 Model window 页
  唯一带描述的设置项，符合 ADR-0066「描述只在标题与控件说不清时出现」：描述逐字写出被暂停的两项设置在页面上的
  标题且与页面顺序一致（先「鼠标穿透」，后「鼠标悬停时隐藏」）；控件只显示已录入的键，标题也只说明
  键的用途，没有说明它影响哪两项、以及松开会不会有事。描述同时承担邻接可能引起的误读——它就在行内，
  紧贴着它不影响的那几行。该描述同时进入搜索索引，因此在任意页面搜索「穿透」
  或「click-through」都能找到这一行。该行不跟随任何
  开关门禁，因为它同时被「鼠标穿透」与「鼠标悬停时隐藏」两个开关绑定，而门禁规则绑定的是「一个开关与其下方
  的设置项」；该行只在结构性编辑阻塞时禁用，取值保留到任一开关打开时生效。About 的
  操作行使用标准设置项：产品信息/手动检查更新、隐私安全的软件信息复制、项目主页、问题反馈和打开
  application-owned 日志目录；日志路径不进入 SettingsSnapshot，由 settings service 持有并校验。
  软件信息复制写入的是一个 JSON 对象而不是本地化文案：字段名稳定，不随界面语言变化，报告方可以检索、
  比较和引用。字段只包含 build 与进程事实——产品版本、build environment、Cubism Core 版本、平台与
  架构、操作系统版本与 build（由 bongocat-platform 在复制时向系统查询，因此不会像 revisioned
  snapshot 里的值一样过期）、界面语言、runtime health 与最近一次 render error code、input service
  状态、平台输入能力名与其是否具备（input_capability + input_capability_available）、已连接
  手柄数、input release 校正计数、当前模型来源与导入模型的就绪/无效计数（只计数与固定词表，不含
  模型 id、标题或目录）、设置窗口的显示缩放与逻辑尺寸（复制当刻从 Window 读取，因此布局问题
  可以被复现）；不含任何路径、模型名、日志正文、快捷键或用户配置值。系统无法自报版本时该字段
  缺省而不是填占位值。
  输入能力不是一个跨平台同形的 granted/denied/unsupported：macOS 门在 TCC Input Monitoring，
  Windows 门在提权令牌（TokenElevation，高完整性前台窗口存在时 Raw Input 才会继续送达，
  ADR-0032），因此契约用「平台自己的能力名 + 本进程是否具备」表达，两平台都真、都有用。
  早期实现用 macOS 语汇的 input_monitoring_permission，在 Windows 上报 unsupported，
  读起来像「该平台没有权限概念」而实际是「门在提权上且当前未提权」，已随本字段改为能力模型。
  仍未采集的是 GPU adapter 名称与渲染后端：它需要 Metal/DXGI 枚举（新的 objc2-metal 依赖或新的
  windows feature）与无法在本机验证的 unsafe FFI，不属于本字段的最小闭环；渲染问题先靠
  runtime_error_code 与 cubism_core_version 定位，adapter 名称是下一个独立条目。
  About 的描述只在标题和按钮说不清时才出现：产品信息行显示产品版本，不带 build environment
  （Development/Production 是同一份二进制、不同数据根，只对更新通道有意义，该值仍留在 snapshot
  与复制的软件信息报告里），软件信息行说明复制内容；项目主页、问题反馈与日志目录三行都不显示
  描述（标题与按钮已经说清各自做什么）。About 的操作按钮
  以「检查更新」为唯一实心 primary，「反馈问题」用 danger 描边，复制、项目主页与日志目录三行
  保持组件库默认按钮，使颜色本身始终携带含义。
  About 不再展示法律与隐私正文。页面与分组标题同时作为设置搜索关键词，
  旧页面名保留为只搜索的别名；模型库还索引当前模型显示名。About 位于同一菜单的最后一项。
  配置损坏在 settings window 出现前完成 fallback，不显示配置恢复横幅、按钮或重启提示。
  原 Diagnostics 页面已移除，输入可靠性计数、runtime/renderer 状态和 build 标识只留在
  app-owned 日志和匿名 diagnostics export 里：周期性刷新只服务于界面上仍在显示的数字。
  OpenConfigBackupLocation 与 ExportDiagnostics 仍是 settings service 的强类型排障
  command，不从常规 UI 触发；About 的日志动作只打开应用自有目录，不暴露诊断内容。Development、Production
  和 smoke 的设置窗口使用同一套可见页面、分组和按钮组成；smoke 只改变驱动方式，不额外显示“重置偏好设置”等产品窗口没有的控件。
• 产品启动时以只读 CGPreflightListenEventAccess 检查 Input Monitoring，缺失时用原生系统弹框
  引导用户。检查非阻塞：主线程完成窗口、菜单栏等正常初始化后，由专用 worker 线程执行检查与提示，
  提示未应答或被关闭不影响任何产品窗口的显示与使用（ADR-0032「非阻塞执行修正」）。提示不写配置、
  不写 window state、不缓存「稍后」，每次启动重新读取平台真实状态；提示本身不调用 TCC request
  （ADR-0032）。实现必须使用 rfd 无父窗口的异步消息框：同步路径会在调用线程上构造
  PolicyManager/FocusManager 并触碰共享 NSApplication，而 gpui_macos 的 MacPlatform::run
  需要该实例是自带 platform ivar 的 GPUIApplication 子类（ADR-0032「macOS 弹框实现修正」）。
• macOS 的「授权/去设置」动作在 ADR-0078 之后是 permission-flow 的 INPUT_MONITORING 引导
  面板：它把用户送到「系统设置 → 隐私与安全性 → 输入监控」并显示拖拽授权引导。该动作前先执行
  tccutil reset ListenEvent com.ayangweb.bongo-cat，因此每次进入流程都从「未授权」开始。面板的
  语言跟随产品语言（CFBundleLocalizations + 本应用域的 AppleLanguages），拖拽目标取自当前
  可执行文件所在的 bundle。permission-flow 的 Swift 静态库带来两项构建前提：链接它的每个包都要
  在自己的 build script 里加 Swift 运行时 rpath，打包要把 PermissionFlow_PermissionFlow.bundle
  放进 Contents/Resources。以上细节与未完成项见 ADR-0078。
• 监听 tap 被系统禁用、超时和 session 变化，并自动重建。
• listen-only tap 必须创建在 kCGHIDEventTap 的 kCGHeadInsertEventTap 位置（与 rdev 的 listen 一致），不得使用 session 层 tail append。实测 macOS 26.5.2：session tail 位置收不到右 Shift 的释放 FlagsChanged，且重复按下事件 flags 逐字节相同；同一台机器的 HID head 位置能收到全部修饰键的完整 press/release 对。tap 是 listen-only，只观察不修改、不吞事件；HID 层事件流跨用户会话可见，锁屏/快速用户切换仍依赖既有 session 生命周期 Reset 清空 pressed state。
• FlagsChanged 的 down/up 方向必须在 callback 中冻结，按优先级依次使用：事件 flags 相对上一个 FlagsChanged 事件的设备位跳变（flags 低 8 位中每个物理修饰键有独立 bit，左右天然区分，同侧兄弟键按住时家族 flag 不清零也不影响）、家族 flag 位跳变（rdev LAST_FLAGS 同思路）、按 callback 记录的前一边沿交替。HID head tap 下设备位跳变覆盖全部常规修饰键事件；session tail 上观察到的右 Shift 事件缺失/不变序列由交替回退兜底。decoder 状态不属于 runtime pressed state，并随任何 Reset 清空，周期校正强制释放候选时必须同步清除 decoder 记录。不得等到 consumer drain 时用较新的全局状态反推旧事件，无法识别的修饰键必须触发可观测 Reset。
• CapsLock 是唯一例外，必须单独处理而不是纳入上述交替规则。实测 macOS 27.0 arm64、同机 listen-only kCGHIDEventTap head tap：N 次物理点按恰好投递 N 个 FlagsChanged，物理松开不投递任何事件。AlphaShift 位是驱动在按下时翻转的锁存位，不是物理边沿；Apple 的无状态 Caps Lock 掩码 NX_ALPHASHIFT_STATELESS_MASK (0x01000000) 与 NX_DEVICE_ALPHASHIFT_STATELESS_MASK (0x00000080) 在事件 flags 中始终为 0。锁存键没有 kCGEventKeyUp，因此该键的物理释放在平台层不可表达，任何解码都无法恢复。平台按产品既定的「短暂触发」语义处理：FlagsChanged 到达即成为按下候选，候选存活 100 ms 后由 adapter 合成唯一的释放边沿，并通过 set_pressed(57, false) 重新锚定 decoder，使下一次点按重新解码为按下。该 100 ms 是 Caps Lock 行为的一部分，不是可配置项，也不是已移除的 input.keyboard.release_fallback_timeout_ms：后者要回答「用户是否仍按着」这个真实释放问题，本键没有可保留的按压状态。其余修饰键一律不得纳入该定时释放。
• 对键盘和鼠标 pressed set 分别使用 CGEventSourceKeyState、CGEventSourceButtonState 校正；右侧修饰键键码（54/60/61/62）在按住时也返回 false，必须同时查询其家族主键码（55/56/58/59）作为状态来源；保留 0–31 号 mouse button 身份，按统一的 250 ms/连续 2 次缺失策略确认释放，睡眠、锁屏、权限变化和 tap 重启时直接复位。CapsLock 的 CGEventSourceKeyState(CombinedSessionState, 57) 返回的是锁存状态而非物理键状态，因此周期校正无法代替该键自己的释放边沿；这正是 CapsLock 必须在 adapter 内单独定时的原因。
• 手柄由 ayangweb/gilrs 固定 commit 的 IOHID backend 提供；不再由 BongoCat 枚举
  GCExtendedGamepad 或管理 GameController background policy。连接分配新的项目 generation，按钮/
  连接边沿进入可靠队列，axis 进入固定容量 keyed latest-values；全局 Reset 后以相同 connection
  重播 gilrs 已缓存的 current held state，断开后的旧 generation 不得作用于重连设备。backend
  必须另外提供 authoritative initial snapshot、reset epoch 和 lossless release 证明后，才能把
  held-state/replay contract 视为完成。当前 runtime 不对 gamepad 做键盘式 reconcile；若 backend
  release 丢失，必须由 fork 提供 authoritative snapshot 或 health-triggered Reset。
• callback 只做映射和入队，不执行模型、文件或 UI 工作。

10. 平台实现 Copy Chapter

10.1 Windows Copy Section

• 应用：GPUI/Win32 主事件循环，单实例使用 named mutex + 唤醒消息。
• Overlay：透明桌宠用 Win32 无边框 popup，普通窗口使用系统标题栏与 resize 边框（ADR-0089）。
  无已保存 bounds 时以 350px 作为 100% 的默认逻辑宽度，再应用当前 DPI 与缩放；高度按
  Cubism Core 返回的模型 Canvas 宽高比推导。恢复保存位置时保留客户区宽度并校正高度。
  只有呈现模式切换重建窗口资源；桌宠模式切换模型仍重建窗口，普通窗口切换模型保留 HWND。
  scale/opacity、圆角和屏幕约束设置在现有窗口上更新。桌宠非 click-through 模式的
  客户区支持拖动，click-through 仍返回 HTTRANSPARENT。桌宠右键拖动缩放窗口：位移越过
  3px 后按 (dx + dy) * 0.5 改 overlay.scale_percent（钳制在 25–400），窗口左上角
  不动，尺寸逐帧经 IDXGISwapChain1::ResizeBuffers 与就地重建的 render target、staging
  纹理、mask target 生效（不重建窗口、不重载模型纹理），松手后缩放写回配置（ADR-0057）。
  keep_inside_screen 开启时，窗口必须完整落在所有显示器矩形（EnumDisplayMonitors +
  MONITORINFO.rcMonitor）的并集内，因此允许覆盖任务栏，负坐标保持有效；跨显示器摆放只要不越过
  桌面边界就不纠正。创建、缩放/资源设置重建和模型重建立即收敛一个不可用的放置（窗口大于显示器时保留
  尺寸并把原点贴到显示器原点）；拖动后的收敛由 frame tick 驱动的延迟约束完成：窗口静止累计 1 秒后
  才移回显示器内，期间任何被观测到的位移都重新计时，因此跨显示器拖拽不会被打断。约束缓存最多
  500ms 复用一次放置检查，显示器变化（含拔掉外接屏）在静止窗口下也会被重新评估并纠正。关闭时
  不执行该收敛，但完全离开现存显示器的持久化 bounds 仍按 state 恢复规则回退。
• Renderer：D3D11 + DXGI；桌宠使用 DirectComposition/DWM 与预乘 alpha，普通窗口使用
  不透明 HWND blt swap chain，同时支持 OBS BitBlt 与 Windows Graphics Capture。
• DPI：Per-Monitor-V2，处理 WM_DPICHANGED、显示器热插拔和负坐标。
• 输入：Raw Input、状态校正、可选低级 hook、gilrs/WGI 手柄。
• 产品图标：bongocat-app 在构建期把 BongoCat 自有 .ico 编译进 Windows executable，用于窗口、
  任务栏和文件身份；它不再是托盘图标来源，托盘也不会回退到系统通用应用图标。
• 托盘：tray-icon 0.26.1 拥有 TrayIcon 和固定 GUID，直接依赖的 muda 0.21.2 拥有一个由托盘和
  overlay 右键共用的 popup 根。Windows 状态图标从 BongoCat 自有
  resources/icons/tray-windows.png 解码；托盘隐藏点击恢复和 overlay 右键入口均由该唯一菜单 owner
  管理，overlay 弹出使用自身 HWND，不借用托盘隐藏窗口。共用菜单根包含设置入口、模型窗口操作分组（显隐、
  穿透、置顶、鼠标移入隐藏）、可用的更新入口和退出。
• 启动项：统一由 auto-launch 0.6.0 提供双平台后端。Windows 写当前用户 HKCU Run 并同步
  StartupApproved\Run 启用标记；macOS 写 ~/Library/LaunchAgents/{app_name}.plist
  （RunAtLoad）。Production 使用该后端；命令固定为当前 executable 加 --run-seconds 0，
  默认不要求管理员权限或 TCC 授权（ADR-0043）。该能力只属于已发布的产品：开发构建的可执行文件是
  构建产物而非已安装应用，所以 bongocat-app 按构建环境判定，开发构建直接汇报
  Unsupported(BuildEnvironment)、不触碰平台，设置里的启动项整行按统一禁用样式置灰，并保留可见的 unsupported_build 文案（ADR-0051）。
• 启动权限：产品启动时以自身进程令牌的 TokenElevation 判断是否已提权，未提权时用 rfd 的
  原生系统弹框说明「属性 → 兼容性 → 勾选以管理员身份运行此程序」路径，并提供定位当前
  executable 的操作。检查非阻塞：主线程完成窗口、菜单栏等正常初始化后，由专用 worker 线程
  执行检查与提示，提示未应答或被关闭不影响任何产品窗口（ADR-0032「非阻塞执行修正」）。
  产品不原地提权、不写 HKCU/HKLM、不注册 service，提示也不持久化任何状态；
  每次启动重新读取真实令牌状态，已提权则完全不提示（ADR-0032）。

10.2 macOS Copy Section

• 应用：GPUI/AppKit 主事件循环，平台 UI 操作固定在 main thread。
• 产品图标：.app 的 Info.plist 以 CFBundleIconFile 指向随 bundle 签名封装的 BongoCat 自有
  .icns；该键与 bundle 的其余生成键由打包工具写入，仓库只保留 macos/Info.plist overlay
  （LSMultipleInstancesProhibited、NSPrincipalClass），打包入口在签名前验证元数据与资源存在。
• Overlay：通过 objc2 创建透明 nonactivating NSPanel；无已保存 bounds 时以
  350px 作为 100% 的默认逻辑宽度，高度按 Cubism Core 返回的当前模型
  Canvas 宽高比自适应，两者再应用缩放设置；已保存 bounds 优先，允许通过窗口背景拖动。
  右键拖动缩放窗口：位移越过 3px 后按 (dx + dy) * 0.5 改 overlay.scale_percent
  （钳制在 25–400），窗口顶边不动（AppKit frame 原点在左下角，因此修正 origin.y），尺寸
  逐帧经 setFrame:display: 与重设的 drawable size 生效，mask 纹理随 drawable 尺寸重建，
  松手后缩放写回配置（ADR-0057）。
  always_on_top 开启时使用高于 macOS 菜单栏的 AppKit status window level（NSStatusWindowLevel，
  25），关闭时恢复 normal window level。菜单栏自身在 NSMainMenuWindowLevel（24）并压住同层级的应用
  窗口，因此处于该层级的模型窗口被拖进菜单栏区域后那部分不可见（issue #1155）；25 同时仍高于程序坞
  （20），并低于 AppKit 给 NSMenu 弹出菜单的 NSPopUpMenuWindowLevel（101），所以托盘菜单与模型
  窗口右键菜单依然显示在模型窗口之上。配置的 runtime snapshot 变化和任何 overlay 重建都必须立即重放
  当前层级，不能由其他路径覆盖。
  keep_inside_screen 开启时，窗口必须完整落在所有 NSScreen 的 frame（含菜单栏与程序坞
  占用条）并集内，因此允许覆盖系统区域，负坐标保持有效；跨显示器摆放只要不越过桌面边界就不纠正。
  需要纠正时选择与窗口交叠面积最大的 screen，完全无交叠时选择中心距离最近的 screen，再收敛原点。
  创建、缩放/资源设置重建和模型重建立即收敛一个不可用的放置（窗口大于显示器时保留尺寸并把原点贴到
  显示器原点）；拖动后的收敛由 frame tick 驱动的延迟约束完成：窗口静止累计 1 秒后才移回显示器内，
  期间任何被观测到的位移都重新计时，因此跨显示器拖拽不会被打断。约束缓存最多 500ms 复用一次
  放置检查，显示器变化（含拔掉外接屏）在静止窗口下也会被重新评估并纠正。关闭时不执行该收敛，但
  完全离开现存显示器的持久化 bounds 仍按 state 恢复规则回退。
• Renderer：Metal + CAMetalLayer，drawable size 跟随 backing scale。
• Spaces：按配置设置 collection behavior 和 full-screen auxiliary。
• 输入：CGEventTap、状态校正、gilrs/IOHID 手柄。
• 菜单栏：tray-icon 0.26.1 在 macOS 主线程拥有 NSStatusItem，同一份直接依赖的
  muda 0.21.2 owner 持有一个由托盘和 overlay 右键共用的 popup 根；状态图标使用 BongoCat 自有
  resources/icons/tray-macos.png 并作为 template image。overlay 右键通过 content NSView 在同一主线程
  调用同一棵菜单树，不借用托盘状态项。登录启动在 macOS 13+ Production .app 使用
  SMAppService.mainAppService。macOS 12 和 Development 构建明确报告 capability unsupported，不回退到
  废弃 API 或自行写 LaunchAgent。
• 发布：Hardened Runtime、签名、notarization 和 TCC 权限说明。

平台 unsafe 必须集中在小型 wrapper，写明安全不变量并有 smoke test。业务和 UI crate 默认禁止 unsafe_code。

11. Live2D 与渲染 Copy Chapter

模型资源中的 resources/background.png 作为独立背景资产随渲染资源提交，在 drawable
之前绘制；背景缺失时保持透明 overlay，背景文件损坏则拒绝该模型提交。按键图片从
resources/left-keys 和 resources/right-keys 按目录绑定，当前按下键优先使用精确文件名；
HID 功能键 F1-F24 缺少专属 F1.png…F24.png 时回退到该模型共享的 Fn.png，左右修饰键同理回退到
Control/Shift/Alt/Meta；没有匹配资源时不绘制按键层，也不产生任何按键动作（见下）。Fn 是这张
共享功能键图的名字，不是 Fn 键：旧版输入层把"模型没逐键画图"的 F<数字> 重写成 Fn，两个预置键盘
模型出厂的共享图就在这个主干下，所以它既不改名也不迁移。左右修饰键的精确名是两侧各自的
canonical 名（AltLeft/AltRight、ControlLeft/ControlRight、ShiftLeft/ShiftRight、
MetaLeft/MetaRight），Alt/Control/Shift/Meta 只作为两侧共用的家族图；AltGr 是只对右 Alt
生效的旧名（见 ADR-0038），Return 是主 Enter 的旧拼写（见 ADR-0039），Function 是地球键的旧名
（见 ADR-0049）——三者都排在最具体名之后，用于兼容没有经过导入归一化的包。小键盘（HID 0x53…0x63）的
精确名是 NumLock 与 Mver 词汇表的 Kp*，其中在主键盘上重复的七个键回退到主键盘的键位图
（Kp1…Kp9、Kp0 → Num1…Num9、Num0，KpEnter → Enter，KpDivide → Slash）；
NumLock、KpMultiply、KpMinus、KpPlus、KpDecimal 在主键盘上没有对应键，缺图时不绘制。
小键盘整块归左手，因为可复用的数字、Enter 和 Slash 图只存在于 left-keys（见 ADR-0040）。键位词表
覆盖标准 104/105 布局、小键盘与 Apple 地球键的全部按键，范围是
0x04..=0x65 ∪ {0x67} ∪ 0x68..=0x73 ∪ 0xe0..=0xe7 ∪ {0xff03}（八个修饰键 usage；0x66
Power 两边都不产出）。这是词表覆盖的上界，不等于"两个 adapter 实际能产出的集合"：IntlHash
0x32 与 F21–F24 0x70..=0x73 目前两个平台都产不出，仍然命名。命名不以预置模型当前是否有图、
也不以今天有没有硬件能按为前提：它是与模型作者的契约，模型提供 Dot.png、Minus.png、
Delete.png 等任何键位图都必须在不改产品代码的前提下生效。反过来，"某个 adapter 能产出某个 usage"
必须有该 adapter 自己的断言支撑，不得从这张并集推断——Apps 0x65 就曾在这个并集里躺了很久，而
两个平台都没有映射，于是 Apps.png 永远画不出来（见 ADR-0041 修订与 TODO 第 90 项）；hand 归属
覆盖同一集合（含修饰键块，见 ADR-0041 事实 4 修订），因为 InputState::model_snapshot 会丢弃没有
hand 归属的按键，且该集合由契约测试遍历而不是由实现恰好用到的区间决定。

地球键是这套词表里唯一不在 HID Keyboard/Keypad 页的键：它的 usage 是 Apple 厂商页 0xFF 的 0x03
（KeyboardFn）折叠成 0xff00 | usage，即 bongocat-render::GLOBE_KEY_USAGE = 0xff03。任何
0x04..=0xe7 式区间都覆盖不到它，所以命名、绑定和两处契约并集都必须显式写出。它的精确名是 Globe，
旧名 Function 作为末位别名；它与功能键的候选列表完全不相交（见 ADR-0049）。平台可达性：macOS 经
CGEvent keycode 63（kVK_Function）以 FlagsChanged + MaskSecondaryFn 到达，Windows 的 Fn 键由
键盘固件处理、Raw Input 从不报告，所以没有 Windows 映射。同理，F13–F24 在 Windows 侧没有可依据的扫描码
（不猜值）、在 macOS 侧 Carbon 没有 kVK_F21…kVK_F24，0x70..=0x73 属于"命名到位但两个平台都不可达"。

只有模型确实提供对应键位图时，按键才产生动作（见 ADR-0042）：bongocat-app 在激活模型时用
bongocat-live2d-render::KeyImageInventory 读取该模型的键位图清单（与渲染侧加载共用同一次目录扫描和同一套
候选回退），并只把清单里能画出来的键写进 InputBindings。写入 runtime 的每模型绑定因此是
"静态 hand 表 ∩ 该模型的键位图"：缺图的按键不进入 InputState::model_snapshot，既不驱动
CatParamLeftHandDown/CatParamRightHandDown，也不产生按键层，所以按键层与爪部反馈永远一致。
判断在 runtime 之前完成，renderer 仍只消费不可变 RenderSnapshot，不决定动作；该规则只覆盖键位图，
鼠标指针/按键不属于键位图资源。功能键的范围、名字和左右手归属由
bongocat-render 的同一张 HID 表给出（0x3a..=0x45 与 0x68..=0x73 两段，中间是 PrintScreen
至方向键和数字键盘），避免按键图片解析和 runtime 绑定各自定义；没有 hand 归属的按键不产生按键层。

手柄按键走同一条通道，词表是产品自己的（见 ADR-0070）。bongocat_render::KeyPress 携带的是
带标签的 KeyIdentity（Keyboard(hid_usage) 或 Gamepad(GamepadButton)），不是裸 usage：手柄按钮
没有 HID Keyboard/Keypad usage，两族共用一个数字空间会让一类按键被当成另一类解析。每个按钮的图片名
就是 GamepadButton 变体名本身（GamepadButton::key_image_name），16 个按钮一一对应、互不重名，
因此类型和美术词表不会漂移。名字是产品词汇，不是 backend 词汇：旧 Tauri 输入层用
format!("{:?}", Button) 派生文件名，产物里 LB/RB 叫 LeftTrigger/RightTrigger、LT/RT 叫
LeftTrigger2/RightTrigger2、摇杆键叫 LeftThumb/RightThumb、方向键叫 DPad*；预置 gamepad
模型已按产品名重命名（LeftShoulder/RightShoulder、LeftTrigger/RightTrigger、
LeftStick/RightStick、Dpad*），导入路径在模型 store 把旧名改写为产品名
（bongocat-model-store::key_names）。手柄词表没有运行时旧名候选：LeftTrigger 在旧词表里已经是
肩键的名字，任何别名表都会把肩键或扳机键解析成对方的图。左右手归属同样由模型自己的目录决定——
left-keys 里的图画在左爪上、right-keys 里的画在右爪上，这与旧实现的判定一致，也让 Mver 转换按
lefthand/righthand 落盘的结果直接可用。缺图的按钮保持惰性（ADR-0042）；两个摇杆键另外驱动
StickLeftDown/StickRightDown，摇杆本身另有可见性参数并按下述规则带动爪子（ADR-0082）。

按键层画在哪个四边形上由按键图自己的尺寸决定，不是恒定等于画布四边形（见 ADR-0037 修订）。
ModelBounds::from_canvas 给出模型画布在模型空间的四边形，背景就画在它上面；按键图则先经过
bongocat-render 的 legacy_key_overlay_bounds：BongoCatMver 把按键图画在窗口原点、一图素对一窗口
像素，而模型画布居中画在同一个窗口里，因此按键图比画布左移 (窗口宽 − 按键图宽) / 2 图素。窗口宽取
该图自身较大的一边——按键图就是画布在窗口里的尺寸，窗口不会比它窄，作者不按画布尺寸设窗口时用的是
包含它的正方形——所以按键图宽 ≥ 高时偏移为 0，画布四边形原样返回，出厂预置模型与所有宽按键图模型
都不动；只有比宽更窄的按键图（例如 issue #1129 的 986×1000 对 1000×1000 窗口）才左移。
这条规则在双平台渲染器里对每张按键图各建一个四边形缓冲，背景仍用画布四边形，因此旧包与新包、
resources 里任何分辨率与宽高比的按键图都落在同一套几何里，不需要重写已转换的模型资源。

列表，双平台渲染器都按这个顺序绘制且都没有深度附件或深度模板，因此列表里最后一项就是最上层；
z 序完全由列表顺序决定，渲染器没有额外状态。model.show_all_pressed_keys 决定这份列表的内容：

• 关闭（默认，兼容模式）：InputState::model_snapshot_with_filter 对每只手只保留一个"最后按下且仍
  有效"的按键，左右手各至多一个，按左手先、右手后写入列表。
• 打开（叠放模式）：每一个仍按住、且模型为它提供了键位图的键都进列表，按
  PressedRecord::pressed_at 与可靠输入队列的 pressed_sequence 从旧到新排序。单调时钟是毫秒精度，
  快速连击会落在同一毫秒内，只有 sequence 能给出全序。

两种模式都不改变 pressed state、释放路径和 CatParamLeftHandDown/CatParamRightHandDown：只要有任意
一个绑定到该手的键仍按住，该手就是按下的。resolve_key_overlays 只做"按键 → 资产"的解析，不再按手
折叠；两个按住的键解析到同一张图时（Fn 家族回退、小键盘复用主键区图）只画一次，先按下的那个占住
底层。列表容量固定为 KeyPressSet::CAPACITY，溢出时丢最早按下的那几个。

11.1 Cubism 边界 Copy Section

Official Cubism Core binary
          |
   raw Rust sys bindings
          |
  Moc / Model safe wrappers
          |
model evaluation + render snapshot

• Core 二进制按平台分发，版本、hash、来源和许可证记录在构建清单中。
• 当前验证基线固定为 Cubism Native 5-r.5 / Core 06.00.0001；升级必须重跑
  header/binding provenance、目标 ABI、三个预置 Moc、offscreen/enhanced rendering
  fixture 和双 renderer 门禁。
• raw binding 只由精确锁定的离线生成工具从 hash 固定的官方 header 生成；生成配置、target ABI、libclang 版本和输出 hash 必须进入 provenance，禁止手改生成代码。
• 维护者提供并批准用于开发的固定基线已存入 vendor/cubism/5-r.5，包括
  Core、官方 header 和由该 header 生成的 target binding。公开发布前另行核对
  attribution 与再分发清单；该发布工作不阻塞本地功能实现和开发提交。
• 原始指针不离开 safe wrapper；Moc 必须比 Model 活得更久。
• Core 全局日志 callback 只在 callback 生命周期内有界复制至多 512 bytes，并以容量 128 的
  非阻塞队列交给专用 Rust worker；callback 不获取 writer mutex、不转义/格式化文本、不执行文件 I/O。
  worker 通过 application/Core 共用的文本 writer 写入当天的 cubism-core-YYYY-MM-DD.log；Core callback
  不提供可信级别，因此原始 message 固定按 debug 过滤，实际 Core/renderer 失败仍由 app owner 以
  error/warn stable code 记录。全局 callback-slot 竞争、队列满、停止后的迟到 callback 都只增加
  匿名 dropped 计数。关闭时先注销 Core callback，拒绝新记录，再排空已接收记录并 join worker；
  Core message 与日志路径不进入 runtime、UI 或 diagnostics export。
• 不把未经验证的新纯 Rust Cubism 兼容 crate 作为生产基础。
• .model3.json、motion、expression、physics 和 pose 兼容性由 fixture 验证。
• motion3/exp3 的字节解析、曲线/fade/loop/UserData 求值和 expression Add/Multiply/Overwrite
  混合由 bongocat-live2d-playback 纯数值完成；bongocat-live2d-render 从 CommittedModel
  读取并准备 RenderResources，bongocat-live2d 再做 Core ID/range/part 校验并把结果写入 Core。
• 每帧从 Core 默认 parameter 和模型初始化时捕获的 part opacity 开始，依次应用 motion、
  expression、类型化产品输入、自动 EyeBlink/参考 Breath、physics3（已声明时），最后调用 Core
  update；这与固定 Mver 参考实现的更新顺序一致，使 neutral pointer input 不会抹掉角度呼吸，
  physics 也能看到产品输入。自动 Breath 使用 Mver 的固定 Cubism Framework 参数集合
  ParamAngleX/Y/Z、ParamBodyAngleX 和 ParamBreath，按各目标的 offset/peak/cycle 计算，
  再以 current + value * 0.5 的加法贡献写入并按 Core 范围 clamp；不能把 Breath 目标向当前值
  插值，否则鼠标角度会被削弱。它不要求 model3 存在 Breath 组。model3 首个
  Parameter/Breath 组仍可声明最多 64 个额外 ID，并保留既有的 model-range blend 语义；
  固定 ID 不重复驱动，缺少该组也不影响
  固定参考目标。声明的 physics3 由 bongocat-model 做有界解析、由 bongocat-live2d 按 R5
  结构执行固定步进、惯性、延迟和输出插值；旧版资源省略 Meta.Fps 时使用当前单调 frame delta，
  不臆造固定频率，但显式提供的 FPS 仍必须是有限正数；未知输入/输出安全跳过，pose 仍未实现。
  physics3 设置项的 Output 可以为空数组：官方 schema 只要求该键存在而不约束长度，编辑器
  导出的模型普遍带有「模拟了粒子但不写回任何参数」的设置项，求值器按同一语义跳过它的写回而
  不因此拒绝整个包（ADR-0077）；输入项非空和至少两个顶点仍然是硬要求。不得把
  有符号正弦直接钳到单边参数范围，也不得按满量程绝对覆盖参数。completed motion 仍以 clip
  声明时长对应的完整求值样本参与这一步，因此默认值逐帧恢复不会抹掉动作最终姿态；该样本保留
  自然结束 fade 的权重，显式停止的外层正弦权重再与 motion 原有权重路径相乘。PartOpacity
  motion curve 遵循 R5 Framework 语义，按 curve ID 写入 Core part-opacity sink，和普通 parameter
  curve 使用独立的目标表与权重路径；每帧先恢复初始 part opacity，因此 stop、替换或不含该 part
  的后继动作不会残留旧值。model3 Groups 由模型索引保留并校验；motion Model target 中
  EyeBlink 对匹配的 Parameter curve 做乘法、LipSync 做加法，对未被 Parameter curve
  覆盖的首个同名 Parameter group（最多 64 个 ID）使用 motion fade 插值。Opacity 作为
  独立 model opacity 进入 RenderSnapshot，只在 renderer 的模型颜色合成中与 drawable opacity
  相乘，不参与 mask 生成；窗口 presentation opacity 不进入逐 drawable alpha，而是在模型、背景、
  按键和 mask 完成合成后由平台最终 surface 统一施加，并保持到后续 motion opacity curve 更新或模型切换。
  expression 的 Add/Multiply/Overwrite 和正弦淡入淡出由 bongocat-live2d-playback 纯函数计算；
  替换期间最多保留上一层与当前层，淡入完成后将当前层权重锁定为 1.0，稳定后只保留并持续
  应用最新 expression，直到被下一次有效 expression、成功的模型切换或 shutdown 清理；测试时钟
  回退不会重新启动已完成的淡入。内存和每帧成本保持有界。产品输入与 reference Breath/physics
  的组合顺序遵循本节前述 Mver 顺序。
• 模型加载采用 prepare/commit/rollback，失败时保留当前可用模型。
• 模型切换是 CPU/GPU 两阶段提交：runtime 先保留旧 active model/bindings，准备新的
  Cubism generation，并随候选 RenderSnapshot 发布一次性强类型 commit token；平台
  renderer 只有在纹理、mesh、mask 和 pipeline 资源全部准备成功后才能确认。runtime
  收到匹配 token 的确认后才替换产品事实状态；renderer 拒绝时双方继续使用旧模型。
• 普通 render frame 使用独立单调 transport sequence，可以按 latest-value 合并；模型
  commit feedback 使用不可覆盖的可靠单槽并且同时只允许一个候选 generation，不能被
  普通帧、cursor 或输入事件合并。等待 GPU 确认期间可靠输入仍由旧 bindings 消费。

官方 Cubism Framework 的动作、physics3 等逻辑必须在 Phase 0 验证 Rust 实现的兼容性；当前
physics3 只覆盖已验证的 v3 结构与 R5 数值路径，pose、完整黑盒轨迹和未覆盖的平台/资源边界仍
须形成 go/no-go ADR，不能绕过该门槛扩大实现范围。

11.2 Renderer Copy Section

GPUI renderer 与 Live2D renderer 完全分离：

RenderSnapshot
├── model opacity / horizontal mirror / drawables / offscreens / order / opacity / masks
├── color + alpha blend / multiply + screen color
├── vertex / uv / index buffers
├── texture ids
└── transform / viewport
        ├── Windows D3D11 renderer
        └── macOS Metal renderer

renderer 负责遮罩、混合、裁剪、纹理上传、dirty flag、present 和 GPU 生命周期；不读取配置、不决定动作、不访问 GPUI entity。模型、背景和按键先在 premultiplied render target 中按模型 alpha 完成合成；窗口呈现 opacity 不再乘入每个 drawable，而是在合成完成后由 Windows DirectComposition visual effect 或 macOS NSPanel 对最终 surface 统一施加一次，避免多层 Live2D 互相重复衰减。Core 的 double_sided 必须同时驱动 D3D11/Metal 的背面剔除状态。水平镜像会反转三角形 winding，因此单面 drawable 在镜像时必须改用相反的剔除面；D3D11 与 Metal 都以 counter-clockwise 为正面，背景和按键 overlay 不剔除。

Cubism Core 在每次 UpdateModel 后的 drawable dynamic flags 必须随 RenderSnapshot 一起复制，
并在 ResetDrawableDynamicFlags 前完成读取。v1 中 drawable index topology 在同一 model generation
内不可变，backend 检测到变化即拒绝该 snapshot；Windows 与 macOS 只在
vertex_positions_changed 时重写对应 vertex buffer，render order、visibility、opacity 与颜色仍以
同一帧 snapshot 更新 CPU-side draw state。

所有 v1 PNG RGBA 贴图（Cubism texture、背景与按键 overlay）遵循 ADR-0063 固定的
encoded-space 兼容契约：Windows 使用 R8G8B8A8_UNORM texture view 和
B8G8R8A8_UNORM composition/render target，macOS 使用 RGBA8Unorm texture view 和
BGRA8Unorm drawable。两端 shader 都不得加入 sRGB decode 或 encode；normal、additive 与
multiplicative blend 使用相同的 premultiplied 输入。clipping mask 只携带 alpha，保持
UNORM，避免对 coverage 作颜色空间转换。

该契约是为兼容历史 Mver 观感而作的产品选择，不是对实际 Mver 二进制来源链或跨平台像素
一致性的既成证明。精确 Mver build provenance、背景/按键上传语义和目标硬件 readback 仍是
TODO 的验收门禁。若未来要切换到物理 linear-light 合成，必须同时修改两端的 texture view、
composition attachment、shader 和跨平台像素 contract，不能只改一个平台。v1 不解释或转换
嵌入 ICC/wide-gamut profile；模型导入将此类颜色管理作为明确的后续能力，而不是让平台默认
行为决定结果。系统级显示色彩管理仍存在平台差异：macOS Core Animation 与 Windows
DirectComposition 对最终 surface 的显示转换不同，因此同一组 encoded 值在广色域显示器上的
绝对观感仍可能不同；这属于合成器行为，不由 renderer 消除。

窗口圆角是 overlay 窗口自身的形状属性，与模型、动作和输入无关。overlay.corner_radius_percent
按窗口宽高的百分比给出四个角的椭圆半径：N% 表示水平半轴为窗口宽度的 N%、垂直半轴为窗口
高度的 N%，与旧版 CSS border-radius: N% 相同，因此同一个数值在非正方形窗口上产生的水平
圆角比垂直圆角更大；0 保持直角，50 时四条弧线相接、内容被裁剪为窗口的内切椭圆。renderer
在片元着色器中按 drawable 像素位置求该椭圆的 coverage，并把它乘进每次绘制的 alpha，因此圆角
只改变窗口边缘的合成结果，不改变 RenderSnapshot、模型资源、绘制顺序或 blend 模式。该值只
作用于 overlay 窗口；GPUI 设置窗口和其他产品窗口保持各自的平台边框。Windows 圆角与屏幕范围约束
在现有窗口上更新，普通窗口模式暂停圆角裁剪；macOS 改变这两项仍重建原生窗口资源。缩放通过
现有窗口与 renderer 原地调整，不透明度则更新最终 surface 的 presentation alpha，二者都不应
因为设置变化替换 HWND/NSPanel。

指针悬停隐藏是 overlay 窗口的临时呈现状态，不是窗口可见性。overlay.hide_on_pointer_hover
开启时，指针进入 overlay 窗口矩形并停留 overlay.hide_on_pointer_hover_delay_seconds 之后，owner 把
窗口的呈现 alpha 淡到 0 并强制指针穿透；指针离开窗口矩形后按同样的时长延迟淡回
opacity_percent，并把穿透恢复为 overlay.click_through。窗口本身既不隐藏也不销毁，
runtime 的 overlay visibility 不受影响，frame source 继续按 overlay.maximum_fps 出帧，shutdown 顺序不变。隐藏期间
穿透强制为开，因此不可见的 overlay 不会吞掉本该落到下层窗口的点击。

淡入淡出复刻旧版 CSS transition-opacity-300 的 300 ms，但按「从过渡起点起算的绝对经过时间」
求值，而不是按帧累加：同样的时间点在不同帧率下得到同一个 alpha，60 FPS 与 240 FPS 的采样结果
一致。首版按线性插值，不复刻旧版 CSS 的 transition-timing-function：该曲线来自样式框架默认值、
未在旧版代码中显式声明，因此不视为已冻结的行为。命中测试用指针采样与窗口矩形的半开区间比较
（x >= left && x < left + width，纵向同理），因此相邻显示器共享的边界像素只会落在其中一个窗口内。
命中测试读采样里指针自身的位置，而不是模型跟随的位置：input.mouse.force_move 打开时后者由
相对位移累加而来（见 ADR-0081），是对指针位置的估计而非指针位置本身，用它做命中测试会让同一个
手势因为鼠标走到窗口的路径不同而得到不同结果。两个位置都由平台适配器在同一条采样里发布。
平台采样与窗口矩形的坐标空间不同时必须在 owner 内换算，不允许把平台坐标泄漏给 runtime 或 renderer。
圆角窗口的透明角落仍算在窗口矩形内，与旧版一致。

指针采样缺失、或平台输入服务不在 Running 状态时一律视为「不在窗口内」。这条降级规则保证指针
链路失效时 overlay 最坏情况是保持可见，而不会永久停在全透明且穿透的状态。悬停隐藏与
opacity_percent 共同决定最终 alpha。改变不透明度只更新现有 surface 的 presentation alpha；开关和
延迟本身也在 frame tick 内原地生效，不触发原生窗口重建。

「按住修饰键以恢复交互」是这两个临时状态之上的一个开关，而不是第三个状态机。
overlay.hold_modifier_to_interact 设置后，平台 owner 在每次 frame tick 内把它与 runtime snapshot
里的 input.pressed_modifiers 相与：按住期间悬停隐藏按「关闭」处理（状态机复位、alpha 淡回
opacity_percent），并且最终穿透判定从 click_through 收窄为 click_through && !held。因此
一只配置成「鼠标穿透 + 悬停隐藏」的猫仍然可以被抓住拖动，不必先关掉设置再打开。松开键后两者
立即恢复，指针通常仍停在窗口内，因此悬停延迟重新开始计时而不是恢复一个已经过期的截止时间。
该字段只读不改：落盘配置、runtime 设置与 overlay options 都保持用户原值，忘记哪个键也不会在
下一次按住时改变行为。

input.pressed_modifiers 是 runtime pressed set 在八个 HID 修饰键词汇表（0xE0..=0xE7）上的投影，
左右两侧各占一位。它存在的理由是现有两条读法都答不了这个问题：snapshot 只有按键计数，而模型投影
会丢掉当前模型没有对应按键图的键——修饰键恰好就是模型不会提供的键。因此设置页的录入控件也读它，
而不是读 GPUI 的按键事件：GPUI 把修饰键报告为不带键身份的布尔标志变化（macOS 上按修饰键根本不
产生按键事件，Windows 上左右 Shift 的虚拟键码落在同一分支），既分不出左右，也没有可供录入的
按键事件。控件因此是「按住」语义而非「点按」语义，这也正好是设置本身要求用户做的动作。

无操作隐藏与悬停隐藏是同一呈现通道上的第二个临时状态。overlay.hide_on_idle 开启且
overlay.hide_on_idle_delay_seconds 内没有任何新输入时，overlay 把 alpha 淡到 0 并强制指针穿透；
任意新输入重新开始计时并淡回 opacity_percent。它的「活动」判定只读 runtime snapshot 里的三个输入
计数器：输入事件序号、指针采样时间戳、手柄轴已发布样本数。三者任一变化都算一次新活动；鼠标停在
原地不产生新采样，因此不会把闲置状态续期。平台 owner 不自己监听全局输入，也不新增平台 API。
两个状态机的 alpha 相乘、穿透取或，因此任意一个生效都不会让 overlay 停在透明但吞掉点击的状态。
输入服务不在 Running 状态时无操作隐藏同样关闭，避免输入链路失效时永久隐藏窗口。窗口、frame
loop 与 runtime overlay visibility 都不受影响，shutdown 顺序不变。

原生 overlay 窗口创建后默认保持隐藏。平台 owner 只有在对应 renderer 已成功完成至少一次
非空帧 draw/present 后才允许首次显示；启动、隐藏后重显、设置导致的窗口重建和模型切换重建
都遵守同一顺序。首帧提交或验证失败时窗口保持隐藏，模型准备失败仍保留当前可用窗口与模型，
不得暴露未初始化 swapchain/drawable 造成黑框或不透明闪烁。

overlay 隐藏时不连续消费或 present 普通动画帧，latest data frame 继续在 transport 中合并；
可靠 model commit 被消费时淘汰早于候选 generation 的旧 data frame，避免重显回退 GPU owner。
带 model commit token 的可靠控制帧仍由 100 ms 上限的隐藏 tick 单独消费：候选 GPU owner
完成一次隐藏 draw/present 验证后回报 prepared 并替换旧 owner，失败则回报 rejected 并保留旧
owner。后续重显必须先同步当前 latest frame、再次成功 present，再显示已提交的候选窗口。

renderer 的模型资源准备结果通过稳定项目 error code 回到 runtime，不返回 GPU handle、
平台对象或任意字符串协议。候选准备失败只结束对应模型 command，不得终止 frame loop、
清空当前 GPU model 或让 runtime 提前宣布候选模型 active。

临时 presentation unavailable（例如 macOS CAMetalLayer 未交付 drawable）不是模型或设备
准备失败：frame source 必须以单调、有限的退避延迟重试，成功 present 后重置；不得把重复临时
不可用写成 failure 日志或停止 frame source。候选模型的可靠 commit token 必须保留至实际首帧
成功，不能因临时 drawable 缺失被拒绝。未知 D3D11 present/device-loss 仍按明确 HRESULT 恢复策略
处理，不能笼统归类为临时成功。

Linux 阶段再决定增加 Vulkan/OpenGL backend，或基于数据迁移到 wgpu。首发优先保证 Windows/macOS 透明窗口的确定性。

11.3 Motion 音效 Copy Section

• bongocat-audio 使用精确锁定的 rodio 0.23.0，只启用 output playback 与 FLAC；
  rodio/CPAL 类型不进入 runtime、model、UI 或 renderer 公共接口。
• runtime 只在 motion priority 与资源解析均成功后，通过固定容量有序队列非阻塞发布
  强类型 Prepare/ActivatePrepared/Play/Stop。解码、文件 I/O 和设备创建全部由独立 worker 执行。
• renderer 与 audio 对候选模型并行 prepare；audio worker 将去重 sound 解码为 immutable PCM，二者完成
  或 audio 已稳定降级后才 commit 模型。ActivatePrepared 只保留活动模型 cache；output stream 的惰性打开由
  audio owner 执行且不能阻塞 model 或 motion。已活动模型的 motion 在同一 runtime command 中发布缓存 Play
  并启动 motion；不得等待 mixer position、设备回调或轮询音频诊断。audio owner 优先使用 512-frame buffer，设备拒绝时回退默认 sink。
• 同时最多一个 motion voice。新动作（包括没有 sound 的动作）、显式停止、禁用音效、
  成功模型 commit 和 shutdown 都停止旧 voice；被 priority 拒绝或加载失败的动作不改变
  当前 voice。
• model3 sound 相对路径必须先通过模型包规范化与包根约束，再由 runtime 组合为本地路径；
  audio backend 不解析 model3，也不接受 URL 或未验证的模型引用。
• 文件、解码、输出设备和队列故障只更新匿名诊断，不改变 motion、input 或 render 状态。
  满载恢复丢弃不可信 backlog 并停止 voice，禁止阻塞输入边沿。
• motion3 UserData 由 Live2D evaluator 保留并按单调 elapsed 的 (previous, current] 区间
  产生强类型 occurrence；循环跨越不重复，时间回退不重放，单 tick 最多发布 256 项并
  对跳过数量计数，避免睡眠恢复后的无界分配。

12. 配置、模型与安全 Copy Chapter

应用身份：

com.ayangweb.bongo-cat

构建产物携带不可变的 Development 或 Production 环境。环境由构建入口显式选择，运行时参数、环境变量和设置项均不能切换。两个环境使用相同 schema 和相对目录结构，只改变数据根目录：

正式 app 使用 Cargo feature 选择环境：默认不启用 production，即 Development；Production
build/package 必须显式启用 bongocat-app/production。packaging 继续校验 --environment 只接受
development/production，并只在 Production 时给子 Cargo 命令添加该 feature。运行时不读取
BONGOCAT_BUILD_ENV 或其他环境变量。正式 Application::start 只以编译期环境调用当前平台 path
resolver，不接受外部 StorageLayout、根目录或生产路径覆盖；隔离临时根注入只存在于显式
storage-test-injection Development 测试产物，Production 与该 feature 的组合在编译期失败，
默认产品 CLI 和 API 均不包含该入口。

每个根目录包含 config.json、window-state.json、models/、model-overrides/、backups/、logs/、updates/ 和 locks/。model-overrides/ 是预置模型用户侧内容的命名空间（每张替换封面一个 /resources/cover.png），因为预置包位于 app 包内、不可写；它与 models/ 一样只被设置页与 app 层写入。锁、单实例命名、更新 channel 和诊断同样按环境隔离；任何环境不得读取、写入或 fallback 到另一个环境。updates/ 是保留给更新的环境私有命名空间：当前 cargo-packager-updater 使用进程临时文件/目录下载和暂存载荷，不落在该目录下，因此 updates/ 当前无写入方，仅作为环境形状契约的一部分保留。StorageLayout 只描述这些用户数据路径；安装器使用平台 InstallationLayout 描述 product files root，不能从用户数据根推导或操作安装目录。

预置模型属于 product files：macOS 从 BongoCat.app/Contents/Resources/models 解析，Windows 从
bongocat-app.exe 同级 resources/models 解析。仅未打包的开发二进制可在该相对路径缺失时回退到
仓库 resources/models；安装产物不得依赖源码树、当前工作目录或用户数据目录。

要求：

• BongoCat 配置从全新 schema 开始，不读取、不探测、不导入旧 Tauri/Pinia store。

• JSON key 使用 snake_case，字段按当前领域语义命名，不提供旧字段 alias。

• 初始版本是全新的，当前完整配置统一使用 schema_version: 1。v1 直接包含完整的
  model.selected_model: { id, source }、用户导入模型的元数据列表 model.imported_models 与内置
  模型的列表 model.built_in_models。imported 记录包含稳定唯一的 id、可编辑 title 与必填的
  input_mode（standard、keyboard 或 gamepad）；built-in 记录只包含 id 与 title，其模式
  由构建拥有的稳定 id 派生。普通包在 staging 提交前通过 left-keys/right-keys 资源判定模式，
  判定失败直接拒绝导入；不从标题或路径生成模式。两个元数据列表各自判重：列表内 id 不得重复，
  title 去除首尾空白后不得为空。built_in_models 为空表示所有内置模型都还用构建给的名字，
  它没有任何导入、删除或裁剪路径；input_mode 不参与 { id, source } 身份。输入配置使用
  input.gamepad.stick_dead_zone 和 input.gamepad.trigger_dead_zone；两个 dead-zone 都必须是
  [0, 1) 的有限数。模型随机播放由 model.random_behavior.mode 与
  model.random_behavior.interval_seconds 成对表达：mode 是 off（默认）、expressions、
  motions 或 motions_and_expressions 的单一枚举，关闭是它的一个取值而不是独立布尔门禁；后者为
  [1, 3600] 秒且默认 30。两者直接进入当前 v1，不读取旧字段。model.gamepad_auto_switch 直接包含当前 v1：门禁
  enabled 默认 false，connected_model 与 disconnected_model 是完整 ModelIdentity 或
  null，null 是默认值并表示「上次在该输入族上使用过的模型」；该「上次使用」是
  Application 的会话状态而不是配置字段（ADR-0071）。model.toggle_repeated_expression 直接包含当前 v1 且默认 false，带 #[serde(default)]：
  旧文档没有这个键时读出 false。model.remember_last_expression 与
  model.last_expressions 直接包含当前 v1：门禁默认 false，列表每个元素是一个
  { model: ModelIdentity, expression } 记录且同一模型最多一条，列表默认为 []。
  记录与门禁分离：记录只由用户主动触发的 expression command 产生，随机行为播放的
  expression 不写入；门禁只决定模型成为当前模型时是否播放自己那条记录，不决定是否记录，
  因此关闭再打开恢复的是用户原本选过的表情。没有记录、或记录中的表情已不在模型包内时
  模型保持自己的默认表情。删除导入模型时该模型自己的记录在同一次提交中清除，
  model 语义详见 shared/config/contract.md。overlay visibility 属于 runtime 会话状态，
  不写入 config；设置页使用
  settings.overlay.hide_model_window.label 将其投影为“隐藏模型窗口”开关，开关选中表示已隐藏，默认未选中。

• 开发期间不读取或转换任何早期中间结构，不实现 schema migration、字段 alias 或版本兼容
  分支。新增字段直接更新当前 v1 的 Rust 类型、JSON Schema、默认值和 fixture。解析入口保留显式
  版本检查并拒绝非 v1 数据；首次正式发布后的后续版本再以该发布版为基线单独设计迁移链。

• 写入使用同目录临时文件、flush、原子替换和提交后验证；替换前把当前配置封装为带格式版本、
  墙上时间、源 schema 和 revision 的环境内备份。每个环境只管理 config-*.json 自有命名空间，
  按持久排序键保留最新 8 份且总计不超过 8 MiB；系统时钟回退不得让新备份被误删，未知文件
  不参与清理。备份写入或收敛失败时保留当前配置；原子替换后的重读、typed validation、revision
  或值比较失败时逐字节恢复替换前配置，固定 temp 不得残留，后续启动必须可以重新尝试提交。

• 正式配置提交先以只创建方式写入并 flush 固定的同目录 config.json.tmp，再使用平台原子替换
  提交 config.json。启动在同一 writer lock 内先处理残留 temp：有效 current 优先并把有效 temp
  归档为 stale；current 缺失或损坏时才提升有效 temp；无效 temp 单独归档且不覆盖 current；非 v1
  schema temp 原样保留并明确报错。stale/invalid 归档共用每环境最多 4 份、总计 8 MiB 的自有
  命名空间，未知文件不参与清理。仅启动恢复以 10 ms 间隔重试 writer lock 最多 1 秒，普通提交
  仍立即报告竞争；app 只保留不含路径、原始字节或 I/O 文本的匿名恢复动作。

• 当前配置属于 v1 但 parse/validate 失败时，只在同一 writer lock 内从新到旧检查自有备份，
  同时验证 envelope 格式、源 schema、源 revision 和完整 typed config。找到第一份有效备份后，
  将损坏原文写入 config-corrupt-*.bin quarantine，原子写回该配置并重新读取验证。
  没有有效备份时，直接 quarantine 损坏原文、原子写入并验证当前 v1 默认配置。两条 fallback
  都返回普通可用配置，没有 RecoveryRequired、recovery-only settings window、snapshot 恢复字段、
  RestoreDefaultConfiguration command 或“恢复后必须重启”流程。非 v1 schema 仍按当前 v1
  的严格版本入口报告 unsupported，禁止自动转换、downgrade 或覆盖未知格式。

• 配置写入将权限/只读文件系统、存储空间/配额不足和 temp 目标占用分类为稳定的匿名失败原因；
  settings 只显示可操作的项目文案，不泄漏路径或操作系统原始错误。写入只清理由当前调用成功创建的
  temp；若固定 temp 已被文件、目录、符号链接或并发创建占用，则保留该条目和 current 并明确失败。
  权限与磁盘满在 temp 创建前后都必须可受控注入，验证失败不改变当前 snapshot/revision。

• OpenConfigBackupLocation 是强类型 command，打开当前构建环境的 backups/；自 Diagnostics 页面
  移除后它没有 UI 入口，只由 settings service、隔离 smoke 与排障路径使用；
  路径只由 Application 从正式 StorageLayout 派生并传给 platform adapter，不进入 command、
  snapshot、错误或 GPUI Entity。platform adapter 先验证绝对目录并 canonicalize，再通过 opener
  crate 交给系统默认程序；成功只返回当前 snapshot 且不推进 revision，失败只返回
  BackupLocationOpenFailed。

• config.json 只包含用户设置；窗口布局写入 window-state.json，pressed state、权限结果和模型解析缓存不持久化。

• window-state.json 使用独立 v1 schema，保存设置窗口的逻辑坐标、尺寸与 maximized 状态，以及 overlay
  的坐标与尺寸；不读取或转换开发期间出现过的其他结构。坐标支持多显示器负值并设有有限范围，
  设置窗口尺寸限制为 640x480..16384x16384，overlay 尺寸限制为
  64x64..16384x16384。缺失、损坏、越界、未知字段或读取失败只回退到鼠标当前所在显示器
  居中的默认尺寸，不得阻塞 config 或 runtime 启动；非 v1 window state 回退显示且不被覆盖。

• window state 通过环境内独立的 window-state.writer.lock 和原子替换提交，提交后重读 typed window state，失败恢复
  替换前 bytes；它不进入 config revision、backup 或 quarantine。GPUI bounds observer 对连续变化
  合并 150 ms 后通知 settings worker，overlay frame source 仅在几何真正变化时通知同一 worker；
  正常 shutdown 前仍强制 flush。配置提交、模型切换和窗口重建必须保留另一窗口已保存的几何，
  窗口完全离开当前显示器时回退到鼠标当前所在显示器居中，fullscreen 不持久化。

• 模型导入防止路径穿越、符号链接逃逸、压缩炸弹和覆盖现有用户数据。

• 模型来源只有一种：用户通过文件夹选择器或窗口拖放提供的文件夹，就地读取后复制进 store 自己的
  staging。压缩包来源与它的解压边界已随实现一并移除（ADR-0036 已撤回，见该 ADR 的撤回说明）；要恢复
  时先与维护者确认。

• 嵌套模型文件夹由 settings worker 调用 model store 只读发现：复用包的深度与条目预算，
  拒绝链接、路径逃逸和包含目标 store 的来源，按相对路径排序。识别模型根后停止向资源目录
  继续发现；普通包复用包验证与输入模式分类，Mver 源保留整组模式。单个嵌套模型自动进入
  原导入流程；多个模型复用 GPUI Kit Dialog/Checkbox 展示所选文件夹名称与相对路径，默认
  全选、空选禁止确认。选中来源逐个重新检测，按需选择模式，再执行已有导入与封面截取，
  当前模型结束后才继续下一项。失败通知后继续独立来源；取消导入或关闭任一选择弹框清空
  剩余队列。队列只存 UI 临时草稿，不进入持久化配置（ADR-0087）。

• 导入在提交前把包内 resources/left-keys 与 resources/right-keys 下的旧键位名归一化到产品
  词汇表：Alt.png → AltLeft.png、AltGr.png → AltRight.png（ADR-0038）。这一步只作用在
  ModelStore 自己的 staging 上，因此用户选中的源目录始终是只读输入；改名不改变文件数与字节数，
  ModelImportProgress 的计数仍然真实。canonical 文件已存在时保留它、旧名文件原样留下，不猜
  作者意图。Mver 转换路径不做这一步——它的输出已经按产品词汇表命名。

• 第二种来源是 BongoCatMver 模型（ADR-0037），同样按内容识别，且需要两条独立证据：根
  config.json 能解析成 legacy 的 section 形状，且它命名的模式里至少有一个在
  <资源根>/<模式>/cat_model/ 下恰好带一个 .model3.json。缺任一条就回退到普通包导入并
  由那条路径报错，检测本身不报错。

• 解析 legacy config.json 的严格程度必须与它自己的读取端一致：该应用用 JsonCpp
  CharReaderBuilder 读这个文件，而它的默认设置含 allowComments，所以模型作者用 // 或
  /* */ 注释标注键位表是格式本身接受的内容，不是损坏。因此读取前先剔除字符串字面量之外的
  注释（字符串里的 / 是数据，\" 不结束字面量），再做严格 JSON 解析。放宽只到注释为止：
  注释移除不能把不是 config 的文件变成 config，也不能破坏多字节字符——否则检测又会静默回退，
  用户拿到的仍是「模型包无效」这种与模型无关的解释。

• 普通包的模式在 staging 复制、键名归一化和第二次 PreparedModel 校验之后、原子 rename
  之前判定：任一手出现手柄专用键名（DPad*、*Trigger*、South/East/West/North、
  Start/Select 等）判 gamepad；否则有 right-keys 判 keyboard；否则有 left-keys 判
  standard；两类都没有则以 InvalidPackage 拒绝。该结果由 store API 返回并写入 config，
  不在 UI 每次渲染时重新扫描。手工复制进 store 的异常目录若没有 metadata，只有在仍能通过
  同一资源判定时才临时投影模式；无效目录不显示模式 Badge。

• 一个 Mver 源产出多个 BongoCat 模型：每种输入模式各自转换成一个包，各自分配随机 UUID
  v4 存储键与元数据记录，因此三种模式是模型列表里三个可独立启用/改名/删除的条目。每个转换
  模型把所选 legacy source section 的模式写入 model.imported_models[].input_mode；模式事实来自
  source section，不从转换后目录形状或标题反推。每个模式独立提交——某个模式的键位图损坏不
  影响已转换成功的模式，与"这几种模式彼此独立"的事实一致。

• 转换只把合成后的包写进 ModelStore 自己的 staging，并与目录复制共用同一个 PreparedModel
  校验与单次 rename 提交尾部，因此不可能绕过包校验，也不存在第二个临时位置。

• 键位图合成是"最小画布上的 Porter-Duff over"：画布取两层较小的宽高、两层锚在原点，因此过大
  的一层被裁切而非缩放；模式没有 keyboard/ 图集时按字节安装 paw 图而不合成；某个绑定缺 paw
  或配套键帽时只跳过该绑定。输出文件名沿用产品自己的词汇表——键盘键是 bongocat-live2d-render 从
  HID usage 解析出的名字，手柄键是 GamepadButton::key_image_name（ADR-0070）；gamepad 的键位表用
  历史 XInput 按钮序号（这是 Mver 资源词表，不是当前手柄 backend API），映射到产品自己的十六个按钮
  名：0–3 面部键、4/5 肩键、6/7 模拟扳机、8/9 菜单键、10/11 摇杆键、12–15 方向键；无法命名的控制码
  不产出图片也不报错。

• 合成图按 lossless 方式重编码（oxipng，只开库入口）：位深/颜色类型/调色板/灰度缩减保持解码
  后像素不变，optimize_alpha 只改写全透明像素的颜色通道。有损量化库因许可证（GPL）被排除；
  Zopfli 后端实测多 5% 体积换 15 倍时间，不采用。重编码失败写回普通编码结果，不让转换失败。

• 转换逐字节复制模式的 Live2D 包，唯一例外是 motion 条目里指向源中不存在文件的 Sound
  引用：以「源实际携带的文件集合」判定悬空，丢弃该 Sound 键，其余内容保持不变。这沿用上文
  「少一张键位图不等于这个模型不可用」的决定——从 Cubism 官方示例包改装的模型会留下示例的
  Sound 名，而 Mver 实际从自己的每模式音效列表播放，丢掉这个名字不损失任何东西，保留它则让
  整个模式过不了包校验。只丢弃「缺失」的引用：无法规范化的引用（越出包根、绝对路径）保持
  原样交由包校验报错，不因为转换而悄悄抹掉一条路径安全发现。没有悬空引用时 entry 逐字节不变，
  因此转换不会顺手重写第三方模型文件。

• Mver 源的检测与转换只在 settings service worker 执行，UI executor 不做阻塞文件或模型解析；
  跨模型进度在应用层折叠（累计已完成模型的文件数与字节数、stage 取最大值），因此用户看到的是
  不倒退且终值等于各模型总和的一条序列，而不是卡在第一个模型的终值。标题为
  「用户标题 · 本地化模式名」，模式名在截断之后拼接，长来源名不能挤掉三个模型之间唯一的区别。
  诊断上只新增 store 码 SourceConversionFailed（映射到既有
  ModelImportSourceUnsupported），没有新增用户可见错误码。

• 模型包在反序列化或图片解码前执行 JSON 字节/深度、单文件/整包字节、文件数、目录深度
  和纹理尺寸上限。model ID、资源路径、model3 数组索引、任意 JSON bytes 和 PNG header/
  dimensions 具有可收缩 property contract；接受的资源路径必须规范化为幂等、相对且只含
  normal component 的包内引用，任何随机输入不得 panic、越界索引或绕过分配上限。

• model ID 是跨 Windows/macOS 可移植的 ASCII store key：禁止前导/尾随点、路径分隔符及
  Windows 保留设备 stem（含带扩展名的 CON、PRN、AUX、NUL、COM1..9、
  LPT1..9），不得让同一 installed identity 在目标平台解析为设备或隐藏路径。

• 任意外部目录只能产生待导入的 PreparedModel；只有当前环境 ModelStore 完成复制、复验和
  原子提交后签发的 InstalledModel 才能进入 runtime 激活 command。

• 应用装配时打开并持有只读 PresetModelCatalog；设置与模型管理只消费预置目录和当前
  环境 ModelStore 的合并目录，不在 UI executor 临时扫描或解析模型文件。

• installed 目录扫描逐条目降级：ModelStore::list 只在 store 根目录本身不可读或 writer
  lock 竞争时失败，单个条目绝不使整表不可用。文件管理器与操作系统元数据（.DS_Store、
  .localized、Thumbs.db、desktop.ini、AppleDouble ._*）按文件名忽略，既不计入
  目录也不计入诊断；其余不是「自有模型目录」的条目（非常规目录、符号链接、非 UTF-8 名称、
  非可移植 model_id 的目录名）静默跳过并计入 InstalledModelCatalog::skipped_entries。
  带合法 model_id 但包校验失败的目录仍签发 Invalid 条目，保持可见。过滤完全在 store
  内部完成：skipped_entries 不进入 settings snapshot，也不产生任何用户可见文案或无障
  碍输出，用户只看到可用的模型集合；符号链接始终不被跟随。

• 标准预置模型 standard 是始终可用的默认回退：目录身份 (origin, model_id) 在数据结构
  上区分预置模型与用户导入的自定义模型，所有自定义模型不可用时仍能回退到 standard。

• 应用启动时执行模型恢复：优先激活配置中完整的 model.selected_model: { id, source }；该模型缺失或
  不可用时记录匿名回退事件、把 standard 内置模型持久化为修正后的选择并激活它，恢复失败不阻塞启动。
  未配置选择时同样默认激活 standard。启动还会在 operational 状态下清理指向已不存在模型目录的
  model.imported_models 元数据记录；
  目录存在但内容无效的记录保留，由合并目录的稳定诊断码呈现。启动期清理失败的记录留待
  下次启动重试，不影响其他模型或应用整体。

• 模型导入 command 携带标题与文件选择来源（文件夹选择器选中的目录，或设置窗口拖入的单个目录）；
  标题只是显示名称，不参与身份——settings service worker 在导入前用随机 UUID v4（uuid 1.28.0，
  精确 pin）生成当前 store 内唯一的可移植存储 ID，因此重复导入同一目录不会覆盖已有模型，
  显示名称可以随时编辑，用户也无需发明任何 ID。导入成功后把标题和模式写入 model.imported_models
  元数据：Mver 写入实际选中的 source mode；普通包在 staging 通过 left-keys/right-keys 资源
  判定为 standard/keyboard/gamepad，判定失败直接拒绝导入，不写入 store 或 config。标题
  取导入 command 携带的值，页面在选中来源时按文件夹自身的名字预填，导入后可在模型卡片里
  改名；空白值依次降级为该名字和模型 ID，超长标题截断到元数据上限；元数据提交失败按导入
  失败报告且已导入目录保留。改名只更新 title，保留 input_mode；删除模型在 store 删除成功
  后同步移除对应元数据记录。

• 模型目录身份是 { id, source }。同一 id 的 built-in 与 imported 条目都保留，
  后续选择 command 必须携带 source，不得以静默覆盖解决冲突。Models 页面的顺序由
  Application::model_catalog 一处决定，分两半：built-in 在前，按 MverInputMode::ALL 的
  模式顺序（标准 → 键盘 → 手柄，不是 id 字母序——三个 id 的字母序恰好是它的倒序）；
  imported 在后，按 config.model.imported_models 的记录位置，也就是导入顺序，因此新导入的
  模型落在页面末尾且此后不再移动。没有元数据记录、只存在于 store 根目录的包排在该半区末尾并
  按 id 排序；id 在两半区都出现时 built-in 一定在前，因为整个 built-in 半区都排在前面。

• 模型改名与换封面对两个 source 完全一致（见 ADR-0047）。imported_models[].title 与
  built_in_models[].title 是可编辑显示名；imported 记录还保存导入时确定的 input_mode，
  built-in 模式由稳定 built-in id 派生。封面在 imported source 上是包内文件
  resources/cover.png，在 built-in source 上是用户侧的
  <data>/model-overrides//resources/cover.png（app 包不可写，见 ADR-0047 决策 2），两边都由
  bongocat-model 的 package_cover_path 推出布局，分别由 bongocat-model-store 的
  ModelStore::replace_cover 与 PresetCoverStore::replace_cover 做同目录原子替换。导入成功后，每个新导入模型的封面会被换成
  该模型自己渲染的一帧（见 ADR-0055）：settings worker 只把模型与它在协议里的身份排队，
  GPUI 线程在永不显示的原生窗口里渲染、读回、裁切并编码，再经 ReplaceModelCover 写回同一位置，
  因此转换输出的占位封面只在捕获失败时保留。预置模型只多一件事是禁止的：删除。它的包永远是
  product files，改名与封面只是用户侧的记录，包本身从不被写入。

• settings 快照把页面需要、但不属于配置的模型事实一并投影：每个模型条目携带 input_mode、自己的
  包目录与包内封面路径（包内没有封面时为 None），页面因此只显示模型自己的图、显示已解析的
  模式并可直接打开模型文件夹，而不自行推导任何路径或扫描资源目录。模式 Badge 是展示元数据，
  不在 snapshot 层改变 runtime 输入绑定。

• 模型选择 command 携带完整复合身份。应用先校验并加载候选，再以 expected revision
  持久化选择并启动 runtime/renderer 两阶段提交；候选被拒绝时 runtime 保留旧模型，应用
  使用刚取得的 config revision 原子恢复旧选择。配置写入失败时不得发送激活 command。

• 合并目录通过强类型 settings snapshot 投影来源、可用状态、资源计数和稳定诊断码；无效
  模型继续可见，但用户路径、底层 I/O 文本和模型内容不得进入 UI snapshot 或日志。

• 模型导入 command 只由 settings service worker 执行复制和复验；成功后刷新合并目录，但
  不隐式激活模型或修改选择配置。失败只返回稳定、
  可操作且不含用户路径的导入错误码。settings snapshot revision 同时观察 runtime 变化并为
  catalog-only 变化递增，禁止返回内容已变但 revision 未变的快照。settings client 为每次导入
  分配跨 clone 单调递增的强类型 operation ID；operation 只公开 prepare/copy/validate/commit
  stage、已复制文件数和字节数，不携带用户路径，并通过共享原子取消令牌在 service worker
  阻塞于分块复制时仍可取消。cancel 在原子 rename 提交前生效并清理 staging，
  final result 携带同一 operation ID；后续 Models 页面只消费该契约，不自行执行文件 I/O。

• 模型来源进入设置 UI 有两个等价入口：原生文件夹选择器 pick_model_folder，以及设置窗口根视图
  接收的 GPUI ExternalPaths 文件拖放。两平台的选择器都用 rfd 0.17.2 的 pick_folder（macOS
  AsyncFileDialog，Windows FileDialog）。macOS 只在 AppKit 主线程且已有窗口可作为 sheet parent
  时创建 AsyncFileDialog，缺少 sheet parent 时返回 BackendUnavailable，不回退同步 runModal；
  Windows 在专用 worker 的 STA 中调用 FileDialog。两平台都只向上返回 Selected(PathBuf) /
  Cancelled 和稳定无路径错误码，Rust 侧重新检查绝对、存在与类型（必须是目录）并 canonicalize；
  选择层不判定所选目录里是不是可用的模型包，真正的包解析/复制仍只由 settings worker 执行。
  rfd 将取消与后端失败都表示为 None，当前 adapter 按取消处理；对话框取消不是错误，错误不得
  携带系统文本或用户路径。

• 文件拖放是窗口级手势：根视图和临时蒙层都注册 ExternalPaths 的 drag/drop handler，另由
  paint-phase 的 window listener 接收 FileDropEvent::Exited，因此指针已经移出 viewport 时也能立即
  清理蒙层。一次只接受一个路径；多选在蒙层阶段显示拒绝状态，松手后只产生稳定的
  ModelImportDropInvalid 通知。单路径若不是目录、已不存在或无法 canonicalize，则由后台复验拒绝并
  通过同一稳定错误码报告。拖入路径先由 bongocat-platform::validate_model_folder 在 background
  executor 复验并 canonicalize，再进入既有 InspectModelSource、转换选择、导入、取消和封面截取
  流程；UI executor 不遍历、复制或解析模型文件。

• 剪贴板 adapter 通过私有 arboard 3.6.1 边界只接受最多 1 MiB、无内嵌 NUL 的纯文本；无文本
  返回空选项，过大、无效、拒绝或系统故障只返回稳定匿名错误，绝不记录文本。macOS 调用必须
  在 AppKit 主线程和 autorelease pool 内，Windows 的打开、写入和关闭由 arboard 的 RAII
  guard 在同一线程完成。依赖类型、系统错误和剪贴板内容都不离开 adapter；底层读取在项目
  大小校验前可能已物化系统提供的完整文本，这是当前第三方文本 API 的已知边界。

• Models 页面在 GPUI Entity 中只保存视图状态——导入草稿（来源目录、由来源名派生的标题、导入状态
  与本次导入的 baseline，运行中的 operation monitor 就在该状态里）、删除确认、编辑草稿、每行的
  焦点句柄，以及文件拖入期间的临时 Ready/Busy/InvalidSelection 蒙层状态——不持有任何路径文案：
  导入卡片只显示匿名的 choosing/validating-source/importing/capturing 步骤；validating-source 是文件夹
  选择器与拖放在取得路径后共用的“读取模型文件夹”阶段，不进入 snapshot、状态文案或日志。导入进行中以
  100 ms UI timer 重新渲染卡片，读的只有 operation ID 与取消状态（不读文件数/字节数），cancel 直接
  设置共享原子令牌；失败与取消都回到上传提示并只经 Notification 报告，不提供页面内 retry。GPUI
  executor 不遍历、解析或复制模型文件，成功只刷新 catalog，不隐式切换 active model。

• Models 卡片的模式信息只来自 SettingsModelEntry.input_mode：固定 GPUI Kit Badge 作为封面右上角的
  覆盖层容器，承载无图标的中性 secondary Tag；三种模式使用相同的主题底色，文字在两种语言中始终可见。
  它不创建新行，不加入 Tab 顺序，也不在 UI 线程重新扫描资源。Badge 的上游 primitive 本身不承载文字，
  因此可见 Tag 才是模式标签。模式 Badge 是配置/来源类别的展示，不改变 renderer 或 runtime 的输入绑定。

• 模型删除 command 同样携带 (origin, model_id)；preset 永不可删。installed 模型始终可删，
  包括当前 runtime active 或配置所选的那个：删除前先按同一 typed selection 路径切回标准预置，
  切换失败即中止删除，绝不在 runtime 仍持有该包时移除文件。删除本身仍以 rename 后删除事务退休；
  同 ID preset 不得阻止删除 installed 副本。成功刷新 catalog，并把回退后的选择一并反映到快照。

• 更新的 manifest 获取、版本比较、下载、验签、安装与重启由 cargo-packager-updater 0.2.3 承担；
  bongocat-update 只保留 BongoCat 侧策略与诊断契约，不自行实现传输或替换层。信任模型为
  detached minisign 签名：发行载荷必须由发布私钥签名，客户端以编译进构建的公钥校验，
  私钥不得进入源码、产物或配置。签名端与打包端是同一个 crate（cargo_packager::sign），
  因此签名器与验签器不会各自演进。ADR-0021、ADR-0022、ADR-0025 与 ADR-0026 定义的 detached
  清单签名、manifest v1 schema、单调 release_sequence 防降级与旧自研 manifest scheduler 已由 ADR-0029 取代；
  ADR-0029 的库选择与 zipsign 归档内嵌签名模型已由 ADR-0034 取代，均不再有效。

• 更新源由不可变 ReleaseConfiguration 描述：发行仓库、构建期 channel、target triple、二进制名与
  macOS bundle 名全部是编译期常量，任何用户配置、CLI 或运行时输入都不能改变它们。Development
  构建的 channel 不允许联网或安装，check 与 install 在发出任何请求前即失败关闭；Production
  构建从公开发行渠道更新。更新 channel 按环境隔离是 AGENTS.md §10 的约束，独立于各 ADR。

• 签名公钥缺失时失败关闭：RELEASE_SIGNING_KEY 已内嵌发布公钥（key ID
  DF5E2C9D255DD85E）；缺失、空串或纯空白时 runtime 在发出任何请求前即返回
  update_signature_key_missing，绝不静默接受未签名载荷。UpdateRuntime::is_available() 仅在
  production channel 与有效公钥同时具备时为真，系统菜单据此决定是否在托盘根中创建「检查更新」入口；该
  门禁产出的是稳定、无路径的错误码，而不是库错误。

• 发行清单是一份共享 manifest（latest.json），形状为库的 static 形状：顶层 version、
  可选的 notes 加一个 platforms 映射，键为 <os>-<arch>，每项含 url、signature、format；
  runtime 从 releases/latest/download/latest.json 读取。平台键拼写必须与库一致（macos 而非
  darwin，aarch64 而非 arm64）。crates/bongocat-packaging 每个 target 写一份 fragment
  （<os>-<arch>.json，文件名即平台键），发布前由同一个工具的 --merge-manifests 合并成共享
  manifest——manifest 的形状与资产名由一处拥有，工作流只调用工具。发布漏掉某个平台键时，
  runtime 命中 update_no_matching_asset。notes 是发布说明，由 --release-notes <file> 写入，
  上限 32 KiB，超长在字符边界截断并追加可见标记；它随同一次请求到达客户端，不需要第二次网络调用。
  说明的内容不是两次 tag 之间的提交摘要，而是该版本在双语 changelog 里的条目：发布工作流先用
  --extract-release-notes <file> 从 CHANGELOG.md 与 CHANGELOG.zh-CN.md 各取出产品版本对应的
  同一条目，按「英文正文 → --- → 中文正文」合成一份文件，再把这一份同时喂给 manifest 与
  gh release create --notes-file，所以发布页和更新窗口渲染的是同一段文本。条目按 Markdown 二级
  标题匹配而不是按版本号搜索文本，因此正文里提到的版本、### 子标题和围栏代码块里的示例都不会
  被误当条目；版本在 changelog 里没有条目时提取直接失败，而不是发出一份描述别的版本的说明。

• 更新载荷：macOS 为已完成的 .app 打包成的 BongoCat-<version>-<arch>.app.tar.gz，
  架构段是 aarch64 / x64（归档根必须是 BongoCat.app/，库会丢弃根条目再装到 bundle 路径）；
  Windows 复用已发布的 NSIS 安装器 BongoCat_<version>_x64.exe。载荷名不带 target triple：
  该文件只可能出现在它所属的那个平台上，重复平台后缀对读者和 updater 都没有信息量，而扩展名
  已经足以区分它和 Windows 安装器。.dmg 不是更新载荷——它是人工安装路径。
  签名是打包流程的最后一步：minisign 签名覆盖发布时的确切字节，签名后不得改名、重压缩或 strip。

• 传输与安装由库承担，启用 Rustls 与 HTTPS；库的 reqwest 后端不启用。安装位置：macOS 由库从
  运行中的可执行文件推导其所属 .app 并整包替换；Windows 由库运行下载到的安装器
  （install_mode = Quiet → NSIS /S 静默、/R 重启）后自行退出进程，因此
  UpdateOutcome::Installed 只在 macOS 可观测。安装根为 $LOCALAPPDATA\Programs\BongoCat，
  用户可写，不需要提权。

• 库的错误、配置与平台类型不得扩散为项目公共 API。cargo_packager_updater::Error 在
  bongocat-update 边界内映射为 14 个稳定错误码，未识别的变体降级为 update_internal_failed；
  诊断导出只消费这些码与匿名聚合计数，不含任何库类型或动态平台文本。

• 打包入口 crates/bongocat-packaging 产出并签名更新资产：每个 target 的载荷、其 .sig 与
  manifest fragment；发布前再用同一个工具的 --merge-manifests 把 fragment 合并成共享
  latest.json。签名密钥通过 SIGNING_PRIVATE_KEY 注入，未设置即跳过签名（本地构建）；
  release workflow 反过来断言发布构建一定签过名，未配置密钥时直接失败，而不是发出一批无人能
  更新的产物。

• 更新管线由 bongocat-app::ApplicationUpdateService 独占：一条独立线程持有 UpdateRuntime，
  是唯一触碰网络、下载与安装的组件。它不复用设置服务循环——设置循环是串行阻塞的，一次百 MB
  级传输会让所有设置读写排队。命令通道有界且非阻塞；状态经 UpdateStateHandle 覆盖发布，窗口
  按 250 ms 轮询，因此窗口关闭、隐藏或渲染慢都不会反压 worker。操作属于 worker，不属于窗口，
  所以关闭窗口不取消任何操作。

• 更新窗口（bongocat-ui::update_window）是单例，入口是系统菜单「检查更新」与设置页 About。
  它渲染 Unavailable / Idle / Checking / UpToDate / Available / Downloading /
  Verifying / Installing / Installed / Failed 十种状态。Downloading / Verifying /
  Installing 三段可观测靠拆分库调用实现：runtime 用 download_extended + install 两次调用，
  因为库的 download_and_install 把验签与安装合成一次调用。失败带明确的 stage，下载阶段的错误
  再按 code 区分为传输失败与验签失败。

• 更新窗口按内容定高，下限 WINDOW_MIN_HEIGHT、上限 WINDOW_MAX_HEIGHT（与改版前同一高度）：
  十个状态里有一半只渲染一行文字，固定 460px 会让窗口大半是空的。测量的间距与内边距都取自该帧
  自身的 bounds，不写死常量，调整 p_4 或 gap 不会让窗口高度与内容脱钩。窗口测量在窗口过矮时
  仍然准确：内容列 flex_shrink_0 不收缩、空隙塌成 0，所以两处 gap 都还是那两处 gap，于是
  「先跳到上限再回落」的两步收敛变成一步到位。说明区（notes）按内容取高、以常量封顶，
  这是测量能收敛的前提：若让它跟着窗口长，窗口变高 → 说明区变高 → 窗口再变高会互相喂给。
  平台会把内容高度取整到整像素，所以「已经在目标高度」允许半像素误差，否则窗口会每帧重问一个
  平台给不出的高度。

• 更新窗口不允许拖拽边缘改变尺寸（is_resizable: false，macOS 去掉
  NSWindowStyleMaskResizable、Windows 去掉 WS_THICKFRAME/WS_MAXIMIZEBOX）：窗口高度就是
  内容高度，允许拖拽等于让用户选一个下一次状态变化就会撤销的高度。窗口没有 resize 手柄，因此
  也不需要「用户拖过就接管高度」这条分支。

• 开窗时先按内容定高并画完，再显示：内容定高只能在布局后才知道，而窗口未显示时拿不到帧
  （macOS 只为「遮挡状态判定为在屏幕上」的窗口跑 display link，也就是只发帧给它），所以等待
  「已经画对了再显示」会死等。做法是隐藏状态下手动布局一次测出目标高度，resize 之后再排一个
  foreground executor 任务把新高度同步回来、重画并 activate_window。应用 resize 本身也是同一
  个 executor 上的任务，因此后排的任务一定排在它后面——靠顺序保证，不轮询也不超时。

• 更新内容（notes）来自 manifest，是不可信输入。渲染交给 gpui-kit 的 TextView
  （CommonMark + GFM，含删除线、任务列表与表格），bongocat-ui::update_markdown 只持有策略，
  通过 MarkdownExtensions 插件在 gpui-kit 自己的节点处理之前认领（claim）节点：
  NoRemoteImage 认领 Node::Image 与 Node::ImageReference 并只显示 alt 文本，
  LiteralHtml 在 inline 与 block 两个位置各注册一次、认领 Node::Html 并按字面文本显示，
  RefusedLink 认领目标未通过 HTTPS 检查的 Node::Link 并把标签降为普通文本。不存在可注入的
  markup 层；图片与 HTML 里的 URL 都不会成为请求。输入在解析前截断至 32 KiB，并把块容器标记数
  限在 512——每层 CommonMark 嵌套至少对应一个容器标记，因此该上限同时限定了树深，而 TextView
  按层递归遍历，树深即渲染栈深。链接引用（[a][ref]）的目标在 gpui-kit 内部才解析，
  RefusedLink 无法在此判定，仍由只接受 HTTPS 的平台 opener 兜底。ADR-0069 记录了这条依赖：
  插件先于内建处理被询问，一旦上游改变顺序，认领就不再是拒绝。

• 更新协议由 bongocat-ui-protocol 拥有，bongocat-ui 只负责窗口与展示策略；两者不依赖
  bongocat-update。bongocat-app 做穷尽映射（stage 与 14 个错误码），新增一项会让映射编译失败，
  直到它被赋予用户可见含义。

• 安装后是否需要重启进程是平台事实：macOS 由库整包替换 .app，运行中的进程此后执行已删除的
  文件（预设模型目录是惰性读盘的），因此安装成功后自动重启——先按 §5.3 的顺序完成产品 shutdown，
  再以新进程启动新构建；Windows 由安装器 /R 重启，Installed 在该平台不可观测。
  重启不用 exec 替换进程镜像：它不结束进程、PID 不变，而 shutdown 已移除托盘 NSStatusItem，
  替换后的镜像创建的 status item 不会被布局，菜单栏图标因此消失（ADR-0035 §5）。

• 自动检查由 GPUI 侧调度（开关与间隔只有设置服务读得到）：新配置的
  updates.check_automatically 默认为 false，不会在启动时主动检查；用户打开后，
  启动后等 10 秒首次检查，之后按 updates.check_interval_hours 等待下一次检查；该整小时字段默认 24、范围为
  1..=8760，并随当前 v1 配置持久化。调度器以最近一次实际派发为期限锚点，并以低成本设置轮询
  重新读取间隔，因此修改间隔会重排下一次期限（缩短后若已到期则立即检查）。发现可用更新且窗口未
  打开时打开更新窗口。关闭自动检查不会改写已保存间隔；手动检查不受该字段影响。

• 传输有 30 分钟上限：transport 自身无超时，不设界会让 worker 永久阻塞；取值覆盖整条载荷传输。
  下载不支持取消——库没有 abort 钩子，真取消只能自研下载与验签，而自研验证层已被 ADR-0029/0034
  删除，因此不提供取消按钮而不是提供一个假的。

• 真实签名公钥注入、真实发布链路验证、操作系统包签名验证与失败启动恢复仍未完成；在这些证据齐备前
  不得声称更新功能或 stable 发布完成。ADR-0034 记录了换实现新引入的能力损失（归档完整性校验、
  per-platform 资产匹配、公钥轮换窗）与待验证项；ADR-0035 记录了 worker、窗口、发布说明与
  "安装后协调 shutdown 而非安装前"这一处需要维护者复核的取舍。

• 日志不记录真实按键序列、剪贴板内容、用户路径、配置/模型正文、URL、密钥/凭据或动态 OS 错误文本。

• 匿名 diagnostics export 由 settings service 的强类型 command 触发（自 Diagnostics 页面移除后无 UI
  入口，只由隔离 smoke 与排障路径使用），在当前环境 logs 目录以同目录
  原子替换写出固定格式的 JSON。导出只包含稳定错误码、匿名聚合计数、模型来源计数和 revision；
  不包含模型 ID、用户路径、按键值、原始配置/事件内容、时间戳或动态平台错误文本。

• application 与 Cubism Core 共用一套 UTF-8 单行文本 writer：每条记录依次包含 UTC 时间、级别、
  module、闭合 stable code、固定人类可读 message 和经过转义/截断的允许上下文；不写 JSONL，也不接受
  动态 OS 错误或用户资源正文作为日志协议。application 按 UTC 日写
  application-YYYY-MM-DD.log，Core 写 cubism-core-YYYY-MM-DD.log；单个文件达到 1 MiB 后切分
  编号文件，两类日志合计最多 8 MiB/32 个文件。

• 当前 v1 logging.level 接受 error/warn/info/debug/trace 并默认 info；
  logging.retention_days 接受 1..=30 并默认 7。日志先按日切换、再按单文件大小轮转，不提供
  rotation mode 配置；设置变更后立即更新共享过滤/retention controller 并清理允许删除的旧文件。
  error 用于关键失败，warn 用于降级/fallback/可恢复异常，info 用于重要业务状态，
  debug/trace 用于低频开发诊断；逐输入、逐帧、下载进度与 temporary presentation unavailable
  不逐次记录。清理或写入失败只增加匿名 dropped/pruned 计数，不删除当前配置或模型数据。

• writer 初始化后同步创建环境隔离的运行标记；标记只含 v1 schema 与固定 phase：running、
  shutting_down 或 panicked。下一次启动将旧标记匿名分类为 forced/unknown、shutdown interrupted
  或 panic 后立刻覆盖为新的 running，避免重复恢复循环；只有 runtime、音频与配置相关 owner
  完成正常 shutdown 后才删除。process panic hook 使用非阻塞写入追加固定
  application/panicked 文本 code，不读取 payload、源码位置、backtrace 或用户路径；
  Development-only 隔离 smoke 必须以同一 release 可执行文件产生真实 panic=abort，验证日志脱敏、
  配置字节不变、重启分类和标记清理；默认产品 CLI/API 不暴露该测试入口。

• 匿名 diagnostics export 的摘要只读取 app-owned writer 和 Cubism Core 的匿名
  written/dropped/rotated/pruned/active-bytes/retained-files/retained-bytes 统计，并另输出二者
  retained-bytes/files 的饱和聚合，不读取或复制 Core message。可预览的
  application lifecycle 历史仅能按 ADR-0027 从已知 .log 文件严格提取闭合 code，再重写为不含
  原始时间戳/上下文的 application-events.log，与该摘要组成当前环境的私有 preview bundle；Core
  历史内容不属于该 bundle。

初始字段命名和数据分类见 shared/config/contract.md，环境和 Bundle ID 决策见 ADR-0008。

继续兼容：

.model3.json  .moc3  .motion3.json  .exp3.json
.physics3.json  .pose3.json  .cdi3.json
texture_*.png  audio files
resources/left-keys  resources/right-keys
resources/background.png  resources/cover.png

新增 manifest 只能是可选元数据，不能破坏现有模型。

13. 测试、指标与可观测性 Copy Chapter

13.1 测试层级 Copy Section

• Rust 单元测试：reducer、输入映射、动画、配置、路径验证和模型语义。
• fixture：相同输入序列产生规范化状态快照。
• Cubism fixture：三个预置模型和异常/自定义样本的加载、动作、表情、物理和销毁。
• GPUI 测试：设置表单、命令、错误状态、键盘导航和窗口重建。
• 平台集成：窗口、输入、权限、显示器、托盘、启动项和单实例。
• renderer smoke/golden：非空帧、alpha、遮罩、blend 和资源语义。
• 性能/soak：启动、首帧、frame time、输入延迟、CPU/RSS/GPU 和 8 小时运行。
  macOS 定时 diagnostic preview 对每次 NativeOverlay::draw 调用记录有界的微秒样本，输出
  nearest-rank p50/p95/p99 与主线程完整循环错过下一 60 FPS deadline 的次数；采样不包括输入、
  runtime handoff 或 sleep，最多保留 4,096 个样本并显式报告溢出数。它是可复现的 renderer
  baseline 输入，不替代 Instruments、Metal System Trace 或跨设备发布验收。

13.2 输入不变量 Copy Section

• 每个 pressed key 最终由 KeyUp、状态校正或 Reset 释放。
• 队列压力不能静默丢 key/button edge。
• 重复 KeyDown 不破坏按压状态或边沿动画。
• 设备断开、锁屏和睡眠后 pressed set 为空。
• 鼠标移动合并不能阻塞键盘释放。
• gilrs adapter 的每 tick event 上限不能替代 backend 与高层 pending queue 上界；fork 的 bounded
  queue/epoch、overflow marker、authoritative reset 和 bounded stop/join acknowledgement 已有代码证据，但 WGI 焦点矩阵和双平台
  物理设备/长期证据仍未完成。backend context 启动后的最终诊断必须真实反映 gilrs shutdown 结果；不得
  因键鼠 callback 和 final Reset 成功而伪造 clean shutdown。

13.3 验收指标 Copy Section

• 60 FPS 时 p95 frame time <= 16.7 ms。
• input callback 到 runtime 接收 p95 目标 <= 2 ms。
• 正常压力测试 key/button edge 丢失计数为 0。
• 8 小时固定模型无持续内存增长或 GPU 资源泄漏。
• 所有线程在退出超时内完成 join，不依赖进程强杀。

Windows 使用 ETW/WPA、PresentMon、GPUView；macOS 使用 Instruments、Metal System Trace 和 os_signpost。基准记录硬件、系统、模型、DPI、FPS、样本和构建 commit。

14. Linux 策略 Copy Chapter

Linux 是后续能力，不是隐藏的首发任务：

• runtime、配置、模型和 UI 不使用 Windows/macOS 类型。
• GPUI 保持 X11/Wayland 构建路径，但首期 CI 不发布 Linux 安装包。
• X11 评估 XInput2；Wayland 全局输入受 compositor/portal 限制，不能承诺功能等价。
• Linux renderer、托盘、启动项和打包单独立项并建立能力矩阵。
• 不用轮询兼容层掩盖 Wayland 权限或协议缺失。

15. 风险与 Phase 0 退出条件 Copy Chapter

任一核心退出条件失败，先记录 ADR 并调整受影响的实现或发布目标，不能用产品代码、合成测试或编译结果掩盖 spike 失败。按 ADR-0011，未完成的外部证据不阻止无关模块的渐进实现，但持续阻塞对应功能声明和 stable 发布。

16. ADR 摘要 Copy Chapter

ADR-001：单一 Rust 应用 Copy Section

Rust 同时承担 UI、业务、平台调用和渲染实现，所有模块在同一 workspace 内以强类型接口协作。

ADR-002：GPUI 只用于设置 UI Copy Section

GPUI 提供设置体验，但不成为 Live2D renderer 或实时状态所有者，以隔离 pre-1.0 风险。

ADR-003：平台原生 Overlay Renderer Copy Section

Windows 使用 D3D11，macOS 使用 Metal。模型窗口不嵌入 GPUI renderer。

ADR-004：输入状态可校正 Copy Section

输入事件提供低延迟边沿，系统状态查询与生命周期 Reset 保证最终一致。任何 hook 库都不是唯一事实来源。

ADR-005：Cubism 是唯一厂商 FFI 边界 Copy Section

允许调用官方 Cubism Core；BongoCat 业务不得进入 SDK bridge。

ADR-006：首发不支持 Linux，但不封死 Linux Copy Section

共享模块保持平台无关；Linux 的输入和窗口限制在后续能力矩阵中诚实处理。

ADR-007：单一 Rust 运行环境 Copy Section

生产版本的 UI、运行时、平台服务和渲染器均属于同一 Rust 应用。历史版本只用于行为与资源对照。

ADR-008：应用身份与存储环境隔离 Copy Section

Bundle ID 固定为 com.ayangweb.bongo-cat。Development 与 Production 使用相同数据结构和不同存储根，BongoCat 不读取旧配置。

ADR-011：渐进实现与发布门禁分离 Copy Section

允许正式 Rust workspace 在外部证据补齐期间持续开发；Cubism 授权与分发、实机矩阵、签名和稳定性证据保持 stable 发布门禁。

ADR-012：有序 Motion 音频服务 Copy Section

runtime 非阻塞发布强类型音效命令，独立 Rust worker 使用最小 rodio/FLAC feature 管理唯一 voice、错误恢复和 shutdown；音频失败不影响动作或渲染。

ADR-013：启动项能力与环境隔离（已被 ADR-0043 取代） Copy Section

Windows 当前用户 Run value 按 Development/Production 分名；macOS 13+ 只允许 Production
.app 使用 SMAppService.mainAppService，macOS 12 与 Development 明确报告不支持且不回退。

ADR-043：启动项后端统一 auto-launch Copy Section

双平台启动项后端统一为 auto-launch 0.6.0：macOS 12+ 全版本 LaunchAgent plist、Windows
HKCU Run（CurrentUser），环境隔离通过不同 app_name 保持；后端只产生 Enabled/Disabled，
Stale/RequiresApproval/NotFound 保留为契约变体。Windows stale 检测退役。

ADR-051：开发构建不提供登录时启动 Copy Section

登录时启动只属于已发布的产品：开发构建的可执行文件是 Cargo 构建产物，注册项会在 cargo build
或清理 target/ 后指向已过期或不存在的二进制。bongocat-app 因此按构建环境判定，开发构建直接汇报
Unsupported(BuildEnvironment) 且不触碰平台（读取与写入两个方向都答同一状态，写入是 no-op 而非
错误），设置里的启动项整行只在该构建不提供该能力时按统一样式禁用，并保留可见的 unsupported_build 文案说明原因。
取代 ADR-0043 中"Development 构建从此支持启动项"这一条决策，平台后端与环境隔离本身不变。

ADR-021：签名更新 Manifest 信任边界（已被 ADR-0029 取代） Copy Section

自研 manifest 验签、构建环境绑定与单调 sequence 防降级已退役，更新信任模型改为归档签名。
正文保留在 ADR-0021 中作为历史记录。

ADR-022：更新 Manifest 传输 Envelope（已被 ADR-0029 取代） Copy Section

携带固定 key ID 与 signature header 的 manifest envelope 随 ADR-0021 一并退役，传输改由更新库
承担。正文保留在 ADR-0022 中作为历史记录。

ADR-029：第三方更新库边界（已被 ADR-0034 取代） Copy Section

bongocat-update 只保留构建期 ReleaseConfiguration、环境 channel 门禁、签名公钥失败关闭与
匿名诊断契约；下载、校验、安装与重启全部交给第三方更新库。ADR-0021、ADR-0022、ADR-0025 与
ADR-0026 由本 ADR 取代。本 ADR 的库选择（self_update 1.3.0）与签名方案（zipsign 归档内嵌签名）
已由 ADR-0034 取代。正文保留在 ADR-0029 中作为历史记录。

ADR-0036：模型导入的压缩包来源与解压边界（**已撤回**） Copy Section

该 ADR 已撤回（2026-09-22）：压缩包来源、解压边界与 SourceArchiveUnsupported 稳定码连同
实现一并移除，bongocat-model 不再依赖 zip/flate2，ModelPackageLimits 不再有
maximum_archive_bytes。模型来源只有一种：由文件夹选择器或窗口拖放提供的文件夹。ADR 正文保留在
docs/adr/0036-model-archive-import-boundary.md 作为恢复该功能时的设计输入——恢复前先与维护者确认
（压缩包上传需要一组本次不做的新功能）。压缩包与第三方模型内容不进入仓库。

ADR-0035：更新 worker、更新窗口与发布说明 Copy Section

更新管线由独立 worker 线程独占，窗口只消费它发布的状态；UI 拥有协议，app 做穷尽映射。三段可观测
（下载/校验/安装）靠把库的 download_and_install 拆成 download_extended + install 实现。发布说明
随共享 manifest 的 notes 一起发布（有界、无第二次请求）。安装后重启是平台事实：macOS 自动重启，
Windows 由安装器 /R 负责。明确不做下载取消。记录一处与 §8.4 措辞不同的取舍：shutdown 协调放在
安装完成之后、替换进程之前，理由见该 ADR。

ADR-0034：Detached Minisign 更新信任模型 Copy Section

更新库改为 cargo-packager-updater 0.2.3，信任模型改为 detached minisign 签名。签名端与打包端
是同一个 crate（cargo_packager::sign），签名器与验签器不会各自演进。发行清单是一份共享
latest.json（库的 static 形状，含 <os>-<arch> 平台映射），由每个 target 的 fragment 合并
而成；macOS 载荷是根为 BongoCat.app/ 的 .app.tar.gz，Windows 载荷复用已发布的 NSIS 安装器；
两者各附一个 .sig，签名是打包流程的最后一步。本 ADR 取代 ADR-0029 的更新库与签名部分，并记录
换实现新引入的能力损失（归档完整性校验、per-platform 资产匹配、公钥轮换窗）与待验证项。

ADR-0030：先复用现有方案 Copy Section

新功能按现有代码、标准库、平台能力、已安装依赖、成熟第三方方案、最小自有实现的顺序选择。
只有现成方案无法满足已确认的边界，或引入成本明显高于自研时才自行实现；第三方类型和生命周期
仍受现有架构、安全与依赖规则约束。

ADR-0031：托盘第三方库边界 Copy Section

macOS/Windows 托盘使用 tray-icon 0.26.1，菜单与右键弹出使用直接依赖的 muda 0.21.2；平台
adapter 负责加载 PNG、映射强类型 action、调用 hide/show，并从 overlay session 的真实
HWND/NSView 弹出与托盘共用的菜单树。第三方类型、句柄和错误不进入 runtime/UI 公共 API，Windows
固定 GUID 与双平台唯一 owner 由 ADR-0031 约束。

ADR-0068：托盘与模型窗口右键菜单复用 Copy Section

托盘和模型窗口右键由同一个 SystemMenu owner 持有一个 popup 根、同一套菜单项、强类型 action 映射和
事件队列；菜单集中提供设置、模型窗口显隐/穿透/置顶/鼠标移入隐藏、可用的检查更新和退出。源码、版本、
重启和重复的缩放/透明度不进入原生菜单；菜单层级、析构顺序与平台实机验收门禁见 ADR-0068。

ADR-0066：gilrs 手柄后端边界 Copy Section

Windows/macOS 手柄统一使用 ayangweb/gilrs 固定 commit，平台只保留强类型输入与 generation/axis
适配。BongoCat 不再维护 XInput/GameController backend；fork 已提供 bounded queue/epoch、authoritative
reset、macOS/WGI bounded stop/join 和 target-scoped compile guard，Windows WGI 焦点矩阵与双平台物理/
长期证据仍是完成门禁，相关修复不在产品层增加 workaround。

ADR-0070：手柄按键图片词表与解析通道 Copy Section

手柄按钮与键盘键共用按键层通道，KeyPress 改为携带带标签的 KeyIdentity
（Keyboard(hid_usage) | Gamepad(GamepadButton)）。每个按钮的图片名等于 GamepadButton 变体名，
16 个按钮互不重名；预置 gamepad 模型已按该词表重命名，导入时由模型 store 把旧 backend 词表名
（LeftTrigger2/LeftThumb/DPad* 等）改写为产品名。手柄词表不提供运行时旧名候选，因为旧词表里
LeftTrigger 已经是肩键的名字；按钮左右手由模型自身的 left-keys/right-keys 目录决定，缺图按钮
保持惰性。

ADR-023：Windows Per-User Installer Copy Section

Windows 首发采用固定、可审计 NSIS per-user installer，不请求管理员权限或触及环境数据。原设计中的
「独立 Rust update helper 只接收已验证 artifact」已随 ADR-0029 作废：不再有独立 helper，替换由
更新库在进程内完成（Windows 上由库运行下载到的安装器），installer 权限、原子替换与 rollback 仍是
独立发布门禁。

ADR-0066：任务导向的设置信息架构 Copy Section

设置侧边栏固定为七个业务分类（外观与语言、模型库、模型行为、模型窗口、输入与交互、快捷键、应用与系统）
加最后的关于入口；模型库与模型行为各自独立成页，键鼠/手柄、启动/更新/日志形成明确的二级分组。
About 仍是 Settings 中的普通页面，产品/软件信息、项目与反馈入口、日志目录和手动检查更新使用标准设置项；
不展示法律与隐私正文，日志路径不进入 snapshot。页面与分组标题进入搜索关键词，旧页面名作为搜索别名；不增加第三级导航、常用页或高级页。

17. 实施阶段 Copy Chapter

Phase 0：风险验证和行为冻结 Copy Section

冻结参考行为和模型样本，定义全新配置命名与环境隔离契约；完成 GPUI + 独立 overlay、Cubism、输入可靠性、透明合成和许可证 spike。

Phase 1：Rust 工程骨架 Copy Section

在 Phase 0 外部证据补齐期间渐进建立 Cargo workspace、CI、日志、配置最小实现、runtime 生命周期、GPUI 空设置窗口和双平台空 overlay；只提升已通过对应 contract 的模块。

Phase 2：输入到 Live2D 最小闭环 Copy Section

加载标准模型，键鼠输入驱动参数/动作并绘制；Windows 完成 #47 校正，macOS 完成权限和 tap 恢复。

Phase 3：产品 Runtime 与模型兼容 Copy Section

实现状态、动画、手柄、动作、表情、物理、音效和模型管理，并由 fixture 验证。

Phase 4：GPUI 设置和配置存储 Copy Section

完成 design system、设置页、模型管理、快捷键、权限、诊断、环境隔离与当前 v1 schema。

Phase 5：系统集成 Copy Section

完成托盘/菜单栏、启动项、单实例、更新、日志导出、签名和权限流程。

Phase 6：稳定性与发布 Copy Section

完成性能基线、异常恢复、8 小时 soak、安装/升级/回滚和发布清单。达到门槛后完成发布切换。

Update Signing Guide (`docs/update-signing-guide.md`) Copy Section

桌面应用更新签名机制入门

文档性质：解释性说明，非规范性事实来源。
本文只用于讲解概念与记录调研结论，不定义目标架构。
规范性事实仍以 docs/technical-design.md 和 docs/adr/ 为准。
如果本文的结论要变成项目约定，必须先写成 ADR（见 §6.3）。

---

状态更新（2026-09-14）：本文的结论已经落地。

§0.3 推荐的方案 B（detached minisign 签名）已被采纳并实现，规范记录见
docs/adr/0034-detached-minisign-update-trust-model.md：更新库改为
cargo-packager-updater 0.2.3，签名端由 crates/bongocat-packaging 调用
cargo_packager::sign，macOS 载荷是 .app.tar.gz、Windows 载荷复用 NSIS 安装器，
各附一个 .sig。检查地址是
https://github.com/ayangweb/BongoCat/releases/latest/download/latest.json：一份共享
manifest（platforms 映射按 <os>-<arch> 给出每个 target 的载荷），由每个构建 job 写出的
<os>-<arch>.json fragment 在发布前用 just manifest 合并而成。

因此，下文凡是把 "self_update + zipsign 内嵌签名" 描述为"本仓库当前实现"的段落，
指的都是本文写作时（2026-09-14 上午）的 ADR-0029 状态，现已退役。§2.2、§4.1、
§4.2、§5.2、§5.3 属于该状态的技术记录，保留作为决策依据与历史对照，不再描述现状。
§6.2 的落地步骤已执行完毕；§7 清单中已完成的项在 §6.2 中可查到对应实现。
仍未被验证的事项以 ADR-0034 的"待验证项"为准——本文 §8 的若干条目已由
release_manifest_capability.rs 的 loopback 能力测试覆盖（真实密钥对、真实签名、真实验签）。

状态更新（2026-09-28）：macOS 载荷名去掉了 target triple。
下文写作时假定载荷必须含完整 triple，那是 self_update 的 Release::asset_for 按资产名
匹配资产的要求；该库已由 cargo-packager-updater 取代，载荷 URL 来自 manifest，不按名字匹配。
因此载荷现名为 BongoCat-<version>-aarch64.app.tar.gz / BongoCat-<version>-x64.app.tar.gz。
§5.2 那条"资产名必须包含完整 triple"的要求已随旧库退役，保留在正文里只作为历史对照。

写作日期：2026-09-14。所有"已确认"结论均来自本机源码阅读，没有执行过任何一次真实签名
或真实更新；未验证事项集中列在 §8。

0. 先给结论 Copy Chapter

0.1 你的产物形状与仓库现状不匹配 Copy Section

你描述的产物是：macOS = .dmg + .app.tar.gz，Windows = 只有一个 .exe，两平台各加一个
.sig。这是 Tauri 的模型（minisign 分离签名）。本文写作时本仓库的实现是
self_update + zipsign 内嵌签名（ADR-0029，现已退役），两者不兼容。三个当时已核实的硬事实：

0.2 Windows 用 `.exe` 是当前实现的必然失败 Copy Section

即使先不管签名格式：self_update 的安装语义是用下载物替换自己（单文件模式替换
bongocat-app.exe，bundle 模式整包交换 .app）。用 NSIS 安装器去替换 bongocat-app.exe
在语义上就是把应用本体换成一个安装器。上游对此有明确声明（self_update-1.3.0/src/lib.rs:302）：

.deb / .msi packages are a different shape entirely — hand the downloaded file to
dpkg -i / msiexec /i yourself; the crate's replace-and-verify semantics do not apply
to a system installer.

所以「Windows 只有一个 .exe」等价于「Windows 必须自己走『下载 → 校验 → 静默运行安装器』」，
这条路 self_update 不提供，必须自研编排。

0.3 推荐（已于 2026-09-14 采纳，见 ADR-0034） Copy Section

采用 cargo-packager 的 minisign 签名（生产端）+ minisign-verify（消费端），理由是它
同时满足你的产物约束和"不重复实现通用机制"的项目纪律：签名工具已经在依赖图里，.app.tar.gz
和 .sig 由现有工具生成，不需要引入新工具链。代价是要写一个新 ADR 取代 ADR-0029 的签名部分，
并在 Windows 上单独实现"运行安装器"的安装步骤。

落地时发现后一项代价比预期小：消费端不必自研。cargo-packager-updater 与
cargo-packager 同属一个项目，它自带 UpdateFormat::Nsis（运行下载到的安装器）与
UpdateFormat::App（整包替换 macOS bundle），因此"运行安装器"这一步不需要本项目实现。
最终方案是整条链路换用 cargo-packager-updater，而不是在 self_update 上挂 minisign 钩子。

如果不想动验证模型，则走方案 A（保持 zipsign）：macOS 几乎零成本，但 Windows 必须增加一个
载荷归档文件，与你的"不引入其他文件"约束冲突。详见 §6。

1. 密码学基础 Copy Chapter

1.1 自动更新要防的是什么 Copy Section

用户装的是你发布的二进制。攻击者有几个现实的入手点：

1. 网络中间人：篡改下载内容（虽然 HTTPS 已经防了大部分，但 CDN、镜像、企业代理、
   证书被误信任都可能出问题）。
2. 分发渠道被投毒：GitHub Release 资产被替换、账号被盗后发布恶意版本。
3. 降级攻击：强迫客户端回退到有已知漏洞的旧版本。
4. 本地文件被替换：用户机器上已下载的临时文件被改。

签名机制主要针对 1 和 2 的"内容换掉了但看起来一样"这一面。它不能防：你的私钥被偷、
操作系统代码签名被绕过、或用户主动安装了你没有签名的东西。

1.2 哈希（摘要） Copy Section

哈希函数（如 SHA-256、SHA-512、BLAKE2b）把任意长度的数据压成固定长度的指纹：

• 单向：从指纹推不回原文。
• 抗碰撞：极难找到两段不同的数据得到同一个指纹。
• 雪崩：改一个字节，指纹面目全非。

哈希只解决 完整性（数据有没有被改动），不解决真实性。原因很直接：攻击者改完文件，
顺手把指纹文件一起改成新的就行。所以"我只公布 SHA-256"不足以证明东西是你发的。

1.3 为什么必须用签名而不是哈希 Copy Section

数字签名把"完整性"和"身份"绑在一起：用只有你能持有的私钥产生签名，任何人都能用公开的
公钥验证。攻击者能改文件，但改不出一个新签名——因为他没有私钥。

这正是哈希做不到的那一半。

1.4 非对称密钥与 Ed25519 Copy Section

• 一对密钥：私钥（保密，用来签名）+ 公钥（公开，用来验签）。
• 公钥不是从私钥"反推"出来的，而是数学上成对生成；所以即使公钥满天飞，私钥也不会泄漏。
• Ed25519 是目前桌面应用签名的默认选择：签名 64 字节、公钥 32 字节、私钥 32 字节种子，
  实现小、速度快、没有 RSA/ECDSA 那类参数选择陷阱（选错曲线、随机数复用导致私钥泄露等）。

Ed25519 的私钥在实践里常存成 64 字节的 keypair（32 字节种子 + 32 字节公钥）。本仓库用到的
zipsign 就是读 64 字节 keypair（SigningKey::from_keypair_bytes），公钥文件则是裸 32 字节。

1.5 预哈希：为什么出现 `Ed25519ph` 和 `BLAKE2b` Copy Section

Ed25519 原始定义是"对整条消息签名"。文件可能有几百 MB，而且流式读取时无法把整条消息留在内存里。
RFC 8032 因此定义了 Ed25519ph：先对消息做一次哈希，再对哈希值签名（ph = prehash），并用
一个域分离前缀防止与其他用法混淆。

不同项目选取的预哈希算法不同，这是两套签名格式互不兼容的根因：

两者都是"Ed25519 + 预哈希"，但预哈希不同、封装格式不同，签名文件不能互相识别。

1.6 信任根：公钥必须随二进制发布 Copy Section

这是整个机制里最容易被忽略、却最关键的一点：

验证用的公钥必须内嵌在客户端二进制里（编译期常量），绝不能从网络获取。

如果你从网络拿公钥，攻击者只需把公钥一起换掉，签名验证就变成自证清白。本仓库的公钥就是编译期
常量：crates/bongocat-update/src/runtime.rs 的 RELEASE_SIGNING_KEY。

推论：换钥匙必须先发一个"同时认识新旧两把钥匙"的版本。否则老版本用户会验不过新签名，更新链
从此断掉。这是 §3.3 密钥轮换的约束来源。

1.7 密钥 ID、多密钥与"any-of"语义 Copy Section

真实项目会轮换密钥，所以验签要能同时接受多把公钥。两套方案的差异：

• zipsign：verifying_keys(&[key1, key2])，语义是 any-of——签名在归档里可以有多条，
  命中任意一条即通过。这天然支持轮换窗。
• minisign：签名结构里带 8 字节 key ID；验签先比对 key ID，不匹配直接
  UnexpectedKeyId 失败（minisign-verify-0.2.5 源码确认）。所以传错公钥是明确报错，
  不会"悄悄通过"。

key ID 的价值是错误定位：日志里能区分"钥匙不对"和"内容被改".

1.8 上下文绑定：签名可以绑到文件名上 Copy Section

zipsign 的签名计算把文件名作为 Ed25519ph 的 context 一起签（self_update 传的是下载文件的
file_name()；zipsign CLI 的 -c/--context 默认也是文件名）。

后果很实际：zipsign 签名过的归档改名之后就验不过了。这条约束直接决定 CI 里"命名"和"签名"
的先后顺序（§5.1）。

minisign 把文件名放在 trusted comment（timestamp:...\tfile:<名字>）里，并且对这段注释有第二
个"全局签名"。但客户端是否比对文件名取决于验证实现：minisign-verify 0.2.5 的
PublicKey::verify() 只校验 key ID + 内容预哈希 + Ed25519 签名，不比对 file: 字段。所以
minisign 改名后技术上仍可验证通过（代价是丢掉了文件名绑定这一层弱保护）。即便如此，仍然应当
"先命名、后签名"，避免给未来留坑。

1.9 更新签名 ≠ 操作系统代码签名 Copy Section

这是新手最容易混淆的一点。它们是两套独立机制，各防各的：

本仓库两者都还是缺口：打包只做 ad-hoc 签名（crates/bongocat-packaging/src/main.rs:97 的
ADHOC_SIGNING_IDENTITY = "-"），release.yml 里 Windows Authenticode 目前只打 warning。

2. 两套现成方案 Copy Chapter

2.1 对比 Copy Section

2.2 「哪些产物能被签名」速查 Copy Section

self_update 用扩展名判定归档类型，所以能不能被 zipsign 签名完全由文件名决定：

再叠加一条：.dmg 本来也不该作为更新产物。它是人工安装路径（拖进 /Applications），
self_update 没有安装 dmg 的能力。Tauri 同样不使用 dmg 做更新。更新产物必须是"应用本体"：
macOS 是 .app 归档，Windows 是安装器或应用本体。

2.3 cargo-packager 已经能做的事（已读源码确认） Copy Section

cargo-packager 0.11.8 公开导出 pub mod sign，关键 API：

// 生成密钥（返回 base64 编码的公钥与私钥字符串）
cargo_packager::sign::generate_key(Some(String::new()))?;   // 空密码 = 不提示

// 把密钥对落盘：<path> 与 <path>.pub
cargo_packager::sign::save_keypair(&keypair, path, force)?;

// 签名单个文件，产出 <file>.sig
cargo_packager::sign::sign_file(&SigningConfig { private_key, password }, path)?;

// 签名整批产物；目录会先被打成 <dir>.tar.gz 再签名
cargo_packager::sign_outputs(&signing_config, &mut packages)?;

// 打包 + 签名一步完成
cargo_packager::package_and_sign(&config, &signing_config)?;

两个已核实的细节，正好对上你的需求：

1. 目录会被自动打成 BongoCat.app.tar.gz（with_additional_extension("tar.gz")），且
   归档根目录就是 BongoCat.app/——因为内部用 append_dir_all(filename, src_dir) 而不是
   展开内容。这正是更新库 bundle 模式要求的布局。该布局在落地后由
   crates/bongocat-packaging 的 the_bundle_archive_roots_at_the_bundle_directory 与
   crates/bongocat-update/tests/release_manifest_capability.rs 的
   installing_replaces_the_configured_bundle 共同锁定（原先锁定它的
   archive_layout_capability.rs 已随 self_update 退役删除）。
2. 签名产出的 .sig 内容是 base64 编码的 minisign 签名盒，sig_alg 固定为
   prehashed，trusted comment 形如 timestamp:\tfile:<文件名>，
   untrusted comment 是 signature from cargo-packager secret key。

3. 需求 1：签名密钥的生成方式与安全存储管理 Copy Chapter

3.1 生成 Copy Section

zipsign（当前方案） — 需要 cargo install zipsign：

zipsign gen-key priv.key pub.key      # 生成密钥对
zipsign gen-key -e priv.key pub.key   # 只从已有私钥导出公钥

产物形态（已读 zipsign-api 源码确认）：

• priv.key = 64 字节二进制（Ed25519 keypair = seed‖public）
• pub.key = 32 字节二进制

注意：它是裸二进制，不是 base64 文本。这意味着往 GitHub Secrets 里放之前必须自己 base64
编码，CI 里再解码。多一层手工步骤，也是出错点。

minisign（已采纳） — 已经在依赖的工具里，且不需要全局安装：

# 本项目入口（推荐）：用精确 pin 的 cargo-packager 生成，产物已 chmod 600
just keygen ~/.bongocat/release.key

它等价于 crates/bongocat-packaging --generate-signing-key <file>，也等价于直接调
cargo_packager::sign::{generate_key, save_keypair}。口令通过
SIGNING_PRIVATE_KEY_PASSWORD 提供（与签名时解锁私钥用的是同一个变量）；不设口令时
会生成未加密的私钥并打印警告。

just keygen 没有 password 参数，这是刻意设计：把口令放上命令行会进入 shell history，
也可能出现在进程列表中。交互式生成带口令的 key pair 时，在当前 zsh 中执行：

read -rs "SIGNING_PRIVATE_KEY_PASSWORD?Signing key password: "
echo
export SIGNING_PRIVATE_KEY_PASSWORD

just keygen ~/.bongocat/release.key

unset SIGNING_PRIVATE_KEY_PASSWORD

read -s 不回显输入；-r 保留反斜杠字面值。若 shell 是 bash，等价写法是：

read -rsp 'Signing key password: ' SIGNING_PRIVATE_KEY_PASSWORD
echo
export SIGNING_PRIVATE_KEY_PASSWORD

just keygen ~/.bongocat/release.key

unset SIGNING_PRIVATE_KEY_PASSWORD

不要写成 SIGNING_PRIVATE_KEY_PASSWORD='...' just keygen ...：虽然功能上可用，但口令会进入
shell history。生成完成后把私钥文件内容放进 SIGNING_PRIVATE_KEY secret，把同一口令放进
SIGNING_PRIVATE_KEY_PASSWORD secret；两者必须同时存在。

产物形态（本机实测，2026-09-14）：

• <file>：私钥，base64 单行文本，348 字节，权限 0600（工具显式收紧；save_keypair
  自身按 umask 落盘，默认账号下会是 644）
• <file>.pub：公钥，base64 单行文本，152 字节，0644
• 工具同时把公钥那一行打印出来，可直接粘进 RELEASE_SIGNING_KEY

因为是纯文本，可以直接整段塞进 CI secret，不需要额外编码步骤。

若坚持用上游 CLI：cargo install cargo-packager --version 0.11.8 --locked 后
cargo packager signer generate-key --path <file>。参数为 --path、--password（或环境变量
CARGO_PACKAGER_SIGN_PRIVATE_KEY_PASSWORD）、--force、--ci；不传 --path 时它只把密钥对
打印到日志，在 CI 里会直接把私钥写进日志。本项目不采用这条路，因为它要求全局安装与
lockfile 版本一致的二进制，而 just keygen 用的是同一份 pin。

Tauri 的等价命令是 tauri signer generate -w ~/.tauri/myapp.key，产出同一个格式
（base64 minisign 密钥），并支持给私钥设密码。

3.2 怎么进 CI（这是本需求真正的难点） Copy Section

私钥绝不能进仓库。 三条铁律：

1. 不进源码、不进构建产物、不进日志。 检查清单：git log -S 搜不到；构建输出里 grep 不到；
   错误信息不打印私钥内容。
2. 只通过 CI secret 注入。 GitHub Actions 里用
   secrets.SIGNING_PRIVATE_KEY（口令用 secrets.SIGNING_PRIVATE_KEY_PASSWORD）
   传给打包步骤的环境变量。注意 Tauri 文档特别强调的一点：.env 文件不生效，必须是真的
   环境变量。变量名已在 crates/bongocat-packaging/src/main.rs 中固定为
   SIGNING_PRIVATE_KEY / SIGNING_PRIVATE_KEY_PASSWORD。
3. 本地开发一律不签名。 签名只在发布流水线里发生；本地 just build 不设私钥时应当
   跳过签名（而不是用一个空密钥签名成功——那是最坏的情况，见 §4.4）。

具体形式（已落地在 .github/workflows/release.yml）：

# .github/workflows/release.yml 里新增
- name: Sign the update artifacts
  env:
    SIGNING_PRIVATE_KEY: ${{ secrets.SIGNING_PRIVATE_KEY }}
  run: just build            # 打包工具读到该变量才签名

对应到 crates/bongocat-packaging/src/main.rs 的现有模式：它已经有一个凭据注入点的先例——
BONGOCAT_MACOS_SIGNING_IDENTITY（第 103 行）。更新签名密钥应该照同样的方式设计：
一个环境变量注入点，不设就跳过，且必须让 CI 能断言"发布构建一定签过名"。

3.3 权限、备份、轮换、丢失 Copy Section

3.4 本仓库的落点 Copy Section

公钥的位置是 crates/bongocat-update/src/runtime.rs 的 RELEASE_SIGNING_KEY。

已落地的形态（ADR-0034）：base64 的 minisign 公钥盒文本，也就是
cargo packager signer generate-key 写出的 .pub 文件内容。仓库现已内嵌发布公钥，
key ID 为 DF5E2C9D255DD85E，因此 Production runtime 的
UpdateRuntime::is_available() 为真，系统菜单可以显示更新入口：

pub const RELEASE_SIGNING_KEY: Option<&str> = Some("<minisign public key>");

公钥不是秘密，可以正常提交到仓库；只有私钥和私钥口令必须留在仓库之外。运行时会拒绝
None、空串和纯空白值，并在构造更新库实例之前返回 update_signature_key_missing；
runtime.rs 的定向测试同时锁定已配置公钥和空白值失败关闭两条路径。真实 GitHub 发布链路尚未
验证，不能据此宣称发布签名已经端到端可用（见 ADR-0034 待验证项 1）。

4. 需求 2：更新校验时签名验证的完整流程 Copy Chapter

4.1 `self_update` 的完整校验链（已读源码确认顺序） Copy Section

取发布列表 → 选资产 → 下载 → ┌ 1. checksum（显式传入的摘要）
                             ├ 2. release digest（GitHub API 为该资产公布的 sha256）
                             ├ 3. signature（zipsign，用内置公钥集）
                             ├ 4. verify_archive 钩子（你注入的闭包）
                             ├ 解压
                             ├ 5. verify_binary 钩子（跑一下新二进制做冒烟测试）
                             └ 替换安装

第 2 项值得单独说：GitHub 会为每个 Release 资产公布一个 sha256:<hex>，self_update 在有
checksums feature 时默认自动校验。但上游明确写了这是纯完整性检查——攻击者替换资产后
GitHub 会重新计算这个摘要，所以它不能替代签名。

第 4、5 项是两个公开可用的钩子，签名类型是普通闭包：

pub fn verify_archive(&mut self, verify: impl Fn(&std::path::Path) -> crate::Result<()> + Send + Sync + 'static)
pub fn verify_binary(&mut self,  verify: impl Fn(&std::path::Path) -> crate::Result<()> + Send + Sync + 'static)

上游文档把"crate 自身不支持的分离签名校验"明确列为 verify_archive 的用途。这是把
minisign 接进现有流水线的关键入口——不需要抛弃 self_update 的下载/解压/替换引擎。

4.2 zipsign 的验签步骤（当前实现） Copy Section

1. 按扩展名判定归档类型；不是 .zip / .tar.gz → Error::NoSignatures。
2. 从归档里定位签名块：tar.gz 读追加的 gzip 成员注释；zip 读前置数据。
3. 校验魔数头 \x0c\x04\x01 + ed25519ph + \x00\x00，读出签名条数（u16 LE）。
4. 用文件名作为 context，对归档中"签名块之前"的内容算 SHA-512 预哈希。
5. 对每把公钥 × 每条签名做 verify_prehashed_strict；任意一条通过即通过（any-of）。
6. 全部不匹配 → Error::Signature → 映射为 update_signature_invalid。

4.3 minisign 的验签步骤（推荐方案） Copy Section

1. 读取 <产物>.sig，base64 解码得到 minisign 签名结构。
2. 比对签名里的 key ID 与内置公钥的 key ID；不匹配 → UnexpectedKeyId。
3. 对产物内容算 BLAKE2b-512 预哈希。
4. 用公钥对预哈希值做 Ed25519 验签。
5. 通过则继续解压/安装；否则拒绝。

（minisign-verify 0.2.5：PublicKey::verify(data, &signature, allow_legacy=false)。
allow_legacy=false 是正确值——它拒绝 minisign 老版本的非预哈希签名，也正好和
cargo-packager 的 prehashed 输出匹配。）

4.4 必须在设计里消掉的陷阱：fail-open Copy Section

这是本文最重要的一条实操警告。

self_update::verify_signature() 的第一行逻辑是：

if keys.is_empty() {
    return Ok(());      // ← 静默跳过验签
}

公钥集为空 = 验签直接通过 = 会安装未签名产物，且不报任何错。 任何"把公钥列表原样转发下去"
的封装都会踩这个坑。

本仓库已经做了正确补偿：RELEASE_SIGNING_KEY 缺失、为空或纯空白时，runtime 在发出任何网络
请求之前就返回 update_signature_key_missing（门禁位于 runtime.rs 的 updater()，并由
定向测试锁定）。仓库当前内嵌发布公钥，因此这条拒绝路径只会在未配置的构建或测试输入上命中。

换实现时必须保留这条性质。设计原则一句话："验签不可能成功"必须等于"拒绝更新"，而不是
"跳过验签"。

落地结果（2026-09-14）：新库在这一点上已经是 fail-closed——verify_signature 先 base64 解码
公钥再 PublicKey::decode，空字符串解不出公钥，直接得到 Error::Minisign，不会静默通过。
但它发生在下载之后：check() 只解析 manifest，因此空公钥仍会先得到一个更新offer，
失败落在 download()（这正是 release_manifest_capability.rs 的
an_empty_public_key_cannot_verify_a_payload 断言的形状）。

项目仍然保留了自己的门禁，理由不变：它在构造更新库实例之前就返回稳定、无路径的
update_signature_key_missing，而不是一个需要映射的库错误，也不会先发出请求。两者是纵深
防御关系，不是重复实现。

4.5 其余校验原则 Copy Section

• 先验签，后使用：签名校验必须发生在解压和替换之前（self_update 的顺序已经满足）。
• 失败一律 fail-closed：任何一步失败都不留下"半个已安装的新版本"。
• 错误码稳定：crates/bongocat-update/src/diagnostics.rs 的 14 个错误码是诊断导出契约
  （ADR-0016 / ADR-0027），换实现时只能收敛到既有码，不能泄漏第三方错误文本。
• 降级防护：ADR-0029 记录了 zipsign 模型没有单调 release_sequence，降级攻击不再被
  检测，只按 semver 比较。这是换实现时应当一并考虑补回来的东西。

5. 需求 3：更新分发环节如何接入并校验签名 Copy Chapter

5.1 顺序：命名 → 签名 → 合并 → 上传 Copy Section

关键约束来自 §1.8：签名与内容（含文件名）绑定。所以流水线上的正确顺序是：

编译 → 打包（.app / .dmg / .exe）
     → macOS: codesign + notarize（.app 必须先真正签名并公证）
     → 生成更新归档（macOS: .app.tar.gz；Windows: 复用 .exe）
     → 用正式名字命名
     → 签名（产出 .sig）
     → 写本 target 的 manifest fragment（<os>-<arch>.json）
     → 每个 target 各自上传为构建产物
     → 发布前合并 fragment 成共享 latest.json（just manifest）
     → 上传 Release

三条硬规则：

1. 签名必须是最后一步。 签名之后任何字节改动（重新压缩、改名、strip）都会让签名失效。
   对 zipsign 而言改名一定失效（文件名是签名 context）。
2. 归档内的 .app 必须先完成 codesign + notarize。 一旦打成 tar.gz，再想签名里面的 .app
   就晚了——解压、签名、重新打包会直接让归档签名失效。实际上"先打包再公证"在流程上根本走不通。
3. 命名和签名严格分先后。 先改好名字，再签名。

现状（2026-09-14）：合并发生在签名之后，但只作用于 manifest——它把各 target 已经签好的
url/signature/format 组装成一份文档，不触碰任何已签名的载荷字节，因此不破坏上面三条规则。
合并由 crates/bongocat-packaging --merge-manifests 承担（just manifest），CI 只调用工具。

5.2 资产命名要求（决定客户端能不能找到） Copy Section

现状（2026-09-28）：本节描述的是 Tauri self_update 的资产匹配规则，已随 Tauri 退役。
当前运行时用 cargo-packager-updater，载荷从 latest.json 的平台键
（macos-aarch64 / macos-x86_64 / windows-x86_64）取出，不再按资产名匹配，所以
资产名里既不需要也不应该有 target triple。名称规则现在是：每个 target 一个架构标记
（Rust target architecture，即 aarch64 / x64），同一个 target 的磁盘镜像与归档共用它。
唯一定义在 ReleaseTarget::architecture。下面保留 self_update 的原始分析供考古。

self_update 的 Release::asset_for 先用完整 target triple匹配资产名，失败后退化为
arch + os 标记（arch = triple 首段，os ∈ darwin/windows/…）。注意
bin_name 不参与资产名匹配。

所以资产名必须包含完整 target triple，例如：

BongoCat-1.1.0-aarch64-apple-darwin.app.tar.gz
BongoCat-1.1.0-x86_64-apple-darwin.app.tar.gz
BongoCat_1.1.0_x64.exe                      ← 现有名字，不含 triple

⚠️ 最后一行是个真问题：现有 Windows 安装器名 BongoCat_<version>_x64.exe 里只有 x64，
退化匹配需要 arch + os 两个标记同时命中才算。这一点在换方案时必须实测确认，不能靠推断。

5.3 归档内布局要求 Copy Section

多套一层目录会直接报错（不会静默取错文件）。

现状（2026-09-14）：Windows 已不再是"单文件替换"模式。落地后 Windows 载荷就是那个 NSIS
安装器，由库的 UpdateFormat::Nsis 路径运行，因此 resources/ 会随安装器一起更新——
原先需要 MoveAll 自行编排的理由（单文件替换不更新 resources/）随 self_update 一并
退役。这一条是结构推论，未在 Windows 实机验证（本机是 macOS），见 ADR-0034 待验证项 2。

5.4 `.dmg` 与 `.sig` 的取舍（直接回答你的约束） Copy Section

你的约束是"若两平台均需 .sig，则仅额外增加该文件，不引入其他文件"。逐条对照：

方案 A（保持 zipsign）

结论：zipsign 满足 macOS 的零新增文件，但满足不了 Windows。

方案 B（改用 minisign，推荐）

结论：完全符合你的描述。 注意 cargo-packager 的 sign_outputs 会连 .dmg 也一起签名
（产出 .dmg.sig）；如果不想发布这个文件，就只对更新产物调 sign_file，或者把
PackageOutput 列表过滤后再交给 sign_outputs。

6. 落地步骤 Copy Chapter

6.1 方案 A：保持 zipsign（macOS 可用，Windows 阻塞） Copy Section

1. 生成并托管密钥
   sh Copy

   cargo install zipsign
   zipsign gen-key release.key release.pub && chmod 600 release.key
   base64 -i release.key | pbcopy        # 存进 GitHub Secret

2. 把公钥编译进去：release.pub 是 32 字节裸数据 → 填进
   runtime.rs 的 RELEASE_SIGNING_KEY。
3. 改 CI 的 macOS 归档步骤（.github/workflows/release.yml 的
   Package the bundle for publication）：现在用 ditto -c -k 产的是 .zip，改成产
   BongoCat-$version-${{ matrix.arch }}.app.tar.gz（归档根必须是 BongoCat.app/）。
4. 加签名步骤：在 upload 之前，解码私钥、zipsign sign tar <归档> release.key。
5. Windows：需要额外决策——要么接受新增一个载荷归档并实现 MoveAll 多文件编排，
   要么放弃 Windows 自更新。

6.2 方案 B：改用 minisign（推荐） Copy Section

生产端（crates/bongocat-packaging）

1. 复用已在依赖里的 cargo_packager::sign，不引入新工具。
2. 在 packaging_config 之后、verify_artifacts 之前插入签名步骤：
   • 从环境变量读私钥（照 BONGOCAT_MACOS_SIGNING_IDENTITY 的先例）；
   • 未设置则跳过签名，并让发布流水线能断言"发布构建必须签过名"；
   • 把 .app 打成 BongoCat-<ver>-<arch>.app.tar.gz（根目录 BongoCat.app/），
     把 Windows 安装器确认为 BongoCat_<ver>_x64.exe；
   • 对这两个文件调 sign_file，产出 .sig。
3. 更新 tools/tests/test_update_release_contract.py，把"资产名必须含完整 triple"这条
   编译期不可见的耦合固定下来。

消费端（crates/bongocat-update）

4. 新增依赖 minisign-verify = "=0.2.5"（MIT，零依赖，本机源码确认支持 prehashed 模式
   与 key ID 校验）。按 §9 的依赖纪律，先用 cargo info minisign-verify 核对最新稳定版。
5. 把 RELEASE_SIGNING_KEY 换成 minisign 公钥，并把
   builder.verifying_keys([key]) 换成 builder.verify_archive(|path| ...)：
   在闭包里读 .sig、调 PublicKey::verify，失败时返回
   self_update::Error::archive_verification_rejected(...)。
6. 保留 fail-closed 门禁：公钥未配置时，在发请求前就返回 update_signature_key_missing
   （等价于现在的 runtime.rs:202）。
7. 新增 ADR，取代 ADR-0029 的签名部分，并显式记录丢失的能力（§4.5 的降级防护）。

需要正视的两个未解决问题

• .sig 从哪来？ verify_archive 钩子只拿到下载文件的路径，而 .sig 是另一个 Release
  资产。self_update 只提供 checksum_from_asset()，没有 signature_from_asset()。
  可行做法是在闭包内自行请求一次 Release API 找到同名 .sig 资产并下载（self_update 已
  re-export ureq）。这带来额外一次网络请求和一段自研胶水，必须写进 ADR 的成本栏。
• Windows 的安装步骤要自研。 .exe 是系统安装器，self_update 明确不支持（§0.2）。
  需要自己实现「下载 → 验签 → 静默运行安装器 → 重启」，并处理安装器与正在运行的进程的冲突。
  自签名发布前还要确认 per-user NSIS 安装器的静默开关（cargo-packager 的 NSIS 模板是否
  支持 /S 需实测）。

6.3 对"我该先做什么"的建议顺序 Copy Section

1. 先不要动代码。 先写一个 ADR 决定签名方案（zipsign 内嵌 vs minisign 分离），因为这两条
   路对产物、依赖、Windows 安装语义的影响都是不可逆的。
2. 决定 Windows 的更新语义（自替换 vs 运行安装器）。这是真正的分水岭，比签名算法重要得多。
3. 再改打包工具产归档 + 签名，最后才是客户端验签。

该顺序已被遵循：决策记录在 ADR-0034，随后才动代码。§6.2 的"消费端"步骤 4–5 在执行时被
简化——self_update 的 verify_archive 钩子方案没有采用，因为整条链路换成了
cargo-packager-updater，它自己取 manifest 里的 .sig，不需要在钩子里再请求一次 Release
API。§6.2 列出的两个"未解决问题"因此都不成立：.sig 由 manifest 携带，Windows 安装步骤由
库提供。

§6.2 的生产端步骤 1–3 与"签名必须是最后一步"的约束按原样执行，落在
crates/bongocat-packaging 的 publish_update_assets。

7. 注意事项清单 Copy Chapter

下列清单是决策前的检查表。落地后各项的归属见括号内的说明；打勾表示已由代码或契约
强制，而不是靠人记住。

• 私钥不进仓库、不进构建产物、不进日志；只从 CI secret 注入（.env 不生效）
  （SIGNING_PRIVATE_KEY 环境变量注入，代码里没有任何密钥字面量）
• 生成后 chmod 600 私钥文件（just keygen 已显式收紧到 0600；实测确认）
• 公钥编译期内嵌，绝不从网络取（RELEASE_SIGNING_KEY 常量）
• 公钥未配置时在发请求前就失败（updater() 的门禁，有定向测试锁定）
• 本地构建默认跳过签名，发布构建断言签过名
  （release workflow 的 "Require the update signing key" 与 "Verify the signed update assets"）
• 签名是所有步骤的最后一步；签名后不改名、不重新压缩、不 strip
  （publish_update_assets 在产物确定后才签名，manifest 的 URL 在签名之后写入）
• macOS 的 .app 必须在打 tar.gz 之前完成 codesign + notarize（公证仍是独立门禁）
• 更新载荷名不必再含完整 target triple：载荷位置由共享 manifest 的 platforms 条目
  给出，不再按资产名匹配（这正是 asset_for 退役后的变化）
• macOS 归档根必须是 BongoCat.app/（write_bundle_archive 回归 + release workflow 断言）
• .dmg 不作为更新产物（update_payload 只取 bundle 或 .exe）
• Windows 的 resources/ 随安装器一起更新（结构推论，未在 Windows 实机验证）
• .sig 只在方案 B 存在；方案 B 已采纳，两平台各一个 .sig
• 更新签名 ≠ Authenticode / 公证，两件事都要做（Authenticode 仍只打 warning）
• 一把钥匙泄露 = 换钥匙 = 必须先发"双钥匙版本"；务必备份私钥
  （单公钥模型下这条约束更硬，见 ADR-0034 待验证项 4）
• ADR-0029 已丢失的降级防护（release_sequence）值得在换实现时补回（本次未补）
• 任何签名/安装路径的改动都要同步更新 ADR、契约测试和诊断错误码

8. 未验证事项（按 `AGENTS.md` §3.4 诚实标注） Copy Chapter

下列条目是本文写作时（决策前）的状态。落地后其中一部分已由
crates/bongocat-update/tests/release_manifest_capability.rs 覆盖，逐条标注如下；
仍未验证的事项以 ADR-0034 的"待验证项"为准。

1. 没有生成过任何密钥 → 已覆盖：能力测试调用 cargo_packager::sign::generate_key 生成
   真实密钥对并落盘；just keygen 也已用于生成并验证发布私钥/公钥。发布私钥的 GitHub secrets
   托管与真实发布链路仍未验证。
2. 没有跑通一次"签名 → 客户端验签" → 部分覆盖：签名与验签都在 loopback 上真实执行过
   （真实密钥、真实 .sig、真实 PublicKey::verify），但真实 GitHub 发布链路仍未跑通。
3. minisign-verify 0.2.5 与 minisign 0.7.9 的互操作性未实测 → 已覆盖：两者由能力测试
   交叉验证通过，cargo-packager 的 prehashed 输出可被 cargo-packager-updater 验签。
4. GitHub 上的资产名退化匹配未实测 → 已失效：换库后不再按资产名匹配，载荷位置来自
   manifest。新风险是 manifest 本身没有防降级保护（见 ADR-0034 待验证项 5）。
5. Windows 静默安装：install_mode = Quiet 映射到 NSIS /S /R 已由源码确认
   （WindowsUpdateInstallMode::nsis_args），但能否在被占用的可执行文件上完成替换仍未验证
   ——本机是 macOS。
6. .dmg 是否被 sign_outputs 一并签名 → 已失效：本项目不调用 sign_outputs，只对
   更新载荷调 sign_file，因此不会产出 .dmg.sig。
7. cargo-packager 的 signer generate-key CLI 子命令的确切参数名未核实 → 已核实：
   cargo packager signer generate-key [--path ] [--password ] [--force] [--ci]
   （src/cli/signer/mod.rs 的 Commands::Generate，参数定义在 generate.rs）。
   产出的 .key / .key.pub 是 base64 文本，可直接整段放进 CI secret。

Adr 0001 Single Rust Application (`docs/adr/0001-single-rust-application.md`) Copy Section

ADR-0001: Single Rust Application

状态：Accepted
日期：2026-08-28

Context Copy Chapter

BongoCat 需要在 Windows 和 macOS 上统一实现设置 UI、实时输入、动画、模型管理、窗口、渲染和系统集成，同时保持平台 API 的直接控制能力。

Decision Copy Chapter

BongoCat 自有应用代码统一使用 Rust 2024 edition，并在一个 Cargo workspace 中组织。业务模块通过强类型 Rust 接口协作；平台差异进入明确的 platform adapter。

官方 Cubism Core 平台二进制是唯一允许的厂商 FFI 例外。该例外只提供模型计算能力，不承载 BongoCat 业务逻辑。

Consequences Copy Chapter

• 状态、配置、模型和行为只实现一次。
• Windows/macOS 的窗口、输入和 GPU backend 仍分别实现。
• 平台 handle、裸指针和 unsafe 不能进入共享业务模块。
• Linux 可在首发后通过新增 platform/renderer backend 评估。

Verification Copy Chapter

Phase 0 必须证明 GPUI、独立 overlay、输入服务和 Cubism wrapper 可以在同一应用生命周期内可靠启动和停止。

Adr 0002 Gpui Settings Ui (`docs/adr/0002-gpui-settings-ui.md`) Copy Section

ADR-0002: GPUI for Settings UI

状态：Accepted, pending Phase 0 validation
日期：2026-08-28

Context Copy Chapter

BongoCat 需要一套跨 Windows/macOS、可主题化、支持复杂表单和模型管理的 Rust 设置界面。设置 UI 不是实时 Live2D 渲染表面。

Decision Copy Chapter

使用 GPUI 构建设置、模型管理、快捷键、权限、更新和诊断界面。首个 spike 固定 gpui = "=0.2.2" 并提交 Cargo.lock。

GPUI Entity 只拥有临时视图状态。运行时配置和业务状态通过强类型 command/snapshot 边界访问。

Consequences Copy Chapter

• 项目维护一套设置 UI 和 design system。
• 不依赖 Zed 应用内部 UI crate 或 GPUI renderer 私有接口。
• GPUI 升级必须独立验证，不能无约束跟随上游。
• GPUI 设置窗口关闭后，输入、动画和 overlay 必须继续运行；设置和更新窗口的普通 close 都销毁
  当前 GPUI 窗口，下一次打开重新创建。
• 设置窗口的侧边栏当前页面由 app coordinator 持有 process-local SettingsNavigationMemory 记忆，
  窗口重建时恢复；该 UI 状态不写入配置，应用重启后回到 Appearance。
• GPUI 0.2.2 的 Windows WM_DESTROY 回调会同步重入已借用的 AsyncApp；显式 Quit 必须先完成
  全部 BongoCat owner 的 shutdown/join，再由平台适配器跳过有缺陷的最终 GPUI 析构。普通设置/更新
  窗口销毁仍须通过双平台原生 smoke 验证，不得用进程退出代替或提前截断业务 shutdown。

Verification Copy Chapter

Phase 0 验证双平台字体、中文输入法、焦点、键盘导航、辅助功能、DPI/Retina、窗口销毁/重建、侧边栏页面记忆、后台生命周期和 shutdown。

历史证据（2026-08-31）：Windows CI run 33328391234、job 99302481796 证明保留窗口后的真实
WM_DESTROY 仍以 0xC0000409 fast-fail；同期检查确认 Zed commit
399258feeaf90ad8a3a208c99221ee87b6452f38 的 main close callback 仍执行同步
handle.update。该证据限定上述兼容措施，并不解除未来恢复正常 GPUI 析构的门禁。

Adr 0003 Native Overlay Renderers (`docs/adr/0003-native-overlay-renderers.md`) Copy Section

ADR-0003: Native Overlay Renderers

状态：Accepted, macOS validated; Windows pending Phase 0 validation
日期：2026-08-28

Context Copy Chapter

模型窗口需要透明、置顶、穿透、低延迟、高 DPI/Retina 和可控 GPU 生命周期。GPUI 没有为双平台 Live2D 外部纹理提供稳定的公共合成接口。

Decision Copy Chapter

模型窗口使用独立原生 overlay：

• Windows：Win32 + D3D11 + DXGI + DirectComposition/DWM。
• macOS：AppKit NSPanel + Metal + CAMetalLayer。

Renderer 只消费不可变 RenderSnapshot，不访问 GPUI、配置或输入服务。

Consequences Copy Chapter

• 设置 UI 与实时渲染拥有独立的窗口和 frame loop。
• 两个平台分别实现 GPU backend，但共享模型求值和 render contract。
• 首发不为了后续 Linux 强行统一 GPU API。
• 窗口、renderer 和 GPU object 必须有明确的 owner 与析构顺序。

Verification Copy Chapter

macOS spike 已验证 NSPanel + CAMetalLayer 的透明 clear/present、独立于 GPUI renderer 的窗口生命周期，以及设置窗口与 overlay 同时存在时的显示/隐藏/退出流程。

Windows Win32 + D3D11 尚未在 Windows 实机验证；macOS 结果不能替代 Windows 结论。双平台模型绘制、真实 frame source、device lost/swapchain recovery 和 100 次真实窗口创建/销毁仍是 Phase 0 未完成项。

Adr 0004 Reconcilable Input State (`docs/adr/0004-reconcilable-input-state.md`) Copy Section

ADR-0004: Reconcilable Input State

状态：Accepted, pending platform validation
日期：2026-08-28

Context Copy Chapter

系统快捷键、锁屏、安全桌面、权限变化或输入队列异常可能导致应用收到按下边沿却收不到释放边沿。只依赖事件配对会产生永久 pressed state。

Decision Copy Chapter

输入状态由三类信号共同维护：

1. 低延迟的按下/释放事件。
2. 对当前 pressed set 的系统状态校正。
3. 锁屏、睡眠、设备移除和服务重启等生命周期 Reset。

Key/button edge 使用可靠有序队列。鼠标移动和手柄轴使用 latest-value 合并，不得阻塞释放边沿。

Windows 以 Raw Input 为主路径，并用 GetAsyncKeyState 校正。macOS 使用 CGEventTap，并用 CGEventSourceKeyState 校正。

平台 adapter 统一使用单调时钟调度校正：默认间隔为 250 ms，同一个本地 pressed key 必须连续 2 次系统快照缺失才生成释放。单次查询异常只增加该 key 的待确认次数；后续快照确认仍按下时清零待确认次数。正常 KeyUp 和生命周期 Reset 立即清理待确认状态，Reset 不等待确认阈值；时钟回退不得推进校正调度游标。该策略由平台无关状态 contract 固定，平台只负责提供候选 pressed-set。

经过的时间不是第四条路径。早期的 input.keyboard.release_fallback_timeout_ms 按键释放超时已被移除：
用户仍按住的按键与丢失的松开事件在时长上无法区分，用时长区分等于把一帧变慢翻译成一个猫不再
相信的按键。捕获键盘按键因此没有超时配置，runtime 也不维护按键期限或与之相关的匿名计数。

唯一例外是 macOS 的 CapsLock。该键是锁存键，平台实测只投递「锁存翻转」事件而完全不投递物理松开
（见 Technical Design 的 FlagsChanged 条目），它的物理释放在平台层不存在，因此没有「用户仍按着」
这一状态需要区分。平台按产品既定的「短暂触发」语义在固定 100 ms 后合成释放边沿。该时长是按键
行为本身，不是超时配置、不进 schema、不暴露设置项，也不得推广到任何其它键。

Consequences Copy Chapter

• 单个释放事件丢失不会永久卡键。
• 队列溢出必须可观测，不能静默丢弃边沿。
• 丢失 KeyUp 的按键只能由状态校正或生命周期 Reset 释放；校正延迟上限由平台查询周期和确认
  次数共同决定，实机应分别测量权限、锁屏和睡眠恢复下的延迟。
• macOS CapsLock 的释放由 adapter 合成，CGEventSourceKeyState 反映锁存状态、无法替代它；该
  合成边沿走 InputSource::Capture 通道，runtime 侧因此把它计入 captured_up。这是已知且接受的
  精度损失，平台侧计数器不声称该边沿来自系统。
• Renderer 不直接查询系统键盘状态。

Verification Copy Chapter

Windows 强制覆盖 PixPin Ctrl+Alt+A、Win+L、PrintScreen 和 UAC 返回。双平台覆盖锁屏、睡眠、设备变化、服务 restart 和输入压力测试。

Adr 0005 Cubism Core Ffi Boundary (`docs/adr/0005-cubism-core-ffi-boundary.md`) Copy Section

ADR-0005: Cubism Core FFI Boundary

状态：Accepted, pending SDK and license validation
日期：2026-08-28

Context Copy Chapter

BongoCat 需要加载既有 .moc3 模型。官方 Cubism Core 以平台二进制形式提供，应用必须控制其版本、所有权、分发和错误边界。

Decision Copy Chapter

通过窄 Rust sys layer 调用官方 Cubism Core，并在其上建立 safe Rust wrapper：

Cubism Core binary -> raw bindings -> Moc/Model wrappers -> model evaluation

原始指针不得离开 wrapper。Rust owner 必须保证 Moc、Model 和 backing buffer 的存活与析构顺序。BongoCat 的动作、表达式、物理、资源和状态逻辑保留在 Rust 模块中。

Consequences Copy Chapter

• 构建清单必须记录 SDK/Core 版本、来源、hash、架构和许可证。
• FFI callback 不执行阻塞工作，不允许 panic 穿越边界。
• 模型切换采用 prepare/validate/commit，失败保留当前模型。
• 不通过扩大非 Rust bridge 来绕过兼容性问题。

Verification Copy Chapter

Phase 0 使用三个预置模型验证 moc/model 生命周期、drawable 数据、motion、expression、physics/pose 需求和重复销毁，并形成 SDK 分发结论。

Adr 0006 Linux Post Launch Strategy (`docs/adr/0006-linux-post-launch-strategy.md`) Copy Section

ADR-0006: Linux Is a Post-Launch Evaluation

状态：Accepted
日期：2026-08-28

Context Copy Chapter

BongoCat 的首发目标是 Windows 和 macOS。Linux 的透明窗口、窗口层级、全局输入、托盘和桌面集成能力会随 X11、Wayland、portal 与 compositor 改变，不能从 Windows/macOS backend 的结果推断等价支持。

同时，runtime、配置、模型、动画和行为 fixture 本身不需要依赖具体桌面系统。首发实现不应为了未验证的 Linux 能力统一平台 backend，也不应让共享业务类型依赖 Win32、AppKit 或 GPU handle。

Decision Copy Chapter

Linux 不进入首发支持矩阵，不阻塞 Windows/macOS 的 Phase 0、实现和发布。

共享 Rust crate 保持平台无关：业务接口使用项目自有类型，平台能力通过 adapter 和 capability reporting 提供。Windows 使用 D3D11，macOS 使用 Metal；首发不为了 Linux 预先引入统一窗口、输入或 GPU abstraction。

Linux 只在首发后按独立 spike 评估。评估必须分别覆盖 X11 与 Wayland，并允许结论是某些桌面环境、compositor 或全局输入能力不受支持。尤其不得承诺 Wayland 下存在与 Windows Raw Input 或 macOS CGEventTap 等价的全局键鼠捕获。

Consequences Copy Chapter

• 首发 CI 可以对平台无关 crate 执行 Linux cargo check，但该结果不代表 Linux 产品支持。
• 新增共享业务 API 时不得暴露 HWND、Objective-C 对象、X11 handle、Wayland object 或 backend 专用 GPU 类型。
• Linux backend 可以在首发后新增，不要求修改已冻结的输入、配置和模型语义。
• 若 Linux 平台能力不足，产品必须显式降级或限制支持范围，不能用静默丢失输入代替能力声明。

Verification Copy Chapter

Phase 1 CI 对共享 crate 执行 Linux compile check。首发后按照 TODO 的 Linux backlog 建立 X11/Wayland 能力矩阵，并在全局输入、透明 overlay、渲染和系统集成均达到门槛后，另行提交支持决策 ADR。

Adr 0007 Single Rust Runtime Environment (`docs/adr/0007-single-rust-runtime-environment.md`) Copy Section

ADR-0007: Single Rust Runtime Environment

状态：Accepted
日期：2026-08-28

Context Copy Chapter

BongoCat 的输入、pressed state、动画、当前模型和配置协调需要单一事实来源。如果生产应用同时保留多个业务 runtime，或通过 IPC 在 UI、输入和模型状态之间复制事实，会扩大时序、恢复、版本兼容和 shutdown 风险。

历史实现仍用于行为观察和模型资源兼容证据，但不应进入 BongoCat 的生产执行链路。旧配置只作为已归档考古样本，不属于产品输入。

Decision Copy Chapter

生产应用使用一个 Rust 进程和一个业务 runtime owner。GPUI 设置界面、平台输入服务、Live2D 求值、原生 overlay 和系统集成都属于同一 Rust 应用生命周期，并通过强类型 Rust command、event 和 snapshot 协作。

不得引入第二套常驻业务运行环境、跨语言共享业务 core、sidecar 业务进程或用于同步核心状态的 IPC 边界。历史应用只作为行为与资源对照，不随 BongoCat 生产应用启动，也不作为功能 fallback。

官方 Cubism Core 平台二进制仍是 ADR-0005 定义的窄 FFI 例外。它只提供模型计算能力，不成为独立业务 runtime，不拥有应用状态。

安装或更新若因操作系统权限必须使用短生命周期 helper，需要在系统集成阶段单独威胁建模和 ADR；helper 必须使用 Rust、不得持有持续业务状态，也不得改变本 ADR 的单一应用 runtime 所有权。

Consequences Copy Chapter

• pressed state、动画、当前模型和配置协调只存在一个可变 owner。
• GPUI 关闭或重建不会创建第二份业务状态；UI 只发送 command 并读取带 revision 的 snapshot。
• 输入 callback、renderer 和平台服务不能绕过 runtime 直接维护产品状态。
• 发布切换前保留历史源码、tag 和样本；生产包不包含历史 runtime、Web 资产或旧配置读取器。

Verification Copy Chapter

Phase 0 验证 GPUI、输入服务、runtime、Cubism wrapper 和独立 overlay 可以在同一进程中按既定顺序启动、停止和重建。Phase 1 对 release dependency tree 与产物内容执行检查，确认不存在第二套业务 runtime、WebView 或 JavaScript runtime。

Adr 0008 Application Identity And Storage Environments (`docs/adr/0008-application-identity-and-storage-environments.md`) Copy Section

ADR-0008: Application Identity and Isolated Storage Environments

状态：Accepted
日期：2026-08-28

Context Copy Chapter

BongoCat 需要稳定的应用身份，同时开发构建不能读取、覆盖或锁住用户的生产数据。旧版配置字段和存储布局不再是新应用的兼容目标，因此新配置可以直接采用清晰、一致的 Rust 领域命名。

仅依赖 debug_assertions 或可变命令行参数选择数据目录会让错误构建访问生产数据。只隔离 config.json 也不充分：模型、备份、日志、锁和其他可变文件仍可能互相污染。

Decision Copy Chapter

BongoCat 的 Bundle ID 固定为：

com.ayangweb.bongo-cat

构建产物携带不可变的 BuildEnvironment：

Development
Production

工作区内直接执行的 Cargo 命令默认选择 Development；Production build/package 必须显式启用
bongocat-app/production Cargo feature。环境选择不依赖进程环境变量；应用启动后不能通过 CLI、
环境变量或设置项切换环境。packaging 的 --environment 只作为产品 CLI 校验并映射为上述 feature。
正式启动 API 只从当前平台与该编译期环境解析数据根，不接受调用方传入 StorageLayout 或路径。
需要隔离临时根目录的进程级测试必须显式启用 storage-test-injection，该能力不进入默认产品
CLI/API，并且 Production 构建与该 feature 的组合在编译期失败。

持久数据根目录为：

两个环境使用相同的目录结构和 schema：

<data-root>/
  config.json
  window-state.json
  models/
  backups/
  logs/
  updates/
  locks/

锁、单实例命名、诊断和更新 channel 也必须包含环境身份。任何环境都不得探测、读取或回退到另一个环境的目录。

BongoCat 不读取或导入旧 Tauri/Pinia 配置。配置 JSON 键统一使用 snake_case，名称从当前产品领域语义定义，不保留旧字段 alias。

初始版本是全新的，当前完整 config.json 与 window-state.json 都以 schema_version: 1
开始。在首次正式发布前，新增字段直接修改当前 v1，不保留开发中间结构，也不实现迁移、
旧数据转换或历史版本兼容判断。解析边界保留版本字段并拒绝非 v1 数据，避免静默改写未知格式。
首次正式发布后，后续版本才以实际发布的 v1 为基线单独设计顺序、幂等迁移。

window-state.json 的领域名称明确限定其只承载 settings 与 overlay 的可恢复窗口状态，不能作为
通用 application state 容器。开发期旧路径不属于首版兼容输入；产品不读取、迁移或 fallback 到它。

Alternatives Considered Copy Chapter

• Cargo profiles and debug_assertions were rejected: both describe the Cargo profile, not the immutable product environment. A release Development smoke and a release Production package must remain distinguishable.
• Build-metadata crates such as vergen, shadow-rs, and built were rejected: they expose Git, Cargo, Rust, and system metadata, but they do not own or enforce BongoCat's mutually exclusive Development/Production data-root semantics. Adopting one would retain the current custom mapping and validation while adding a dependency and lockfile surface.
• cfg_aliases was rejected because it only aliases conditions; the project can express the two states directly with one Cargo feature and cfg.
• A build script that reads an environment variable was rejected in favor of Cargo's native feature resolution. Cargo now owns the selection path and feature propagation; the remaining explicit compile_error! represents the required product invariant that Production cannot include storage test injection.

Consequences Copy Chapter

• 首次启动 BongoCat 时生成当前环境的全新配置。
• 开发构建可安全使用合成数据和自定义模型，不影响生产安装。
• 旧配置目录和字段只保留为历史行为参考，不进入生产 dependency graph 或发布产物。
• 用户模型仍可通过受验证的显式导入流程加入；不会根据旧配置路径自动发现或搬运。
• 工作区直接 Cargo 命令默认 Development；Production build/package 必须显式启用
  bongocat-app/production。
• Production 构建不能携带存储根注入能力；需要隔离临时数据根的进程级测试必须使用独立 Development 测试产物并显式启用 storage-test-injection。
• 开发过程中产生的旧 schema 或中间数据需要删除并重新生成，不属于产品兼容输入。

Verification Copy Chapter

• 对 Windows/macOS path resolver 分别测试 Development 和 Production，断言根目录不同且内部相对结构一致。
• 工作区直接 cargo check 成功并编译为 Development；启用 production feature 后编译为
  Production，且 Production 与 storage-test-injection 的组合必须失败。
• 默认产品参数拒绝存储测试入口；CI 证明 Production + storage-test-injection 构建失败。
• 在两个环境写入不同 sentinel，重启后只读取各自数据。
• 验证锁、日志、备份、模型目录和更新 channel 均无跨环境访问。
• 发布产物验证 Bundle ID 精确等于 com.ayangweb.bongo-cat。
• 扫描发布依赖和运行日志，确认没有旧 Tauri/Pinia 配置探测。
• 扫描产品代码，确认不存在 schema migration、字段 alias 或旧结构转换路径。

Adr 0009 Gpui Accessibility Gate (`docs/adr/0009-gpui-accessibility-gate.md`) Copy Section

ADR-0009: GPUI Accessibility Gate

状态：Proposed；历史 release/UI-completion gate，项目自有 AccessKit 部分由 ADR-0054 取代
日期：2026-08-28

后续修订（2026-09-23）：ADR-0054 将设置 UI 收口为 visual-first。项目自有 AccessKit tree/native bridge/action 不再是 UI 完成或发布门槛；gpui-kit 传递语义可保留，但不是 BongoCat 语义契约。

Context Copy Chapter

设置 UI 必须向 macOS 辅助功能 API 暴露可识别的 label、value、role、错误和进度。spikes/gpui-settings/ 在 macOS 26.5.2 上的人工 smoke 能识别应用、标准窗口、标题栏按钮和菜单，但不能识别 GPUI 绘制的 Appearance、Theme、模型名称输入框或 Refresh 控件。可见截图不能替代辅助功能树证据。

GPUI 0.2.2 的公开源码和 feature 列表没有为普通 element 提供 role/label/value 的通用 accessibility API。直接依赖私有 Zed UI crate、修改 GPUI 私有 renderer 或以隐藏原生控件伪造整棵表单，都会破坏已冻结的依赖和 UI 边界。

Decision Copy Chapter

GPUI 继续作为当前首选设置 UI，但在辅助功能 gate 通过前保持 provisional：

• 允许建立正式 UI crate 和最小产品窗口，但在门禁通过前不实现或宣称完整、可发布的设置界面；
• 不引入 GPUI 私有 API、未维护 fork 或隐藏控件 workaround；
• 使用 GPUI 公开的 raw window handle 安装项目自有 AccessKit semantic tree；macOS/Windows adapter 只负责系统协议，语义 snapshot 由 UI crate 维护；
• 辅助技术 action 必须通过有界强类型 channel 回到 GPUI 主线程，不允许平台 callback 直接修改 Entity 或 runtime；
• 可见控件和语义节点使用同一份 UI 状态，必须覆盖 role、label/title、value、focus、selected、loading/error 和支持的 action；
• 若 GPUI 仍无法提供基础语义，才启动 Iced 替代 spike。Iced 只作为此门槛的 fallback，不与 GPUI 并行进入产品。

截至本 ADR 日期，Iced 0.14.0 的公开 crate feature/source 中也未发现可直接满足 role/label/value 的通用 accessibility API，因此它是待验证候选，不是当前 go 结论。不能因为换 UI 框架名称就视为问题已解决。

Gate Copy Chapter

以下条件是 ADR-0054 前的历史验收定义。满足后才能将本 ADR 标记 Accepted；“项目自有 AccessKit tree”的当前完成与发布门槛已由 ADR-0054 退役。当时要求：

1. 选定版本的公开 API 能为设置表单提供稳定 role、label、value、错误和进度节点；
2. macOS AX tree 能读取主题选择、模型名称输入框、Refresh、错误和 loading 状态；
3. Windows UI Automation 能读取同等语义；
4. 键盘导航、真实 IME、剪贴板、缩放和窗口重建回归仍通过；
5. 方案不依赖私有 crate、未审阅 patch 或平台特定的业务状态副本。

若以上历史条件在完整设置 UI 实现前仍不满足，形成明确的 NO-GO 或 GO WITH CONDITIONS 决策，并为 Iced 或其他后续方案指定独立 owner、截止阶段和回退条件。ADR-0011 允许其他正式产品模块继续开发。ADR-0054 后，项目自有 AX tree 的部分不再阻塞当前 visual-first UI。

Evidence Copy Chapter

• GPUI 版本固定为 crates.io 0.2.2，见 spikes/gpui-settings/Cargo.toml；
• macOS 本机通过 AppKit AX API 读取 8 个项目语义节点，并通过 accessibilityPerformPress 将 Dark radio action 送回 GPUI；
• commit fd9ad85 的 push run 33255204781、job 99107586036 使用进程外 UI Automation client 读取同等节点，并通过 SelectionItem.Select 验证 Dark radio 的 selected/action 闭环；
• 2026-08-30 的 macOS .app smoke 读取 Reset 的 help text，并验证打开确认框后只暴露 modal AlertDialog 子树、初始 Cancel 焦点、键盘关闭与语义树恢复；commit 45b8dba 的 push run 33273470907、job 99156013603 通过同一实现的 Windows UI Automation dialog 门禁；
• macOS .app 的延迟 runtime probe 已通过 AX value/invalid 状态观察到 Runtime Ready · revision 1 -> runtime probe failed -> Runtime Ready · revision 2；commit 21ee8aa 的 push run 33291750411、job 99204478369 与 pull request run 33291751558、job 99204481348 已从 Windows UI Automation 依次读取 loading、注入错误、retry 和 revision 2 恢复。runner 托管 UIA client 不提供 AriaPropertiesProperty 标识，因此仍无法据此验证 AccessKit 的 busy=true 投影；VoiceOver/Narrator 操作和宣读仍未验证；
• 双平台设置 spike 通过原生合成 mouse-move 进入 GPUI 平台事件链，验证 Reset hitbox、500ms tooltip delay/build 和 hover exit；物理 pointer 与 VoiceOver/Narrator tooltip 朗读仍未验证；
• Iced 候选版本与 feature 清单通过 cargo info [email protected] --verbose 获取，源码检索未发现通用 accessibility surface。

Adr 0010 Windows Cpu Targets (`docs/adr/0010-windows-cpu-targets.md`) Copy Section

ADR-0010: Windows CPU Targets

状态：已被 ADR-0033 取代（2026-09-14，Windows ARM64 不再是产品目标，只剩 x64）

Context Copy Chapter

BongoCat 需要明确 Windows 发布架构，避免继续为不再支持的 target
维护输入、renderer、安装和更新分支。当前固定的 Cubism 5 SDK for Native R5
提供 desktop Windows x86/x64 Core，但没有 desktop Windows ARM64 Core；其
experimental UWP ARM64 DLL 不能用于 Win32 desktop 应用。

Decision Copy Chapter

Windows 产品目标只包括：

• x86_64-pc-windows-msvc。

i686-pc-windows-msvc 和 aarch64-pc-windows-msvc 都不属于 BongoCat
的构建、CI、安装包、更新或测试目标。历史 x86 安装包只作为行为与发布考古证据
保留，不形成兼容承诺。

Windows ARM64 曾作为产品目标保留；ADR-0033 已取消该目标。原因不是"R5 缺少
Core"这一次要阻碍，而是它使产品矩阵多出一个无法端到端验证的原生构建：
没有官方可授权的 desktop ARM64 Core，就没有真实的 ABI、模型和 renderer 证据链。
Windows 自身提供 x64 仿真，Windows on ARM 设备运行 x64 构建在正常情况下可用，
因此维持一个不可验证的原生 ARM64 目标只增加成本、CI 面积和发布风险。

Consequences Copy Chapter

• 新的 target matrix、binding fixture 和发布配置不得加入 i686-pc-windows-msvc
  或 aarch64-pc-windows-msvc。
• deny.toml 的 [graph].targets、bongocat-update::UpdateTargetTriple 与
  发布流水线必须只包含 x86_64-pc-windows-msvc；契约测试强制三者一致。
• Windows 平台依赖与 renderer 只在 x64 上验证。ARM64 上的实际体验通过 Windows
  的 x64 仿真覆盖，不再有独立的原生 ARM64 证据要求。

Verification Copy Chapter

• tools/inspect-cubism-sdk.py 把 Windows ARM64 报告为 unsupported_by_r5，
  把 i686 报告为 excluded_by_product。
• tools/cubism-bindgen 只为当前 R5 可用且仍在产品矩阵内的 Windows x64 和
  macOS targets 生成合成 bindings；它拒绝 Windows ARM64 和 i686。
• Phase 0 CI 不安装或编译 i686，也不再安装或编译 Windows ARM64。
• tools/tests/test_packaging_contract.py 断言打包工具的 target 集合、
  deny.toml 与 UpdateTargetTriple 三者一致且不含 ARM64。

Adr 0011 Progressive Implementation Release Gates (`docs/adr/0011-progressive-implementation-release-gates.md`) Copy Section

ADR-0011: Progressive Implementation With Release Gates

状态：Accepted
日期：2026-08-30

后续修订（2026-09-23）：ADR-0033 已退役 Windows 原生 ARM64，Windows on ARM 改由 x64 仿真覆盖；因此本文的 Windows ARM64 desktop Core 发布门槛只作历史记录。

Context Copy Chapter

Phase 0 已通过独立 spike 验证 runtime、配置隔离、GPUI 设置窗口、原生 overlay
和可校正输入的核心所有权模型。剩余证据主要依赖厂商授权、标准 Cubism SDK、
物理设备、辅助技术、目标系统和签名环境。把这些外部证据全部作为创建产品
workspace 的前置条件，会阻止已经具备自动化契约的业务模块进入正式实现。

维护者已提供仓库外的 CubismSdkForNative-5-r.5.zip，并明确授权本地技术
验证和正式产品代码开发；公开发布授权和实机验收延后到产品完成后处理。

Decision Copy Chapter

项目采用渐进式实现，并把开发门禁与发布门禁分离：

• 允许建立正式 Rust workspace，并逐步实现 runtime、配置、模型、UI、平台和
  renderer；每项仍必须满足自己的自动化测试和代码边界。
• Phase 0 未完成项继续保持未勾选。缺失的 Cubism 行为、物理设备、辅助功能、
  GPU、签名和目标系统证据不能由编译或合成测试替代。
• Cubism 发布授权、最终 SDK/二进制清单、Windows ARM64 desktop Core、实机矩阵、
  签名、notarization、更新回滚和 soak 结果全部是 stable 发布门禁，不再阻止
  不公开分发的本地开发。
• 维护者批准把功能开发所需的最小 Core、header、生成 bindings 和预置模型固定到
  vendor/ 与 resources/，使本地开发和目标 ABI 检查可复现。完整
  SDK ZIP 与 Framework 源码不进入仓库；公开安装包仍在发布阶段核对 attribution、
  再分发范围和最终合规清单。
• 产品构建默认不联网，也不从未固定来源下载 SDK。缺少本地 SDK 时，与 Cubism
  无关的 workspace、测试和 CI 必须保持可用。
• 完整设置 UI 仍受 ADR-0009 的辅助功能条件约束；允许建立 UI crate 和最小产品
  窗口，但不得把未通过的交互或辅助功能宣称为可发布功能。

Supplied SDK Disposition Copy Chapter

当前本地基线是 Cubism SDK for Native 5-r.5，archive SHA-256 为
7ff3a4bbc19c0a8728965aa522ab77eb11b252916453e68a8a78d3b71188bb12，Core
版本为 06.00.0001。它包含 Windows x64 和 macOS arm64/x64 Core，不包含
desktop Windows ARM64 Core。

此前提供的 CubismSdkMotionSyncPluginForNative-5-r.2.1.zip 是可选 MotionSync
插件，SHA-256 为
26baaf30b0ebb26bc6253884aa61b010666e2ecc2491e3a7fff6d43eb64d6548。它不是
标准 Native SDK，不能加载 .moc3，当前不进入产品范围。

Consequences Copy Chapter

正式实现可以从已验证的 runtime/config 契约开始，不再等待外部测试人员或合规
流程。发布状态必须单独判断；“功能已实现”不表示“可以公开分发”。如果后续发布
核对、SDK ABI 或实机验证失败，受影响的发布目标保持阻塞，并通过后续 ADR 调整
能力或目标矩阵，不能用错误架构的 artifact 或模拟结果绕过。

Adr 0012 Json Localization (`docs/adr/0012-json-localization.md`) Copy Section

ADR-0012: JSON Localization

状态：已接受（2026-09-10；2026-10-06 修订）

决策 Copy Chapter

BongoCat 使用 rust-i18n = 4.2.4 加载编译期嵌入的 JSON 语言资源。应用层资源由独立的 bongocat-i18n crate 管理，默认语言为 en-US，已落地的语言为 zh-CN、zh-TW、ar-SA、vi-VN、pt-BR、ko-KR 与 fr-FR。

语言命名采用带地区子标签的提名式，与 en-US 一致：一份语言只发一份 catalog，地区子标签提名这份文案所依据的主要变体，并不声称 catalog 未携带的地区特化。en-US 本身也是这种名字——它同样服务 en-GB。

解析走 RFC 4647 的 language-subtag fallback（浏览器 Intl、CLDR 与操作系统自身的做法）：
按 primary subtag 匹配已发布 catalog，ar/ar-EG/ar_MA/ar-SA 全部落到 ar-SA，vi 与
vi-VN 全部落到 vi-VN，pt/pt-PT/pt-BR 全部落到 pt-BR，ko 与 ko-KR 全部落到 ko-KR，
fr/fr-CA/fr-BE/fr-CH 全部落到 fr-FR，en/en-GB 全部落到 en-US。
因此机器实际上报的 tag 几乎总不是 catalog 自身的名字，而 primary subtag 匹配让它们收敛到同一份
文案，而不是各自回退英文。pt-BR 尤其说明这件事的必要性：葡萄牙语没有单一写法，catalog 只发
一种变体，报 pt-PT 的机器读到的也是它。

语言枚举的变体名按语言本身命名，不带地区：Arabic、Vietnamese、Portuguese、Korean、
French 各自服务整个语言，地区子标签只是提名，PortugueseBrazil 这类名字会声称 catalog 并不携带的地区特化。
语言下拉里的名称按 endonym 规则写成本地人自称语言的名字，同样不附地区后缀——Português 而不是
Português (Brasil)，العربية 而不是 العربية (السعودية)，한국어 而不是 한국어(대한민국)，
Français 而不是 Français (France)，对应的 i18n key 也只写 portuguese、arabic、korean、
french。ChineseSimplified 是唯一保留限定词的名字，
因为它命中的确实是脚本分叉：zh 下的简繁是两种书写体系。

zh 是唯一不能只看 primary subtag 的情形：简繁是不同书写体系而非地区变体，因此两种写法各发
一份 catalog（zh-CN 简体、zh-TW 繁体），并在 zh 分支内按书写体系子标签直接分流，不进入
下面的 subtag 循环。hant 与 TW/HK/MO 判为繁体，hans 与其余 zh 标签判为简体——两种
拼写都要覆盖，因为平台只报地区子标签时 TW/HK/MO 是唯一可用的线索。
bongocat-config 的 Language::from_system_locale 与 bongocat-i18n::locale_code 各做一次
同样的判定：两个 crate 之间不存在依赖方向，不能共用一个 helper，行为必须由测试对齐。

语言文件放在 crates/bongocat-i18n/locales/，每种语言一个 JSON 文件，使用 _version: 1
和真正嵌套的领域结构。rust-i18n 在编译期将嵌套路径解析为查找 key；JSON 源文件本身不得使用
点号分隔的扁平 key。Rust UI 在文案实际使用处直接引用稳定的领域路径，不内嵌翻译文本或维护
enum 到 key 的集中映射。

新增一种语言是一次数据加注册的改动，不改变本 ADR 的任何结构决定：写一份与 en-US 同
key、同占位符的 JSON，然后在 build.rs 的 CATALOGS、Language/SettingsLanguage 两个
枚举及其 code/catalog_locale/from_system_locale/resolve、settings_language_display_name
和 tools/validate-locales.py 的 EXPECTED_LOCALES 中各加一项。语言下拉里每种语言用自身
文字书写（endonym），而不是当前窗口语言的名字。

约束 Copy Chapter

• 翻译 key 使用小写 snake_case，按 navigation、settings、models、shortcuts、
  diagnostics、about、actions、status 和 errors 等领域分层；字段名必须表达具体上下文。
• 插值使用 rust-i18n 的 %{name} 语法；所有语言必须保持相同的占位符集合。
• 找不到语言或 key 时回退到 en-US；system 在配置/平台层先解析为受支持语言。
• GPUI 语言切换通过已有带 revision 的设置 snapshot 触发重绘；本地化查询不进入 overlay frame loop。
• 新文案必须先加入 JSON，再由 Rust 使用 key；禁止在 .rs 中新增自然语言翻译文本。
• bongocat-i18n 是唯一调用 rust_i18n::i18n! 的 catalog owner。UI 使用其 text(locale, key)
  facade，并在使用点写出 key；不得为 UI crate 再初始化同一份 catalog 或依赖全局 locale。
• 测试/CI 必须检查 JSON 可解析、语言 key 集合相同、值为非空字符串且占位符集合一致。
  语言清单只在 crates/bongocat-i18n/src/tests/mod.rs 的 LOCALES 一处枚举，各条比较型测试
  都遍历它，因此新增语言不会让某条比较悄悄少覆盖一种语言。
• UI 文案的书写约定见 docs/localization-copy-conventions.md。当前已落地的一条：省略号一律写
  单个 …（U+2026，视觉上是三个点），禁止中文排版习惯的 ……（六个点）与拉丁写法的 ASCII
  ...——同一个 key 由所有语言共用，写法必须与语言无关。该规则由 tools/validate-locales.py
  机械强制，不依赖 review。

取舍 Copy Chapter

gpui-kit 的底层 gpui-component 也使用 rust-i18n，因此依赖生态一致。rust-i18n 与传递的 rust-i18n-macro／rust-i18n-support 必须停在同一个补丁序列：4.2.4 的宏展开调用 rust_i18n::replace_patterns_cow，只存在于 4.2.4 的运行时 crate，跨版本混用会让 gpui-component 与 bongocat-i18n 同时编译失败。JSON 比 YAML/TOML 更适合现有前端资源、翻译工具和跨语言校验；本方案不引入 Fluent 的复数/选择语法。若后续产品需要复杂 ICU/Fluent 消息，应另行提交 ADR，不在业务代码中混用第二套格式。

Adr 0012 Ordered Motion Audio Service (`docs/adr/0012-ordered-motion-audio-service.md`) Copy Section

ADR-0012: Ordered Motion Audio Service

状态：Accepted
日期：2026-08-31

后续修订（2026-10-12）：rodio 由 =0.22.2 升级到 crates.io 精确 pin =0.23.0。
该 release 把 cpal 由 0.17.3 升到 0.18.2，并把此前分散的 cpal 错误类型
（StreamError、BuildStreamError、PlayStreamError、DevicesError、
DefaultStreamConfigError、SupportedStreamConfigsError）统一为 cpal::Error，以
CpalError/CpalErrorKind 重导出，rodio::DevicesError 被移除。项目只使用 Decoder、
SamplesBuffer、DeviceSinkBuilder、Player 与 rodio::cpal::BufferSize，不匹配这些
错误类型，源码零改动。仍然只启用 playback 与 flac，不改变本 ADR 的替换边界。

Context Copy Chapter

预置 model3 的 motion 通过相对路径引用 FLAC。音效是动作被接受后的产品副作用，
不能进入 RenderSnapshot、阻塞 runtime/input，也不能因文件、解码或输出设备故障让
动作或画面失败。旧产品同一时刻只保留一个 motion voice；新动作、显式停止、禁用、
成功切模和退出都需要明确停止边界。

Decision Copy Chapter

• 使用 crates.io 当日最新稳定版 rodio 0.23.0，精确 pin，只启用 playback 与 flac。
  不启用录音、MP3、MP4、Vorbis、WAV、dither 或其它未使用 feature。
• bongocat-audio 是独立 Rust owner。它持有固定容量 16 的有序 command queue、专用
  worker、decoder、output stream 和唯一 voice；runtime 只非阻塞发布强类型
  Play/Stop，不执行文件、解码或设备工作。
• motion request 只有在 runtime priority 与 Live2D resource 校验均接受后才触发音效。
  新 motion 替换当前 voice；无声音的新 motion 也停止旧 voice。显式 motion stop、关闭
  配置、成功 model commit 和 shutdown 立即停止 voice，不等待 motion fade 结束。
• 模型 activation 在 renderer prepare 成功后，把该模型的去重 sound paths 作为 Prepare 发送给
  audio worker。worker 在这里解码 FLAC 为 immutable PCM cache；renderer prepare 与 PCM prepare 都完成后
  才提交该模型。预热失败只形成稳定 audio 诊断，仍允许模型提交；随后 play 会按既有降级语义失败，不能阻塞
  动作或渲染。成功 commit 后 ActivatePrepared 只保留新活动模型的 cache。
• 已活动模型的 motion 在同一 runtime command 中先向有序队列发布缓存 Play，再以同一单调 tick
  启动 motion。动作路径不执行文件 I/O、解码、设备创建、get_pos() 等待或 1 ms 轮询。audio owner
  优先以 512-frame buffer 打开默认设备，设备拒绝时回退 rodio 默认 sink。
• 音量使用经过校验的 [0, 1] 强类型值，当前产品触发值为 1.0。同一时刻最多一个
  motion voice，不混音、不排队延后播放。
• 队列满载不阻塞 runtime：返回原 command、增加匿名 overflow 计数、丢弃无法证明
  顺序的 backlog 并强制停止 voice。文件 I/O、解码和输出故障进入稳定 error code 与
  聚合诊断，后续 command 可以恢复服务；诊断不包含用户路径或音频内容。
• 应用先停止输入与 runtime，再停止并 join 音频 worker；worker 在返回 Stopped 前
  停止 voice、丢弃 pending command 并释放 rodio/CPAL output owner。

Dependency Boundary Copy Chapter

rodio 0.23.0 声明 MIT OR Apache-2.0，Rust 1.87+，仓库在审计日仍活跃；底层 CPAL
支持 Windows/macOS 系统输出。rodio 0.23.0 把 cpal 升到 0.18.2，lockfile 因此解析为
0.18.2；项目不直接依赖或 fork CPAL 来伪造版本升级。

rodio/CPAL 类型不离开 bongocat-audio 私有 backend。替换其它音频库时只需保持
MotionAudioClient、强类型 command、诊断和 shutdown contract，不修改 runtime、模型
或 UI 公共协议。Linux 首发后评估时再启用对应 output target；当前 Linux contract build
不链接 ALSA，也不把 Linux 音频变成 Windows/macOS 首发阻塞。

Consequences Copy Chapter

音频解码成本转移到模型 activation；设备打开继续由 audio owner 惰性执行，但 runtime 不等待它。
rodio::Player::get_pos() 只反映 mixer 位置，不能作为扬声器起播确认，因此不再用作动画时钟。当前实现支持现有预置模型实际使用的 FLAC；
新增格式必须先形成模型兼容需求，再单独启用 decoder feature 和测试。默认设备热切换、运行中 stream
error callback、端到端音频/画面时序测量、100 次 model/audio 资源测量与 8 小时 soak 仍属于后续
稳定性验收，不由本 ADR 的单元测试替代。

Adr 0013 Startup Item Capability (`docs/adr/0013-startup-item-capability.md`) Copy Section

ADR-0013: Startup Item Capability and Environment Isolation

状态：Superseded by ADR-0043
日期：2026-08-31

Context Copy Chapter

BongoCat 支持 macOS 12+，但 SMAppService.mainAppService 只在 macOS 13+
可用。Development 与 Production 又固定使用相同 Bundle ID；若开发构建直接注册 main
app login item，会覆盖同一用户的生产启动项系统状态。Windows 的当前用户启动项没有同样
的 Bundle ID 限制，但仍必须按构建环境隔离名称与目标命令。

启动项是可选平台能力，失败不能阻止 runtime、overlay 或设置窗口启动。UI 需要区分未启用、
已启用、路径过期、等待系统批准和当前环境不支持，而不能把所有情况压缩成一个布尔值。

Decision Copy Chapter

• 共享平台 API 使用稳定的 StartupItemEnvironment、StartupItemState 和
  StartupItemError，不暴露 registry handle、Objective-C object 或第三方错误类型。
• Windows 使用当前用户 HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run，
  Development 与 Production 使用不同 value name。启用时写入当前 executable 的带引号绝对
  路径和 --run-seconds 0；状态检测必须区分完全匹配与 stale value；禁用只删除当前环境的
  value，不读取或修改另一环境。
• macOS 13+ Production .app 使用 SMAppService.mainAppService。状态映射保留
  not-registered、enabled、requires-approval 和 not-found；not-found 是可显式尝试注册的
  预注册状态，不在 adapter 或 UI 提前判为无效。注册/取消注册错误只向上返回稳定匿名 code。
• macOS 12 返回明确的 unsupported capability，应用其余功能继续运行。不得回退到已废弃的
  SMLoginItemSetEnabled、自行写 LaunchAgent 或修改用户登录项数据库。
• macOS Development 构建只报告 unsupported build environment，不注册或取消注册
  mainAppService，从而不改变 Production 的系统登录项状态。真实变更 smoke 使用临时签名的
  Production .app 和隔离测试用户/CI runner，并从 /Applications 下的临时唯一安装目录
  启动，使 LaunchServices 与 SMAppService 验证的是安装态 main application。
• 启用、禁用只能由显式用户 command 触发；正常启动只读取状态。平台失败不改变配置，也不
  阻塞 input/runtime/renderer。

Consequences Copy Chapter

• macOS 12 用户可使用产品核心功能，但设置页会明确显示登录启动不可用。
• 开发构建不能直接演练 macOS 注册变更；平台 contract test 与 Production bundle smoke 负责
  覆盖，公开发布前仍需签名构建和 System Settings 批准路径实测。
• Windows 安装位置变化会显示 stale，而不是误报 enabled；用户再次启用可原子覆盖当前环境
  value。
• 启动项状态属于平台 snapshot，不进入配置 schema，也不由 runtime 动画状态持有。

Verification Copy Chapter

• 纯 contract test 覆盖所有 state/error code、环境命名和 Windows command 编码。
• Windows 临时当前用户 value smoke 覆盖 disabled -> enabled -> stale -> disabled，并保证只
  触及当前环境 value。
• macOS 12 availability probe 不引用缺失 class；macOS 13+ Production bundle smoke 从
  /Applications 的临时安装目录覆盖 status、register/unregister 和 requires-approval 映射，
  结束时恢复原状态并注销/删除临时 bundle。首次 not-found 注册后取消注册允许规范化为
  not-registered，因为两者都不留下启用的登录项。
• 双平台 smoke 后运行完整 format、Clippy、workspace test 和 release check。

Adr 0014 Formal Settings Accessibility Bridge (`docs/adr/0014-formal-settings-accessibility-bridge.md`) Copy Section

ADR-0014: Formal Settings Accessibility Bridge

状态：Accepted（2026-08-31）

后续修订（2026-09-23）：ADR-0054 已退役项目自有设置语义桥。本文保留作为当时的 AccessKit/action 实现证据；当前设置 UI 只验收可见控件、焦点和键盘导航。

Context Copy Chapter

The settings window needs project-owned accessibility semantics before the startup-item UI can
close its accessibility gate. GPUI 0.2.2 does not provide a stable public element-level semantic
API, while platform accessibility adapters must not become a second business-state owner.

Decision Copy Chapter

• bongocat-ui builds an AccessibilityTree from its existing page, snapshot, pending and focus
  state. Node IDs, roles, values, toggles and supported actions are project-owned types.
• bongocat-platform owns the AccessKit macOS/Windows adapter and receives only a copied raw
  window handle plus the project tree. It does not read settings, runtime or config state.
• AccessKit Click/Focus actions cross a bounded capacity-32 channel and are applied by the GPUI
  entity. Clicks reuse the existing typed settings commands; focus is applied through existing
  FocusHandles on the next render.
• Disabled/loading/unsupported controls do not expose mutation actions. Adapter diagnostics count
  forwarded and rejected actions without recording labels, key identities or user content.
• Product smoke may inspect the native AX/UIA role, value, enabled/focusable state and advertised
  action pattern. It must not toggle the startup item; platform lifecycle smoke remains responsible
  for mutation and restoration.
• The bridge is attached after the GPUI native handle exists but while WindowOptions::show is
  still false, then the window is activated. It is retained by SettingsView and dropped before
  the corresponding GPUI window is destroyed; attachment failure leaves the window hidden and is
  returned to the product coordinator.

Consequences Copy Chapter

The startup switch now has a formal switch role, value, toggle state and action mapping on both
platform adapters. This does not claim VoiceOver/Narrator or physical assistive-technology
verification; those remain release evidence gates. If GPUI later exposes an equivalent stable API,
the platform adapter can be removed without changing runtime or settings command contracts.

Adr 0015 Settings Revision Boundaries (`docs/adr/0015-settings-revision-boundaries.md`) Copy Section

ADR-0015: Separate UI Snapshot and Configuration Revisions

状态：已接受

背景 Copy Chapter

设置 snapshot 需要在 runtime、平台状态、输入诊断和模型目录变化时刷新。配置写入同时需要
compare-and-swap，防止窗口中的旧编辑覆盖后台配置。若两者共用一个 revision，纯诊断变化会
错误拒绝仍然有效的配置编辑。

决策 Copy Chapter

• SettingsSnapshot.revision 是 UI 可观察内容的单调版本，只用于丢弃过期异步结果和刷新视图。
• SettingsSnapshot.config_revision 是当前环境持久化配置的版本；没有可编辑配置 snapshot 时为 None。ADR-0054 后，损坏配置按备份/默认值 fallback，恢复路径仍进入普通设置窗口，不再有 recovery-only 版本。
• 所有已接入的配置/模型选择 command（overlay settings、motion audio、model selection）携带
  expected_config_revision，settings worker 在调用 Application 写入前比较它。Overlay visibility
  是 runtime-only command，不写配置；它仍携带当前 config revision 作为 stale-view guard。
• 比较失败返回匿名 SnapshotOutdated，不改变 runtime、配置文件或任何 revision；UI 读取最新
  snapshot 并保留可操作错误。

后续边界 Copy Chapter

模型选择、启动项和其他配置域接入 optimistic concurrency 时继续使用 config_revision；纯
平台/诊断状态不得改变该 token。revision 仍可因这些状态变化推进。

Adr 0016 Diagnostics Export Contract (`docs/adr/0016-diagnostics-export-contract.md`) Copy Section

ADR-0016: Anonymous Diagnostics Export Contract

状态：已接受（2026-09-01）

背景 Copy Chapter

Diagnostics 页面已经聚合 runtime、输入、配置和模型目录状态，但用户和维护者需要一个可预览
的文件来复现问题。直接打包原始日志、模型目录或输入事件会泄漏用户路径、模型身份和按键内容，
也会让导出格式依赖 Rust Debug 文本而无法稳定解析。

决策 Copy Chapter

• 通过 settings service 的 ExportDiagnostics 强类型 command 生成 format version 1 JSON。
• 导出目标固定为当前不可变构建环境的 logs/diagnostics.json，使用同目录原子写入；UI executor
  不执行文件 I/O。
• 文档只包含 runtime/input/configuration 的稳定 code、匿名计数、模型来源计数和
  settings/config revision。模型 ID、路径、原始按键或事件流、原始配置、时间戳和动态 I/O 文本
  永远不进入导出。
• 导出成功状态只回传格式版本和字节数，作为 UI snapshot 的非配置 revision；失败返回固定的
  diagnostics_export_failed，不暴露操作系统文本。
• Diagnostics 页面提供键盘和 AccessKit 可访问的导出操作；“无报告”与成功字节数属于显示状态，
  不影响配置 revision。
• 更新诊断以可选的 update 分栏加入导出，仅允许匿名稳定错误码和阶段计数
  （check/download/install 的 started/succeeded/failed）；未接入更新 worker 时该分栏为 null。
  provider 的错误码必须来自 bongocat-update 统一 catalog；未知值在 Application 边界被丢弃，
  计数仍保留。不导出 endpoint、URL、HTTP 状态正文、artifact 路径、版本或签名材料。
• 导出额外包含 app-owned 和 Cubism Core 两个日志 owner 各自的匿名聚合统计（written、dropped、
  rotated、pruned、bytes 和 retained_files），但不读取或复制任何日志正文、路径或 Core 消息。
• format version 1 是当前完整的匿名结构；消费者必须拒绝非 v1，不能猜测或忽略不兼容的
  导出格式。在首版发布前字段直接修改当前 v1，并同步此 ADR、测试与文档，不保留中间格式的兼容分支。
  首版发布后才为不兼容演进建立新的版本、schema、测试与 ADR。

后续边界 Copy Chapter

应用级日志 writer 的实现与有界清理已记录在 ADR-0017；跨域历史日志合并、预览器和更新系统的
诊断 manifest 仍需单独设计。
实现不得为了导出而放宽日志隐私、环境隔离或原子写入约束。

Adr 0017 Bounded Application Logging (`docs/adr/0017-bounded-application-logging.md`) Copy Section

ADR-0017: Bounded Application Logging

状态：已接受（2026-09-01）；2026-09-24 由 ADR-0064 修订文本格式、过滤与统一 retention

背景 Copy Chapter

BongoCat 需要可诊断的应用生命周期记录，但不能把按键、路径、剪贴板、配置/模型正文、URL、密钥/凭据或用户文件
内容写入日志。Cubism Core callback 只覆盖厂商边界，不能替代应用级日志；无界文件增长也会破坏环境
隔离和稳定性验收。早期实现使用 JSONL 与两个独立 writer，ADR-0064 已把输出改为普通文本，并让
application/Core 共用一套 writer policy。

决策 Copy Chapter

• bongocat-app 持有 app-owned ApplicationLogHandle，业务调用只能提交闭合 event catalog 中的
  module、stable code、固定 message 和有界安全上下文。路径、原始按键、剪贴板、配置/模型正文、
  动态 OS 错误文本和密钥不进入日志协议。
• application 与 Cubism Core 使用 bongocat-log 的同一套 UTF-8 单行文本 writer、级别过滤、按 UTC
  日切换、单文件大小保护、目录总量/文件数预算与 retention；两类 stream 仍分离，便于支持人员区分
  产品事件和厂商 callback message。
• 文件名固定为 application-YYYY-MM-DD.log / cubism-core-YYYY-MM-DD.log；轮转段使用
  .<generation>.log。单个文件达到 1 MiB 后继续切分，两类日志合计最多 8 MiB/32 个文件，当前
  UTC 日活动文件始终保留，过期或超预算的最旧已轮转文件优先删除。
• 当前 v1 logging.level 接受 error、warn、info、debug、trace，默认 info；
  logging.retention_days 接受 1..=30，默认 7。设置先原子持久化，再立即更新共享 controller
  并收敛允许删除的旧文件；不提供 rotation mode、文件大小或目录容量配置。
• Cubism Core callback 只复制至多 512 bytes 到容量 128 的 non-blocking queue；专用 Rust worker
  才调用共享 writer。callback 不执行格式化或文件 I/O；callback-slot contention、queue full 和 stop
  后迟到记录只增加匿名 dropped 计数。shutdown 先注销 callback，再拒绝新记录、排空队列并 join
  worker。Core callback 没有可信 severity，原始 message 固定按 debug 过滤；实际 Core/renderer
  失败由 app owner 以稳定 error/warn event 记录。
• Application startup creates application-running.marker inside the environment's log directory.
  The v1 marker contains only a schema version and one fixed phase: running, shutting_down, or
  panicked; it is flushed before services start and is removed only after runtime/audio shutdown
  and the shutdown_completed event. The next startup classifies a leftover marker anonymously as
  forced/unknown, shutdown interrupted, or panic, then immediately overwrites it with a new
  running marker. This preserves diagnosis without recording payloads or paths and prevents a
  stale marker from causing a repeated recovery loop.
• Diagnostics export includes aggregate counts for the fixed application event codes and a saturated
  application-plus-Core retained-byte/file summary, alongside separate anonymous source counters, as
  part of its current format version 1. Consumers must reject non-v1 data rather than guessing. The
  export never embeds raw log records, panic payloads, paths, key values, or user file content.
• Diagnostics preview 另由 ADR-0027/0064 约束：只从严格命名且可解析的 application .log 来源重写
  闭合 code，不复制原日志行；Core 原始 message 永远不进入 preview。

验证 Copy Chapter

bongocat-log 单元测试覆盖级别顺序、共享 controller、UTC 日切换、1 MiB 轮转、配置化保留、目录级
8 MiB/32 文件预算、未知文件/符号链接隔离、严格文本 parser 与 owner-only 权限。bongocat-app 覆盖
固定 event catalog、panic 脱敏、运行标记分类、共享过滤/retention 和脱敏 preview；bongocat-live2d
覆盖 Core callback contention、queue saturation、shutdown drain、文本写入和跨 writer prune 统计。
macOS Development release smoke 已验证 diagnostics-export 固定 entries、panic=abort 恢复和
settings-window lifecycle；独立 bounded normal run 在本机最新尝试中超时并留下 unclean marker，仍需复核。
Windows release smoke 与完整双平台证据仍待发布门禁补齐。

后续边界 Copy Chapter

远程上传、Core message 导出和第三方稳定日志 schema 不在本 ADR 范围。.log 面向用户与支持人员，
需要机器处理时使用匿名 diagnostics.json 或严格重写后的 preview entry。

Adr 0018 Model Interaction Settings (`docs/adr/0018-model-interaction-settings.md`) Copy Section

ADR-0018: Typed Model Interaction Settings

状态：已接受（2026-09-01；2026-09-25 增加键盘/手柄模型输入门禁；2026-09-27 指针跟随按轴拆分）

背景 Copy Chapter

BongoCat 的 配置已经包含水平镜像、镜像指针跟随和忽略指针字段，但此前
这些字段没有穿过 runtime 边界。直接让 renderer 读取配置会违反 renderer 只消费不可变
RenderSnapshot 的所有权规则，也会让模型求值与显示变换在不同线程拥有不一致的设置。

决策 Copy Chapter

• bongocat-runtime::ModelSettings 是六项模型交互设置的唯一 runtime 类型，并通过
  RuntimeCommand::SetModelSettings 写入、RuntimeSnapshot::model_settings 读回。
• mirror 由 runtime 写入 RenderSnapshot::mirror_horizontal；Windows D3D11 和 macOS
  Metal 只依据该不可变字段对模型中心执行水平变换，不读取配置或 UI 状态。
• 指针跟随按轴拆成 mirror_pointer_tracking_horizontal 和
  mirror_pointer_tracking_vertical，两项互相独立、默认均为 false：水平项在产品参数覆盖阶段
  反转指针的 X/Z 值（Z 与 X 是同一水平扫视的两个方向），垂直项只反转 Y 值。拆成两个布尔值而不是
  一个方向枚举，是因为「左右相反」和「上下相反」可以只出现其一、也可以同时出现，枚举无法在不增加
  第三种取值的前提下表达这四种组合；ignore_pointer 仍然跳过所有指针参数覆盖，使 Core 默认值或
  前序动画值保持有效。
• ignore_keyboard 和 ignore_gamepad 是模型输入投影门禁：分别屏蔽键盘的键图/手部贡献，
  以及手柄的按钮/手部/摇杆/扳机贡献。它们不停止平台采集、pressed-state 校正与复位、
  匿名诊断或独立的快捷键注册；原始 pressed state 始终保留，解除门禁后仍能正确处理释放。
  三个模型输入忽略开关各自有一个可选的 application shortcut target，触发后仍经 settings
  service 的 typed command 和配置 revision 原子持久化。
• 应用启动在配置验证后发送一次 typed settings command。动态设置页编辑、revision-checked
  持久化 command 和完整多显示器/实机输入证据由后续 TODO 继续跟踪。

验证 Copy Chapter

runtime 测试验证 settings command 的 revision、snapshot 和 shutdown 保留，分别验证键盘/手柄
输入门禁只改变模型投影而不丢失另一来源或原始 pressed state，并验证两个指针翻转开关各自只影响
所属轴：单开水平项时 X/Z 反号而 Y 不变，单开垂直项时只有 Y 反号，两项同开等于两次单开结果的组合。
app service 测试验证三个输入门禁快捷键会切换并持久化对应设置，并验证两个翻转字段经 typed command
写入配置文件后重启仍被恢复。macOS Cubism 测试验证指针镜像/忽略规则及 render snapshot 镜像
字段；overlay 变换测试验证普通与水平镜像在中心点保持相同且 X scale 符号相反。Windows 使用
相同纯 Rust 变换逻辑，其真实 GPU/DPI 矩阵仍属于平台门禁。

后续边界 Copy Chapter

本 ADR 不改变 physics/pose 的授权 fixture 和行为求值门禁，不声称完整 Live2D 兼容；
也不定义快捷键冲突、用户编辑或平台全局 hotkey 注册协议。

Adr 0019 Gpui Component Design System (`docs/adr/0019-gpui-component-design-system.md`) Copy Section

ADR-0019: gpui-component Design System

状态：已被 ADR-0020 取代（2026-09-04）

后续修订（2026-09-23）：除 ADR-0020 的 facade 取代外，ADR-0054 进一步退役了项目 AccessKit bridge；本文的组件与语义细节均为历史证据。

背景 Copy Chapter

设置窗口需要与固定的 gpui 0.2.2 兼容的主题、输入和桌面控件。维护者决定将现有
guise-ui 1.5.3 替换为 gpui-component，并指定其官方组件文档作为 API 事实来源。

决策 Copy Chapter

• workspace 使用 GPUI Kit 官方开发版 gpui-component 0.5.2 revision
  c0946e6acdc9e2f984f317ef7f998ee2c79f1a87，关闭未使用的可选 feature；其许可证为
  Apache-2.0，依赖 GPUI 0.2.2。GPUI Kit 的 manifest 使用官方 Zed git source，提交的
  Cargo.lock 固定当前解析到的 GPUI revision 55c0cc36d18cf06c6c54f640a87ce83d09413ae4，
  避免组件与应用加载两份 GPUI 类型；gpui_platform 使用同一 Zed source。
• 设置窗口在首次创建组件前调用 gpui_component::init，以官方 Root 作为窗口根视图，并在
  系统外观变化时同步 Theme。
• 该 GPUI revision 默认会为窗口安装自己的 AccessKit adapter，而现有项目桥接仍承载已验证的
  macOS AX/Windows UIA 语义和 action contract。过渡期所有 GPUI 应用入口使用
  Application::new_inaccessible(gpui_platform::current_platform(false))，仅禁用重复的 GPUI
  adapter，避免两套 accesskit_macos 向同一 NSView 注册同名 Objective-C 类并触发 abort；
  项目桥接继续提供辅助功能。迁移到 GPUI 原生 element-level 语义后必须同时删除项目桥接、
  直接 AccessKit 依赖和此兼容构造，并重跑双平台辅助功能门禁。
• 图标资源使用官方 gpui-component-assets = 0.5.1 的 Assets（Lucide SVG），通过
  Application::with_assets 注册给 GPUI；应用不自维护重复的 icons/*.svg 文件。
• UI 使用组件库的 Settings、SettingPage、SettingGroup、SettingItem、SettingField，以及
  Button、Switch、Tag、Input 和 NumberInput。偏好设置页面由官方 Settings
  sidebar 管理，页面内按职责使用 SettingGroup；Settings 自带的搜索会按 SettingItem 标题、描述和显式关键词过滤，页面/分组名称由 ADR-0066 作为关键词提供，业务关键词不再塞进可见描述。
  InputState 只持有编辑状态；InputEvent/NumberInputEvent 转换为现有 typed command，
  runtime snapshot 仍是持久状态事实来源。
• gpui-component 0.5.2 没有普通 Card primitive；HoverCard 是悬浮预览组件而非内容容器。
  Settings 分组使用官方 GroupBoxVariant::Outline，模型管理和诊断等复杂内容通过官方
  SettingField::element 嵌入，不另建设置框架。
• 第三方类型不进入 runtime、config 或 model 公共 API。停止维护或 GPUI 版本不兼容时，替换
  边界保持在 bongocat-ui 和窗口初始化代码内。

影响 Copy Chapter

gpui-component 提供的控件范围更广，但传递依赖和编译成本高于 Guise。锁文件必须提交，后续
升级继续按仓库依赖规则审计版本、许可证、平台构建和完整输入/窗口 smoke。双平台辅助功能、缩放
及真实交互证据仍是 UI 完成门禁，本 ADR 不将这些 TODO 标记完成。

Adr 0020 Gpui Kit Facade (`docs/adr/0020-gpui-kit-facade.md`) Copy Section

ADR-0020: GPUI Kit 统一依赖入口

状态：已接受（2026-09-04）

后续修订（2026-09-24）：ADR-0054 退役项目自有设置语义桥。上游已合并 SettingGroup::variant()，但包含该能力与 Popover::arrow() 的 crates.io release 尚未发布；当前直接依赖上游固定 revision 500852f449c05dc01920ec82f3ae2656a61d0387，不再使用 [patch.crates-io] 或维护者 fork。对应 release 发布后恢复纯 registry 精确 pin。

后续修订（2026-09-28）：上游已发布 gpui-kit v0.7.0，该 release 同时包含
SettingGroup::variant() 与 Popover::arrow()。按上一条与 ADR-0056 的既定条件，直接依赖
切回 crates.io 精确 pin =0.7.0，longbridge/gpui-kit git source 与 deny.toml 的对应
放行项一并删除。GPUI 依赖随之上移到 gpui-pre 0.3.7。

后续修订（2026-10-06）：升级到 crates.io 精确 pin =0.7.1，GPUI 依赖随之上移到
gpui-pre 0.3.8。仍然只依赖同一个 registry 版本，不改变本 ADR 的替换边界。

后续修订（2026-10-12）：升级到 crates.io 精确 pin =0.7.3，GPUI 依赖随之上移到
gpui-pre 0.3.9（Zed 快照 93d745668805029476e6d7fbb19652116fed51de）。仍然只依赖同一个
registry 版本，不改变本 ADR 的替换边界。

背景 Copy Chapter

ADR-0019 直接组合 Zed git source 的 gpui、gpui_platform 与 GPUI Component 开发版及
assets。应用必须手工保证四个 source 的类型一致，manifest、import 和升级边界分散。GPUI Kit
随后在 crates.io 发布 0.6.0，提供 GPUI、platform、base、component 和 assets 的统一入口。

决策 Copy Chapter

• workspace 只直接依赖 gpui-kit，当前为 crates.io 精确 pin =0.7.3，并提交完整
  cargo update 后的 Cargo.lock。不再直接声明 gpui、gpui_platform、gpui-component
  或独立 assets crate，也不使用其它 git source 混装 GPUI。
• 代码从 gpui_kit 根使用 GPUI 类型，从 gpui_kit::platform、gpui_kit::component 和
  gpui_kit::assets 使用对应层；组件初始化统一调用 gpui_kit::init。
• 当前固定的 gpui-kit 使用 Apache-2.0 许可证。它的 GPUI 依赖
  通过 crates.io gpui-pre 同步包交付；当前 lockfile 解析到 0.3.9（v0.7.3 起
  gpui-kit 以 =0.3.9 精确 pin 该家族，gpui-pre-reqwest 仍为 0.12.15），包元数据声明
  Zed gpui 0.2.2 revision 93d745668805029476e6d7fbb19652116fed51de。因此项目不再直接
  覆写 GPUI，但也不把该传递包误记为 crates.io 包名 gpui = 0.2.2。
• 2026-09-19：gpui-kit 由 =0.6.1 升级到 =0.6.4（v0.6.2 功能版与 v0.6.4 补丁的
  最新稳定版；无 breaking API 变化），升级范围仍在 bongocat-ui 与 bongocat-app，
  不改变本 ADR 的替换边界。
• 2026-09-22：gpui-kit 由 =0.6.4 升级到 =0.6.6（crates.io 最新非 yanked 稳定版；
  v0.6.5/v0.6.6 为补丁：masked label 跳过高亮，以及把 gpui-pre 改为 =0.3.6 精确
  pin，无 breaking API 变化）。lockfile 中 gpui-kit 本体之外，gpui-base/
  gpui-component/gpui-kit-assets 0.6.6 与 gpui-pre 0.3.6（Zed 快照
  bcf6582ce3500df93a8a39366640173e6786cea6，zed-version 仍为 0.2.2）在本次
  cargo update 前已由此前一次完整 cargo update 解析到位，本次无 diff；v0.6.6 的
  =0.3.6 约束恰好与既有解析一致。升级范围仍在 bongocat-ui 与 bongocat-app，
  不改变本 ADR 的替换边界。
• 2026-09-24：cargo search gpui-kit --limit 1 与 cargo info gpui-kit 仍显示 crates.io
  最新稳定版为 0.6.6，但该 release 不含上游后来合并的 SettingGroup::variant() 与
  Popover::arrow()。上游 merge commit 500852f449c05dc01920ec82f3ae2656a61d0387
  的 package 元数据仍为 0.6.5，因此本仓库直接固定该完整 commit；lockfile 中
  gpui-kit、gpui-component、gpui-base、gpui-component-macros 与
  gpui-kit-assets 统一为同一 git source，gpui-pre 仍为 crates.io 0.3.6。
• 同一 revision 由 Root 自动挂载 dialog、sheet 与 notification layer；业务根视图删除旧的
  Root::render_*_layer 调用。PopConfirm 转发 Popover::arrow(bool)，模型删除确认启用
  anchor-aligned arrow。对应上游 release 发布后，本条临时 git source 决策自动失效并恢复
  crates.io 精确 pin。
• 2026-09-28：gpui-kit v0.7.0 发布，包含上述两项 API 与 Root 的自动挂载行为，因此
  切回 crates.io 精确 pin =0.7.0，删除 longbridge/gpui-kit git source 与 deny.toml
  的对应放行项。lockfile 中五个 suite package 统一解析为 0.7.0，GPUI 同步包升到
  gpui-pre 0.3.7（v0.7.0 以 =0.3.7 精确 pin 该家族）。项目未使用 release notes 中
  breaking change 涉及的 Chart/Plot、DatePicker/TimeField、Table、TextView heading 与
  表单/表格/弹层 primitive 迁移面，源码零改动；Root 与 WindowExt 仍由业务窗口入口
  直接使用。
• 2026-10-06：gpui-kit 由 =0.7.0 升级到 =0.7.1（crates.io 最新非 yanked 稳定版）。
  suite 五个 package 统一为 0.7.1，GPUI 同步包升到 gpui-pre 0.3.8（v0.7.1 以 =0.3.8
  精确 pin 该家族；同版本内含 continuation-indent API 适配，保持原有换行行为）。release notes
  里的两处行为变化——chart 首次绘制动画默认开启、Questionnaire 单选即确认——只涉及项目未使用的
  组件；新增的 speech/ColorSelect 与 RenderedText::source 也是增量 API。IME 候选框定位、输入框
  单行裁剪、disabled Radio、菜单键盘高亮、CJK 标点换行等修复落在设置界面实际使用的组件上，
  源码零改动。workspace 范围的 cargo update 同时把 rust-i18n-macro/rust-i18n-support 带到
  4.2.4，与 gpui-component 展开 t! 所需的 rust-i18n 运行时不再匹配，因此直接 pin 由 =4.2.2
  上调到 =4.2.4（ADR-0012）。
• 2026-10-12：gpui-kit 由 =0.7.1 升级到 =0.7.3（crates.io 最新稳定版；上游发布说明
  声明 v0.7.3 取代 v0.7.2 并包含其全部改动）。suite 五个 package 统一为 0.7.3，GPUI 同步包
  家族统一为 gpui-pre 0.3.9（v0.7.3 以 =0.3.9 精确 pin 该家族）。lockfile 随之移除
  gpui-pre 不再需要的传递依赖——tracing-subscriber/sval/value-bag 系列、
  bindgen/clang-sys/cexpr/prettyplease、bzip2 与 libbz2-rs-sys、cgl、
  core-graphics2、core-video、io-surface、objc2-core-media、
  objc2-screen-capture-kit、async-compression/compression-*——并新增 v0.7.3 引入的
  可选后端 gpui-fast 0.1.7 家族与 Diff 组件所需的 similar。libbz2-rs-sys 已不在依赖图
  中，deny.toml 为它保留的 bzip2-1.0.6 例外一并删除（cargo deny 会把它报成
  unmatched license exception）。
• v0.7.3 的两处行为变化落在项目实际使用的组件上：TextView 默认排版改为按继承字号计算标题
  字号（0.7.1 是相对硬编码 px(14.) 的绝对 rem 阶梯，更新窗口以 .text_xs() 渲染更新日志时
  二级标题会到 21px），段落间距由 1rem 收到 0.75rem；设置列表的横向内边距移进列表行，
  焦点环不再被列表裁剪。两者都是外观变化，不涉及项目代码的 API 迁移面——Dialog 入场动画、
  TooltipDefaults、DataTable header_row_height、Editor 补全、InputState::add_selection
  等均为项目未使用或纯增量能力，源码零改动。
• gpui-fast 是 v0.7.3 新增的可选 feature，启用后整套 GPUI 实现由 gpui-pre 换成 wgpu 后端的
  gpui-fast。本 ADR 不启用它：后端替换需要单独的 ADR、双平台实机证据与设置窗口、IME、缩放、
  窗口重建回归，不能作为依赖升级的附带结果。
• GPUI Kit 默认 component/assets feature 正好覆盖当前设置窗口。tree-sitter、decimal、
  inspector 和 test-support 等可选 feature 不启用。其 native facade 还会引入配套 HTTP client
  与 TLS 传递依赖；这些依赖不得进入 BongoCat 的业务 API。
• 当时保留项目 AccessKit bridge、typed command/snapshot 和独立 overlay 边界；Application::new_inaccessible 通过 gpui_kit::platform 构造。ADR-0054 后项目桥接已退役，new_inaccessible 只作为禁用 GPUI adapter 的兼容选择保留，不再形成 BongoCat 的辅助功能 contract。
• 替换边界限定在 bongocat-ui 与 bongocat-app 的窗口入口。上游停止维护、许可证变化或
  GPUI 版本不兼容时，只替换这一 UI 边界，不向 runtime、config、model 或 renderer 扩散
  GPUI Kit 类型。

影响 Copy Chapter

manifest 和 Rust import 只有一个版本入口，避免应用与组件解析到两套 GPUI 类型。来源在
2026-09-28 回到 crates.io 精确 pin，lockfile 记录 registry checksum，deny.toml 不再放行
GPUI Kit 的 git 仓库。代价是 GPUI Kit
统一管理整套传递版本，升级必须作为单独变更重跑双平台构建、设置窗口、IME、辅助功能、缩放、
窗口重建和 shutdown smoke；ADR-0054 后“辅助功能 smoke”不再是项目自有 UI 完成条件。本 ADR 不把仍缺少实机证据的 UI TODO 标记完成。

Adr 0021 Signed Update Manifest (`docs/adr/0021-signed-update-manifest.md`) Copy Section

ADR-0021: Signed Update Manifest Trust Boundary

状态：已被 ADR-0029 取代（2026-09-13）

后续修订（2026-09-23）：本文已由 ADR-0029、再由 ADR-0034 取代。当前更新目标为 Windows x64、macOS aarch64 与 macOS x64；Windows 原生 ARM64 已由 ADR-0033 退役。

背景 Copy Chapter

BongoCat 将自动/手动更新列为首发行为，但旧版 updater 使用 HTTP endpoint、前端固定凭据和
旧 payload，不能进入新架构。下载和安装前必须先建立独立、可离线验证的信任边界；否则网络 client、
设置 UI 和高权限 installer 会各自解释版本、target、hash 或签名，形成不一致的安全判断。

Development 与 Production 构建也不能共享可变 channel。Windows 只支持 x64/ARM64，macOS 支持
Intel/Apple Silicon；Windows ARM64 在官方 desktop Cubism Core 可用前仍是发布阻塞，而不是由更新
manifest 绕过。

决策 Copy Chapter

• 新增平台无关且禁止 unsafe 的 bongocat-update crate。它只执行 manifest、签名、版本、target
  和 artifact 完整性验证，不联网、不写文件、不启动 installer，也不持有 runtime 或 UI 状态。
• manifest v1 使用严格 snake_case JSON 和 detached Ed25519 签名。客户端先对收到的原始 manifest
  bytes 执行严格验签，成功后才反序列化；未知字段、非 v1 schema、超过 1 MiB 或无效 JSON 均拒绝。
• manifest 固定包含 Development/Production channel、SemVer release、最低可升级版本、单调
  release_sequence、Unix 发布时间和 1 至 8 个 artifact。artifact 明确携带 target triple、arch、
  HTTPS URL、字节数和小写 SHA-256；只接受既定的四个 Windows/macOS target/arch 组合。
• verifier 由不可变构建环境、当前 target、当前版本、已安装 release sequence 和编译期信任公钥集
  构造。公钥以稳定 key ID、环境 channel 和 sequence 有效窗绑定；未知、跨环境、重复或超出轮换窗
  的 key 均拒绝。私钥不进入源码、构建产物或运行时配置。
• manifest sequence 低于已安装值，或新版本没有更高 sequence，视为降级攻击。当前版本低于
  manifest 的最低可升级版本时不尝试就地更新；相同或更旧版本只返回 up-to-date，不产生安装候选。
• 每个环境的最高已验证 sequence 由 bongocat-update::UpdateSequenceStore 从不可变
  StorageLayout 单独保存为 updates/update-sequence.json v1，不进入用户 config 或窗口 state 事务。
  状态固定包含 channel
  和最高 sequence；同目录锁串行化 writer，写入经同目录原子替换并回读验证。未知字段、非 v1、
  跨环境、符号链接、损坏或较低 sequence 一律失败关闭，绝不重置或覆盖已有状态。Unix 在创建或
  重开 updates/ 时强制 0700；Windows 继续以用户 profile ACL 作为同等私有边界。
• 验证成功只返回字段私有、只提供只读 accessor 的项目自有不可变 VerifiedUpdate/VerifiedArtifact。
  第三方 URL、SemVer、签名或 digest 类型不进入公共 API。下载层必须把流交回 VerifiedArtifact
  同时验证精确长度和 SHA-256，通过前不得进入安装阶段。
• UpdateVerificationSession 将 verifier 与当前环境的 sequence store 成对创建：打开时读取最高
  sequence，验签和严格 manifest 验证成功后才记录新 sequence；Available 与 UpToDate 都属于
  成功验证，并立即更新 session 的 rollback 下限。验证失败不得创建或推进 state；该 session
  不联网、不下载或启动 installer。
• 公共 schema 与 accept/reject fixtures 位于 shared/update/。签名传输 envelope、endpoint、下载
  恢复、OS 包签名、installer 权限与回滚属于后续独立 contract。

依赖与替换边界 Copy Chapter

• ed25519-dalek = 3.0.0（BSD-3-Clause）提供纯 Rust Ed25519 严格验签；关闭默认 zeroize feature，
  只启用 verifier 所需 fast 表。维护仓库为 dalek-cryptography，Rust 1.85+。
• sha2 = 0.11.0、semver = 1.0.28 和 url = 2.5.8 均为当前稳定版，许可证为
  MIT OR Apache-2.0，支持项目 Rust 1.97。它们分别只位于 digest、版本和 HTTPS 解析边界。
• bongocat-config 是同一 workspace 的平台无关依赖，只提供不可变的 StorageLayout 与
  BuildEnvironment，用于把更新 sequence 固定在当前环境的 updates/ 根；它不向 update
  verifier 暴露配置内容、平台 handle 或 UI 类型。
• 这些依赖均由 bongocat-update 封装；若停止维护，可替换实现而不改变 app/runtime/UI 公共协议。
  manifest 算法或字段变化仍需新 schema/ADR，不能在 v1 中静默替换。

验证 Copy Chapter

• 单元测试使用固定测试私钥覆盖有效签名、篡改、环境错配、公钥轮换窗、sequence 降级、最低版本、
  target/arch 错配、重复 target、未知字段、HTTP URL、artifact 长度/hash 和读取失败。
• Draft 2020-12 门禁验证共享 accept/reject fixtures；Rust 测试对同一 valid fixture 签名并解析，防止
  schema 与实现漂移。
• 完整 workspace 在 macOS、Windows 和 Ubuntu 执行 format、严格 Clippy、测试与 release
  check；dependency policy 继续覆盖许可证和 registry source。

后续边界 Copy Chapter

下一步建立环境绑定 endpoint 与 24 小时自动/手动检查调度，再实现有界下载、取消、临时文件清理、
平台 installer、操作系统签名验证和失败回滚。没有这些证据前不得声称更新功能或 stable 发布完成。

Adr 0022 Update Manifest Transport Envelope (`docs/adr/0022-update-manifest-transport-envelope.md`) Copy Section

ADR-0022: Update Manifest Transport Envelope

状态：已被 ADR-0029 取代（2026-09-13）

背景 Copy Chapter

ADR-0021 已固定签名 manifest 的离线验证边界，但尚未定义网络响应如何无损携带 key ID、detached
signature 和原始 body。让 HTTP client、设置服务或发布脚本各自选择 JSON wrapper、base64 或 redirect
策略会使待验签 bytes 产生歧义，也会把传输库类型带入信任判断。

决策 Copy Chapter

• manifest endpoint 只能经 HTTPS GET 获取，客户端不跟随 redirect，只接受 200 响应。endpoint
  自身继续由不可变环境发布配置提供，不能来自用户 config、CLI 或运行时输入。
• 响应 body 是不经 JSON 解析、字符转换、解压或重编码的 manifest 原始 bytes，最大为 1 MiB。
• bongocat-update-key-id header 携带最多 64 字节的 ASCII key ID，只允许字母、数字、-、_ 和 .。
  bongocat-update-signature-ed25519 header 携带恰好 128 个小写十六进制字符，代表 64-byte detached
  Ed25519 signature。缺失、过长或语法无效的 header 以稳定 update error code 失败关闭。
• transport adapter 只把有限 header 和精确 body 转为 UpdateManifestEnvelope。它不验证 manifest、写入
  sequence state、下载 artifact 或调用 installer；envelope 只可交给 ADR-0021 的 verifier/session。
• HTTP、TLS、代理、状态文本和 response 类型不离开 transport adapter。自动/手动调度、取消、下载与
  安装另行实现。

验证 Copy Chapter

bongocat-update 单元测试覆盖 envelope 的 body 上限、key ID/signature 编码拒绝、exact-byte 保留以及
通过 envelope 的验签路径。后续网络 adapter 必须补充真实 HTTPS、redirect、代理、非-200、截断和超限
body 测试。

后续边界 Copy Chapter

本 ADR 不选择 HTTP crate、Production endpoint 或公钥注入方式，也不授权下载、包签名、installer 权限或
回滚行为。

Adr 0023 Windows Per User Installer (`docs/adr/0023-windows-per-user-installer.md`) Copy Section

ADR-0023: Windows Per-User Installer

状态：已接受（2026-09-05）；NSIS toolchain 与 wrapper 边界已由 ADR-0033 取代（2026-09-14）

注（2026-09-14）：本 ADR 关于 per-user 安装、权限面、卸载语义与数据隔离的决策仍然有效。
以下内容已随 ADR-0033 作废，不要再据此实现：

• 由本项目维护 NSIS 脚本、固定官方 nsis-3.11-setup.exe 的 MD5、以及通过
  BONGOCAT_NSIS_SETUP_PATH / BONGOCAT_MAKENSIS_PATH 注入本机 NSIS 路径；
  安装器改由 cargo-packager 的 NSIS 模板与 install-mode 配置生成。
• "x86 不构建或发布，ARM64 在 Cubism desktop Core 门禁通过前不生成可发布 artifact"：
  Windows 现在只有 x64（ADR-0010 已更新）。
• "Windows packaging 仅接受已 Authenticode 签名的 payload"：新流水线在未配置签名
  身份时会生成未签名安装器并输出警告，签名验证降级为 release workflow 的显式门禁。
• "未来 Rust update helper 只接收 ADR-0021 验证完成的本 target/arch artifact"一句已随
  ADR-0029 作废：不再有独立 Rust update helper，替换由 self_update 1.3.0 在进程内完成，
  其权限边界、原子性与失败恢复未经本项目威胁建模。ADR-0021 已标记「已被 ADR-0029 取代」。

背景 Copy Chapter

BongoCat 已使用当前用户 HKCU Run 启动项、环境隔离的数据根和独立的签名更新 trust boundary。
Windows 首发仍需要固定安装格式，以便明确 installer 权限、卸载语义和未来 update helper 的交接。

决策 Copy Chapter

• Windows 首发采用 per-user NSIS installer。每个受支持 target/arch 生成独立安装 artifact；
  当前只有 x86_64-pc-windows-msvc。
• 安装器以当前用户身份安装，不请求管理员权限，不安装 service、driver 或机器级注册项；
  卸载元数据写在 HKCU。
• installer 升级只在固定 product root 内替换旧的 product files，避免遗留 binary。
• 安装、升级和卸载不能读取、导入、迁移或删除 Development/Production 的 config、window state、models、
  backups、logs 或 updates 数据。默认卸载只删除 product files；删除用户数据必须是独立且明确的
  用户操作。
• installer 不联网、不解析 update manifest，也不自行选择 artifact。NSIS 只作为安装 packaging
  tool，不承载 BongoCat 业务逻辑。

备选方案 Copy Chapter

• MSIX 会把启动、activation 与更新交由 package model，不能作为当前 HKCU Run 与进程内
  self_update 路径的无附加重构替代。
• WiX / MSI 主要服务机器级部署，通常引入管理员权限与企业安装策略；首发不需要该权限面。
  cargo-packager 的 wix format 因此不进入发布矩阵。

验证 Copy Chapter

后续 installer job 必须在干净 Windows 10 1903+ 与 Windows 11 用户 profile 验证安装、升级、卸载、
签名、环境数据保留、x64 artifact 选择和失败 rollback。这些证据尚未取得，不能宣称 Windows
package 可发布。

Adr 0024 Macos Tcc Capability Boundary (`docs/adr/0024-macos-tcc-capability-boundary.md`) Copy Section

ADR-0024: macOS TCC Capability Boundary

状态：已接受（2026-09-05）

后续修订（2026-09-23）：ADR-0054 退役了项目自有 AccessKit/AppKit 设置桥；Input Monitoring 与 Accessibility TCC 的边界仍然有效。

背景 Copy Chapter

BongoCat 需要在应用失焦时监听键盘和鼠标边沿，以驱动 BongoCat overlay；同时设置窗口必须向
VoiceOver 等辅助技术公开自身的可访问语义。两种能力不能因为都被 macOS 归入隐私或辅助技术领域而
混为同一项 TCC 请求。

决策 Copy Chapter

• 全局键盘、鼠标和修饰键监听只使用 Input Monitoring。bongocat-platform 仅以
  CGPreflightListenEventAccess 查询状态，并只在由用户发起的明确设置操作中允许调用
  CGRequestListenEventAccess；启动、轮询和服务恢复不得弹出请求或重复请求。
• listen-only CGEventTap、CGEventSourceKeyState 和 CGEventSourceButtonState 都属于上述
  Input Monitoring 用途。权限拒绝或撤销必须让输入服务进入匿名 PermissionDenied 状态并可靠 Reset；
  overlay、设置窗口和本地配置仍继续运行。
• 设置窗口的 AccessKit/AppKit adapter 只公开 BongoCat 自己窗口的可访问树和 action channel。它不
  读取、控制或自动化其它应用，不调用 Accessibility trust/prompt API，因此不得为此请求 Accessibility
  TCC 权限。
• NSOpenPanel、NSWorkspace URL 打开和 pasteboard wrapper 保持各自最小能力边界；它们不得借由
  Input Monitoring 或 Accessibility 状态扩大访问范围。
• Settings 必须分别显示 Input Monitoring 的当前状态和输入服务状态。状态变化只更新 snapshot/诊断，
  不把“已授权”表述为输入服务已经重启；重新启动输入服务仍必须经过显式、受控的 owner 生命周期。

验证 Copy Chapter

• 静态检查确认平台输入路径只使用 listen-event preflight/request API，AccessKit bridge 不链接或调用
  Accessibility trust API。
• macOS 实机矩阵覆盖未授权、拒绝、授权和撤销 Input Monitoring；确认不出现 Accessibility 提示，且
  拒绝时 overlay/settings 保持可用。
• 后续 TCC UI 刷新实现必须分别测试 permission snapshot 与 service status，确保授权变化不会被误报为
  已运行的 event tap。

引导流程与逐次重置（2026-09-30，ADR-0078） Copy Chapter

ADR-0078 把 macOS 的引导动作换成 permission-flow 的浮动面板，并在每次进入授权流程前执行
tccutil reset ListenEvent com.ayangweb.bongo-cat。本 ADR 的 Input Monitoring 边界因此有两处修订：

• 「只在由用户发起的明确设置操作中允许调用 CGRequestListenEventAccess」仍然成立，且引导流程
  整体位于用户点击之后，没有引入启动或轮询路径上的 TCC 请求。
• 但「不重复请求」的语义改变了：逐次重置会主动把已有授权清回未授权，因此用户每次进入引导都要重新
  授权。这是产品明确要求的行为，不是实现偏差。
• 「权限拒绝或撤销必须让输入服务进入匿名 PermissionDenied 状态并可靠 Reset」中，进入
  PermissionDenied 这一半已有覆盖（tap 被禁用 → 重启 → 进程内 CGPreflightListenEventAccess
  复查 → PermissionDenied），但重新授权之后没有自动重启输入服务的触发点：重置使运行中的
  tap 失效，用户重新授权后输入要等应用重启才恢复。这一缺口记录在 ADR-0078 的「未完成项」。
• 能力面保持最小：permission-flow 虽然暴露 8 类权限，但产品只使用 INPUT_MONITORING 一项，
  且其类型不离开 bongocat-platform 的私有 adapter。

Adr 0025 Signed Manifest Https Transport (`docs/adr/0025-signed-manifest-https-transport.md`) Copy Section

ADR-0025: Signed Manifest HTTPS Transport

状态：已被 ADR-0029 取代（2026-09-13）

背景 Copy Chapter

ADR-0021 和 ADR-0022 已定义离线验签及 HTTP envelope 字节协议，但没有实际 HTTPS client 时，
endpoint、redirect、压缩和 response-body 限制仍可能在后续 app 接线时被各自实现。尤其是 transparent
compression 会改变 detached Ed25519 signature 必须覆盖的原始 bytes。

决策 Copy Chapter

• bongocat-update 使用精确固定的 ureq 3.4.0 作为唯一 signed-manifest HTTPS transport。它只启用
  纯 Rust rustls feature，显式关闭默认 features，因而不启用 gzip、charset、cookie 或 proxy feature。
• UreqUpdateManifestSource 只接受 UpdateManifestEndpoint。endpoint 最多 2 KiB，必须是无 credentials、
  无 fragment 且具有 host 的 HTTPS URL；它来自后续不可变的构建发布配置，绝不来自用户 config、CLI 或
  运行时输入。
• 每次 fetch 只发送一次 GET，限制为 15 秒 global deadline，不跟随 redirect，且只接受 HTTP 200。
  response body 以 Read::take(1 MiB + 1) 有界读取，不进行 JSON/字符集/压缩处理；超过上限和空 body
  均通过既有 manifest_too_large verifier code 失败关闭。
• transport 只构造 UpdateManifestEnvelope，由其继续校验 key-ID/signature header。endpoint、status、
  transport 和 body-read 错误只公开固定匿名 transport code；底层 URL、HTTP status text、TLS 或 client
  类型不离开 update crate。调用方必须在专用 update worker 运行 blocking fetch，禁止在 GPUI executor
  执行。
• UpdateCheckCoordinator 只能以 UpdateManifestSource 取得 envelope，再调用既有
  UpdateVerificationSession。其顺序固定为 fetch -> signature/schema/target verification -> sequence
  store commit；任何 fetch 或 verification failure 都不能改变当前环境的 anti-rollback state。
• 同一受限 agent 还提供 artifact source，但它只可打开 VerifiedArtifact 已验证的 URL，固定 HTTPS、
  无 redirect、200，并只返回 raw reader 或既有 HttpStatus/Transport retry 分类。下载 coordinator
  继续独占重试、取消与 staging，artifact verifier 继续独占长度和 hash 校验。

依赖与替换边界 Copy Chapter

ureq 3.4.0 为 MIT OR Apache-2.0、Rust 1.85+ 的公开维护 crate。它是纯 Rust blocking client；只在
UreqUpdateManifestSource 私有字段出现。若维护或安全边界不再满足要求，可替换该 source，不改变
UpdateManifestEndpoint、UpdateManifestEnvelope、verifier、runtime 或 UI contract。

验证 Copy Chapter

• 单元测试锁定 HTTPS/credential/fragment/长度 endpoint 边界、HTTPS-only、no-redirect agent config 和
  transport code 唯一性。
• 注入式 source 回归验证通过时仅写入验证后的 release sequence，而 source failure 后 sequence 保持不变。
• workspace 的 format、strict Clippy、test、release check 与 dependency policy 覆盖新 crate graph。
• 后续 app-owned worker 必须在真实 HTTPS endpoint 验证断网、代理、redirect、non-200、截断、超限、
  签名错误和降级攻击，且不影响本地 overlay。

后续 Copy Chapter

本 ADR 不选择 Production endpoint 或公钥，不实现 UI command、自动/手动 dispatch、installer 或 rollback。
它们仍需要各自的发布基础设施与安全验收。

Adr 0026 Update Helper Replacement Boundary (`docs/adr/0026-update-helper-replacement-boundary.md`) Copy Section

ADR-0026: Update Helper Replacement Boundary

状态：已被 ADR-0029 取代（2026-09-13）

背景 Copy Chapter

ADR-0021 至 ADR-0025 已将 manifest、artifact URL、下载和 staging 限制为不可变、已验证的
项目类型。它们不授权网络 worker、GPUI 或 installer 写入正在运行的 product files。若将这一
边界隐含在后续 helper 中，path substitution、部分替换、权限扩大和 rollback 降级都会绕过已有
的签名与 anti-rollback 结论。

威胁模型 Copy Chapter

• 不可信输入包括 update endpoint、manifest transport、artifact bytes、staging directory contents、
  product directory contents、环境变量、当前工作目录和用户可修改的 registry/launch arguments。
• 可信输入只包括编译进当前 app 的环境、target/arch、trust key、当前 installation root，和由
  VerifiedArtifact 只读 accessor 传递的 release identity、精确长度、digest 与 staging file。
  私钥、endpoint 配置和任意用户配置均不进入 helper。
• helper 与 app 同为当前用户权限；它不得请求 elevation、安装 service/driver、写入 HKLM、修改其他
  用户 profile，或以 Development/Production 用户数据目录作为 product replacement source/target。
• 被攻击者替换、删除或锁定的 app/helper/staging file 必须导致失败关闭和保留已知可运行 product，
  而不是重试到另一路径或启动未知 binary。

决策 Copy Chapter

• update helper 是独立、平台限定的 Rust owner，不属于 bongocat-update、runtime 或 GPUI。它只在
  app 完成 shutdown coordinator 的停止 frame tick、输入、runtime、config flush、audio/renderer/overlay
  release 后启动；app 必须等待 helper acknowledgement 或将本次更新报告为未安装。helper 不接受裸
  URL、manifest、target、版本、安装目录或 shell command-line replacement request。
• 调用方传入的 installation root 必须等于平台固定的 current-user product root。Windows 为
  $LOCALAPPDATA\Programs\BongoCat，macOS 为当前已签名 .app bundle；helper 在写入前重新解析
  root、拒绝 reparse point/symlink/非目录和任何与当前 target/arch 不一致的 payload。它绝不从
  StorageLayout 的 config、state、models、backups、logs 或 updates root 导出安装路径。
• helper 只接受同一环境 UpdateDownloadCoordinator 完成的唯一 staging file，重新检查 regular-file
  identity、所有权、无 link、精确 byte length 与 SHA-256，并执行对应 OS package signature/integrity
  verification。解包后的每个 product file 必须保持在 private same-volume work directory，拒绝 link、
  absolute path、path traversal 和已有 uninstaller；不允许把 archive entry 直接写入 product root。
• 替换采用 prepare -> validate -> commit：先在 product root 同卷创建全新的 private candidate directory，
  验证 candidate 的 target/arch、required resources、OS signature 与 executable launchability；再将
  current root 原子重命名为唯一 rollback directory，将 candidate 原子重命名为 current root。任何
  prepare/validate/commit failure 都不得删除 current root。commit 后 launch failure、health timeout 或
  explicit failure acknowledgement 必须在同一 helper invocation 内将 rollback directory 原子恢复；成功
  acknowledgement 后才删除 rollback directory。
• 同一 installation root 一次只允许一个 helper。lock/pid ownership 失效、父进程未退出、超时、unexpected
  child process 或 ambiguous recovery state 都停止替换并保留可诊断的 anonymous failure code。下一次
  launch 仅可在验证 current/rollback 两个固定 sibling 的签名与 target 后恢复其中一个；不得猜测、
  merge 或扫描其他目录。
• helper 不联网、不解析 JSON、不检查更新、不记录 URL、路径、按键、artifact 内容或签名材料。日志只记录
  stable replacement phase/error code、environment、target 和 release sequence；其保留策略服从应用
  diagnostics contract。Windows NSIS installer 继续只用于初始/显式 per-user packaging，不成为
  background update executor。

验证 Copy Chapter

• 平台 contract tests 覆盖拒绝裸输入、root/staging link substitution、path traversal、cross-environment、
  cross-target、invalid signature、concurrent helper、parent alive、prepare failure、atomic commit failure、
  launch/health failure rollback 与成功后 cleanup。
• Windows 10 1903+ 和 Windows 11 以非管理员 profile 验证真实 Authenticode、lock、upgrade、rollback、
  uninstall 后无残留和 Development/Production 数据保留；macOS 12+ 验证 signed/notarized bundle、
  quarantine、rollback 和 data preservation。
• 断电/kill fault injection 在每个 prepare/rename/acknowledgement 点重启，断言只会启动完整已验证的
  current 或 rollback product，且 never deletes user data。

后续边界 Copy Chapter

本 ADR 不实现 helper、OS signature verification、archive format、health protocol、endpoint、公钥或
release hosting。每个实现需要独立平台代码、自动化与实机证据；在上述验证通过前，更新安装和 stable
发布仍不可宣称完成。

Adr 0027 Diagnostics Preview Bundle Boundary (`docs/adr/0027-diagnostics-preview-bundle-boundary.md`) Copy Section

ADR-0027: Diagnostics Preview Bundle Boundary

状态：已接受（2026-09-06）；2026-09-24 由 ADR-0064 修订 application event 输入与输出格式

后续修订（2026-09-23）：ADR-0054 后设置 UI 不再以 AccessKit 语义作为当前契约；本文的 “AccessKit 语义”验收应理解为当时的历史证据，当前改以可见文案和 typed result 为准。

背景 Copy Chapter

ADR-0016 定义的 diagnostics.json 是当前环境内原子写入的匿名摘要。它足以显示
runtime、输入、配置和日志 owner 的聚合状态，但不能让维护者查看有界的应用生命周期 code
历史。直接复制 logs/ 的所有内容不可接受：Cubism Core 的 message 不能被当作稳定、无用户内容
的记录，文件名、路径和未来日志 owner 也不能隐式进入导出。

决策 Copy Chapter

• 预览包是当前不可变环境 logs/ 中的固定 diagnostics-preview.zip。它是 format version 1 的
  ZIP container，内容路径固定为 manifest.json、diagnostics.json 和
  application-events.log；archive entry 不携带宿主绝对路径、环境根、时间戳、模型 ID 或任意
  user-provided name。
• package writer 只枚举严格的 application-YYYY-MM-DD.log 与
  application-YYYY-MM-DD.<generation>.log 普通文件，并使用 bongocat-log 的共享严格文本 parser
  验证固定宽度 UTC timestamp、level、module、stable code、message 与有界 context 语法。历史 JSONL
  与 cubism-core-*.log 不是 application event 来源，也不会触发兼容 reader。
• 每个 code 必须来自 app-owned 闭合 catalog，module 必须与 code 的固定 component 相等，level
  必须与 code 的固定 severity 相等。任一记录未知、损坏、UTF-8/大小/普通文件检查失败时，整份来源
  文件跳过并增加匿名 skipped_source_files；不从部分文件复制记录。目录本身无法枚举则整个导出
  失败关闭，不伪装成空 preview。
• 重写后的每条 event 固定为 <LEVEL padded> [<module>] <code>\n。输出不包含源 timestamp、固定或
  动态 message、context、原始行、来源路径或模型身份；因此 application-events.log 既保留旧版
  component/level/code 的可读性，又不会把日志正文或用户邻近数据复制进 support bundle。
• Cubism Core 原始 .log 文件和 Core message 永远不进入预览包。Core 的 retained-file/byte 与
  written/dropped/rotated/pruned 聚合值继续只由 ADR-0016 的 diagnostics.json 表示。未来若要导出
  Core 历史内容，必须先定义可证明的固定结构和新的 ADR，不能复用路径关键词清洗作为授权。
• ZIP 在当前环境 logs/ 下以私有同目录 staging file 创建，完成所有 entry 的大小、数量和结构验证
  后 flush/sync_all 并原子替换目标。取消、解析、写入、同步或替换失败必须删除本次 staging，
  保留上一份有效 preview；Unix 目录/文件分别恢复 0700/0600，Windows 使用当前 profile ACL。
• package format 继续是首版 v1；在首版发布前字段可直接同步调整 manifest、writer、
  fixture 和测试，不添加任何兼容 reader 或 migration。首版发布后才为不兼容演进建立新的 versioned
  format 与 ADR。
• UI executor 只调用 typed export command。UI 显示 stable result code、format version、entry count
  和 bytes，不直接枚举日志或解压 archive；失败不得显示 OS text、路径、archive entry 或日志正文。

验证 Copy Chapter

• unit tests 覆盖 active/rotated 固定文件名、固定 entry 名称、严格 text record reserialization、
  全部 catalog code、unknown/mismatched module/level/code、malformed timestamp/delimiter、整文件跳过、
  旧 JSONL/Core 排除，以及路径/context/message/时间戳不进入输出。
• transaction tests 覆盖成功原子替换、parse/write/sync/replace failure 清理、已有 preview 保留、
  symlink/non-regular source 拒绝、目录枚举失败和 Development/Production 目录隔离。
• settings/UI contract tests 覆盖 typed result、pending/error/retry，不显示动态 path 或 archive 内容。
  Windows/macOS release smoke 验证 owner-only storage、真实 application event 重写和预览包可由系统
  工具打开，但不需要把原始日志上传或读回产品 runtime。

后续边界 Copy Chapter

本 ADR 不实现 remote upload、Core history export 或 support endpoint。具体 archive writer lifetime
必须在实现提交中记录；在完整验证前，Phase 7 日志导出门禁保持未勾选。

首个 writer 使用 zip = 9.0.2（MIT，zip-rs/zip2，Rust 1.88+），精确 pin 且关闭默认 feature，
只写标准 Stored entries；它不提供 encryption、compression 或 archive extraction。替换边界是同样
能在双平台写出并验证此固定 v1 ZIP entry 集合的维护中 Rust crate，不能改变本 ADR 的隐私/原子性约束。

Adr 0028 Rust I18n Catalog Structure (`docs/adr/0028-rust-i18n-catalog-structure.md`) Copy Section

ADR-0028: Rust i18n catalog structure

状态：已接受（2026-09-10）

背景 Copy Chapter

BongoCat 最初把所有文案放在 ui.* 扁平 key 下。随着设置、模型、快捷键和诊断页面
增加，这种命名无法表达页面上下文，也让相同词语在不同语义下被误复用。rust-i18n 会在
编译期把嵌套 JSON 展平为查找路径，因此可以同时获得可读的源文件层级和稳定的运行时 key。

调研结论 Copy Chapter

• Zed 的桌面 UI 资源按产品域和页面区域组织，状态与
  操作不是一个无意义的 common 大对象。
• Joplin 的 locale 资源强调稳定语义标识和参数契约，
  复数/参数消息与页面结构分离，便于翻译工具和校验脚本处理。
• Nextcloud 的大型桌面/服务界面
  以功能上下文维护消息，避免把视觉组件名称作为 key；同一文案只有在语义确实相同才复用。
• KeePassXC 的桌面对话框
  和菜单动作按交互上下文组织，说明按钮、菜单项和错误提示需要稳定的领域归属，而不是泛化
  的 label/text。

这些项目没有被直接照搬；BongoCat 根据自己的页面和 runtime 状态建立独立目录。

决策 Copy Chapter

locale 文件保留根级 _version: 1，所有叶子 key 使用 snake_case，并按以下顶层领域组织：