FrontierAgent 追踪与恢复机制完整指南：trace.jsonl、会话检查点与 --resume 断点续跑

FrontierAgent 追踪与恢复机制完整指南trace.jsonl、会话检查点与 --resume 断点续跑【免费下载链接】FrontierAgent FrontierAgent, our agent framework, open-sourced alongside it — native command-line TUI, ReAct and Agent Team modes, one command on macOS and Linux, no preinstall, no hard Docker dependency.项目地址: https://gitcode.com/gh_mirrors/fr/FrontierAgentFrontierAgent 是一个面向 macOS 与 Linux 的开源命令行 AI Agent 框架自带原生终端 TUI、ReAct 与 Agent Team 两种模式一条命令即可运行、无需预装、不强依赖 Docker。长任务最怕中途崩溃后失忆——FrontierAgent 用三件套解决trace.jsonl 全量追踪日志、session.json 会话检查点、--resume断点续跑让 Agent 的每一轮对话、每一次工具调用都可追溯、可恢复。为什么需要追踪与恢复机制AI Agent 跑一次真实任务往往要经历几十轮 LLM 调用和上百次工具执行。一旦进程被中断网络抖动、终端关闭、Ctrl-C你会关心三个问题它到底做了什么—— 有没有留下完整记录做到哪一步了—— 能否定位中断点还能接着干吗—— 能不能从断点继续而不是从头再来FrontierAgent 对这三个问题的回答分别是trace.jsonl、session.json和--resume。三者全部落地在项目的.apodex/目录里无需任何额外配置。追踪文件都放在哪里.apodex/runs目录结构每次运行都会在--cwd指定的项目目录下生成一棵统一的运行目录Run Tree原生模式、Docker CLI 与 Docker Compose 三种启动方式下的宿主机布局完全一致cwd/.apodex/ ├── runs/ │ └── session-id/ │ ├── session.json # 可恢复的会话检查点 │ ├── trace.jsonl # 有序的 LLM 与工具事件追踪 │ ├── engine.log # 警告与故障诊断日志 │ ├── trajectories/ # 工作流与子代理轨迹 │ ├── workspace/ # 运行私有的克隆、草稿、临时文件 │ └── outputs/ # 持久化的用户交付物 └── runtime/ └── native/ # 仅原生模式的缓存与临时状态目录结构详见官方文档 docs/run-artifacts.md。一个细节值得注意session-id 采用本地时间 UTC 偏移 模式 随机后缀的格式例如20260812-1530450800-react-ab12。目录名肉眼可读而持久化的时间戳一律用标准 UTC 存储跨时区对比也不会乱。 运行中的workspace/与outputs/通过稳定的/workspace和/outputs路径暴露给 Agent你传入--cwd的目录始终只是项目根不再被当作草稿区。trace.jsonl 里到底记录了什么trace.jsonl是一个只追加append-only的 JSONL 事件流每行一个事件事件类型包括——事件类型记录内容start运行开始包含模式mode与工作目录cwdllm每一轮 LLM 回复的文本与工具调用列表tool每次工具调用的名称、参数、耗时ms、是否报错、完整结果end运行结束包含停止原因、总轮数、工具调用次数两个设计让它敢崩源码见 apodex/trace.py每行写入后立即 flush即使进程突然崩溃已写入的部分依然是合法 JSONL随时可以tail查看写失败被静默吞掉追踪是观察者Observer插件它坏了也绝不能拖垮主流程所以追踪永远不影响运行本身。想查看当前追踪文件在哪TUI 里敲/log即可打印活跃 trace 的位置想盯着实时诊断信息则可以用run_dir/path/to/project/.apodex/runs/session-id tail -f $run_dir/engine.log会话检查点 session.json每一轮都自动存档追踪解决看检查点解决存。FrontierAgent 的Session对象在每一轮对话完成后都会触发一次检查点写入per-turn checkpoint把完整现场序列化到session.json——这就是interrupt-safe resume中断安全恢复的基础实现见 apodex/session.py。检查点里保存的不只是聊天历史而是一整份现场快照完整对话历史history与 TUI 展示历史display_history工作流轮次workflow_turns让 Agent Team 模式下恢复后依然多轮用量统计token usage、当前模型与工作目录工作区日记journal记录文件变更基线支持回滚计划状态与 Todo 清单、以及 outputs 目录路径写入是尽力而为的任何一次写盘失败都不会打断会话本身。加载侧同样做了容错——检查点可能被人工编辑或写了一半apodex/session_state.py 在列出会话时直接跳过损坏条目保证其他历史会话依然可见。如何用 --resume 断点续跑恢复入口非常直接命令行与 TUI 各有一条路径CLI 参数定义见 apodex/cli.py1️⃣ 不带参数列出所有历史会话frontier-agent --resume会按时间倒序列出保存的会话名称、模式、目录、消息数、修改时间方便你挑选要续跑的那一个。TUI 内对应命令是/sessions。2️⃣ 带会话 ID直接进入续跑frontier-agent --resume 20260812-1530450800-react-ab12续跑时系统会自动完成这几件事把进程切回原会话的工作目录os.chdir到检查点里的 cwd恢复模型配置——若你同时显式传了--model则以命令行优先可以把旧会话重定向到新的模型端点通过session.restore(state)装载全部历史、journal、Todo 与用量数据TUI 会提示resumed session ...N prior messages若 outputs 目录中已有上一段的交付物续跑的后续追问会把精确文件路径直接交给模型省去重复搜索。3️⃣ 兼容老版本检查点早期版本把检查点存放在~/.apodex/sessions。这些旧检查点仍会被自动发现并可续跑文件不会被重命名或删除一旦旧会话被恢复后续检查点就统一写入所选--cwd下的运行目录了。常见问题崩溃后我该怎么排查一个实用的排查顺序frontier-agent --resume列出会话找到最近那条tail -f .apodex/runs/id/engine.log看引擎侧警告与错误python -m json.tool .apodex/runs/id/session.json快速确认检查点完整直接--resume id续跑Agent 会带着全部上下文继续工作。这套trace checkpoint resume的组合本质上把 AI Agent 从一次性对话变成了可断点续跑的工程任务——崩溃不可怕丢上下文才可怕。延伸阅读运行产物与时间戳规范docs/run-artifacts.md追踪观察者实现apodex/trace.py检查点读写实现apodex/session_state.py、apodex/session.pyCLI 参数与恢复流程apodex/cli.py运行目录布局apodex/run_layout.py掌握 trace.jsonl、session.json 与--resume你就能让 FrontierAgent 的每一个长任务都跑得起、查得到、接得上。【免费下载链接】FrontierAgent FrontierAgent, our agent framework, open-sourced alongside it — native command-line TUI, ReAct and Agent Team modes, one command on macOS and Linux, no preinstall, no hard Docker dependency.项目地址: https://gitcode.com/gh_mirrors/fr/FrontierAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考