主题

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

Astro site 用于标记把 Astro 作为 public/static site 交付面的项目。它不等同于“整个仓库都是 Astro 应用”：在当前代表项目里，Astro 负责面向读者的 public content rendering 和 static export，而 admin SPA、gateway、API 或 legacy runtime 由其他边界承担。关键证据通常包括 astro.config.

Async embedded 表示嵌入式 Rust 代码把 async 当成正式 API surface 或正式 runtime contract 来维护，而不是只在某个样例里顺手用了异步。

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 的工程形态，而不是简单的语言标签。

Config-driven ops 表示操作命令、硬件目标、端口、artifact、backend 或运行策略优先通过 checked-in 配置声明，而不是让维护者每次手写临时命令。它适合 MCU flashing、服务端口、部署资源和多 Agent 协作场景。

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 的核心是设备级知识不能被某一个技术栈吞掉。

Display driver 表示项目围绕显示控制器驱动建立了稳定的可复用模式，通常是面向 LCD/OLED/controller 的驱动 crate，或在产品固件中把显示驱动视为独立维护边界。这里的重点不是“有屏幕”，而是显示控制器交互本身已经成为长期维护契约。 这个 Topic 关注显示控制器层，而不是更高层的 UI/graphics 语义。

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

Dockerized dev 标记 Dockerfile、Compose 或 container build 是本地开发、集成验证或部署交付的一等路径。它不表示“仓库里偶然有 Dockerfile”，而是 Docker 影响运行环境、数据卷、端口、build args、嵌入式前端产物或 release artifact。

EdgeOne Makers static-site deploy 指仓库把静态站点构建结果作为单一 publish artifact 交给 GitHub Actions，再由 workflow 用 npx edgeone makers deploy 持续发布到 EdgeOne Makers 的 direct-upload project。

Embedded admin UI 表示 operator/admin UI 不是独立部署的前端产品，而是主服务交付物的一部分，通常由同一个 release binary、同一个镜像或同一个部署单元一起提供。这里的重点是交付和边界耦合，而不是框架选型。 这个 Topic 用来回答“控制台为什么要随服务一起发、一起验、一起部署”。

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、测试方式和下游组合方式。

Embedded Rust 表示 Rust 代码运行在 MCU、driver、firmware 或硬件 bring-up 环境中，通常涉及 no_std、Embassy、esp-hal、STM32/ESP32、probe-rs、espflash 或 embedded-hal。它不是所有 Rust 项目的泛化标签。

Embedded USB control plane 表示把 MCU 的 USB CDC / USB Serial-JTAG 当成本地设备控制面，而不是普通调试串口。它要求运行态控制协议、设备身份、日志/trace、secret 脱敏、串口 ownership，以及 flash/reset/monitor 等生命周期操作被同一个本地 owner 模型管理。

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

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

GitHub Actions CI performance 表示把 CI 当作一个由触发器、DAG、runner 准备、编译、fixture、测试层级、产物传递和质量门禁共同组成的系统来优化。

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 上”。

macOS app 指交付物是原生 macOS 图形应用，仓库需要长期处理 app bundle、平台工具链、桌面运行行为和 macOS 特有能力，而不是只有一个能在 macOS 上运行的 CLI。这里真正重要的是应用外壳和平台契约：如何构建 .app、怎样运行 dev/prod variant、何时接入 Keychain、文件访问与本地状态如何管理，以及后续是否能顺利走到签名、打包或分发（projects/televy-backup.

macOS Launch Services window handoff 指这样的原生 macOS 应用行为合同：用户从 Finder、Dock、Spotlight 或其他正常 Launch Services 入口再次启动一个已经运行的 app 时，系统把请求交给已有进程；已有进程复用 retained presenter 和 retained primary user window，将它恢复并前置，而不是创建第二个进程或第二个窗口。

Manual version release delivery 是一种可复用的发布交付合同：维护者显式选择或确认一次 release target，系统再用可插拔的 Version Policy 校验版本、绑定 source identity、完成 reservation、经过 PR 与质量门禁、创建显式 Release，并让部署与 recovery 复用该 identity 下对应的不可变产物。

Markdown style 定义 Markdown 源文件的正文排版、格式化和 Git 自动修复惯例。默认每个自然段保持一行，使用 Markdown 语法表达必要的结构；软换行由官方 formatter 合并，显式硬换行保留语义。它提供可重复的源文件样式，而不是要求作者按固定字符数拆分内容（dprint.json、docs/specs/markdown-style/SPEC.md）。

MCP server 表示仓库主要交付一个 Model Context Protocol 服务面，供 agent/client 通过 MCP 调用工具、资源或相关能力。这里的重点不是“有 HTTP API”，而是协议层契约、工具语义和上游/下游映射。

MCU flashing integration 表示项目通过 espflash 管理 ESP32 系列，通过 probe-rs 管理 STM32/其他 probe-supported MCU，并把这些 backend 接入项目配置或明确的本地操作入口。Topic token 使用可复用工程模式命名；espflash 与 probe-rs 作为具体工具名放在定义和证据里。 这个 Topic 关注的是“硬件操作入口可复现且可审计”。

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

Native macOS visual evidence 是一套把原生 macOS 应用的 owner-facing 窗口截图当作可审计交付物的合同。它要求截图来自当前源码构建并运行的真实 .app，并且可以沿着 PID、bundle identifier、Accessibility role/title 语义和唯一 WindowServer window ID 回溯到目标窗口；PNG 只是证据载体，不是验收本身。

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

Ops tool 表示项目的核心价值在于运维自动化本身：部署、升级、监控、编排、设备管理、触发器或共享工作流，而不是面向终端用户的业务功能。这里的主语是“帮维护者安全地操作系统”，不是“恰好带个管理后台”。 这个 Topic 用来回答一个问题：系统真正的产品是不是一套可复用的操作能力。

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 是程序写入后会被同一程序或后续程序版本继续读取的状态，不限于关系数据库：文件、对象、消息、设备配置、嵌入式存储或其他跨版本数据都在范围内。

Playwright e2e 指仓库把真实浏览器里的关键用户流程当成正式质量门禁，而不是“顺手写了几条页面脚本”。它强调的是产品行为验证：路由、认证、交互链路、浏览器 API、嵌入式控制台或多 runtime 页面组合，必须在接近真实使用路径的浏览器环境里被证明可用（projects/blog-26.md、projects/proxy-broker.md、projects/octo-rill.

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

PR label release 是逐 PR 的产品发布协议：PR labels 只提供经过 gate 验证的发布操作与发布阶段；最高的合格 final vX.Y.Z Git release tag 是唯一数字版本基线，VERSION 只锁定 trusted preparation 已决定的精确产品版本。label 不能计算、覆盖或为版本提供 fallback。

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 等入口体现。

Quality gates 表示仓库把“什么叫可以合并、什么叫可以发布”写成了显式、可审计的契约，并通过本地脚本、CI workflows、review/signature policy、GitHub required checks 或同类机制把它执行出来。它关注的是 gate contract，而不是某一门具体技术。 这个 Topic 用来回答“仓库怎样防止低质量或不完整的改动穿过默认分支”。

React app 标记 React 是主要用户界面、管理台、控制台或嵌入式操作面 runtime。这里关心的是 route、component tree、client state、表单流、dashboard 交互和前端构建后的真实运行边界，而不是“项目依赖里有 React”。 这个 Topic 用来回答“用户实际操作的是不是一个 React runtime，以及它在系统里承担什么职责”。

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

Release failure notification 指一个仓库为所有“预期成功但最终以 failure 结束”的交付 workflow 建立显式、可审查的告警路径。范围包括 release、deploy、CI、Docs Pages 和 required gate，但必须由 checked-in allowlist 声明；成功、skipped、cancelled 和通知 workflow 自身不属于通知条件。

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 web service 表示 Rust binary 承担长期运行的服务职责：提供 HTTP API、proxy、SSE、docs/data service、admin backend 或 ops daemon，并对外暴露稳定的网络、存储和部署边界。这里的关键词不是“Rust”，而是“服务进程”。 这个 Topic 不只是“语言是 Rust”。

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 的受约束投影。

SemVer change governance 是一套可选的 house policy，用于在 owner 明确要求时分类一个 compatibility scope 对 public API 与 persistent state 合同的版本影响。

Service ports 表示端口号、bind 地址、dev/prod 暴露方式和多组件端口分工本身就是仓库的稳定 contract。它不是“服务都会有端口”这种空泛事实，而是说端口设计会直接影响本地预览、反向代理、权限边界、自动化脚本和故障排查。 这个 Topic 关注的是端口作为系统边界的那一面。

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 共同构成组件约定。

SQLite 表示项目把 SQLite 作为默认持久层、ledger、audit log、content/settings store 或低运维 embedded database，并围绕它建立路径、schema、迁移、volume、备份和运行时 ownership 约定。它不是“依赖树里有 sqlite”这么宽，而是数据库文件本身已经成为系统 contract 的一部分。

STM32 firmware 表示项目把 STM32 系 MCU 作为正式固件目标来维护，并围绕工具链、.ioc 硬件配置、刷写后端、板级职责和与其他 MCU/外设的分工建立了稳定契约。这里的主语不是“用了 STM32”，而是 STM32 固件在系统中的角色。

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

Storybook component QA 表示仓库把 Storybook 当作组件级文档、状态枚举、视觉检查或 interaction smoke 的稳定入口。它不等同于 Storybook accessibility：只有项目明确引入 a11y addon 或等价 Axe sweep 时，才同时打 accessibility Topic。这个拆分用于避免“只要有 Storybook 就叫 a11y”的误判。

System design docs 指仓库把系统级设计文档本身当成长期真相源，而不是把关键决策散落在 PR 讨论、Issue 评论或脑内记忆里。这里的“系统设计”不只指架构图，也包括硬件行为文档、质量门禁、控制面边界、设计取舍和后续实现必须服从的 current truth（projects/mains-aegis.md、projects/style-playbook-skills.md）。

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

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

TypeScript web 表示项目把 TypeScript 作为一个或多个 Web surface 的主语言，并围绕它建立 workspace scripts、typecheck、bundler、lint/format、env contract 和前端构建门禁。这里的主语不是“仓库里出现了 .ts 文件”，而是 TypeScript 已经决定了维护者怎样启动、构建、校验和交付实际 Web surface。

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

USB PD 表示仓库围绕 USB Power Delivery 协议或 PD-aware 固件/驱动维护代码，并把协商档位、controller 行为、sink/source 语义、PPS/AVS 等供电协商边界当成长期知识。这里的主语是供电协商协议，不是 generic embedded I/O。

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

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