创建 Mojo/MAX 新项目时：按上下文推断选项并用结构化…

适用于从零初始化 Mojo 或 MAX 项目，并选择 pixi/uv/pip/conda、nightly/stable 环境。

适用场景

解决思路

1. 当用户想创建新项目时，先从请求中尽可能推断选项，例如：“new Mojo project”表示 type=Mojo，“called foo”表示 name=foo。
2. 然后使用结构化多选提示（不是纯文本）在一次交互中只收集仍未指定的选项。
3. 不要询问用户已经提供或暗示的选项。
4. 需要确定的选项：项目名称（Project name）：如果用户未指定就询问。
5. 需要确定的选项：项目类型（Type of project）：Mojo 或 MAX；如果用户说“Mojo project”或“MAX project”则从上下文推断。
6. 需要确定的选项：环境管理器（Environment manager）：`pixi`（推荐）或 `uv`。
7. 需要确定的选项：`uv` 项目类型（仅当环境管理器为 `uv`）：完整 uv 项目（`uv init` + `uv add`，推荐）或快速 uv 环境（`uv venv` + `uv pip install`，更轻量）。
8. 需要确定的选项：Channel：nightly 或 stable。MAX 项目默认 nightly，Mojo 项目默认 stable；仅在用户未暗示时询问。
9. 之后按下面相应 `pixi` 或 `uv` 部分初始化项目，并选择 `max` 或 `mojo`。不要固定版本：每个 channel 已解析到正确版本。
10. MAX 和 Mojo 一起发布但版本号规则不同，所以版本字符串看起来不相似。stable 上 `max` 是 `26.5`，`mojo` 是 `1.0.0`；nightly 上是 `26.6.0.dev*` 和 `1.1.0.dev*`。这是预期情况，不是不匹配。
11. 不要寻找或使用 `magic` 创建 Mojo 或 MAX 项目；它已不再支持，Pixi 已完全取代其能力。
12. 系统前置条件：Mojo 编译需要 C linker。若尚未安装则安装：
13. Ubuntu/Debian：`sudo apt install gcc`
14. Fedora/RHEL：`sudo dnf install gcc`
15. macOS：`xcode-select --install`
16. Windows：先安装 WSL2（见 Windows 用户），然后安装 `gcc`
17. Windows 用户：Mojo 无法在 Windows 原生运行。在 PowerShell 中运行 `wsl --install` 安装 WSL2，然后在 WSL 环境中按 Linux 说明操作。
18. Pixi（推荐）：Pixi 以可复现方式在受控环境中管理 Python、Mojo 和其他依赖。
19. 先确定是否安装了 `pixi`。如果命令行不可用，按 <https://pixi.prefix.dev/latest/#installation> 的最新说明安装。
20. 安装 `pixi` 后，可能需要将其加入本地 shell 环境。
21. Pixi Nightly 新项目：`pixi init [PROJECT] -c https://conda.modular.com/max-nightly/ -c conda-forge && cd [PROJECT]`，然后 `pixi add [max / mojo]`，然后 `pixi shell`。
22. Pixi Nightly 现有项目：先向 `pixi.toml` channels 添加：`[workspace]` 和 `channels = ["https://conda.modular.com/max-nightly/", "conda-forge"]`，然后 `pixi add [max / mojo]`。
23. Pixi Stable 新项目：`pixi init [PROJECT] -c https://conda.modular.com/max/ -c conda-forge && cd [PROJECT]`，然后 `pixi add [max / mojo]`，然后 `pixi shell`。
24. Pixi Stable 现有项目：`pixi add [max / mojo]`。
25. 使用 Python 的项目：如果项目使用 Python 库配合 Mojo：`pixi add python`。
26. `pixi add requests`（conda-forge 包）。
27. `pixi add --pypi some-pkg`（仅 PyPI 的包）。
28. `uv`：`uv` 是快速且流行的包管理器，Python 背景开发者熟悉，也适用于 Mojo 项目。
29. uv Nightly（project）：`uv init [PROJECT] && cd [PROJECT]`。
30. uv Nightly（project）：`uv add [max / mojo] --index https://whl.modular.com/nightly/simple/ --prerelease allow`。
31. uv Stable（project）：`uv init [PROJECT] && cd [PROJECT]`。
32. uv Stable（project）：`uv add "max[all]"`。这会从 PyPI 解析。`all` extra 会拉入 `mojo` 和其余 MAX stack，因此 MAX 与 Mojo 版本始终匹配。
33. uv Nightly（quick environment）：`mkdir [PROJECT] && cd [PROJECT]`。
34. uv Nightly（quick environment）：`uv venv`。
35. uv Nightly（quick environment）：`uv pip install [max / mojo] --index https://whl.modular.com/nightly/simple/ --prerelease allow`。
36. uv Stable（quick environment）：`mkdir [PROJECT] && cd [PROJECT]`。
37. uv Stable（quick environment）：`uv venv`。
38. uv Stable（quick environment）：`uv pip install "max[all]"`。
39. 使用 `uv` 时，可在项目环境中直接使用 `max` 或 `mojo`：`source .venv/bin/activate`。
40. `pip`：标准 Python 包管理器。
41. pip Nightly：`python3 -m venv .venv && source .venv/bin/activate`。
42. pip Nightly：`pip install --pre [max / mojo] --extra-index-url https://whl.modular.com/nightly/simple/`。
43. 使用 `--extra-index-url`，不要使用 `--index-url`。后者会替换 PyPI，而 nightly index 不包含像 `numpy` 这样的第三方依赖，所以 `pip` 会回溯每个 `max` 版本，而不是给出清晰错误。
44. pip Stable：`python3 -m venv .venv && source .venv/bin/activate`。
45. pip Stable：`pip install "max[all]"`。
46. 与 `uv` 一样，`all` extra 也会安装 `mojo`，因此 MAX 与 Mojo 版本始终匹配。
47. Conda：适用于 `conda` 和 `mamba` 用户。
48. Conda Nightly：`conda install -c conda-forge -c https://conda.modular.com/max-nightly/ [max / mojo]`。
49. Conda Stable：`conda install -c conda-forge -c https://conda.modular.com/max/ [max / mojo]`。
50. 与 MAX 的版本对齐：如果使用 MAX 和自定义 Mojo kernels，两者必须来自同一 channel。不要比较版本号：MAX 和 Mojo 编号方式不同，匹配的一对看起来像不匹配（stable 是 `max` `26.5` 配 `mojo` `1.0.0`）。
51. 检查两者来自同一 channel：`pixi list | grep -E "^(max|mojo)\b"`。
52. 或者安装 `max[all]`（用 pip/uv）或 `max-all`（用 conda/pixi）：`uv add "max[all]"`。
53. 或者安装 `max[all]`（用 pip/uv）或 `max-all`（用 conda/pixi）：`pixi add max-all`。
54. 安装带 "all" optional dependencies 的 `max`，而不是分别安装 `max` 和 `mojo`，可确保 `max` 和 `mojo` 版本始终匹配。混用两者版本会导致 kernel 编译失败。
55. 参考资料：[Mojo Installation Guide](https://mojolang.org/install)、[Mojo Stable Docs](https://mojolang.org/docs/)、[Mojo Nightly Docs](https://mojolang.org/nightly/docs/)。

适用边界 · 注意事项

• 非 Mojo/MAX 项目或不需要创建 Mojo/MAX 环境时不适用。
• Windows 原生环境不适用；Mojo 不能在 Windows 原生运行，需先安装 WSL2 并按 Linux 说明操作。
• 不要使用 `magic`；它已弃用，相关能力已由 `pixi` 取代。