FrontierAgent 技术学习手册
基于当前 GitHub main 源码整理。文档聚焦四个学习目标：项目定位、Agent 执行原理、多 Agent 协作机制，以及可靠性与安全边界。
学习导读：先建立正确的源码边界
| 学习主题 | 源码说明 |
|---|---|
| Self-Evolving 与 FrontierAgent 的关系 | 仓库没有 RL / fine-tune / PIVOT-RL / 自动更新模型参数的实现；运行时具备任务内自适应与恢复能力，但不等同于模型参数学习。 |
| Skills 扩展机制 | 存在 SkillLoader / SkillInjectionMiddleware 扩展接口，但当前仓库不内置 plugins/skills/，enable_skills 默认关闭，因此更适合作为扩展接口理解。 |
| Sandbox 与 native 运行模式 | 共享 workflow/tool sandbox 是 fail-closed；但 apodex 终端产品可使用 native 模式，native shell 具有当前用户权限，安全主要依赖审批、路径授权与 journaling。 |
| Workflow 数量与历史命名 | 当前公开仓库的两个主要 workflow 是 stateful_react_agent 与 agent_team；代码中的 swarm 多为历史兼容命名。 |
项目定位
Stateful ReAct
单个状态化 Agent，在任务级工作区中搜索、读文件、执行命令、生成文件，并通过多轮工具反馈完成任务。
Agent Team
Coordinator 维护 Task Board，把独立子任务并行委派给 Sub-agents，收集结构化报告并综合任务结果。
相同 workflow engine 同时被 TUI 和 benchmark runner 使用，因此“产品运行”与“评测运行”共享底层执行逻辑。
总体架构：边界比功能数量更重要
Agent Runtime：run_agent_loop() 是核心
为什么这个设计值得学
run_agent_loop() 接收 system_prompt、llm、tools、LoopConfig、observers、model_profile。它本身不知道当前是研究任务、文件任务还是 Team worker。
因此角色差异通过 Prompt + Tools + Profile + Observer 注入，而不是不断修改主 Loop。
Observer = Agent 行为控制平面
Observer 可以在 LLM 响应、Tool Call、Tool Result、Turn End 等阶段观察或返回 Intervention，完成审批、retry、替换内容、停止、重复检测、trace 等行为。
Stateful ReAct：单 Agent 长任务模式
核心特点
- 无 Tool Call 的 assistant response 是自然终止条件。
- 支持 Web、Shell、文件读取/编辑与 deliverable 生成。
- 通过 Observer 实现 wall-clock、context compaction、重复检测和 final-answer recovery。
- Profile 将交互产品、可复现 benchmark、简单 baseline 的预算与压缩策略分开。
Agent Team：Coordinator + AgentBus + Task Board
AgentBus
提供任务提交、消息、报告收集、取消和共享上下文；Sub-agent 仍复用同一个 Agent Loop。
SpawnGuard
限制嵌套深度、并行度与 wall-time，避免子 Agent 无限制递归和并发爆炸。
可选 Fast Reporter 在 Coordinator 已经产生答案后做证据复核；Reporter 失败是 fail-open，保留 Coordinator 原答案。
可靠性：FrontierAgent 真正有工程价值的地方
| 问题 | 机制 | 作用 |
|---|---|---|
| 上下文越来越长 | Tiered Compaction | 先压缩旧 Tool Result，必要时再做 LLM Summary；用真实 token gauge 校准触发。 |
| 重复搜索 / 重复调用 | DuplicateQueryRollback / RepetitionGuard | 回滚重复 turn、提示模型换策略或停止失控循环。 |
| 模型长时间只输出 reasoning | Reasoning runaway guard | 按时间、reasoning token、logical call timeout 限制单次调用。 |
| Tool Result 被截断 | recover_result | 从本次运行 trajectory 中按 turn + call_id 分页恢复原始结果。 |
| 任务中途暂停 / 退出 | Checkpoint / Resume | 持久化 history 和状态后继续执行。 |
安全与运行模式：必须区分 Framework 和 TUI
A. Workflow / Benchmark 的共享 Sandbox
| 路径 | 策略 | 用途 |
|---|---|---|
/inputs | 只读 | 用户文件 / benchmark 输入 |
/workspace | 读写 | 任务工作状态 |
/outputs | 受控读写 | 持久化交付物 |
共享 sandbox backend 是 auto / bwrap / container。隔离或授权失败时 fail-closed，不回退到未隔离 host。
B. apodex 终端产品
终端产品还提供 native 执行：Linux 默认 native；macOS 在 Docker 不可用时也可 native。其本地 Shell / File 工具直接作用于用户真实工作目录。
native 不是 OS sandbox：命令拥有当前用户权限。保护来自 Approval、Path Authorization、Diff、Journal 与 /revert，而不是进程级隔离。
TUI / Session：把 Runtime 做成可控产品
Approval + Diff
写文件和高风险操作展示 diff / target，并等待批准；危险 Shell 有额外风险分类。
Trace + Revert
每个动作写本地 JSONL trace；文件修改建立 journal，支持 session 级 /revert。
Resume
--resume 恢复 history、工作目录、workflow mode 和 session 状态。
Live Steering
运行时输入新指令，通过 SteerInbox 排队，在下一个安全 turn boundary 注入，不粗暴丢弃当前运行。
Benchmark：同一 Runtime 的第二个消费者
评测模式
每个 benchmark question 在独立 subprocess 中运行，支持并发、恢复、artifact 收集，并根据数据集使用 deterministic 或 model-based judge。
uv run python -m benchmarks.public.runner.run_subprocess \ --benchmark browsecomp \ --pipeline stateful-react-agent \ --profile default \ --limit 1 --concurrency 1 \ --out ./results/smoke
Agent Team 的内部并行度会叠加 benchmark --concurrency，因此官方建议从 1 开始。
Self-Evolving：当前源码的实现边界
| 能力 | 源码是否存在 | 正确理解 |
|---|---|---|
| 任务内重新规划 / Team 调整 | 有 | Runtime Adaptation |
| Context Compaction / Recovery | 有 | 运行时可靠性 |
| Trajectory / Benchmark | 有 | 可用于分析与训练数据采集的基础设施 |
| Skills Loader | 接口存在 | 扩展 seam；当前无 bundled skills，默认关闭 |
| 自动 fine-tune / RL / 权重更新 | 未发现 | 不属于本仓库 |
| PIVOT-RL 实现 | 未发现 | 不属于本仓库源码 |
| 运行后自动重写 FrontierAgent 自身源码并发布 | 未发现 | 不能从公开仓库得出该结论 |
因此学习 FrontierAgent 时，应该把重点放在 Agent Runtime、工具权限、上下文治理、多 Agent 调度、Session 恢复和 Evaluation。如果研究 Apodex 1.1 的模型训练式 Self-Evolution，应把官方技术报告视为另一层材料，不与本仓库实现混写。
最短源码学习路线
README.md：先确认项目边界与两个 workflow。
docs/framework.md：理解 Pipeline、Agent Loop、Observer、AgentBus、Sandbox。
frontier_agent/core/runtime/loop/agent_loop.py：跟一遍完整 turn。
workflows/stateful_react_agent/README.md：理解单 Agent 如何组合 Runtime。
workflows/agent_team/README.md：理解 Coordinator、AgentBus、SpawnGuard。
plugins/tools/__init__.py：理解显式 Tool allowlist 和 role filtering。
apodex/README.md：最后看 TUI、native/bwrap/container、approval、resume/revert。
最小运行
git clone https://github.com/ApodexAI/FrontierAgent.git cd FrontierAgent uv sync --python 3.12 --extra dev cp .env.example .env # 单 Agent uv run frontier-agent --mode react --cwd /path/to/project # Agent Team uv run frontier-agent --mode agent_team --cwd /path/to/project
Agent Loop → Observer → Tool Registry → ReAct → AgentBus → Sandbox → TUI/Session → Benchmark。Skills 和外部 Self-Evolution 训练都不是第一阶段必读。源码依据
- ApodexAI/FrontierAgent — 当前仓库。
- README.md — 项目定位、两个 workflow、TUI、评测。
- docs/framework.md — Framework、Observer、AgentBus、共享 Sandbox。
- Stateful ReAct README — Guardrails / Profiles。
- Agent Team README — Coordinator / Task Board / SpawnGuard。
- Tool Registry — 显式 built-in allowlist。
- apodex/README.md — Native / bwrap / container、Approval、Trace、Resume。
- Skills Runtime — 扩展接口与 no bundled skills 说明。
源码基线：GitHub main 提交 76ac16b6a88c2bb6ae45095b4896fdfc643519cb（2026-08-27）。