# bot-forge 使用手册
本手册面向第一次准备 Rust 开发环境的工程师、维护组织级工具链的基础设施团队，以及需要从脚本或 Agent 调用安装能力的工具作者。
`bot-forge` 不只是依次运行一组安装命令。它先把用户配置、内置配方目录、组织覆盖层
和当前平台展开成严格的规范配置，再生成不可变执行计划。所有安装后端共享同一份依赖
闭包和资源感知 DAG；实际资源、包管理器、工件、二进制文件和状态锁决定哪些工作可以
安全重叠。
执行后，工件、事务日志与托管注册表分别记录“验证过的内容”“事务到达的阶段”和
“已经提交的托管状态”。手册按照输入、计划、执行、恢复和维护这条路径组织内容。
## 如何阅读
不必从头读到尾。先按目标选择最短路径：
| 第一次安装 | [第二章](02-getting-started.md) -> [第三章](03-commands.md) |
| 维护组织配置 | [第四章](04-configuration.md) -> [第五章](05-planning-and-dag.md) |
| 调优并发或缓存 | [第六章](06-efficiency-and-concurrency.md) -> [第七章](07-artifacts-and-recovery.md) |
| 接入 CI 或 Agent | [第三章](03-commands.md) -> [第八章](08-output-and-interaction.md) |
| 扩展或发布项目 | [第十章](10-architecture.md) -> [第十一章](11-quality-and-release.md) |
希望先理解设计动机时，从[导言](00-preface.md)开始。
### 基础篇：完成第一次可信安装
1. [认识 bot-forge](01-overview.md)：理解工具解决什么问题、不承诺什么，以及完整生命周期怎样工作。
2. [安装与第一次运行](02-getting-started.md)：构建 CLI，创建短配置，完成诊断、预览、安装和状态检查。
3. [从预览到日常维护](03-commands.md)：按首次安装、自动化、修复、恢复、删除和缓存清理等场景使用命令。
4. [组织配置与安装策略](04-configuration.md)：使用配方目录、group、类型化简写、安装级别和覆盖层。
### 进阶篇：理解效率、安全和恢复
5. [计划、依赖与执行 DAG](05-planning-and-dag.md)：理解不可变计划、依赖闭包、节点结果和稳定身份。
6. [效率、并发与资源调度](06-efficiency-and-concurrency.md)：理解容量 token、阶段租约、动态 Cargo jobs、跨进程公平性、缓存快速路径和性能反馈。
7. [工件、事务与故障恢复](07-artifacts-and-recovery.md)：理解 Acquire 内部的 Fetch、Build、Verify、Store、Activate、Record、事务日志和缓存。
8. [终端交互与机器输出](08-output-and-interaction.md)：正确使用选择器、键盘、取消、人类可读输出、JSON 输出、JSONL 边界和退出码。
9. [安全模型与供应链边界](09-security.md)：理解配置、下载、归档、进程、路径、日志和系统包管理器的信任边界。
### 专家篇：扩展与维护
10. [架构与模块边界](10-architecture.md)：理解当前主流程、`artifact`、`events`、`skills`
等中立能力、公开边界和依赖门禁。
11. [质量、性能与发布边界](11-quality-and-release.md)：建立本地门禁、性能基线、平台验证和 Release 证据链。
12. [工程参考与扩展阅读](12-engineering-reference.md)：查找生成文档、机器 Schema、源码和发布资料。
## 按目标查找
| 尽快完成第一次安装 | [安装与第一次运行](02-getting-started.md) |
| 安装前确认所有副作用 | [从预览到日常维护](03-commands.md#32-先看计划再执行) |
| 缩短 `bot-forge.toml` | [组织配置与安装策略](04-configuration.md#42-推荐短配置) |
| 同时安装多个 Cargo 工具 | [效率、并发与资源调度](06-efficiency-and-concurrency.md#64-外层事务与-cargo-内层-jobs) |
| 理解为什么某个任务在等待 | [效率、并发与资源调度](06-efficiency-and-concurrency.md#63-进程内与跨进程协调) |
| 中断后继续安装 | [工件、事务与故障恢复](07-artifacts-and-recovery.md#78-resume-不是盲目重放) |
| 给 CI 或 Agent 消费输出 | [终端交互与机器输出](08-output-and-interaction.md#87-人类可读输出json-与-quiet-输出) |
| 添加组织镜像或内部源 | [组织配置与安装策略](04-configuration.md#49-用覆盖层表达组织差异) |
| 审计 Shell 与供应链风险 | [安全模型与供应链边界](09-security.md) |
| 扩展一种安装后端 | [架构与模块边界](10-architecture.md#105-扩展安装能力) |
| 判断首次正式版本是否可以发布 | [质量、性能与发布边界](11-quality-and-release.md#118-发布结论需要什么证据) |
## 术语与写法
正文优先使用中文概念，配置字段、事件、Rust 类型和源码模块保留原名。下表固定两者的对应关系，避免同一概念在章节之间反复换名。
| 配方目录 | `catalog` | 可复用的安装配方集合；内置配方目录随程序提供，加载时不访问网络。 |
| 覆盖层 | `overlay` | 按命令行顺序叠加的组织或机器配置层。 |
| 规范配置 | `canonical config` | 简写全部展开后，规划器实际消费并参与哈希计算的完整配置。 |
| 安装级别 | `profile` | 按安装深度逐级继承的组件集合，例如 `minimal`、`standard` 和 `advanced`；操作系统差异由平台选择器自动处理。 |
| 组件 | `component` | 可检测、安装、验证并声明依赖、平台和资源的逻辑安装单元。 |
| 安装后端 | `backend` | 实现安装能力的类型化提供者，例如 Cargo、APT、Homebrew、archive 或 rustup。 |
| 执行计划 | `ExecutionPlan` / `plan` | 配置与平台解析后得到的不可变 DAG，包含组件、节点、资源声明和 hash。 |
| 指纹 | `fingerprint` | 由 Cargo 坐标、features、target、toolchain 等确定输入计算出的构建身份。 |
| 工件 | `artifact` | 已校验的二进制文件集及来源信息，保存在工件存储中。 |
| 激活 | `activation` | 原子切换 Unix symlink 或 Windows `.exe` 副本。 |
| 事务日志 | `journal` | 记录一次 run 在 Store、Activate、Record 各阶段状态的恢复依据。 |
| 托管注册表 | `registry` | 记录已提交托管状态的严格文档；`revision` 表示锁内提交顺序。 |
| 资源声明 | `resource claim` | 节点对 network、CPU、memory、disk 或命名锁的需求。 |
| 生命周期事件 | `lifecycle event` | 安装运行期间产生的有序事实；与事务日志 `checkpoint` 和最终报告不是同一种记录。 |
| 遥测摘要 | `telemetry summary` | 本机 Cargo 构建样本、工件命中和预计节省时间；不参与状态正确性判断。 |
统一写法还有三条：
- 中文正文使用“组件、安装后端、执行计划、工件、事务日志、托管注册表、资源声明”；引用字段、类型或事件时使用反引号内的原名。
- `plan` 表示命令或 JSON 名称，Rust 类型写作 `ExecutionPlan`；普通叙述统一写“执行计划”。
- “包管理器”用于普通叙述，`package-manager:*` 只表示真实资源 key；协议名统一写 `JSON` / `JSONL`。
命令、字段、文件和状态使用代码格式，例如 `bot-forge plan`、`max_downloads`、`Stored` 和 `registry-write`。
---