安装

本文介绍 ClientX 是什么、它的架构分层，以及两种安装 core 的方式：本地 workspace 包（源码，可二次开发）与预打包下载（解压即用）。最后用 clientx create 创建你的第一个资源项目。

1. ClientX 是什么

ClientX 是一个资源化解耦的前端应用框架。它把一套完整的前端应用拆成 core（内核） + 可插拔资源（resource） 两部分：

core：应用帧、运行时加载器、内核注册表、共享包（@clientx/runtime / @clientx/common）。core 不包含任何具体资源的名字 —— 它只负责「跑起来」。
资源：每个资源是一个自包含的功能单元，有自己的身份、路由、能力、槽位、i18n 与代码。例如 client（应用壳）、msgx（消息中心）、userx（用户中心）、agix（AI 引擎）、sitex（官网框架）、portal（官网站点）。

三句话记住架构：

core 不 import 资源：core-loader.ts 在运行时从 manifest.json 读取闭包，动态加载资源。
资源自声明：每个资源用 register.ts 的 declare / activate 声明自己，依赖与能力自动进入内核注册表。
单一 React 实例：react 家族经 importmap 解析到 shared-vendor.js，所有资源与 core 共享同一个 React、同一个 i18n、同一个 query client。

2. 安装 core：两种方式

方式 A：本地 workspace 包（源码，可二次开发）

下载 clientx-core-source.tar.gz 并解压：

tar xzf clientx-core-source.tar.gz
cd clientx/
npm install

工具链源码包含 @clientx/runtime 与 @clientx/common 两个 workspace 包、CLI（scripts/clientx.mjs）、全部构建器（scripts/p3/）与工程配置。安装完成后即可：

node scripts/clientx.mjs build     # 构建默认组合(见打包页)
node scripts/clientx.mjs run       # 启动开发服务器

方式 B：预打包下载（解压即用）

不需要 Node 工具链。下载 clientx-core-prebuild.tar.gz 并解压：

tar xzf clientx-core-prebuild.tar.gz
# 得到 dist/ 目录：core-app + shared-vendor + vendor(@clientx) + 默认资源 + manifest

把 dist/ 交给任意静态服务器即可运行：

npx serve dist           # 或 python3 -m http.server --directory dist 3007

预打包产物是默认闭包（client+userx+msgx+agix+conn+e2ee）的完整应用；它不含官网站点资源（portal / docs / help）。若要组装自定义组合（比如只想要官网站），请用方式 A 从源码构建（见「打包」页）。

3. 创建项目：`clientx create`

安装好 core 源码后，用 CLI 生成一个新资源骨架：

node scripts/clientx.mjs create hello --deps client

参数说明：

hello：资源名。小写字母开头，首段 ≥2 字符、后续段 ≥1 字符，段间用单个连字符分隔（如 demo、my-site、my-a 均合法）。
--deps client：声明资源依赖 client（写入 package.json 的 clientx.deps）。--deps 列表里的每个 id 必须是 src/resource/ 下已有的可构建资源。
--kind app|site：资源类型，默认 app。做站点用 --kind site（再依赖 sitex）。

命令会在 src/resource/hello/ 生成一个最小可构建骨架：

src/resource/hello/
├── package.json     # name: @me/hello + clientx: { id, kind, deps, entry }
├── register.ts      # declareHello() + activateHello()(资源根,与内置资源同构)
└── i18n/
    ├── zh.json      # {} 空语言包
    └── en.json      # {}

验证可构建：

node scripts/clientx.mjs build --resources hello,client

4. 目录结构

clientx/
├── packages/@clientx/
│   ├── runtime/            # 内核：资源/路由/槽位/功能注册表、i18n
│   └── common/             # 通用组件(markdown-content/ui)与库
├── scripts/
│   ├── clientx.mjs         # CLI：build / create / run
│   └── p3/                 # 构建器 + 闭包解析 + 下载产物生成
├── src/
│   ├── App.tsx             # 应用帧(布局/查询客户端/外观)
│   ├── main.tsx            # 入口(dev 静态 register / prod loader)
│   ├── core-loader.ts      # prod 运行时：从 manifest 加载资源
│   └── resource/<id>/      # 资源(register.ts + 模块 + i18n)
└── vite.config.ts          # 别名/proxy/下载中间件

5. 下载

下载区提供三种产物（见「下载」页）：

产物	用途
`clientx-core-source.tar.gz`	工具链源码，本地包方式使用（本页方式 A）
`clientx-core-prebuild.tar.gz`	预打包 dist/，解压即用（本页方式 B）
`resource-<id>-source.tar.gz`	各资源独立源码，可自行二次开发
`resource-hello-example.tar.gz`	hello 最小示例资源源码

下一步：读完「开发」页，了解资源的 register.ts 与生命周期。

安装