开始一个项目

第二个阶段：创建项目、选择它包含哪些端，然后只安装这些端所隐含的工具链。请按顺序执行下面的步骤；运行和构建在第 3 步，各端的细节在对应的平台页面。

第 1 步 —— 创建项目并勾选端

mars create my-app

命令会询问你要包含哪些端。web-admin 与 api 默认已勾选，其余都是可选。一次勾选决定两件事：哪些目录会进入你的项目，以及 mars init 之后要校验并安装哪些工具链。每一行都会先把代价写出来：

📋 Select platforms to create

  🧰 Ticking a platform also opts into its toolchain: `mars init` checks it
     and installs what is missing. Tick nothing extra and nothing extra is
     downloaded.

  📱 Mobile:
   1. [ ] Android [developing]
         ↳ toolchain: JDK, Android CLI
   2. [ ] iOS [developing]

  🖥️ Desktop:
   3. [ ] Windows [developing]
   4. [ ] Linux [developing]
   5. [ ] macOS [developing]
   6. [ ] Desktop
         Tauri (Win / macOS / Linux)
         ↳ toolchain: Rust

  🌐 Web:
   7. [ ] Web Client [developing]
   8. [✓] Web Admin
         Backend administration system

  ⚙️ API:
   9. [✓] API Service
         RESTful API service
         ↳ toolchain: Docker, JDK, Maven

  Currently selected: 2 modules
  🧰 `mars init` will check/install: Docker, JDK, Maven

汇总行和真正安装时一样去重 —— 同时勾选 api 和 android 只列出一个 JDK；没有 ↳ toolchain: 那一行的端，除了你已有的 Node 和 pnpm 之外不需要任何额外东西。交互式终端里用 ↑ ↓ 移动、space 勾选、enter 确认；检测不到 TTY （CI 或编辑器内置终端）时输入编号切换，a 全选，n 全不选，enter 接受默认值。

想跳过询问、直接使用两个默认端：

mars create my-app --non-interactive

它会替你勾上 web-admin 和 api（所以也就选了 api 的工具链）；其他组合只能通过交互完成 —— create 没有 --platform 参数，输入语法见配合 AI Agent 使用。

你会得到什么

mars create 复制一份真实可跑的模板，再按勾选裁剪，而不是待填空的骨架。未勾选的端不会被复制，它们的工具链同样不会被安装。每个端包含什么见平台，create 执行的确切步骤见 CLI 参考。

第 2 步 —— 初始化项目

create 结束时会打印接下来的命令。进入项目并执行 mars init：

cd my-app
mars init

pnpm install 由 mars init 自己执行 —— 它替代这一步，所以不要再单独跑 pnpm install。随后它读取 platforms.json，只检测已启用的端真正需要的工具链，再用 mise 把缺的补上；纯 Web 项目不会下载任何语言工具链。每项下载都会说明来源，出现意料之外的下载时可以一路追回是哪一行要求的：

🧰 Toolchain required by this project: Docker, JDK, Maven
   (derived from: API Service)

如果 API 只会跑在容器里，可跳过宿主机的 JDK 和 Maven：

mars init --docker

这需要你主动声明，不会自动判断：装了 Docker 并不等于 API 就跑在里面 —— Docker 页面的做法是 MySQL 和 Redis 跑容器、API 留在本机，这种组合仍需要本机 JDK。在 api + android 项目里只有 Maven 会被跳过，因为 Gradle 跑在本机。

有三样东西它只报告、不安装 —— 没有版本管理器管得了系统服务、GUI 程序和 C 语言库：Docker、Android SDK 和 Tauri 的系统依赖。跑 mars init 之前先装好 mise，否则它们全部只会被报告。安装成功后它会提示你打开一个新终端，让工具进入 PATH。完整流程见 mars init，包括从 compileSdk 推导出的 Android SDK 包清单。

后来又加了一个端

在 platforms.json 里启用新的端，再跑一次 mars init：

mars init

它只补装新端需要的东西，已有的跳过，所以重复跑是安全的，而且这就是唯一需要做的事。create 时跳过的端从未被复制过，启用它还需要对应的 apps/<platform> 目录，见创建之后再启用某个平台。只要端的集合变了，再跑一次 mars init 就行。

什么时候一次装完反而更好

个人笔记本上不需要提前决定任何事。当机器要干什么事前已经定了，则改为预装：

情况	为什么预装更好
CI 机器和 Docker 镜像	镜像的用途本身就固定了它要构建什么；工具链烧进层里可被缓存、运行时不需要联网 —— Docker 工作流就是这么做的
离线或只有内网的机器	按需安装假设了 `mars init` 那一刻能下载；趁还能联网时装好
统一发的团队机器、教学机器	机器一模一样本身就是目标，机器之间的差异不是要保留的东西

第 3 步 —— 运行和构建项目

工作区级命令读取与 init 同一份 platforms.json，同时作用于每个已启用的端。

一次启动所有端

mars dev

只聚焦一个端：

mars dev --platform web-admin

Web 工作区通过 Turborepo 启动；原生平台用各自的工具链 —— 目前只有 android 接好了脚本（gradlew installDebug），ios、windows、linux、macos 会打印一条 "pending" 提示。api 是 Maven 模块而不是 pnpm 工作区成员，没有 dev 脚本，需要手动启动 —— 见各平台页面。

一次构建所有端

mars build                          # 每个已启用的端
mars build --platform web-admin
mars build --platform api --docker

build 已为 web、web-admin、desktop 和 android 实现；其他端会报告暂不支持构建。--docker 改为在容器里构建和运行，而不是在本机 —— 见 Docker。

清理

mars clean

删除整个工作区的构建产物。

各端指南

每个已启用的应用都按同样三个阶段来写 —— 环境准备、如何开发、部署。"Ready" 的端开箱即可构建和运行；"Scaffold only" 的端预留了结构但仍是占位 —— 见平台。

应用	成熟度	从这里开始
后台管理系统 —— Web Admin + API（`apps/web-admin`、`apps/api`）	Ready	环境准备
桌面端（`apps/desktop`）	Ready	环境准备
Android（`apps/android`）	Scaffold only	环境准备
Web、iOS、Windows、Linux、macOS	Scaffold only	见平台矩阵

每个平台目录还带有各自的 AGENTS.md，包含构建命令、编码规范和注意事项，动手改那个平台之前先读它。

第 4 步 —— 保持接线为最新

把后续对构建接线的改进拉进已有项目，而无需改动应用代码：

mars update

它会刷新 AGENTS.md、turbo.json、pnpm-workspace.yaml、platforms.json、 package.json、scripts/ 和 packages/，并刻意跳过 apps/、docs/、 .docs/ 和 design/。被替换的文件会先备份到 .mars-update-backup。见 mars update。

第 1 步 —— 创建项目并勾选端​

你会得到什么​

第 2 步 —— 初始化项目​

后来又加了一个端​

什么时候一次装完反而更好​

第 3 步 —— 运行和构建项目​

一次启动所有端​

一次构建所有端​

清理​

各端指南​

第 4 步 —— 保持接线为最新​