面向开发环境的安全安装编排器：把精简配置展开成可解释、可并发、可恢复的执行计划。
➡️ 这是什么 | 安装 | 快速开始 | 能力地图 | 模式与命令 | 安全与恢复 | 文档 ⬅️
🤔 这是什么
BotForge 是开发环境安装编排器。你选择内置 profile 或提供一份短配置，它会先检测机器现状，再把组件、provider、依赖、平台差异和资源约束展开为不可变执行计划，确认后才执行安装。
配置、规划、执行和状态彼此分离：
| 结果 | 回答的问题 |
|---|---|
| 环境检测 | 当前机器已有和缺少什么，哪些后端可用？ |
| 执行计划 | 将使用哪些 provider、版本、依赖、资源和安装顺序？ |
| 事务状态 | 哪些组件已完成，失败后能否继续，缓存是否可信？ |
BotForge 不把任意命令包装成“安全安装”。Cargo、archive、Git、APT、Homebrew、rustup、npm、pip、uv-tool 和 winget 使用类型化后端；Shell 必须显式启用，且不享有托管工件的原子回滚承诺。系统包管理器造成的全局修改也不会被伪装成完全托管状态。
🛠️ 安装
从源码构建需要 Rust 1.91+、edition 2024 和 Cargo：
BotForge 支持 Linux、macOS 和 Windows；具体安装后端取决于当前平台和用户授权。使用 APT、Homebrew 或 winget 时，需要相应系统权限。第一次试用只需运行 doctor，实际选中某个后端后再准备其依赖。
发布附件可用时，仓库的 install.sh / install.ps1 会下载匹配平台的二进制并校验 SHA256SUMS。运行前必须从可信发布页面取得清单摘要并设置 BOT_FORGE_CHECKSUMS_SHA256；附件尚未发布时使用源码安装。官方目标以 Release 中实际存在的资产为准。
🚀 快速开始
交互终端中直接启动：
选择环境级别后，BotForge 会检测现状、展示缺口并请求确认，然后安装和复查。需要把审查与执行分开时：
# 检查环境和配置
# 只生成计划，不修改系统
# 确认后安装并检查状态
非交互环境不会把管道 stdin 当成授权，必须明确确认并选择机器输出：
🗺️ 能力地图
flowchart LR
A[短配置 + catalog + overlay] --> B[严格加载与展开]
B --> C[环境检测与 provider 选择]
C --> D[不可变执行计划]
D --> E[资源感知 DAG]
E --> F[获取 / 验证 / 激活]
F --> G[注册表 / 事务 / 缓存]
D --> H[Human / JSON]
G --> H
| 能力 | BotForge 如何处理 |
|---|---|
| 严格配置 | 未知字段、循环依赖、浮动 Cargo 版本和未固定 Git revision 在规划前失败。 |
| 可解释计划 | plan --why 与 config explain 展示来源、依赖、平台、资源和 catalog digest。 |
| 类型化后端 | 每种安装来源使用明确字段与验证规则；Shell 默认关闭。 |
| 资源调度 | 按 DAG、网络、CPU、内存、磁盘、host token 和命名锁安排并发。 |
| 托管工件 | 下载、构建、校验、store 与 activate 分阶段执行，内容身份不符时拒绝复用。 |
| 事务恢复 | 日志绑定 config/plan hash，resume 只继续同一计划中的未完成组件。 |
| 机器边界 | 交互界面和 JSON/JSONL 来自同一状态模型，非 TTY 要求显式授权。 |
🧭 模式与命令
内置 profile 逐级追加能力：
minimal → standard → advanced
| Profile | 在上一级基础上获得什么 | 什么时候选 |
|---|---|---|
minimal |
Rust toolchain、基础构建环境和 RustBot | 只需要可用的 Rust 开发起点。 |
standard |
日常开发、质量门禁、Miri、Fuzz 和自动化工具 | 日常开发、团队协作、CI 或运行时检查。 |
advanced |
Bindgen、Valgrind 和大型工程分析工具 | FFI 开发、深度诊断或大型工程工作流。 |
选择一个 profile 会包含它左侧的全部能力。平台不支持的可选根组件会自动排除；已选组件的必需依赖不可用时则明确失败，不会生成看似成功的不完整环境。
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
平台差异由计划明确展示：cargo-valgrind 及 Valgrind 依赖只在 Linux 进入计划；Miri 使用 nightly rustup component；rustfmt 和 clippy 随 Rust toolchain 安装，因此不在 profile 中重复列出。
日常入口：
| 任务 | 命令 |
|---|---|
| 准备配置 | config init/validate/effective/explain |
| 预览与执行 | plan、install |
| 查看与恢复 | status、resume |
| 删除托管组件 | remove --dry-run 后再执行 remove |
| 缓存治理 | cache status/gc |
| 环境诊断 | doctor |
| 生成契约 | generate |
最小配置只引用受信 catalog：
= "rust-dev"
只覆盖项目实际差异，不复制完整规范配置：
[]
= 12
[]
= ["cargo-watch"]
= ["miri"]
config effective 用于审计展开后的事实，不建议把它重新作为手写配置。完整命令和配置字段见命令手册与配置策略。
🛡️ 安全与恢复
| 场景 | BotForge 的保障 | 你需要做什么 |
|---|---|---|
| 安装并发 | 相同包管理器、工件、二进制和环境目标使用命名锁；阶段结束即释放资源。 | 用 plan --why 先检查依赖与资源。 |
| 中断或失败 | 第一次 Ctrl-C 优雅取消并终止进程树；事务日志保留未完成状态。 | 运行 status；确认计划未变后使用 resume。 |
| 缓存复用 | 来源、版本和内容身份全部匹配才视为命中；损坏工件不会激活。 | 用 cache status 检查占用和命中情况。 |
| 删除与回收 | remove 只处理注册表内的托管目标；GC 在独占锁下回收无引用内容。 |
先运行 remove --dry-run，再确认删除。 |
每个组件都经过获取/构建、校验、存储、激活和登记等适用阶段。完整命令输出写入受限日志，终端只展示有界摘要，代理凭据和敏感配置统一脱敏。
系统包管理器、用户显式启用的 Shell 和上游包供应链仍属于外部风险，BotForge 不会把它们描述成完全可回滚的托管事务。
需要调优时按三步进行：
plan --why：确认依赖和资源声明是否合理；- JSONL 中的
resource-wait：定位真正等待的资源； - cold/warm wall time、峰值内存、下载量和失败率：判断 policy 调整是否有效。
完整并发、取消和缓存模型见效率与并发。
📚 文档
| 入口 | 适合解决的问题 |
|---|---|
| 使用手册 | 从安装、配置到恢复与安全的完整阅读路径。 |
| 命令与日常维护 | 预览、安装、状态、恢复和缓存操作。 |
| 配置策略 | catalog、profile、overlay 与类型化来源。 |
| 计划与 DAG | 依赖闭包、冻结计划和结果传播。 |
| 效率与并发 | 资源预算、动态 Cargo jobs 和跨进程协调。 |
| 产物与恢复 | 注册表、事务日志、缓存和回滚边界。 |
| 机器输出 | JSON/JSONL、退出码与终端行为。 |
| 安全模型 | 信任边界、供应链控制和残余风险。 |
官方仓库位于 GitCode。发布附件和平台支持以对应 tag 的实际 Release 资产与验证记录为准。