系统总览
1. 一段系统总览
Terminus 2 是一个让大语言模型直接操作终端完成任务的 Agent（会自己反复观察、决定、执行的小系统）。它的作用是把“本来需要人一步步在终端里手动做”的事，交给模型自动完成。你可以把它理解成一个会远程操控终端的助手：它先看终端现在是什么样，收集任务信息和前面发生过的关键信息，再去问 LLM（大语言模型）下一步该做什么；如果模型说要敲命令，它就把命令发到 tmux session（可远程发命令的终端）里，等结果回来，再继续看。这个循环会一直重复，直到任务被明确确认做完、达到轮数上限，或运行被中断。整套系统的骨架很简单：准备环境、反复“看→想→敲→读→记”、结束时收尾并保存记录。
2. 两张 ASCII 小图
图 A · 生命周期
[初始化配置]
|
v
[准备终端和环境]
|
v
[run 主循环：反复看→想→敲]
|
v
[结束收尾并保存记录]图 B · 一次迭代做什么
[看终端]
|
v
[收集任务信息和前面重点]
|
v
[问 LLM 下一步]
|
v
{模型说“任务已完成”？}
| yes | no
v v
[再做一次完成确认] [拿到要敲的命令]
| |
v v
{确认真的完成？} [把命令发到终端]
| yes | no |
v v v
[停止运行] [继续执行] [等待结果返回]
|
v
[记一步，再转下一圈]3. 主流程地图
- 配置阶段：把用户给的参数整理成这次运行规则。
- 环境准备：启动终端会话，连到这次试验环境。
- 开始运行：清空本轮计数和记录，进入主循环前状态。
- 主循环：反复看终端、问模型、敲命令、读结果、记步骤。
- 结束收尾：不管怎么停，都整理输出并保存运行记录。
- 录屏后处理：把运行中的标记补进终端录屏文件。
1配置固化6 个函数
这一阶段把用户传入的零散配置收拢成一个稳定的 Terminus2 实例。它会确定模型、解析器、模板路径、计数器和会话字段，让后面的阶段不用反复猜默认值或担心上一次运行留下的状态。
2环境搭建3 个函数
这一阶段把已经确定好的配置接到真实试验环境里，启动后续步骤可以操控的 tmux 终端会话。它负责把静态参数变成这一次 trial 里的活终端，为模型观察和执行命令铺好地基。
3运行起点3 个函数
这一阶段把准备好的环境正式变成一次新的、可追踪的运行。它清掉上一轮可能残留的运行状态，整理终端信息、工具说明和技能说明，让 LLM 第一轮就拿到完整起点。
4迭代主循环★ Core50 个函数
这一阶段是 Terminus 2 的核心循环：每一轮先检查还能不能继续，再决定是否需要摘要，然后调用 LLM、解析回复、执行命令、观察结果，并判断任务是否已经真正完成。
4.1循环入口门控2 个函数
这一阶段是每轮迭代的入口检查。它先给当前轮次立好编号，再确认 tmux 终端还活着，确保后面的观察、思考和执行都建立在可追踪、可继续的状态上。
4.2主动摘要探测2 个函数
这一阶段在调用 LLM 之前先检查上下文空间是否紧张。如果聊天历史快要超出模型容量，它会提前触发摘要流程，避免等到模型调用失败后才被动补救。
4.3LLM 调用6 个函数
这一阶段把整理好的上下文发给 LLM，并尽量稳妥地拿回一条可以继续推进的回复。它同时负责记录日志和成本，处理上下文过长、输出截断等模型调用中的常见风险。
4.4响应解析16 个函数
这一阶段把 LLM 返回的自由文本拆成系统能理解的结果：是否继续、要执行什么命令、有没有格式或内容错误。没有这一步，后面只能靠猜测来驱动终端，流程会很不稳定。
4.5待交接提示 → 用户步骤(或切分)2 个函数
这一阶段处理摘要后的交接提示词。它会根据当前历史模式，决定把交接内容写成新的用户消息，还是切到新的轨迹段里继续运行。
4.6错误分支2 个函数
这一阶段专门处理 LLM 回复格式不合规的情况。它拦住不能安全执行的结果，把错误原因反馈给模型，让下一轮有机会重新给出可解析、可执行的回答。
4.7命令执行 → 观察 → 轨迹步骤2 个函数
这一阶段把模型决定执行的命令真正送进终端，并把终端新产生的输出整理成观察结果。它是“想法”落到真实 shell 的地方，也会把这次动作写进轨迹，方便之后复盘。
4.8完成门控与循环控制2 个函数
这一阶段决定本轮之后是继续循环还是正式收尾。即使模型说任务完成，它也不会马上相信，而是用连续确认等规则降低过早结束的风险。
4.9解析器内部辅助11 个函数
这一阶段是解析器内部的修补层。面对缺标签、半截 JSON、输出被截断等接近合法但不完整的回复，它会尽量恢复出可用结果，或给出明确失败原因。
5运行收尾4 个函数
这一阶段负责运行结束时的收尾和对账。无论任务正常完成、中断还是报错，它都会尽量把轨迹、token、耗时和成本等信息汇总落盘。
6录制后处理(外部)7 个函数
这一阶段处理运行结束后的录制文件。它查看本次 trial 是否留下录制标记，并在需要时把终端录像等外部产物整理到最终结果里。
S1上下文摘要7 个函数
这一阶段负责在上下文装不下时做摘要。它把已经发生的长对话压缩成后续还能接着用的交接材料，但不直接把材料塞回主对话。
X1Token 与成本核算5 个函数
这一横切层持续记录每次 LLM 调用和子 Agent 调用消耗的 token、耗时和成本。它不单独推动流程，却让整次试验的账本最后能对得上。
X2输出长度限制1 个函数
这一横切层负责限制过长的终端输出。它在观察阶段先把要发给 LLM 的内容裁到合理长度，避免一次输出占满上下文空间。
X3日志0 个函数
这一横切层负责记录关键日志：流程走到哪里、为什么分支、哪里出错、是否接近限制。它像黑匣子一样贯穿整次运行，方便事后排查。
subTmux 内部辅助21 个函数
这一子系统把 tmux 终端会话封装成上层 Agent 可以稳定使用的能力。它处理会话启动、按键发送、输出读取和等待命令完成等终端 I/O 细节。
Handbook Studio · Terminal Agent
Terminus 2 Handbook
20 stages · 106 functions documented · 10 registers · State-flow registers →
System overview
1. System Overview Paragraph
Terminus 2 is a program that lets an LLM operate a terminal to complete tasks. You can think of it as an AI using a command-line window the way a person would: it looks at what is on screen, thinks about the next move, types a command, waits, then reads the result. The point is to let an LLM actually carry out multi-step terminal work instead of only describing what someone else should do. A terminal here is a command-line window, and Terminus 2 drives one through tmux, which is a terminal you can control remotely. Most of the system is just that loop repeated until the task appears complete, the run hits a limit, or the terminal dies. Around that core loop, Terminus 2 has a simple harness: set settings, start the terminal, begin a run, repeat the think-and-type loop, finish cleanly, and optionally clean up the screen recording afterward. Later chapters zoom into the loop, summarization, logging, token and cost tracking, output trimming, and the terminal and parsing subsystems.
2. Two Small ASCII Diagrams
Diagram A · Lifecycle
set settings
↓
start terminal
↓
begin run
↓
REPEAT LOOP ← centerpiece
↓
finish run
↓
fix recording (optional)Diagram B · One Iteration
1. Read the terminal screen
2. Gather the task and recent history
3. Ask the LLM what to do next
4. Interpret its reply into an action
5. Does the task look complete?
├─ yes → confirm stop and end the run
└─ no → continue
6. Run the command in the terminal
7. Wait for output from the command
8. Record what happened for the next turn3. Main Flow Map
- Set settings: turns user options into one ready-to-run configuration before anything starts.
- Start terminal: creates and starts the remote terminal for this run before the main loop.
- Begin run: clears old run state and captures the initial screen right before looping.
- Repeat loop: the core cycle that reads the terminal, asks the LLM, acts, and checks for completion.
- Finish run: always cleans up and saves the final run record after the loop stops.
- Fix recording: optionally post-processes the terminal recording after the run is fully finished.
1Configuration Crystallization6 functions
This stage turns loose constructor options into a stable Terminus2 instance. It settles the model, parser, prompt templates, counters, and run fields so later stages can rely on one clear agent configuration.
2Environment Setup3 functions
This stage connects that settled configuration to a real trial environment. It starts the tmux terminal session that later stages will observe and control.
3Run Onset3 functions
This stage turns the prepared environment into a fresh, traceable run. It clears leftover state, gathers terminal and tool context, and gives the LLM a clean starting point for the first turn.
4Iteration Loop★ Core49 functions
This is the core Terminus 2 loop. Each round checks whether the run can continue, manages context pressure, queries the LLM, parses the reply, executes commands, observes results, and decides whether the task is truly done.
4.1Loop Entry Gates2 functions
This stage is the entry check for each loop iteration. It assigns a stable episode number and confirms the tmux session is still alive before the agent observes, thinks, or acts.
4.2Proactive Summarize Probe2 functions
This stage checks context pressure before the next LLM call. If the conversation is getting too large, it prepares a summary handoff early instead of waiting for the model call to fail.
4.3LLM Query6 functions
This stage sends the prepared context to the LLM and tries to get back a usable next step. It also records timing and cost, and handles common model-call risks such as context overflow or truncated output.
4.4Response Parse16 functions
This stage turns the LLM's free-form reply into structured decisions the system can trust: whether to continue, which commands to run, and whether the reply has format or content problems.
4.5Pending Handoff Prompt → User Step (or Split)2 functions
This stage handles a pending summary handoff. Depending on the history mode, it either writes the handoff as a new user step or splits the trajectory so the next stretch can continue cleanly.
4.6Error Branch2 functions
This stage handles malformed LLM replies. It blocks unsafe output, feeds the parse error back to the model, and gives the next round a chance to produce a valid response.
4.7Command Execute → Observation → Trajectory Step2 functions
This stage sends the model's chosen commands to the terminal and turns the new terminal output into an observation. It is where the agent's plan becomes real shell activity, and where that activity is recorded for later review.
4.8Completion Gate + Loop Control2 functions
This stage decides whether to keep looping or finish. Even when the model says the task is done, it uses confirmation rules to reduce the chance of stopping too early.
4.9Parser internal helpers10 functions
This stage is the parser's repair layer. When a reply is almost valid but has missing tags, partial JSON, or truncated structure, it tries to recover a usable result or return a clear failure.
5Run Teardown4 functions
This stage closes out the run and reconciles the record. Whether the task completed, stopped early, or hit an error, it gathers the final trajectory, token counts, timing, and cost data.
6Recording Post-process (External)7 functions
This stage handles recording artifacts after the run. It looks for recording markers left by the trial and folds terminal recording output into the final result when needed.
S1Context Summarization7 functions
This side stage summarizes long conversation history when the context window is getting full. It prepares a compact handoff for future turns, but does not itself insert that handoff back into the main dialogue.
X1Token & Cost Accounting5 functions
This cross-cutting layer tracks token usage, latency, and cost across main LLM calls and subagent work. It does not drive the task forward, but it makes the final run accounting reliable.
X2Output Length Limiting1 functions
This cross-cutting layer keeps terminal output from overwhelming the LLM. During observation, it trims very long command output before it enters the model context.
X3Logging0 functions
This cross-cutting layer records what the agent is doing and why. It leaves a debug trail for branch decisions, failures, limits, and subagent activity across the whole run.
subTmux internal helpers21 functions
This subsystem wraps tmux into a reliable execution surface for the agent. It handles session setup, keystroke delivery, output reading, and waiting for commands to finish.