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

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 MakaIncubating桌面应用渲染进程源码目录 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到 AppShellRenderer 的入口链为main.tsx→app.tsx→AppShellapp-shell.tsxindex.html是 Vite 的 HTML 壳。main.tsx 在挂载 React 之前会预取prefetchonboarding 快照让正常路径的首次提交直接绘制出真实界面app.tsx用ToastProviderErrorBoundary包裹AppShell。1.1 启动前的三件事在createRoot之前main.tsx依次执行syncUiLocaleDocument(readSystemUiLocale())—— 把系统 UI locale 同步到文档applyCachedThemeBeforeMount()—— 应用缓存的主题避免首帧闪色见 cached-theme-bootstrap.tscreateDesktopFeatureServices()—— 构造整个桌面的 feature 服务容器见 desktop-feature-services.tsx随后以DesktopFeatureServicesProvider注入 React 树。1.2 预取 Onboarding 快照的容错设计prefetchOnboardingSnapshot()的意图在源码注释中写得很清楚preload 骨架index.html里的.maka-preload在快照解析期间留在屏幕上因此 React 第一次提交时就已经拥有 sessions connections直接绘制真实聊天界面——没有中间的 loading 卡片、没有布局跳动即注释中提到的配置页闪了一下启动闪烁。它采用 fail-open失败开放策略快速重试一次首次调用失败后等待150msONBOARDING_SNAPSHOT_RETRY_DELAY_MS再试IPC handler 可能在最初几毫秒尚未注册硬超时2500msONBOARDING_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 声明了严格的 CSPmeta http-equivContent-Security-Policy contentdefault-src self; script-src self; style-src self unsafe-inline; img-src self data: blob:; connect-src self /div idroot内嵌一个.maka-preload骨架带rolestatus、aria-busytrue其颜色是硬编码的不使用 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各区域的职责与红线区域职责禁止事项shell/只拥有固定框架、区域regions与挂载/可见性策略禁止 Desktop bridge 访问、feature 实现导入、业务 state/effects直接存储、定时器、fetch、DOM/全局订阅同样被禁止bootstrap/一次性启动与 React 挂载排序除定位 DOM 挂载点外不拥有 React state/类生命周期、存储、定时器、订阅或网络访问composition/组装 providers、adapters 与公共 feature hosts只是接线不是另一个生命周期或浏览器环境所有者application/显式共享的 renderer 权威不得依赖 feature、shell、Desktop adapter、preload 或 main-process 实现features/name/一个纵向能力不能访问window.maka、不能导入其他 feature 的内部、不能依赖 AppShell/preload/main/platform/desktop消费者只用其公共index入口testing仅供测试/Storybookplatform/desktop/preload bridge 的外部适配区实现窄向的 inward-facing ports 而非导出整个 bridge若 port 是某 bridge 命名空间的结构子集适配器直接透传命名空间如sessions: bridge.sessions只手写需要重命名、守卫或转换的块此外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 有状态 hooksuseState、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集合禁止的环境 importelectron与全部 Node 内置模块FORBIDDEN_ENVIRONMENT_IMPORTS。同时它还会拒绝内部区域导入 Electron/Node、深层或跨 feature 导入、import.meta.glob逃生舱、生产环境使用 feature testing 入口、以及 application contracts 重导出 application 实现等违规。4.2 台账与棘轮ratchetrenderer-architecture.json4564 行记录了精确的遗留/根债务并把每一个 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.htmlVite 必须从src/renderer构建该文档且源 HTML 必须在/main.tsx保持唯一的外部模块入口。构建期的 Vite 证明attestation会检查最终模块图构建后验证器 check-renderer-entry-output.mjs 把产物 HTML 的唯一 script 绑定到该确切入口 chunk同时保留固定 CSP 并拒绝额外的可执行或导航面——因此 HTML-transform 插件无法在源码检查后静默替换或扩充规范入口。移动该链的任何部分都需要显式架构变更而不是绕过台账。五、样式与令牌体系5.1 文件分工文件角色astryx-theme/makaTheme.tsAstryx 字体刻度、中性色 remap 与主题级组件覆盖的源头astryx-theme/maka.css生成的 Astryx 主题由styles.css导入必须从makaTheme.ts重新生成绝不直接编辑maka-tokens.css产品 CSS 令牌主源color / shadow / typography 别名 / radius / spacing / motion / z / layout尾部还有一大段 recipe过渡期令牌与 recipe 共存于一个文件reference-shell.css目标布局的 shell 重建从参考实现摘录手工编写头注释记录出处过渡期——计划折回令牌/样式体系后删除styles/*.css各表面手工编写的 recipe如chat-*、sidebar、composer、palette、settings/*、module-pages/*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 最后新增代码的决策顺序是优先使用 Astryx 支撑的maka/uiprimitive仅当没有任何 primitive 承载时才在对应的styles/surface.css中写 CSS并遵循 docs/frontend-css-governance.md层规则、非分层覆盖清单、!important审计、死 CSS 白名单不加未在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.mdCSS 级联 / 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 bridgecheck-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考