主题

Application icon 记录的是一个产品在安装、主屏、任务栏、Dock 或浏览器应用窗口里被识别时所使用的图标 contract。它区分产品的原始 mark、给普通上下文使用的 regular any icon、可被平台裁切的 maskable icon、Apple touch icon，以及原生 app bundle 图标；它不把这些角色混成一张“看起来像应用图标”的 PNG。

Battery management 表示仓库主要处理充电、监测、保护或电池状态管理相关 IC/固件边界，并把这些语义当成长期维护契约，而不是普通传感器读写。这里的主语是电池系统安全和电源行为，不只是某个 I2C 设备。 这个 Topic 的关键是把“配置一个寄存器”与“改变充放电/保护语义”区分开。

Browser automation 表示真实浏览器不是测试工具，而是产品/运维工作流的一部分。仓库需要直接处理浏览器身份、challenge、邮箱验证、代理环境、headless/headed 切换和运行诊断，因此浏览器本身就是 runtime contract。 这个 Topic 和 Playwright e2e 不同。后者是质量门禁，Browser automation 则是在生产性自动化里把浏览器当执行引擎使用。

Browser userscript 表示交付物不是网站或浏览器扩展，而是运行在用户浏览器上下文里的用户脚本，例如 Tampermonkey/Violentmonkey 脚本。这里的重点是宿主页面、metadata、权限和 DOM 耦合，而不是常规 Web app 结构。

C firmware 表示仓库以 C 为主要固件实现语言，并围绕 Make/CMake、板级目录、手写 bring-up 文档和硬件资产协同建立了稳定维护方式。这里关注的是 C firmware 的工程形态，而不是简单的语言标签。

DC fan speed control 表示项目明确采用两线 DC 风扇的模拟调压控制模式，而不是直接把 PWM chopping 当默认方案。典型实现是 PWM -> RC 滤波 -> 注入可调 LDO 反馈网络，再配合独立 EN 和可选 tach 反馈，把“风扇供电轨”作为一个可调模拟系统来维护。 这个 Topic 的重点是控制策略和电路语义，而不是“有风扇”这么宽。

Developer utility 表示仓库的价值主要来自一个窄而高频的开发者/运维者工具循环，而不是完整产品面。它通常解决重复、繁琐、容易出错但又不值得手工反复做的小任务。

Device mono-repo 表示一个仓库同时承载硬件资料、固件、Web/desktop UI、docs/specs、测试工具或发布流程。它强调边界协调：硬件、firmware、UI 和文档互相影响，不应把仓库当作单一应用。 这个 Topic 的核心是设备级知识不能被某一个技术栈吞掉。

Distributed system 在这里指“系统行为依赖多节点协同、复制状态或集群控制面”的工程模式，而不是“仓库里有几个服务”这么宽。真正命中这个 Topic 的项目，通常存在 cluster-wide desired state、节点成员关系、复制日志、leader/follower 语义、局部 runtime reconcile 和网络分区后的恢复问题；维护者必须同时考虑单节点局部行为与跨节点一致性（projects/xp.

Embedded device control plane 表示设备把 ESP32-S3 作为正式控制面 MCU，并依赖其板载 USB 与 Wi‑Fi 同时承载本地与局域网控制入口。这里的主语不是“某一种传输协议”，而是 devd、CLI、Web App、可选 desktop/local agent、Web Serial 与 native USB 如何围绕同一设备事实、安全边界、发现机制、连接 ownership 和运行态协议协作。

embedded-hal driver 表示一个 crate 的主 API 明确建立在 embedded-hal trait 生态之上，目标是被其他 firmware 或 board-support 代码组合进系统，而不是自己成为整机应用。这里的核心不是器件名，而是“驱动 crate 的复用边界”。 这个 Topic 关注的是 crate API 形状、trait 依赖、feature flags、测试方式和下游组合方式。

ESP32 firmware 表示项目把 ESP32 家族 MCU 作为正式固件目标来维护，并围绕 toolchain、烧录、板级职责、连接能力和与其他 MCU/上位机的分工建立了稳定约定。这里的重点不是“芯片型号”，而是 ESP32 在系统里承担什么角色。 这个 Topic 往往不只是单片机源码。

Floating UI tooltip 表示 tooltip/气泡说明已经被当成正式交互层来维护，而不是临时 title 文本。这里默认采用 @floating-ui/react 一类定位中间件，处理视口避让、箭头、滚动更新和交互稳定性，而不是手写定位魔法。

GitHub Actions scheduling 表示仓库把 workflow 触发事件、并发 namespace、cancel-in-progress 和 required check 可见性组织成可审计的运行调度合同。目标不是让每个事件只跑一次，而是让当前 PR head 获得正确且可观察的 gate，同时不让无关 PR、main、deploy 或手工任务被同一个并发键误取消。

GitHub reusable workflow 表示仓库把 GitHub Actions 逻辑做成 workflow_call 可复用单元，供其他仓库以薄 caller workflow 调用。它关注安全边界、inputs/secrets contract、template rollout 和多仓库维护成本。 这个 Topic 不等同于“有 GitHub Actions”。

I2C 表示总线本身就是项目的主要维护边界之一，仓库需要持续处理地址、寄存器读写模式、mux/switch/expander、shared bus ownership 或 async/sync 访问策略。这里的重点是 I2C 作为协议/总线契约，而不是“芯片刚好挂在 I2C 上”。

Monitoring dashboard 表示一套面向长期运行服务的观测集成：应用从真实 source event 产出有界、低基数的 Counter、Gauge 和 Histogram，Prometheus 负责抓取与时间序列历史，Grafana 通过仓库内 provisioning 提供固定 dashboard、查询和告警；Docker Compose 或等价编排负责把应用 exporter、Prometheus、Grafana...

Next.js app 在当前 playbook 中表示 Next.js 仍承担项目的 current runtime、API、preview 或 compatibility surface。它不一定意味着整个项目是纯 Next.js；在 Ivan 博客项目中，它是 legacy internal runtime，与 Astro public site 和 React admin SPA 共存。

PCB assets 表示仓库把 PCB 设计文件、板级资产或硬件工程输出当成真相源之一来维护，而不是只把它们当附件。这里的重点是电路板资产与固件/文档的同步关系，而不是“仓库里有几个截图”。 它通常会和 C firmware、Device mono-repo 一起出现，但不替代这些 Topic：PCB assets 解释板级资产的维护边界，其他 Topic 解释固件或设备整体结构（projects/whisker-breeze.

Persistent-state migrations 是主人确认的 house policy，管理 durable state 在程序版本之间的迁移、兼容性、rollout、验证与恢复。durable state 是程序写入后会被同一程序或后续程序版本继续读取的状态，不限于关系数据库：文件、对象、消息、设备配置、嵌入式存储或其他跨版本数据都在范围内。

Power management IC 表示仓库主要维护电源转换、调压、监测或供电控制类芯片的驱动边界，并把这些电源语义当作独立主题来维护。这里的主语不是 generic embedded 外设，而是会直接改变供电行为的 PMIC / buck-boost / regulation 类器件。

Progressive web app 在这套 playbook 里不是“网页顺手带个 manifest”的统称，而是“把一个 Web surface 当成可安装应用去维护”的工程模式。

Project docs site 指项目在工程仓库内维护一个独立的 web 文档站点，通常以 docs-site/、docs-pages.yml 或等价 publish workflow、docs:build / build-docs-site、DOCS_PORT 等入口体现。

README content contract 是面向项目入口文档的可审查规范：README 先让目标读者理解产品、边界和下一步，再提供可复现的 Quick Start、集成 contract、交付语义、文档真相源、许可证入口、有限产品 preview，以及有来源的 Logo 和 Badge 入口。

Responsive web UI 指界面把不同视口下的可用性当成正式交付契约，而不是“桌面版做好后再缩一缩”。它关注的是布局、信息层级、交互方式和状态可读性如何在手机、平板和桌面之间持续成立，尤其适用于密集控制台、嵌入式运维界面和需要长期使用的工具型 Web UI（projects/dockrev.md）。 它与 React app、Embedded admin UI、Floating UI tooltip 常同时出现，但边界不同。

Rust application 指 Rust 是主执行面之一，交付物直接面向终端用户或操作者，而不是仅作为库、后端服务或固件组件存在。这里关心的是“应用如何被构建、运行、打包、调试和支撑用户工作流”，包括桌面 app、带 Web UI 的 hybrid app，或强用户导向的本地工具（projects/display-ambient-light-desktop.md、projects/televy-backup.md）。

Rust crate release 是 Rust library crate 发布到 crates.io 时的媒介合同：一个明确的源码版本必须先通过 manifest、package 和 dry-run 检查，再以同一 source SHA 形成 crates.io package、不可变 Git tag 和 GitHub Release 三面一致的 release unit。

Rust source quality 指把 Rust 源码的可读性、结构边界和 lint 可执行性写成可重复运行的 contract。它至少区分格式化、语义 lint、源码结构检查和 target/features coverage，并把每一层绑定到仓库内可运行的命令、配置或 checker，而不是把“能编译”当成质量结论（projects/flux-purr.md、data/topics/rust-source-quality.

Rust workspace 指仓库通过 multi-crate workspace 明确拆出 domain、daemon、CLI、平台壳层或共享库边界，并把这种拆分当成长期维护契约，而不是一时为了方便 cargo 命令。这里关注的是 crate 之间的职责分工、共享代码如何流动、哪些能力应该被隔离，以及 workspace 结构怎样支撑后续测试、打包和演进（projects/televy-backup.md）。

Same-repository Homebrew Cask release 指产品仓库同时承担产品源码、稳定 Release 产物和 Homebrew Tap 的一部分职责，并把 GUI Cask 作为稳定 Release metadata 的受约束投影。

shadcn/ui 表示项目采用官方 shadcn/ui 风格的 checked-in component layer：components.json、@/components/ui aliases、Radix primitives、Tailwind utilities、class-variance-authority、tailwind-merge、clsx 和 Lucide icons 共同构成组件约定。

Storybook accessibility 表示 Storybook 不只是组件展示，还明确引入 a11y audit 能力，通常是 @storybook/addon-a11y 或等价的 browser-backed Axe sweep。它关注 story-level 可访问性信号，例如对比度、ARIA 基础错误、表单语义和交互状态，而不是泛化的 Storybook 文档能力。

Tauri desktop app 指 Rust 原生侧与 Web UI 前端通过 Tauri 组成同一个桌面产品，二者共同构成交付面。它不是单纯“桌面端套个网页壳”，而是要长期维护 Rust 系统能力、前端交互层、桌面打包和两侧桥接 API 的工程模式（projects/display-ambient-light-desktop.md）。

Touch controller 表示仓库主要维护触摸控制器 IC 的驱动边界，把触点采集、事件语义和总线交互当成独立可复用模式来处理。这里的重点不是“有输入设备”，而是触摸控制器的读数和事件模型本身。

UI version display 指产品有意识地把“当前运行的到底是哪一版”暴露给用户或操作者查看，而不是把版本号藏在构建日志或开发者工具里。它通常包含一个稳定的人类可读显示位点，以及一条由运行时或构建链提供的版本真相路径，用于支持排障、远程协作和发布确认（projects/codex-vibe-monitor.md、projects/dockrev.

Web demo 表示仓库刻意提供一个可直接给 owner、评审者或潜在用户体验的 Web 演示面，而且这个演示面复用正式产品前端与正式路由，而不是单独做一套只用于截图的 demo 页面。它允许用 mock backend、simulation device、read-only seed data 或等价安全输入来稳定复现产品行为，但默认不要求接入真实生产登录、真实后端写路径或真实硬件危险写操作。

Worktree bootstrap 表示仓库把 linked worktree 的“首次进入可开发状态”当成正式 contract 来维护，而不是依赖维护者记忆、散落且无统一入口的手工 checklist，或假定只有主工作区才值得被照顾。