<div align="center" markdown="1">
<p>
<img src="assets/BotForge.png" alt="RustBot Forge 主视觉" width="680">
</p>
**面向开发环境的安全安装编排器：把精简配置展开成可解释、可并发、可恢复的执行计划。**
[](https://gitcode.com/xuanwu/bot-forge)
</div>
---
<a id="what"></a>
## 🤔 这是什么
BotForge 是开发环境安装编排器。你选择内置安装级别或提供一份短配置，它会先检测机器现状，再把组件、能力提供者、依赖、平台差异和资源约束展开为不可变执行计划，确认后才执行安装。
配置、规划、执行和状态彼此分离：
| 环境检测 | 当前机器已有和缺少什么，哪些后端可用？ |
| 执行计划 | 将使用哪些能力提供者、版本、依赖、资源和安装顺序？ |
| 事务状态 | 哪些组件已完成，失败后能否继续，缓存是否可信？ |
BotForge 不把任意命令包装成“安全安装”。Cargo、archive、Git、APT、Homebrew、rustup、npm、pip、uv-tool 和 winget 使用类型化后端；Shell 必须显式启用，且不享有托管工件的原子回滚承诺。系统包管理器造成的全局修改也不会被伪装成完全托管状态。
---
<a id="install"></a>
## 🛠️ 安装
从源码构建需要 Rust `1.89+`、edition 2024 和 Cargo：
```bash
git clone https://gitcode.com/xuanwu/bot-forge.git
cd bot-forge
cargo install --path . --locked
bot-forge doctor
```
BotForge 支持 Linux、macOS 和 Windows；具体安装后端取决于当前平台和用户授权。使用 APT、Homebrew 或 winget 时，需要相应系统权限。第一次试用只需运行 `doctor`，实际选中某个后端后再准备其依赖。
发布附件可用时，仓库的 `install.sh` / `install.ps1` 会下载匹配平台的二进制并校验 `SHA256SUMS`。运行前必须从可信发布页面取得清单摘要并设置 `BOT_FORGE_CHECKSUMS_SHA256`；附件尚未发布时使用源码安装。官方目标以 Release 中实际存在的资产为准。
---
<a id="start"></a>
## 🚀 快速开始
交互终端中直接启动：
```bash
bot-forge
```
选择环境级别后，BotForge 会检测现状、展示缺口并请求确认，然后安装和复查。需要把审查与执行分开时：
```bash
# 检查环境和配置
bot-forge doctor
bot-forge config init
bot-forge config validate --config bot-forge.toml
# 只生成计划，不修改系统
bot-forge plan standard --why
# 确认后安装并检查状态
bot-forge install standard
bot-forge status standard
```
非交互环境不会把管道 stdin 当成授权，必须明确确认并选择机器输出：
```bash
bot-forge install standard --yes --format json
```
---
<a id="map"></a>
## 🗺️ 能力地图
```mermaid
flowchart LR
A[短配置 + 配方目录 + 覆盖层] --> B[严格加载与展开]
B --> C[环境检测与能力提供者选择]
C --> D[不可变执行计划]
D --> E[资源感知 DAG]
E --> F[获取 / 验证 / 激活]
F --> G[注册表 / 事务 / 缓存]
D --> H[人类可读输出 / JSON]
G --> H
```
| 严格配置 | 未知字段、循环依赖、浮动 Cargo 版本和未固定 Git revision 在规划前失败。 |
| 可解释计划 | `plan --why` 与 `config explain` 展示来源、依赖、平台、资源和配方目录摘要。 |
| 类型化后端 | 每种安装来源使用明确字段与验证规则；Shell 默认关闭。 |
| 资源调度 | 按 DAG、网络、CPU、内存、磁盘、host token 和命名锁安排并发。 |
| 托管工件 | 下载、构建、校验、存储与激活分阶段执行，内容身份不符时拒绝复用。 |
| 事务恢复 | 日志绑定配置和计划哈希，`resume` 只继续同一计划中的未完成组件。 |
| 机器边界 | 交互界面和 JSON/JSONL 来自同一状态模型，非 TTY 要求显式授权。 |
---
<a id="usage"></a>
## 🧭 模式与命令
内置安装级别逐级追加能力：
```text
minimal → standard → advanced
```
| `minimal` | Rust toolchain、基础构建环境和 RustBot | 只需要可用的 Rust 开发起点。 |
| `standard` | 日常开发、质量门禁、Miri、Fuzz 和自动化工具 | 日常开发、团队协作、CI 或运行时检查。 |
| `advanced` | Bindgen 和工程自动化工具 | FFI 开发、深度诊断或大型工程工作流。 |
选择一个安装级别会包含它左侧的全部能力。平台不支持的可选根组件会自动排除；已选组件的必需依赖不可用时则明确失败，不会生成看似成功的不完整环境。
<details>
<summary>查看各层新增的精确组件</summary>
**`minimal` 基础组件**
`rust-build-base`, `rust-toolchain`, `rust-bot`
**`standard` 追加项**
`git`, `cmake`, `ninja`, `python`, `llvm-toolchain`, `rust-analyzer`, `rust-src`, `miri`, `cargo-fuzz`, `nodejs`, `tsx`, `openspec`, `cargo-expand`, `cargo-nextest`, `cargo-audit`, `cargo-deny`, `cargo-geiger`, `cargo-llvm-cov`, `bot-gate`, `bot-metric`, `cargo-valgrind`
**`advanced` 追加项**
`bindgen-cli`, `uv`, `project-brain`, `gitnexus`
</details>
平台差异由计划明确展示：`cargo-valgrind` 及 Valgrind 依赖只在 Linux 进入计划；Miri 使用 nightly rustup component；`rustfmt` 和 `clippy` 随 Rust toolchain 安装，因此不在安装级别中重复列出。
日常入口：
| 准备配置 | `config init/validate/effective/explain` |
| 预览与执行 | `plan`、`install` |
| 查看与恢复 | `status`、`resume` |
| 删除托管组件 | `remove --dry-run` 后再执行 `remove` |
| 缓存治理 | `cache status/gc` |
| 环境诊断 | `doctor` |
| 生成契约 | `generate` |
最小配置只引用受信配方目录：
```toml
catalog = "rust-dev"
```
只覆盖项目实际差异，不复制完整规范配置：
```toml
[policy]
max_parallel = 12
[profiles.standard]
add = ["cargo-watch"]
remove = ["miri"]
```
`config effective` 用于审计展开后的事实，不建议把它重新作为手写配置。完整命令和配置字段见[命令手册](docs/manual/03-commands.md)与[配置策略](docs/manual/04-configuration.md)。
---
<a id="safety"></a>
## 🛡️ 安全与恢复
| 安装并发 | 相同包管理器、工件、二进制和环境目标使用命名锁；阶段结束即释放资源。 | 用 `plan --why` 先检查依赖与资源。 |
| 中断或失败 | 第一次 Ctrl-C 优雅取消并终止进程树；事务日志保留未完成状态。 | 运行 `status`；确认计划未变后使用 `resume`。 |
| 缓存复用 | 来源、版本和内容身份全部匹配才视为命中；损坏工件不会激活。 | 用 `cache status` 检查占用和命中情况。 |
| 删除与回收 | `remove` 只处理注册表内的托管目标；GC 在独占锁下回收无引用内容。 | 先运行 `remove --dry-run`，再确认删除。 |
每个组件都经过获取/构建、校验、存储、激活和登记等适用阶段。完整命令输出写入受限日志，终端只展示有界摘要，代理凭据和敏感配置统一脱敏。
系统包管理器、用户显式启用的 Shell 和上游包供应链仍属于外部风险，BotForge 不会把它们描述成完全可回滚的托管事务。
需要调优时按三步进行：
1. `plan --why`：确认依赖和资源声明是否合理；
2. JSONL 中的 `resource-wait`：定位真正等待的资源；
3. 冷启动/热启动耗时、峰值内存、下载量和失败率：判断策略调整是否有效。
完整并发、取消和缓存模型见[效率与并发](docs/manual/06-efficiency-and-concurrency.md)。
---
<a id="docs"></a>
## 📚 文档
| [使用手册](docs/manual/README.md) | 从安装、配置到恢复与安全的完整阅读路径。 |
| [命令与日常维护](docs/manual/03-commands.md) | 预览、安装、状态、恢复和缓存操作。 |
| [配置策略](docs/manual/04-configuration.md) | 配方目录、安装级别、覆盖层与类型化来源。 |
| [计划与 DAG](docs/manual/05-planning-and-dag.md) | 依赖闭包、冻结计划和结果传播。 |
| [效率与并发](docs/manual/06-efficiency-and-concurrency.md) | 资源预算、动态 Cargo jobs 和跨进程协调。 |
| [产物与恢复](docs/manual/07-artifacts-and-recovery.md) | 注册表、事务日志、缓存和回滚边界。 |
| [机器输出](docs/manual/08-output-and-interaction.md) | JSON/JSONL、退出码与终端行为。 |
| [安全模型](docs/manual/09-security.md) | 信任边界、供应链控制和残余风险。 |
官方仓库位于 [GitCode](https://gitcode.com/xuanwu/bot-forge)。发布附件和平台支持以对应 tag 的实际 Release 资产与验证记录为准。