包总览

仓库把后台系统里反复出现的能力拆成了 29 个包。这一页是它们的全局视图：总表、分层、依赖关系与命名规则。

API 参考按平台分成三处，下面的总表每一行都直接指过去：

想知道这些能力在应用里怎么装配，去 Admin 应用；想理解为什么这么拆，去 包分层与依赖方向。

分层

packages/ 按「跨平台基础能力 + 平台子树」组织，依赖总体从应用和平台实现流向跨平台基础能力：

              apps/admin · apps/admin-example
                            │
      ┌─────────────────────┴─────────────────────┐
      │                                           │
 packages/web/*                            packages/native/*
 DOM · antd · Vite                         RN · Expo · Uniwind
      │                                           │
      └─────────────────────┬─────────────────────┘
                            │
            packages/primitives/* · packages/hooks
                            │
                    packages/@core/*

@core 只是物理目录分组，不是 TypeScript namespace，也不存在 @skyroc/core 这个包。

硬约束

同一层内允许职责明确的单向依赖——「同层」不是禁止依赖的理由。完整规则见 packages/ARCHITECTURE.md。

28 个包总表

「内部依赖」一列只列 workspace 内的包（dependencies + peerDependencies），不含第三方。

packages/@core —— 基础设施层（9）

跨端 hooks 与原语（2）

packages/web —— Web 平台（13）

设计系统

主题

布局与样式

运行时

构建

三个 ui/* 包的组件文档、实时 Demo 和 Props 表在独立的 Web UI 站点，主站只保留 一页指路。

packages/native —— Native 平台（1）

组件文档与 Expo Demo 在独立的 Native UI 站点。

internal —— 内部配置（3）

内部包统一使用 @skyroc scope，见 命名规范。

依赖关系

改一个包会波及谁

按运行时反向依赖数排序——这张表决定改动的风险等级：

@skyroc/utils 和 @skyroc/color 是两个真正的枢纽：改它们的公开 API，一次要验证 8–10 个下游包。

但两者的波及方向不同：

• @skyroc/utils 横跨两棵平台子树——Web 侧 9 个包 + Native 侧的 native-ui 都依赖它。同时被 Web 和 Native 依赖的运行时包只有三个：utils、hooks、form。改这三个要两端一起验。
• @skyroc/color 全部下游都在 Web 侧（外加 internal/uno-config），native-ui 并不依赖它。改它只需验 Web。

最重的集成包

@skyroc/web-admin-layouts 依赖 10 个内部包，是整棵 Web 树的顶点：

@skyroc/web-admin-layouts
├── @skyroc/web-admin-theme      主题状态与 antd 适配
├── @skyroc/web-admin-i18n       菜单与界面文案
├── @skyroc/materials            AdminLayout 骨架、PageTab
├── @skyroc/web-ui               基础组件
├── @skyroc/web-ui-antd          antd 复合组件
├── @skyroc/web-ui-compose       无状态复合组件
├── @skyroc/core-state           Jotai store
├── @skyroc/hooks                跨端 hooks
├── @skyroc/color                色板计算
└── @skyroc/utils                工具函数

所以「后台壳」不是一个包，而是一条装配链。定位布局问题时按这条链自上而下排查。

零内部依赖的包（12）

这些包不依赖任何其他 workspace 包，可以单独理解、测试和发布：

types、color、core-state、logger、scripts、type-utils、ui-types、hooks、web-admin-styles、web-admin-vite、tsconfig、config

工程化底座（devDependency）

有三个包几乎被所有包引用，但都是 devDependencies，不进运行时产物：

@skyroc/types 值得单独说明：它只声明全局命名空间，不导出任何运行时值，所以是 devDependency 而非 dependency。业务代码写 Api.Auth.UserInfo 时不需要 import——这也是为什么它的运行时反向依赖数是 0。

命名规则

@skyroc/materials 是位于 web/ 下的历史专名，新包不要照此扩大例外。@skyroc/tailwind-plugin 的裸名是合规的——它是跨平台能力，住在 @core/。目录名与发布名不要求一致，以 package.json#name 为准。

怎么查

Last updated on