FrontierAgent

FrontierAgent 是 Apodex 推出的开源代理框架、终端产品（TUI）及评估套件。它专为处理需要长时间运行、涉及复杂文件操作和深度研究的任务而设计。FrontierAgent 不仅是一个工具，更是一个模块化的基础设施，其核心工作流引擎同样驱动着 Apodex 模型的基准测试。

核心工作流模式

FrontierAgent 内置两种原生工作流，用户可根据任务复杂度自由选择：

1. ReAct (单代理模式)：
   • 一个带状态的智能体在任务限定的沙盒中独立工作。
   • 它能够进行研究、读取/写入文件、执行命令、撰写交付物，并通过迭代不断优化结果。
   • 适合中等复杂度的单一任务。
2. Agent Team (多代理协作模式)：
   • 协调器 (Coordinator)：维护任务看板，将复杂请求分解为独立的子任务。
   • 并行子代理：接收边界清晰的子任务并行执行，并返回结构化报告。
   • 综合与审查：协调器收集所有报告，合成最终结果，并可选择使用快速报告器进行证据审查。
   • 适合高复杂度、需要多维度探索的大型研究项目。

关键特性亮点

• 实时任务看板：
  • 在 TUI 侧边栏实时显示 add_task 和 update_task 事件。
  • 状态清晰可见：待处理、进行中、已完成、已阻塞、已取消。
• 沙盒化文件工作：
  • 严格的文件系统隔离：/inputs (只读输入), /workspace (工作状态), /outputs (持久交付物)。
  • 共享同一任务限定环境，确保操作安全。授权失败或越界访问将被直接拒绝。
• 异步干预与控制：
  • 用户可在代理运行时随时输入新指令。
  • 指令会在下一个安全轮次边界注入，不会打断正在运行的逻辑。
  • 在 Agent Team 模式下，新指令会引导协调器调整计划，而已运行的子代理允许完成当前工作。
• 透明的交付物与追踪：
  • 在 macOS/Docker 环境下，/outputs 目录直接映射到主机 .apodex/runs/<session-id>/outputs。
  • 运行目录包含完整的检查点、跟踪日志、引擎日志和执行轨迹，便于审计与复现。
• 审批、跟踪与恢复：
  • 变更审批：敏感操作（如文件修改）会显示差异并需用户确认（除非启用 --yes）。
  • 会话检查点：每个操作本地跟踪，支持 /revert 回滚更改，--resume 从中断处继续运行。
• 内置评估套件：
  • 支持研究和基于文件的基准测试。
  • 提供确定性产物收集、并发执行、进度检查及失败项单独重跑功能。

快速开始

前置要求

• Git, Python 3.12, uv
• OpenAI 兼容的模型端点
• Docker (可选，用于更强隔离)

安装与配置

# 1. 克隆仓库
git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent

# 2. 同步依赖
uv sync --python 3.12 --extra dev

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的 API Key 和端点信息

.env 示例：

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name

# 可选：网页研究工具密钥
SERPER_API_KEY=
JINA_API_KEY=

启动 TUI

# 模式 1: ReAct (有状态单代理)
uv run frontier-agent --mode react --cwd /path/to/project

# 模式 2: Agent Team (协调器 + 并行子代理)
uv run frontier-agent --mode agent_team --cwd /path/to/project

注：uv sync 仅安装轻量级终端运行时。科学计算和文档处理包设为可选，代理会根据任务需求动态安装到 <project>/.apodex/runtime/native 中，保持环境整洁。

本地部署与 GPU 支持

对于希望完全本地化运行的用户，FrontierAgent 提供了便捷的脚本支持：

• macOS/Linux 通用脚本：./scripts/run-macos.sh 和 ./scripts/run-linux.sh 可自动设置托管端点安装。
• Linux NVIDIA GPU 支持：
  • 使用 ./scripts/run-linux-gpu.sh --install-system-deps --setup-only 准备原生的、隔离的 SGLang 环境。
  • 注意：SGLang 服务对 NVIDIA 驱动程序/CUDA 版本有严格要求。请务必对照 GPU 兼容性矩阵确认你的 nvidia-smi 驱动版本，以避免加载错误。辅助程序会根据主机驱动选择经过审查的用户空间版本，但不会替换系统驱动。