autoforgeai 2.7.28

     _         _        _____
    / \  _   _| |_ ___ |  ___|__  _ __ __ _  ___
   / _ \| | | | __/ _ \| |_ / _ \| '__/ _` |/ _ \
  / ___ \ |_| | || (_) |  _| (_) | | | (_| |  __/
 /_/   \_\__,_|\__\___/|_|  \___/|_|  \__, |\___|
                                       |___/

AI 多智能体框架 — 自主科研推理 · 形式化证明 · 全栈项目生成

English | 开发者文档

目录

• 安装与配置
  • 安装
  • 首次运行引导
  • 支持的 LLM 提供商
  • 系统要求
• 三种工作模式
• 学术与科研能力
  • 端到端文章推理
  • 形式化验证与定理证明
  • 自主科研发现
  • 论文全流程
  • 论文复现管线
  • 核心技术来源
  • 算法优先架构
• 工程能力
  • 5 阶段流水线
  • 6 智能体协作
  • 智能引擎
• CLI 命令参考
• 守护进程模式
• 待落实：DAG 联邦同步

安装与配置

安装

pip install autoforgeai       # 从 PyPI 安装
autoforgeai                  # 启动（首次运行自动进入配置引导）

pip install "autoforgeai[openai]"    # OpenAI 支持
pip install "autoforgeai[google]"    # Google Gemini 支持
pip install "autoforgeai[search]"    # Web 搜索能力
pip install "autoforgeai[channels]"  # Telegram / Webhook 频道
pip install "autoforgeai[all]"       # 全部安装

git clone https://github.com/AlyciaBHZ/autoforge.git
cd autoforge
pip install -e ".[all]"

首次运行引导

首次运行 autoforgeai 会自动进入交互式配置向导，全部步骤均可跳过（Ctrl+C），之后随时用 autoforgeai setup 重新配置：

步骤 1 │ 配置 LLM 提供商（可选）
       │   选择 Anthropic / OpenAI / Google（可多选）
       │   每个提供商支持多种认证方式（API Key、OAuth、Bedrock、Vertex AI 等）
       │   选择强模型（Director/Architect 使用）和快模型（Builder/Tester 使用）
       │
步骤 2 │ 预算上限（默认 $10）
       │
步骤 3 │ 并行 Builder 数量（默认 3，最多 8）
       │
步骤 4 │ Docker 沙盒（可选，用于隔离构建环境）
       │
步骤 5 │ GitHub 环境
       │   自动检测 git 和 gh CLI
       │   可选配置自动推送到 GitHub

配置保存在 ~/.autoforge/config.toml，也可以通过环境变量覆盖。

DAG 联邦同步（社区共享知识）配置

如果你要开启“本地 DAG/理论图 ↔ 远端知识服务”同步，需要额外配置以下环境变量：

# 1) 开关（不配默认关闭）
export FORGE_DAG_FEDERATION_ENABLED=true

# 2) 远端快照服务地址（必填）
export FORGE_DAG_FEDERATION_ENDPOINT="https://your-domain/api/dag/snapshot"

# 3) 可选：鉴权
export FORGE_DAG_FEDERATION_API_KEY="your_token"

# 4) 可选：网络超时（秒，默认 10）
export FORGE_DAG_FEDERATION_TIMEOUT_SECONDS=15

运行行为：

• 启动时：先从 FORGE_DAG_FEDERATION_ENDPOINT 拉取远端知识快照，合并到本地。
• 结束时：把本次运行后的合并结果推送回远端。

远端接口约定（当前实现）：

• GET <endpoint>：返回 JSON 快照（capability_dag + 可选 theories）
• POST <endpoint>：接收同结构 JSON 快照并保存

最小可用配置只有 2 项：FORGE_DAG_FEDERATION_ENABLED=true + FORGE_DAG_FEDERATION_ENDPOINT=...

支持的 LLM 提供商

支持的认证方式：

支持跨厂商混搭模型：

export FORGE_MODEL_STRONG=o3              # 强模型用 OpenAI
export FORGE_MODEL_FAST=gemini-2.5-flash  # 快模型用 Google

OpenAI Subscription Notes

• Codex OAuth will start browser login immediately during setup (with manual URL fallback if auto-open fails).
• When both selected default models are OpenAI and auth method is codex_oauth/device_code, setup and interactive mode skip the USD budget prompt.
• Thinking level is configurable via openai_reasoning_effort in ~/.autoforge/config.toml or env FORGE_OPENAI_REASONING_EFFORT (minimal|low|medium|high|xhigh|none).

系统要求

• Python 3.10+ — python.org
• 至少一个 LLM API Key — Anthropic / OpenAI / Google
• Git（推荐）— 用于 Worktree 隔离并行构建
• Docker（可选）— 用于沙盒执行
• Lean 4（可选）— 用于形式化定理证明

三种工作模式

配置完成后，autoforgeai 进入交互式会话，第一步选择工作模式：

? Select mode:
❯ Development — generate complete runnable projects
  Academic — scientific reasoning, theorem proving, theory evolution
  Verification — review & verify existing codebases

每种模式下可进一步设置预算和并行度，然后用自然语言描述任务即开始。

学术与科研能力

AutoForge 内置完整的学术科研流水线，可作为 AI 驱动的自主科研助手使用——从输入一篇论文到输出一篇新论文，全部自动化。

端到端文章推理

输入任意一篇论文，自动完成：解析 → 理论图谱构建 → 声明验证 → 形式-非形式交错推理 → Lean 4 形式化 → 自主发现 → Elo 假说排序 → 推理扩展 → 同行评审 → 输出新论文

核心编排模块：article_reasoning.py — 统一 8 阶段管线

形式化验证与定理证明

自主科研发现

论文全流程

论文复现管线

AutoForge 支持从高层研究目标出发，自动推断相关论文并构建复现方案：

autoforgeai paper infer "improve sample efficiency in offline RL"   # 推断相关 ICLR 论文
autoforgeai paper benchmark                                         # 评估推断质量
autoforgeai paper reproduce "goal" --with-pdf --run-generate        # 端到端复现

管线流程：研究目标 → OpenReview 论文检索 → TF-IDF 排序匹配 → 信号提取 → 复现方案生成 → 可选自动执行

核心技术来源

算法优先架构

AutoForge 的学术引擎遵循 "算法优先，LLM 兜底" 的设计原则——每个声称的技术能力都有真实的算法实现，LLM 仅在算法失败或依赖缺失时作为后备。

核心方法：用确定性计算替代 LLM prompt

12 个增长算子，12 种不同的数学算法：

每个 GrowthOperator 拥有独立的 SymPy 实现，而非统一 dispatch 到同一个 LLM prompt：

每个模块内置 algorithm_ratio 监控：

engine = GrowthOperatorEngine()
engine.apply(GrowthOperator.SPECTRAL_DECOMPOSE, {"rows": [[2,1],[1,3]]})
print(engine.algorithm_ratio)  # 1.0 = 100% 算法路径，0.0 = 全部走 LLM

所有外部依赖均为可选（torch, sympy, scipy, faiss, pint），缺失时自动降级到 LLM 路径，不影响系统运行。

工程能力

AutoForge 同时也是一个全栈代码生成引擎——6 个 AI 智能体协作，将自然语言描述转化为完整可运行的代码项目。

5 阶段流水线

  "做一个带登录的 Todo App"
           │
           ▼
  ┌────────────────────────────────────────────────┐
  │  SPEC       Director 分析需求、拆解模块         │
  ├────────────────────────────────────────────────┤
  │  BUILD      Architect 设计架构                  │
  │             Builder 并行写代码，Reviewer 审查    │
  ├────────────────────────────────────────────────┤
  │  VERIFY     Tester 安装依赖、构建、运行测试      │
  │             失败自动生成修复任务                 │
  ├────────────────────────────────────────────────┤
  │  REFACTOR   Gardener 优化代码质量               │
  ├────────────────────────────────────────────────┤
  │  DELIVER    生成 README、整理结构、成本报告      │
  └────────────────────────────────────────────────┘
           │
           ▼
     workspace/my-todo-app/

另有两条专用管线：

• Review 管线： SCAN → REVIEW → REFACTOR → REPORT
• Import 管线： SCAN → REVIEW → ENHANCE → VERIFY → REFACTOR → DELIVER

6 智能体协作

智能引擎

47 个内置引擎在构建全流程中自动协作：

• MCTS 搜索树 — UCB1 选择 + PUCT 探索，真实的蒙特卡洛树搜索算法，支持 RethinkMCTS 兄弟节点修正
• 自然语言梯度反馈 (EvoMAC) — 有限差分梯度估计 + 动量累积，拓扑优化基于梯度流剪枝
• 过程奖励模型 (CodePRM) — AST 语法检查 + 导入解析 + 类型标注覆盖率 + 圈复杂度 + 沙箱测试通过率，复合评分替代 LLM 判断
• 自适应算力分配 — 关键词启发式 + 自校准偏差修正（指数滑动平均），95% 算法路径
• 语言强化学习 (Reflexion) — TF-IDF 加权词重叠检索 + IDF 逆文档频率 + 指数时间衰减，真实的情景记忆评分
• 块级故障定位 (LDB) — AST 基本块分解 + 变量活性分析 + Tarantula/Ochiai 频谱可疑度排名
• 函数级任务分解 — 依赖图拓扑排序 + 模块化分解
• 阶段预执行 — 流水线各阶段重叠并行，加速构建
• 达尔文自改写 (SICA) — Welch's t-test A/B 测试 + 宪法冲突检测（NLP 向量余弦相似度），仅统计显著改进才接受
• 安全扫描 (RedCode) — 18+ 正则模式匹配覆盖 CWE 分类，95% 算法路径
• 跨项目 RAG — BM25+TF-IDF 混合跨项目代码检索
• 知识图谱自增长 (CapabilityDAG) — 内容寻址去重 + BM25 检索 + DFS 传递闭包 + 合并冲突解决
• 跨项目演化 (Evolution) — 真实遗传算法：softmax 适应度选择 + Jaccard 新颖性拒绝 + JSON 持久化
• 动态宪法学习 — Apriori 关联规则挖掘 + Beta-Binomial 贝叶斯置信度更新 + 命题逻辑冲突检测
• 条件辩论 (AgentDebate) — Elo 评分系统 + TF-IDF 论证质量评估 + 形式逻辑一致性校验

CLI 命令参考

# 交互式（推荐）
autoforgeai                                    # 引导式会话

# 项目生成
autoforgeai generate "用 Flask + Vue 做书店管理系统"
autoforgeai generate "SaaS 落地页" --budget 3.00

# 代码审查
autoforgeai review ./my-project

# 导入增强
autoforgeai import ./my-project --enhance "加上暗色模式"

# 运行管理
autoforgeai status                             # 查看所有项目
autoforgeai resume                             # 恢复中断的任务
autoforgeai setup                              # 重新配置

# 论文复现
autoforgeai paper infer "research goal"        # 推断相关论文
autoforgeai paper benchmark                    # 评估推断质量
autoforgeai paper reproduce "goal" --run-generate  # 端到端复现

全局可选参数：--budget、--agents、--model、--mode、--mobile、--tdd、--verbose

守护进程模式

AutoForge 可作为 24/7 后台服务运行，通过 CLI、Telegram 或 Webhook 接收构建请求：

autoforgeai daemon start                       # 启动守护进程
autoforgeai daemon status                      # 查看状态
autoforgeai daemon stop                        # 停止

autoforgeai queue "支持 Markdown 的博客系统" --wait --tail  # 排队并跟随进度 + 输出任务日志
autoforgeai watch <project_id> --tail          # 跟随单个项目直到结束 + 输出任务日志
autoforgeai msg <project_id> "请优先把登录做完"  # 异步干预：追加用户提示（安全点生效）
autoforgeai projects                           # 查看所有项目
autoforgeai deploy <project_id>                # 显示部署指南

支持 systemd (Linux) 和 launchd (macOS) 系统服务安装，详见 services/ 目录。

消息处理采用统一异步桥接事件模型（normal response / timeout / late response），即使超时后晚到消息也会被投递到上层，由业务策略决定如何处理。

Telegram 渠道会定期推送进度汇总（[progress] ...）。当系统需要确认时会发送 [checkpoint] ... 提示，你可以用 /reply <request_id> yes|no 异步回复；也可以用 /msg <project_id> <text> 异步追加用户提示（安全点生效）。

可选环境变量：

• FORGE_PROGRESS_NOTIFY_INTERVAL_SECONDS：进度推送间隔（秒，默认 120，设为 0 禁用）
• FORGE_BRIDGE_TIMEOUT_SECONDS：交互等待超时（秒，默认 60）

如果在 checkpoint 选择 no，项目会进入 paused 状态；可用 autoforgeai unpause <project_id> 或 Telegram /resume <project_id> 继续由守护进程恢复执行。

待落实：DAG 联邦同步（代码框架已就绪，服务器未 setup）

状态：待落实

当前仓库已具备联邦同步代码框架（客户端 pull/push、服务端示例、配置项）， 但你需要先完成远端服务部署（例如 Vercel API + 持久化存储，或自有服务器）后才能正式启用。

如果你要开启“本地 DAG/理论图 ↔ 远端知识服务”同步，需要额外配置以下环境变量：

# 1) 开关（不配默认关闭）
export FORGE_DAG_FEDERATION_ENABLED=true

# 2) 远端快照服务地址（必填）
export FORGE_DAG_FEDERATION_ENDPOINT="https://your-domain/api/dag/snapshot"

# 3) 可选：鉴权
export FORGE_DAG_FEDERATION_API_KEY="your_token"

# 4) 可选：网络超时（秒，默认 10）
export FORGE_DAG_FEDERATION_TIMEOUT_SECONDS=15

运行行为：

• 启动时：先从 FORGE_DAG_FEDERATION_ENDPOINT 拉取远端知识快照，合并到本地。
• 结束时：把本次运行后的合并结果推送回远端。

远端接口约定（当前实现）：

• GET <endpoint>：返回 JSON 快照（capability_dag + 可选 theories）
• POST <endpoint>：接收同结构 JSON 快照并保存

最小可用配置只有 2 项：FORGE_DAG_FEDERATION_ENABLED=true + FORGE_DAG_FEDERATION_ENDPOINT=...

许可证

MIT

Harness / OpenAI Eval Bundle

AutoForge can now export local harness datasets and completed harness runs into an OpenAI-friendly eval bundle.

# Export a dataset into OpenAI-style JSONL records
autoforgeai harness openai-export ./benchmarks/todo.jsonl

# Local harness run still executes deterministically on your side,
# and AutoForge will also emit: <run_dir>/openai_eval_bundle/
autoforgeai harness run ./benchmarks/todo.jsonl

# Re-export an existing harness run directory
autoforgeai harness openai-export ./.autoforge/harness/runs/harness-abc123

Each bundle contains items.jsonl, item_schema.json, and bundle_manifest.json. This keeps build/test execution local while making prompts, traces, judge results, and artifact paths easier to hand off to OpenAI Evals / agent-eval workflows.

Claude Code Plugin

AutoForge now ships a Claude Code plugin package plus a repository-hosted marketplace manifest.

/plugin marketplace add AlyciaBHZ/autoforge
/plugin install autoforge@autoforge

Plugin assets live under plugins/autoforge, with marketplace metadata in .claude-plugin/marketplace.json. This lets the same repository act as both the plugin source and a GitHub-hosted marketplace while you wait for official marketplace approval.