# 第二章：安装与第一次运行
本章在一台普通开发机器上构建 `bot-forge`，生成严格短配置，并完成“诊断 -> 计划 -> 安装 -> 状态检查”的第一次闭环。
这条流程中只有 `install` 会执行安装副作用；`config validate`、`doctor` 和 `plan` 都适合在真正修改机器前使用。
本章的最短成功路径是：准备构建条件 -> 创建配置 -> 诊断 -> 预览计划 -> 安装 -> 检查
状态。每一步都给出下一步判断依据，不需要先理解全部内部实现。
## 2.1 准备条件
从源码构建需要：
- Rust stable 与 Cargo；
- Git，用于取得源码；
- Linux GNU x86_64/AArch64、macOS 12+ Intel/Apple Silicon，或 Windows 10/11 x64/ARM64 MSVC 开发环境。
| Linux | Debian/Ubuntu、APT | 默认配方不覆盖 musl/Alpine |
| macOS | Homebrew、Xcode Command Line Tools | CLI 不自动安装 Homebrew |
| Windows | winget、MSVC Build Tools | 使用 MSVC 目标与 PowerShell 安装器 |
预编译安装脚本可以让目标机器免装 Rust，但前提是对应系统和架构的附件已经实际上传并通过下载校验。
公开附件尚未上传时，本章使用源码构建路径；附件发布后，安装脚本从 release 或 `BOT_FORGE_BASE_URL` 指定的内部目录下载并校验当前平台工件。
安装脚本把可执行文件写入 bin 目录，把入口配置写入平台配置目录；设置 `BOT_FORGE_CONFIG_DIR` 时使用该目录。这与 CLI 后续的自动发现规则一致。
`BOT_FORGE_HOME` 只控制状态、缓存和工件数据根。重复运行只更新二进制文件，不覆盖已经存在的用户配置。
安装具体级别还可能需要网络、系统包管理器、管理员权限或组织代理。`doctor --format json` 会检查常见前置条件，但不能替代软件仓库自身的权限和可用性。
macOS CLI 的最低构建目标是 12.0。默认安装级别还需要当前系统可用的 [Homebrew](https://brew.sh/) 和 Xcode Command Line Tools，上游 formula 可能有更高系统要求。
先运行 `xcode-select --install` 并按 Homebrew 官方方式完成安装。bot-forge 只调用已存在的 `brew`，不会自动执行 Homebrew 的远程安装脚本；`doctor` 会分别检查 `brew` 与 `xcrun`。
Linux 默认配方目录使用 APT，当前正式发布范围是 Debian/Ubuntu 系 GNU libc x86_64/AArch64；musl/Alpine 和其他包管理器不属于默认配方。
Windows 默认配方目录使用 winget 和 MSVC Build Tools，需要 App Installer/winget；PowerShell 安装器兼容 Windows PowerShell 5.1 与 PowerShell 7。
## 2.2 从源码构建
进入仓库后执行：
```bash
cargo build --release --locked
./target/release/bot-forge --version
```
`--locked` 要求构建严格使用 `Cargo.lock`。如果希望在任意目录直接运行：
```bash
cargo install --path . --locked
bot-forge --version
```
源码构建成功只证明当前机器能够构建 CLI，不代表 Release 附件已经上传，也不代表其他目标平台已经完成真实安装。正式发布结论仍必须以实际 Release job、附件 checksum 和三平台安装 smoke 为准。
## 2.3 创建最小配置
在希望保存用户入口配置的目录中运行：
```bash
bot-forge config init
bot-forge config init --output /path/to/bot-forge.toml
```
命令创建 `bot-forge.toml`，如果文件已存在则停止。只有确认要替换时才使用：
```bash
bot-forge config init --force
```
生成内容只声明 `rust-dev` 配方目录。安全策略、三个默认安装级别和完整安装配方都留在内置配方目录中，不会复制到用户文件；需要修改时只写差异。
## 2.4 校验并理解配置
先检查 Schema、引用、版本、平台和安全策略：
```bash
bot-forge config validate --config bot-forge.toml
```
再查看来源和展开关系：
```bash
bot-forge config explain --config bot-forge.toml
```
`explain` 会列出配方目录、摘要来源、组、绑定版本、Cargo 简写与覆盖层来源。需要审计规划器实际消费的完整配置时运行：
```bash
bot-forge config effective --config bot-forge.toml
```
`effective` 很长是正常的。它是规范配置的审计视图，不是推荐手写格式。
## 2.5 运行系统诊断
```bash
bot-forge doctor
```
无参数 `doctor` 以便于人阅读的格式显示完整检查。机器读取使用：
```bash
bot-forge doctor --format json
```
两种模式使用同一组平台、包管理器、代理、权限、磁盘、锁目录、缓存、待处理事务日志、配置来源以及 DNS/TLS endpoint 检查，区别只有序列化格式。
要诊断非默认配置，可添加 `--config <path>`；该路径会被实际加载，而不是只检查文件是否存在。macOS 还会验证 `xcrun --find clang` 并报告进程是否运行在 Rosetta 2 下。
代理诊断只报告配置项数量，不输出认证信息。单项诊断通过也不意味着所有安装级别组件已经安装；`status` 才回答组件检测和托管状态。
macOS 的默认目录如下：
| 数据根 | `~/Library/Application Support/bot-forge` |
| 配置根 | `~/Library/Application Support/bot-forge/config` |
| 托管命令 | 数据根下的 `bin` |
路径含空格属于正常情况。CLI 在每次组件检测前会把自己的托管 bin 前置到进程 PATH，因此 `status`、交互选择和安装后复检不依赖父 shell 是否已经重载配置。
如果希望在 bot-forge 外直接运行托管命令，CLI 会按当前 shell 持久化 PATH：
| zsh | `~/.zprofile` |
| bash | `~/.bash_profile` |
| fish | `~/.config/fish/config.fish` |
未知 shell 会明确拒绝持久化，避免写入不会被读取的文件。
即使非登录 GUI 环境没有 Homebrew PATH，CLI 也会探测 Apple Silicon 的 `/opt/homebrew/bin/brew` 和 Intel 的 `/usr/local/bin/brew`。
## 2.6 选择安装级别
默认配方目录提供三个逐级继承的跨平台等级：
| `minimal` | 最小 Rust 构建环境 | 构建基础、Rust toolchain |
| `standard` | 日常开发与质量环境 | 继承 `minimal`，增加开发、审计、覆盖率、Miri、fuzz、Valgrind 和常用自动化工具 |
| `advanced` | 高级工程环境 | 继承 `standard`，增加 Bindgen 和工程分析工具 |
平台专属组件由目标平台自动筛选，不需要用户选择操作系统安装级别。`standard` 中的 Valgrind 只会在 Linux 进入执行计划；在 macOS 或 Windows 的组件选择页仍会显示为不可用项，不会阻断安装。
预编译的 bot-forge 二进制文件可以在尚未安装 Rust/rustup 的目标机器执行 `minimal`。默认配方目录会下载固定版本的 `rustup-init`，验证当前平台 SHA-256 后无交互引导，再安装固定 Rust toolchain、rustfmt 与 clippy。
rustfmt 与 clippy 是该固定 toolchain 的 rustup components，不会在安装级别表中作为两个
独立组件重复出现。Miri 同样由 rustup 分发，但要求 nightly 和 `rust-src`，因此在
`standard` 中作为独立组件安装；不要用 `cargo install miri` 替代。
源码构建 bot-forge 本身需要 Rust 1.89 或更新的 stable toolchain 与 Cargo。默认配方目录
同样固定安装 Rust 1.89.0，并用该工具链构建受管 Cargo 工具。
## 2.7 先生成计划
```bash
bot-forge plan standard --why --config bot-forge.toml
```
执行计划会展示组件、能力提供者、依赖、资源和来源。它不修改系统。
需要保存机器可读计划时：
```bash
bot-forge plan standard --format json --config bot-forge.toml > plan.json
```
可以只选择或排除部分组件：
```bash
bot-forge plan standard --only cargo-audit --why
# 仅 Linux
bot-forge plan standard --only cargo-valgrind --why
```
依赖仍由解析器处理；`--only` 不是让用户绕过所需前置项。显式选择当前平台不支持的组件会返回错误，不会生成空计划。
## 2.8 执行安装
第一次在交互终端中使用，直接运行：
```bash
bot-forge
```
启动页会让用户选择 `minimal`、`standard` 或 `advanced` 安装级别，再进入检测、组件选择与确认流程。需要指定配置路径或精确控制安装级别时，使用显式命令：
```bash
bot-forge install standard --config bot-forge.toml
```
CLI 会先检测组件，随后使用与 `bot-gate` 相同的选择器显示缺失项。`›` 表示当前项，`◉` / `○` 表示选择状态，`✓` 表示已安装，`-` 表示当前平台不可选。常用键位：
| `↑` / `↓`、`J` / `K` | 移动选择 |
| `Space` | 切换当前组件 |
| `A` / `N` | 全选 / 清空 |
| `Enter` | 确认选择 |
| `Esc` / `Q` / `Ctrl-C` | 取消 |
确认选择后，执行计划会自动补齐所选组件的传递依赖。
安装期间可用 Ctrl-C 取消整个 run。工具不会在包管理器或构建命令中途提供不安全的“强制跳过”语义；失败会明确返回失败。
非交互环境不会把 stdin 当作许可。自动化必须显式授权：
```bash
bot-forge install standard --yes --format json --config bot-forge.toml
```
如果只想验证真正执行时将使用的路径，使用 `plan`；它与执行入口共享同一规划器，但不会进入授权和副作用阶段。
## 2.9 检查结果
```bash
bot-forge status standard --config bot-forge.toml
```
输出联合显示当前检测结果、托管注册表修订号、托管安装项和待恢复事务日志。脚本使用：
```bash
bot-forge status standard --format json --config bot-forge.toml
```
若某个组件缺失或验证失败，重新运行安装即可：
```bash
bot-forge install standard --config bot-forge.toml
```
`install` 会重新检测并只处理缺失或验证失败的组件，不会绕过规划器或安全校验。
## 2.10 第一次运行后检查什么
建议确认：
1. `config explain` 中没有意外覆盖层或字段来源；
2. `plan --why` 的组件、能力提供者和资源符合目标平台；
3. 自动化确实使用 `--yes`，人类可读输出与 JSON 输出没有混用；
4. `status` 中没有待恢复事务日志；
5. 新二进制文件来自托管 bin 目录，并符合组织的 PATH 策略；
6. 系统包管理器或 Shell 引起的非托管副作用已经被单独审计。
如果前四项不满足，先不要运行 `remove` 或 `cache gc`；回到 `config explain`、
`plan --why` 或 `resume` 确认事实来源和事务状态。
## 2.11 下一步
下一章按真实场景介绍命令：如何比较计划、处理失败、恢复中断事务、安全删除以及回收无引用缓存。
---