# 导言：从命令清单到安全安装计划
为一台新机器准备开发环境，看起来只需列出工具、逐条运行安装命令，再检查它们是否
存在。工具很少、机器只使用一次时，这种方法通常足够；但当清单包含 Rust toolchain、
多种 Cargo 工具、Node.js、Python、系统编译器和组织镜像时，安装就成为状态管理问题。
多个 Cargo 构建会争用 CPU、内存和注册表缓存，两个组件可能生成同名二进制文件，网络
中断也可能发生在下载之后、激活之前。系统包管理器可能已经修改全局状态，而最终版本
检查仍然失败；自动化还可能把管道输入误当成用户授权。
因此需要回答四个问题：执行前能否解释所有动作，哪些工作可以安全并发，验证过的结果
怎样复用，以及中断发生在哪个提交点。只有明确这些事实，才能判断哪些修改可以
回滚，哪些只能报告并交由用户处置。
`bot-forge` 围绕这些问题设计：先把配置编译成执行计划，再执行；先验证工件，再对外激活；先记录事务阶段，再提交托管注册表状态。
本手册沿着这条链路解释如何使用工具，以及为什么这些边界对效率和安全同样重要。
## 本书讨论什么
读完导言后，你应能区分输入、计划、执行和持久状态，并理解后续章节为什么不把它们
合并为一条脚本路径。
完整链路如下：
```text
用户短配置 + 内置配方目录 + site 覆盖层
|
v
严格加载与规范化展开
|
v
组件选择、平台变体与依赖解析
|
v
不可变执行计划与配置/计划哈希
|
v
资源感知 DAG 调度与类型化安装后端
|
v
Detect / Acquire transaction
|
v
事务日志 / 托管注册表 / 缓存
|
v
人类可读输出 / JSON / Diagnostics
```
每一层承担不同责任：
- **输入层**决定用户想要哪些工具、允许哪些网络和 Shell 行为，以及组织差异从哪里进入。
- **展开层**把短格式还原成规划器能完整审计的事实，并为每个字段保留来源。
- **规划层**只做确定性选择和 DAG 构建，不安装软件，也不在加载配置期间探测网络。
- **调度层**只在依赖满足且资源可分配时启动组件；Cargo 子进程的内部 jobs 会按已分配 CPU 与启动时剩余容量动态缩小。
- **安装后端层**把 Cargo、archive、APT 等能力表达为类型化操作，避免把所有行为降级成字符串 Shell。
- **事务层**区分“已经构建”“已经激活”和“已经提交状态”，让恢复动作建立在明确阶段上。
- **输出层**把人类交互与机器协议分开，保证 JSON 不被进度条和提示语污染。
如果这些层混在一起，预览与真正执行可能不是同一套决策，并发数也可能只限制进程数量，却没有限制每个 Cargo 子进程的 jobs。
此外，缓存命中可能跳过校验；托管注册表可能写入成功，但二进制文件只激活了一半；恢复命令也可能在配置变化后盲目重放旧动作。
## 谁适合阅读
| 开发者 | 在新机器上获得可用 Rust 开发环境 | 导言 -> 第一至三章 |
| 工具链维护者 | 维护安装级别、版本、内部源和平台变体 | 基础篇 -> 第五、八章 |
| CI/Agent 作者 | 无交互执行并稳定解析结果 | 第三章 -> 第八章 -> 第十一章 |
| 项目维护者 | 扩展安装后端、调度、状态或输出 | 全书，重点阅读专家篇 |
如果只想尽快开始，可以直接进入[第二章](02-getting-started.md)。如果当前最关心“多个 Cargo 工具到底如何并发”，可以先读[第六章](06-efficiency-and-concurrency.md)，再回到配置章节理解资源策略的来源。
## 三条贯穿全书的原则
第一，**计划必须与执行一致**。`plan` 和 `install` 使用同一个规划器；执行器接收已经验证的不可变计划，不在执行中重新解释配置。
第二，**安全并发依赖资源语义，而不是只提高线程数**。所有安装后端的依赖闭包进入同一 DAG；依赖状态、CPU/内存/网络 token、包管理器、指纹、二进制文件名和托管注册表写锁共同决定组件何时可以运行。
第三，**恢复必须绑定原始事实**。事务日志保存配置哈希与计划哈希。配置、组件选择或目标平台变化后，`resume` 会拒绝把旧 run 当成当前执行计划继续执行。
## 本地证据与外部证据
文档会区分三类结论：代码和测试定义了什么、本机实际测量了什么、远端 CI 或 Release 是否真的运行成功。
Workflow 文件存在不等于远端任务已经通过；安装脚本能够构造 URL 也不等于附件已经上传；Windows ARM64 能编译也不等于某次 Release 提供可下载二进制文件。
这种区分与安装事务本身遵循同一个原则：只依据已经取得的证据声明状态。
---