bot-forge 1.0.2

Rust CLI for installing agent skills and developer tools from configurable forms.
Documentation

面向开发环境的安全安装编排器：把精简配置展开成可解释、可并发、可恢复的执行计划。

➡️ 这是什么 | 安装 | 快速开始 | 能力地图 | 模式与命令 | 安全与恢复 | 文档 ⬅️

Rust CLI Status Config Output Platforms

🤔 这是什么

BotForge 是开发环境安装编排器。你选择内置安装级别或提供一份短配置，它会先检测机器现状，再把组件、能力提供者、依赖、平台差异和资源约束展开为不可变执行计划，确认后才执行安装。

配置、规划、执行和状态彼此分离：

结果 回答的问题
环境检测 当前机器已有和缺少什么，哪些后端可用？
执行计划 将使用哪些能力提供者、版本、依赖、资源和安装顺序？
事务状态 哪些组件已完成，失败后能否继续，缓存是否可信？

BotForge 不把任意命令包装成“安全安装”。Cargo、archive、Git、APT、Homebrew、rustup、npm、pip、uv-tool 和 winget 使用类型化后端；Shell 必须显式启用，且不享有托管工件的原子回滚承诺。系统包管理器造成的全局修改也不会被伪装成完全托管状态。

🛠️ 安装

从源码构建需要 Rust 1.89+、edition 2024 和 Cargo：

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 中实际存在的资产为准。

🚀 快速开始

交互终端中直接启动：

bot-forge

选择环境级别后，BotForge 会检测现状、展示缺口并请求确认，然后安装和复查。需要把审查与执行分开时：

# 检查环境和配置

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 当成授权，必须明确确认并选择机器输出：

bot-forge install standard --yes --format json

🗺️ 能力地图

flowchart LR
    A[短配置 + 配方目录 + 覆盖层] --> B[严格加载与展开]
    B --> C[环境检测与能力提供者选择]
    C --> D[不可变执行计划]
    D --> E[资源感知 DAG]
    E --> F[获取 / 验证 / 激活]
    F --> G[注册表 / 事务 / 缓存]
    D --> H[人类可读输出 / JSON]
    G --> H
能力 BotForge 如何处理
严格配置 未知字段、循环依赖、浮动 Cargo 版本和未固定 Git revision 在规划前失败。
可解释计划 plan --why 与 config explain 展示来源、依赖、平台、资源和配方目录摘要。
类型化后端 每种安装来源使用明确字段与验证规则；Shell 默认关闭。
资源调度 按 DAG、网络、CPU、内存、磁盘、host token 和命名锁安排并发。
托管工件 下载、构建、校验、存储与激活分阶段执行，内容身份不符时拒绝复用。
事务恢复 日志绑定配置和计划哈希，resume 只继续同一计划中的未完成组件。
机器边界 交互界面和 JSON/JSONL 来自同一状态模型，非 TTY 要求显式授权。

🧭 模式与命令

内置安装级别逐级追加能力：

minimal → standard → advanced
安装级别 在上一级基础上获得什么 什么时候选
minimal Rust toolchain、基础构建环境和 RustBot 只需要可用的 Rust 开发起点。
standard 日常开发、质量门禁、Miri、Fuzz 和自动化工具 日常开发、团队协作、CI 或运行时检查。
advanced Bindgen 和工程自动化工具 FFI 开发、深度诊断或大型工程工作流。

选择一个安装级别会包含它左侧的全部能力。平台不支持的可选根组件会自动排除；已选组件的必需依赖不可用时则明确失败，不会生成看似成功的不完整环境。

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 安装，因此不在安装级别中重复列出。

日常入口：

任务 命令
准备配置 config init/validate/effective/explain
预览与执行 plan、install
查看与恢复 status、resume
删除托管组件 remove --dry-run 后再执行 remove
缓存治理 cache status/gc
环境诊断 doctor
生成契约 generate

最小配置只引用受信配方目录：

catalog = "rust-dev"

只覆盖项目实际差异，不复制完整规范配置：

[policy]

max_parallel = 12



[profiles.standard]

add = ["cargo-watch"]

remove = ["miri"]

config effective 用于审计展开后的事实，不建议把它重新作为手写配置。完整命令和配置字段见命令手册与配置策略。

🛡️ 安全与恢复

场景 BotForge 的保障 你需要做什么
安装并发 相同包管理器、工件、二进制和环境目标使用命名锁；阶段结束即释放资源。 用 plan --why 先检查依赖与资源。
中断或失败 第一次 Ctrl-C 优雅取消并终止进程树；事务日志保留未完成状态。 运行 status；确认计划未变后使用 resume。
缓存复用 来源、版本和内容身份全部匹配才视为命中；损坏工件不会激活。 用 cache status 检查占用和命中情况。
删除与回收 remove 只处理注册表内的托管目标；GC 在独占锁下回收无引用内容。 先运行 remove --dry-run，再确认删除。

每个组件都经过获取/构建、校验、存储、激活和登记等适用阶段。完整命令输出写入受限日志，终端只展示有界摘要，代理凭据和敏感配置统一脱敏。

系统包管理器、用户显式启用的 Shell 和上游包供应链仍属于外部风险，BotForge 不会把它们描述成完全可回滚的托管事务。

需要调优时按三步进行：

  1. plan --why：确认依赖和资源声明是否合理；
  2. JSONL 中的 resource-wait：定位真正等待的资源；
  3. 冷启动/热启动耗时、峰值内存、下载量和失败率：判断策略调整是否有效。

完整并发、取消和缓存模型见效率与并发。

📚 文档

入口 适合解决的问题
使用手册 从安装、配置到恢复与安全的完整阅读路径。
命令与日常维护 预览、安装、状态、恢复和缓存操作。
配置策略 配方目录、安装级别、覆盖层与类型化来源。
计划与 DAG 依赖闭包、冻结计划和结果传播。
效率与并发 资源预算、动态 Cargo jobs 和跨进程协调。
产物与恢复 注册表、事务日志、缓存和回滚边界。
机器输出 JSON/JSONL、退出码与终端行为。
安全模型 信任边界、供应链控制和残余风险。

官方仓库位于 GitCode。发布附件和平台支持以对应 tag 的实际 Release 资产与验证记录为准。