企业官网建设流程全解析

Maka Desktop Renderer 架构全解：React 渲染进程的分层边界、样式令牌体系与迁移护栏

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka

导读

本文以 Apache Maka（Incubating）桌面应用渲染进程源码目录 apps/desktop/src/renderer 为对象，系统讲解 Electron 三层架构（main / preload / renderer）中的 React UI 层：从main.tsx → app.tsx → AppShell的启动链、index.html预加载骨架与首帧渲染优化，到以bootstrap / composition / shell / application / features / platform为核心的所有权分区模型，再到由check-renderer-architecture.mjs强制执行的架构护栏（architecture guardrail）与债务台账（migration ledger），以及 CSS 令牌与分层样式规范。读完本文，你将掌握 Maka renderer 的内部组织方式、新增代码应落位的正确区域、样式与令牌的书写规则，以及如何用一条 npm 命令验证债务没有在 PR 中回涨。

说明：main / preload / renderer 三层划分与 IPC 契约见 apps/desktop/README.md；本文只覆盖 renderer 内部。

一、启动链路：从main.tsx到 AppShell

Renderer 的入口链为main.tsx→app.tsx→AppShell（app-shell.tsx），index.html是 Vite 的 HTML 壳。main.tsx 在挂载 React 之前会预取（prefetch）onboarding 快照，让正常路径的首次提交直接绘制出真实界面；app.tsx用ToastProvider+ErrorBoundary包裹AppShell。

1.1 启动前的三件事

在createRoot之前，main.tsx依次执行：

1. syncUiLocaleDocument(readSystemUiLocale())—— 把系统 UI locale 同步到文档；
2. applyCachedThemeBeforeMount()—— 应用缓存的主题，避免首帧闪色（见 cached-theme-bootstrap.ts）；
3. createDesktopFeatureServices()—— 构造整个桌面的 feature 服务容器（见 desktop-feature-services.tsx），随后以DesktopFeatureServicesProvider注入 React 树。

1.2 预取 Onboarding 快照的容错设计

prefetchOnboardingSnapshot()的意图在源码注释中写得很清楚：preload 骨架（index.html里的.maka-preload）在快照解析期间留在屏幕上，因此 React 第一次提交时就已经拥有 sessions + connections，直接绘制真实聊天界面——没有中间的 loading 卡片、没有布局跳动（即注释中提到的"配置页闪了一下"启动闪烁）。

它采用 fail-open（失败开放）策略：

• 快速重试一次：首次调用失败后等待150ms（ONBOARDING_SNAPSHOT_RETRY_DELAY_MS）再试（IPC handler 可能在最初几毫秒尚未注册）；
• 硬超时：2500ms（ONBOARDING_SNAPSHOT_TIMEOUT_MS）内未完成即返回null，保证主进程卡死时渲染进程仍能挂载；
• 失败后 React 以null挂载，走应用内经典 loading 路径兜底；
• WorkHub 会话模式不消费桌面 onboarding 快照（workHub.surface === 'workhub'时直接返回null）。

1.3 首帧绘制信号与窗口显示

app.tsx 用一个useEffect等待两个 animation frame之后才调用window.maka?.appWindow?.notifyRendererReady?.()。原因在注释中说明：主进程创建的BrowserWindow是隐藏的（show: false），因此操作系统永远不会在 React 绘制前闪出index.html的骨架。布局效果（layout effect）对这一信号来说太早——它在 DOM 提交后、Chromium 实际绘制前执行，可能导致主进程在最后一帧合成仍是骨架时显示窗口。等待两次动画帧能保证信号出现在 AppShell 至少一次绘制之后。该信号是无条件的：即使快照为null、AppShell 挂载了 fail-soft loading 状态，窗口也应出现。同时window.maka在 Electron 之外（如 Storybook）是 undefined，因此调用做了可选链保护。

二、index.html与唯一的样式入口

2.1 CSP 与预加载骨架

index.html 声明了严格的 CSP：

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self'" />

<div id="root">内嵌一个.maka-preload骨架（带role="status"、aria-busy="true"），其颜色是硬编码的（不使用 CSS 变量，因为maka-tokens.css还没加载），明暗主题通过prefers-color-scheme选择，与cached-theme-bootstrap.ts的兜底逻辑保持一致。注释中还披露了性能量级：这个骨架是为了覆盖355KB CSS + 5.8MB JS的加载窗口，避免白屏/灰屏。createRoot挂载时会将骨架替换掉。

2.2styles.css：唯一打包的样式入口

styles.css 是唯一的样式打包入口，它导入：

• Astryx 的 reset 与组件基座（@astryxdesign/core/reset.css、astryx.css、@maka/ui/styles.css、xterm.css）；
• 字体（Geist / Geist Mono 可变字体）；
• maka-tokens.css、reference-shell.css以及每一个styles/*.css文件。

它只做顶层编排，真正的选择器规则放在styles/*.css中。所有产品级导入都进入命名层（layer(components)等），分层声明见 cascade-layers.css。文档中唯一的契约例外就是index.html的内联.maka-preload骨架。

三、Renderer 所有权分区模型

app-shell.tsx、app-shell-*与use-app-shell-*是一组冻结的遗留边界（frozen legacy boundary），不是新代码的范式。它们暂时保留着组合根（composition-root）迁移之前的旧所有权；禁止再向这个家族添加文件，也禁止把新的 state、effects、subscriptions、bridge 调用或 feature view-model 构造移入其中。其记录在案的债务只能随着每个能力迁移到目标所有者而下降。

目标依赖方向是：

bootstrap -> composition -> shell + application contracts + feature public entries platform/desktop -> injected feature/application ports features -> own internals + shared contracts/core/UI application -> shared contracts + injected ports

各区域的职责与红线：

此外，composition 与 adapters 消费的是 application 的公共入口而不是深层实现模块；适配器可以持有 bridge 与浏览器环境访问权，但绝不能拥有 React UI/hooks/类生命周期、Electron/Node 导入或非静态依赖加载。右侧/底部 Workbar 及其余已抽取的 feature 在自己的 README 中定义详细状态与生命周期边界；跨 feature 行为使用显式契约与意图（intents），不用私有导入或 service locator。

四、架构护栏与迁移台账（核心机制）

4.1 检查器做什么

check-renderer-architecture.mjs 解析 renderer 的 import、bridge 别名、浏览器环境访问与有状态 hook 所有权，强制执行上一节的分区规则。从脚本源码可以看到它实际监控的能力集合：

• React 19 有状态 hooks：useState、useEffect、useLayoutEffect、useReducer、useRef、useSyncExternalStore、useTransition、useOptimistic、useDeferredValue等 13 个（STATEFUL_HOOKS集合）；
• 类组件生命周期方法：componentDidMount、componentDidUpdate、getDerivedStateFromProps等 14 个（REACT_LIFECYCLE_METHODS集合）；
• 浏览器环境调用：fetch、setTimeout、addEventListener、WebSocket、Worker、IntersectionObserver、matchMedia、localStorage等（ENVIRONMENT_CALLS集合）；
• 浏览器环境对象：document、navigator、location、history、indexedDB等（ENVIRONMENT_OBJECTS集合）；
• 禁止的环境 import：electron与全部 Node 内置模块（FORBIDDEN_ENVIRONMENT_IMPORTS）。

同时它还会拒绝：内部区域导入 Electron/Node、深层或跨 feature 导入、import.meta.glob逃生舱、生产环境使用 feature testing 入口、以及 application contracts 重导出 application 实现等违规。

4.2 台账与棘轮（ratchet）

renderer-architecture.json（4564 行）记录了精确的遗留/根债务，并把每一个 AppShell/root 路径映射到其预期所有者。它冻结了每个未分类的遗留 renderer 源文件，以及从 AppShell 可传递到达的每个非所有者 Desktop 源文件。台账在跨越显式 feature/application/platform 所有者的同时，把遗留 renderer、shared、preload 等非所有者中间节点记入债务闭包；对声明（declarations）只做依赖解析遍历、不当作运行时债务。

关键机制：

• 依赖路径债务只对回归性运行时边定价；type-only import 在编译期被擦除，永不计数；
• 进入 shell、feature public 或 application public/contract 边界的边是迁移希望的方向，AppShell 家族与两个闭包可以自由添加；root 入口不允许（main.tsx与app.tsx注定要变成瘦挂载），只能同数量地替换为 bootstrap 或 composition 目标；
• AppShell 家族与 root 入口文件是完整棘轮：依赖路径、导入绑定、bridge/hooks/browser 能力、action factories 与非平凡 token 数都不得增长；其传递支持闭包只对架构能力与依赖做棘轮，普通实现可以自由演进；
• 支持入口只能单向地从 AppShell 闭包移入 root 闭包，反向移动会被拒绝；遗留 import 允许名单只能相对 base 分支收缩。

4.3--base与--strict-base语义

CI 以--base <sha> --strict-base运行检查器：棘轮会从 base 提交的物化树重新推导其债务，而不是信任已提交的台账；--strict-base会把任何无法物化或分析该树的情况变成硬错误。文档特别点名了 #4250 教训：如果静默回退到已提交台账，可能重新引入"base 台账低估自身树导致 CI 卡死"的失败模式。

当检查器脚本本身与 base 提交不同时，还会导入 base 提交的检查器来同时测量两棵树——base 测量规则（生成与分类）本应标记的债务会以base-checker cross-check:违规失败，这样一次变更不可能同时放松债务测量方式和降低棘轮两侧。在--strict-base下：无法写入/导入/运行已有 base 检查器、缺少generateArchitectureConfig导出、或输出与当前台账 schema 不符，都是硬错误；不带该 flag 时这些条件只报告、跳过交叉检查。base 提交没有检查器时两种模式都跳过旧测量规则。另外文档明确提示：validateMonotonicDebt的变更不受交叉检查保护，属于评审关注点。

4.4 本地验证命令

# 1. 当前树的检查 npm run check:renderer-architecture # 2. PR 前验证债务相对 main 未增长 npm run check:renderer-architecture -- --base upstream/main # 3. 合法的债务削减之后：先重新生成机械计数，再跑 base 对比 npm run check:renderer-architecture -- --write --base upstream/main

注意第 3 步的顺序：先--write重新生成，再跑 base 对比；重新生成不能对 CI 隐藏增长（脚本根目录package.json中映射为npm --workspace @maka/desktop run check:architecture --）。

4.5 Copy catalog 的放行机制

locale 策略（#2672）强制把用户可见文案从业务文件移入locales/*-copy.ts目录，这必然引入债务棘轮原本禁止的 import 边。因此每个目录都被结构性验证：

• 必须携带来自@maka/core/ui-locale的UiCatalog标记；
• 记录零个被追踪的 hook/bridge/lifecycle/environment/action-factory 能力；
• 运行时 import 只能是裸包说明符（bare package specifiers）——绝不使用相对路径或@maka/desktop/路径，否则目录就变成依赖隧道。

验证失败的locales/*-copy.ts是专门违规（copy catalog validation failed: …），不会静默回退到棘轮。放行的边从依赖计数棘轮、闭包准入和 feature/Desktop-adapter 遗留预算中排除，但导入文件的其他一切仍照常棘轮，root 入口的 import/token 计数保持严格。

4.6 永久守卫的 root 入口与生产入口链

main.tsx与app.tsx是永久受守卫的 root 入口：其记录债务可随它们变薄而降到零，但台账条目保留，防止后续 PR 把 bridge、hook、浏览器环境、动态导入或遗留依赖所有权重新加回去。root 入口守卫只能在守卫的源文件被删除时移除。

生产入口链属于同一 root 契约：主进程把唯一的 renderer 导航委托给 main-renderer-loader.ts，只加载dist-renderer/index.html；Vite 必须从src/renderer构建该文档，且源 HTML 必须在/main.tsx保持唯一的外部模块入口。构建期的 Vite 证明（attestation）会检查最终模块图，构建后验证器 check-renderer-entry-output.mjs 把产物 HTML 的唯一 script 绑定到该确切入口 chunk，同时保留固定 CSP 并拒绝额外的可执行或导航面——因此 HTML-transform 插件无法在源码检查后静默替换或扩充规范入口。移动该链的任何部分都需要显式架构变更，而不是绕过台账。

五、样式与令牌体系

5.1 文件分工

5.2 令牌书写规则

• 自定义 CSS 变量进maka-tokens.css；新的组件局部变量应带/* local: ... */注释（现存变量并非全部都有）；
• 不新增硬编码的 color / radius / z-index；
• 特别注意--foreground-N拆分：wash 停靠点（-2/-3/-5/-8/-10）是用于背景与边框的表面填充，不是文字；两个语义别名（--foreground/--muted-foreground）才是文字色词汇。两者是不同关注点——不要将 wash 停靠点折叠进文字别名。

六、新代码规范：Primitive 优先，CSS 最后

新增代码的决策顺序是：

1. 优先使用 Astryx 支撑的@maka/uiprimitive；
2. 仅当没有任何 primitive 承载时，才在对应的styles/<surface>.css中写 CSS，并遵循 docs/frontend-css-governance.md（层规则、非分层覆盖清单、!important审计、死 CSS 白名单）；
3. 不加未在maka-tokens.css注册的令牌。

七、过渡面收敛方向

以下是被承认的过渡状态（不是 TODO；具体工作跟踪在 issues/PR）：

• 现有手写styles/*.cssrecipe 与对 Astryx 支撑的@maka/uiprimitive 的内部 DOM 覆盖是承认的过渡状态，不是新工作的先例；新样式使用公开 props、令牌或稳定的themeProps扩展点；
• reference-shell.css的终态是折入令牌/样式体系并删除文件；
• maka-tokens.css混合令牌+recipe 的终态是这里只放令牌，recipe 迁移到 primitive /styles/。

八、契约与护栏一览

• 产品设计意图：根目录 DESIGN.md；
• CSS 级联 / layer /!important/ 死 CSS / 令牌规则：docs/frontend-css-governance.md；
• 组件状态、ARIA、令牌与文案行为由源码与聚焦的契约测试拥有；
• 当散文与代码或行为测试冲突时，代码与测试是真相来源；CSS 约定靠评审与渲染表面验证；构建/测试入口是根目录 package.json 中的 npm scripts（见顶层 README.md）。

结语

Maka 的 renderer 层并非一个随意堆叠的 React 目录，而是一套"分区模型 + 自动护栏 + 债务台账"三件套支撑的可演进架构：main.tsx/app.tsx是永久守卫的瘦挂载，features/各自纵向自治，platform/desktop/以窄 port 消化 preload bridge，check-renderer-architecture.mjs在每次 CI 中把架构规则变成可验证的硬约束。理解这套组织方式，是向 Maka renderer 贡献代码、或借鉴其 Electron + React 架构治理实践的最短路径。

【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka