FrontierAgent
开源终端智能体运行时：一个 ReAct 智能体或协调者加并行子智能体团队，在沙盒中完成长周期研究与文件交付。
证据显示路径策略（/inputs 只读、/workspace 读写、/outputs 受控）、fail-closed 沙箱、写入/删除/装包需批准、部分操作即使 --yes 仍拒绝、文件变异有日志可供 /revert。pyproject 有 Dependabot 驱动的传递依赖安全下限（cryptography、urllib3 等），属于超出平均的扎实做法。扣分点：审批流、沙箱隔离、deny-even-with---yes 的实现代码均未在提交的文件中出现，多为 README 断言；密钥仅建议放 .env，未见脱敏或防泄漏机制的具体实现。source_attribution 有完整的 LICENSE、引用条目与代码路径命名，但发布者身份未经注册表验证，只能计 2。
README 与 pyproject、CI 高度一致：入口 frontier-agent 与 apodex 别名、extras 划分、测试路径、ruff 规则均互相印证，计 3。依赖可用性扣分：运行时依赖多为 >= 浮动下限而非锁定版本（uv sync --locked 在 CI 使用，但发布给用户的 quick start 未用 --locked）；GPU 栈自身承认驱动/CUDA/SGLang 不匹配会以不可读错误失败。失败消息有部分证据（测试断言 escapes workspace、symbolic links 等错误文案，fail-closed 声明），但整体错误面未被充分展示，计 2。
部署矩阵覆盖 macOS/Linux/WSL2/GPU 容器、Docker 多架构镜像、中文文档，受众与场景划分清楚，计 3。环境适配同样有安装选择器、GPU 兼容矩阵、compose 验证，计 3。能力边界有 REACT_NO_WEB/SWARM_NO_WEB、--concurrency 1 建议、benchmark 注册表为权威来源，但多数为文档声明而非代码证据，计 2。触发精度仅见附件契约区分 react/agent_team 的测试证据，覆盖面窄，计 2。
信息架构（文档索引、分层目录说明）与安装说明（多平台、中文、Docker、GPU）证据充分，计 3。License 为完整 Apache-2.0 正文，计 3。扣分点：无 CHANGELOG，版本仅 0.1.0 且 SECURITY 支持表只列 0.1.x，versioning_changelog 计 1；命名稳定性靠 apodex 兼容别名维持但有历史包袱，计 2；示例集中在 quick start，FAQ 未见，计 2；已知局限（GPU 栈易碎、镜像内包私有不能匿名拉取）有主动披露但零散，计 2；维护责任有安全响应时限与 CI 门禁，但无公开的发布节奏或维护者承诺，计 2。
输出可用性有 /outputs 主机映射、run 目录含 checkpoint/trace/trajectory、任务板侧栏，但均未附实现代码，计 2。边际价值：ReAct+Agent Team+评测套件三者复用同一引擎并明确分层，有差异化，但性能提升数字完全依赖厂商自述报告，计 2。成本收益有 token 预算文档与并发乘积警告，但 GPU/模型托管成本与 free-tier 促销混杂，未做中性评估，计 2。
主张可追溯：性能表引用 arXiv 报告，行为主张给出具体代码路径（frontier_agent/infra/config.py 等），计 2。跨源印证：CI（bwrap 沙箱下跑 pytest）、py.typed 门禁、附件测试（路径逃逸、symlink 拒绝、会话隔离）确实印证了 README 的部分安全声明，这是超出平均的加分项；但审批、/revert、trace 等核心信任主张无代码佐证，计 2。事实与推断分离扣分明显：README 将营销（限时免费 API）、自评基准数字与机制描述混排，无内部区分，计 1。
- 静态审查未执行任何代码；审批门、沙箱隔离、/revert 回滚等核心安全机制仅有 README 声明，请在使用前自行审计 apodex/ 与 plugins/tools/ 的实际实现。
- 运行时依赖为 >= 浮动下限，用户 quick start 未使用 --locked；生产部署建议自行锁定并审计依赖树。
- 基准性能数字全部来自发布方自述与关联 arXiv 报告，属于利益相关证据，未经独立复现，不应作为选型唯一依据。
- README 将限时免费 API 促销与机制文档混排，注意区分营销内容与技术事实。
- GPU/SGLang 栈被项目自身承认在版本不匹配时会以不可读的 CUDA/Triton 错误失败，GPU 部署前务必核对兼容矩阵。
- 发布者身份未经企业注册表验证，安全披露仅依赖 [email protected] 邮箱通道，无第三方背书。
这个 Agent 能做什么，适合哪些场景？
FrontierAgent 是 ApodexAI 开源的智能体运行时、终端产品（TUI）和评测套件，面向长周期研究与基于文件的工作。它提供两种原生工作流：Stateful ReAct（单个有状态智能体研究、读写文件、运行命令并在任务级沙盒中迭代）和 Agent Team（协调者维护任务板，向并行子智能体分派独立工作并汇总结果）。框架层（frontier_agent/）、工具插件（plugins/tools/）、工作流（workflows/）、终端层（apodex/）和评测层（benchmarks/）边界清晰，可独立复用。文件系统采用统一沙盒策略：/inputs 只读、/workspace 可写、/outputs 存放持久交付物。部署上支持 macOS 原生或 Docker、Linux 原生/bubblewrap/Docker，以及本地 SGLang GPU 服务，可连接任意 OpenAI 兼容端点。同一工作流引擎也驱动评测基准运行器，内置 14 个基准的评测能力。
安装后通过 uv run frontier-agent --mode react|agent_team --cwd /path/to/project 启动 TUI。ReAct 模式下，单个有状态智能体读取 /inputs 中的文档，在 /workspace 中检索与分析，调用 web、shell、file、sandbox 等工具（plugins/tools/），并在 /outputs 写入交付物。Agent Team 模式下，协调者将请求分解为任务板上的条目（add_task/update_task 事件实时显示在 TUI 侧边栏），派发给有界的并行子智能体，收集结构化报告并综合最终结果。变更类操作会展示 diff 并需批准（除非 --yes）；会话自动 checkpoint，所有动作本地留痕，支持 /revert 回滚和 --resume 恢复。智能体运行中用户可随时输入新指令，在下一个安全回合边界注入。评测层面，benchmarks.public.runner.run_subprocess 在隔离子进程中运行基准题目，支持可恢复的多轮实验与确定性/模型裁判。环境变量 OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL 指定模型端点；SWARM_NO_WEB=1 或 REACT_NO_WEB=1 可关闭联网工具。
- 需要在代码库或文档集中做深度调研并产出报告的研究人员：用 --mode react --cwd /repo 指向项目目录，智能体只读读取材料、在沙盒中检索并写出报告到 /outputs。
- 处理需要拆分的宽泛问题的分析师：用 --mode agent_team 让协调者分解问题、并行派出子智能体调查后汇总综合结论。
- 评测自托管模型智能体能力的工程团队：内置 BrowseComp、Humanity's Last Exam、SWE 类文件基准等 14 个基准的子进程评测器与成绩收集。
- 本地 GPU 用户想跑自家模型：用 scripts/run-linux-gpu.sh 配置 SGLang，按 GPU 兼容性矩阵核对驱动后以原生或 Docker 方式服务模型。
- 不熟悉 Python 环境的用户：直接运行 linux/amd64 或 linux/arm64 预构建镜像
docker compose run --rm agent，无需本地 Python 环境。
这个 Agent 有哪些优点和局限？
- 双工作流开箱即用：Stateful ReAct 适合聚焦研究，Agent Team 提供协调者 + 有界并行子智能体 + 任务板实时可视，是较少数在终端原生实现多智能体编排的开源框架之一。
- 安全模型完整：统一的 /inputs 只读、/workspace、/outputs 沙盒路径策略，变更操作 diff + 审批门禁，fail-closed，会话 checkpoint、本地 trace、/revert 回滚与 --resume 恢复齐备。
- 评测即框架：同一工作流引擎驱动基准运行器，支持子进程隔离、可恢复多轮实验、并发控制与失败重跑，附带 14 个公开基准注册表。
- 部署路径多样：macOS/Linux 原生、bubblewrap、Docker、多架构预构建镜像、本地 SGLang GPU 模板（RTX 4090/5090 等）均有文档，且不强制 Docker。
- 依赖 OpenAI 兼容端点（默认指向 Apodex-1.1 API 平台，README 中有为期两周的免费推广），使用其他模型供应商需要自行确认工具调用兼容性与稳定性。
- 本地 SGLang GPU 服务对 NVIDIA 驱动 / CUDA / SGLang 版本有严格版本锁定，不匹配会在模型加载时以晦涩的 CUDA 或 Triton 内核错误暴露，排障成本高。
- 科学计算与文档解析包在原生模式被刻意设为可选，智能体按需安装到 <project>/.apodex/runtime/native，意味着首次运行可能产生额外等待和网络依赖。
- 评测需要自行下载数据集并配置裁判凭证（部分基准需 SERPER/JINA 等 API key），GDPval 的开源版仅用确定性校验，省略了成对模型裁判。
如何安装或部署这个 Agent？
前置要求：Git、Python 3.12、uv，以及一个 OpenAI 兼容模型端点（Docker 可选）。
- 克隆并同步依赖：
git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent
uv sync --python 3.12 --extra dev
cp .env.example .env- 在 .env 中填入端点：
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-nameSERPER_API_KEY= # 可选：联网研究工具
JINA_API_KEY= # 可选：联网研究工具
- 或者一键脚本：
./scripts/run-macos.sh/./scripts/run-linux.sh（托管端点安装）；GPU 本地部署用./scripts/run-linux-gpu.sh --install-system-deps --setup-only。 - Docker 路线：预构建 linux/amd64 和 linux/arm64 镜像发布在 GitHub Container Registry，
cp .env.example .env && docker compose run --rm agent即可，无需本地 Python。文档另提供 macOS/Linux/中文一键启动指南（docs/install/macos.zh-CN.md 等）。
如何使用这个 Agent？
交互式 TUI：
uv run frontier-agent --mode react --cwd /path/to/project
uv run frontier-agent --mode agent_team --cwd /path/to/project带任务启动：
uv run frontier-agent --mode agent_team --cwd /repo "研究备选方案，核实证据并写出报告"
uv run frontier-agent --mode react --cwd /repo -p "explain src/main.py"uv run frontier-agent --mode agent_team --no-tui "对比这两个实现"
uv run frontier-agent --resume启动前附加只读附件（可重复）：--input ~/Downloads/claim.pdf --input ~/Desktop/photo.jpg。运行中直接输入文字可将后续指令排队到下一个安全回合边界；写文件、删除、装包等变更操作需批准（或加 --yes），/revert 可回滚会话变更。评测冒烟：uv run python -m benchmarks.public.runner.run_subprocess --benchmark browsecomp --pipeline stateful-react-agent --profile default --limit 1 --concurrency 1 --out ./results/smoke（需先按 docs/eval.md 下载数据集，uv sync --extra eval --extra sandbox --extra document-readers）。