Mains Aegis
Mains Aegis 是 UPS / power-management 设备 mono-repo：它把硬件行为文档、ESP32-S3 固件、Web 管理界面、docs-site、前面板/音频预览工具和质量门禁放在同一个维护边界里。PRODUCT.md 明确把 Web 管理界面定义为面向多设备 UPS 的只读运维控制台，首要目标是让维护者快速判断设备健康、离线、后备供电和告警状态，而不是做可写控制台。
- System design docs
- Device mono-repo
- Embedded Rust
- TypeScript web
- Web demo
- Quality gates
- MCU flashing integration
- Embedded USB control plane
- Embedded device control plane
- Project docs site
目录
技术栈
运行与交付
- CI 工作流
- ci.yml
- dependency-review.yml
- docs-pages.yml
- firmware.yml
- lint-pr-title.yml
- 能力标记
- bun_lock
- github_actions
- package_json
依赖与工具
- package.json
- 开发依赖
- @commitlint/cli
- @commitlint/config-conventional
- commitlint-plugin-function-rules
- 项目脚本
- commitlint
- web:build
- web:check
- web:dev
- web:preview
配置与质量
- 配置文件
- .gitignore
- .gitmodules
- lefthook.yml
- package.json
{
"ci_workflows": [
"ci.yml",
"dependency-review.yml",
"docs-pages.yml",
"firmware.yml",
"lint-pr-title.yml"
],
"configs_root": [
".gitignore",
".gitmodules",
"lefthook.yml",
"package.json"
],
"markers_present": [
"bun_lock",
"github_actions",
"package_json"
],
"package_json": {
"deps_dev": [
"@commitlint/cli",
"@commitlint/config-conventional",
"commitlint-plugin-function-rules"
],
"scripts": [
"commitlint",
"web:build",
"web:check",
"web:dev",
"web:preview"
]
}
}Purpose
Mains Aegis 是 UPS / power-management 设备 mono-repo：它把硬件行为文档、ESP32-S3 固件、Web 管理界面、docs-site、前面板/音频预览工具和质量门禁放在同一个维护边界里。PRODUCT.md 明确把 Web 管理界面定义为面向多设备 UPS 的只读运维控制台，首要目标是让维护者快速判断设备健康、离线、后备供电和告警状态，而不是做可写控制台。
Taxonomy
- Tags: System design docs, Device mono-repo, Embedded Rust, TypeScript web, Web demo, Quality gates, MCU flashing integration, Embedded USB control plane, Embedded device control plane, Project docs site
- Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括
PRODUCT.md、docs/README.md、docs/quality-gates.md、docs/bms-design.md、docs/charger-design.md、docs/ups-output-design.md、firmware/Cargo.toml、web/package.json。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。
Repository map
docs/是工程设计中心，包含bms-design.md、charger-design.md、ups-output-design.md、power-monitoring-design.md、quality-gates.md等硬件/固件/产品决策。firmware/是 ESP32-S3 Rust firmware crate，firmware/Cargo.toml暴露 main voltage selector、BMS diag、thermal protect test 等编译特性。web/是 React/Vite TypeScript 管理界面，web/package.json暴露dev、preview、build、check。docs-site/使用 Rspress 生成公开文档站；固件 target、artifact 与本地控制面边界由项目文档和固件 manifest 共同维护。
Runtime and delivery
根 package.json 只负责 workspace 脚本和 commitlint；Web 运行通过 bun run web:dev 进入 web/，默认 WEB_PORT 可覆盖。PRODUCT.md 还要求测试示例与 direct-access demo path 复用正式 frontend 和正式 route，并允许 mock seed data 作为稳定交互输入。docs-site 通过 DOCS_PORT 覆盖端口，默认 50885。固件侧依赖 firmware/Cargo.toml，target、artifact 与 selector 约定由 checked-in 项目资料维护。
Architecture notes
这个项目的架构重心是“文档先行的设备系统”。UPS 行为拆成 BMS、charger、output、audio、boot self-test、power monitoring 等文档，再由 firmware 和 web UI 分别落地。Web 首版只读是关键边界：PRODUCT.md 明确避免误触 UPS 状态；任何后续控制操作都应该先进入 specs 和 safety gate，而不是直接加到 React 页面。
Workflow and quality gates
.github/workflows/ci.yml、firmware.yml、docs-pages.yml、dependency-review.yml 和 lint-pr-title.yml 把固件、文档站、依赖审查和 PR 标题规则分开。docs/quality-gates.md 与 lefthook.yml 说明质量门禁是项目 contract 的一部分。
Reusable decisions
- 复杂硬件项目用
docs/承载 current truth，比把设计散在 PR 里更可复用。 - 只读运维 UI 先行，硬件控制写操作延后到安全模型清楚之后。
- 固件操作参数应在 checked-in 项目资料中保持可复现，减少每次 flashing 的口头约定。
- Web demo 只接受复用正式前端与正式路由的 mock-seeded / read-only 演示路径，不把 docs-site 或普通 preview 误算成产品演示面。
Risks and open questions
- Web UI 与 firmware/docs 的事实可能漂移；UI 声称的状态必须能追到设备 API 和设计文档。
- 电源/电池/热保护相关改动需要硬件证据或仿真证据，不能只看 TypeScript build。
Evidence index
PRODUCT.mddocs/README.mddocs/quality-gates.mddocs/bms-design.mddocs/charger-design.mddocs/ups-output-design.mdfirmware/Cargo.tomlweb/package.jsondocs-site/package.json.github/workflows/ci.yml.github/workflows/firmware.yml
相关内容
Device mono-repo
主题Device mono-repo 表示一个仓库同时承载硬件资料、固件、Web/desktop UI、docs/specs、测试工具或发布流程。它强调边界协调：硬件、firmware、UI 和文档互相影响，不应把仓库当作单一应用。 这个 Topic 的核心是设备级知识不能被某一个技术栈吞掉。
Embedded device control plane
主题Embedded device control plane 表示设备把 ESP32-S3 作为正式控制面 MCU，并依赖其板载 USB 与 Wi‑Fi 同时承载本地与局域网控制入口。这里的主语不是“某一种传输协议”，而是 devd、CLI、Web App、可选 desktop/local agent、Web Serial 与 native USB 如何围绕同一设备事实、安全边界、发现机制、连接 ownership 和运行态协议协作。
Embedded Rust
主题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
主题Embedded USB control plane 表示把 MCU 的 USB CDC / USB Serial-JTAG 当成本地设备控制面，而不是普通调试串口。它要求运行态控制协议、设备身份、日志/trace、secret 脱敏、串口 ownership，以及 flash/reset/monitor 等生命周期操作被同一个本地 owner 模型管理。
MCU flashing integration
主题MCU flashing integration 表示项目通过 espflash 管理 ESP32 系列，通过 probe-rs 管理 STM32/其他 probe-supported MCU，并把这些 backend 接入项目配置或明确的本地操作入口。Topic token 使用可复用工程模式命名；espflash 与 probe-rs 作为具体工具名放在定义和证据里。 这个 Topic 关注的是“硬件操作入口可复现且可审计”。
Project docs site
主题Project docs site 指项目在工程仓库内维护一个独立的 web 文档站点，通常以 docs-site/、docs-pages.yml 或等价 publish workflow、docs:build / build-docs-site、DOCS_PORT 等入口体现。
Quality gates
主题Quality gates 表示仓库把“什么叫可以合并、什么叫可以发布”写成了显式、可审计的契约，并通过本地脚本、CI workflows、review/signature policy、GitHub required checks 或同类机制把它执行出来。它关注的是 gate contract，而不是某一门具体技术。 这个 Topic 用来回答“仓库怎样防止低质量或不完整的改动穿过默认分支”。
System design docs
主题System design docs 指仓库把系统级设计文档本身当成长期真相源，而不是把关键决策散落在 PR 讨论、Issue 评论或脑内记忆里。这里的“系统设计”不只指架构图，也包括硬件行为文档、质量门禁、控制面边界、设计取舍和后续实现必须服从的 current truth（projects/mains-aegis.md、projects/style-playbook-skills.md）。
TypeScript web
主题TypeScript web 表示项目把 TypeScript 作为一个或多个 Web surface 的主语言，并围绕它建立 workspace scripts、typecheck、bundler、lint/format、env contract 和前端构建门禁。这里的主语不是“仓库里出现了 .ts 文件”，而是 TypeScript 已经决定了维护者怎样启动、构建、校验和交付实际 Web surface。
Web demo
主题Web demo 表示仓库刻意提供一个可直接给 owner、评审者或潜在用户体验的 Web 演示面，而且这个演示面复用正式产品前端与正式路由，而不是单独做一套只用于截图的 demo 页面。它允许用 mock backend、simulation device、read-only seed data 或等价安全输入来稳定复现产品行为，但默认不要求接入真实生产登录、真实后端写路径或真实硬件危险写操作。